@tryhamster/gerbil 1.0.0-rc.9 → 1.0.0

package/dist/gpu-33qCAtHW.mjs

@@ -0,0 +1,3615 @@
+import { n as resolveDefaultRepo } from "./defaults-9komdrbY.mjs";
+import { C as parseKaniConfig, E as GEMMA4_VIS_KEYS, T as DTYPE_BYTES, _ as generateNanoCodecDecoderGraph, b as kaniLayerAlpha, d as KANI_START_OF_HUMAN, f as audioTokensToCodes, g as generateKaniTtsGraph, m as computeKaniPositions, p as buildKaniLayerCosSin, u as KANI_END_OF_HUMAN, v as kaniAttentionLayerIndices, w as CANONICAL_KEYS, x as kaniSinTensor, y as kaniCosTensor } from "./architectures-C1I5V3Dt.mjs";
+import { c as MATMUL_BIAS_F16C_SPEC, d as createStorageBuffer, f as createUniformBuffer, g as verifyGPU, h as initGPU, i as loadModel, l as clearPipelineCache, m as getOrCreatePipeline, o as Executor, p as destroyBuffers, r as loadKaniTTS, s as KERNEL_REGISTRY, u as createBindGroup } from "./moonshine-stt-v_P_Ci_m.mjs";
+
+//#region src/gpu/architectures/gemma4_vision.ts
+/**
+* Resolve the Gemma 4 vision dims from a raw HF config. Accepts either the
+* top-level config (reads `.vision_config` + `.text_config.hidden_size`) or a
+* bare vision_config (then `textHidden` falls back to the projector row count if
+* present, else hidden). Family-general — no E2B constants.
+*/
+function resolveGemma4VisionInfo(rawConfig) {
+	const vcfg = rawConfig.vision_config ?? rawConfig;
+	const tcfg = rawConfig.text_config ?? {};
+	const hidden_size = vcfg.hidden_size;
+	const num_heads = vcfg.num_attention_heads;
+	const head_dim = vcfg.head_dim ?? Math.floor(hidden_size / num_heads);
+	const depth = vcfg.num_hidden_layers;
+	const intermediate_size = vcfg.intermediate_size;
+	const patch_size = vcfg.patch_size;
+	const patch_dim = (vcfg.num_channels ?? 3) * patch_size * patch_size;
+	const pooling_kernel_size = vcfg.pooling_kernel_size ?? 1;
+	const rope_theta = (vcfg.rope_parameters ?? {}).rope_theta ?? 100;
+	const rms_norm_eps = vcfg.rms_norm_eps ?? 1e-6;
+	return {
+		hiddenSize: hidden_size,
+		numHeads: num_heads,
+		headDim: head_dim,
+		depth,
+		intermediateSize: intermediate_size,
+		textHidden: tcfg.hidden_size ?? hidden_size,
+		patchSize: patch_size,
+		patchDim: patch_dim,
+		poolingKernelSize: pooling_kernel_size,
+		ropeTheta: rope_theta,
+		rmsNormEps: rms_norm_eps
+	};
+}
+/**
+* Dequantize an MLX affine-int4 weight to a plain f32 [rows, cols] matrix.
+* MLX packs 8 int4 values per u32 (low-nibble first); each group of `groupSize`
+* columns shares one scale + bias: w[r,c] = scale[r, c/gs] * q + bias[r, c/gs].
+* Used for the Gemma 4 multimodal projector (`embed_vision.embedding_projection`)
+* in MLX-4bit checkpoints, where (unlike the BF16 ViT body) the projector is int4.
+*/
+function dequantizeMLXProjection(packed, scales, biases, rows, cols, groupSize) {
+	const out = new Float32Array(rows * cols);
+	const numGroups = cols / groupSize;
+	const u32PerRow = cols / 8;
+	for (let r = 0; r < rows; r++) {
+		const rowPacked = r * u32PerRow;
+		const rowScale = r * numGroups;
+		for (let c = 0; c < cols; c++) {
+			const q = packed[rowPacked + (c >> 3)] >>> (c & 7) * 4 & 15;
+			const g = Math.floor(c / groupSize);
+			out[r * cols + c] = scales[rowScale + g] * q + biases[rowScale + g];
+		}
+	}
+	return out;
+}
+/**
+* If the Gemma 4 multimodal projector arrived as an MLX affine-int4 triplet
+* (`embed_vision.embedding_projection.{weight(U32), scales, biases}`), dequantize
+* it in-place to a plain f32 `embed_vision.embedding_projection.weight` and drop
+* the scales/biases, so the vision graph's plain MatMul on the projector works for
+* MLX-4bit checkpoints too. No-op for BF16 (HF) checkpoints (weight already f32).
+*/
+function dequantizeGemma4VisionProjection(weights, groupSize, rows, cols) {
+	const wKey = GEMMA4_VIS_KEYS.projW;
+	const w = weights.get(wKey);
+	const sc = weights.get("embed_vision.embedding_projection.scales");
+	const bi = weights.get("embed_vision.embedding_projection.biases");
+	if (!w || !(w.data instanceof Uint32Array) || !sc || !bi) return;
+	const scales = sc.data instanceof Float32Array ? sc.data : new Float32Array(sc.data.buffer, sc.data.byteOffset, sc.data.byteLength / 4);
+	const biases = bi.data instanceof Float32Array ? bi.data : new Float32Array(bi.data.buffer, bi.data.byteOffset, bi.data.byteLength / 4);
+	const f32 = dequantizeMLXProjection(w.data, scales, biases, rows, cols, groupSize);
+	weights.set(wKey, {
+		data: f32,
+		shape: [rows, cols]
+	});
+	weights.delete("embed_vision.embedding_projection.scales");
+	weights.delete("embed_vision.embedding_projection.biases");
+}
+/**
+* Ensure the Gemma3n multimodal-embedder norm weights exist in the weights map.
+*
+* `embed_vision.embedding_post_projection_norm` is a no-scale RMSNorm in HF
+* (Gemma3nRMSNorm(..., with_scale=False)), so the checkpoint ships NO weight for
+* it — we synthesize a ones gain (matching the kernel's `(x/rms)*weight`).
+*
+* `embed_vision.soft_embedding_norm` IS a learned RMSNorm; the full BF16 repo ships
+* its gain. Lean exports (e.g. some MLX-4bit conversions) omit it — we fall back to
+* a ones gain so the model still loads and produces coherent (if not bit-exact)
+* output. Call BEFORE VisionExecutor.uploadWeights().
+*
+* Gemma 4 vision RMSNorm stores the FULL gain (no +1 bake), so a ones gain is a
+* true identity scale.
+*/
+function ensureGemma4VisionEmbedderNorms(weights, visionHidden, textHidden) {
+	const ones = (n) => ({
+		data: new Float32Array(n).fill(1),
+		shape: [n]
+	});
+	if (!weights.has(GEMMA4_VIS_KEYS.postProjNormW)) weights.set(GEMMA4_VIS_KEYS.postProjNormW, ones(textHidden));
+	if (!weights.has(GEMMA4_VIS_KEYS.softEmbNormW)) weights.set(GEMMA4_VIS_KEYS.softEmbNormW, ones(visionHidden));
+}
+/**
+* Patch the ClippedMatMul nodes of a Gemma 4 vision graph with the calibrated clip
+* scalars from the checkpoint (Gemma4ClippableLinear's per-tensor input/output
+* min/max buffers), then drop those scalar tensors from the weights map so the
+* vision executor doesn't try to upload them as GPU buffers. Call BEFORE
+* VisionExecutor.uploadWeights(). Missing scalars default to ±inf (clip = identity),
+* so a checkpoint without calibration still loads.
+*/
+function patchGemma4VisionClips(graph, weights) {
+	const readScalar = (key) => {
+		if (!key) return void 0;
+		const e = weights.get(key);
+		if (!e) return void 0;
+		const d = e.data instanceof Float32Array ? e.data : new Float32Array(e.data.buffer, e.data.byteOffset, e.data.byteLength / 4);
+		return d.length > 0 ? d[0] : void 0;
+	};
+	for (const node of graph.nodes) {
+		if (node.opType !== "ClippedMatMul") continue;
+		const a = node.attributes;
+		const imin = readScalar(a.clip_input_min_key);
+		const imax = readScalar(a.clip_input_max_key);
+		const omin = readScalar(a.clip_output_min_key);
+		const omax = readScalar(a.clip_output_max_key);
+		if (imin !== void 0) a.imin = imin;
+		if (imax !== void 0) a.imax = imax;
+		if (omin !== void 0) a.omin = omin;
+		if (omax !== void 0) a.omax = omax;
+		for (const k of [
+			a.clip_input_min_key,
+			a.clip_input_max_key,
+			a.clip_output_min_key,
+			a.clip_output_max_key
+		]) if (k) weights.delete(k);
+	}
+}
+/**
+* Build the Gemma 4 ViT graph. Shaped by symbolic "N" (number of patches, runtime)
+* and "Np" (number of pooled tokens = ceil(grid_h/k)·ceil(grid_w/k), runtime),
+* resolved from input tensor dims — like the Qwen ViT's "N"/"Nm".
+*/
+function generateGemma4VisionGraph(rawConfig) {
+	const info = resolveGemma4VisionInfo(rawConfig);
+	const { hiddenSize: hidden_size, numHeads: num_heads, headDim: head_dim, depth, intermediateSize: intermediate_size, textHidden: text_hidden, patchDim: patch_dim, rmsNormEps: eps } = info;
+	const qkv_dim = num_heads * head_dim;
+	const tensors = {};
+	const nodes = [];
+	const executionOrder = [];
+	function addTensor(desc) {
+		tensors[desc.name] = desc;
+	}
+	function addNode(node) {
+		nodes.push(node);
+		executionOrder.push(node.id);
+	}
+	function constant(name, shape, safetensorsKey = name) {
+		addTensor({
+			name,
+			shape,
+			dtype: "f32",
+			storage: "constant",
+			safetensorsKey
+		});
+	}
+	function activation(name, shape) {
+		addTensor({
+			name,
+			shape,
+			dtype: "f32",
+			storage: "activation"
+		});
+	}
+	/** MatMul (no bias): out[M,N] = in[M,K] @ W[N,K]^T. M from `mTensor`. */
+	function matmul(id, input, weight, output, K, N, mTensor) {
+		addNode({
+			id,
+			opType: "MatMul",
+			inputs: [input, weight],
+			outputs: [output],
+			attributes: {
+				M_tensor: mTensor,
+				K,
+				N
+			}
+		});
+	}
+	/**
+	* Gemma4ClippableLinear: out = clamp(clamp(x,imin,imax) @ W^T, omin, omax).
+	* The four clip scalars live in the checkpoint as per-tensor tensors under
+	* `<projBase>.{input_min,input_max,output_min,output_max}`; the loader reads
+	* them and patches the op's imin/imax/omin/omax attributes (and drops the
+	* scalar tensors), like Gemma4's layer_scalar. `projBase` is the canonical
+	* key prefix of the projection (e.g. `vision_tower.encoder.layers.0.self_attn.q_proj`).
+	*/
+	function clippedMatmul(id, input, weight, output, K, N, mTensor, projBase) {
+		addNode({
+			id,
+			opType: "ClippedMatMul",
+			inputs: [input, weight],
+			outputs: [output],
+			attributes: {
+				M_tensor: mTensor,
+				K,
+				N,
+				clip_input_min_key: `${projBase}.input_min`,
+				clip_input_max_key: `${projBase}.input_max`,
+				clip_output_min_key: `${projBase}.output_min`,
+				clip_output_max_key: `${projBase}.output_max`
+			}
+		});
+	}
+	/** RMSNorm over `hidden` (per row), Gemma full-gain (no +1; baked elsewhere=none). */
+	function rmsnorm(id, input, w, output, hidden, seqTensor) {
+		addNode({
+			id,
+			opType: "RMSNorm",
+			inputs: [input, w],
+			outputs: [output],
+			attributes: {
+				hidden_size: hidden,
+				eps,
+				seq_len_tensor: seqTensor
+			}
+		});
+	}
+	function residualAdd(id, a, b, output) {
+		addNode({
+			id,
+			opType: "Add",
+			inputs: [a, b],
+			outputs: [output],
+			attributes: {
+				count_tensor: a,
+				hidden_size
+			}
+		});
+	}
+	activation("g4v_patches", ["N", patch_dim]);
+	activation("g4v_pos_embeds", ["N", hidden_size]);
+	activation("g4v_cos", ["N", head_dim]);
+	activation("g4v_sin", ["N", head_dim]);
+	activation("g4v_pool_w", ["Np", "N"]);
+	constant(GEMMA4_VIS_KEYS.patchEmbedProjW, [hidden_size, patch_dim]);
+	activation("g4v_patch_mm", ["N", hidden_size]);
+	activation("g4v_h0", ["N", hidden_size]);
+	matmul("g4v_patch_proj", "g4v_patches", GEMMA4_VIS_KEYS.patchEmbedProjW, "g4v_patch_mm", patch_dim, hidden_size, "g4v_patches");
+	addNode({
+		id: "g4v_add_pos",
+		opType: "Add",
+		inputs: ["g4v_patch_mm", "g4v_pos_embeds"],
+		outputs: ["g4v_h0"],
+		attributes: {
+			count_tensor: "g4v_patch_mm",
+			hidden_size
+		}
+	});
+	let prev = "g4v_h0";
+	for (let i = 0; i < depth; i++) {
+		const p = `g4v_b${i}`;
+		constant(GEMMA4_VIS_KEYS.inputNorm(i), [hidden_size]);
+		activation(`${p}_n1`, ["N", hidden_size]);
+		rmsnorm(`${p}_input_norm`, prev, GEMMA4_VIS_KEYS.inputNorm(i), `${p}_n1`, hidden_size, prev);
+		constant(GEMMA4_VIS_KEYS.qProjW(i), [qkv_dim, hidden_size]);
+		constant(GEMMA4_VIS_KEYS.kProjW(i), [qkv_dim, hidden_size]);
+		constant(GEMMA4_VIS_KEYS.vProjW(i), [qkv_dim, hidden_size]);
+		activation(`${p}_q`, ["N", qkv_dim]);
+		activation(`${p}_k`, ["N", qkv_dim]);
+		activation(`${p}_v`, ["N", qkv_dim]);
+		const saBase = `vision_tower.encoder.layers.${i}.self_attn`;
+		clippedMatmul(`${p}_q_proj`, `${p}_n1`, GEMMA4_VIS_KEYS.qProjW(i), `${p}_q`, hidden_size, qkv_dim, `${p}_n1`, `${saBase}.q_proj`);
+		clippedMatmul(`${p}_k_proj`, `${p}_n1`, GEMMA4_VIS_KEYS.kProjW(i), `${p}_k`, hidden_size, qkv_dim, `${p}_n1`, `${saBase}.k_proj`);
+		clippedMatmul(`${p}_v_proj`, `${p}_n1`, GEMMA4_VIS_KEYS.vProjW(i), `${p}_v`, hidden_size, qkv_dim, `${p}_n1`, `${saBase}.v_proj`);
+		constant(GEMMA4_VIS_KEYS.qNormW(i), [head_dim]);
+		constant(GEMMA4_VIS_KEYS.kNormW(i), [head_dim]);
+		activation(`${p}_qn`, ["N", qkv_dim]);
+		activation(`${p}_kn`, ["N", qkv_dim]);
+		rmsnorm(`${p}_q_norm`, `${p}_q`, GEMMA4_VIS_KEYS.qNormW(i), `${p}_qn`, head_dim, `${p}_q`);
+		rmsnorm(`${p}_k_norm`, `${p}_k`, GEMMA4_VIS_KEYS.kNormW(i), `${p}_kn`, head_dim, `${p}_k`);
+		activation(`${p}_qr`, ["N", qkv_dim]);
+		activation(`${p}_kr`, ["N", qkv_dim]);
+		addNode({
+			id: `${p}_rope_q`,
+			opType: "ApplyRotaryEmb",
+			inputs: [
+				`${p}_qn`,
+				"g4v_cos",
+				"g4v_sin"
+			],
+			outputs: [`${p}_qr`],
+			attributes: {
+				num_heads,
+				head_dim
+			}
+		});
+		addNode({
+			id: `${p}_rope_k`,
+			opType: "ApplyRotaryEmb",
+			inputs: [
+				`${p}_kn`,
+				"g4v_cos",
+				"g4v_sin"
+			],
+			outputs: [`${p}_kr`],
+			attributes: {
+				num_heads,
+				head_dim
+			}
+		});
+		activation(`${p}_attn`, ["N", qkv_dim]);
+		addNode({
+			id: `${p}_attention`,
+			opType: "Attention",
+			inputs: [
+				`${p}_qr`,
+				`${p}_kr`,
+				`${p}_v`
+			],
+			outputs: [`${p}_attn`],
+			attributes: {
+				num_q_heads: num_heads,
+				num_kv_heads: num_heads,
+				head_dim,
+				causal: false
+			}
+		});
+		constant(GEMMA4_VIS_KEYS.oProjW(i), [hidden_size, qkv_dim]);
+		activation(`${p}_o`, ["N", hidden_size]);
+		clippedMatmul(`${p}_o_proj`, `${p}_attn`, GEMMA4_VIS_KEYS.oProjW(i), `${p}_o`, qkv_dim, hidden_size, `${p}_attn`, `${saBase}.o_proj`);
+		constant(GEMMA4_VIS_KEYS.postAttnNorm(i), [hidden_size]);
+		activation(`${p}_post_attn`, ["N", hidden_size]);
+		rmsnorm(`${p}_post_attn_norm`, `${p}_o`, GEMMA4_VIS_KEYS.postAttnNorm(i), `${p}_post_attn`, hidden_size, `${p}_o`);
+		activation(`${p}_res1`, ["N", hidden_size]);
+		residualAdd(`${p}_residual1`, prev, `${p}_post_attn`, `${p}_res1`);
+		constant(GEMMA4_VIS_KEYS.preFfNorm(i), [hidden_size]);
+		activation(`${p}_n2`, ["N", hidden_size]);
+		rmsnorm(`${p}_pre_ff_norm`, `${p}_res1`, GEMMA4_VIS_KEYS.preFfNorm(i), `${p}_n2`, hidden_size, `${p}_res1`);
+		constant(GEMMA4_VIS_KEYS.gateProjW(i), [intermediate_size, hidden_size]);
+		constant(GEMMA4_VIS_KEYS.upProjW(i), [intermediate_size, hidden_size]);
+		constant(GEMMA4_VIS_KEYS.downProjW(i), [hidden_size, intermediate_size]);
+		activation(`${p}_gate`, ["N", intermediate_size]);
+		activation(`${p}_up`, ["N", intermediate_size]);
+		activation(`${p}_gelu`, ["N", intermediate_size]);
+		activation(`${p}_geglu`, ["N", intermediate_size]);
+		activation(`${p}_mlp`, ["N", hidden_size]);
+		const mlpBase = `vision_tower.encoder.layers.${i}.mlp`;
+		clippedMatmul(`${p}_gate_proj`, `${p}_n2`, GEMMA4_VIS_KEYS.gateProjW(i), `${p}_gate`, hidden_size, intermediate_size, `${p}_n2`, `${mlpBase}.gate_proj`);
+		clippedMatmul(`${p}_up_proj`, `${p}_n2`, GEMMA4_VIS_KEYS.upProjW(i), `${p}_up`, hidden_size, intermediate_size, `${p}_n2`, `${mlpBase}.up_proj`);
+		addNode({
+			id: `${p}_gelu_op`,
+			opType: "GELU",
+			inputs: [`${p}_gate`],
+			outputs: [`${p}_gelu`],
+			attributes: { count_tensor: `${p}_gate` }
+		});
+		addNode({
+			id: `${p}_geglu_mul`,
+			opType: "Mul",
+			inputs: [`${p}_gelu`, `${p}_up`],
+			outputs: [`${p}_geglu`],
+			attributes: {
+				count_tensor: `${p}_gelu`,
+				hidden_size: intermediate_size
+			}
+		});
+		clippedMatmul(`${p}_down_proj`, `${p}_geglu`, GEMMA4_VIS_KEYS.downProjW(i), `${p}_mlp`, intermediate_size, hidden_size, `${p}_geglu`, `${mlpBase}.down_proj`);
+		constant(GEMMA4_VIS_KEYS.postFfNorm(i), [hidden_size]);
+		activation(`${p}_post_ff`, ["N", hidden_size]);
+		rmsnorm(`${p}_post_ff_norm`, `${p}_mlp`, GEMMA4_VIS_KEYS.postFfNorm(i), `${p}_post_ff`, hidden_size, `${p}_res1`);
+		activation(`${p}_res2`, ["N", hidden_size]);
+		residualAdd(`${p}_residual2`, `${p}_res1`, `${p}_post_ff`, `${p}_res2`);
+		prev = `${p}_res2`;
+	}
+	activation("g4v_pooled", ["Np", hidden_size]);
+	addNode({
+		id: "g4v_pool",
+		opType: "PoolMatMul",
+		inputs: ["g4v_pool_w", prev],
+		outputs: ["g4v_pooled"],
+		attributes: {
+			K_tensor: prev,
+			hidden_size,
+			np_tensor: "g4v_pool_w"
+		}
+	});
+	constant(GEMMA4_VIS_KEYS.softEmbNormW, [hidden_size]);
+	activation("g4v_soft_normed", ["Np", hidden_size]);
+	rmsnorm("g4v_soft_emb_norm", "g4v_pooled", GEMMA4_VIS_KEYS.softEmbNormW, "g4v_soft_normed", hidden_size, "g4v_pooled");
+	constant(GEMMA4_VIS_KEYS.projW, [text_hidden, hidden_size]);
+	activation("g4v_proj_out", ["Np", text_hidden]);
+	matmul("g4v_proj", "g4v_soft_normed", GEMMA4_VIS_KEYS.projW, "g4v_proj_out", hidden_size, text_hidden, "g4v_proj_out");
+	constant(GEMMA4_VIS_KEYS.postProjNormW, [text_hidden]);
+	activation("g4v_image_embeds", ["Np", text_hidden]);
+	rmsnorm("g4v_post_proj_norm", "g4v_proj_out", GEMMA4_VIS_KEYS.postProjNormW, "g4v_image_embeds", text_hidden, "g4v_proj_out");
+	return {
+		architecture: "Gemma4VisionModel",
+		config: {
+			hidden_size,
+			num_layers: depth,
+			num_heads,
+			num_kv_heads: num_heads,
+			head_dim,
+			intermediate_size,
+			vocab_size: 0,
+			context_length: rawConfig.vision_config?.max_position_embeddings ?? 0,
+			rms_norm_eps: eps,
+			norm_type: "rmsnorm",
+			rope_base: info.ropeTheta,
+			rope_dim: head_dim,
+			kv_layout: "LHSd",
+			is_moe: false,
+			has_vision_tower: true,
+			vision_architecture: "gemma4_vision",
+			vision_patch_size: info.patchSize,
+			vision_embed_dim: hidden_size
+		},
+		capabilities: {
+			text: true,
+			vision: true,
+			moe: false
+		},
+		tensors,
+		nodes,
+		executionOrder,
+		inputs: [
+			"g4v_patches",
+			"g4v_pos_embeds",
+			"g4v_cos",
+			"g4v_sin",
+			"g4v_pool_w"
+		],
+		outputs: ["g4v_image_embeds"]
+	};
+}
+
+//#endregion
+//#region src/gpu/architectures/qwen3_5_vision.ts
+const VIS_NORM_EPS = 1e-6;
+/**
+* Build the ViT graph. The graph is shaped by symbolic "N" (number of patches),
+* resolved at run time from the input tensor's first dim — exactly like the LM's
+* symbolic "T".
+*/
+function generateQwen3_5VisionGraph(rawConfig) {
+	const vcfg = rawConfig.vision_config ?? rawConfig;
+	const hidden_size = vcfg.hidden_size;
+	const num_heads = vcfg.num_heads;
+	const head_dim = Math.floor(hidden_size / num_heads);
+	const depth = vcfg.depth;
+	const intermediate_size = vcfg.intermediate_size;
+	const out_hidden_size = vcfg.out_hidden_size;
+	const spatial_merge_size = vcfg.spatial_merge_size;
+	const in_channels = vcfg.in_channels;
+	const temporal_patch_size = vcfg.temporal_patch_size;
+	const patch_size = vcfg.patch_size;
+	const patch_dim = in_channels * temporal_patch_size * patch_size * patch_size;
+	const merged_in = hidden_size * (spatial_merge_size * spatial_merge_size);
+	const tensors = {};
+	const nodes = [];
+	const executionOrder = [];
+	function addTensor(desc) {
+		tensors[desc.name] = desc;
+	}
+	function addNode(node) {
+		nodes.push(node);
+		executionOrder.push(node.id);
+	}
+	function constant(name, shape) {
+		addTensor({
+			name,
+			shape,
+			dtype: "f32",
+			storage: "constant",
+			safetensorsKey: name
+		});
+	}
+	function activation(name, shape) {
+		addTensor({
+			name,
+			shape,
+			dtype: "f32",
+			storage: "activation"
+		});
+	}
+	/**
+	* Fused MatMul + row-broadcast bias → out = in @ W^T + bias. Replaces a MatMul
+	* followed by a separate AddBias, removing a full read+write of the matmul
+	* output per ViT linear layer.
+	*/
+	function matmulBias(id, input, weight, bias, output, K, N, mTensor) {
+		addNode({
+			id,
+			opType: "MatMulBias",
+			inputs: [
+				input,
+				weight,
+				bias
+			],
+			outputs: [output],
+			attributes: {
+				M_tensor: mTensor,
+				K,
+				N
+			}
+		});
+	}
+	function layernorm(id, input, w, b, output, hidden, seqTensor) {
+		addNode({
+			id,
+			opType: "LayerNorm",
+			inputs: [
+				input,
+				w,
+				b
+			],
+			outputs: [output],
+			attributes: {
+				hidden_size: hidden,
+				eps: VIS_NORM_EPS,
+				seq_len_tensor: seqTensor
+			}
+		});
+	}
+	activation("vis_patches", ["N", patch_dim]);
+	activation("vis_pos_embeds", ["N", hidden_size]);
+	activation("vis_cos", ["N", head_dim]);
+	activation("vis_sin", ["N", head_dim]);
+	constant(CANONICAL_KEYS.visPatchEmbedWeight, [hidden_size, patch_dim]);
+	constant(CANONICAL_KEYS.visPatchEmbedBias, [hidden_size]);
+	activation("vis_patch_mm", ["N", hidden_size]);
+	activation("vis_patch_bias", ["N", hidden_size]);
+	activation("vis_h0", ["N", hidden_size]);
+	matmulBias("vis_patch_mm", "vis_patches", CANONICAL_KEYS.visPatchEmbedWeight, CANONICAL_KEYS.visPatchEmbedBias, "vis_patch_bias", patch_dim, hidden_size, "vis_patches");
+	addNode({
+		id: "vis_add_pos",
+		opType: "Add",
+		inputs: ["vis_patch_bias", "vis_pos_embeds"],
+		outputs: ["vis_h0"],
+		attributes: {
+			count_tensor: "vis_patch_bias",
+			hidden_size
+		}
+	});
+	let prev = "vis_h0";
+	const qkv_dim = hidden_size * 3;
+	for (let i = 0; i < depth; i++) {
+		const p = `vis_b${i}`;
+		constant(CANONICAL_KEYS.visBlockNorm1W(i), [hidden_size]);
+		constant(CANONICAL_KEYS.visBlockNorm1B(i), [hidden_size]);
+		activation(`${p}_n1`, ["N", hidden_size]);
+		layernorm(`${p}_norm1`, prev, CANONICAL_KEYS.visBlockNorm1W(i), CANONICAL_KEYS.visBlockNorm1B(i), `${p}_n1`, hidden_size, prev);
+		constant(CANONICAL_KEYS.visBlockQkvW(i), [qkv_dim, hidden_size]);
+		constant(CANONICAL_KEYS.visBlockQkvB(i), [qkv_dim]);
+		activation(`${p}_qkv_mm`, ["N", qkv_dim]);
+		activation(`${p}_qkv`, ["N", qkv_dim]);
+		matmulBias(`${p}_qkv_proj`, `${p}_n1`, CANONICAL_KEYS.visBlockQkvW(i), CANONICAL_KEYS.visBlockQkvB(i), `${p}_qkv`, hidden_size, qkv_dim, `${p}_n1`);
+		activation(`${p}_q`, ["N", hidden_size]);
+		activation(`${p}_k`, ["N", hidden_size]);
+		activation(`${p}_v`, ["N", hidden_size]);
+		const sliceCols = (id, output, offset) => addNode({
+			id,
+			opType: "SliceCols",
+			inputs: [`${p}_qkv`],
+			outputs: [output],
+			attributes: {
+				in_width: qkv_dim,
+				out_width: hidden_size,
+				col_offset: offset,
+				seq_len_tensor: `${p}_qkv`
+			}
+		});
+		sliceCols(`${p}_split_q`, `${p}_q`, 0);
+		sliceCols(`${p}_split_k`, `${p}_k`, hidden_size);
+		sliceCols(`${p}_split_v`, `${p}_v`, 2 * hidden_size);
+		activation(`${p}_qr`, ["N", hidden_size]);
+		activation(`${p}_kr`, ["N", hidden_size]);
+		addNode({
+			id: `${p}_rope_q`,
+			opType: "ApplyRotaryEmb",
+			inputs: [
+				`${p}_q`,
+				"vis_cos",
+				"vis_sin"
+			],
+			outputs: [`${p}_qr`],
+			attributes: {
+				num_heads,
+				head_dim
+			}
+		});
+		addNode({
+			id: `${p}_rope_k`,
+			opType: "ApplyRotaryEmb",
+			inputs: [
+				`${p}_k`,
+				"vis_cos",
+				"vis_sin"
+			],
+			outputs: [`${p}_kr`],
+			attributes: {
+				num_heads,
+				head_dim
+			}
+		});
+		activation(`${p}_attn`, ["N", hidden_size]);
+		addNode({
+			id: `${p}_attention`,
+			opType: "Attention",
+			inputs: [
+				`${p}_qr`,
+				`${p}_kr`,
+				`${p}_v`
+			],
+			outputs: [`${p}_attn`],
+			attributes: {
+				num_q_heads: num_heads,
+				num_kv_heads: num_heads,
+				head_dim,
+				causal: false
+			}
+		});
+		constant(CANONICAL_KEYS.visBlockProjW(i), [hidden_size, hidden_size]);
+		constant(CANONICAL_KEYS.visBlockProjB(i), [hidden_size]);
+		activation(`${p}_proj_mm`, ["N", hidden_size]);
+		activation(`${p}_proj`, ["N", hidden_size]);
+		matmulBias(`${p}_proj_op`, `${p}_attn`, CANONICAL_KEYS.visBlockProjW(i), CANONICAL_KEYS.visBlockProjB(i), `${p}_proj`, hidden_size, hidden_size, `${p}_attn`);
+		activation(`${p}_res1`, ["N", hidden_size]);
+		addNode({
+			id: `${p}_residual1`,
+			opType: "Add",
+			inputs: [prev, `${p}_proj`],
+			outputs: [`${p}_res1`],
+			attributes: {
+				count_tensor: prev,
+				hidden_size
+			}
+		});
+		constant(CANONICAL_KEYS.visBlockNorm2W(i), [hidden_size]);
+		constant(CANONICAL_KEYS.visBlockNorm2B(i), [hidden_size]);
+		constant(CANONICAL_KEYS.visBlockFc1W(i), [intermediate_size, hidden_size]);
+		constant(CANONICAL_KEYS.visBlockFc1B(i), [intermediate_size]);
+		constant(CANONICAL_KEYS.visBlockFc2W(i), [hidden_size, intermediate_size]);
+		constant(CANONICAL_KEYS.visBlockFc2B(i), [hidden_size]);
+		activation(`${p}_n2`, ["N", hidden_size]);
+		activation(`${p}_fc1_mm`, ["N", intermediate_size]);
+		activation(`${p}_fc1`, ["N", intermediate_size]);
+		activation(`${p}_gelu`, ["N", intermediate_size]);
+		activation(`${p}_fc2_mm`, ["N", hidden_size]);
+		activation(`${p}_fc2`, ["N", hidden_size]);
+		activation(`${p}_res2`, ["N", hidden_size]);
+		layernorm(`${p}_norm2`, `${p}_res1`, CANONICAL_KEYS.visBlockNorm2W(i), CANONICAL_KEYS.visBlockNorm2B(i), `${p}_n2`, hidden_size, `${p}_res1`);
+		matmulBias(`${p}_fc1_op`, `${p}_n2`, CANONICAL_KEYS.visBlockFc1W(i), CANONICAL_KEYS.visBlockFc1B(i), `${p}_fc1`, hidden_size, intermediate_size, `${p}_n2`);
+		addNode({
+			id: `${p}_gelu_op`,
+			opType: "GELU",
+			inputs: [`${p}_fc1`],
+			outputs: [`${p}_gelu`],
+			attributes: { count_tensor: `${p}_fc1` }
+		});
+		matmulBias(`${p}_fc2_op`, `${p}_gelu`, CANONICAL_KEYS.visBlockFc2W(i), CANONICAL_KEYS.visBlockFc2B(i), `${p}_fc2`, intermediate_size, hidden_size, `${p}_gelu`);
+		addNode({
+			id: `${p}_residual2`,
+			opType: "Add",
+			inputs: [`${p}_res1`, `${p}_fc2`],
+			outputs: [`${p}_res2`],
+			attributes: {
+				count_tensor: `${p}_res1`,
+				hidden_size
+			}
+		});
+		prev = `${p}_res2`;
+	}
+	constant(CANONICAL_KEYS.visMergerNormW, [hidden_size]);
+	constant(CANONICAL_KEYS.visMergerNormB, [hidden_size]);
+	constant(CANONICAL_KEYS.visMergerFc1W, [merged_in, merged_in]);
+	constant(CANONICAL_KEYS.visMergerFc1B, [merged_in]);
+	constant(CANONICAL_KEYS.visMergerFc2W, [out_hidden_size, merged_in]);
+	constant(CANONICAL_KEYS.visMergerFc2B, [out_hidden_size]);
+	activation("vis_merge_norm", ["N", hidden_size]);
+	activation("vis_merge_fc1_mm", ["Nm", merged_in]);
+	activation("vis_merge_fc1", ["Nm", merged_in]);
+	activation("vis_merge_gelu", ["Nm", merged_in]);
+	activation("vis_merge_fc2_mm", ["Nm", out_hidden_size]);
+	activation("vis_image_embeds", ["Nm", out_hidden_size]);
+	layernorm("vis_merger_norm", prev, CANONICAL_KEYS.visMergerNormW, CANONICAL_KEYS.visMergerNormB, "vis_merge_norm", hidden_size, prev);
+	matmulBias("vis_merger_fc1", "vis_merge_norm", CANONICAL_KEYS.visMergerFc1W, CANONICAL_KEYS.visMergerFc1B, "vis_merge_fc1", merged_in, merged_in, "vis_merge_fc1");
+	addNode({
+		id: "vis_merger_gelu",
+		opType: "GeluErf",
+		inputs: ["vis_merge_fc1"],
+		outputs: ["vis_merge_gelu"],
+		attributes: { count_tensor: "vis_merge_fc1" }
+	});
+	matmulBias("vis_merger_fc2", "vis_merge_gelu", CANONICAL_KEYS.visMergerFc2W, CANONICAL_KEYS.visMergerFc2B, "vis_image_embeds", merged_in, out_hidden_size, "vis_image_embeds");
+	return {
+		architecture: "Qwen3_5VisionModel",
+		config: {
+			hidden_size,
+			num_layers: depth,
+			num_heads,
+			num_kv_heads: num_heads,
+			head_dim,
+			intermediate_size,
+			vocab_size: 0,
+			context_length: vcfg.num_position_embeddings,
+			rms_norm_eps: VIS_NORM_EPS,
+			norm_type: "layernorm",
+			rope_base: 1e4,
+			rope_dim: head_dim,
+			kv_layout: "LHSd",
+			is_moe: false,
+			has_vision_tower: true,
+			vision_architecture: "qwen3_5_vit",
+			vision_patch_size: patch_size,
+			vision_embed_dim: hidden_size
+		},
+		capabilities: {
+			text: true,
+			vision: true,
+			moe: false
+		},
+		tensors,
+		nodes,
+		executionOrder,
+		inputs: [
+			"vis_patches",
+			"vis_pos_embeds",
+			"vis_cos",
+			"vis_sin"
+		],
+		outputs: ["vis_image_embeds"]
+	};
+}
+
+//#endregion
+//#region src/gpu/kani-tts.ts
+/**
+* KaniTTS — native text-to-speech engine for Gerbil's WebGPU backend.
+*
+* Kani-TTS-2 (nineninesix/kani-tts-2-en) is a two-stage TTS model that, like
+* Moonshine, needs more than one graph:
+*
+*   1. CODEC-LM BACKBONE (LFM2-350M body): autoregressively emits NanoCodec audio
+*      tokens (4 per frame) into the same vocab as text. Reuses LFM2's block math
+*      with two KaniTTS2 deltas — frame-level position IDs (the 4 audio tokens of a
+*      frame share a position) and learnable per-layer RoPE (α^(l)-scaled freqs) —
+*      both folded host-side into per-layer cos/sin tables fed to the MRoPE op.
+*   2. NANOCODEC DECODER (NVIDIA NeMo 22 kHz): FSQ dequant + causal HiFi-GAN conv
+*      decoder → 22 kHz PCM. Validated bit-exact vs MLX (test-nanocodec-decode.mjs).
+*
+* The AR loop runs on the host with full-logit readback so each frame's 4 audio
+* tokens are sampled per-codebook (constrained to the valid codebook window), then
+* the collected codes are decoded once through the NanoCodec graph.
+*
+* Validated on Dawn (desktop) via scripts/engine/test-kani-speak.mjs.
+*/
+const KANI_SAMPLE_RATE = 22050;
+const KANI_HOP = 1764;
+const KANI_END_OF_TEXT = 2;
+/** NanoCodec decode chunking (keeps per-dispatch under WebGPU's 65535 cap). */
+const KANI_CODEC_CHUNK_FRAMES = 32;
+const KANI_CODEC_LOOKBACK_FRAMES = 32;
+/** Hard cap so a stuck decode cannot loop forever (reference uses 3000). */
+const DEFAULT_MAX_NEW_TOKENS = 3e3;
+/** Build a fresh map of just the constant weights a graph references (see moonshine-stt). */
+function selectGraphWeights(graph, weights) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [name, desc] of Object.entries(graph.tensors)) {
+		if (desc.storage !== "constant") continue;
+		const w = weights.get(name) ?? (desc.safetensorsKey ? weights.get(desc.safetensorsKey) : void 0);
+		if (w) out.set(name, w);
+	}
+	return out;
+}
+/**
+* Top-p nucleus sample from a (already softmaxed) probability array over `ids`.
+* Sorts by prob desc, keeps the smallest prefix whose cumulative mass ≥ topP,
+* renormalizes, and samples one id.
+*/
+function nucleusSample(probs, ids, topP) {
+	const n = probs.length;
+	const order = Array.from({ length: n }, (_, i) => i).sort((a, b) => probs[b] - probs[a]);
+	let cum = 0;
+	let cutoff = n;
+	for (let r = 0; r < n; r++) {
+		cum += probs[order[r]];
+		if (cum >= topP) {
+			cutoff = r + 1;
+			break;
+		}
+	}
+	let keepSum = 0;
+	for (let r = 0; r < cutoff; r++) keepSum += probs[order[r]];
+	let pick = Math.random() * keepSum;
+	for (let r = 0; r < cutoff; r++) {
+		pick -= probs[order[r]];
+		if (pick <= 0) return ids[order[r]];
+	}
+	return ids[order[0]];
+}
+/** In-place softmax of `scores`. */
+function softmaxInPlace(scores) {
+	let maxV = Number.NEGATIVE_INFINITY;
+	for (let i = 0; i < scores.length; i++) if (scores[i] > maxV) maxV = scores[i];
+	let sum = 0;
+	for (let i = 0; i < scores.length; i++) {
+		const e = Math.exp(scores[i] - maxV);
+		scores[i] = e;
+		sum += e;
+	}
+	for (let i = 0; i < scores.length; i++) scores[i] /= sum;
+}
+var KaniTTS = class KaniTTS {
+	ctx;
+	loaded;
+	tokenizer;
+	cfg;
+	rawConfig;
+	maxSeqLen;
+	/** Backbone executor (built once; reused across speak() calls). */
+	backboneExec;
+	/** The attention layer indices (carry learnable α) and their α values. */
+	attnLayers;
+	layerAlpha;
+	headDim;
+	ropeBase;
+	_destroyed = false;
+	architecture = "KaniTTS2ForCausalLM";
+	constructor(ctx, loaded, maxSeqLen) {
+		this.ctx = ctx;
+		this.loaded = loaded;
+		this.tokenizer = loaded.tokenizer;
+		this.rawConfig = loaded.rawConfig;
+		this.cfg = parseKaniConfig(loaded.rawConfig);
+		this.maxSeqLen = maxSeqLen;
+		const hidden = this.rawConfig.hidden_size;
+		const heads = this.rawConfig.num_attention_heads;
+		this.headDim = this.rawConfig.head_dim ?? Math.floor(hidden / heads);
+		this.ropeBase = this.rawConfig.rope_theta ?? 1e6;
+		this.attnLayers = kaniAttentionLayerIndices(this.rawConfig);
+		this.layerAlpha = /* @__PURE__ */ new Map();
+		const useLearnable = this.rawConfig.use_learnable_rope ?? false;
+		for (const layer of this.attnLayers) {
+			let alpha = 1;
+			if (useLearnable) {
+				const w = loaded.backboneWeights.get(`learnable_rope_layers.${layer}.alpha_weight`);
+				alpha = kaniLayerAlpha(w ? w.data[0] ?? 0 : 0, this.cfg);
+			}
+			this.layerAlpha.set(layer, alpha);
+		}
+		const graph = generateKaniTtsGraph(this.rawConfig);
+		this.backboneExec = new Executor(ctx, graph, {
+			maxSeqLen,
+			kvMode: "f32"
+		});
+		this.backboneExec.uploadWeightsMap(selectGraphWeights(graph, loaded.backboneWeights));
+		this.backboneExec.initBindGroups();
+	}
+	static async create(options = {}) {
+		const ctx = await initGPU();
+		const loaded = await loadKaniTTS({
+			repo: options.repo,
+			codecRepo: options.codecRepo,
+			revision: options.revision,
+			hfToken: options.hfToken,
+			cacheDir: options.cacheDir,
+			onProgress: options.onProgress
+		});
+		const ctxLen = loaded.rawConfig.max_position_embeddings ?? 4096;
+		return new KaniTTS(ctx, loaded, Math.min(options.maxSeqLen ?? 2048, ctxLen));
+	}
+	/** Write per-layer cos/sin for token rows [rowStart, rowStart+positions.length). */
+	writeCosSin(positions, rowStart) {
+		const rowBytes = this.headDim * 4;
+		for (const layer of this.attnLayers) {
+			const alpha = this.layerAlpha.get(layer) ?? 1;
+			const { cos, sin } = buildKaniLayerCosSin(positions, this.headDim, this.ropeBase, alpha);
+			if (rowStart === 0) {
+				this.backboneExec.writeInput(kaniCosTensor(layer), cos);
+				this.backboneExec.writeInput(kaniSinTensor(layer), sin);
+			} else {
+				this.backboneExec.writeInputAt(kaniCosTensor(layer), cos, rowStart * rowBytes);
+				this.backboneExec.writeInputAt(kaniSinTensor(layer), sin, rowStart * rowBytes);
+			}
+		}
+	}
+	/**
+	* Synthesize speech for `text`. Returns 22 kHz mono PCM.
+	*
+	* Pipeline: build the [SOH]+text+[EOT,EOH] prompt → prefill the codec-LM →
+	* AR-decode 4-token frames (per-codebook constrained sampling) until end_of_speech
+	* → strip markers → codes → NanoCodec decode → PCM.
+	*/
+	async speak(text, opts = {}) {
+		if (this._destroyed) throw new Error("KaniTTS has been destroyed.");
+		const temperature = opts.temperature ?? 1;
+		const topP = opts.topP ?? .95;
+		const repetitionPenalty = opts.repetitionPenalty ?? 1.1;
+		const tag = opts.languageTag ?? "en_us";
+		const maxNewTokens = Math.min(opts.maxNewTokens ?? DEFAULT_MAX_NEW_TOKENS, this.maxSeqLen);
+		const prompt = [
+			KANI_START_OF_HUMAN,
+			...this.tokenizer.encode(`${tag.trim()}: ${text}`),
+			KANI_END_OF_TEXT,
+			KANI_END_OF_HUMAN
+		];
+		if (prompt.length >= this.maxSeqLen) throw new Error(`Kani prompt is ${prompt.length} tokens >= maxSeqLen ${this.maxSeqLen}.`);
+		this.backboneExec.reset();
+		const promptPos = computeKaniPositions(prompt, this.cfg);
+		this.writeCosSin(promptPos, 0);
+		const { logits } = await this.backboneExec.forward(new Uint32Array(prompt));
+		const startTime = performance.now();
+		const { audioTokens, finished } = await this.runDecodeLoop(prompt, logits, {
+			temperature,
+			topP,
+			repetitionPenalty,
+			maxNewTokens,
+			maxFrames: opts.maxFrames ?? Number.POSITIVE_INFINITY
+		});
+		const usable = audioTokens.length - audioTokens.length % this.cfg.tokensPerFrame;
+		if (usable === 0) throw new Error(`Kani produced no complete audio frames (finished=${finished}, audioTokens=${audioTokens.length}). The codec-LM emitted no speech.`);
+		const { codes, numFrames } = audioTokensToCodes(audioTokens.slice(0, usable), this.cfg);
+		const pcm = await this.decodeCodes(codes, numFrames);
+		const totalTime = (performance.now() - startTime) / 1e3;
+		const audioSeconds = numFrames * KANI_HOP / KANI_SAMPLE_RATE;
+		console.log(`[kani] frames=${numFrames} audio=${audioSeconds.toFixed(2)}s wall=${totalTime.toFixed(2)}s RTF=${(audioSeconds / totalTime).toFixed(2)}x`);
+		return {
+			pcm,
+			sampleRate: KANI_SAMPLE_RATE,
+			frames: numFrames,
+			audioSeconds
+		};
+	}
+	/**
+	* Autoregressive decode: from the prefill logits, emit one token per step —
+	* greedy for the structural markers ([SOA][SOS]) and per-codebook constrained
+	* sampling once in speech — collecting the audio tokens between SOS and EOS.
+	* Writes each step's per-layer cos/sin row (frame-level logical position) before
+	* the forward. Returns the collected audio tokens and whether EOS/cap was hit.
+	*/
+	async runDecodeLoop(prompt, prefillLogits, p) {
+		const seq = [...prompt];
+		const audioTokens = [];
+		const frameCap = p.maxFrames * this.cfg.tokensPerFrame;
+		let logits = prefillLogits;
+		let inSpeech = false;
+		let finished = false;
+		for (let step = 0; step < p.maxNewTokens; step++) {
+			const nextToken = inSpeech ? this.sampleAudioToken(logits, audioTokens.length % this.cfg.tokensPerFrame, {
+				temperature: p.temperature,
+				topP: p.topP,
+				repetitionPenalty: p.repetitionPenalty,
+				previous: seq
+			}) : this.argmax(logits);
+			if (nextToken === this.cfg.startOfSpeech) inSpeech = true;
+			else if (nextToken === this.cfg.endOfSpeech) {
+				seq.push(nextToken);
+				finished = true;
+				break;
+			} else if (inSpeech && nextToken >= this.cfg.audioTokensStart) audioTokens.push(nextToken);
+			seq.push(nextToken);
+			if (inSpeech && audioTokens.length >= frameCap) {
+				finished = true;
+				break;
+			}
+			if (seq.length >= this.maxSeqLen) break;
+			this.writeCosSin(Float32Array.of(this.logicalPositionAt(seq)), this.backboneExec.currentSeqPos);
+			logits = (await this.backboneExec.forward(new Uint32Array([nextToken]))).logits;
+		}
+		return {
+			audioTokens,
+			finished
+		};
+	}
+	/** Logical (frame-level) position of the LAST token in `seq`. */
+	logicalPositionAt(seq) {
+		const positions = computeKaniPositions(seq, this.cfg);
+		return positions[positions.length - 1];
+	}
+	/** Greedy argmax over a logits row. */
+	argmax(logits) {
+		let best = 0;
+		let bestVal = logits[0];
+		for (let i = 1; i < logits.length; i++) if (logits[i] > bestVal) {
+			bestVal = logits[i];
+			best = i;
+		}
+		return best;
+	}
+	/**
+	* Sample one audio token for codebook position `codebook`, constrained to that
+	* codebook's valid window [audio_tokens_start + 4032*c, +4032). Allows end_of_speech
+	* only at codebook 0 (frame boundary). Applies temperature, top-p, rep-penalty.
+	*/
+	sampleAudioToken(logits, codebook, p) {
+		const winStart = this.cfg.audioTokensStart + this.cfg.codebookSize * codebook;
+		const winLen = this.cfg.codebookSize;
+		const allowEos = codebook === 0;
+		const n = winLen + (allowEos ? 1 : 0);
+		const ids = new Int32Array(n);
+		for (let i = 0; i < winLen; i++) ids[i] = winStart + i;
+		if (allowEos) ids[winLen] = this.cfg.endOfSpeech;
+		const prev = p.repetitionPenalty !== 1 ? new Set(p.previous) : null;
+		const scores = new Float32Array(n);
+		for (let i = 0; i < n; i++) {
+			let s = logits[ids[i]];
+			if (prev?.has(ids[i])) s = s > 0 ? s / p.repetitionPenalty : s * p.repetitionPenalty;
+			scores[i] = s / p.temperature;
+		}
+		softmaxInPlace(scores);
+		return nucleusSample(scores, ids, p.topP);
+	}
+	/**
+	* Decode NanoCodec codes [groups, T] (group-major) → PCM.
+	*
+	* The decoder graph carries concrete lengths, and the upsampled conv activations
+	* for long clips overflow WebGPU's 65535 per-dimension dispatch cap. The decoder
+	* is fully causal with a small (≤ a few frames) receptive field, so we decode in
+	* frame chunks with a left-context lookback and keep only each chunk's own output
+	* samples — numerically identical to a single decode, but bounded per dispatch.
+	*/
+	async decodeCodes(codes, numFrames) {
+		const groups = 4;
+		const lookback = KANI_CODEC_LOOKBACK_FRAMES;
+		const chunk = KANI_CODEC_CHUNK_FRAMES;
+		const pcm = new Float32Array(numFrames * KANI_HOP);
+		for (let start = 0; start < numFrames; start += chunk) {
+			const ctxStart = Math.max(0, start - lookback);
+			const ctxFrames = start - ctxStart;
+			const end = Math.min(numFrames, start + chunk);
+			const winFrames = end - ctxStart;
+			const winCodes = new Uint32Array(groups * winFrames);
+			for (let g = 0; g < groups; g++) for (let t = 0; t < winFrames; t++) winCodes[g * winFrames + t] = codes[g * numFrames + (ctxStart + t)];
+			const win = await this.decodeCodesWindow(winCodes, winFrames);
+			const dropSamples = ctxFrames * KANI_HOP;
+			const keepSamples = (end - start) * KANI_HOP;
+			pcm.set(win.subarray(dropSamples, dropSamples + keepSamples), start * KANI_HOP);
+		}
+		for (let i = 0; i < pcm.length; i++) pcm[i] = Math.min(1, Math.max(-1, pcm[i]));
+		return pcm;
+	}
+	/** Run the NanoCodec decoder graph for a single (bounded) code window → PCM. */
+	async decodeCodesWindow(winCodes, winFrames) {
+		const graph = generateNanoCodecDecoderGraph({ numFrames: winFrames });
+		const exec = new Executor(this.ctx, graph, {
+			maxSeqLen: winFrames,
+			kvMode: "f32"
+		});
+		try {
+			exec.uploadWeightsMap(selectGraphWeights(graph, this.loaded.codecWeights));
+			exec.initBindGroups();
+			exec.reset();
+			exec.writeInput("audio_codes", winCodes);
+			return await exec.runGraphOutput(graph.outputs[0], winFrames * KANI_HOP);
+		} finally {
+			exec.destroy();
+		}
+	}
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		this.backboneExec.destroy();
+		this.loaded.backboneWeights.clear();
+		this.loaded.codecWeights.clear();
+	}
+};
+
+//#endregion
+//#region src/gpu/sampler.ts
+let _heapIndices = null;
+let _heapValues = null;
+/**
+* Sample a token ID from logits.
+*
+* Pipeline: repetition penalty → temperature → top-k (min-heap) → softmax → top-p → sample.
+*/
+function sampleToken(logits, params = {}, previousTokens) {
+	const temperature = params.temperature ?? .7;
+	const topK = params.topK ?? 50;
+	const topP = params.topP ?? .9;
+	const repetitionPenalty = params.repetitionPenalty ?? 1;
+	if (temperature < 1e-6) return argmax(logits);
+	const N = logits.length;
+	const K = Math.min(topK > 0 ? topK : N, N);
+	if (!_heapIndices || _heapIndices.length < K) {
+		_heapIndices = new Uint32Array(K);
+		_heapValues = new Float32Array(K);
+	}
+	const hIdx = _heapIndices;
+	const hVal = _heapValues;
+	let penaltySet = null;
+	if (repetitionPenalty !== 1 && previousTokens?.length) penaltySet = new Set(previousTokens);
+	let heapSize = 0;
+	for (let i = 0; i < N; i++) {
+		let s = logits[i];
+		if (penaltySet?.has(i)) s = s > 0 ? s / repetitionPenalty : s * repetitionPenalty;
+		s /= temperature;
+		if (heapSize < K) {
+			hIdx[heapSize] = i;
+			hVal[heapSize] = s;
+			heapSize++;
+			if (heapSize === K) for (let j = (K >> 1) - 1; j >= 0; j--) siftDown(hIdx, hVal, j, K);
+		} else if (s > hVal[0]) {
+			hIdx[0] = i;
+			hVal[0] = s;
+			siftDown(hIdx, hVal, 0, K);
+		}
+	}
+	for (let i = 1; i < heapSize; i++) {
+		const vi = hVal[i];
+		const ii = hIdx[i];
+		let j = i - 1;
+		while (j >= 0 && hVal[j] < vi) {
+			hVal[j + 1] = hVal[j];
+			hIdx[j + 1] = hIdx[j];
+			j--;
+		}
+		hVal[j + 1] = vi;
+		hIdx[j + 1] = ii;
+	}
+	const maxScore = hVal[0];
+	let sumExp = 0;
+	for (let i = 0; i < heapSize; i++) {
+		const p = Math.exp(hVal[i] - maxScore);
+		hVal[i] = p;
+		sumExp += p;
+	}
+	const invSum = 1 / sumExp;
+	for (let i = 0; i < heapSize; i++) hVal[i] *= invSum;
+	let candidateCount = heapSize;
+	if (topP < 1) {
+		let cumulative$1 = 0;
+		for (let i = 0; i < heapSize; i++) {
+			cumulative$1 += hVal[i];
+			if (cumulative$1 >= topP) {
+				candidateCount = i + 1;
+				break;
+			}
+		}
+		let sum = 0;
+		for (let i = 0; i < candidateCount; i++) sum += hVal[i];
+		const inv = 1 / sum;
+		for (let i = 0; i < candidateCount; i++) hVal[i] *= inv;
+	}
+	const r = Math.random();
+	let cumulative = 0;
+	for (let i = 0; i < candidateCount; i++) {
+		cumulative += hVal[i];
+		if (r <= cumulative) return hIdx[i];
+	}
+	return hIdx[candidateCount - 1];
+}
+/**
+* Return the index of the maximum value (greedy decoding).
+*/
+function argmax(arr) {
+	let maxIdx = 0;
+	let maxVal = arr[0];
+	for (let i = 1; i < arr.length; i++) if (arr[i] > maxVal) {
+		maxVal = arr[i];
+		maxIdx = i;
+	}
+	return maxIdx;
+}
+/** Min-heap sift down on parallel index/value typed arrays. */
+function siftDown(indices, values, i, n) {
+	while (true) {
+		let smallest = i;
+		const left = 2 * i + 1;
+		const right = 2 * i + 2;
+		if (left < n && values[left] < values[smallest]) smallest = left;
+		if (right < n && values[right] < values[smallest]) smallest = right;
+		if (smallest === i) break;
+		const ti = indices[i];
+		indices[i] = indices[smallest];
+		indices[smallest] = ti;
+		const tv = values[i];
+		values[i] = values[smallest];
+		values[smallest] = tv;
+		i = smallest;
+	}
+}
+
+//#endregion
+//#region src/gpu/vision-executor.ts
+const MAP_MODE_READ = 1;
+/** Pack an f32 array to IEEE half (f16) bits (round-to-nearest-even). */
+const _f16scratch = /* @__PURE__ */ new ArrayBuffer(4);
+const _f16f32 = new Float32Array(_f16scratch);
+const _f16u32 = new Uint32Array(_f16scratch);
+function packF16(src) {
+	const out = new Uint16Array(src.length);
+	for (let i = 0; i < src.length; i++) {
+		_f16f32[0] = src[i];
+		const f = _f16u32[0];
+		const sign = f >>> 16 & 32768;
+		const exp = (f >>> 23 & 255) - 112;
+		const mant = f & 8388607;
+		if (exp <= 0) out[i] = sign;
+		else if (exp >= 31) out[i] = sign | 31744;
+		else {
+			const round = (mant & 4096) !== 0;
+			let half = sign | exp << 10 | mant >>> 13;
+			if (round) half += 1;
+			out[i] = half;
+		}
+	}
+	return out;
+}
+/**
+* WebKit only: the ViT bidirectional Attention op is a single dispatch whose
+* grid is [N query rows, heads], each row looping over all N keys — O(N²) work in
+* one submission. Past a few hundred rows that can exceed Metal's ~few-second GPU
+* watchdog and kill the web-content process (indistinguishable from OOM). We split
+* the attention grid into windows of this many query rows, each its own
+* submit + onSubmittedWorkDone() drain, so no single submission runs long enough
+* to trip the watchdog. Math is unchanged: every query row computes identically
+* regardless of how the grid is partitioned.
+*/
+const WEBKIT_ATTN_CHUNK_ROWS = 64;
+var VisionExecutor = class {
+	ctx;
+	graph;
+	mergeUnit;
+	weightBuffers = /* @__PURE__ */ new Map();
+	activationBuffers = /* @__PURE__ */ new Map();
+	dispatches = [];
+	maxPatches;
+	/** Weight (B) names of MatMulBias nodes stored as f16 (empty without shader-f16). */
+	f16WeightNames = /* @__PURE__ */ new Set();
+	/** Runtime pooled-token count for the Gemma 4 ViT ("Np" dim); 0 for Qwen. */
+	gemma4Np = 0;
+	/** True when this graph is the Gemma 4 vision tower (uses "Np" + PoolMatMul). */
+	isGemma4;
+	constructor(ctx, graph, maxPatches) {
+		this.ctx = ctx;
+		this.graph = graph;
+		this.maxPatches = maxPatches;
+		this.isGemma4 = graph.architecture === "Gemma4VisionModel";
+		const mergedIn = graph.tensors[CANONICAL_KEYS.visMergerFc1W]?.shape[1];
+		const hidden = graph.config.hidden_size;
+		this.mergeUnit = mergedIn && hidden ? mergedIn / hidden : 1;
+		if (ctx.hasF16) {
+			for (const node of graph.nodes) if (node.opType === "MatMulBias" && node.inputs[1]) this.f16WeightNames.add(node.inputs[1]);
+		}
+		this.allocateActivationBuffers();
+	}
+	uploadWeights(weights) {
+		for (const [name, desc] of Object.entries(this.graph.tensors)) {
+			if (desc.storage !== "constant") continue;
+			const w = weights.get(name);
+			if (!w) throw new Error(`VisionExecutor: missing weight "${name}"`);
+			let data = w.data;
+			if (this.f16WeightNames.has(name) && w.data instanceof Float32Array) data = packF16(w.data);
+			const buffer = createStorageBuffer(this.ctx, `vweight_${name}`, data.byteLength, data);
+			this.weightBuffers.set(name, buffer);
+		}
+	}
+	initBindGroups() {
+		const dummyShapes = this.resolveShapes(this.maxPatches);
+		for (const nodeId of this.graph.executionOrder) {
+			const node = this.graph.nodes.find((n) => n.id === nodeId);
+			let spec = KERNEL_REGISTRY[node.opType];
+			if (!spec) throw new Error(`VisionExecutor: no kernel for op "${node.opType}"`);
+			if (node.opType === "MatMulBias" && this.f16WeightNames.has(node.inputs[1])) spec = MATMUL_BIAS_F16C_SPEC;
+			const pipeline = getOrCreatePipeline(this.ctx, `vkernel_${nodeId}`, spec.shaderCode, spec.entryPoint);
+			const paramsData = spec.buildParams(node, dummyShapes, { seqPos: 0 });
+			const uniformBuffer = createUniformBuffer(this.ctx, `vuniform_${nodeId}`, paramsData);
+			const bufferEntries = this.gatherBuffers(spec, node, uniformBuffer);
+			const bindGroup = createBindGroup(this.ctx, pipeline, bufferEntries, `vbg_${nodeId}`);
+			this.dispatches.push({
+				node,
+				spec,
+				pipeline,
+				bindGroup,
+				uniformBuffer
+			});
+		}
+	}
+	/**
+	* Encode patches → merged image embeddings [Nm, out_hidden_size].
+	*
+	* `onStage` (optional) fires coarse phase breadcrumbs during the WebKit path so
+	* a host can localize a GPU-process crash to a specific layer.
+	*/
+	async encode(inputs, onStage) {
+		const N = inputs.numPatches;
+		if (N > this.maxPatches) throw new Error(`VisionExecutor: ${N} patches exceeds maxPatches=${this.maxPatches}`);
+		const q = this.ctx.device.queue;
+		q.writeBuffer(this.activationBuffers.get("vis_patches"), 0, inputs.patches);
+		q.writeBuffer(this.activationBuffers.get("vis_pos_embeds"), 0, inputs.posEmbeds);
+		q.writeBuffer(this.activationBuffers.get("vis_cos"), 0, inputs.cos);
+		q.writeBuffer(this.activationBuffers.get("vis_sin"), 0, inputs.sin);
+		const resolvedShapes = this.resolveShapes(N);
+		const ctxRt = { seqPos: 0 };
+		const sizes = [];
+		for (const d of this.dispatches) {
+			const params = d.spec.buildParams(d.node, resolvedShapes, ctxRt);
+			q.writeBuffer(d.uniformBuffer, 0, params);
+			sizes.push(d.spec.getDispatchSize(d.node, resolvedShapes, ctxRt));
+		}
+		if (this.ctx.isWebKitWebGPU) {
+			onStage?.("vit-encode-start", { total: this.dispatches.length });
+			for (let i = 0; i < this.dispatches.length; i++) {
+				const d = this.dispatches[i];
+				if (d.node.opType === "Attention") {
+					const [gridX, gridY, gridZ] = sizes[i];
+					const layer = Number.parseInt(d.node.id.replace(/\D+/g, ""), 10);
+					if (!Number.isNaN(layer)) onStage?.("vit-attn", { layer });
+					for (let start = 0; start < gridX; start += WEBKIT_ATTN_CHUNK_ROWS) {
+						const rows$1 = Math.min(WEBKIT_ATTN_CHUNK_ROWS, gridX - start);
+						const params = d.spec.buildParams(d.node, resolvedShapes, {
+							seqPos: 0,
+							qOffset: start
+						});
+						q.writeBuffer(d.uniformBuffer, 0, params);
+						const enc$2 = this.ctx.device.createCommandEncoder();
+						const p$1 = enc$2.beginComputePass();
+						p$1.setPipeline(d.pipeline);
+						p$1.setBindGroup(0, d.bindGroup);
+						p$1.dispatchWorkgroups(rows$1, gridY, gridZ);
+						p$1.end();
+						q.submit([enc$2.finish()]);
+						await q.onSubmittedWorkDone();
+					}
+					continue;
+				}
+				const enc$1 = this.ctx.device.createCommandEncoder();
+				const p = enc$1.beginComputePass();
+				p.setPipeline(d.pipeline);
+				p.setBindGroup(0, d.bindGroup);
+				p.dispatchWorkgroups(...sizes[i]);
+				p.end();
+				q.submit([enc$1.finish()]);
+				await q.onSubmittedWorkDone();
+			}
+			onStage?.("vit-encode-done");
+		} else {
+			const enc$1 = this.ctx.device.createCommandEncoder({ label: "vision_encode" });
+			const pass = enc$1.beginComputePass({ label: "vision_pass" });
+			for (let i = 0; i < this.dispatches.length; i++) {
+				pass.setPipeline(this.dispatches[i].pipeline);
+				pass.setBindGroup(0, this.dispatches[i].bindGroup);
+				pass.dispatchWorkgroups(...sizes[i]);
+			}
+			pass.end();
+			q.submit([enc$1.finish()]);
+		}
+		const rows = N / this.mergeUnit;
+		const dim = this.graph.config.vision_embed_dim ? this.graph.tensors.vis_image_embeds.shape[1] : this.graph.tensors.vis_image_embeds.shape[1];
+		const byteLen = rows * dim * 4;
+		const out = this.activationBuffers.get("vis_image_embeds");
+		const readback = this.ctx.device.createBuffer({
+			size: byteLen,
+			usage: 9
+		});
+		const enc = this.ctx.device.createCommandEncoder();
+		enc.copyBufferToBuffer(out, 0, readback, 0, byteLen);
+		this.ctx.device.queue.submit([enc.finish()]);
+		await readback.mapAsync(MAP_MODE_READ, 0, byteLen);
+		const embeds = new Float32Array(readback.getMappedRange(0, byteLen).slice(0));
+		readback.unmap();
+		readback.destroy();
+		return {
+			embeds,
+			rows,
+			dim
+		};
+	}
+	/**
+	* Encode patches through the Gemma 4 ViT → projected image tokens [Np, text_hidden].
+	*
+	* Distinct from the Qwen `encode()`: the Gemma graph has 5 inputs (patches,
+	* axial pos-embeds, axial rotary cos/sin, and a host-built [Np,N] pooling matrix)
+	* and its output rows (Np) are the pooled soft-token count, resolved from the
+	* pooling matrix rather than an N/mergeUnit ratio. Reuses the same dispatch
+	* machinery + WebKit per-dispatch-drain discipline.
+	*/
+	async encodeGemma4(inputs, onStage) {
+		const N = inputs.numPatches;
+		if (N > this.maxPatches) throw new Error(`VisionExecutor(Gemma4): ${N} patches exceeds maxPatches=${this.maxPatches}`);
+		this.gemma4Np = inputs.numPooled;
+		const q = this.ctx.device.queue;
+		q.writeBuffer(this.activationBuffers.get("g4v_patches"), 0, inputs.patches);
+		q.writeBuffer(this.activationBuffers.get("g4v_pos_embeds"), 0, inputs.posEmbeds);
+		q.writeBuffer(this.activationBuffers.get("g4v_cos"), 0, inputs.cos);
+		q.writeBuffer(this.activationBuffers.get("g4v_sin"), 0, inputs.sin);
+		q.writeBuffer(this.activationBuffers.get("g4v_pool_w"), 0, inputs.poolMatrix);
+		const resolvedShapes = this.resolveShapes(N);
+		const ctxRt = { seqPos: 0 };
+		const sizes = [];
+		for (const d of this.dispatches) {
+			const params = d.spec.buildParams(d.node, resolvedShapes, ctxRt);
+			q.writeBuffer(d.uniformBuffer, 0, params);
+			sizes.push(d.spec.getDispatchSize(d.node, resolvedShapes, ctxRt));
+		}
+		if (this.ctx.isWebKitWebGPU) {
+			onStage?.("vit-encode-start", { total: this.dispatches.length });
+			for (let i = 0; i < this.dispatches.length; i++) {
+				const d = this.dispatches[i];
+				if (d.node.opType === "Attention") {
+					const [gridX, gridY, gridZ] = sizes[i];
+					const layer = Number.parseInt(d.node.id.replace(/\D+/g, ""), 10);
+					if (!Number.isNaN(layer)) onStage?.("vit-attn", { layer });
+					for (let start = 0; start < gridX; start += WEBKIT_ATTN_CHUNK_ROWS) {
+						const rows$1 = Math.min(WEBKIT_ATTN_CHUNK_ROWS, gridX - start);
+						const params = d.spec.buildParams(d.node, resolvedShapes, {
+							seqPos: 0,
+							qOffset: start
+						});
+						q.writeBuffer(d.uniformBuffer, 0, params);
+						const enc$2 = this.ctx.device.createCommandEncoder();
+						const p$1 = enc$2.beginComputePass();
+						p$1.setPipeline(d.pipeline);
+						p$1.setBindGroup(0, d.bindGroup);
+						p$1.dispatchWorkgroups(rows$1, gridY, gridZ);
+						p$1.end();
+						q.submit([enc$2.finish()]);
+						await q.onSubmittedWorkDone();
+					}
+					continue;
+				}
+				const enc$1 = this.ctx.device.createCommandEncoder();
+				const p = enc$1.beginComputePass();
+				p.setPipeline(d.pipeline);
+				p.setBindGroup(0, d.bindGroup);
+				p.dispatchWorkgroups(...sizes[i]);
+				p.end();
+				q.submit([enc$1.finish()]);
+				await q.onSubmittedWorkDone();
+			}
+			onStage?.("vit-encode-done");
+		} else {
+			const enc$1 = this.ctx.device.createCommandEncoder({ label: "gemma4_vision_encode" });
+			const pass = enc$1.beginComputePass({ label: "gemma4_vision_pass" });
+			for (let i = 0; i < this.dispatches.length; i++) {
+				pass.setPipeline(this.dispatches[i].pipeline);
+				pass.setBindGroup(0, this.dispatches[i].bindGroup);
+				pass.dispatchWorkgroups(...sizes[i]);
+			}
+			pass.end();
+			q.submit([enc$1.finish()]);
+		}
+		const rows = inputs.numPooled;
+		const dim = this.graph.tensors.g4v_image_embeds.shape[1];
+		const byteLen = rows * dim * 4;
+		const out = this.activationBuffers.get("g4v_image_embeds");
+		const readback = this.ctx.device.createBuffer({
+			size: byteLen,
+			usage: 9
+		});
+		const enc = this.ctx.device.createCommandEncoder();
+		enc.copyBufferToBuffer(out, 0, readback, 0, byteLen);
+		this.ctx.device.queue.submit([enc.finish()]);
+		await readback.mapAsync(MAP_MODE_READ, 0, byteLen);
+		const embeds = new Float32Array(readback.getMappedRange(0, byteLen).slice(0));
+		readback.unmap();
+		readback.destroy();
+		return {
+			embeds,
+			rows,
+			dim
+		};
+	}
+	/** True if this executor is the Gemma 4 vision tower. */
+	get gemma4() {
+		return this.isGemma4;
+	}
+	/** Read back any named activation (debug). Must be called right after encode(). */
+	async debugReadBuffer(name, maxElements) {
+		const buffer = this.activationBuffers.get(name) ?? this.weightBuffers.get(name);
+		if (!buffer) throw new Error(`VisionExecutor: no buffer "${name}"`);
+		const byteLen = maxElements ? Math.min(maxElements * 4, buffer.size) : buffer.size;
+		const readback = this.ctx.device.createBuffer({
+			size: byteLen,
+			usage: 9
+		});
+		const enc = this.ctx.device.createCommandEncoder();
+		enc.copyBufferToBuffer(buffer, 0, readback, 0, byteLen);
+		this.ctx.device.queue.submit([enc.finish()]);
+		await readback.mapAsync(MAP_MODE_READ, 0, byteLen);
+		const data = new Float32Array(readback.getMappedRange(0, byteLen).slice(0));
+		readback.unmap();
+		readback.destroy();
+		return data;
+	}
+	destroy() {
+		destroyBuffers([...this.weightBuffers.values()]);
+		destroyBuffers([...this.activationBuffers.values()]);
+		for (const d of this.dispatches) d.uniformBuffer.destroy();
+		this.weightBuffers.clear();
+		this.activationBuffers.clear();
+		this.dispatches = [];
+	}
+	/** Max pooled tokens for buffer sizing: maxPatches with no merge/pool ratio applied. */
+	maxPooled() {
+		return this.maxPatches;
+	}
+	resolveShapes(N) {
+		const Nm = N / this.mergeUnit;
+		const Np = this.gemma4Np || N;
+		const resolved = {};
+		for (const [name, desc] of Object.entries(this.graph.tensors)) resolved[name] = desc.shape.map((d) => {
+			if (d === "N") return N;
+			if (d === "Nm") return Nm;
+			if (d === "Np") return Np;
+			return d;
+		});
+		return resolved;
+	}
+	allocateActivationBuffers() {
+		for (const [name, desc] of Object.entries(this.graph.tensors)) {
+			if (desc.storage !== "activation") continue;
+			const bytes = desc.shape.map((d) => {
+				if (d === "N") return this.maxPatches;
+				if (d === "Nm") return this.maxPatches / this.mergeUnit;
+				if (d === "Np") return this.maxPooled();
+				return d;
+			}).reduce((a, b) => a * b, 1) * DTYPE_BYTES[desc.dtype];
+			this.activationBuffers.set(name, createStorageBuffer(this.ctx, `vact_${name}`, bytes));
+		}
+	}
+	gatherBuffers(spec, node, uniformBuffer) {
+		const entries = [];
+		const tensorNames = [...node.inputs, ...node.outputs];
+		let tensorIdx = 0;
+		for (const binding of spec.bindings) if (binding.type === "uniform") entries.push({ buffer: uniformBuffer });
+		else {
+			const tensorName = tensorNames[tensorIdx++];
+			const buffer = this.weightBuffers.get(tensorName) ?? this.activationBuffers.get(tensorName);
+			if (!buffer) throw new Error(`VisionExecutor: no buffer for "${tensorName}" in op ${node.id}`);
+			entries.push({ buffer });
+		}
+		return entries;
+	}
+};
+
+//#endregion
+//#region src/gpu/vision-preprocess.ts
+/** linspace(0, n-1, count) matching torch.linspace. */
+function linspace(stop, count) {
+	const out = new Float64Array(count);
+	if (count === 1) {
+		out[0] = 0;
+		return out;
+	}
+	const step = stop / (count - 1);
+	for (let i = 0; i < count; i++) out[i] = i * step;
+	return out;
+}
+/**
+* Compute the spatial-merge reorder index for a (h, w) grid:
+* reorder[k] gives the source patch index (row-major h*w) for output slot k,
+* grouping 2×2 (merge×merge) spatial blocks contiguously. Matches the `reorder`
+* in get_vision_bilinear_indices_and_weights and the position-id reshape.
+*/
+function spatialMergeReorder(h, w, merge) {
+	const hb = h / merge;
+	const wb = w / merge;
+	const out = new Int32Array(h * w);
+	let k = 0;
+	for (let bh = 0; bh < hb; bh++) for (let bw = 0; bw < wb; bw++) for (let ih = 0; ih < merge; ih++) for (let iw = 0; iw < merge; iw++) {
+		const hh = bh * merge + ih;
+		const ww = bw * merge + iw;
+		out[k++] = hh * w + ww;
+	}
+	return out;
+}
+/**
+* Build bilinear-interpolated learned position embeddings [N, hidden].
+* posEmbedTable is the raw pos_embed.weight [num_position_embeddings, hidden].
+*/
+function buildPosEmbeds(gridTHW, posEmbedTable, cfg) {
+	const [t, h, w] = gridTHW;
+	const hidden = cfg.hiddenSize;
+	const side = Math.round(Math.sqrt(cfg.numPositionEmbeddings));
+	const merge = cfg.spatialMergeSize;
+	const hGrid = linspace(side - 1, h);
+	const wGrid = linspace(side - 1, w);
+	const hFloor = new Int32Array(h);
+	const hCeil = new Int32Array(h);
+	const hFrac = new Float64Array(h);
+	for (let i = 0; i < h; i++) {
+		hFloor[i] = Math.trunc(hGrid[i]);
+		hCeil[i] = Math.min(hFloor[i] + 1, side - 1);
+		hFrac[i] = hGrid[i] - hFloor[i];
+	}
+	const wFloor = new Int32Array(w);
+	const wCeil = new Int32Array(w);
+	const wFrac = new Float64Array(w);
+	for (let j = 0; j < w; j++) {
+		wFloor[j] = Math.trunc(wGrid[j]);
+		wCeil[j] = Math.min(wFloor[j] + 1, side - 1);
+		wFrac[j] = wGrid[j] - wFloor[j];
+	}
+	const hw = h * w;
+	const cornerIdx = [
+		new Int32Array(hw),
+		new Int32Array(hw),
+		new Int32Array(hw),
+		new Int32Array(hw)
+	];
+	const cornerW = [
+		new Float64Array(hw),
+		new Float64Array(hw),
+		new Float64Array(hw),
+		new Float64Array(hw)
+	];
+	let p = 0;
+	for (let i = 0; i < h; i++) {
+		const hf = hFloor[i] * side;
+		const hc = hCeil[i] * side;
+		const hfr = hFrac[i];
+		for (let j = 0; j < w; j++) {
+			cornerIdx[0][p] = hf + wFloor[j];
+			cornerIdx[1][p] = hf + wCeil[j];
+			cornerIdx[2][p] = hc + wFloor[j];
+			cornerIdx[3][p] = hc + wCeil[j];
+			cornerW[0][p] = (1 - hfr) * (1 - wFrac[j]);
+			cornerW[1][p] = (1 - hfr) * wFrac[j];
+			cornerW[2][p] = hfr * (1 - wFrac[j]);
+			cornerW[3][p] = hfr * wFrac[j];
+			p++;
+		}
+	}
+	const reorder = spatialMergeReorder(h, w, merge);
+	const N = t * hw;
+	const out = new Float32Array(N * hidden);
+	for (let tt = 0; tt < t; tt++) for (let k = 0; k < hw; k++) {
+		const src = reorder[k];
+		const dstBase = (tt * hw + k) * hidden;
+		for (let corner = 0; corner < 4; corner++) {
+			const tableRow = cornerIdx[corner][src] * hidden;
+			const wgt = cornerW[corner][src];
+			if (wgt === 0) continue;
+			for (let d = 0; d < hidden; d++) out[dstBase + d] += posEmbedTable[tableRow + d] * wgt;
+		}
+	}
+	return out;
+}
+/**
+* Build the reordered (row, col) position ids [N, 2] for rotary, matching
+* get_vision_position_ids.
+*/
+function buildPositionIds(gridTHW, merge) {
+	const [t, h, w] = gridTHW;
+	const hb = h / merge;
+	const wb = w / merge;
+	const hw = h * w;
+	const perFrame = new Int32Array(hw * 2);
+	let k = 0;
+	for (let bh = 0; bh < hb; bh++) for (let bw = 0; bw < wb; bw++) for (let ih = 0; ih < merge; ih++) for (let iw = 0; iw < merge; iw++) {
+		perFrame[k * 2] = bh * merge + ih;
+		perFrame[k * 2 + 1] = bw * merge + iw;
+		k++;
+	}
+	const out = new Int32Array(t * hw * 2);
+	for (let tt = 0; tt < t; tt++) out.set(perFrame, tt * hw * 2);
+	return out;
+}
+/**
+* Build rotary cos/sin tables [N, head_dim] from position ids, matching
+* Qwen3_5VisionRotaryEmbedding + the cat((rotary, rotary)) in VisionModel.forward.
+*
+* rotary_pos_emb(position_ids) = (position_ids[..,None] * inv_freq).flatten(1)
+*   where inv_freq has length (head_dim/2)/2 = head_dim/4, computed over dim=head_dim/2.
+* For each token the two position components (h, w) each produce head_dim/4 freqs,
+* concatenated → head_dim/2, then duplicated → head_dim for cos/sin.
+*/
+function buildRotaryCosSin(positionIds, headDim, theta = 1e4) {
+	const rotaryDim = headDim / 2;
+	const half = rotaryDim / 2;
+	const invFreq = new Float64Array(half);
+	for (let i = 0; i < half; i++) invFreq[i] = 1 / theta ** (2 * i / rotaryDim);
+	const N = positionIds.length / 2;
+	const cos = new Float32Array(N * headDim);
+	const sin = new Float32Array(N * headDim);
+	for (let n = 0; n < N; n++) {
+		const hp = positionIds[n * 2];
+		const wp = positionIds[n * 2 + 1];
+		const base = n * headDim;
+		for (let i = 0; i < half; i++) {
+			const fh = hp * invFreq[i];
+			const fw = wp * invFreq[i];
+			const ch = Math.cos(fh);
+			const sh = Math.sin(fh);
+			const cw = Math.cos(fw);
+			const sw = Math.sin(fw);
+			cos[base + i] = ch;
+			sin[base + i] = sh;
+			cos[base + half + i] = cw;
+			sin[base + half + i] = sw;
+			cos[base + rotaryDim + i] = ch;
+			sin[base + rotaryDim + i] = sh;
+			cos[base + rotaryDim + half + i] = cw;
+			sin[base + rotaryDim + half + i] = sw;
+		}
+	}
+	return {
+		cos,
+		sin,
+		numPatches: N
+	};
+}
+/**
+* Build all host position tensors for a single image grid in one call.
+*/
+function buildVisionPositionTensors(gridTHW, posEmbedTable, cfg) {
+	const headDim = Math.floor(cfg.hiddenSize / cfg.numHeads);
+	const posEmbeds = buildPosEmbeds(gridTHW, posEmbedTable, cfg);
+	const { cos, sin, numPatches } = buildRotaryCosSin(buildPositionIds(gridTHW, cfg.spatialMergeSize), headDim, cfg.ropeTheta ?? 1e4);
+	return {
+		posEmbeds,
+		cos,
+		sin,
+		numPatches
+	};
+}
+/**
+* Per-patch (x, y) grid coordinates in row-major order, matching the Gemma4
+* image processor's meshgrid(arange(width), arange(height)) reshape: patch p at
+* row r (0..gridH-1), col c (0..gridW-1) → x=c, y=r, index = r*gridW + c.
+*/
+function gemma4PatchXY(gridH, gridW) {
+	const n = gridH * gridW;
+	const x = new Int32Array(n);
+	const y = new Int32Array(n);
+	let p = 0;
+	for (let r = 0; r < gridH; r++) for (let c = 0; c < gridW; c++) {
+		x[p] = c;
+		y[p] = r;
+		p++;
+	}
+	return {
+		x,
+		y
+	};
+}
+/**
+* Build axial learned position embeddings [N, hidden] from the [2, posSize, hidden]
+* table: pos[p] = table[0][x_p] + table[1][y_p]. Direct lookup, no interpolation
+* (HF F.embedding on clamped positions).
+*/
+function buildGemma4PosEmbeds(gridH, gridW, posEmbedTable, hidden, posSize) {
+	const { x, y } = gemma4PatchXY(gridH, gridW);
+	const n = gridH * gridW;
+	const out = new Float32Array(n * hidden);
+	const yPlane = posSize * hidden;
+	for (let p = 0; p < n; p++) {
+		const xi = Math.max(0, x[p]);
+		const yi = Math.max(0, y[p]);
+		const xBase = xi * hidden;
+		const yBase = yPlane + yi * hidden;
+		const dst = p * hidden;
+		for (let d = 0; d < hidden; d++) out[dst + d] = posEmbedTable[xBase + d] + posEmbedTable[yBase + d];
+	}
+	return out;
+}
+/**
+* Build the 2D axial rotary cos/sin tables [N, headDim].
+*   spatial_dim = headDim / 2;  inv_freq[j] = 1/theta^((2j)/spatial_dim), j in [0, spatial_dim/2)
+*   per spatial dim: f = pos * inv_freq (spatial_dim/2 values); emb = cat(f, f) (spatial_dim values)
+*   cos/sin = cat([emb_x, emb_y]) → headDim values, layout [fx,fx,fy,fy].
+* Applied with the global-half rotate_half kernel (ApplyRotaryEmb), which computes
+* out = x*cos + rotate_half(x)*sin element-wise — exact for this layout.
+*/
+function buildGemma4RotaryCosSin(gridH, gridW, headDim, theta) {
+	const { x, y } = gemma4PatchXY(gridH, gridW);
+	const n = gridH * gridW;
+	const spatialDim = headDim / 2;
+	const half = spatialDim / 2;
+	const invFreq = new Float64Array(half);
+	for (let j = 0; j < half; j++) invFreq[j] = 1 / theta ** (2 * j / spatialDim);
+	const cos = new Float32Array(n * headDim);
+	const sin = new Float32Array(n * headDim);
+	for (let p = 0; p < n; p++) {
+		const xp = Math.max(0, x[p]);
+		const yp = Math.max(0, y[p]);
+		const base = p * headDim;
+		for (let j = 0; j < half; j++) {
+			const fx = xp * invFreq[j];
+			const fy = yp * invFreq[j];
+			const cx = Math.cos(fx);
+			const sx = Math.sin(fx);
+			const cy = Math.cos(fy);
+			const sy = Math.sin(fy);
+			cos[base + j] = cx;
+			sin[base + j] = sx;
+			cos[base + half + j] = cx;
+			sin[base + half + j] = sx;
+			cos[base + spatialDim + j] = cy;
+			sin[base + spatialDim + j] = sy;
+			cos[base + spatialDim + half + j] = cy;
+			sin[base + spatialDim + half + j] = sy;
+		}
+	}
+	return {
+		cos,
+		sin
+	};
+}
+/**
+* Build the [Np, N] average-pooling matrix for k×k spatial pooling over the real
+* (unpadded) grid, matching modeling_gemma4's kernel_idxs/one_hot pooling:
+*   cell(p) = floor(x_p/k) + ceil(gridW/k) * floor(y_p/k)
+*   poolMatrix[cell, p] = 1/k²  (so pooled = poolMatrix @ hidden = mean over the k×k block)
+* Np = ceil(gridH/k) * ceil(gridW/k). Each pooled cell averages exactly the patches
+* that fall in it (edge cells with fewer than k² patches still divide by k², matching
+* HF's fixed 1/k² normalization).
+*/
+function buildGemma4PoolMatrix(gridH, gridW, k) {
+	const n = gridH * gridW;
+	const cellsW = Math.ceil(gridW / k);
+	const np = cellsW * Math.ceil(gridH / k);
+	const inv = 1 / (k * k);
+	const poolMatrix = new Float32Array(np * n);
+	const { x, y } = gemma4PatchXY(gridH, gridW);
+	for (let p = 0; p < n; p++) {
+		const cell = Math.floor(x[p] / k) + cellsW * Math.floor(y[p] / k);
+		poolMatrix[cell * n + p] = inv;
+	}
+	return {
+		poolMatrix,
+		numPooled: np
+	};
+}
+/**
+* Build all Gemma 4 vision host tensors for one image grid in one call.
+* `posEmbedTable` is the raw [2, posSize, hidden] flattened table.
+*/
+function buildGemma4VisionPositionTensors(gridH, gridW, posEmbedTable, posSize, cfg) {
+	const posEmbeds = buildGemma4PosEmbeds(gridH, gridW, posEmbedTable, cfg.hiddenSize, posSize);
+	const { cos, sin } = buildGemma4RotaryCosSin(gridH, gridW, cfg.headDim, cfg.ropeTheta);
+	const { poolMatrix, numPooled } = buildGemma4PoolMatrix(gridH, gridW, cfg.poolingKernelSize);
+	return {
+		posEmbeds,
+		cos,
+		sin,
+		poolMatrix,
+		numPatches: gridH * gridW,
+		numPooled
+	};
+}
+/** Gemma 4 image processor config (from processor_config.json). */
+const GEMMA4_IMAGE_PROCESSOR = {
+	patchSize: 16,
+	temporalPatchSize: 1,
+	mergeSize: 1,
+	imageMean: [
+		0,
+		0,
+		0
+	],
+	imageStd: [
+		1,
+		1,
+		1
+	],
+	rescaleFactor: 1 / 255,
+	minPixels: 256,
+	maxPixels: 2520 * 16 * 16
+};
+/**
+* Preprocess a decoded RGB image for the Gemma 4 ViT: aspect-preserving resize so
+* the patch grid is ≤ max_soft_tokens·k² patches and H,W divisible by k·patch,
+* rescale ×1/255 (no normalize), patchify row-major into [N, 3·16·16].
+*
+* @param pixels row-major HWC RGB (0..255), length width*height*3.
+*/
+function preprocessImageGemma4(pixels, width, height, maxSoftTokens = 280, poolingKernelSize = 3, patchSize = 16) {
+	const factor = poolingKernelSize * patchSize;
+	const maxPatches = maxSoftTokens * poolingKernelSize * poolingKernelSize;
+	const floorByFactor = (n) => Math.max(factor, Math.floor(n / factor) * factor);
+	let outH = floorByFactor(height);
+	let outW = floorByFactor(width);
+	while (outH / patchSize * (outW / patchSize) > maxPatches) {
+		const beta = Math.sqrt(outH / patchSize * (outW / patchSize) / maxPatches);
+		outH = floorByFactor(outH / beta);
+		outW = floorByFactor(outW / beta);
+		if (outH <= factor && outW <= factor) break;
+	}
+	const resized = bilinearResize(pixels, height, width, outH, outW);
+	const gridH = outH / patchSize;
+	const gridW = outW / patchSize;
+	const ch = 3;
+	const ps = patchSize;
+	const patchDim = ch * ps * ps;
+	const numP = gridH * gridW;
+	const patches = new Float32Array(numP * patchDim);
+	const rescale = 1 / 255;
+	let pIdx = 0;
+	for (let pr = 0; pr < gridH; pr++) for (let pc = 0; pc < gridW; pc++) {
+		const base = pIdx * patchDim;
+		let kk = 0;
+		for (let c = 0; c < ch; c++) for (let py = 0; py < ps; py++) {
+			const row = (pr * ps + py) * outW;
+			for (let px = 0; px < ps; px++) {
+				patches[base + kk] = resized[(row + pc * ps + px) * 3 + c] * rescale;
+				kk++;
+			}
+		}
+		pIdx++;
+	}
+	return {
+		patches,
+		gridHW: [gridH, gridW]
+	};
+}
+const QWEN3_5_IMAGE_PROCESSOR = {
+	patchSize: 16,
+	temporalPatchSize: 2,
+	mergeSize: 2,
+	imageMean: [
+		.5,
+		.5,
+		.5
+	],
+	imageStd: [
+		.5,
+		.5,
+		.5
+	],
+	rescaleFactor: 1 / 255,
+	minPixels: 65536,
+	maxPixels: 16777216
+};
+/**
+* Qwen2-VL smart-resize: round H and W to multiples of factor=patch*merge,
+* keeping aspect ratio and clamping the total pixel budget to [minPixels, maxPixels].
+* Matches transformers.models.qwen2_vl.image_processing.smart_resize.
+*/
+function smartResize(height, width, factor, minPixels, maxPixels) {
+	if (height < factor || width < factor) {
+		const scale = factor / Math.min(height, width);
+		height = Math.max(factor, Math.round(height * scale));
+		width = Math.max(factor, Math.round(width * scale));
+	}
+	const roundByFactor = (n) => Math.round(n / factor) * factor;
+	const floorByFactor = (n) => Math.floor(n / factor) * factor;
+	const ceilByFactor = (n) => Math.ceil(n / factor) * factor;
+	let hBar = Math.max(factor, roundByFactor(height));
+	let wBar = Math.max(factor, roundByFactor(width));
+	if (hBar * wBar > maxPixels) {
+		const beta = Math.sqrt(height * width / maxPixels);
+		hBar = Math.max(factor, floorByFactor(height / beta));
+		wBar = Math.max(factor, floorByFactor(width / beta));
+	} else if (hBar * wBar < minPixels) {
+		const beta = Math.sqrt(minPixels / (height * width));
+		hBar = ceilByFactor(height * beta);
+		wBar = ceilByFactor(width * beta);
+	}
+	return [hBar, wBar];
+}
+/**
+* Bilinear-resample an RGB image (HWC, 0..255 or 0..1) to (outH, outW).
+* Half-pixel-centered sampling to match PIL/torchvision BILINEAR closely.
+* `pixels` is row-major [H, W, 3].
+*/
+function bilinearResize(pixels, inH, inW, outH, outW) {
+	const out = new Float32Array(outH * outW * 3);
+	const scaleH = inH / outH;
+	const scaleW = inW / outW;
+	for (let oy = 0; oy < outH; oy++) {
+		let sy = (oy + .5) * scaleH - .5;
+		if (sy < 0) sy = 0;
+		if (sy > inH - 1) sy = inH - 1;
+		const y0 = Math.floor(sy);
+		const y1 = Math.min(y0 + 1, inH - 1);
+		const fy = sy - y0;
+		for (let ox = 0; ox < outW; ox++) {
+			let sx = (ox + .5) * scaleW - .5;
+			if (sx < 0) sx = 0;
+			if (sx > inW - 1) sx = inW - 1;
+			const x0 = Math.floor(sx);
+			const x1 = Math.min(x0 + 1, inW - 1);
+			const fx = sx - x0;
+			const i00 = (y0 * inW + x0) * 3;
+			const i01 = (y0 * inW + x1) * 3;
+			const i10 = (y1 * inW + x0) * 3;
+			const i11 = (y1 * inW + x1) * 3;
+			const od = (oy * outW + ox) * 3;
+			for (let c = 0; c < 3; c++) {
+				const top = pixels[i00 + c] * (1 - fx) + pixels[i01 + c] * fx;
+				const bot = pixels[i10 + c] * (1 - fx) + pixels[i11 + c] * fx;
+				out[od + c] = top * (1 - fy) + bot * fy;
+			}
+		}
+	}
+	return out;
+}
+/**
+* Preprocess a decoded RGB image into the [N, 1536] patch tensor + grid_thw that
+* `encodeImage()` expects, matching the HF Qwen2-VL image processor:
+*   smart_resize → rescale (×1/255) → normalize → temporal-pair (×temporal_patch_size)
+*   → patchify into spatial_merge×spatial_merge blocks → flatten to [N, C·T·P·P].
+*
+* @param pixels row-major HWC RGB, length width*height*3. Values 0..255 (default)
+*   or already 0..1 if `rescaled` is true.
+* @param width  source pixel width
+* @param height source pixel height
+*/
+function preprocessImage(pixels, width, height, cfg = QWEN3_5_IMAGE_PROCESSOR, rescaled = false) {
+	const [outH, outW] = smartResize(height, width, cfg.patchSize * cfg.mergeSize, cfg.minPixels, cfg.maxPixels);
+	const resized = bilinearResize(pixels, height, width, outH, outW);
+	const [mr, mg, mb] = cfg.imageMean;
+	const [sr, sg, sb] = cfg.imageStd;
+	const mean = [
+		mr,
+		mg,
+		mb
+	];
+	const std = [
+		sr,
+		sg,
+		sb
+	];
+	const rescale = rescaled ? 1 : cfg.rescaleFactor;
+	const chw = new Float32Array(3 * outH * outW);
+	const plane = outH * outW;
+	for (let y = 0; y < outH; y++) for (let x = 0; x < outW; x++) {
+		const src = (y * outW + x) * 3;
+		const dst = y * outW + x;
+		for (let c = 0; c < 3; c++) chw[c * plane + dst] = (resized[src + c] * rescale - mean[c]) / std[c];
+	}
+	const t = 1;
+	const gridH = outH / cfg.patchSize;
+	const gridW = outW / cfg.patchSize;
+	const ps = cfg.patchSize;
+	const tps = cfg.temporalPatchSize;
+	const ch = 3;
+	const merge = cfg.mergeSize;
+	const gridHm = gridH / merge;
+	const gridWm = gridW / merge;
+	const patchDim = ch * tps * ps * ps;
+	const numPatches = t * gridH * gridW;
+	const patches = new Float32Array(numPatches * patchDim);
+	let pIdx = 0;
+	for (let gt = 0; gt < t; gt++) for (let bh = 0; bh < gridHm; bh++) for (let bw = 0; bw < gridWm; bw++) for (let mh = 0; mh < merge; mh++) for (let mw = 0; mw < merge; mw++) {
+		const patchRow = (bh * merge + mh) * ps;
+		const patchCol = (bw * merge + mw) * ps;
+		const base = pIdx * patchDim;
+		let k = 0;
+		for (let c = 0; c < ch; c++) for (let tt = 0; tt < tps; tt++) for (let py = 0; py < ps; py++) {
+			const row = (patchRow + py) * outW;
+			for (let px = 0; px < ps; px++) {
+				patches[base + k] = chw[c * plane + row + (patchCol + px)];
+				k++;
+			}
+		}
+		pIdx++;
+	}
+	return {
+		patches,
+		gridTHW: [
+			t,
+			gridH,
+			gridW
+		]
+	};
+}
+/**
+* Build the 3D M-RoPE position ids [3, seq] for a text sequence that contains
+* `image_token_id` runs, matching Qwen3_5Model.get_rope_index for a single image.
+*
+* Text tokens advance all three (t,h,w) components together (standard 1D RoPE).
+* Each image run uses the vision grid: temporal=start (t=1), height=start+h_block,
+* width=start+w_block, in row-major (h outer, w inner) order; after the image the
+* cursor jumps by max(h_merged, w_merged). Returns Int32Array of length 3*seq
+* laid out as [T-row(seq), H-row(seq), W-row(seq)].
+*/
+/**
+* Fill the 3D position rows for one image run starting at sequence index `at`
+* and logical `start`. Returns the next sequence index and the post-image cursor.
+*/
+function fillImagePositions(rows, at, start, grid, mergeSize) {
+	const [gt, gh, gw] = grid;
+	const hm = gh / mergeSize;
+	const wm = gw / mergeSize;
+	let i = at;
+	for (let tt = 0; tt < gt; tt++) for (let h = 0; h < hm; h++) for (let w = 0; w < wm; w++) {
+		rows.t[i] = start + tt;
+		rows.h[i] = start + h;
+		rows.w[i] = start + w;
+		i++;
+	}
+	return {
+		next: i,
+		cursor: start + Math.max(hm, wm)
+	};
+}
+function buildMRoPEPositionIds(inputIds, imageGrids, imageTokenId, mergeSize) {
+	const seq = inputIds.length;
+	const rows = {
+		t: new Int32Array(seq),
+		h: new Int32Array(seq),
+		w: new Int32Array(seq)
+	};
+	let i = 0;
+	let cursor = 0;
+	let imageIdx = 0;
+	while (i < seq) if (inputIds[i] === imageTokenId) {
+		const res = fillImagePositions(rows, i, cursor, imageGrids[imageIdx++], mergeSize);
+		i = res.next;
+		cursor = res.cursor;
+	} else {
+		rows.t[i] = cursor;
+		rows.h[i] = cursor;
+		rows.w[i] = cursor;
+		cursor++;
+		i++;
+	}
+	const out = new Int32Array(3 * seq);
+	out.set(rows.t, 0);
+	out.set(rows.h, seq);
+	out.set(rows.w, 2 * seq);
+	return out;
+}
+/**
+* Per-pair frequency→dimension assignment for interleaved M-RoPE, matching
+* Qwen3_5TextRotaryEmbedding.apply_interleaved_mrope. For pair index i in
+* [0, sum(section)) the position component is section-cyclic: T,H,W,T,H,W,...
+* but each component capped at its section count. Returns an array of length
+* (rope_dim/2) with values 0=T, 1=H, 2=W.
+*/
+function mropeFreqDims(mropeSection) {
+	const total = mropeSection[0] + mropeSection[1] + mropeSection[2];
+	const dims = new Int32Array(total);
+	for (let d = 1; d <= 2; d++) {
+		const length = mropeSection[d] * 3;
+		for (let idx = d; idx < length && idx < total; idx += 3) dims[idx] = d;
+	}
+	return dims;
+}
+/**
+* Build the interleaved-M-RoPE cos/sin tables [seq, rope_dim] from 3D position
+* ids, matching Qwen3_5TextRotaryEmbedding.forward:
+*   freqs[d][i] = pos[d] * inv_freq[i],  inv_freq[i] = 1/theta^(2i/rope_dim)
+*   freq[i] picks component mropeFreqDims[i]; emb = cat(freqs, freqs).
+* cos/sin have length seq*rope_dim. For text-only (all 3 pos rows equal) this
+* reduces exactly to standard 1D partial RoPE.
+*
+* @param positionIds3 [3, seq] as produced by buildMRoPEPositionIds.
+* @param ropeDim      number of rotated dims per head (head_dim * partial_factor).
+*/
+function buildMRoPECosSin(positionIds3, seq, ropeDim, theta, mropeSection) {
+	const half = ropeDim / 2;
+	const freqDims = mropeFreqDims(mropeSection);
+	const invFreq = new Float64Array(half);
+	for (let i = 0; i < half; i++) invFreq[i] = 1 / theta ** (2 * i / ropeDim);
+	const cos = new Float32Array(seq * ropeDim);
+	const sin = new Float32Array(seq * ropeDim);
+	for (let n = 0; n < seq; n++) {
+		const base = n * ropeDim;
+		for (let i = 0; i < half; i++) {
+			const angle = positionIds3[freqDims[i] * seq + n] * invFreq[i];
+			const c = Math.cos(angle);
+			const s = Math.sin(angle);
+			cos[base + i] = c;
+			sin[base + i] = s;
+			cos[base + half + i] = c;
+			sin[base + half + i] = s;
+		}
+	}
+	return {
+		cos,
+		sin
+	};
+}
+
+//#endregion
+//#region src/browser/device-guards.ts
+const WEBKIT_GROUP_PROBE_KEY = "gerbil-webkit-group-v1";
+const DEFAULT_PROBE = {
+	knownGood: 1,
+	trying: null,
+	capped: false
+};
+/** Read the persisted WebKit group probe record (guarded; safe on node). */
+function readGroupProbe() {
+	if (typeof localStorage === "undefined") return { ...DEFAULT_PROBE };
+	try {
+		const raw = localStorage.getItem(WEBKIT_GROUP_PROBE_KEY);
+		if (!raw) return { ...DEFAULT_PROBE };
+		const parsed = JSON.parse(raw);
+		return {
+			knownGood: typeof parsed.knownGood === "number" && parsed.knownGood >= 1 ? parsed.knownGood : 1,
+			trying: typeof parsed.trying === "number" ? parsed.trying : null,
+			capped: parsed.capped === true
+		};
+	} catch {
+		return { ...DEFAULT_PROBE };
+	}
+}
+/** Persist the WebKit group probe record (guarded; no-op on node). */
+function writeGroupProbe(rec) {
+	if (typeof localStorage === "undefined") return;
+	try {
+		localStorage.setItem(WEBKIT_GROUP_PROBE_KEY, JSON.stringify(rec));
+	} catch {}
+}
+/**
+* The validated non-phone sweet spot. iPad swept 1→7.9, 8→19, 32→24.8, 64→26.6,
+* 128→26.9 (peak), 256→26.2 tok/s — a plateau from ~64 up, so 128 is the best
+* stable target (more batching just costs memory). Non-phone WebKit jumps here
+* directly; the crash breadcrumb caps it down if a device can't sustain it.
+*/
+const NONPHONE_TARGET_GROUP = 128;
+/**
+* Resolve the WebKit group size to use this session, recording `trying` as a
+* side effect so a crash this load is detectable on the next load.
+*
+* Algorithm (only meaningful on WebKit; inert otherwise):
+*  1. Read the record (default {knownGood:1, trying:null, capped:false}).
+*  2. If `trying !== null` on entry → the previous load set it but never cleared
+*     it → that load CRASHED at `trying`. Cap there, keep `knownGood`, clear
+*     `trying`. Use `knownGood` this session.
+*  3. Else if !capped and there is a rung above `knownGood` → set `trying = next`,
+*     persist BEFORE any GPU work, and use it (we're escalating).
+*  4. Else → use `knownGood`.
+*
+* @returns the group size to use this session.
+*/
+function resolveWebkitGroupSize(args) {
+	if (args.override && args.override > 0) return args.override;
+	if (!args.isWebKit) return 1;
+	const rec = readGroupProbe();
+	if (rec.trying !== null) {
+		const crashedAt = rec.trying;
+		const next = {
+			knownGood: rec.knownGood,
+			trying: null,
+			capped: true
+		};
+		writeGroupProbe(next);
+		console.log(`[engine] webkit group probe: previous load crashed at group=${crashedAt} → capping at knownGood=${next.knownGood}`);
+		return next.knownGood;
+	}
+	if (!rec.capped && !args.conservative && rec.knownGood < NONPHONE_TARGET_GROUP) {
+		writeGroupProbe({
+			knownGood: rec.knownGood,
+			trying: NONPHONE_TARGET_GROUP,
+			capped: false
+		});
+		console.log(`[engine] webkit group probe: trying target group=${NONPHONE_TARGET_GROUP} (knownGood=${rec.knownGood})`);
+		return NONPHONE_TARGET_GROUP;
+	}
+	console.log(`[engine] webkit group probe: knownGood=${rec.knownGood} trying=null capped=${rec.capped} → using ${rec.knownGood}`);
+	return rec.knownGood;
+}
+/**
+* Promote (or cap) the WebKit group probe after the first successful forward.
+*
+* Call this once per page-load, after the model has loaded AND a first forward
+* completed without the page dying. The breadcrumb already handles the crash
+* class (the page death leaves `trying` set for the next load); this handles the
+* wrong-output class and records success.
+*
+* @param correct  true if the first forward produced non-corrupt output.
+*   - correct  → promote: knownGood = trying, trying = null.
+*   - incorrect → cap: keep knownGood at the prior rung, trying = null, capped.
+*/
+function promoteGroupProbe(correct) {
+	if (typeof localStorage === "undefined") return;
+	const rec = readGroupProbe();
+	if (rec.trying === null) return;
+	if (correct) {
+		writeGroupProbe({
+			knownGood: rec.trying,
+			trying: null,
+			capped: rec.capped
+		});
+		console.log(`[engine] webkit group probe: PROMOTED group=${rec.trying} to known-good`);
+	} else {
+		writeGroupProbe({
+			knownGood: rec.knownGood,
+			trying: null,
+			capped: true
+		});
+		console.log(`[engine] webkit group probe: group=${rec.trying} produced INCORRECT output → capping at knownGood=${rec.knownGood}`);
+	}
+}
+
+//#endregion
+//#region src/gpu/index.ts
+/**
+* WebGPUEngine -- gerbil's native WebGPU inference engine.
+*
+* Public API:
+*   const engine = await WebGPUEngine.create({ repo: "Qwen/Qwen3.5-0.8B" });
+*   const result = await engine.generate("What is 2+2?");
+*   engine.destroy();
+*/
+/** EmbeddingGemma task prefixes (from config_sentence_transformers.json prompts). */
+const EMBEDDING_GEMMA_PROMPTS = {
+	query: "task: search result | query: ",
+	document: "title: none | text: "
+};
+/**
+* Extract the first complete JSON object or array from a model's text output.
+*
+* Tolerant of prose, markdown, and ```json code fences: it scans for the first
+* `{` or `[`, then walks forward tracking string/escape state and brace/bracket
+* depth to find the matching close, returning the balanced substring. Returns
+* `undefined` when no JSON-looking span is present. Used by
+* {@link WebGPUEngine.generateObject}.
+*/
+function extractJson(text) {
+	const cleaned = text.replace(/```(?:json)?/gi, "");
+	const start = cleaned.search(/[{[]/);
+	if (start === -1) return void 0;
+	const open = cleaned[start];
+	const close = open === "{" ? "}" : "]";
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < cleaned.length; i++) {
+		const ch = cleaned[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") inString = true;
+		else if (ch === open) depth++;
+		else if (ch === close) {
+			depth--;
+			if (depth === 0) return cleaned.slice(start, i + 1);
+		}
+	}
+}
+/**
+* The main WebGPU inference engine.
+*
+* Usage:
+*   const engine = await WebGPUEngine.create({ repo: "Qwen/Qwen3.5-0.8B" });
+*   const result = await engine.generate("Hello!");
+*   console.log(result.text);
+*   engine.destroy();
+*/
+var WebGPUEngine = class WebGPUEngine {
+	ctx;
+	executor;
+	tokenizer;
+	_destroyed = false;
+	_isEmbedding;
+	/** HF architecture string (e.g. "Gemma3TextModel", "Qwen3ForCausalLM"). */
+	_architecture;
+	/** Vision encoder (built only when enableVision and the model is vision-capable). */
+	visionExecutor;
+	/** Raw vision_config (for host preprocessing of grids). */
+	visionConfig;
+	/** Raw pos_embed.weight table for bilinear interpolation. */
+	visionPosEmbedTable;
+	/** True when the LM graph was built with the multimodal (M-RoPE + splice) path. */
+	_multimodalGraph;
+	/** Raw config.json (for M-RoPE params: mrope_section, rope_theta, partial factor). */
+	rawConfig;
+	/** Effective max sequence length (cos/sin table coverage). */
+	maxSeqLen;
+	/** Original create() options (used to lazily spin up the Kani-TTS engine for speak()). */
+	_createOptions;
+	/** Lazily-created Kani-TTS engine (codec-LM + NanoCodec) backing speak(). */
+	_kaniTTS = null;
+	/**
+	* WebKit group-size probe state. When true, a candidate group size is being
+	* tried this page-load and must be promoted (or capped) after the FIRST
+	* successful forward produces non-corrupt logits. Goes false once handled so
+	* promotion runs at most once per session. Always false on Dawn/node.
+	*/
+	_groupProbePending = false;
+	/** Model capabilities (text, vision, moe). */
+	capabilities;
+	/** Model architecture config. */
+	config;
+	constructor(ctx, executor, tokenizer, graph, opts, vision) {
+		this.ctx = ctx;
+		this.executor = executor;
+		this.tokenizer = tokenizer;
+		this.capabilities = graph.capabilities;
+		this.config = graph.config;
+		this._isEmbedding = graph.outputs.includes("embedding");
+		this._architecture = graph.architecture;
+		this.visionExecutor = vision?.executor ?? null;
+		this.visionConfig = vision?.config ?? null;
+		this.visionPosEmbedTable = vision?.posEmbedTable ?? null;
+		this._multimodalGraph = opts.multimodalGraph;
+		this.rawConfig = opts.rawConfig;
+		this.maxSeqLen = opts.maxSeqLen;
+		this._createOptions = opts.createOptions;
+		this._groupProbePending = opts.groupProbePending ?? false;
+	}
+	/** True if this engine has a vision encoder built (use encodeImage()). */
+	get hasVision() {
+		return this.visionExecutor !== null;
+	}
+	/** Per-opType decode GPU-time breakdown (only populated under GERBIL_PROFILE). */
+	getDecodeProfile() {
+		return this.executor.getProfile();
+	}
+	/** Clear accumulated decode profiler data (e.g. to drop warm-up tokens). */
+	resetDecodeProfile() {
+		this.executor.resetProfile();
+	}
+	/** Profile ONE real decode step (the pipelined-greedy kernels). Token-independent
+	* timing — pass any valid id. Only meaningful under GERBIL_PROFILE. */
+	async profileDecodeStep(tokenId) {
+		await this.executor.profileDecodeStep(tokenId);
+	}
+	/** Decode dispatch count + the device's storage-buffer limit (which gates the
+	* INT4 projection fusions). Lets the iPad runner report whether fusions applied
+	* on-device or silently fell back (8 < 9 ⇒ more dispatches ⇒ more mobile drains). */
+	getDecodeStats() {
+		return {
+			dispatches: this.executor.decodeDispatchCount,
+			maxStorageBuffers: this.executor.maxStorageBuffers
+		};
+	}
+	/**
+	* Write a coarse crash-phase breadcrumb that survives a GPU-process kill / page
+	* reload. The iPad harness reads `localStorage["gerbil-crash-phase"]` after a
+	* crash; without these, a describe-time crash only shows the last load phase
+	* ("engine:ready"). The describe path tags vit-encode / splice / text-decode so
+	* the next run shows WHERE it died, not just "crashed after load".
+	*/
+	setPhase(phase) {
+		try {
+			if (typeof localStorage !== "undefined") localStorage.setItem("gerbil-crash-phase", phase);
+		} catch {}
+	}
+	/** True if this engine was loaded as an embedding model (use embed(), not generate()). */
+	get isEmbedding() {
+		return this._isEmbedding;
+	}
+	/**
+	* WebKit group-size probe promotion hook. Runs at most once per session, after
+	* the FIRST forward completes without the page dying. If the page had crashed
+	* at this group size, this code never runs and the localStorage breadcrumb
+	* (left by the resolver) caps the device on the next load — that is what makes
+	* the probe survive the crash class. Here we additionally handle the
+	* wrong-output class by inspecting the first forward's logits for corruption
+	* (NaN / Inf / all-zero / all-same), reusing the same signals as integrityCheck().
+	*/
+	maybePromoteGroupProbe(logits) {
+		if (!this._groupProbePending) return;
+		this._groupProbePending = false;
+		const n = Math.min(logits.length, 256);
+		let allZero = true;
+		let allSame = true;
+		let finite = true;
+		const first = logits[0];
+		for (let i = 0; i < n; i++) {
+			const v = logits[i];
+			if (!Number.isFinite(v)) {
+				finite = false;
+				break;
+			}
+			if (v !== 0) allZero = false;
+			if (v !== first) allSame = false;
+		}
+		promoteGroupProbe(finite && !allZero && !allSame);
+	}
+	/**
+	* Create and initialize a WebGPUEngine.
+	*
+	* Downloads the model from HuggingFace, compiles shaders, uploads weights.
+	*/
+	static async create(options = {}) {
+		options = {
+			...options,
+			repo: resolveDefaultRepo(options)
+		};
+		const ctx = await initGPU();
+		const isBrowser = typeof navigator !== "undefined" && typeof location !== "undefined";
+		const isSafari = isBrowser && /Safari/.test(navigator.userAgent) && !/Chrome/.test(navigator.userAgent);
+		const params = isBrowser ? new URLSearchParams(location.search) : null;
+		const forceKvF32 = params?.has("kvf32");
+		const maxSeqOverride = params?.get("maxseq");
+		const groupOverride = params?.get("group");
+		let kvMode;
+		if (options.kvMode) kvMode = options.kvMode;
+		else if (forceKvF32) kvMode = "f32";
+		else if (isSafari && ctx.hasF16) kvMode = "packed-f16";
+		else if (ctx.hasF16) kvMode = "native-f16";
+		else kvMode = "f32";
+		const kvDtype = kvMode === "f32" ? "f32" : "f16";
+		console.log(`[engine] kvMode: ${kvMode}, kvDtype: ${kvDtype}, f16 supported: ${ctx.hasF16}, safari: ${isSafari}`);
+		const setPhase = (phase) => {
+			try {
+				if (typeof localStorage !== "undefined") localStorage.setItem("gerbil-crash-phase", phase);
+			} catch {}
+		};
+		setPhase("engine:loading-model");
+		const maxVisionPatches = options.maxVisionPatches ?? (ctx.isWebKitWebGPU ? 1024 : 4096);
+		const multimodal = options.enableVision ? { maxVisionTokens: Math.ceil(maxVisionPatches / 4) } : void 0;
+		const { graph, tokenizer, weights, rawConfig, pleSource } = await loadModel({
+			...options,
+			repo: resolveDefaultRepo(options),
+			kvDtype,
+			multimodal
+		});
+		setPhase(`engine:model-loaded:${weights.size}-weights`);
+		let visionBundle = null;
+		const hasVisionConfig = rawConfig.vision_config != null;
+		const isGemma4Vision = rawConfig.vision_config?.model_type === "gemma4_vision" || [...weights.keys()].some((k) => k.startsWith("vision_tower."));
+		const visPosKey = isGemma4Vision ? "vision_tower.patch_embedder.position_embedding_table" : "visual.pos_embed.weight";
+		const towerPrefix = isGemma4Vision ? "vision_tower." : "visual.";
+		const hasVisualWeights = weights.keys().some((k) => k.startsWith(towerPrefix));
+		if (Boolean(options.enableVision && hasVisionConfig) && hasVisualWeights) {
+			const visGraph = isGemma4Vision ? generateGemma4VisionGraph(rawConfig) : generateQwen3_5VisionGraph(rawConfig);
+			const maxPatches = maxVisionPatches;
+			const visWeights = /* @__PURE__ */ new Map();
+			for (const k of weights.keys()) if (k.startsWith(towerPrefix) || k.startsWith("embed_vision.") || k === visPosKey) {
+				const w = await weights.get(k);
+				if (w) visWeights.set(k, w);
+			}
+			if (isGemma4Vision) {
+				patchGemma4VisionClips(visGraph, visWeights);
+				const gi = resolveGemma4VisionInfo(rawConfig);
+				dequantizeGemma4VisionProjection(visWeights, (rawConfig.quantization_config ?? rawConfig.quantization)?.group_size ?? 64, gi.textHidden, gi.hiddenSize);
+				ensureGemma4VisionEmbedderNorms(visWeights, gi.hiddenSize, gi.textHidden);
+			}
+			const visExec = new VisionExecutor(ctx, visGraph, maxPatches);
+			const posW = visWeights.get(visPosKey);
+			const posTable = posW && posW.data instanceof Float32Array ? new Float32Array(posW.data) : posW ? new Float32Array(posW.data.buffer, posW.data.byteOffset, posW.data.byteLength / 4).slice() : null;
+			await visExec.uploadWeights(visWeights);
+			visExec.initBindGroups();
+			if (posTable) visionBundle = {
+				executor: visExec,
+				config: rawConfig.vision_config ?? rawConfig,
+				posEmbedTable: posTable
+			};
+		}
+		let maxSeqLen;
+		if (maxSeqOverride) maxSeqLen = Math.min(Number.parseInt(maxSeqOverride, 10), graph.config.context_length);
+		else if (forceKvF32 && isSafari) maxSeqLen = Math.min(options.maxSeqLen ?? 1024, graph.config.context_length, 1024);
+		else if (ctx.isWebKitWebGPU) maxSeqLen = Math.min(options.maxSeqLen ?? 512, graph.config.context_length, 2048);
+		else maxSeqLen = Math.min(options.maxSeqLen ?? graph.config.context_length, graph.config.context_length, 4096);
+		console.log(`[engine] maxSeqLen: ${maxSeqLen}, architecture: ${graph.architecture}`);
+		if (ctx.isWebKitWebGPU) console.log(`[engine] device limits: maxBufferSize=${ctx.limits.maxBufferSize}, maxStorageBufferBindingSize=${ctx.limits.maxStorageBufferBindingSize}, maxComputeWorkgroupStorageSize=${ctx.limits.maxComputeWorkgroupStorageSize}`);
+		setPhase("engine:allocating-buffers");
+		ctx.device.pushErrorScope("out-of-memory");
+		ctx.device.pushErrorScope("validation");
+		const groupOverrideNum = groupOverride ? Number.parseInt(groupOverride, 10) : void 0;
+		let webkitGroupSize;
+		let probingGroup = false;
+		if (groupOverrideNum) {
+			webkitGroupSize = groupOverrideNum;
+			console.log(`[engine] webkitGroupSize override: ${webkitGroupSize} dispatches/command buffer`);
+		} else if (ctx.isWebKitWebGPU) {
+			webkitGroupSize = resolveWebkitGroupSize({ isWebKit: true });
+			probingGroup = true;
+		}
+		const executor = new Executor(ctx, graph, {
+			maxSeqLen,
+			kvMode,
+			webkitGroupSize
+		});
+		if (pleSource) executor.setPleSource(pleSource);
+		setPhase("engine:uploading-weights");
+		await executor.uploadWeights(weights);
+		await weights.dispose?.();
+		setPhase("engine:compiling-shaders");
+		executor.initBindGroups();
+		const validationError = await ctx.device.popErrorScope();
+		const oomError = await ctx.device.popErrorScope();
+		if (oomError || validationError) {
+			const detail = [oomError ? `out-of-memory: ${oomError.message}` : null, validationError ? `validation: ${validationError.message}` : null].filter(Boolean).join("; ");
+			setPhase(`engine:gpu-error:${detail.slice(0, 120)}`);
+			throw new Error(`GPU setup failed (${detail}). The model likely exceeds this device's memory budget — try a smaller maxSeqLen or a q4-quantized model.`);
+		}
+		setPhase("engine:ready");
+		return new WebGPUEngine(ctx, executor, tokenizer, graph, {
+			multimodalGraph: Boolean(multimodal),
+			rawConfig,
+			maxSeqLen,
+			createOptions: options,
+			groupProbePending: probingGroup
+		}, visionBundle);
+	}
+	/**
+	* Encode an image (already preprocessed into patches) into merged
+	* image-embedding tokens of dim `out_hidden_size` (1024 for Qwen3.5).
+	*
+	* This is the VISION ENCODER ONLY — it returns the image tokens; it does not
+	* splice them into a text sequence or apply M-RoPE (that is the LM-side
+	* integration phase). Requires `enableVision: true` at create() on a
+	* vision-capable checkpoint.
+	*
+	* @param patches Flattened patches, row-major [numPatches, patch_dim].
+	*   patch_dim = in_channels * temporal_patch_size * patch_size^2 (1536 for Qwen3.5).
+	*   Patches must already be ordered in spatial_merge_size×spatial_merge_size
+	*   groups (as the HF image processor emits them).
+	* @param gridTHW The (temporal, height, width) patch-grid dims for the image.
+	*   numPatches must equal t*h*w.
+	*/
+	async encodeImage(patches, gridTHW, onStage) {
+		this.checkDestroyed();
+		if (!this.visionExecutor || !this.visionConfig || !this.visionPosEmbedTable) throw new Error("encodeImage() requires a vision encoder. Load with { enableVision: true } on a vision-capable checkpoint (e.g. Qwen/Qwen3.5-0.8B).");
+		const vcfg = this.visionConfig;
+		if (this.visionExecutor.gemma4) {
+			const info = resolveGemma4VisionInfo({ vision_config: vcfg });
+			const gridH = gridTHW[1];
+			const gridW = gridTHW[2];
+			const posSize = Math.floor(this.visionPosEmbedTable.length / (2 * info.hiddenSize));
+			const host$1 = buildGemma4VisionPositionTensors(gridH, gridW, this.visionPosEmbedTable, posSize, {
+				hiddenSize: info.hiddenSize,
+				numHeads: info.numHeads,
+				headDim: info.headDim,
+				ropeTheta: info.ropeTheta,
+				poolingKernelSize: info.poolingKernelSize
+			});
+			return this.visionExecutor.encodeGemma4({
+				patches,
+				posEmbeds: host$1.posEmbeds,
+				cos: host$1.cos,
+				sin: host$1.sin,
+				poolMatrix: host$1.poolMatrix,
+				numPatches: host$1.numPatches,
+				numPooled: host$1.numPooled
+			}, onStage);
+		}
+		const hiddenSize = vcfg.hidden_size;
+		const numHeads = vcfg.num_heads;
+		const host = buildVisionPositionTensors(gridTHW, this.visionPosEmbedTable, {
+			hiddenSize,
+			numHeads,
+			numPositionEmbeddings: vcfg.num_position_embeddings,
+			spatialMergeSize: vcfg.spatial_merge_size,
+			ropeTheta: 1e4
+		});
+		const numPatches = gridTHW[0] * gridTHW[1] * gridTHW[2];
+		return this.visionExecutor.encode({
+			patches,
+			posEmbeds: host.posEmbeds,
+			cos: host.cos,
+			sin: host.sin,
+			numPatches
+		}, onStage);
+	}
+	/** Resolve M-RoPE params from rawConfig: rope_dim, theta, mrope_section. */
+	mropeParams() {
+		const cfg = this.rawConfig ?? {};
+		const rope = (cfg.text_config ?? cfg).rope_parameters ?? {};
+		const headDim = this.config.head_dim;
+		const partial = rope.partial_rotary_factor ?? .25;
+		const ropeDim = Math.floor(headDim * partial);
+		const theta = rope.rope_theta ?? this.config.rope_base ?? 1e4;
+		const section = rope.mrope_section ?? [
+			11,
+			11,
+			10
+		];
+		const visCfg = cfg.vision_config ?? {};
+		return {
+			ropeDim,
+			theta,
+			section,
+			imageTokenId: cfg.image_token_id ?? 248056,
+			mergeSize: visCfg.spatial_merge_size ?? 2
+		};
+	}
+	/**
+	* Write the M-RoPE cos/sin (token order) + image row-map for a prefill of
+	* `positionIds3` ([3, seq]). `rowMap[i]` = vision-buffer row for image tokens,
+	* -1 for text. Returns the logical position of the last token (for decode).
+	*/
+	writeMRoPEPrefill(positionIds3, seq, rowMap) {
+		const { ropeDim, theta, section } = this.mropeParams();
+		const { cos, sin } = buildMRoPECosSin(positionIds3, seq, ropeDim, theta, section);
+		this.executor.writeInput("mrope_cos", cos);
+		this.executor.writeInput("mrope_sin", sin);
+		this.executor.writeInput("vision_row_map", rowMap);
+		const last = seq - 1;
+		return Math.max(positionIds3[last], positionIds3[seq + last], positionIds3[2 * seq + last]);
+	}
+	/**
+	* Write a single decode-step M-RoPE cos/sin row at table slot `seqPos` for a
+	* text token at logical position `logicalPos`, plus a -1 row-map entry.
+	*/
+	writeMRoPEDecodeStep(seqPos, logicalPos) {
+		const { ropeDim, theta, section } = this.mropeParams();
+		const pid = new Int32Array(3);
+		pid[0] = logicalPos;
+		pid[1] = logicalPos;
+		pid[2] = logicalPos;
+		const { cos, sin } = buildMRoPECosSin(pid, 1, ropeDim, theta, section);
+		const rowBytes = ropeDim * 4;
+		this.executor.writeInputAt("mrope_cos", cos, seqPos * rowBytes);
+		this.executor.writeInputAt("mrope_sin", sin, seqPos * rowBytes);
+	}
+	/** Write linear-position M-RoPE inputs for a pure-text forward (no image). */
+	writeMRoPELinearText(seq) {
+		const { ropeDim, theta, section } = this.mropeParams();
+		const pid = new Int32Array(3 * seq);
+		for (let i = 0; i < seq; i++) {
+			pid[i] = i;
+			pid[seq + i] = i;
+			pid[2 * seq + i] = i;
+		}
+		const { cos, sin } = buildMRoPECosSin(pid, seq, ropeDim, theta, section);
+		this.executor.writeInput("mrope_cos", cos);
+		this.executor.writeInput("mrope_sin", sin);
+		const rowMap = new Int32Array(seq).fill(-1);
+		this.executor.writeInput("vision_row_map", rowMap);
+	}
+	/**
+	* Generate text from a prompt.
+	*/
+	async generate(prompt, options = {}) {
+		this.checkDestroyed();
+		const { maxTokens = 512, stopSequences = [], sampling = {}, systemPrompt, onToken } = options;
+		this.executor.reset();
+		let inputIds;
+		if (typeof prompt === "string") {
+			const messages = [];
+			if (systemPrompt) messages.push({
+				role: "system",
+				content: systemPrompt
+			});
+			messages.push({
+				role: "user",
+				content: prompt
+			});
+			inputIds = this.tokenizer.encodeChat(messages, { addGenerationPrompt: true });
+		} else {
+			const messages = systemPrompt ? [{
+				role: "system",
+				content: systemPrompt
+			}, ...prompt] : prompt;
+			inputIds = this.tokenizer.encodeChat(messages, { addGenerationPrompt: true });
+		}
+		const startTime = performance.now();
+		const isGreedy = (sampling.temperature ?? .7) < 1e-6;
+		const hasMRoPE = this._multimodalGraph && this.executor.hasBuffer("mrope_cos");
+		if (this._multimodalGraph) {
+			if (hasMRoPE) this.writeMRoPELinearText(inputIds.length);
+			else if (this.executor.hasBuffer("vision_row_map")) this.executor.writeInput("vision_row_map", new Int32Array(inputIds.length).fill(-1));
+		}
+		let { logits } = await this.executor.forward(new Uint32Array(inputIds));
+		this.maybePromoteGroupProbe(logits);
+		const generatedIds = [];
+		let finishReason = "max_tokens";
+		let generatedText = "";
+		const eosId = this.tokenizer.config.eosTokenId;
+		const consumeToken = (nextToken) => {
+			generatedIds.push(nextToken);
+			if (eosId !== null && nextToken === eosId) {
+				finishReason = "eos";
+				return true;
+			}
+			const tokenText = this.tokenizer.decode([nextToken], true);
+			generatedText += tokenText;
+			onToken?.(tokenText);
+			if (stopSequences.some((s) => generatedText.includes(s))) {
+				for (const s of stopSequences) {
+					const idx = generatedText.indexOf(s);
+					if (idx !== -1) generatedText = generatedText.slice(0, idx);
+				}
+				finishReason = "stop_sequence";
+				return true;
+			}
+			return false;
+		};
+		const mmDecode = hasMRoPE;
+		let mmLogicalPos = inputIds.length;
+		if (isGreedy && !this.executor.needsMultiEncoder && !mmDecode) {
+			const firstToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			if (!consumeToken(firstToken)) {
+				const depth = Executor.PIPELINE_DEPTH;
+				const stepsNeeded = Math.min(maxTokens - 1, this.executor.decodeCapacityRemaining());
+				let submitted = 0;
+				let consumed = 0;
+				while (consumed < stepsNeeded) {
+					while (submitted < stepsNeeded && submitted < consumed + depth) {
+						this.executor.submitGreedyDecodeStep(submitted === 0 ? firstToken : null, submitted % depth);
+						submitted++;
+					}
+					const tok = await this.executor.readDecodeToken(consumed % depth);
+					consumed++;
+					if (consumeToken(tok)) break;
+				}
+			}
+		} else for (let step = 0; step < maxTokens; step++) {
+			let nextToken;
+			if (step === 0 || !isGreedy) nextToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			else {
+				if (mmDecode) this.writeMRoPEDecodeStep(this.executor.currentSeqPos, mmLogicalPos);
+				nextToken = await this.executor.forwardArgmax(new Uint32Array([generatedIds[generatedIds.length - 1]]));
+				mmLogicalPos++;
+			}
+			if (consumeToken(nextToken)) break;
+			if (!isGreedy) {
+				if (mmDecode) this.writeMRoPEDecodeStep(this.executor.currentSeqPos, mmLogicalPos);
+				logits = (await this.executor.forward(new Uint32Array([nextToken]))).logits;
+				mmLogicalPos++;
+			}
+		}
+		const totalTime = performance.now() - startTime;
+		const tokensGenerated = generatedIds.length;
+		const tokensPerSecond = tokensGenerated / (totalTime / 1e3);
+		return {
+			text: generatedText,
+			tokensGenerated,
+			tokensPerSecond,
+			totalTime,
+			finishReason
+		};
+	}
+	/**
+	* Generate a STRUCTURED object: generate text, extract the first JSON
+	* object/array, parse it, validate it, and RETRY until it is valid (on-device
+	* tokens are free, so re-rolling a malformed JSON is cheap).
+	*
+	* Extraction is tolerant: prose, markdown, and ```json code fences are
+	* stripped, then the outermost balanced `{...}` or `[...]` is matched and
+	* `JSON.parse`d. Validation is one of:
+	*  - a predicate `(o) => boolean` (return false to reject),
+	*  - a minimal JSON-schema-ish object with `required` (those keys must exist),
+	*  - nothing (only valid JSON is required).
+	*
+	* On each retry the prompt is nudged with a terse "return ONLY valid JSON…"
+	* instruction (including the required-key shape when known). Throws a clear
+	* error if it never validates within `maxRetries + 1` attempts.
+	*
+	* ```ts
+	* const { object } = await engine.generateObject(
+	*   'Extract {name, age} from: "I am Sarah, 28"',
+	*   { schema: { required: ["name", "age"] } },
+	* );
+	* // object === { name: "Sarah", age: 28 }
+	* ```
+	*
+	* @typeParam T Expected object type (not enforced at runtime — validate via schema).
+	*/
+	async generateObject(prompt, options = {}) {
+		this.checkDestroyed();
+		const { schema, maxRetries = 4, ...generateOpts } = options;
+		const validate = (value) => {
+			if (typeof schema === "function") return schema(value);
+			if (schema && typeof schema === "object" && Array.isArray(schema.required)) {
+				if (value === null || typeof value !== "object") return false;
+				const obj = value;
+				return schema.required.every((key) => key in obj);
+			}
+			return true;
+		};
+		const nudge = `\n\nReturn ONLY valid JSON matching ${schema && typeof schema === "object" && Array.isArray(schema.required) ? `{ ${schema.required.join(", ")} }` : "the requested shape"}. No prose, no markdown, no code fences.`;
+		const attemptsMax = Math.max(0, maxRetries) + 1;
+		let lastText = "";
+		let lastError = "";
+		for (let attempt = 1; attempt <= attemptsMax; attempt++) {
+			const promptForAttempt = attempt === 1 ? prompt : prompt + nudge;
+			const result = await this.generate(promptForAttempt, generateOpts);
+			lastText = result.text;
+			const parsed = extractJson(result.text);
+			if (parsed === void 0) {
+				lastError = "no JSON object/array found in output";
+				continue;
+			}
+			let value;
+			try {
+				value = JSON.parse(parsed);
+			} catch (e) {
+				lastError = `JSON.parse failed: ${e instanceof Error ? e.message : String(e)}`;
+				continue;
+			}
+			if (!validate(value)) {
+				lastError = "parsed JSON failed schema validation";
+				continue;
+			}
+			return {
+				object: value,
+				text: result.text,
+				attempts: attempt
+			};
+		}
+		throw new Error(`generateObject failed after ${attemptsMax} attempt(s): ${lastError}. Last output: ${JSON.stringify(lastText.slice(0, 200))}`);
+	}
+	/**
+	* Text-to-speech: text → 22 kHz PCM via Kani-TTS-2 (LFM2-350M codec-LM + NVIDIA
+	* NeMo NanoCodec). Returns `{ pcm: Float32Array, sampleRate: 22050 }`.
+	*
+	* Runs the full pipeline: the codec-LM backbone autoregressively emits NanoCodec
+	* audio tokens (4 per frame, frame-level positions + learnable per-layer RoPE),
+	* then the bit-exact NanoCodec decoder (FSQ + causal HiFi-GAN) turns the codes
+	* into PCM. The heavy lifting lives in {@link KaniTTS} (src/gpu/kani-tts.ts); this
+	* lazily constructs that engine on first use (downloading the NanoCodec codec
+	* checkpoint alongside the backbone).
+	*
+	* Requires a Kani-TTS-2 checkpoint (architecture "KaniTTS2ForCausalLM").
+	*/
+	async speak(text, options = {}) {
+		this.checkDestroyed();
+		if (this._architecture !== "KaniTTS2ForCausalLM") throw new Error(`speak() requires a Kani-TTS-2 model (architecture "KaniTTS2ForCausalLM"), loaded engine is "${this._architecture}".`);
+		if (!this._kaniTTS) this._kaniTTS = await KaniTTS.create({
+			repo: this._createOptions.repo,
+			revision: this._createOptions.revision,
+			hfToken: this._createOptions.hfToken,
+			cacheDir: this._createOptions.cacheDir,
+			maxSeqLen: this.maxSeqLen
+		});
+		return this._kaniTTS.speak(text, options);
+	}
+	/**
+	* Describe an image: image-in → text-out. Runs the vision encoder, splices the
+	* merged image tokens into a text prompt, applies multimodal M-RoPE, and
+	* generates a description. Requires `enableVision: true` at create().
+	*
+	* Image input forms:
+	*  - `{ pixels, width, height }` — decoded RGB (HWC, 0..255), host-preprocessed
+	*    (smart-resize/normalize/patchify) to match the HF image processor.
+	*  - `{ patches, gridTHW }` — already-built [N,1536] patch tensor + grid (e.g.
+	*    HF-exact pixel_values from a reference; skips host preprocessing).
+	*/
+	async describeImage(image, prompt = "Describe this image.", options = {}) {
+		this.checkDestroyed();
+		if (!this.visionExecutor) throw new Error("describeImage() requires a vision encoder. Load with { enableVision: true } on a vision-capable checkpoint (Qwen3.5 or Gemma 4).");
+		if (this.visionExecutor.gemma4) {
+			if (!this._multimodalGraph) throw new Error("Gemma 4 describeImage() requires the multimodal text graph. Load with { enableVision: true } so generateGemma4Graph builds the vision_embeds + EmbedSplice variant.");
+			let g4patches;
+			let g4gridHW;
+			if ("patches" in image) {
+				g4patches = image.patches;
+				g4gridHW = [image.gridTHW[1], image.gridTHW[2]];
+			} else {
+				const pre$1 = preprocessImageGemma4(image.pixels, image.width, image.height);
+				g4patches = pre$1.patches;
+				g4gridHW = pre$1.gridHW;
+			}
+			const gThw = [
+				1,
+				g4gridHW[0],
+				g4gridHW[1]
+			];
+			const numPatches$1 = gThw[0] * gThw[1] * gThw[2];
+			this.setPhase(`describe:vit-encode:N=${numPatches$1}`);
+			const vision$1 = await this.encodeImage(g4patches, gThw, (stage, info) => {
+				const suffix = info?.layer != null ? `:L${info.layer}` : "";
+				this.setPhase(`describe:${stage}${suffix}`);
+			});
+			const cfg = this.rawConfig ?? {};
+			const imageTokenId$1 = cfg.image_token_id ?? 258880;
+			const boiId = this.tokenizer.tokenToId("<|image>") ?? cfg.boi_token_id ?? 255999;
+			const eoiId = this.tokenizer.tokenToId("<image|>") ?? cfg.eoi_token_id ?? 258882;
+			const bos = this.tokenizer.config.bosToken ? this.tokenizer.tokenToId(this.tokenizer.config.bosToken) ?? [] : [];
+			const bosIds = Array.isArray(bos) ? bos : [bos];
+			const turnUserOpen = this.tokenizer.encode("<|turn>user\n");
+			const imgLead = this.tokenizer.encode("\n\n");
+			const imgTrail = this.tokenizer.encode("\n\n");
+			const promptIds = this.tokenizer.encode(prompt);
+			const turnClose = this.tokenizer.encode("<turn|>\n<|turn>model\n");
+			const imageRun$1 = new Array(vision$1.rows).fill(imageTokenId$1);
+			const inputIds$1 = [
+				...bosIds,
+				...turnUserOpen,
+				...imgLead,
+				boiId,
+				...imageRun$1,
+				eoiId,
+				...imgTrail,
+				...promptIds,
+				...turnClose
+			];
+			return this.runMultimodalGemma4(vision$1.embeds, inputIds$1, imageTokenId$1, options);
+		}
+		if (!this._multimodalGraph) throw new Error("describeImage() requires a multimodal engine. Load with { enableVision: true } on a vision-capable checkpoint (e.g. Qwen/Qwen3.5-0.8B).");
+		const procCfg = options.imageProcessor ?? QWEN3_5_IMAGE_PROCESSOR;
+		let patches;
+		let gridTHW;
+		if ("patches" in image) {
+			patches = image.patches;
+			gridTHW = image.gridTHW;
+		} else {
+			const pre$1 = preprocessImage(image.pixels, image.width, image.height, procCfg);
+			patches = pre$1.patches;
+			gridTHW = pre$1.gridTHW;
+		}
+		const numPatches = gridTHW[0] * gridTHW[1] * gridTHW[2];
+		this.setPhase(`describe:vit-encode:N=${numPatches}`);
+		const vision = await this.encodeImage(patches, gridTHW, (stage, info) => {
+			const suffix = info?.layer != null ? `:L${info.layer}` : "";
+			this.setPhase(`describe:${stage}${suffix}`);
+		});
+		const visStart = this.tokenizer.tokenToId("<|vision_start|>") ?? 248053;
+		const visEnd = this.tokenizer.tokenToId("<|vision_end|>") ?? 248054;
+		const { imageTokenId } = this.mropeParams();
+		const numImageTokens = vision.rows;
+		const pre = this.tokenizer.encode("<|im_start|>user\n");
+		const post = this.tokenizer.encode(`${prompt}<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n`);
+		const imageRun = new Array(numImageTokens).fill(imageTokenId);
+		const inputIds = [
+			...pre,
+			visStart,
+			...imageRun,
+			visEnd,
+			...post
+		];
+		return this.runMultimodal(vision.embeds, gridTHW, inputIds, options);
+	}
+	/**
+	* Prepare the multimodal prefill: upload vision embeds, build the image row-map
+	* and 3D M-RoPE cos/sin, reset state, and write all host inputs. Returns the
+	* input ids and the post-image logical cursor for decode. Does NOT run forward.
+	*/
+	prepareMultimodalPrefill(visionEmbeds, gridTHW, inputIds) {
+		const { imageTokenId, mergeSize } = this.mropeParams();
+		const seq = inputIds.length;
+		if (seq > this.maxSeqLen) throw new Error(`describeImage: prompt+image is ${seq} tokens > maxSeqLen ${this.maxSeqLen}. Increase maxSeqLen or use a smaller image.`);
+		this.executor.reset();
+		this.executor.writeInput("vision_embeds", visionEmbeds);
+		const rowMap = new Int32Array(seq).fill(-1);
+		let v = 0;
+		for (let i = 0; i < seq; i++) if (inputIds[i] === imageTokenId) rowMap[i] = v++;
+		const positionIds3 = buildMRoPEPositionIds(inputIds, [gridTHW], imageTokenId, mergeSize);
+		return { lastLogicalPos: this.writeMRoPEPrefill(positionIds3, seq, rowMap) };
+	}
+	/**
+	* Gemma 4 multimodal prefill + decode. Unlike Qwen3.5 (M-RoPE), Gemma 4 uses
+	* STANDARD sequential 1D RoPE computed inside each layer from the KV write
+	* position, so there are no host cos/sin inputs and decode positions are simply
+	* the running seqPos — identical to plain text generation. We only upload the
+	* merged vision embeds + an image-token row-map (EmbedSplice scatters them into
+	* the image_token rows) before the forward pass.
+	*/
+	async runMultimodalGemma4(visionEmbeds, inputIds, imageTokenId, options) {
+		const seq = inputIds.length;
+		if (seq > this.maxSeqLen) throw new Error(`describeImage: prompt+image is ${seq} tokens > maxSeqLen ${this.maxSeqLen}. Increase maxSeqLen or use a smaller image.`);
+		this.setPhase(`describe:splice:seq=${seq}`);
+		this.executor.reset();
+		this.executor.writeInput("vision_embeds", visionEmbeds);
+		const rowMap = new Int32Array(seq).fill(-1);
+		let v = 0;
+		for (let i = 0; i < seq; i++) if (inputIds[i] === imageTokenId) rowMap[i] = v++;
+		this.executor.writeInput("vision_row_map", rowMap);
+		this.setPhase("describe:text-decode");
+		const { maxTokens = 512, stopSequences = [], sampling = {}, onToken } = options;
+		const startTime = performance.now();
+		const isGreedy = (sampling.temperature ?? .7) < 1e-6;
+		let { logits } = await this.executor.forward(new Uint32Array(inputIds));
+		const generatedIds = [];
+		let finishReason = "max_tokens";
+		let generatedText = "";
+		const eosId = this.tokenizer.config.eosTokenId;
+		const eotId = this.tokenizer.tokenToId("<turn|>");
+		const consumeToken = (nextToken) => {
+			generatedIds.push(nextToken);
+			if (eosId !== null && nextToken === eosId || eotId !== null && nextToken === eotId) {
+				finishReason = "eos";
+				return true;
+			}
+			const tokenText = this.tokenizer.decode([nextToken], true);
+			generatedText += tokenText;
+			onToken?.(tokenText);
+			if (stopSequences.some((s) => generatedText.includes(s))) {
+				for (const s of stopSequences) {
+					const idx = generatedText.indexOf(s);
+					if (idx !== -1) generatedText = generatedText.slice(0, idx);
+				}
+				finishReason = "stop_sequence";
+				return true;
+			}
+			return false;
+		};
+		for (let step = 0; step < maxTokens; step++) {
+			let nextToken;
+			if (step === 0) nextToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			else if (isGreedy) nextToken = await this.executor.forwardArgmax(new Uint32Array([generatedIds[generatedIds.length - 1]]));
+			else nextToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			if (consumeToken(nextToken)) break;
+			if (!isGreedy) logits = (await this.executor.forward(new Uint32Array([nextToken]))).logits;
+		}
+		const totalTime = performance.now() - startTime;
+		const tokensGenerated = generatedIds.length;
+		return {
+			text: generatedText,
+			tokensGenerated,
+			tokensPerSecond: tokensGenerated / (totalTime / 1e3),
+			totalTime,
+			finishReason
+		};
+	}
+	/** Prepare + prefill + decode for a fully-specified multimodal token sequence. */
+	async runMultimodal(visionEmbeds, gridTHW, inputIds, options) {
+		this.setPhase(`describe:splice:seq=${inputIds.length}`);
+		const { lastLogicalPos } = this.prepareMultimodalPrefill(visionEmbeds, gridTHW, inputIds);
+		this.setPhase("describe:text-decode");
+		return this.generateFromPrepared(inputIds, lastLogicalPos + 1, options);
+	}
+	/**
+	* Debug: run ONLY the multimodal prefill for an explicit token sequence and
+	* return the spliced input embeddings [seq, hidden] + first-token logits. Lets
+	* tests compare the fused text+vision stream and M-RoPE numerically vs HF
+	* without the decode loop overwriting intermediate buffers.
+	*/
+	async debugMultimodalPrefill(patches, gridTHW, inputIds) {
+		this.checkDestroyed();
+		if (!this._multimodalGraph || !this.visionExecutor) throw new Error("debugMultimodalPrefill requires a multimodal engine (enableVision: true).");
+		const vision = await this.encodeImage(patches, gridTHW);
+		this.prepareMultimodalPrefill(vision.embeds, gridTHW, inputIds);
+		const { logits } = await this.executor.forward(new Uint32Array(inputIds));
+		return {
+			splicedEmbeds: await this.executor.debugReadBuffer("embed_spliced", inputIds.length * this.config.hidden_size),
+			logits,
+			seq: inputIds.length
+		};
+	}
+	/**
+	* Internal: run prefill (assumes M-RoPE/splice inputs already written) + decode,
+	* with decode logical positions starting at `decodeStartPos`. Used by
+	* describeImage so the post-image cursor is honored.
+	*/
+	async generateFromPrepared(inputIds, decodeStartPos, options) {
+		const { maxTokens = 512, stopSequences = [], sampling = {}, onToken } = options;
+		const startTime = performance.now();
+		const isGreedy = (sampling.temperature ?? .7) < 1e-6;
+		let { logits } = await this.executor.forward(new Uint32Array(inputIds));
+		const generatedIds = [];
+		let finishReason = "max_tokens";
+		let generatedText = "";
+		const eosId = this.tokenizer.config.eosTokenId;
+		let mmLogicalPos = decodeStartPos;
+		const consumeToken = (nextToken) => {
+			generatedIds.push(nextToken);
+			if (eosId !== null && nextToken === eosId) {
+				finishReason = "eos";
+				return true;
+			}
+			const tokenText = this.tokenizer.decode([nextToken], true);
+			generatedText += tokenText;
+			onToken?.(tokenText);
+			if (stopSequences.some((s) => generatedText.includes(s))) {
+				for (const s of stopSequences) {
+					const idx = generatedText.indexOf(s);
+					if (idx !== -1) generatedText = generatedText.slice(0, idx);
+				}
+				finishReason = "stop_sequence";
+				return true;
+			}
+			return false;
+		};
+		for (let step = 0; step < maxTokens; step++) {
+			let nextToken;
+			if (step === 0) nextToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			else if (isGreedy) {
+				this.writeMRoPEDecodeStep(this.executor.currentSeqPos, mmLogicalPos);
+				nextToken = await this.executor.forwardArgmax(new Uint32Array([generatedIds[generatedIds.length - 1]]));
+				mmLogicalPos++;
+			} else nextToken = sampleToken(logits, sampling, [...inputIds, ...generatedIds]);
+			if (consumeToken(nextToken)) break;
+			if (!isGreedy) {
+				this.writeMRoPEDecodeStep(this.executor.currentSeqPos, mmLogicalPos);
+				logits = (await this.executor.forward(new Uint32Array([nextToken]))).logits;
+				mmLogicalPos++;
+			}
+		}
+		const totalTime = performance.now() - startTime;
+		const tokensGenerated = generatedIds.length;
+		return {
+			text: generatedText,
+			tokensGenerated,
+			tokensPerSecond: tokensGenerated / (totalTime / 1e3),
+			totalTime,
+			finishReason
+		};
+	}
+	/**
+	* Embed text into an L2-normalized vector. The pooling strategy depends on the
+	* model: Qwen3-Embedding uses last-token (EOS-position) pooling, while
+	* EmbeddingGemma (Gemma3 encoder) uses mean pooling over all tokens followed by
+	* a 2-layer Dense head. Requires an embedding model (loaded with
+	* { embedding: true }).
+	*
+	* The returned Float32Array has unit L2 norm, so cosine similarity reduces to a
+	* dot product. Length is the model's embedding dim (768 for EmbeddingGemma;
+	* config.hidden_size for Qwen3-Embedding).
+	*
+	* EmbeddingGemma is asymmetric — pass `{ taskType: "query" }` for search
+	* queries and `{ taskType: "document" }` for the corpus, or a raw
+	* `{ taskPrompt }` for other tasks (clustering/classification/STS).
+	*/
+	async embed(text, options = {}) {
+		this.checkDestroyed();
+		if (!this._isEmbedding) throw new Error("embed() requires an embedding model. Load with { embedding: true } (e.g. repo: 'Qwen/Qwen3-Embedding-0.6B' or 'mlx-community/embeddinggemma-300m-4bit').");
+		this.executor.reset();
+		const { instruction, taskType, taskPrompt, maxTokens } = options;
+		if (this._architecture === "Gemma3TextModel" || this._architecture === "Gemma3Model") {
+			const input$1 = `${taskPrompt ?? EMBEDDING_GEMMA_PROMPTS[taskType ?? "query"] ?? EMBEDDING_GEMMA_PROMPTS.query}${text}`;
+			let ids$1 = this.tokenizer.encode(input$1);
+			const cap$1 = maxTokens ?? this.config.context_length;
+			if (ids$1.length > cap$1) ids$1 = ids$1.slice(0, cap$1);
+			return this.executor.embed(new Uint32Array(ids$1));
+		}
+		const input = instruction ? `Instruct: ${instruction}\nQuery:${text}` : text;
+		let ids = this.tokenizer.encode(input);
+		const padId = this.tokenizer.tokenToId("<|endoftext|>") ?? this.tokenizer.config.eosTokenId;
+		if (padId !== null && ids[ids.length - 1] !== padId) ids.push(padId);
+		const cap = maxTokens ?? this.config.context_length;
+		if (ids.length > cap) {
+			const tail = padId !== null && ids[ids.length - 1] === padId ? [padId] : [];
+			ids = [...ids.slice(0, cap - tail.length), ...tail];
+		}
+		return this.executor.embed(new Uint32Array(ids));
+	}
+	/**
+	* Generate text as an async iterator (streaming).
+	*
+	* Uses the onToken callback from generate() to push tokens into a queue
+	* that the async generator yields from. The generator returns the full
+	* GenerateResult when generation completes.
+	*
+	* Usage:
+	*   const gen = engine.stream("Hello!");
+	*   for await (const token of gen) {
+	*     process.stdout.write(token);
+	*   }
+	*   const result = gen.next(); // { done: true, value: GenerateResult }
+	*/
+	async *stream(prompt, options = {}) {
+		this.checkDestroyed();
+		const tokenQueue = [];
+		let resolve = null;
+		let done = false;
+		const pushToken = (token) => {
+			tokenQueue.push(token);
+			if (resolve) {
+				const r = resolve;
+				resolve = null;
+				r();
+			}
+		};
+		const waitForToken = () => {
+			if (tokenQueue.length > 0 || done) return Promise.resolve();
+			return new Promise((r) => {
+				resolve = r;
+			});
+		};
+		const genPromise = this.generate(prompt, {
+			...options,
+			onToken: (token) => {
+				options.onToken?.(token);
+				pushToken(token);
+			}
+		}).then((result) => {
+			done = true;
+			if (resolve) {
+				const r = resolve;
+				resolve = null;
+				r();
+			}
+			return result;
+		});
+		let yielded = 0;
+		while (true) {
+			await waitForToken();
+			while (yielded < tokenQueue.length) yield tokenQueue[yielded++];
+			if (done && yielded >= tokenQueue.length) break;
+		}
+		return await genPromise;
+	}
+	/**
+	* Debug: read back a named GPU buffer (weight or activation).
+	* Call after forward() to inspect intermediate values.
+	*/
+	async debugReadBuffer(tensorName, maxElements) {
+		return this.executor.debugReadBuffer(tensorName, maxElements);
+	}
+	/**
+	* Run GPU diagnostics (buffer integrity, compute, shared memory).
+	* Useful for isolating Safari/WebKit-specific WebGPU issues.
+	*/
+	async diagnose() {
+		return verifyGPU(this.ctx);
+	}
+	/**
+	* Run GPU diagnostics without loading a model.
+	* Quick way to check if WebGPU is working correctly on this device.
+	*/
+	static async quickDiagnose() {
+		const ctx = await initGPU();
+		const result = await verifyGPU(ctx);
+		clearPipelineCache(ctx.device);
+		ctx.device.destroy();
+		return result;
+	}
+	/**
+	* Run a raw forward pass (no tokenization/chat template).
+	* Returns logits for the last token.
+	*/
+	async rawForward(inputIds) {
+		return this.executor.forward(inputIds);
+	}
+	/**
+	* Reset executor state (SSM, positions, etc.)
+	*/
+	resetState() {
+		this.executor.reset();
+	}
+	/**
+	* Encode text to token IDs (useful for debugging / token counting).
+	*/
+	encode(text) {
+		return this.tokenizer.encode(text);
+	}
+	/**
+	* Decode token IDs to text.
+	*/
+	decode(ids, skipSpecialTokens) {
+		return this.tokenizer.decode(ids, skipSpecialTokens);
+	}
+	/**
+	* Integrity check: reads back key weight tensors and runs a single forward pass,
+	* returning checksums for comparison against a known-good reference (Dawn/Node.js).
+	*
+	* Use this to isolate Safari/iPad corruption:
+	* - If weights mismatch → fetch/download pipeline is corrupt
+	* - If weights match but logits mismatch → kernel computation bug on Metal
+	*
+	* Resets executor state before and after (safe to call anytime).
+	*/
+	async integrityCheck() {
+		this.checkDestroyed();
+		const checks = [];
+		const log = (label, data) => {
+			const f = data instanceof Float32Array ? data : new Float32Array(data.buffer);
+			let sum = 0;
+			let maxVal = -Infinity;
+			let argmax$1 = 0;
+			for (let i = 0; i < f.length; i++) {
+				sum += f[i];
+				if (f[i] > maxVal) {
+					maxVal = f[i];
+					argmax$1 = i;
+				}
+			}
+			const entry = {
+				label,
+				length: f.length,
+				sum: Math.round(sum * 1e6) / 1e6,
+				first4: [
+					Math.round(f[0] * 1e6) / 1e6,
+					Math.round(f[1] * 1e6) / 1e6,
+					Math.round(f[2] * 1e6) / 1e6,
+					Math.round(f[3] * 1e6) / 1e6
+				],
+				argmax: argmax$1,
+				maxVal: Math.round(maxVal * 1e4) / 1e4
+			};
+			checks.push(entry);
+			return entry;
+		};
+		checks.push({
+			label: `webkit_detection: isWebKitWebGPU=${this.ctx.isWebKitWebGPU} needsMultiEncoder=${this.executor.needsMultiEncoder}`,
+			length: 0,
+			sum: 0,
+			first4: [
+				0,
+				0,
+				0,
+				0
+			],
+			argmax: 0,
+			maxVal: 0,
+			note: this.ctx.adapterDescription
+		});
+		for (const name of ["norm.weight", "layers.0.input_layernorm.weight"]) try {
+			log(name, await this.debugReadBuffer(name));
+		} catch {
+			checks.push({
+				label: name,
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: "buffer not found"
+			});
+		}
+		for (const qName of [
+			"layers.0.mlp.gate_proj.weight.q",
+			"embed_tokens.weight.q",
+			"embed_tokens.weight.scales",
+			"embed_tokens.weight.zeros"
+		]) try {
+			const q = await this.debugReadBuffer(qName, 16);
+			log(`${qName} (reinterpret)`, q);
+		} catch {
+			checks.push({
+				label: qName,
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: "not found"
+			});
+		}
+		this.executor.reset();
+		try {
+			const result = await this.executor.debugFirstDispatch(new Uint32Array([1]));
+			const entry = log(`single_dispatch(${result.opType})`, result.output);
+			entry.note = `dispatch=${result.dispatchSize.join(",")} node=${result.nodeId}`;
+		} catch (e) {
+			checks.push({
+				label: "single_dispatch",
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: e.message
+			});
+		}
+		try {
+			const result = await this.executor.debugDispatchEntry(1, 1);
+			const entry = log(`isolated_entry1(${result.opType})`, result.output);
+			entry.note = `node=${result.nodeId}`;
+		} catch (e) {
+			checks.push({
+				label: "isolated_entry1",
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: e.message
+			});
+		}
+		try {
+			const result = await this.executor.debugDispatchEntry(2, 1);
+			const entry = log(`isolated_entry2(${result.opType})`, result.output);
+			entry.note = `node=${result.nodeId}`;
+		} catch (e) {
+			checks.push({
+				label: "isolated_entry2",
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: e.message
+			});
+		}
+		this.executor.reset();
+		const jsParams = this.executor.debugComputeParams(1, 5);
+		for (const p of jsParams) checks.push({
+			label: `jsParams[${p.idx}] ${p.opType} dispatch=[${p.dispatchSize}] u32=[${p.paramsU32}]`,
+			length: p.paramsU32.length,
+			sum: p.paramsU32.reduce((a, b) => a + b, 0),
+			first4: p.paramsU32.slice(0, 4).map(Number),
+			argmax: 0,
+			maxVal: 0
+		});
+		this.executor.reset();
+		try {
+			const { logits } = await this.executor.forward(new Uint32Array([1]));
+			log("logits(token=1)", logits);
+			try {
+				log("embed_out", await this.debugReadBuffer("embed_out", 16));
+			} catch {}
+			try {
+				const probes = await this.executor.debugPipelineProbe(1);
+				for (const p of probes) {
+					const paramsStr = p.uniformParams ? ` params=[${p.uniformParams.join(",")}]` : "";
+					const entry = {
+						label: `probe[${p.idx}] ${p.opType} → ${p.tensor}${paramsStr}`,
+						length: 16,
+						sum: p.sum,
+						first4: p.first4,
+						argmax: 0,
+						maxVal: Math.max(...p.first4.map(Math.abs))
+					};
+					if (p.sum === 0 && p.first4.every((v) => v === 0)) {
+						entry.match = "FAIL";
+						entry.note = "all zeros — activation dead";
+					}
+					checks.push(entry);
+				}
+			} catch (e) {
+				checks.push({
+					label: "pipeline_probe",
+					length: 0,
+					sum: NaN,
+					first4: [
+						NaN,
+						NaN,
+						NaN,
+						NaN
+					],
+					argmax: -1,
+					maxVal: NaN,
+					error: e.message
+				});
+			}
+		} catch (e) {
+			checks.push({
+				label: "logits(token=1)",
+				length: 0,
+				sum: NaN,
+				first4: [
+					NaN,
+					NaN,
+					NaN,
+					NaN
+				],
+				argmax: -1,
+				maxVal: NaN,
+				error: e.message
+			});
+		}
+		this.executor.reset();
+		const reference = {
+			"norm.weight": {
+				sum: 4412.571289,
+				first4: [
+					.222656,
+					3.75,
+					3.640625,
+					4.0625
+				]
+			},
+			"layers.0.input_layernorm.weight": {
+				sum: 1267.312683,
+				first4: [
+					2,
+					1.294922,
+					1.535156,
+					1.746094
+				]
+			},
+			embed_out: {
+				sum: -.067839,
+				first4: [
+					.010059,
+					.0264,
+					.001888,
+					-.030794
+				]
+			}
+		};
+		for (const check of checks) {
+			const ref = reference[check.label];
+			if (ref) {
+				const sumMatch = Math.abs(check.sum - ref.sum) < Math.max(Math.abs(ref.sum) * .001, 1);
+				const first4Match = check.first4.every((v, i) => Math.abs(v - ref.first4[i]) < .01);
+				check.match = sumMatch && first4Match ? "PASS" : "FAIL";
+				check.refSum = ref.sum;
+			} else if (check.label === "logits(token=1)") {
+				const hasNaN = check.first4.some((v) => Number.isNaN(v));
+				const hasInf = check.first4.some((v) => !Number.isFinite(v));
+				const allSame = check.first4.every((v) => v === check.first4[0]);
+				const argmaxValid = check.argmax >= 0 && check.argmax < check.length;
+				check.match = !hasNaN && !hasInf && !allSame && argmaxValid ? "PASS" : "FAIL";
+			}
+		}
+		console.log("\n=== INTEGRITY CHECK ===");
+		for (const c of checks) {
+			const status = c.error ? "ERR" : c.match ?? "---";
+			console.log(`[${status}] ${c.label}: sum=${c.sum}, first4=[${c.first4.join(", ")}], argmax=${c.argmax}, len=${c.length}` + (c.refSum !== void 0 ? ` (ref sum=${c.refSum})` : "") + (c.error ? ` ERROR: ${c.error}` : "") + (c.note ? ` | ${c.note}` : ""));
+		}
+		console.log("=== END INTEGRITY CHECK ===\n");
+		return {
+			checks,
+			allPass: checks.every((c) => c.match === "PASS" || c.match === void 0)
+		};
+	}
+	/**
+	* Destroy the engine and free all GPU resources.
+	*/
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		this.executor.destroy();
+		this._kaniTTS?.destroy();
+		this.visionExecutor?.destroy();
+		clearPipelineCache(this.ctx.device);
+		this.ctx.device.destroy();
+	}
+	checkDestroyed() {
+		if (this._destroyed) throw new Error("WebGPUEngine has been destroyed");
+	}
+};
+
+//#endregion
+export { generateGemma4VisionGraph as C, dequantizeMLXProjection as S, resolveGemma4VisionInfo as T, smartResize as _, buildGemma4PosEmbeds as a, generateQwen3_5VisionGraph as b, buildMRoPECosSin as c, buildPositionIds as d, buildRotaryCosSin as f, preprocessImageGemma4 as g, preprocessImage as h, buildGemma4PoolMatrix as i, buildMRoPEPositionIds as l, mropeFreqDims as m, GEMMA4_IMAGE_PROCESSOR as n, buildGemma4RotaryCosSin as o, buildVisionPositionTensors as p, QWEN3_5_IMAGE_PROCESSOR as r, buildGemma4VisionPositionTensors as s, WebGPUEngine as t, buildPosEmbeds as u, VisionExecutor as v, patchGemma4VisionClips as w, dequantizeGemma4VisionProjection as x, KaniTTS as y };
+//# sourceMappingURL=gpu-33qCAtHW.mjs.map