mlx-bun 0.3.0 → 0.5.0

package/src/vision/prompt.ts

@@ -17,6 +17,8 @@
 //     multimodal soft tokens (image | audio) — multimodalMask, decoupled
 //     from the bidirectional mask.
 
+import type { EncoderCache } from "../backends/mlx/encoder-cache";
+import type { PromptNativeWork } from "../serve/model-binding";
 import { MlxArray } from "../mlx/array";
 import { Dtype } from "../mlx/ffi";
 import * as ops from "../mlx/ops";
@@ -35,6 +37,7 @@ import { fetchMediaBytes, videoMediaFetchPolicy } from "../media-fetch";
  *  embed_scale). The two own different preprocessing, so the tower carries
  *  its own. */
 export interface VisionEncoder<P extends { softTokens: number } = { softTokens: number }> {
+  readonly cacheIdentity?: string;
   preprocess(bytes: Uint8Array): Promise<P>;
   features(pre: P): MlxArray;
   dispose?(): void;
@@ -42,6 +45,7 @@ export interface VisionEncoder<P extends { softTokens: number } = { softTokens:
 
 export interface VisionPrompt {
   ids: number[];
+  prefixIdentity?: string;
   /** Unscaled merged embeddings [1, L, hidden] — caller disposes. */
   embeddings: MlxArray;
   /** bool [L] image-token mask — caller disposes. */
@@ -50,6 +54,8 @@ export interface VisionPrompt {
 
 export interface MultimodalPrompt {
   ids: number[];
+  /** Includes every media item and the exact token prefix through the last one. */
+  prefixIdentity?: string;
   /** Unscaled merged embeddings [1, L, hidden] — caller disposes. */
   embeddings: MlxArray;
   /** bool [L] image-token mask for the bidirectional attention overlay.
@@ -76,8 +82,8 @@ export interface AudioTokenIds {
 /** The towers a multimodal prompt may need; pass only what the request uses
  *  (vision-only and audio-only fall out as special cases). */
 export interface MultimodalTowers<P extends { softTokens: number }> {
-  vision?: { tower: VisionEncoder<P>; tokenIds: VisionTokenIds };
-  audio?: { tower: AudioTower; tokenIds: AudioTokenIds };
+  vision?: { tower: VisionEncoder<P>; tokenIds: VisionTokenIds; cache?: EncoderCache };
+  audio?: { tower: AudioTower; tokenIds: AudioTokenIds; cache?: EncoderCache };
 }
 
 /** Extract image bytes from OpenAI-style content parts, rewriting the
@@ -223,6 +229,7 @@ export async function buildMultimodalPrompt<P extends { softTokens: number }>(
   images: Uint8Array[],
   audio: Uint8Array[],
   tools: ToolDefinition[] | null = null,
+  nativeWork: PromptNativeWork = (work) => work(),
 ): Promise<MultimodalPrompt> {
   if (images.length > 0 && !towers.vision)
     throw new Error("images present but no vision tower configured");
@@ -280,70 +287,97 @@ export async function buildMultimodalPrompt<P extends { softTokens: number }>(
   if (audIdx !== audio.length)
     throw new Error(`${audio.length} audio clips but ${audIdx} <|audio|> markers`);
 
-  // embed text tokens, then overwrite soft-token rows with tower features
-  const idsArr = ops.fromInt32(spliced, [1, spliced.length]);
-  let embeds = model.embed.encode(idsArr);
-  idsArr.dispose();
-  const hidden = embeds.shape[2]!;
-  for (const run of runs) {
-    let cast: MlxArray;
-    if (run.kind === "image") {
-      // vision towers return pre-divided by embed_scale (their oracle's
-      // frontend convention) — cast to the embedding dtype and splice.
-      const feats = towers.vision!.tower.features(pre[run.index]!); // [1, soft, hidden]
-      cast = feats.astype(embeds.dtype);
-      feats.dispose();
-    } else {
-      // audio mirrors gen-e4b-audio-golden.py EXACTLY:
-      //   features.astype(embeds.dtype) / embed_scale
-      // — raw f32 embed_audio output, cast to bf16 FIRST, then divided by a
-      // weak (dtype-following, i.e. bf16) embed_scale scalar. The order is
-      // load-bearing for the bit-exact greedy gate (see AudioTower.features).
-      const clip = clips[run.index]!;
-      const raw = towers.audio!.tower.features(clip.mel, clip.frames, false); // [1, n, hidden] f32
-      if (raw.shape[1] !== clip.softTokens) {
-        const n = raw.shape[1];
-        raw.dispose();
-        embeds.dispose();
-        throw new Error(`audio tower produced ${n} frames but splice expects ${clip.softTokens}`);
-      }
-      const bf = raw.astype(embeds.dtype);
-      raw.dispose();
-      const scale = ops.scalarLike(towers.audio!.tower.embedScale, bf);
-      cast = ops.div(bf, scale);
-      bf.dispose();
-      scale.dispose();
+  // Exact encoded objects contain no request positions or template state.
+  // CPU preprocessing and SSD reads run before acquiring native execution.
+  const keys = runs.map(run => towers[run.kind === "image" ? "vision" : "audio"]?.cache
+    ? new Bun.CryptoHasher("sha256").update(`gemma-${run.kind}-input-v1`)
+      .update(run.kind === "image" ? images[run.index]! : audio[run.index]!).digest("hex")
+    : "");
+  const lastMedia = runs.at(-1);
+  // A matching namespace guarantees any reused prefix includes all media.
+  // The audio-presence bit also identifies Gemma's causal/bidirectional policy.
+  const prefixIdentity = lastMedia && keys.every(Boolean)
+    ? new Bun.CryptoHasher("sha256").update("gemma-prepared-prefix-v1")
+      .update(JSON.stringify({ audio: audio.length > 0,
+        tokens: spliced.slice(0, lastMedia.start + lastMedia.length),
+        media: runs.map((run, i) => [run.kind, keys[i],
+          (run.kind === "image" ? towers.vision : towers.audio)!.cache!.identity]),
+      })).digest("hex") : undefined;
+  const reused: (MlxArray | null)[] = [];
+  try {
+    for (const [index, run] of runs.entries()) {
+      const cache = run.kind === "image" ? towers.vision?.cache : towers.audio?.cache;
+      reused.push(cache ? await cache.take(keys[index]!) : null);
     }
-    const { start, length } = run;
-    const updated = ops.sliceUpdate(embeds, cast, [0, start, 0], [1, start + length, hidden]);
-    cast.dispose();
-    embeds.dispose();
-    embeds = updated;
-  }
+    return await nativeWork(async () => {
+      // embed text tokens, then overwrite soft-token rows with tower features
+      using idsArr = ops.fromInt32(spliced, [1, spliced.length]);
+      let embeds = model.embed.encode(idsArr);
+      try {
+        const hidden = embeds.shape[2]!;
+        for (const [runIndex, run] of runs.entries()) {
+          let cast: MlxArray;
+          if (run.kind === "image") {
+            // vision towers return pre-divided by embed_scale (their oracle's
+            // frontend convention) — cast to the embedding dtype and splice.
+            const cached = reused[runIndex];
+            using feats = cached ?? towers.vision!.tower.features(pre[run.index]!); // [1, soft, hidden]
+            reused[runIndex] = null;
+            if (!cached) towers.vision!.cache?.put(keys[runIndex]!, feats);
+            cast = feats.astype(embeds.dtype);
+          } else {
+            // audio mirrors gen-e4b-audio-golden.py EXACTLY:
+            //   features.astype(embeds.dtype) / embed_scale
+            // — raw f32 embed_audio output, cast to bf16 FIRST, then divided by a
+            // weak (dtype-following, i.e. bf16) embed_scale scalar. The order is
+            // load-bearing for the bit-exact greedy gate (see AudioTower.features).
+            const clip = clips[run.index]!;
+            const cached = reused[runIndex];
+            using raw = cached ?? towers.audio!.tower.features(clip.mel, clip.frames, false); // [1, n, hidden] f32
+            reused[runIndex] = null;
+            if (raw.shape[1] !== clip.softTokens) {
+              const n = raw.shape[1];
+              throw new Error(`audio tower produced ${n} frames but splice expects ${clip.softTokens}`);
+            }
+            if (!cached) towers.audio!.cache?.put(keys[runIndex]!, raw);
+            using bf = raw.astype(embeds.dtype);
+            using scale = ops.scalarLike(towers.audio!.tower.embedScale, bf);
+            cast = ops.div(bf, scale);
+          }
+          const { start, length } = run;
+          try {
+            const updated = ops.sliceUpdate(embeds, cast, [0, start, 0], [1, start + length, hidden]);
+            embeds.dispose();
+            embeds = updated;
+          } finally { cast.dispose(); }
+        }
 
-  // masks over the spliced sequence: union multimodal soft tokens (per-layer
-  // id zeroing) always; image-only bidirectional overlay only when NO audio
-  // is present (§3.3 Q1).
-  const mmInts = new Int32Array(spliced.length);
-  for (let i = 0; i < spliced.length; i++) {
-    const id = spliced[i]!;
-    mmInts[i] = (vIds && id === vIds.imageTokenId) || (aIds && id === aIds.audioTokenId) ? 1 : 0;
-  }
-  const mmI32 = MlxArray.fromInt32(mmInts, [spliced.length]);
-  const multimodalMask = mmI32.astype(Dtype.bool);
-  mmI32.dispose();
+        // masks over the spliced sequence: union multimodal soft tokens (per-layer
+        // id zeroing) always; image-only bidirectional overlay only when NO audio
+        // is present (§3.3 Q1).
+        const mmInts = new Int32Array(spliced.length);
+        for (let i = 0; i < spliced.length; i++) {
+          const id = spliced[i]!;
+          mmInts[i] = (vIds && id === vIds.imageTokenId) || (aIds && id === aIds.audioTokenId) ? 1 : 0;
+        }
+        const mmI32 = MlxArray.fromInt32(mmInts, [spliced.length]);
+        const multimodalMask = mmI32.astype(Dtype.bool);
+        mmI32.dispose();
 
-  let bidirMask: MlxArray | null = null;
-  if (images.length > 0 && audio.length === 0) {
-    const imgInts = new Int32Array(spliced.length);
-    for (let i = 0; i < spliced.length; i++)
-      imgInts[i] = spliced[i] === vIds!.imageTokenId ? 1 : 0;
-    const imgI32 = MlxArray.fromInt32(imgInts, [spliced.length]);
-    bidirMask = imgI32.astype(Dtype.bool);
-    imgI32.dispose();
-  }
+        let bidirMask: MlxArray | null = null;
+        if (images.length > 0 && audio.length === 0) {
+          const imgInts = new Int32Array(spliced.length);
+          for (let i = 0; i < spliced.length; i++)
+            imgInts[i] = spliced[i] === vIds!.imageTokenId ? 1 : 0;
+          const imgI32 = MlxArray.fromInt32(imgInts, [spliced.length]);
+          bidirMask = imgI32.astype(Dtype.bool);
+          imgI32.dispose();
+        }
 
-  return { ids: spliced, embeddings: embeds, bidirMask, multimodalMask };
+        return { ids: spliced, embeddings: embeds, bidirMask, multimodalMask, prefixIdentity };
+      } catch (error) { embeds.dispose(); throw error; }
+    });
+  } finally { for (const tensor of reused) tensor?.dispose(); }
 }
 
 /** Vision-only prompt (back-compat wrapper over buildMultimodalPrompt —
@@ -360,14 +394,16 @@ export async function buildVisionPrompt<P extends { softTokens: number }>(
   images: Uint8Array[],
   tokenIds: VisionTokenIds,
   tools: ToolDefinition[] | null = null,
+  nativeWork: PromptNativeWork = (work) => work(),
+  cache?: EncoderCache,
 ): Promise<VisionPrompt> {
   const mp = await buildMultimodalPrompt(
-    model, { vision: { tower, tokenIds } }, tokenizer, template,
-    messages, images, [], tools,
+    model, { vision: { tower, tokenIds, cache } }, tokenizer, template,
+    messages, images, [], tools, nativeWork,
   );
   // no audio was passed, so the union mask IS the image mask — reuse it for
   // the zero-image edge (the original builder returned an all-false mask).
   const imageMask = mp.bidirMask ?? mp.multimodalMask;
   if (mp.bidirMask) mp.multimodalMask.dispose();
-  return { ids: mp.ids, embeddings: mp.embeddings, imageMask };
+  return { ids: mp.ids, embeddings: mp.embeddings, imageMask, prefixIdentity: mp.prefixIdentity };
 }

package/src/vision/qwen3vl-prompt.ts

@@ -18,10 +18,12 @@ import type { ChatMessage, ChatTemplate, ToolDefinition } from "../chat-template
 import type { LoadedTokenizer } from "../tokenizer";
 import type { Qwen35Model } from "../model/qwen3_5";
 import { qwenRopeIndex, type MropeRequestState } from "../model/qwen3-mrope";
-import { preprocessQwen3VLImage, preprocessQwen3VLVideoFrames, pyFixed1 } from "./qwen3vl-preprocess";
+import { preprocessQwen3VLImage, preprocessQwen3VLVideoFrames, pyFixed1, type Qwen3VLPreprocessed } from "./qwen3vl-preprocess";
 import { extractVideoFrames } from "./video-frames";
 import { QWEN3VL_MERGE_SIZE } from "./qwen3vl-preprocess";
 import type { Qwen3VLVisionTower } from "./qwen3vl-tower";
+import { createHash } from "node:crypto";
+import type { EncoderCache } from "../backends/mlx/encoder-cache";
 
 export interface Qwen3VLTokenIds {
   imageTokenId: number; // <|image_pad|>
@@ -34,6 +36,7 @@ export interface Qwen3VLTokenIds {
 
 export interface Qwen3VLVisionPrompt {
   ids: number[];
+  prefixIdentity?: string;
   /** [1, L, H] bf16 spliced input embeddings (caller owns → generate()). */
   embeddings: MlxArray;
   /** Request mRoPE state for Qwen35Model.mrope. */
@@ -50,6 +53,8 @@ export async function buildQwen3VLVisionPrompt(
   tokenIds: Qwen3VLTokenIds,
   renderOptions: Parameters<ChatTemplate["render"]>[1] = {},
   videos: Uint8Array[] = [],
+  nativeWork: <T>(work: () => Promise<T>) => Promise<T> = work => work(),
+  encoderCache?: EncoderCache,
 ): Promise<Qwen3VLVisionPrompt> {
   // The request's full template options (tools, enableThinking,
   // reasoningEffort, preserveThinking) flow through — a media prompt must
@@ -71,9 +76,9 @@ export async function buildQwen3VLVisionPrompt(
 
   // Preprocess each medium in its own appearance order; videos decode to
   // sampled frames through the AVFoundation sidecar first.
-  const imagePps = [];
+  const imagePps: Qwen3VLPreprocessed[] = [];
   for (const img of images) imagePps.push(await preprocessQwen3VLImage(img));
-  const videoPps = [];
+  const videoPps: Qwen3VLPreprocessed[] = [];
   for (const vid of videos)
     videoPps.push(preprocessQwen3VLVideoFrames(await extractVideoFrames(vid)));
 
@@ -93,11 +98,13 @@ export async function buildQwen3VLVisionPrompt(
   const grids: [number, number, number][] = [];
   let imgIdx = 0;
   let vidIdx = 0;
+  let lastMediaEnd = 0;
   for (const t of rawIds) {
     if (t === tokenIds.imageTokenId) {
       const pp = imagePps[imgIdx++]!;
       grids.push(pp.gridThw);
       for (let i = 0; i < pp.imageTokens; i++) ids.push(tokenIds.imageTokenId);
+      lastMediaEnd = ids.length;
     } else if (t === tokenIds.videoTokenId) {
       const pp = videoPps[vidIdx++]!;
       const [gridT, gridH, gridW] = pp.gridThw;
@@ -111,6 +118,7 @@ export async function buildQwen3VLVisionPrompt(
         for (let i = 0; i < frameTokens; i++) ids.push(tokenIds.videoTokenId);
         ids.push(visionEndId);
       }
+      lastMediaEnd = ids.length;
     } else ids.push(t);
   }
 
@@ -126,71 +134,100 @@ export async function buildQwen3VLVisionPrompt(
   // path can't reach any of it (2026-08-18 review: repeated failing media
   // requests would otherwise strand un-admitted GPU memory on the GC
   // backstop).
-  const idsArr = ops.fromInt32(ids, [1, ids.length]);
-  const textEmb = model.embed.encode(idsArr); // [1, L, H]
-  idsArr.dispose();
-  const owned: MlxArray[] = [];
+  // Look up exact preprocessed content before entering the execution queue.
+  // URLs are not identities: their contents can change. Position/timestamp
+  // assembly above remains request-owned even when encoder features are reused.
+  const inputs = [...imagePps, ...videoPps];
+  const keys = encoderCache ? inputs.map(pp => createHash("sha256")
+    .update(`qwen3vl-v1:${JSON.stringify(pp.gridThw)}:${pp.rows}:${pp.cols}:`)
+    .update(new Uint8Array(pp.pixelValues.buffer, pp.pixelValues.byteOffset, pp.pixelValues.byteLength))
+    .digest("hex")) : [];
+  const prefixIdentity = encoderCache && lastMediaEnd > 0
+    ? createHash("sha256").update("qwen-prepared-prefix-v1").update(encoderCache.identity)
+      .update(JSON.stringify({ keys, tokens: ids.slice(0, lastMediaEnd), delta: mrope.delta,
+        positions: mrope.positions.map(axis => Array.from(axis.slice(0, lastMediaEnd))),
+      })).digest("hex") : undefined;
+  const reused: Array<MlxArray | null> = [];
   try {
-    const H = textEmb.shape[2]!;
-    const segments: MlxArray[] = [];
-    let cursor = 0;
-    imgIdx = 0;
-    vidIdx = 0;
-    // A video's tower features cover ALL its frame groups; consecutive pad
-    // RUNS consume consecutive feature-row windows.
-    let vidFeat: MlxArray | null = null;
-    let vidRow = 0;
-    for (let i = 0; i < ids.length; ) {
-      const isImage = ids[i] === tokenIds.imageTokenId;
-      const isVideo = ids[i] === tokenIds.videoTokenId;
-      if (isImage || isVideo) {
-        // Measure this contiguous pad run.
-        let runEnd = i;
-        while (runEnd < ids.length && ids[runEnd] === ids[i]) runEnd++;
-        const runLen = runEnd - i;
-        if (cursor < i) {
-          const seg = textEmb.slice([0, cursor, 0], [1, i, H]);
+    for (const key of keys) reused.push(await encoderCache!.take(key));
+    return await nativeWork(async () => {
+      const encode = (index: number): MlxArray => {
+        const cached = reused[index];
+        if (cached) return cached.slice([0, 0], [...cached.shape]);
+        const features = tower.encode(inputs[index]!);
+        try { if (encoderCache) encoderCache.put(keys[index]!, features); }
+        catch (error) { features.dispose(); throw error; }
+        return features;
+      };
+      const idsArr = ops.fromInt32(ids, [1, ids.length]);
+      const textEmb = model.embed.encode(idsArr); // [1, L, H]
+      idsArr.dispose();
+      const owned: MlxArray[] = [];
+      try {
+        const H = textEmb.shape[2]!;
+        const segments: MlxArray[] = [];
+        let cursor = 0;
+        imgIdx = 0;
+        vidIdx = 0;
+        // A video's tower features cover ALL its frame groups; consecutive pad
+        // RUNS consume consecutive feature-row windows.
+        let vidFeat: MlxArray | null = null;
+        let vidRow = 0;
+        for (let i = 0; i < ids.length; ) {
+          const isImage = ids[i] === tokenIds.imageTokenId;
+          const isVideo = ids[i] === tokenIds.videoTokenId;
+          if (isImage || isVideo) {
+            // Measure this contiguous pad run.
+            let runEnd = i;
+            while (runEnd < ids.length && ids[runEnd] === ids[i]) runEnd++;
+            const runLen = runEnd - i;
+            if (cursor < i) {
+              const seg = textEmb.slice([0, cursor, 0], [1, i, H]);
+              segments.push(seg);
+              owned.push(seg);
+            }
+            let rows: MlxArray;
+            if (isImage) {
+              const feat = encode(imgIdx++); // [runLen, H]
+              owned.push(feat);
+              rows = feat;
+            } else {
+              if (!vidFeat) {
+                vidFeat = encode(imagePps.length + vidIdx); // [imageTokens, H]
+                owned.push(vidFeat);
+                vidRow = 0;
+              }
+              const sl = vidFeat.slice([vidRow, 0], [vidRow + runLen, H]);
+              owned.push(sl);
+              rows = sl;
+              vidRow += runLen;
+              if (vidRow >= videoPps[vidIdx]!.imageTokens) {
+                vidFeat = null;
+                vidIdx++;
+              }
+            }
+            const feat3 = ops.reshape(rows, [1, runLen, H]);
+            segments.push(feat3);
+            owned.push(feat3);
+            cursor = runEnd;
+            i = cursor;
+          } else i++;
+        }
+        if (cursor < ids.length) {
+          const seg = textEmb.slice([0, cursor, 0], [1, ids.length, H]);
           segments.push(seg);
           owned.push(seg);
         }
-        let rows: MlxArray;
-        if (isImage) {
-          const feat = tower.encode(imagePps[imgIdx++]!); // [runLen, H]
-          owned.push(feat);
-          rows = feat;
-        } else {
-          if (!vidFeat) {
-            vidFeat = tower.encode(videoPps[vidIdx]!); // [imageTokens, H]
-            owned.push(vidFeat);
-            vidRow = 0;
-          }
-          const sl = vidFeat.slice([vidRow, 0], [vidRow + runLen, H]);
-          owned.push(sl);
-          rows = sl;
-          vidRow += runLen;
-          if (vidRow >= videoPps[vidIdx]!.imageTokens) {
-            vidFeat = null;
-            vidIdx++;
-          }
-        }
-        const feat3 = ops.reshape(rows, [1, runLen, H]);
-        segments.push(feat3);
-        owned.push(feat3);
-        cursor = runEnd;
-        i = cursor;
-      } else i++;
-    }
-    if (cursor < ids.length) {
-      const seg = textEmb.slice([0, cursor, 0], [1, ids.length, H]);
-      segments.push(seg);
-      owned.push(seg);
-    }
-    const embeddings = segments.length === 1
-      ? ops.contiguous(segments[0]!)
-      : ops.concatAxis(segments, 1);
-    return { ids, embeddings, mrope };
+        const embeddings = segments.length === 1
+          ? ops.contiguous(segments[0]!)
+          : ops.concatAxis(segments, 1);
+        return { ids, embeddings, mrope, prefixIdentity };
+      } finally {
+        for (const s of owned) s.dispose();
+        textEmb.dispose();
+      }
+    });
   } finally {
-    for (const s of owned) s.dispose();
-    textEmb.dispose();
+    for (const features of reused) features?.dispose();
   }
 }

package/src/vision/qwen3vl-tower.ts

@@ -18,6 +18,7 @@
 
 import { ptr, read } from "bun:ffi";
 import { existsSync, readFileSync } from "node:fs";
+import { tensorFingerprint } from "../model/fingerprint";
 import { MlxArray, cpuStream } from "../mlx/array";
 import { C, Dtype } from "../mlx/ffi";
 import * as ops from "../mlx/ops";
@@ -55,6 +56,15 @@ interface Block {
 }
 
 export class Qwen3VLVisionTower {
+  #identity: string | undefined;
+  readonly #identityWeights: Array<[string, MlxArray]>;
+
+  /** Computed once, under native preparation. Exact weight content prevents
+   * cross-artifact SSD reuse even when model aliases and shapes are identical. */
+  get cacheIdentity(): string {
+    if (this.#identity) return this.#identity;
+    return this.#identity = tensorFingerprint(this.#identityWeights);
+  }
   #patchW: MlxArray; // [1536, 1152] — flattened conv, already transposed
   #patchB: MlxArray;
   #posEmbed: MlxArray; // [2304, 1152]
@@ -64,6 +74,7 @@ export class Qwen3VLVisionTower {
   #mergerFc2W: MlxArray; #mergerFc2B: MlxArray;
 
   private constructor(w: Map<string, MlxArray>) {
+    this.#identityWeights = [...w];
     const t = (n: string): MlxArray => {
       const a = w.get(`vision_tower.${n}`);
       if (!a) throw new Error(`vision sidecar missing tensor vision_tower.${n}`);

package/src/vision/siglip.ts

@@ -54,6 +54,7 @@
 // composition order. Left at tier-a for now (good enough — grounded, exact ids,
 // greedy prefix); revisit to drive the encoder to 0% by aligning the op order.
 
+import { tensorFingerprint } from "../model/fingerprint";
 import { ptr, read } from "bun:ffi";
 import { MlxArray, cpuStream } from "../mlx/array";
 import { C, Dtype } from "../mlx/ffi";
@@ -189,6 +190,13 @@ export async function preprocessSiglip(
 
 export class SiglipVisionTower {
   #weights = new Map<string, MlxArray>();
+  #cacheIdentity?: string;
+  /** Immutable encoder weights and computation settings, hashed once on use. */
+  get cacheIdentity(): string {
+    return this.#cacheIdentity ??= new Bun.CryptoHasher("sha256")
+      .update("gemma-siglip-v1").update(JSON.stringify([this.cfg, this.embedScale]))
+      .update(tensorFingerprint(this.#weights)).digest("hex");
+  }
   readonly cfg: SiglipVisionConfig;
   readonly embedScale: number;
   #wdtype: Dtype = Dtype.bfloat16;

package/src/web/app.html

@@ -1118,6 +1118,13 @@
   #chat-attach-btn{flex:0 0 auto;width:50px;height:50px;border-radius:14px;background:var(--card);
     border:1px solid var(--hairline);color:var(--ink);font-size:23px;line-height:1;cursor:pointer;transition:background .15s,border-color .15s}
   #chat-attach-btn:hover{background:var(--card-hover);border-color:rgba(10,132,255,.5)}
+  /* hold-to-talk mic (voice.ts) */
+  #chat-mic-btn{flex:0 0 auto;width:50px;height:50px;border-radius:14px;background:var(--card);
+    border:1px solid var(--hairline);color:var(--ink);font-size:20px;line-height:1;cursor:pointer;user-select:none;-webkit-user-select:none;transition:background .15s,border-color .15s}
+  #chat-mic-btn:hover{background:var(--card-hover);border-color:rgba(10,132,255,.5)}
+  #chat-mic-btn.recording{background:rgba(255,69,58,.18);border-color:rgba(255,69,58,.7);animation:micpulse 1s ease-in-out infinite}
+  #chat-mic-btn.busy{opacity:.6;cursor:progress}
+  @keyframes micpulse{0%,100%{box-shadow:0 0 0 0 rgba(255,69,58,.35)}50%{box-shadow:0 0 0 8px rgba(255,69,58,0)}}
   .attach-row{display:none;flex-wrap:wrap;gap:8px;max-width:840px;width:100%;margin:0 auto 8px}
   .attach-chip{display:flex;align-items:center;gap:7px;background:var(--card);border:1px solid var(--hairline);
     border-radius:10px;padding:5px 9px;font-size:12px;max-width:240px}
@@ -1496,6 +1503,11 @@
         <div class="inputrow">
           <button id="chat-attach-btn" class="iconbtn" title="Attach files or images" aria-label="Attach files">＋</button>
           <input type="file" id="chat-file-input" multiple style="display:none">
+          <!-- Hold-to-talk dictation (voice.ts): shown only when the `ready`
+               frame carries transcription=true (a Whisper checkpoint serves
+               /v1/audio/sessions). Press and hold (mouse/touch, or Space/Enter
+               while focused); release to transcribe into the box. -->
+          <button id="chat-mic-btn" class="iconbtn" title="Hold to talk (Whisper)" aria-label="Hold to talk" style="display:none">🎙</button>
           <div id="chat-box-wrap">
             <!-- Keep the placeholder SHORT: the Enter/Shift+Enter AND "#"
                  hints live in the chat-hint status line below (and the Cmd+/