@tryhamster/gerbil 1.0.0-rc.9 → 1.0.1

package/dist/{types-CiTc7ez3.d.mts → types-LlyYILII.d.mts}

@@ -41,8 +41,12 @@ type GenerateOptions = {
   system?: string;
   /** Enable thinking/reasoning mode (Qwen3) */
   thinking?: boolean;
-  /** Callback for each token (streaming) */
-  onToken?: (token: string) => void;
+  /** Callback for each token (streaming); `meta` carries live decode-only tok/s */
+  onToken?: (token: string, meta?: {
+    tokenIndex: number;
+    tps: number;
+    elapsedMs: number;
+  }) => void;
   /** Images to include (only used if model supports vision) */
   images?: ImageInput[];
   /** Enable response caching (default: false) */
@@ -92,16 +96,47 @@ type EmbedResult = {
   /** Time in ms */
   totalTime: number;
 };
+type SearchResult = {
+  /** The matched text */
+  text: string;
+  /** Similarity score (0-1, higher is more similar) */
+  score: number;
+  /** Index in the original corpus */
+  index: number;
+};
+type SimilarityResult = {
+  /** Similarity score (0-1, higher is more similar) */
+  score: number;
+  /** First text */
+  textA: string;
+  /** Second text */
+  textB: string;
+  /** Time in ms */
+  totalTime: number;
+};
 type LoadOptions = {
   /** Progress callback */
   onProgress?: (info: ProgressInfo) => void;
-  /** Device: 'auto', 'gpu', 'cpu', 'webgpu' (default: 'auto') */
-  device?: "auto" | "gpu" | "cpu" | "webgpu";
-  /** Quantization: 'q4', 'q8', 'fp16', 'fp32' (default: 'q4') */
+  /**
+   * Compute device. The only inference backend is the native WebGPU engine
+   * (Dawn in Node, WebGPU in the browser); "auto" resolves to "webgpu". There
+   * is no CPU/WASM or ONNX path.
+   */
+  device?: "auto" | "webgpu";
+  /**
+   * Weight quantization. The engine quantizes to INT4 ("q4") on load; the other
+   * values are accepted for forward-compat but currently map to q4.
+   */
   dtype?: "q4" | "q8" | "fp16" | "fp32";
   /** Override context length */
   contextLength?: number;
 };
+type PreloadOptions = {
+  /** Progress callback for download status */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Keep model loaded in memory after preload (default: false - disposes to free memory) */
+  keepLoaded?: boolean;
+};
 type ProgressInfo = {
   status: string;
   progress?: number;
@@ -112,14 +147,18 @@ type ProgressInfo = {
 type GerbilConfig = {
   /** Default model */
   model?: string;
-  /** Default device */
-  device?: "auto" | "gpu" | "cpu";
-  /** Default quantization */
+  /** Default device (native WebGPU only; "auto" resolves to "webgpu") */
+  device?: "auto" | "webgpu";
+  /** Default quantization (engine uses INT4 "q4") */
   dtype?: "q4" | "q8" | "fp16" | "fp32";
   /** Cache configuration */
   cache?: CacheConfig;
   /** Fallback configuration */
   fallback?: FallbackConfig;
+  /** Telemetry hooks for observability (Sentry, logging, etc.) */
+  telemetry?: TelemetryConfig;
+  /** Concurrency control for request queuing */
+  concurrency?: ConcurrencyConfig;
 };
 type CacheConfig = {
   /** Enable caching (default: true) */
@@ -183,14 +222,14 @@ type SystemInfo = {
 type GerbilModelSettings = {
   /** Enable thinking mode */
   thinking?: boolean;
-  /** Device to use */
-  device?: "auto" | "gpu" | "cpu";
+  /** Device to use (native WebGPU only) */
+  device?: "auto" | "webgpu";
   /** Quantization level */
   dtype?: "q4" | "q8" | "fp16" | "fp32";
 };
 type GerbilProviderSettings = {
-  /** Default device */
-  device?: "auto" | "gpu" | "cpu";
+  /** Default device (native WebGPU only) */
+  device?: "auto" | "webgpu";
   /** Default quantization */
   dtype?: "q4" | "q8" | "fp16" | "fp32";
 };
@@ -348,6 +387,65 @@ type StreamingTranscriptionSession = {
   /** Reset session (clear buffer and transcript) */
   reset: () => void;
 };
+/**
+ * Telemetry hooks for production observability.
+ * Pass your own Sentry instance or custom logging functions.
+ */
+type TelemetryConfig = {
+  /**
+   * Called after successful generation with full result and timing.
+   * Use for logging, metrics, or analytics.
+   */
+  onGenerate?: (event: GenerateEvent) => void;
+  /**
+   * Called when any error occurs during Gerbil operations.
+   * Perfect for Sentry.captureException() or similar.
+   */
+  onError?: (error: Error, context: ErrorContext) => void;
+  /**
+   * Called after model loading completes (success or failure).
+   */
+  onModelLoad?: (event: ModelLoadEvent) => void;
+  /**
+   * Called when a request is queued (if concurrency limit reached).
+   */
+  onQueueWait?: (waitTimeMs: number) => void;
+};
+type GenerateEvent = {
+  /** Model used for generation */
+  modelId: string;
+  /** Generation result */
+  result: GenerateResult;
+  /** Whether response came from cache */
+  cached: boolean;
+  /** Time spent waiting in queue (if any) */
+  queueTimeMs?: number;
+};
+/**
+ * Context passed to telemetry onError callback.
+ * Flexible record to allow any relevant context data.
+ */
+type ErrorContext = Record<string, unknown>;
+type ModelLoadEvent = {
+  /** Model that was loaded */
+  modelId: string;
+  /** Time to load in ms */
+  loadTimeMs: number;
+  /** Whether loaded from cache */
+  fromCache: boolean;
+  /** Device used */
+  device: "webgpu" | "cpu" | "wasm";
+  /** Whether load succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+};
+type ConcurrencyConfig = {
+  /** Maximum concurrent generation requests (default: 1 for LLM) */
+  maxConcurrent?: number;
+  /** Request timeout in ms (default: 300000 = 5 min) */
+  timeout?: number;
+};
 //#endregion
-export { TranscribeSegment as A, SpeakResult as C, TTSModelConfig as D, SystemInfo as E, TranscribeOptions as O, SpeakOptions as S, StreamingTranscriptionSession as T, ModelSource as _, FallbackConfig as a, STTModelConfig as b, GerbilConfig as c, ImageInput as d, JsonOptions as f, ModelConfig as g, LoadTTSOptions as h, EmbedResult as i, VoiceInfo as j, TranscribeResult as k, GerbilModelSettings as l, LoadSTTOptions as m, CacheConfig as n, GenerateOptions as o, LoadOptions as p, EmbedOptions as r, GenerateResult as s, AudioChunk as t, GerbilProviderSettings as u, ModelStats as v, StreamingTranscriptionOptions as w, SessionStats as x, ProgressInfo as y };
-//# sourceMappingURL=types-CiTc7ez3.d.mts.map
+export { SpeakResult as A, PreloadOptions as C, SessionStats as D, SearchResult as E, TelemetryConfig as F, TranscribeOptions as I, TranscribeResult as L, StreamingTranscriptionSession as M, SystemInfo as N, SimilarityResult as O, TTSModelConfig as P, TranscribeSegment as R, ModelStats as S, STTModelConfig as T, LoadSTTOptions as _, EmbedResult as a, ModelLoadEvent as b, GenerateEvent as c, GerbilConfig as d, GerbilModelSettings as f, LoadOptions as g, JsonOptions as h, EmbedOptions as i, StreamingTranscriptionOptions as j, SpeakOptions as k, GenerateOptions as l, ImageInput as m, CacheConfig as n, ErrorContext as o, GerbilProviderSettings as p, ConcurrencyConfig as r, FallbackConfig as s, AudioChunk as t, GenerateResult as u, LoadTTSOptions as v, ProgressInfo as w, ModelSource as x, ModelConfig as y, VoiceInfo as z };
+//# sourceMappingURL=types-LlyYILII.d.mts.map

package/dist/types-LlyYILII.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-LlyYILII.d.mts","names":[],"sources":["../src/core/types.ts"],"sourcesContent":[],"mappings":";;;;AAyBY,KAfA,WAAA,GAeW;EASX,EAAA,EAAA,MAAA;EAWA,IAAA,EAAA,MAAA;EAmCA,WAAA,EAAA,MAAc;EA8Bd,IAAA,EAAA,MAAA;EAkBA,aAAA,EAAY,MAAA;EAQZ,gBAAW,EAAA,OAAA;EAWX,YAAA,EAAA,OAAY;EAWZ;EAkBA,cAAW,CAAA,EAAA,OAAA;EAqBX;EAOA,iBAAY,CAAA,EAAA,MAAA;EAYZ,MAAA,EAAA,MAAA,GAAY,QAAA,GAAA,KAAA,GAAA,SAAA,GAAA,OAAA,GAAA,OAAA;CAWd;AAGG,KA7MD,WAAA,GA6MC;EAGC,IAAA,EAAA,SAAA,GAAA,aAAA,GAAA,OAAA;EAGE,IAAA,EAAA,MAAA;CAAiB;AAGrB,KA7MA,UAAA,GA6MW;EAiBX;EAqBA,MAAA,EAAA,MAAA;EAUA;EAOA,GAAA,CAAA,EAAA,MAAA;AAyBZ,CAAA;AAWY,KA7RA,eAAA,GA6RsB;EAYtB;EAeA,SAAA,CAAA,EAAA,MAAc;EAmBd;EAWA,WAAA,CAAA,EAAU,MAAA;EAWV;EAaA,IAAA,CAAA,EAAA,MAAA;EAWA;EAiBA,IAAA,CAAA,EAAA,MAAA;EASA;EASA,aAAA,CAAA,EAAA,MAAgB,EAAA;EAahB;EAWA,MAAA,CAAA,EAAA,MAAA;EAeA;EAES,QAAA,CAAA,EAAA,OAAA;EAEN;EAID,OAAA,CAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,IAgCM,CAhCN,EAAA;IAAO,UAAA,EAAA,MAAA;IAqBT,GAAA,EAAA,MAAA;IAKW,SAAA,EAAA,MAAA;EAMH,CAAA,EAAA,GAAA,IAAA;EAAgB;EAKZ,MAAA,CAAA,EAtdb,UAsda,EAAA;EAAc;EAQ1B,KAAA,CAAA,EAAA,OAAA;EAeA;EAEA,QAAA,CAAA,EAAA,MAAc;AAmB1B,CAAA;KAzfY,cAAA;;;;;;;;;;;;;;;;;;KA8BA;;UAEF,CAAA,CAAE,QAAQ;;;;;;;;KAgBR,YAAA;;;;;;KAQA,WAAA;;;;;;;;KAWA,YAAA;;;;;;;;KAWA,gBAAA;;;;;;;;;;KAkBA,WAAA;;sBAEU;;;;;;;;;;;;;;;KAmBV,cAAA;;sBAEU;;;;KAKV,YAAA;;;;;;;KAYA,YAAA;;;;;;;;UAWF;;aAGG;;cAGC;;gBAGE;;KAGJ,WAAA;;;;;;;;;;;;KAiBA,cAAA;;;;;;;;;;;;KAqBA,YAAA;;;;;;;;;KAUA,UAAA;;;;;;KAOA,UAAA;;SAEH;;;;;;;;;;;;;;;;;;KAuBG,mBAAA;;;;;;;;KAWA,sBAAA;;;;;;KAYA,SAAA;;;;;;;;;;;;;;KAeA,cAAA;;;;;;;;;;;;UAYF;;;;;;KAOE,YAAA;;;;;;sBAMU;;yBAEG;;KAGb,UAAA;;WAED;;;;;;;;KASC,WAAA;;SAEH;;;;;;;;;;KAWG,cAAA;;sBAEU;;;;KASV,cAAA;;;;;;;;;;;;;;;;KAiBA,iBAAA;;;;;;sBAMU;;KAGV,iBAAA;;;;;;;;KASA,gBAAA;;;;;;aAMC;;;;;;KAOD,cAAA;;sBAEU;;;;KASV,6BAAA;;;;;;;;;;;;;;KAeA,6BAAA;;qBAES;;eAEN;;;;cAID;;;;;;;;;;;;;;;;KAqBF,eAAA;;;;;uBAKW;;;;;oBAMH,gBAAgB;;;;wBAKZ;;;;;;KAQZ,aAAA;;;;UAIF;;;;;;;;;;KAWE,YAAA,GAAe;KAEf,cAAA;;;;;;;;;;;;;;KAmBA,iBAAA"}

package/dist/{utils-CZBZ8dgR.mjs → utils-DKO55ZmZ.mjs}

@@ -60,4 +60,4 @@ function extractJson(text) {
 
 //#endregion
 export { zodToJsonSchema as n, extractJson as t };
-//# sourceMappingURL=utils-CZBZ8dgR.mjs.map
+//# sourceMappingURL=utils-DKO55ZmZ.mjs.map

package/dist/{utils-CZBZ8dgR.mjs.map → utils-DKO55ZmZ.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"utils-CZBZ8dgR.mjs","names":["properties: Record<string, any>","required: string[]"],"sources":["../src/core/utils.ts"],"sourcesContent":["/**\n * Shared utility functions for Gerbil core\n */\n\nimport type { z } from \"zod\";\n\n/**\n * Convert Zod schema to JSON Schema (simplified)\n * Handles objects, arrays, primitives, enums, optionals, and defaults\n */\nexport function zodToJsonSchema(schema: z.ZodType<any>): object {\n  try {\n    if (\"_def\" in schema) {\n      const def = (schema as any)._def;\n\n      if (def.typeName === \"ZodObject\") {\n        const shape = def.shape();\n        const properties: Record<string, any> = {};\n        const required: string[] = [];\n\n        for (const [key, value] of Object.entries(shape)) {\n          properties[key] = zodToJsonSchema(value as z.ZodType<any>);\n          // Check if required (not optional)\n          if (!(value as any)._def?.typeName?.includes(\"Optional\")) {\n            required.push(key);\n          }\n        }\n\n        return { type: \"object\", properties, required };\n      }\n      if (def.typeName === \"ZodString\") {\n        return { type: \"string\", description: def.description };\n      }\n      if (def.typeName === \"ZodNumber\") {\n        return { type: \"number\", description: def.description };\n      }\n      if (def.typeName === \"ZodBoolean\") {\n        return { type: \"boolean\" };\n      }\n      if (def.typeName === \"ZodArray\") {\n        return { type: \"array\", items: zodToJsonSchema(def.type) };\n      }\n      if (def.typeName === \"ZodEnum\") {\n        return { type: \"string\", enum: def.values };\n      }\n      if (def.typeName === \"ZodOptional\") {\n        return zodToJsonSchema(def.innerType);\n      }\n      if (def.typeName === \"ZodDefault\") {\n        const inner = zodToJsonSchema(def.innerType);\n        return { ...inner, default: def.defaultValue() };\n      }\n    }\n  } catch {}\n\n  return { type: \"string\" };\n}\n\n/**\n * Extract JSON from text (finds first { } or [ ] block)\n */\nexport function extractJson(text: string): string {\n  const jsonMatch = text.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    return jsonMatch[0];\n  }\n\n  const arrayMatch = text.match(/\\[[\\s\\S]*\\]/);\n  if (arrayMatch) {\n    return arrayMatch[0];\n  }\n\n  return text;\n}\n"],"mappings":";;;;;AAUA,SAAgB,gBAAgB,QAAgC;AAC9D,KAAI;AACF,MAAI,UAAU,QAAQ;GACpB,MAAM,MAAO,OAAe;AAE5B,OAAI,IAAI,aAAa,aAAa;IAChC,MAAM,QAAQ,IAAI,OAAO;IACzB,MAAMA,aAAkC,EAAE;IAC1C,MAAMC,WAAqB,EAAE;AAE7B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;AAChD,gBAAW,OAAO,gBAAgB,MAAwB;AAE1D,SAAI,CAAE,MAAc,MAAM,UAAU,SAAS,WAAW,CACtD,UAAS,KAAK,IAAI;;AAItB,WAAO;KAAE,MAAM;KAAU;KAAY;KAAU;;AAEjD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,aACnB,QAAO,EAAE,MAAM,WAAW;AAE5B,OAAI,IAAI,aAAa,WACnB,QAAO;IAAE,MAAM;IAAS,OAAO,gBAAgB,IAAI,KAAK;IAAE;AAE5D,OAAI,IAAI,aAAa,UACnB,QAAO;IAAE,MAAM;IAAU,MAAM,IAAI;IAAQ;AAE7C,OAAI,IAAI,aAAa,cACnB,QAAO,gBAAgB,IAAI,UAAU;AAEvC,OAAI,IAAI,aAAa,aAEnB,QAAO;IAAE,GADK,gBAAgB,IAAI,UAAU;IACzB,SAAS,IAAI,cAAc;IAAE;;SAG9C;AAER,QAAO,EAAE,MAAM,UAAU;;;;;AAM3B,SAAgB,YAAY,MAAsB;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc;AAC3C,KAAI,UACF,QAAO,UAAU;CAGnB,MAAM,aAAa,KAAK,MAAM,cAAc;AAC5C,KAAI,WACF,QAAO,WAAW;AAGpB,QAAO"}
+{"version":3,"file":"utils-DKO55ZmZ.mjs","names":["properties: Record<string, any>","required: string[]"],"sources":["../src/core/utils.ts"],"sourcesContent":["/**\n * Shared utility functions for Gerbil core\n */\n\nimport type { z } from \"zod\";\n\n/**\n * Convert Zod schema to JSON Schema (simplified)\n * Handles objects, arrays, primitives, enums, optionals, and defaults\n */\nexport function zodToJsonSchema(schema: z.ZodType<any>): object {\n  try {\n    if (\"_def\" in schema) {\n      const def = (schema as any)._def;\n\n      if (def.typeName === \"ZodObject\") {\n        const shape = def.shape();\n        const properties: Record<string, any> = {};\n        const required: string[] = [];\n\n        for (const [key, value] of Object.entries(shape)) {\n          properties[key] = zodToJsonSchema(value as z.ZodType<any>);\n          // Check if required (not optional)\n          if (!(value as any)._def?.typeName?.includes(\"Optional\")) {\n            required.push(key);\n          }\n        }\n\n        return { type: \"object\", properties, required };\n      }\n      if (def.typeName === \"ZodString\") {\n        return { type: \"string\", description: def.description };\n      }\n      if (def.typeName === \"ZodNumber\") {\n        return { type: \"number\", description: def.description };\n      }\n      if (def.typeName === \"ZodBoolean\") {\n        return { type: \"boolean\" };\n      }\n      if (def.typeName === \"ZodArray\") {\n        return { type: \"array\", items: zodToJsonSchema(def.type) };\n      }\n      if (def.typeName === \"ZodEnum\") {\n        return { type: \"string\", enum: def.values };\n      }\n      if (def.typeName === \"ZodOptional\") {\n        return zodToJsonSchema(def.innerType);\n      }\n      if (def.typeName === \"ZodDefault\") {\n        const inner = zodToJsonSchema(def.innerType);\n        return { ...inner, default: def.defaultValue() };\n      }\n    }\n  } catch {}\n\n  return { type: \"string\" };\n}\n\n/**\n * Extract JSON from text (finds first { } or [ ] block)\n */\nexport function extractJson(text: string): string {\n  const jsonMatch = text.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    return jsonMatch[0];\n  }\n\n  const arrayMatch = text.match(/\\[[\\s\\S]*\\]/);\n  if (arrayMatch) {\n    return arrayMatch[0];\n  }\n\n  return text;\n}\n"],"mappings":";;;;;AAUA,SAAgB,gBAAgB,QAAgC;AAC9D,KAAI;AACF,MAAI,UAAU,QAAQ;GACpB,MAAM,MAAO,OAAe;AAE5B,OAAI,IAAI,aAAa,aAAa;IAChC,MAAM,QAAQ,IAAI,OAAO;IACzB,MAAMA,aAAkC,EAAE;IAC1C,MAAMC,WAAqB,EAAE;AAE7B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;AAChD,gBAAW,OAAO,gBAAgB,MAAwB;AAE1D,SAAI,CAAE,MAAc,MAAM,UAAU,SAAS,WAAW,CACtD,UAAS,KAAK,IAAI;;AAItB,WAAO;KAAE,MAAM;KAAU;KAAY;KAAU;;AAEjD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,aACnB,QAAO,EAAE,MAAM,WAAW;AAE5B,OAAI,IAAI,aAAa,WACnB,QAAO;IAAE,MAAM;IAAS,OAAO,gBAAgB,IAAI,KAAK;IAAE;AAE5D,OAAI,IAAI,aAAa,UACnB,QAAO;IAAE,MAAM;IAAU,MAAM,IAAI;IAAQ;AAE7C,OAAI,IAAI,aAAa,cACnB,QAAO,gBAAgB,IAAI,UAAU;AAEvC,OAAI,IAAI,aAAa,aAEnB,QAAO;IAAE,GADK,gBAAgB,IAAI,UAAU;IACzB,SAAS,IAAI,cAAc;IAAE;;SAG9C;AAER,QAAO,EAAE,MAAM,UAAU;;;;;AAM3B,SAAgB,YAAY,MAAsB;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc;AAC3C,KAAI,UACF,QAAO,UAAU;CAGnB,MAAM,aAAa,KAAK,MAAM,cAAc;AAC5C,KAAI,WACF,QAAO,WAAW;AAGpB,QAAO"}

package/dist/vector-B0panuy6.mjs

@@ -0,0 +1,95 @@
+//#region src/memory/serialize.ts
+/** Convert a runtime record to its JSON-safe form. */
+function serializeRecord(record) {
+	return {
+		id: record.id,
+		text: record.text,
+		embedding: record.embedding ? Array.from(record.embedding) : void 0,
+		metadata: record.metadata,
+		createdAt: record.createdAt
+	};
+}
+/** Rebuild a runtime record (with a {@link Float32Array}) from JSON form. */
+function deserializeRecord(record) {
+	return {
+		id: record.id,
+		text: record.text,
+		embedding: record.embedding ? Float32Array.from(record.embedding) : void 0,
+		metadata: record.metadata ?? {},
+		createdAt: record.createdAt
+	};
+}
+/**
+* True when every key in `filter` is present on `metadata` with an equal
+* (strict ===) value. An empty/undefined filter matches everything.
+*/
+function matchesFilter(metadata, filter) {
+	if (!filter) return true;
+	for (const key of Object.keys(filter)) if (metadata[key] !== filter[key]) return false;
+	return true;
+}
+
+//#endregion
+//#region src/memory/vector.ts
+/**
+* Vector math for cosine similarity search.
+*
+* Vectors are stored L2-normalized so cosine similarity is a plain dot
+* product. Normalization happens once on insert via {@link normalize}.
+*/
+/**
+* Return an L2-normalized copy of `vector`.
+*
+* A zero vector is returned unchanged (its norm is 0).
+*/
+function normalize(vector) {
+	let sumSquares = 0;
+	for (let i = 0; i < vector.length; i++) sumSquares += vector[i] * vector[i];
+	const norm = Math.sqrt(sumSquares);
+	if (norm === 0) return vector;
+	const out = new Float32Array(vector.length);
+	for (let i = 0; i < vector.length; i++) out[i] = vector[i] / norm;
+	return out;
+}
+/**
+* Dot product of two equal-length vectors.
+*
+* For L2-normalized inputs this equals cosine similarity.
+*/
+function dot(a, b) {
+	const length = Math.min(a.length, b.length);
+	let sum = 0;
+	for (let i = 0; i < length; i++) sum += a[i] * b[i];
+	return sum;
+}
+/**
+* Cosine similarity of two vectors, normalizing on the fly.
+*
+* Prefer {@link dot} when both inputs are already normalized.
+*/
+function cosine(a, b) {
+	return dot(normalize(a), normalize(b));
+}
+/**
+* Score every candidate against `query` (dot product) and return the top `k`
+* by descending score, optionally filtering by a minimum score.
+*
+* Inputs are assumed normalized; this keeps the hot path branch-free.
+*/
+function topK(query, candidates, k, minScore) {
+	const scored = [];
+	for (const candidate of candidates) {
+		const score = dot(query, candidate.vector);
+		if (minScore !== void 0 && score < minScore) continue;
+		scored.push({
+			item: candidate.item,
+			score
+		});
+	}
+	scored.sort((a, b) => b.score - a.score);
+	return scored.slice(0, k);
+}
+
+//#endregion
+export { deserializeRecord as a, topK as i, dot as n, matchesFilter as o, normalize as r, serializeRecord as s, cosine as t };
+//# sourceMappingURL=vector-B0panuy6.mjs.map

package/dist/vector-B0panuy6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-B0panuy6.mjs","names":["scored: Scored<T>[]"],"sources":["../src/memory/serialize.ts","../src/memory/vector.ts"],"sourcesContent":["/**\n * (De)serialization helpers shared by stores and import/export.\n *\n * Embeddings are stored at runtime as {@link Float32Array} but serialized as\n * plain number arrays so records survive `JSON.stringify` and IndexedDB\n * structured clone round-trips.\n */\n\nimport type { MemoryRecord, SerializedRecord } from \"./types.js\";\n\n/** Convert a runtime record to its JSON-safe form. */\nexport function serializeRecord(record: MemoryRecord): SerializedRecord {\n  return {\n    id: record.id,\n    text: record.text,\n    embedding: record.embedding ? Array.from(record.embedding) : undefined,\n    metadata: record.metadata,\n    createdAt: record.createdAt,\n  };\n}\n\n/** Rebuild a runtime record (with a {@link Float32Array}) from JSON form. */\nexport function deserializeRecord(record: SerializedRecord): MemoryRecord {\n  return {\n    id: record.id,\n    text: record.text,\n    embedding: record.embedding ? Float32Array.from(record.embedding) : undefined,\n    metadata: record.metadata ?? {},\n    createdAt: record.createdAt,\n  };\n}\n\n/**\n * True when every key in `filter` is present on `metadata` with an equal\n * (strict ===) value. An empty/undefined filter matches everything.\n */\nexport function matchesFilter(\n  metadata: Record<string, unknown>,\n  filter?: Record<string, unknown>,\n): boolean {\n  if (!filter) {\n    return true;\n  }\n  for (const key of Object.keys(filter)) {\n    if (metadata[key] !== filter[key]) {\n      return false;\n    }\n  }\n  return true;\n}\n","/**\n * Vector math for cosine similarity search.\n *\n * Vectors are stored L2-normalized so cosine similarity is a plain dot\n * product. Normalization happens once on insert via {@link normalize}.\n */\n\n/**\n * Return an L2-normalized copy of `vector`.\n *\n * A zero vector is returned unchanged (its norm is 0).\n */\nexport function normalize(vector: Float32Array): Float32Array {\n  let sumSquares = 0;\n  for (let i = 0; i < vector.length; i++) {\n    sumSquares += vector[i] * vector[i];\n  }\n  const norm = Math.sqrt(sumSquares);\n  if (norm === 0) {\n    return vector;\n  }\n  const out = new Float32Array(vector.length);\n  for (let i = 0; i < vector.length; i++) {\n    out[i] = vector[i] / norm;\n  }\n  return out;\n}\n\n/**\n * Dot product of two equal-length vectors.\n *\n * For L2-normalized inputs this equals cosine similarity.\n */\nexport function dot(a: Float32Array, b: Float32Array): number {\n  const length = Math.min(a.length, b.length);\n  let sum = 0;\n  for (let i = 0; i < length; i++) {\n    sum += a[i] * b[i];\n  }\n  return sum;\n}\n\n/**\n * Cosine similarity of two vectors, normalizing on the fly.\n *\n * Prefer {@link dot} when both inputs are already normalized.\n */\nexport function cosine(a: Float32Array, b: Float32Array): number {\n  return dot(normalize(a), normalize(b));\n}\n\n/** A scored item used by {@link topK}. */\nexport type Scored<T> = { item: T; score: number };\n\n/**\n * Score every candidate against `query` (dot product) and return the top `k`\n * by descending score, optionally filtering by a minimum score.\n *\n * Inputs are assumed normalized; this keeps the hot path branch-free.\n */\nexport function topK<T>(\n  query: Float32Array,\n  candidates: { item: T; vector: Float32Array }[],\n  k: number,\n  minScore?: number,\n): Scored<T>[] {\n  const scored: Scored<T>[] = [];\n  for (const candidate of candidates) {\n    const score = dot(query, candidate.vector);\n    if (minScore !== undefined && score < minScore) {\n      continue;\n    }\n    scored.push({ item: candidate.item, score });\n  }\n  scored.sort((a, b) => b.score - a.score);\n  return scored.slice(0, k);\n}\n"],"mappings":";;AAWA,SAAgB,gBAAgB,QAAwC;AACtE,QAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,WAAW,OAAO,YAAY,MAAM,KAAK,OAAO,UAAU,GAAG;EAC7D,UAAU,OAAO;EACjB,WAAW,OAAO;EACnB;;;AAIH,SAAgB,kBAAkB,QAAwC;AACxE,QAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,WAAW,OAAO,YAAY,aAAa,KAAK,OAAO,UAAU,GAAG;EACpE,UAAU,OAAO,YAAY,EAAE;EAC/B,WAAW,OAAO;EACnB;;;;;;AAOH,SAAgB,cACd,UACA,QACS;AACT,KAAI,CAAC,OACH,QAAO;AAET,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CACnC,KAAI,SAAS,SAAS,OAAO,KAC3B,QAAO;AAGX,QAAO;;;;;;;;;;;;;;;;ACpCT,SAAgB,UAAU,QAAoC;CAC5D,IAAI,aAAa;AACjB,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,IACjC,eAAc,OAAO,KAAK,OAAO;CAEnC,MAAM,OAAO,KAAK,KAAK,WAAW;AAClC,KAAI,SAAS,EACX,QAAO;CAET,MAAM,MAAM,IAAI,aAAa,OAAO,OAAO;AAC3C,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,IACjC,KAAI,KAAK,OAAO,KAAK;AAEvB,QAAO;;;;;;;AAQT,SAAgB,IAAI,GAAiB,GAAyB;CAC5D,MAAM,SAAS,KAAK,IAAI,EAAE,QAAQ,EAAE,OAAO;CAC3C,IAAI,MAAM;AACV,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,IAC1B,QAAO,EAAE,KAAK,EAAE;AAElB,QAAO;;;;;;;AAQT,SAAgB,OAAO,GAAiB,GAAyB;AAC/D,QAAO,IAAI,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC;;;;;;;;AAYxC,SAAgB,KACd,OACA,YACA,GACA,UACa;CACb,MAAMA,SAAsB,EAAE;AAC9B,MAAK,MAAM,aAAa,YAAY;EAClC,MAAM,QAAQ,IAAI,OAAO,UAAU,OAAO;AAC1C,MAAI,aAAa,UAAa,QAAQ,SACpC;AAEF,SAAO,KAAK;GAAE,MAAM,UAAU;GAAM;GAAO,CAAC;;AAE9C,QAAO,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;AACxC,QAAO,OAAO,MAAM,GAAG,EAAE"}

package/docs/PROJECT-STATE.md

@@ -0,0 +1,321 @@
+# Gerbil — Project State & Architecture Decision
+
+**As of 2026-06-14.** The single authoritative snapshot. When something here conflicts
+with an older doc, this wins. Supersedes scattered findings in `docs/research/*` and
+the paper's roadmap. **Newest material is §12** (native audio begins — Moonshine STT
++ Kani-TTS-2 NanoCodec decoder; Gemma 4 E2B text decode; on-device memory/RAG; the
+text+ViT autoresearch campaign; gerbil-site live on the native engine). §11 captured
+EmbeddingGemma on-device, LFM2.5, the SPM tokenizer fix, MLX/DWQ loader, progress fix.
+
+---
+
+## 1. What Gerbil is
+
+A local LLM inference library that runs models in the browser and Node on a
+**single native WebGPU engine** behind one task API (no fallback lane — §2). The
+headline achievements this cycle: the from-scratch native engine **works on mobile**
+(iPad/iOS Safari 26.5+, WebKit) — previously it crashed — a desktop optimization
+pass roughly doubled its throughput, and the engine went **multimodal natively**:
+text embeddings ship (Qwen3-Embedding-0.6B) and the Qwen3.5 vision encoder is built
+**bit-exact vs HuggingFace** (vision LM-integration is phase 2).
+
+## 2. The decided architecture — NATIVE-ONLY (owner decision, overrides the panel)
+
+**Decision (owner, 2026-06-13):** Gerbil is a single native WebGPU engine. **No
+tfjs fallback lane** — a permanent fallback "assumes defeat to begin with." The
+panel proposed keeping tfjs as a breadth lane; the owner rejected that. Instead:
+
+- **Launch set = text + vision + embeddings, ALL native.** One model per modality
+  by default, expandable to other families via the add-model-family process.
+- **Audio (TTS/STT) is deferred, not delegated to tfjs** — it ships later as
+  small *native* models (candidates under eval: VibeVoice-1.5B, OmniVoice,
+  dots.tts-soar for TTS — IF they publish safetensors; Moonshine for STT). "What's
+  the big deal" — launching without audio is fine; a permanent second engine is not.
+- **tfjs is at most temporary dev scaffolding, not a destination.** It may stay
+  briefly to keep desktop demos working during the native build, but it is being
+  removed, not kept as a lane. `chrome-backend.ts` is deleted outright.
+- **Vision uses Qwen3.5's OWN built-in ViT** (we currently skip its 192MB tower) —
+  one multimodal model, not a separate vision model. Stop dropping it "like idiots."
+- **A thin onnxruntime-web bridge is a break-glass option only** — used solely if
+  a needed model has no extractable weights AND no native alternative. Not a lane.
+
+**Status update (2026-06-13):** both next modalities have landed natively.
+**Embeddings ship** (Qwen3-Embedding-0.6B, validated). The **vision encoder is
+DONE** — the Qwen3.5 ViT runs natively and is **bit-exact vs HF transformers 5.12**
+(per-token cosine 1.000000). The earlier "parallel attention kernel first" gate was
+based on a misread of dead code (§5): the attention kernel was already parallel, and
+non-causal was a one-line `is_causal` flag, not a rewrite. The remaining vision work
+is **LM-side integration** (M-RoPE, token splice, image preprocessing) — phase 2,
+plumbing over a verified core. Audio follows once a native small model is validated.
+
+## 3. Capability matrix (what's true today)
+
+Native-only. The "tfjs lane" is gone — tfjs is temporary dev scaffolding being
+removed (§2), not a capability path.
+
+| Modality | Native status |
+|---|---|
+| Text | ✅ ~51 tok/s mobile (sustained 200-tok), ~207 desktop, bit-correct |
+| Text (alt family) | ✅ **LFM2.5-350M LANDED** (`Lfm2ForCausalLM`, hybrid conv/attn): ~600 tok/s desktop (2.8× Qwen), ~46 tok/s mobile, ~199MB q4, no new kernels |
+| Embeddings | ✅ **DONE + ON iPad** — **EmbeddingGemma-300M** (bidirectional Gemma3 encoder, 173MB MLX-4bit) runs on iPad Safari; cos=1.00000 vs NumPy ref, Mars/bread margin >0.1, dim 768. First non-Qwen embedder. (Qwen3-Embedding-0.6B still works on desktop but OOMs iPad at 1.2GB BF16.) |
+| Vision (image) | ✅ **END-TO-END DONE** — Qwen3.5 ViT, bit-exact vs HF (cosine 1.000000); `describeImage()` word-identical to HF; runs on iPad |
+| Text model families (Llama/Mistral/Gemma) | 🟢 cheap — now usually **Tier-1, generator-only, NO new kernels** (kernel library saturated for standard transformers) |
+| Text (Gemma 4 E2B) | ✅ **COHERENT on q4** (`gemma4.ts`): "capital of France"→"Paris", ~83 tok/s, all 35 layers cos≥0.998 vs MLX-LM. PLE, KV-share (20 layers), proportional/dual-theta RoPE, GeGLU, `Softcap`, double-wide MLP, V-norm, per-node `attn_scale`, head_dim-512 attention. **PLE CPU-streamed (0 MB GPU)** — not GPU-sharded |
+| STT | 🟢 **Moonshine native LANDED** (`moonshine.ts`, `moonshine-executor.ts`, `moonshine-stt.ts`): raw-waveform Conv1d front-end (no FFT/log-mel), bit-exact `CrossAttention` kernel (max|err|<2e-4, cos≥0.9999), dual-graph encode-once/frozen-K-V/AR-decode, interleaved RoPE. Encoder cos≈0.990 vs HF; transcript substring-matches HF refs. **Whisper(ONNX) stays as multilingual / no-GPU fallback** (`src/core/stt.ts`) |
+| TTS | 🟡 **Kani-TTS-2 partial** (`kani_tts.ts`): NanoCodec decoder (FSQ + causal HiFi-GAN) **LANDED + validated bit-exact** (`test-nanocodec-decode.mjs`, gate err<1e-3, measured ~4.2e-6). LFM2-350M codec-LM backbone scaffolded; **AR-loop glue remaining** (frame positions + learnable RoPE + 4-token-frame decode). License: kani-tts-2-en = LFM1.0/other; 450m variant = Apache |
+| Memory / RAG | ✅ **SHIPPED** (`src/memory/`, `@tryhamster/gerbil/memory`): vector store (in-memory/IndexedDB/file), token-budgeted `recall()`, chunking, redaction, native EmbeddingGemma adapter. 12/12 tests. No new kernels |
+| No-WebGPU / old devices | not targeted — engine throws a clear error rather than degrading |
+
+## 4. Performance baselines (re-confirm before quoting)
+
+| Platform | Config | Decode tok/s | Note |
+|---|---|---|---|
+| M4 Max, node-dawn | optimized | ~207 | re-confirm on a cooled run; numbers between commit 2f0cabc and the isMetalBackend fix are invalid |
+| iPad (iOS 26.5) native | batch-all | ~41 (cooled, consistent) | NOT thermal — confirmed; Dawn-tuned autoresearch wins did NOT transfer to Metal (was ~51 pre-optimization) |
+| iPad native, submit floor | group=1 awaited | 6–8 | proven-correct floor |
+| iPad transformers.js (same model) | WebGPU | 7–12 | ~5× slower than native |
+
+## 5. Vision — DONE at the encoder level (bit-exact vs HF)
+
+The native Qwen3.5 vision encoder is **built and validated bit-exact** against HF
+transformers 5.12: **per-token cosine = 1.000000, max abs err ~5e-6**. Exposed as
+`engine.encodeImage(patches, gridTHW)` → merged image tokens `[rows, 1024]`. See
+paper §22 and `src/gpu/architectures/qwen3_5_vision.ts`, `src/gpu/vision-executor.ts`,
+`src/gpu/vision-preprocess.ts`.
+
+The earlier strategy panel claimed native vision was blocked on a single-threaded
+attention kernel. **That was wrong** — it read `src/gpu/kernels/wgsl/attention.wgsl`,
+a STALE reference file **not imported anywhere** (kernels are embedded strings in
+`registry.ts`; the dead `.wgsl` files have been deleted). What actually shipped:
+
+1. **The live attention kernel was already parallel** — `WGSL_ATTENTION` is a
+   tiled, online-softmax (flash-attention-style) kernel. No thread-0 serialization,
+   no rewrite needed.
+2. **Non-causal was a one-line flag.** An `is_causal` uniform
+   (`S_eff = is_causal ? min(S, causal_limit) : S`) makes it bidirectional for the
+   ViT; text stays causal by default. Done.
+3. **Patch-embed was NOT a new Conv3d kernel.** Patches arrive pre-flattened to
+   `[N, 1536]` from the host image processor, so the 5-D unfold/Conv3d collapses to
+   a plain `MatMul` + `AddBias`. New ops added were small: `AddBias`, `GeluErf`
+   (exact-erf merger GELU), `ApplyRotaryEmb` (2D rotary), `SliceCols` (fused-QKV
+   split) — plus host-side pos-embed/rotary precompute (grid-only, bit-exact).
+4. **A real bug surfaced during validation:** `WGSL_GELU` returned NaN for large
+   args on Metal/Dawn (`x³` overflow into fast-math `tanh`); fixed by clamping the
+   inner arg to ±15.
+
+**Net: vision is done at the encoder level.** Remaining work is **LM-side
+integration** (M-RoPE, image-token splice into the text stream, pixel→patch
+preprocessing) — phase 2, bounded plumbing over a verified numerical core. The
+ViT prefill runs through the same parallel attention as text, so there is no
+separate mobile attention risk; on-device ViT speed is a measure-when-integrated
+item, not a feasibility gate.
+
+## 6. Build sequence (ordered)
+
+1. ~~**Native embeddings**~~ — **DONE.** Qwen3-Embedding-0.6B (`Qwen3ForCausalLM`): last-token EOS pooling + `L2Norm` tail. Validated: dim 1024, unit norm, cos(similar)=0.81 > cos(unrelated)=0.56. Confirmed causal-LM-pooling. `engine.embed()`.
+2. ~~**OPFS model cache**~~ — **resolved differently: OPFS removed.** Main-thread OPFS `createWritable` is broken on iOS (leaves unclearable junk that fills the quota). The loader is now **Cache-API-only**. Durable iOS caching needs a PWA (§ paper 24, `docs/research/ios-safari-model-caching.md`), not OPFS.
+3. ~~**Native vision encoder**~~ — **DONE, bit-exact vs HF** (§5). Remaining: LM-side integration (M-RoPE, token splice, image preprocessing) — phase 2.
+4. **Vision LM integration (phase 2)** — splice `encodeImage()` tokens into the text stream: M-RoPE position assignment, placeholder-token splice, host pixel→patch preprocessing. Plumbing over a verified encoder.
+5. **Close the mobile WebKit correctness/perf sweep** — `?group=N` + Test-R bisect on real iOS 26.5 for a stable fast-and-correct submit config above the group=1 floor; re-measure desktop.
+6. **Llama/Mistral/Gemma graph generator** — ~90% is the existing qwen2 generator; unlocks most of the HF text zoo. Low risk, high ROI.
+7. **Remove tfjs scaffolding** — delete `chrome-backend.ts`. The engine is native-only; tfjs was temporary dev scaffolding, not a kept lane.
+8. **Audio, native (deferred, not delegated)** — TTS: **OmniVoice** (Qwen3 backbone + codec decoder — mostly the existing text path + a decoder). STT: **Moonshine** (lean encoder-decoder; raw-waveform Conv1d frontend, no log-mel Conv2d; needs a parallel CrossAttention kernel). Ship once a native small model clears the mobile bar.
+
+## 7. What NOT to build
+
+- **A second permanent engine / kept tfjs lane** — the architecture is native-only across text + vision + embeddings. tfjs is temporary scaffolding being removed, not a breadth lane.
+- **A Conv3d/unfold patch-embed kernel for the ViT** — not needed; patches arrive pre-flattened, so patch-embed is a plain MatMul + AddBias (§5).
+- **A heavyweight native TTS pipeline with custom vocoder kernels now** — audio is deferred; when it lands, OmniVoice's Qwen3 backbone reuses the text path. A thin onnxruntime-web bridge stays break-glass-only.
+- **A general Conv2d kernel / Whisper-on-native** — Moonshine's raw-waveform Conv1d avoids the log-mel Conv2d.
+- **An OPFS write path on iOS** — main-thread `createWritable` is broken; durable caching is a PWA concern, not an OPFS one.
+- **Trusting stale tok/s numbers** between 2f0cabc and the isMetalBackend fix.
+
+## 8. Open spikes (measure before committing)
+
+- ~~**Embedder pooling direction**~~ — RESOLVED: causal-LM last-token (EOS) pooling, validated.
+- ~~**Parallel non-causal attention feasibility for the ViT**~~ — RESOLVED: the live attention kernel was already parallel; non-causal is a one-line `is_causal` flag; the encoder is bit-exact. Remaining ViT spike: **on-device ViT prefill speed on a real iPad** (measure when LM-integration lands; not a feasibility gate).
+- **Mobile WebKit submit config** — does `?group=N`/Test-R land a stable fast config above the group=1 floor on iOS 26.5? The critical path.
+- **Vision LM-integration correctness** — M-RoPE + token splice must stay bit-exact end-to-end (image+text), not just at the encoder boundary.
+- **Native audio on mobile** — OmniVoice (codec-decoder) and Moonshine (CrossAttention kernel) latency/correctness once a candidate is validated.
+- **Autoresearch on-device tax** — desktop kernel wins did NOT transfer to mobile (41 vs 51); the loop needs a mobile-validation leg, possibly per-backend tunings.
+
+## 9. Decision log (this cycle)
+
+- Mobile native inference fixed (four-bug diagnosis: jetsam memory, WebKit visibility, attention race, detection predicate). See `docs/mobile-failure-diagnosis.md`, paper §17–19.
+- Desktop 145→~207 via autoresearch (paper §20).
+- **Architecture decision: NATIVE-ONLY** across text + vision + embeddings; no tfjs fallback lane; `chrome-backend.ts` to be deleted (paper §23).
+- **Native embeddings shipped** — Qwen3-Embedding-0.6B, last-token EOS pool + L2Norm, validated (paper §21).
+- **Native vision encoder shipped** — Qwen3.5 ViT, bit-exact vs HF transformers 5.12 (cosine 1.000000); LM-integration is phase 2 (paper §22). Supersedes the earlier "skip the ViT" stance (`docs/research/qwen35-multimodal.md`).
+- **Vision feasibility corrected** — attention was already parallel (panel read a dead `.wgsl` file); non-causal is a one-line flag (paper §22–23, §5 above).
+- **OPFS removed** — main-thread `createWritable` broken on iOS; Cache-API-only loader; durable caching needs a PWA (`docs/research/ios-safari-model-caching.md`, paper §24).
+- Modality model picks (`docs/research/sota-modality-models.md`); chromium decision (`docs/research/native-vs-chromium-decision.md`); site update plan (`docs/site-update-plan.md`).
+
+---
+
+## 10. 2026-06-13 evening — multimodal milestone + in-flight work (CAPTURE)
+
+**Major wins this session (all committed to `feat/webgpu-engine-mobile`):**
+
+- **Native VISION end-to-end DONE & validated bit-exact** (commit `5fed12b`). `engine.describeImage({pixels,width,height})` → coherent description. Validated vs HF transformers 5.12 on `examples/skelly.png`: 7/7 checks — encoder cosine 1.000000, M-RoPE 3D position ids EXACT, spliced embeds cosine 1.0, first-token exact, full greedy description WORD-IDENTICAL to HF for 201 chars ("This is a detailed black-and-white line drawing of the skeleton of a fox…"). New ops: `MRoPE`, `EmbedSplice`, host image preprocessing (smart-resize/normalize/patchify in `vision-preprocess.ts`). Text path unchanged (M-RoPE on linear positions reduces to 1D RoPE).
+- **Native EMBEDDINGS** (earlier commit): Qwen3-Embedding-0.6B works on DESKTOP (cosine 0.81>0.56). BUT **not iPad-viable** — only BF16 (~1.2GB, OOMs on-device) or a broken MLX-DWQ. → Pivot below.
+- **`is_causal` flag** on f32 attention (from vision) now unlocks **bidirectional encoders**.
+
+**The 51-vs-41 mobile throughput question — RESOLVED: NOT a regression.** t15 hit 51.7 on a 200-token sustained run; the 38-41 readings were 60-token runs (more warmup overhead/token). A fresh 200-token sustained run on the CURRENT (post-autoresearch-optimization) engine **hit ~51 again**. So the Dawn-tuned wins did NOT regress mobile; sustained mobile decode is ~51 tok/s. Lesson: benchmark with enough tokens (≥200) to be representative.
+
+**IN-FLIGHT / NOT YET MERGED (future-me: merge these):**
+- **LFM2.5-350M** — ✅ **LANDED** on `feat/webgpu-engine-mobile` (commit `3c4bac8`). Tier-1, no new kernels. **~600 tok/s desktop (2.8× Qwen3.5's ~213), ~199MB q4 (half Qwen), coherent, bit-exact vs NumPy ref.** Files: new `src/gpu/architectures/lfm2.ts` (824 lines), registered `Lfm2ForCausalLM`, LFM2 CANONICAL_KEYS, loader key-mapper. TWO GENERAL FIXES worth keeping: (1) effective FF dim is 4608 not config's 6656 (`block_auto_adjust_ff_dim` rounding — `multiple_of(⌊2/3·6656⌋)`); (2) **the "garbage output" was the CHAT TEMPLATE, not the graph** — LFM2.5 ships its template as a `chat_template.jinja` sidecar (absent from tokenizer_config.json), so the engine fell back to Qwen ChatML which auto-injects an empty `<think>` → newline loop. Fix: fetch the `.jinja` sidecar + gate think-injection on the template actually emitting `<think>`. This fix helps ANY model with a jinja sidecar. Verdict: LFM2.5 is a viable faster/smaller text-default alternative to Qwen — user picks.
+- **EmbeddingGemma-300M** — ✅ **LANDED + CONFIRMED ON iPad** (commit `4874d01`, see §11). The iPad-ready embedding model (~173MB q4, MTEB 68.36, standard MLX-4bit). Bidirectional Gemma3 encoder — needs the new generator + a MeanPool kernel + dual-theta RoPE + 2 Dense head layers + the MLX-detection loader fix (research found: detector requires `mode:"affine"` but standard MLX converts omit it → silently fall to F32; and DWQ vs standard MLX are config-indistinguishable → the DWQ-garbage trap). See `docs/research/sota-embedding-models.md`.
+
+**iPad harness:** dashboard at `https://<lan-ip>:8766/` with Text/Vision/transformers.js/Storage-probe/Clear-cache/Stop-queue buttons, live results table, `/results` + `/enqueue` + `/clear-queue` endpoints. Embeddings button removed until EmbeddingGemma lands. TODO: show generated text in the results + default Text benchmark to 200 tokens (representative); wire the Vision button to `describeImage` (needs browser ImageBitmap/Canvas→pixels decode).
+
+**iOS caching:** OPFS removed (main-thread createWritable broken on iOS, left unclearable junk). Durable cache needs a PWA (persist() only granted when installed). See `docs/research/ios-safari-model-caching.md`. Deferred.
+
+**Native modality scorecard (as of §10):** text ✅, vision ✅ (end-to-end bit-exact), embeddings ✅ desktop / iPad-pending (EmbeddingGemma building), LFM2.5 text-alt ✅ (pending merge). Audio (TTS/STT) deferred to native OmniVoice/Moonshine. **The native-only multimodal engine is real.** **→ All "pending/building" items above have since landed; see §11.**
+
+---
+
+## 11. 2026-06-14 — EmbeddingGemma on-device, LFM2.5 landed, loader hardening (CAPTURE)
+
+The §10 in-flight items all landed on `feat/webgpu-engine-mobile`. New wins this session
+(paper §25–§30 document each in depth):
+
+- **EmbeddingGemma-300M LANDED and CONFIRMED RUNNING ON iPad Safari** (commit `4874d01`).
+  First **non-Qwen** embedding family — a real **bidirectional Gemma3 encoder**
+  (`src/gpu/architectures/gemma3_encoder.ts`, `generateGemma3EncoderGraph`): 24 pre-norm
+  blocks, GQA 3q/1kv head_dim 256, per-head q/k-norm, **dual-theta RoPE** (sliding θ=10000
+  / full θ=1e6 selected per layer from `layer_types`), GeGLU MLP, Gemma's **four-norm
+  sandwich**, embed ×√768, tail **MeanPool → Dense0(768→3072) → Dense1(3072→768) → L2Norm**.
+  **173 MB at MLX-4bit** (vs the abandoned 1.2 GB Qwen3-Embedding that OOM'd iPad).
+  Two new kernels only: **MeanPool**, **Scale** (`kernels/registry.ts`). Validated
+  **cos=1.00000 vs an independent NumPy reference** (`scripts/engine/test-embedding-gemma-reference.py`),
+  reference gate `cos>0.95`; semantic test asserts a Red-Planet query is closer to two
+  Mars docs than to a bread doc by **>0.1 cosine margin**, unit-norm dim-768, no NaN. The
+  engine **generalizes across embedding families**, not just Qwen.
+
+- **SPM tokenizer fix (load-bearing, cross-family)** (`src/gpu/tokenizer.ts`). Gemma's
+  `tokenizer.json` is `type:"BPE"` but **SentencePiece-flavored** (▁/U+2581 spaces, raw
+  UTF-8 tokens, array-form merges, `<0xHH>` byte-fallback). The byte-level (`Ġ`) BPE path
+  was char-splitting every word → semantically dead embeddings that still passed norm/NaN
+  checks. Auto-detected `spmMode` (structural: `" "→"▁"` Replace normalizer **or**
+  `byte_fallback && "▁the" in vocab`) now drives encode/decode/merges; **Qwen/LFM2 stay
+  byte-level** (no model-name list — they just don't match). Lesson: `type:"BPE"` ≠
+  byte-level BPE; any SentencePiece-lineage family (Gemma/Llama/Mistral) needs this path.
+
+- **MLX-4bit loader hardened** (`src/gpu/model-loader.ts`). (1) Detection broadened to
+  accept mode-less `{bits:4, group_size}` configs (standard mlx-lm omits `mode`). (2) A
+  `VERIFIED_MLX_REPOS` allowlist (currently `mlx-community/embeddinggemma-300m-4bit`) gates
+  mode-less configs. (3) **Explicit DWQ reject** — DWQ repos carry an identical
+  `{bits:4,group_size}` config but pack weights that dequant to garbage, so they're rejected
+  by repo-name substring (`includes("dwq")`). Codifies the MLX-DWQ-garbage trap. (4) Gemma's
+  `(1+weight)` RMSNorm absorption is **baked by the loader even for MLX** (mlx-lm pre-absorbs
+  +1 for Qwen3.5 but NOT for Gemma — the Gemma branch deliberately omits `&& !isMLX`).
+
+- **Progress-reporting fix** (commit `682a09b`, `model-loader.ts`). The bar froze at
+  "10% discovering weight files" because the gap between that emit and the first download
+  chunk (index probe + 2 header range-requests + first-byte latency) emitted nothing. Now
+  emits "Reading {file} header" + "Downloading {file} (0/{N} MB)" up front. **Affected every
+  model**; fixed universally.
+
+- **LFM2.5-350M landed** (commit `3c4bac8`) — Tier-1, no new kernels, ~600 tok/s desktop /
+  ~46 tok/s mobile, ~199 MB q4. The general jinja-sidecar chat-template fix from it helps any
+  model shipping `chat_template.jinja`.
+
+- **Cross-device multi-modal parity.** Text (Qwen3.5 ~51 tok/s, LFM2.5 ~46 tok/s), vision
+  (Qwen3.5 ViT `describeImage`), and embeddings (EmbeddingGemma) **all now run natively on
+  iPad Safari** — the native engine reaches transformers.js-path modality coverage on the
+  modalities that matter, without the mobile crashes and ~5× faster. **Remaining native gap:
+  audio** — TTS via OmniVoice (in progress), STT via Moonshine (not started).
+
+- **Effort-tier shift.** Adding a new TEXT family is now usually **Tier-1: generator only, no
+  new kernels** — the kernel library has saturated for standard transformers (Llama/Mistral/
+  Gemma-text reuse existing ops). New kernels are needed only for genuinely novel ops (SSM,
+  PLE, new norms, cross-attention). See `docs/adding-a-model-family.md`.
+
+- **Site migration assessment** written: `docs/gerbil-site-native-migration.md` (how the
+  marketing/docs site can move its in-browser inference from the transformers.js/ONNX worker
+  to the native engine, modality-by-modality, with the no-fallback device-coverage tradeoff
+  stated plainly). Assessment only — the site repo was not modified.
+
+---
+
+## 12. 2026-06-14 — native audio begins, Gemma 4, memory/RAG, autoresearch campaign (CAPTURE)
+
+This session pushed past the §11 "multimodal parity minus audio" milestone. Paper
+**§31–§35** document each in depth. The decided order from §6 (audio last, native not
+delegated) held — and audio is now *under way natively*, not deferred to tfjs.
+
+- **Native STT — Moonshine LANDED** (`src/gpu/architectures/moonshine.ts`,
+  `moonshine-executor.ts`, `moonshine-stt.ts`; paper §31). Chosen over Whisper to avoid
+  a log-mel/Conv2d front-end: it consumes **16 kHz PCM directly** through three strided
+  `Conv1d`s (downsample 384×, ~41.6 frames/s) — new kernels `Conv1dFull`, `GroupNorm`,
+  `Tanh`, `Transpose`. The real new attention primitive is **`CrossAttention`**
+  (`WGSL_CROSS_ATTENTION`, tiled online-softmax), validated **bit-exact vs NumPy**
+  (`test-crossattention.mjs`: max|err|<2e-4, cos≥0.9999). Runtime is a **dual graph**:
+  `MoonshineEncoderExecutor.encode()` runs the front-end + bidirectional encoder once and
+  freezes per-decoder-layer K/V; `MoonshineSTT.transcribe()` runs greedy AR decode with
+  self- + cross-attention into that frozen K/V. **Interleaved RoPE** (`ROPE_INTERLEAVED_SPEC`,
+  adjacent-dim pairing) vs the default split-half. Validation: encoder cos≈0.990 vs HF
+  (source comment); `test-moonshine-transcribe.mjs` asserts transcript contains HF-ref
+  substrings; RTF/4-bit size are computed-and-reported, not hardcoded-asserted.
+  **Whisper(ONNX) stays the multilingual / no-WebGPU fallback** (`src/core/stt.ts`,
+  `WhisperSTT`) — separate, untouched.
+
+- **Native TTS — Kani-TTS-2 (partial)** (`src/gpu/architectures/kani_tts.ts`; paper §32).
+  The hard novel piece — the **NanoCodec decoder** (FSQ 4×4 levels `[9,8,8,7]`, mixed-radix
+  base `[1,9,72,576]` + causal HiFi-GAN, rates `[7,7,6,3,2]`, hop 1764 @ 22050 Hz) — is
+  **implemented and validated bit-exact** (`test-nanocodec-decode.mjs`, gate `err<1e-3`,
+  measured ~4.2e-6 vs MLX). New kernels: `FSQDequant`, `HalfSnake1d`,
+  `ConvTranspose1dDepthwise`. The backbone is **LFM2-350M** (`KaniTTS2ForCausalLM`, audio
+  tokens above the text vocab, 4/frame); `generateKaniTtsGraph` **deliberately throws** —
+  remaining is the frame-position + learnable-RoPE + 4-token-frame AR-decode glue (most
+  block math reused from `lfm2.ts`). License: **kani-tts-2-en = LFM1.0 (other)**, NanoCodec
+  = NVIDIA OML; the **450m variant is Apache** (same arch).
+
+- **Gemma 4 E2B — text decode COHERENT on real q4 weights** (`src/gpu/architectures/gemma4.ts`;
+  paper §33). **Tier-2**, no MatFormer/AltUp/LAuReL. **PLE** (2nd embedding gathered per
+  token, per-layer gate+GELU+multiply+project+norm+residual), **KV-cache sharing** (E2B: 35
+  layers, last **20** shared via graph-rewire, no kernel change), **proportional RoPE**
+  (rotate 0.25·head_dim=64 dims but inv_freq over full head_dim denom; dual-theta 1e6/1e4),
+  **GeGLU**, and a new **`Softcap`** kernel (`cap·tanh(x/cap)`, cap=30) on final logits.
+  Generates coherently ("The capital of France is" → "Paris") at ~83 tok/s; all 35 layers
+  match an MLX-LM reference cos≥0.998 with identical argmax (`test-gemma4-perlayer.mjs`).
+  Structural validation **67/67** (`test-gemma4-graph.mjs`; 942 nodes); softcap kernel
+  separately validated (`test-gemma4-softcap.mjs`, max err<1e-4). **PLE is CPU-streamed, not
+  GPU-sharded**: the ~1.17 GB q4 PLE table stays CPU-resident (**0 MB GPU**) and the executor
+  streams per-token rows each step — Gemma 4's intended flash design, mobile-viable, and it
+  sidesteps the per-binding cap. Coherence required four fixes: per-node `attn_scale`=1.0
+  (HF scaling=1.0; default 1/√head_dim keeps other models byte-identical), parameter-free
+  V-norm, double-wide MLP on the KV-shared layers, and head_dim-512 support in the flash
+  attention kernel (second per-thread accumulator + smem-capped tiling, 16 KB invariant kept).
+
+- **On-device Memory / RAG SHIPPED** (`src/memory/`, `@tryhamster/gerbil/memory`; paper §34).
+  Pluggable vector store (`InMemoryStore` / `IndexedDBStore` / `FileStore`), token-budgeted
+  `recall()` (default 1024-token greedy pack, ~4-chars/token, returns `{context, records,
+  tokensUsed}`), overlapping-window chunking (1000/200), write-time redaction (regex →
+  `[REDACTED]` or fn), and a `createGerbilEmbedder()` adapter over **native EmbeddingGemma**.
+  **12/12 tests** (`src/memory/memory.test.ts`). No new kernels — a clean consumer of the
+  embedding modality.
+
+- **Autoresearch TPS campaign — 3 more batches** (`scripts/engine/results.jsonl`,
+  `scripts/engine/chart.html`; paper §35), M4 Max / node-dawn. Verified peaks:
+  **Qwen3.5-0.8B 219→~234 tok/s**, **LFM2.5-350M 624→~672 tok/s**, **ViT encode
+  581.8→~502 ms (−~14%)**, **`describeImage` 37.0→42.0 tok/s (+13.5%)** — all kept changes
+  bit-exact (merged cos 1.0, e2e 7/7). **The winning lesson (sharpened):** desktop wins come
+  only from eliminating **large wide reads on poorly-occupied kernels** (fused conv+activation,
+  vec4 + register-blocked + f16-mixed ViT matmul, `MatMul+AddBias→MatMulBias`); **pure
+  dispatch-count cuts on already-tuned kernels are noise** (butterfly reduce, subgroup
+  shuffle, bigger N-tiles all reverted). The INT4 matmuls and Mamba SSM sit at the
+  **bandwidth floor** — the remaining headroom is **mobile**, not desktop (several
+  reverted-on-desktop fusions are *predicted mobile wins*; the loop's next leg is a
+  mobile-validation pass).
+
+- **gerbil-site is LIVE on the native engine.** The marketing/docs site's in-browser
+  inference now runs on the native WGSL engine (no longer the transformers.js/ONNX worker)
+  for the migrated modalities — see `docs/gerbil-site-native-migration.md`. (The §11 entry
+  was an assessment-only; this cycle it went live.)
+
+**Native modality scorecard (as of §12):** text ✅ (Qwen3.5, LFM2.5), text-alt families 🟢
+Tier-1, Gemma 4 E2B 🟡 (decode validated, sharding gates real weights), vision ✅ (Qwen3.5
+ViT, on iPad), embeddings ✅ (EmbeddingGemma, on iPad), **STT ✅ native (Moonshine) + Whisper
+fallback**, **TTS 🟡 (Kani NanoCodec decoder validated, backbone AR loop pending)**, memory/RAG
+✅ shipped. **Audio is no longer the deferred gap — STT is native; TTS is one AR-loop away.**