diskformer.js c8d19ac: chat example, engines, store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chirag Patnaik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,23 @@
 ---
-title: Diskformer Chat
-emoji: 👁
-colorFrom: blue
-colorTo: purple
+title: diskformer chat
+colorFrom: gray
+colorTo: blue
 sdk: static
+app_file: examples/chat/index.html
 pinned: false
+license: mit
+short_description: A 14.4 GB model in 2.5 GB of GPU memory, in your tab
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# diskformer chat
+
+Gemma 4 26B-A4B (14.4 GB) or Qwen3.6 35B-A3B (36.9 GB) running in your browser tab with a GPU memory budget you
+choose. The model downloads once into your browser's private storage (OPFS); the GPU holds the dense layers and a
+small cache of experts, and the rest are read from disk as each token needs them.
+
+Needs Chrome or Edge with WebGPU and shader-f16, and free disk space for the model. Open the app in its own tab,
+so its storage is first-party: https://naklitechie-diskformer-chat.static.hf.space/examples/chat/
+
+Source, measurements and tests: [github.com/NakliTechie/diskformer.js](https://github.com/NakliTechie/diskformer.js).
+Model terms: Gemma ([ai.google.dev/gemma/terms](https://ai.google.dev/gemma/terms)); Qwen3.6, Apache-2.0. Engine
+kernels are ported from gemma4-webgpu (Apache-2.0, see `engines/NOTICE`).

engines/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tyler Straub
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

engines/NOTICE

@@ -0,0 +1,17 @@
+diskformer.js — engines/
+
+The WGSL kernels in these engines are ports of browser-big-fast-lab's custom-kernels engine, an Apache-2.0
+fork of gemma4-webgpu:
+
+  gemma4-webgpu
+  Copyright 2026 Tyler Straub
+  Licensed under the Apache License, Version 2.0 (engines/LICENSE-APACHE)
+  https://github.com/tylerstraub/gemma4-webgpu
+
+Changes from the original: rewritten for mixture-of-experts models whose experts stream from OPFS (Q8_0 and Q4_0
+split planes, slot-indexed expert GEMVs, GPU router top-k, chunked prefill, Q6_K head planes). Everything else in
+this folder is MIT (../LICENSE), Copyright (c) 2026 Chirag Patnaik.
+
+The engine files are copies of LocalMind's (https://github.com/NakliTechie/LocalMind), kept in step by
+scripts/sync-localmind.mjs. Model weights are not distributed: each model is downloaded by the user under its own
+terms (Gemma: https://ai.google.dev/gemma/terms; Qwen3.6: Apache-2.0).

engines/gemma4_moe_ssd.js

@@ -0,0 +1,1291 @@
+/* gemma4_moe_ssd.js — Gemma 4 26B-A4B (GGUF arch `gemma4`, MoE) with its routed experts on disk:
+ * rung 2c of the SSD-streaming ladder. Reuses rung 2a/2b's OPFS ingest, reader pool and expert streamer
+ * (qwen3_moe_ssd.js, moe-expert-stream.js); what differs is the file format and the trunk.
+ *
+ * The math follows llama.cpp b9830's src/models/gemma4.cpp (notes: LocalMind plan/gemma4-26b-a4b-port-notes.md;
+ * a numpy copy of it, scripts/gemma4-ref.py, gives per-layer states to compare against). Per layer:
+ *   attention: RMS norm → Q/K/V (Q4_0) → per-head RMS norm on Q and K (weighted) and V (unweighted; full-attention
+ *   layers have no V projection and reuse K's) → NeoX RoPE (sliding layers: 256-dim heads, base 1e4; full layers:
+ *   512-dim heads, base 1e6, `rope_freqs` leaves all but the first 64 pairs unrotated) → attention with scale 1.0,
+ *   sliding layers over the last 1024 positions → output projection → post-norm → residual;
+ *   FFN: a dense GELU MLP (2112) beside the MoE block (128 experts, top 8, GELU, a per-expert down scale), the router
+ *   on rms_norm(x)·(1/√H)·scale; each branch post-normed, summed, normed again → residual → × layer_output_scale.
+ * Embedding: Q6_K rows × √H; head: the same Q6_K table, then a soft cap tanh(l/30)·30.
+ *
+ * File format (google/gemma-4-26B-A4B-it-qat-q4_0-gguf): matmul weights Q4_0, norms / router / scales F32,
+ * the token embedding (tied output head) Q6_K. Experts: fused `ffn_gate_up_exps` [H, 2F, E] (gate rows first)
+ * and `ffn_down_exps` [F, H, E], both Q4_0, plus `ffn_down_exps.scale` [E].
+ */
+
+import { Qwen3MoeSsd, GGML, Q4_BLOCK, Q6K_BLOCK, tensorBytes, TOK, STORAGE, COPY_SRC, COPY_DST, MAP_READ } from './qwen3_moe_ssd.js';
+import { OpfsReaderPool } from '../src/opfs-reader.js';
+import { QWEN35_BATCH_KERNELS } from './qwen35_moe_ssd.js';
+
+export function configFromGgufGemma4(kv) {
+  const a = kv['general.architecture'];
+  if (a !== 'gemma4') throw new Error(`expected a gemma4 GGUF, got ${a}`);
+  const g = (k) => kv[`${a}.${k}`];
+  const layers = g('block_count');
+  const perLayer = (v) => (Array.isArray(v) ? v : Array(layers).fill(v));
+  const swa = perLayer(g('attention.sliding_window_pattern')).map(Boolean);
+  if (!g('expert_count')) throw new Error('gemma4 GGUF without experts: this engine is for the MoE (26B-A4B)');
+  return {
+    arch: a, layers,
+    hidden: g('embedding_length'), denseFf: g('feed_forward_length'),
+    heads: g('attention.head_count'), kvHeads: perLayer(g('attention.head_count_kv')),
+    swa,                                                             // true: sliding-window layer
+    headDim: swa.map((s) => (s ? g('attention.key_length_swa') : g('attention.key_length'))),
+    ropeDims: swa.map((s) => (s ? g('rope.dimension_count_swa') : g('rope.dimension_count'))),
+    ropeTheta: swa.map((s) => (s ? g('rope.freq_base_swa') : g('rope.freq_base'))),
+    window: g('attention.sliding_window'),
+    experts: g('expert_count'), topK: g('expert_used_count'), expertFf: g('expert_feed_forward_length'),
+    softcap: g('final_logit_softcapping') || 0,
+    eps: g('attention.layer_norm_rms_epsilon'),
+    contextLength: g('context_length'),
+    vocab: kv['tokenizer.ggml.tokens'].length,
+    bos: kv['tokenizer.ggml.bos_token_id'], eos: kv['tokenizer.ggml.eos_token_id'],
+  };
+}
+
+// The OPFS layout from the header alone. One expert record = the fused gate/up planes then the down
+// planes, each split into a nibble plane (16 B per 32 values) and an f16 scale plane (2 B per 32).
+export function planLayoutGemma4(gguf) {
+  const cfg = configFromGgufGemma4(gguf.kv);
+  const H = cfg.hidden, F = cfg.expertFf;
+  const nib = (rows, cols) => rows * cols / 2, scl = (rows, cols) => rows * (cols / 32) * 2;
+  const parts = {
+    guQ: { off: 0, bytes: nib(2 * F, H) },                         // gate rows 0..F-1, up rows F..2F-1
+    guS: { off: nib(2 * F, H), bytes: scl(2 * F, H) },
+    dQ: { off: nib(2 * F, H) + scl(2 * F, H), bytes: nib(H, F) },
+    dS: { off: nib(2 * F, H) + scl(2 * F, H) + nib(H, F), bytes: scl(H, F) },
+  };
+  const record = parts.dS.off + parts.dS.bytes;
+  const dense = {};
+  let off = 0;
+  const take = (n) => { const o = off; off += Math.ceil(n / 256) * 256; return o; };
+  for (const t of gguf.tensors) {
+    if (/_exps\.weight$/.test(t.name)) continue;
+    const n = t.dims.reduce((x, y) => x * y, 1);
+    if (t.type === GGML.Q4_0) {
+      dense[t.name] = { type: 'q4', dims: t.dims, q: { off: take(n / 2), bytes: n / 2 }, s: { off: take(n / 16), bytes: n / 16 } };
+    } else if (t.type === GGML.Q6_K) {
+      dense[t.name] = { type: 'q6k', dims: t.dims, raw: { off: take(tensorBytes(t)), bytes: tensorBytes(t) } };
+    } else if (t.type === GGML.F32) {
+      dense[t.name] = { type: 'f32', dims: t.dims, raw: { off: take(n * 4), bytes: n * 4 } };
+    } else throw new Error(`dense tensor ${t.name}: unsupported type ${t.type}`);
+  }
+  return {
+    config: cfg,
+    experts: { file: 'experts.bin', record, parts, layers: cfg.layers, perLayer: cfg.experts, bytes: record * cfg.layers * cfg.experts },
+    dense: { file: 'dense.bin', bytes: off, tensors: dense },
+  };
+}
+
+// Byte ranges of the GGUF to keep, each small enough to transform in memory: one unit per expert slice
+// (kind q4), row bands of dense Q4_0 tensors (kind q4), whole Q6_K / F32 tensors (raw).
+export function planUnitsGemma4(gguf, layout) {
+  const units = [];
+  const { record, parts, perLayer } = layout.experts;
+  for (const t of gguf.tensors) {
+    const abs = gguf.dataStart + t.offset;
+    const m = /^blk\.(\d+)\.ffn_(gate_up|down)_exps\.weight$/.exec(t.name);
+    if (m) {
+      if (t.type !== GGML.Q4_0) throw new Error(`${t.name}: experts must be Q4_0`);
+      const layer = Number(m[1]), gu = m[2] === 'gate_up';
+      const slice = tensorBytes(t) / perLayer;
+      for (let e = 0; e < perLayer; e++) {
+        const rec = (layer * perLayer + e) * record;
+        units.push({ kind: 'q4', src: abs + e * slice, len: slice, file: 'experts', q: rec + (gu ? parts.guQ.off : parts.dQ.off), s: rec + (gu ? parts.guS.off : parts.dS.off) });
+      }
+      continue;
+    }
+    const d = layout.dense.tensors[t.name];
+    if (d.type !== 'q4') { units.push({ src: abs, len: d.raw.bytes, file: 'dense', raw: d.raw.off }); continue; }
+    const cols = t.dims[0], rows = (d.q.bytes * 2) / cols, rowBytes = (cols / 32) * Q4_BLOCK;
+    const band = Math.max(1, Math.floor((8 << 20) / rowBytes));
+    for (let r = 0; r < rows; r += band) {
+      const nr = Math.min(band, rows - r);
+      units.push({ kind: 'q4', src: abs + r * rowBytes, len: nr * rowBytes, file: 'dense', q: d.q.off + r * cols / 2, s: d.s.off + r * (cols / 32) * 2 });
+    }
+  }
+  units.sort((a, b) => a.src - b.src);
+  return units;
+}
+
+export const GEMMA4_INGEST_PLAN = { layout: planLayoutGemma4, units: planUnitsGemma4 };
+
+export const GEMMA4_26B_A4B = {
+  repo: 'google/gemma-4-26B-A4B-it-qat-q4_0-gguf',
+  file: 'gemma-4-26B_q4_0-it.gguf',
+  revision: 'd1c082be9cf3c8a514acf63b8761f4b41935842e',
+  sha256: '3eca3b8f6d7baf218a7dd6bba5fb59a56ee25fe2d567b6f5f589b4f697eca51d',
+  size: 14439363584,
+};
+
+// The GGUF's chat template (text turns): <bos>, a system turn when there is a system message or thinking is on
+// (<|think|> first), then <|turn>user|model … <turn|> per message, and the model turn opened. With thinking off
+// the model turn starts with an empty thought channel. Earlier model turns lose their thought channels.
+const stripThinking = (t) => t.split('<channel|>').map((p) => (p.includes('<|channel>') ? p.split('<|channel>')[0] : p)).join('').trim();
+export function gemmaChatPrompt(messages, { enableThinking = false } = {}) {
+  let s = '<bos>', msgs = messages;
+  const sys = msgs.length && msgs[0].role === 'system' ? String(msgs[0].content).trim() : null;
+  if (enableThinking || sys !== null) {
+    s += '<|turn>system\n' + (enableThinking ? '<|think|>\n' : '') + (sys ?? '') + '<turn|>\n';
+    if (sys !== null) msgs = msgs.slice(1);
+  }
+  for (const m of msgs) {
+    const role = m.role === 'assistant' ? 'model' : m.role;
+    s += `<|turn>${role}\n${role === 'model' ? stripThinking(String(m.content)) : String(m.content).trim()}<turn|>\n`;
+  }
+  return s + '<|turn>model\n' + (enableThinking ? '' : '<|channel>thought\n<channel|>');
+}
+
+// ── Tokenizer: SentencePiece-style BPE (GGUF tokenizer.ggml.model = gemma4) ──
+// As llama.cpp's LLAMA_VOCAB_PRE_TYPE_GEMMA4: spaces become ▁, the text splits only into runs of newlines and
+// runs of everything else, merges run on raw UTF-8 characters in rank order (leftmost first on equal ranks),
+// and a run made only of newlines that is itself a token stays whole. A character with no token falls back
+// to <0xXX> byte tokens (SentencePiece byte fallback; llama.cpp drops it instead).
+export class GemmaTokenizer {
+  constructor(kv) {
+    this.tokens = kv['tokenizer.ggml.tokens'];
+    const types = kv['tokenizer.ggml.token_type'] || [];
+    const n = this.tokens.length;
+    this.ids = new Map(this.tokens.map((t, i) => [t, i]));
+    this.ranks = new Map((kv['tokenizer.ggml.merges'] || []).map((m, i) => [m, i]));
+    this.isSpecial = new Uint8Array(n); this.byteOf = new Int16Array(n).fill(-1); this.byteTok = new Int32Array(256).fill(-1);
+    const special = [];
+    for (let i = 0; i < n; i++) {
+      if (types[i] === 3 || types[i] === 4) { special.push(this.tokens[i]); this.isSpecial[i] = 1; }
+      const m = types[i] === 6 && /^<0x([0-9A-Fa-f]{2})>$/.exec(this.tokens[i]);
+      if (m) { const b = parseInt(m[1], 16); this.byteOf[i] = b; this.byteTok[b] = i; }
+    }
+    special.sort((a, b) => b.length - a.length);
+    const esc = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    this.specialRe = special.length ? new RegExp(`(${special.map(esc).join('|')})`) : null;
+    this.utf8 = new TextEncoder();
+  }
+  encode(text, { parseSpecial = true } = {}) {
+    const out = [];
+    const pieces = parseSpecial && this.specialRe ? text.split(this.specialRe) : [text];
+    for (let i = 0; i < pieces.length; i++) {
+      const piece = pieces[i];
+      if (!piece) continue;
+      if (parseSpecial && i % 2 === 1) { out.push(this.ids.get(piece)); continue; }
+      for (const [run] of piece.replaceAll(' ', '▁').matchAll(/[^\n]+|\n+/g)) {
+        const whole = run[0] === '\n' ? this.ids.get(run) : undefined;
+        if (whole !== undefined) out.push(whole); else this.bpe(run, out);
+      }
+    }
+    return out;
+  }
+  // Rank-ordered merges over a linked list of symbols, with a binary heap of candidate pairs.
+  bpe(word, out) {
+    const text = Array.from(word), n = text.length;
+    const prev = Int32Array.from({ length: n }, (_, i) => i - 1), next = Int32Array.from({ length: n }, (_, i) => (i + 1 < n ? i + 1 : -1));
+    const heap = [];
+    const less = (a, b) => a.rank < b.rank || (a.rank === b.rank && a.left < b.left);
+    const push = (e) => { heap.push(e); let i = heap.length - 1; while (i > 0) { const p = (i - 1) >> 1; if (!less(heap[i], heap[p])) break; [heap[i], heap[p]] = [heap[p], heap[i]]; i = p; } };
+    const pop = () => {
+      const top = heap[0], last = heap.pop();
+      if (heap.length) { heap[0] = last; let i = 0; for (;;) { const l = 2 * i + 1, r = l + 1; let m = i; if (l < heap.length && less(heap[l], heap[m])) m = l; if (r < heap.length && less(heap[r], heap[m])) m = r; if (m === i) break; [heap[i], heap[m]] = [heap[m], heap[i]]; i = m; } }
+      return top;
+    };
+    const pair = (left, right) => {
+      if (left < 0 || right < 0) return;
+      const t = text[left] + text[right], rank = this.ranks.get(text[left] + ' ' + text[right]);
+      if (rank !== undefined) push({ rank, left, right, t });
+    };
+    for (let i = 1; i < n; i++) pair(i - 1, i);
+    while (heap.length) {
+      const b = pop();
+      if (!text[b.left] || !text[b.right] || text[b.left] + text[b.right] !== b.t) continue;
+      text[b.left] = b.t; text[b.right] = '';
+      next[b.left] = next[b.right];
+      if (next[b.right] >= 0) prev[next[b.right]] = b.left;
+      pair(prev[b.left], b.left);
+      pair(b.left, next[b.left]);
+    }
+    for (let i = 0; i >= 0 && i < n; i = next[i]) {
+      if (!text[i]) continue;
+      const id = this.ids.get(text[i]);
+      if (id !== undefined) { out.push(id); continue; }
+      for (const byte of this.utf8.encode(text[i])) if (this.byteTok[byte] >= 0) out.push(this.byteTok[byte]);
+    }
+    return out;
+  }
+  tokenBytes(id) {
+    if (this.byteOf[id] >= 0) return Uint8Array.of(this.byteOf[id]);
+    const t = this.tokens[id];
+    return this.utf8.encode(this.isSpecial[id] ? t : t.replaceAll('▁', ' '));
+  }
+  decode(ids) {
+    const chunks = ids.map((id) => this.tokenBytes(id));
+    const all = new Uint8Array(chunks.reduce((a, c) => a + c.length, 0));
+    let o = 0; for (const c of chunks) { all.set(c, o); o += c.length; }
+    return new TextDecoder('utf-8', { ignoreBOM: true }).decode(all);
+  }
+}
+
+// ── WGSL ────────────────────────────────────────────────────────────────────
+// Q4_0 as two planes (ingest's splitQ4): nibbles, 16 bytes per 32 values (byte j holds values j and j + 16),
+// and one f16 scale per 32. Value = (nibble − 8) · scale, as ggml dequantizes it. Each thread reads one u32 of
+// nibbles: values 4m..4m+3 (low nibbles) and 16+4m..16+4m+3 (high nibbles) of block b.
+const Q4DOT = `
+fn q4dot(wd: u32, d: f32, xb: u32) -> f32 {
+  let lo = (f32(wd & 15u) - 8.0) * xin[xb] + (f32((wd >> 8u) & 15u) - 8.0) * xin[xb + 1u]
+         + (f32((wd >> 16u) & 15u) - 8.0) * xin[xb + 2u] + (f32((wd >> 24u) & 15u) - 8.0) * xin[xb + 3u];
+  let hi = (f32((wd >> 4u) & 15u) - 8.0) * xin[xb + 16u] + (f32((wd >> 12u) & 15u) - 8.0) * xin[xb + 17u]
+         + (f32((wd >> 20u) & 15u) - 8.0) * xin[xb + 18u] + (f32((wd >> 28u) & 15u) - 8.0) * xin[xb + 19u];
+  return d * (lo + hi);
+}`;
+// Q6_K (ggml block_q6_K: ql[128], qh[64], int8 scales[16], f16 d per 256 values). The GGUF's 210-byte blocks
+// sit at 2-byte alignment, so at load q6kPlanes splits the table on the GPU into aligned planes: ql (32 words
+// per block), qh (16), scales (4) and d as f32. q6v reads value t of block bi exactly as dequantize_row_q6_K
+// forms it: (d · scale) · (q − 32).
+const Q6P = `
+@group(0) @binding(0) var<storage, read> ql: array<u32>;
+@group(0) @binding(1) var<storage, read> qh: array<u32>;
+@group(0) @binding(2) var<storage, read> sc: array<u32>;
+@group(0) @binding(3) var<storage, read> dd: array<f32>;
+fn sc8(bi: u32, si: u32) -> f32 { let s8 = (sc[bi * 4u + (si >> 2u)] >> ((si & 3u) * 8u)) & 0xffu; return f32(select(i32(s8), i32(s8) - 256, s8 >= 128u)); }
+fn q6v(bi: u32, t: u32) -> f32 {
+  let n = t >> 7u; let r = t & 127u; let qd = r >> 5u; let l = r & 31u;
+  let qb = n * 64u + l + (qd & 1u) * 32u;
+  let lo = (ql[bi * 32u + (qb >> 2u)] >> ((qb & 3u) * 8u)) & 0xffu;
+  let q4 = select(lo & 15u, lo >> 4u, qd >= 2u);
+  let hb = n * 32u + l;
+  let h = (qh[bi * 16u + (hb >> 2u)] >> ((hb & 3u) * 8u + qd * 2u)) & 3u;
+  return dd[bi] * sc8(bi, n * 8u + (l >> 4u) + qd * 2u) * f32(i32(q4 | (h << 4u)) - 32);
+}`;
+// tanh with its argument clamped: tanh(±10) is ±1 in f32, and a naive exp-based tanh would give NaN past ~44.
+const TANH = 'fn tanhc(a: f32) -> f32 { return tanh(clamp(a, -10.0, 10.0)); }';
+const GELU = `${TANH}
+fn gelu(x: f32) -> f32 { return 0.5 * x * (1.0 + tanhc(0.7978845608 * x * (1.0 + 0.044715 * x * x))); }`;
+// The window: sliding layers attend to the last `win` positions (llama.cpp masks p_q − p_k ≥ win).
+const WIN = 'fn winStart(n: u32, win: u32) -> u32 { return select(0u, n - win, win > 0u && n > win); }';
+
+const G4 = {
+  // The GGUF's Q6_K bytes (raw) → aligned planes; one thread per block.
+  q6kPlanes: `
+struct P { blocks: u32 }
+@group(0) @binding(0) var<storage, read> raw: array<u32>;
+@group(0) @binding(1) var<storage, read_write> ql: array<u32>;
+@group(0) @binding(2) var<storage, read_write> qh: array<u32>;
+@group(0) @binding(3) var<storage, read_write> sc: array<u32>;
+@group(0) @binding(4) var<storage, read_write> dd: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+fn byteAt(i: u32) -> u32 { return (raw[i >> 2u] >> ((i & 3u) * 8u)) & 0xffu; }
+fn wordAt(i: u32) -> u32 { return byteAt(i) | (byteAt(i + 1u) << 8u) | (byteAt(i + 2u) << 16u) | (byteAt(i + 3u) << 24u); }
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>) {
+  let b = g.y * ng.x * 256u + g.x; if (b >= p.blocks) { return; }
+  let o = b * 210u;
+  for (var i = 0u; i < 32u; i++) { ql[b * 32u + i] = wordAt(o + 4u * i); }
+  for (var i = 0u; i < 16u; i++) { qh[b * 16u + i] = wordAt(o + 128u + 4u * i); }
+  for (var i = 0u; i < 4u; i++) { sc[b * 4u + i] = wordAt(o + 192u + 4u * i); }
+  dd[b] = unpack2x16float(byteAt(o + 208u) | (byteAt(o + 209u) << 8u)).x;
+}`,
+  embedQ6K: `
+${TOK}
+struct P { n: u32, nb: u32, scale: f32 }
+${Q6P}
+@group(0) @binding(4) var<storage, read_write> y: array<f32>;
+@group(0) @binding(5) var<uniform> tok: Tok;
+@group(0) @binding(6) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i >= p.n) { return; }
+  y[i] = q6v(tok.token * p.nb + (i >> 8u), i & 255u) * p.scale;
+}`,
+  // Logits over the Q6_K planes: 4 rows per 256-thread workgroup, 64 threads per row; thread j takes quad j
+  // (4 consecutive values: one ql word, one qh word, one scale) of every block of the row.
+  matmulQ6K: `
+struct P { M: u32, N: u32 }
+${Q6P}
+@group(0) @binding(4) var<storage, read> x: array<vec4<f32>>;
+@group(0) @binding(5) var<storage, read_write> y: array<f32>;
+@group(0) @binding(6) var<uniform> p: P;
+var<workgroup> part: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let j = l.x & 63u; let m = (wg.y * ng.x + wg.x) * 4u + (l.x >> 6u); let mr = min(m, p.M - 1u);
+  let nb = p.N / 256u; let n = j >> 5u; let w = j & 31u; let qd = w >> 3u; let k = w & 7u;
+  var acc = 0.0;
+  for (var bb = 0u; bb < nb; bb++) {
+    let bi = mr * nb + bb;
+    let lo = unpack4xU8(ql[bi * 32u + n * 16u + (qd & 1u) * 8u + k]);
+    let q4 = select(lo & vec4<u32>(15u), lo >> vec4<u32>(4u), qd >= 2u);
+    let h = (unpack4xU8(qh[bi * 16u + n * 8u + k]) >> vec4<u32>(qd * 2u)) & vec4<u32>(3u);
+    let q = vec4<f32>(vec4<i32>(q4 | (h << vec4<u32>(4u))) - vec4<i32>(32));
+    acc += (dd[bi] * sc8(bi, n * 8u + (k >> 2u) + qd * 2u)) * dot(q, x[bb * 64u + j]);
+  }
+  part[l.x] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (j < s) { part[l.x] += part[l.x + s]; } workgroupBarrier(); }
+  if (j == 0u && m < p.M) { y[m] = part[l.x]; }
+}`,
+  // Dense Q4_0 GEMV, 4 output rows per workgroup (2-D dispatch ok).
+  matmulQ4: `enable f16;
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> xin: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+${Q4DOT}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let M = p.M; let nw = p.N / 8u; let nb = p.N / 32u;
+  if (m0 >= M) { return; }
+  let r0 = min(m0, M - 1u); let r1 = min(m0 + 1u, M - 1u); let r2 = min(m0 + 2u, M - 1u); let r3 = min(m0 + 3u, M - 1u);
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var w = t; w < nw; w += 256u) {
+    let b = w >> 2u; let xb = b * 32u + (w & 3u) * 4u;
+    a0 += q4dot(qw[r0 * nw + w], f32(qs[r0 * nb + b]), xb);
+    a1 += q4dot(qw[r1 * nw + w], f32(qs[r1 * nb + b]), xb);
+    a2 += q4dot(qw[r2 * nw + w], f32(qs[r2 * nb + b]), xb);
+    a3 += q4dot(qw[r3 * nw + w], f32(qs[r3 * nb + b]), xb);
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[m0 + t] = part[t * 256u]; }
+}`,
+  // Routed experts, all k at once (workgroup z = top-k position); slots[z] picks the expert's rows in the pool.
+  expertQ4: `enable f16;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputPerSlot: u32 }
+@group(0) @binding(0) var<storage, read> xin: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+${Q4DOT}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let M = p.M; let nw = p.N / 8u; let nb = p.N / 32u;
+  if (m0 >= M) { return; }
+  let rb = slots[z] * p.rowsPerExpert;
+  let xo = select(0u, z * p.N, p.inputPerSlot == 1u);
+  let r0 = rb + min(m0, M - 1u); let r1 = rb + min(m0 + 1u, M - 1u); let r2 = rb + min(m0 + 2u, M - 1u); let r3 = rb + min(m0 + 3u, M - 1u);
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var w = t; w < nw; w += 256u) {
+    let b = w >> 2u; let xb = xo + b * 32u + (w & 3u) * 4u;
+    a0 += q4dot(qw[r0 * nw + w], f32(qs[r0 * nb + b]), xb);
+    a1 += q4dot(qw[r1 * nw + w], f32(qs[r1 * nb + b]), xb);
+    a2 += q4dot(qw[r2 * nw + w], f32(qs[r2 * nb + b]), xb);
+    a3 += q4dot(qw[r3 * nw + w], f32(qs[r3 * nb + b]), xb);
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[z * M + m0 + t] = part[t * 256u]; }
+}`,
+  // gu = k × [gate F | up F] → act = k × F of GELU(gate)·up (ggml_geglu_split).
+  geglu: `
+struct P { F: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> gu: array<f32>;
+@group(0) @binding(1) var<storage, read_write> act: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+${GELU}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i >= p.k * p.F) { return; }
+  let z = i / p.F; let j = i % p.F;
+  act[i] = gelu(gu[z * 2u * p.F + j]) * gu[z * 2u * p.F + p.F + j];
+}`,
+  // Per-head RMS norm without a weight (V), from x into y. One workgroup per head.
+  vNorm: `
+struct P { hd: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read_write> y: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let base = wg.x * p.hd; let t = l.x;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = x[base + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < p.hd; i += 64u) { y[base + i] = x[base + i] * scale; }
+}`,
+  // y = ((x · rms) · k) · w — the router's input (k = 1/√H, w = ffn_gate_inp.scale).
+  rmsnormK: `
+struct P { n: u32, eps: f32, k: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = x[i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { y[i] = ((x[i] * scale) * p.k) * w[i]; }
+}`,
+  // x += rms_norm(y) · w — the post-attention norm and the residual add.
+  rmsnormAdd: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> y: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> x: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = y[i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { x[i] = (y[i] * scale) * w[i] + x[i]; }
+}`,
+  // x = (rms_norm(mlp + moe) · w + x) · out_scale — the FFN's last norm, the residual add, the layer scalar.
+  postFfn: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> mlp: array<f32>;
+@group(0) @binding(1) var<storage, read> moe: array<f32>;
+@group(0) @binding(2) var<storage, read> w: array<f32>;
+@group(0) @binding(3) var<storage, read> os: array<f32>;
+@group(0) @binding(4) var<storage, read_write> x: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = mlp[i] + moe[i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  let k = os[0];
+  for (var i = t; i < p.n; i += 256u) { x[i] = (((mlp[i] + moe[i]) * scale) * w[i] + x[i]) * k; }
+}`,
+  // moe[h] = Σ_j (dn[j·H + h] · ds[id_j]) · w_j, added in pick order (llama.cpp: down · scale · weight, then e0 + e1 + …).
+  moeSum: `
+struct P { H: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> dn: array<f32>;
+@group(0) @binding(1) var<storage, read> sel: array<u32>;
+@group(0) @binding(2) var<storage, read> ds: array<f32>;
+@group(0) @binding(3) var<storage, read_write> moe: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let h = g.x; if (h >= p.H) { return; }
+  var acc = (dn[h] * ds[sel[0]]) * bitcast<f32>(sel[p.k]);
+  for (var j = 1u; j < p.k; j++) { acc = acc + (dn[j * p.H + h] * ds[sel[j]]) * bitcast<f32>(sel[p.k + j]); }
+  moe[h] = acc;
+}`,
+  // Attention with a window: scores, softmax and the weighted sum over positions [start, seqLen); scale 1.0.
+  attnScoreW: `enable f16;
+${TOK}
+struct P { heads: u32, kvHeads: u32, hd: u32, win: u32 }
+@group(0) @binding(0) var<storage, read> q: array<f32>;
+@group(0) @binding(1) var<storage, read> kc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(3) var<uniform> tok: Tok;
+@group(0) @binding(4) var<uniform> p: P;
+${WIN}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let st = winStart(tok.seqLen, p.win); let n = tok.seqLen - st; let idx = g.x;
+  if (idx >= p.heads * n) { return; }
+  let h = idx / n; let j = idx % n; let kvh = h / (p.heads / p.kvHeads);
+  let qo = h * p.hd; let ko = (st + j) * p.kvHeads * p.hd + kvh * p.hd;
+  var acc = 0.0;
+  for (var d = 0u; d < p.hd; d++) { acc += q[qo + d] * f32(kc[ko + d]); }
+  sc[h * n + j] = acc;
+}`,
+  softmaxW: `
+${TOK}
+struct P { heads: u32, kvHeads: u32, hd: u32, win: u32 }
+@group(0) @binding(0) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(1) var<uniform> tok: Tok;
+@group(0) @binding(2) var<uniform> p: P;
+${WIN}
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let n = tok.seqLen - winStart(tok.seqLen, p.win); let base = wg.x * n; let t = l.x;
+  var mx = -3.4e38;
+  for (var i = t; i < n; i += 256u) { mx = max(mx, sc[base + i]); }
+  red[t] = mx; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] = max(red[t], red[t + s]); } workgroupBarrier(); }
+  let m = red[0]; workgroupBarrier();
+  var sum = 0.0;
+  for (var i = t; i < n; i += 256u) { let e = exp(sc[base + i] - m); sc[base + i] = e; sum += e; }
+  red[t] = sum; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let inv = 1.0 / red[0];
+  for (var i = t; i < n; i += 256u) { sc[base + i] = sc[base + i] * inv; }
+}`,
+  attnOutW: `enable f16;
+${TOK}
+struct P { heads: u32, kvHeads: u32, hd: u32, win: u32 }
+@group(0) @binding(0) var<storage, read> pr: array<f32>;
+@group(0) @binding(1) var<storage, read> vc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> tok: Tok;
+@group(0) @binding(4) var<uniform> p: P;
+${WIN}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let idx = g.x; if (idx >= p.heads * p.hd) { return; }
+  let st = winStart(tok.seqLen, p.win); let n = tok.seqLen - st;
+  let h = idx / p.hd; let d = idx % p.hd; let kvh = h / (p.heads / p.kvHeads);
+  let stride = p.kvHeads * p.hd;
+  var acc = 0.0;
+  for (var j = 0u; j < n; j++) { acc += pr[h * n + j] * f32(vc[(st + j) * stride + kvh * p.hd + d]); }
+  y[idx] = acc;
+}`,
+  // Final logit soft cap, in place: l = tanh(l · (1/cap)) · cap.
+  softcap: `
+struct P { n: u32, inv: f32, cap: f32 }
+@group(0) @binding(0) var<storage, read_write> lg: array<f32>;
+@group(0) @binding(1) var<uniform> p: P;
+${TANH}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>) {
+  let i = g.y * ng.x * 256u + g.x; if (i >= p.n) { return; }
+  lg[i] = tanhc(lg[i] * p.inv) * p.cap;
+}`,
+  // Debug capture: y[off + i] = x[i].
+  copyAt: `
+struct P { n: u32, off: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read_write> y: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i < p.n) { y[p.off + i] = x[i]; }
+}`,
+};
+
+// ── Subgroup Q4_0 GEMVs (decode) ─────────────────────────────────────────────────
+// One 32-lane subgroup per output row, 4 rows per 128-thread workgroup (the scalar kernels' dispatch
+// geometry). A lane takes whole blocks: one vec4<u32> of nibbles, unpack4xU8 of the low and high nibble
+// masks, vec4 dot products against the activations, the block scale once; subgroupAdd reduces the row.
+// Used only when the adapter's subgroups are exactly 32 wide.
+const Q4BLK = `
+fn q4blk(w: vec4<u32>, xb: u32) -> f32 {
+  let m = 0x0f0f0f0fu;
+  return dot(vec4<f32>(unpack4xU8(w.x & m)) - 8.0, x[xb]) + dot(vec4<f32>(unpack4xU8((w.x >> 4u) & m)) - 8.0, x[xb + 4u])
+       + dot(vec4<f32>(unpack4xU8(w.y & m)) - 8.0, x[xb + 1u]) + dot(vec4<f32>(unpack4xU8((w.y >> 4u) & m)) - 8.0, x[xb + 5u])
+       + dot(vec4<f32>(unpack4xU8(w.z & m)) - 8.0, x[xb + 2u]) + dot(vec4<f32>(unpack4xU8((w.z >> 4u) & m)) - 8.0, x[xb + 6u])
+       + dot(vec4<f32>(unpack4xU8(w.w & m)) - 8.0, x[xb + 3u]) + dot(vec4<f32>(unpack4xU8((w.w >> 4u) & m)) - 8.0, x[xb + 7u]);
+}`;
+const G4SG = {
+  matmulQ4: `enable f16;
+enable subgroups;
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> x: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read> qw: array<vec4<u32>>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+${Q4BLK}
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m = (wg.y * ng.x + wg.x) * 4u + l.x / 32u; let lane = l.x % 32u;
+  let nb = p.N / 32u; let rb = min(m, p.M - 1u) * nb;
+  var acc = 0.0;
+  for (var b = lane; b < nb; b += 32u) { acc += q4blk(qw[rb + b], b * 8u) * f32(qs[rb + b]); }
+  let total = subgroupAdd(acc);
+  if (lane == 0u && m < p.M) { y[m] = total; }
+}`,
+  expertQ4: `enable f16;
+enable subgroups;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputPerSlot: u32 }
+@group(0) @binding(0) var<storage, read> x: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read> qw: array<vec4<u32>>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+${Q4BLK}
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m = (wg.y * ng.x + wg.x) * 4u + l.x / 32u; let lane = l.x % 32u;
+  let nb = p.N / 32u; let rb = (slots[z] * p.rowsPerExpert + min(m, p.M - 1u)) * nb;
+  let xo = select(0u, z * p.N / 4u, p.inputPerSlot == 1u);
+  var acc = 0.0;
+  for (var b = lane; b < nb; b += 32u) { acc += q4blk(qw[rb + b], xo + b * 8u) * f32(qs[rb + b]); }
+  let total = subgroupAdd(acc);
+  if (lane == 0u && m < p.M) { y[z * p.M + m] = total; }
+}`,
+};
+
+// ── Chunked prefill: T tokens per layer pass (rung 2b's pattern) ────────────────
+// Rows are tokens, token-major. Generic kernels come from rung 2b (rmsnormB, matmulF32T, topkB, kvStoreB,
+// softmaxB, attnOutB); these are Gemma's.
+const QB = 'struct Q { T: u32, pos0: u32, S: u32, pad: u32 }';
+const G4B = {
+  embedQ6KB: `
+struct P { n: u32, nb: u32, scale: f32 }
+${QB}
+${Q6P}
+@group(0) @binding(4) var<storage, read> ids: array<u32>;
+@group(0) @binding(5) var<storage, read_write> y: array<f32>;
+@group(0) @binding(6) var<uniform> p: P;
+@group(0) @binding(7) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; let t = g.y; if (i >= p.n || t >= qd.T) { return; }
+  y[t * p.n + i] = q6v(ids[t] * p.nb + (i >> 8u), i & 255u) * p.scale;
+}`,
+  // Tiled Q4_0 GEMM: y[t·M + m] = Σ_k x[t·N + k]·W[m][k]. 16 rows × 16 tokens per workgroup; each 32-wide
+  // block of W (decoded from its nibbles) and of x goes through shared memory, so a weight serves 16 tokens.
+  // Dispatch (ceil(M/16), ceil(T/16)).
+  matmulQ4T: `enable f16;
+struct P { M: u32, N: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+var<workgroup> ws: array<f32, 512>;
+var<workgroup> xs: array<f32, 512>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m0 = wg.x * 16u; let t0 = wg.y * 16u; let r = l.x / 16u; let c = l.x % 16u;
+  let nb = p.N / 32u; let nw = p.N / 8u; var acc = 0.0;
+  for (var b = 0u; b < nb; b++) {
+    for (var i = l.x; i < 512u; i += 256u) {
+      let rr = i / 32u; let kk = i % 32u;
+      let m = m0 + rr; var wv = 0.0;
+      if (m < p.M) {
+        let wd = qw[m * nw + b * 4u + ((kk & 15u) >> 2u)];
+        wv = (f32((wd >> ((kk & 3u) * 8u + (kk >> 4u) * 4u)) & 15u) - 8.0) * f32(qs[m * nb + b]);
+      }
+      ws[i] = wv;
+      let t = t0 + rr; var xv = 0.0;
+      if (t < qd.T) { xv = x[t * p.N + b * 32u + kk]; }
+      xs[i] = xv;
+    }
+    workgroupBarrier();
+    for (var kk = 0u; kk < 32u; kk++) { acc += ws[r * 32u + kk] * xs[c * 32u + kk]; }
+    workgroupBarrier();
+  }
+  let m = m0 + r; let t = t0 + c;
+  if (m < p.M && t < qd.T) { y[t * p.M + m] = acc; }
+}`,
+  // Routed experts for every (token, pick) pair: z = t·K + j, slots[z] its pool slot. Input: the token's row
+  // (gate/up, inputMode 0) or the pair's own row (down, inputMode 1).
+  expertQ4B: `enable f16;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputMode: u32, K: u32 }
+@group(0) @binding(0) var<storage, read> xin: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+${Q4DOT}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let M = p.M; let nw = p.N / 8u; let nb = p.N / 32u;
+  if (m0 >= M) { return; }
+  let rb = slots[z] * p.rowsPerExpert;
+  let xo = select((z / p.K) * p.N, z * p.N, p.inputMode == 1u);
+  let r0 = rb + min(m0, M - 1u); let r1 = rb + min(m0 + 1u, M - 1u); let r2 = rb + min(m0 + 2u, M - 1u); let r3 = rb + min(m0 + 3u, M - 1u);
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var w = t; w < nw; w += 256u) {
+    let b = w >> 2u; let xb = xo + b * 32u + (w & 3u) * 4u;
+    a0 += q4dot(qw[r0 * nw + w], f32(qs[r0 * nb + b]), xb);
+    a1 += q4dot(qw[r1 * nw + w], f32(qs[r1 * nb + b]), xb);
+    a2 += q4dot(qw[r2 * nw + w], f32(qs[r2 * nb + b]), xb);
+    a3 += q4dot(qw[r3 * nw + w], f32(qs[r3 * nb + b]), xb);
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[z * M + m0 + t] = part[t * 256u]; }
+}`,
+  // Per-head RMS norm and NeoX RoPE in place for (head wg.x, token wg.y); rope holds hd values per token.
+  qkNormRopeB: `
+struct P { hd: u32, row: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> rope: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let base = wg.y * p.row + wg.x * p.hd; let rb = wg.y * p.hd; let t = l.x; let half = p.hd / 2u;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = x[base + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < half; i += 64u) {
+    let a = (x[base + i] * scale) * w[i];
+    let b = (x[base + i + half] * scale) * w[i + half];
+    let c = rope[rb + i]; let sn = rope[rb + half + i];
+    x[base + i] = a * c - b * sn;
+    x[base + i + half] = a * sn + b * c;
+  }
+}`,
+  vNormB: `
+struct P { hd: u32, row: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read_write> y: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let base = wg.y * p.row + wg.x * p.hd; let t = l.x;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = x[base + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < p.hd; i += 64u) { y[base + i] = x[base + i] * scale; }
+}`,
+  // Causal (and, on sliding layers, windowed) scores for T queries over S = pos0 + T keys; scale 1.0.
+  attnScoreWB: `enable f16;
+struct P { heads: u32, kvHeads: u32, hd: u32, win: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> q: array<f32>;
+@group(0) @binding(1) var<storage, read> kc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@group(0) @binding(4) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>) {
+  let idx = g.y * ng.x * 256u + g.x; let S = qd.S; let T = qd.T;
+  if (idx >= p.heads * T * S) { return; }
+  let h = idx / (T * S); let rem = idx % (T * S); let t = rem / S; let pos = rem % S; let qp = qd.pos0 + t;
+  if (pos > qp || (p.win > 0u && qp - pos >= p.win)) { sc[idx] = -3.4e38; return; }
+  let kvh = h / (p.heads / p.kvHeads);
+  let qo = t * p.heads * p.hd + h * p.hd; let ko = pos * p.kvHeads * p.hd + kvh * p.hd;
+  var acc = 0.0;
+  for (var d = 0u; d < p.hd; d++) { acc += q[qo + d] * f32(kc[ko + d]); }
+  sc[idx] = acc;
+}`,
+  // x += rms_norm(y) · w per token row (one workgroup per token).
+  rmsnormAddB: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> y: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> x: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let b = wg.x * p.n; let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = y[b + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { x[b + i] = (y[b + i] * scale) * w[i] + x[b + i]; }
+}`,
+  rmsnormKB: `
+struct P { n: u32, eps: f32, k: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let b = wg.x * p.n; let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = x[b + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { y[b + i] = ((x[b + i] * scale) * p.k) * w[i]; }
+}`,
+  // act = GELU(g) · u over T × n (the dense MLP's separate gate and up).
+  gegluSplitB: `
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> g: array<f32>;
+@group(0) @binding(1) var<storage, read> u: array<f32>;
+@group(0) @binding(2) var<storage, read_write> act: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@group(0) @binding(4) var<uniform> qd: Q;
+${GELU}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let i = gi.x; let t = gi.y; if (i >= p.n || t >= qd.T) { return; }
+  let k = t * p.n + i; act[k] = gelu(g[k]) * u[k];
+}`,
+  moeSumB: `
+struct P { H: u32, k: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> dn: array<f32>;
+@group(0) @binding(1) var<storage, read> sel: array<u32>;
+@group(0) @binding(2) var<storage, read> ds: array<f32>;
+@group(0) @binding(3) var<storage, read_write> moe: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let h = gi.x; let t = gi.y; if (h >= p.H || t >= qd.T) { return; }
+  let sb = t * 2u * p.k; let ob = t * p.k * p.H + h;
+  var acc = (dn[ob] * ds[sel[sb]]) * bitcast<f32>(sel[sb + p.k]);
+  for (var j = 1u; j < p.k; j++) { acc = acc + (dn[ob + j * p.H] * ds[sel[sb + j]]) * bitcast<f32>(sel[sb + p.k + j]); }
+  moe[t * p.H + h] = acc;
+}`,
+  postFfnB: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> mlp: array<f32>;
+@group(0) @binding(1) var<storage, read> moe: array<f32>;
+@group(0) @binding(2) var<storage, read> w: array<f32>;
+@group(0) @binding(3) var<storage, read> os: array<f32>;
+@group(0) @binding(4) var<storage, read_write> x: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let b = wg.x * p.n; let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = mlp[b + i] + moe[b + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  let k = os[0];
+  for (var i = t; i < p.n; i += 256u) { x[b + i] = (((mlp[b + i] + moe[b + i]) * scale) * w[i] + x[b + i]) * k; }
+}`,
+};
+const REUSED_B = ['rmsnormB', 'matmulF32T', 'topkB', 'kvStoreB', 'softmaxB', 'attnOutB'];
+
+// ── Engine ──────────────────────────────────────────────────────────────────
+export class Gemma4MoeSsd extends Qwen3MoeSsd {
+  static configFrom(kv) { return configFromGgufGemma4(kv); }
+  static get ingestPlan() { return GEMMA4_INGEST_PLAN; }
+  static tokenizerFrom(kv) { return new GemmaTokenizer(kv); }
+  static load(modelId, opts = {}) { return super.load(modelId, { ...opts, source: opts.source || GEMMA4_26B_A4B }); }
+
+  chatPrompt(messages, opts) { return gemmaChatPrompt(messages, opts); }
+  get stopTokenIds() { return [this.cfg.eos, this.tokenizer.ids.get('<turn|>')].filter((t) => t !== undefined); }
+  // Thinking: the model writes <|channel>thought\n … <channel|> itself (nothing opens it in the prompt).
+  get thinkOpenTokenId() { return this.tokenizer.ids.get('<|channel>') ?? null; }
+  get thinkCloseTokenId() { return this.tokenizer.ids.get('<channel|>') ?? null; }
+  get thinkInPrompt() { return false; }
+  get thinkPreamble() { return 'thought\n'; }
+
+  get kernels() {
+    return (this._kernels ||= {
+      ...super.kernels, ...G4, ...(this.subgroupKernels ? G4SG : {}),
+      ...(this.batchPrefill ? { ...Object.fromEntries(REUSED_B.map((k) => [k, QWEN35_BATCH_KERNELS[k]])), ...G4B } : {}),
+    });
+  }
+  // Subgroup GEMVs replace the scalar Q4_0 ones when subgroups are exactly 32 wide (Apple, most others).
+  get subgroupKernels() {
+    const i = this.device.adapterInfo || this.opts.adapterInfo || {};
+    return this.opts.subgroups !== false && this.device.features.has('subgroups') && i.subgroupMinSize === 32 && i.subgroupMaxSize === 32;
+  }
+
+  // batchPrefill (default on): prompts go through in chunks of up to prefillChunk tokens, one routing
+  // readback per layer per chunk. capture (debug) records one-token steps, so it turns chunking off.
+  constructor(device, manifest, gguf, opts) {
+    super(device, manifest, gguf, opts);
+    this.batchPrefill = (opts.batchPrefill ?? true) && !opts.capture;
+    this.chunkTokens = Math.max(2, Math.floor(opts.prefillChunk || 256));
+  }
+
+  // A bind group whose entries are buffers or { buffer, offset, size } ranges.
+  bindR(name, entries) {
+    return this.device.createBindGroup({
+      layout: this.pipeline(name).getBindGroupLayout(0),
+      entries: entries.map((e, i) => ({ binding: i, resource: e.buffer ? e : { buffer: e } })),
+    });
+  }
+
+  // Dense upload; the Q6_K token table split into aligned planes on the GPU (the raw copy is then freed);
+  // the full-attention layers' RoPE frequency factors on the CPU side.
+  async uploadDense(onProgress) {
+    await super.uploadDense(onProgress);
+    const dev = this.device, raw = this.w['token_embd.weight'].raw, blocks = raw.size / Q6K_BLOCK | 0;
+    const P = (n) => this.buffer(n, STORAGE, 'dense');
+    this.q6 = { ql: P(blocks * 128), qh: P(blocks * 64), sc: P(blocks * 16), dd: P(blocks * 4) };
+    const enc = dev.createCommandEncoder(), pass = enc.beginComputePass();
+    this.dispatch(pass, 'q6kPlanes', this.bind('q6kPlanes', [raw, this.q6.ql, this.q6.qh, this.q6.sc, this.q6.dd, this.uniform([blocks])]), Math.ceil(blocks / 256));
+    pass.end(); dev.queue.submit([enc.finish()]);
+    await dev.queue.onSubmittedWorkDone();
+    this.gpuBytes.dense -= raw.size; raw.destroy(); this.w['token_embd.weight'].raw = null;
+    const d = this.manifest.dense.tensors['rope_freqs.weight'];
+    this.ropeFreqs = null;
+    if (d) {
+      const r = await OpfsReaderPool.open(`${this.opts.dir}/${this.manifest.dense.file}`, { workers: 1 });
+      const got = await r.read(d.raw.off, d.raw.bytes);
+      this.ropeFreqs = new Float32Array(got.buf.slice(0, d.raw.bytes));
+      await r.close();
+    }
+  }
+
+  initBuffers() {
+    const c = this.cfg, H = c.hidden, K = c.topK, E = c.experts, F = c.expertFf, DF = c.denseFf, Lc = c.layers;
+    if (2 * K * 4 > 256) throw new Error(`top-k ${K} > 32`);
+    if (E > 256) throw new Error(`${E} experts: the router top-k kernel handles at most 256`);
+    const kvn = (l) => c.kvHeads[l] * c.headDim[l], qn = (l) => c.heads * c.headDim[l];
+    const QN = Math.max(...c.headDim.map((d) => c.heads * d)), KVN = Math.max(...c.headDim.map((_, l) => kvn(l)));
+    const HD = Math.max(...c.headDim);
+    this.kc = []; this.vc = [];
+    for (let l = 0; l < Lc; l++) {
+      this.kc.push(this.buffer(this.maxCtx * kvn(l) * 2, STORAGE, 'kv'));
+      this.vc.push(this.buffer(this.maxCtx * kvn(l) * 2, STORAGE, 'kv'));
+    }
+    const A = (n) => this.buffer(n * 4, STORAGE | COPY_SRC | COPY_DST);
+    const gateBytes = DF * 4;
+    if (gateBytes % 256) throw new Error(`dense FFN ${DF}: gate/up halves must sit on 256-byte offsets`);
+    this.a = {
+      x: A(H), xn: A(H), q: A(QN), k: A(KVN), v: A(KVN), vr: A(KVN), att: A(QN), o: A(H), sc: A(c.heads * this.maxCtx),
+      mgu: A(2 * DF), ma: A(DF), md: A(H), mlp: A(H), xm: A(H), rt: A(H), moe: A(H), moe2: A(H),
+      rl: A(E), sel: A(2 * K), prt: A(H), prl: A(E), psel: A(64 * this.lookahead), slots: A(K),
+      gu: A(K * 2 * F), act: A(K * F), dn: A(K * H), logits: A(c.vocab), am: A(4),
+      ropeS: A(HD), ropeF: A(HD),
+    };
+    if (this.opts.capture) this.a.cap = A(2 * Lc * H);
+    this.tok = this.buffer(16, 0x40 | COPY_DST);
+    this.rbSel = this.buffer(256 * (1 + this.lookahead), MAP_READ | COPY_DST);
+    this.rbLogits = this.buffer(c.vocab * 4, MAP_READ | COPY_DST);
+    this.rbArg = this.buffer(16, MAP_READ | COPY_DST);
+
+    const f = (v) => ({ f: v });
+    const eps = f(c.eps);
+    const u = {
+      embed: this.uniform([H, H / 256, f(Math.fround(Math.sqrt(H)))]),
+      rmsH: this.uniform([H, eps]), routerK: this.uniform([H, eps, f(Math.fround(1 / Math.fround(Math.sqrt(H))))]),
+      mmG: this.uniform([DF, H]), mmD: this.uniform([H, DF]), gegluD: this.uniform([DF, 1]),
+      router: this.uniform([E, H]), topk: this.uniform([E, K]),
+      gu: this.uniform([2 * F, H, 2 * F, 0]), dn: this.uniform([H, F, H, 1]), gegluE: this.uniform([F, K]), sum: this.uniform([H, K]),
+      lm: this.uniform([c.vocab, H]), cap: this.uniform([c.vocab, f(Math.fround(1 / c.softcap)), f(c.softcap)]), am: this.uniform([c.vocab]),
+    };
+    // Attention uniforms per layer shape (sliding / full).
+    const shape = new Map();
+    const shapeOf = (l) => {
+      const key = `${c.headDim[l]}/${c.kvHeads[l]}/${c.swa[l]}`;
+      if (!shape.has(key)) shape.set(key, {
+        mmQ: this.uniform([qn(l), H]), mmKV: this.uniform([kvn(l), H]), mmO: this.uniform([H, qn(l)]),
+        hd: this.uniform([c.headDim[l], eps]), kvn: this.uniform([kvn(l)]),
+        att: this.uniform([c.heads, c.kvHeads[l], c.headDim[l], c.swa[l] ? c.window : 0]),
+      });
+      return shape.get(key);
+    };
+    const a = this.a, W = this.w;
+    const q6 = [this.q6.ql, this.q6.qh, this.q6.sc, this.q6.dd];
+    this.g = { embed: this.bind('embedQ6K', [...q6, a.x, this.tok, u.embed]) };
+    this.layers = [];
+    for (let l = 0; l < Lc; l++) {
+      const p = (n) => W[`blk.${l}.${n}`], s = shapeOf(l), rope = c.swa[l] ? a.ropeS : a.ropeF;
+      const hasV = !!p('attn_v.weight');
+      const ly = {
+        swa: c.swa[l], hasV,
+        rmsA: this.bind('rmsnorm', [a.x, p('attn_norm.weight').raw, a.xn, u.rmsH]),
+        q: this.bind('matmulQ4', [a.xn, p('attn_q.weight').q, p('attn_q.weight').s, a.q, s.mmQ]),
+        k: this.bind('matmulQ4', [a.xn, p('attn_k.weight').q, p('attn_k.weight').s, a.k, s.mmKV]),
+        v: hasV ? this.bind('matmulQ4', [a.xn, p('attn_v.weight').q, p('attn_v.weight').s, a.vr, s.mmKV]) : null,
+        vn: this.bind('vNorm', [hasV ? a.vr : a.k, a.v, s.hd]),   // no V projection: V is K's projection
+        ropeQ: this.bind('qkNormRope', [a.q, p('attn_q_norm.weight').raw, rope, s.hd]),
+        ropeK: this.bind('qkNormRope', [a.k, p('attn_k_norm.weight').raw, rope, s.hd]),
+        kv: this.bind('kvStore', [a.k, a.v, this.kc[l], this.vc[l], this.tok, s.kvn]),
+        score: this.bind('attnScoreW', [a.q, this.kc[l], a.sc, this.tok, s.att]),
+        soft: this.bind('softmaxW', [a.sc, this.tok, s.att]),
+        attOut: this.bind('attnOutW', [a.sc, this.vc[l], a.att, this.tok, s.att]),
+        o: this.bind('matmulQ4', [a.att, p('attn_output.weight').q, p('attn_output.weight').s, a.o, s.mmO]),
+        postA: this.bind('rmsnormAdd', [a.o, p('post_attention_norm.weight').raw, a.x, u.rmsH]),
+        rmsF: this.bind('rmsnorm', [a.x, p('ffn_norm.weight').raw, a.xn, u.rmsH]),
+        mg: this.bindR('matmulQ4', [a.xn, p('ffn_gate.weight').q, p('ffn_gate.weight').s, { buffer: a.mgu, offset: 0, size: gateBytes }, u.mmG]),
+        mu: this.bindR('matmulQ4', [a.xn, p('ffn_up.weight').q, p('ffn_up.weight').s, { buffer: a.mgu, offset: gateBytes, size: gateBytes }, u.mmG]),
+        mact: this.bind('geglu', [a.mgu, a.ma, u.gegluD]),
+        md: this.bind('matmulQ4', [a.ma, p('ffn_down.weight').q, p('ffn_down.weight').s, a.md, u.mmD]),
+        mpost: this.bind('rmsnorm', [a.md, p('post_ffw_norm_1.weight').raw, a.mlp, u.rmsH]),
+        xm: this.bind('rmsnorm', [a.x, p('pre_ffw_norm_2.weight').raw, a.xm, u.rmsH]),
+        rp: this.bind('rmsnormK', [a.x, p('ffn_gate_inp.scale').raw, a.rt, u.routerK]),
+        router: this.bind('matmulF32', [a.rt, p('ffn_gate_inp.weight').raw, a.rl, u.router]),
+        topk: this.bind('topk', [a.rl, a.sel, u.topk]),
+        // Routers of layers l+1..l+lookahead on this layer's post-attention state: the prefetch guesses.
+        pf: Array.from({ length: Math.min(this.lookahead, Lc - 1 - l) }, (_, i) => {
+          const at = (n) => W[`blk.${l + 1 + i}.${n}`];
+          return {
+            rp: this.bind('rmsnormK', [a.x, at('ffn_gate_inp.scale').raw, a.prt, u.routerK]),
+            router: this.bind('matmulF32', [a.prt, at('ffn_gate_inp.weight').raw, a.prl, u.router]),
+            topk: this.bindR('topk', [a.prl, { buffer: a.psel, offset: 256 * i, size: 8 * K }, u.topk]),
+          };
+        }),
+        gu: this.bind('expertQ4', [a.xm, this.pool.guQ, this.pool.guS, a.gu, u.gu, a.slots]),
+        act: this.bind('geglu', [a.gu, a.act, u.gegluE]),
+        dn: this.bind('expertQ4', [a.act, this.pool.dQ, this.pool.dS, a.dn, u.dn, a.slots]),
+        sum: this.bind('moeSum', [a.dn, a.sel, p('ffn_down_exps.scale').raw, a.moe, u.sum]),
+        mpost2: this.bind('rmsnorm', [a.moe, p('post_ffw_norm_2.weight').raw, a.moe2, u.rmsH]),
+        post: this.bind('postFfn', [a.mlp, a.moe2, p('post_ffw_norm.weight').raw, p('layer_output_scale.weight').raw, a.x, u.rmsH]),
+      };
+      if (a.cap) {
+        ly.capA = this.bind('copyAt', [a.x, a.cap, this.uniform([H, l * H])]);
+        ly.capX = this.bind('copyAt', [a.x, a.cap, this.uniform([H, (Lc + l) * H])]);
+      }
+      this.layers.push(ly);
+    }
+    this.g.rmsOut = this.bind('rmsnorm', [a.x, W['output_norm.weight'].raw, a.xn, u.rmsH]);
+    this.g.lm = this.bind('matmulQ6K', [...q6, a.xn, a.logits, u.lm]);
+    this.g.cap = this.bind('softcap', [a.logits, u.cap]);
+    this.g.am = this.bind('argmax', [a.logits, a.am, u.am]);
+    // A chunk pins min(experts, T·K) experts per layer at once; keep that under half the pool.
+    if (Math.min(c.experts, this.chunkTokens * c.topK) > this.poolSlots / 2) this.chunkTokens = Math.max(2, Math.floor(this.poolSlots / 2 / c.topK));
+    if (this.batchPrefill) this.initBatch();
+  }
+
+  // Buffers and bind groups for chunked prefill (rows = the chunk's tokens).
+  initBatch() {
+    const c = this.cfg, B = this.chunkTokens, W = this.w, H = c.hidden, K = c.topK, E = c.experts, F = c.expertFf, DF = c.denseFf;
+    const QN = Math.max(...c.headDim.map((d) => c.heads * d)), KVN = Math.max(...c.headDim.map((d, l) => c.kvHeads[l] * d)), HD = Math.max(...c.headDim);
+    const A = (n) => this.buffer(n * 4, STORAGE | COPY_SRC | COPY_DST, 'batch');
+    const b = this.b = {
+      ids: A(B), x: A(B * H), xn: A(B * H), q: A(B * QN), k: A(B * KVN), v: A(B * KVN), vr: A(B * KVN), att: A(B * QN), o: A(B * H),
+      sc: A(c.heads * B * this.maxCtx), mg: A(B * DF), mu: A(B * DF), ma: A(B * DF), md: A(B * H), mlp: A(B * H), xm: A(B * H), rt: A(B * H),
+      rl: A(B * E), sel: A(B * 2 * K), slots: A(B * K), gu: A(B * K * 2 * F), act: A(B * K * F), dn: A(B * K * H), moe: A(B * H), moe2: A(B * H),
+      ropeS: A(B * HD), ropeF: A(B * HD),
+    };
+    this.qb = this.buffer(16, 0x40 | COPY_DST, 'batch');
+    this.rbSelB = this.buffer(B * 2 * K * 4, MAP_READ | COPY_DST, 'batch');
+    const U = (w) => this.uniform(w), eps = { f: c.eps }, qb = this.qb;
+    const u = {
+      embed: U([H, H / 256, { f: Math.fround(Math.sqrt(H)) }]), rmsH: U([H, eps]),
+      routerK: U([H, eps, { f: Math.fround(1 / Math.fround(Math.sqrt(H))) }]), router: U([E, H]), topk: U([E, K]),
+      mg: U([DF, H]), md: U([H, DF]), geglu: U([DF]), gu: U([2 * F, H, 2 * F, 0, K]), dn: U([H, F, H, 1, K]), gegluE: U([F, B * K]), sum: U([H, K]),
+    };
+    const shape = new Map();
+    const shapeOf = (l) => {
+      const hd = c.headDim[l], qn = c.heads * hd, kvn = c.kvHeads[l] * hd, key = `${hd}/${c.kvHeads[l]}/${c.swa[l]}`;
+      if (!shape.has(key)) shape.set(key, {
+        q: U([qn, H]), kv: U([kvn, H]), o: U([H, qn]), ropeQ: U([hd, qn, eps]), ropeK: U([hd, kvn, eps]), kvn: U([kvn]),
+        att: U([c.heads, c.kvHeads[l], hd, c.swa[l] ? c.window : 0]),
+      });
+      return shape.get(key);
+    };
+    const q4 = (name, x, y, uni) => this.bind('matmulQ4T', [x, W[name].q, W[name].s, y, uni, qb]);
+    this.gB = { embed: this.bind('embedQ6KB', [this.q6.ql, this.q6.qh, this.q6.sc, this.q6.dd, b.ids, b.x, u.embed, qb]) };
+    for (let l = 0; l < c.layers; l++) {
+      const n = (t) => `blk.${l}.${t}`, raw = (t) => W[n(t)].raw, sh = shapeOf(l), hasV = !!W[n('attn_v.weight')];
+      const rope = c.swa[l] ? b.ropeS : b.ropeF;
+      this.layers[l].B = {
+        rmsA: this.bind('rmsnormB', [b.x, raw('attn_norm.weight'), b.xn, u.rmsH]),
+        q: q4(n('attn_q.weight'), b.xn, b.q, sh.q), k: q4(n('attn_k.weight'), b.xn, b.k, sh.kv),
+        v: hasV ? q4(n('attn_v.weight'), b.xn, b.vr, sh.kv) : null,
+        vn: this.bind('vNormB', [hasV ? b.vr : b.k, b.v, sh.ropeK]),
+        ropeQ: this.bind('qkNormRopeB', [b.q, raw('attn_q_norm.weight'), rope, sh.ropeQ]),
+        ropeK: this.bind('qkNormRopeB', [b.k, raw('attn_k_norm.weight'), rope, sh.ropeK]),
+        kv: this.bind('kvStoreB', [b.k, b.v, this.kc[l], this.vc[l], sh.kvn, qb]),
+        score: this.bind('attnScoreWB', [b.q, this.kc[l], b.sc, sh.att, qb]),
+        soft: this.bind('softmaxB', [b.sc, qb]),
+        attOut: this.bind('attnOutB', [b.sc, this.vc[l], b.att, sh.att, qb]),
+        o: q4(n('attn_output.weight'), b.att, b.o, sh.o),
+        postA: this.bind('rmsnormAddB', [b.o, raw('post_attention_norm.weight'), b.x, u.rmsH]),
+        rmsF: this.bind('rmsnormB', [b.x, raw('ffn_norm.weight'), b.xn, u.rmsH]),
+        mg: q4(n('ffn_gate.weight'), b.xn, b.mg, u.mg), mu: q4(n('ffn_up.weight'), b.xn, b.mu, u.mg),
+        mact: this.bind('gegluSplitB', [b.mg, b.mu, b.ma, u.geglu, qb]),
+        md: q4(n('ffn_down.weight'), b.ma, b.md, u.md),
+        mpost: this.bind('rmsnormB', [b.md, raw('post_ffw_norm_1.weight'), b.mlp, u.rmsH]),
+        xm: this.bind('rmsnormB', [b.x, raw('pre_ffw_norm_2.weight'), b.xm, u.rmsH]),
+        rp: this.bind('rmsnormKB', [b.x, raw('ffn_gate_inp.scale'), b.rt, u.routerK]),
+        router: this.bind('matmulF32T', [b.rt, raw('ffn_gate_inp.weight'), b.rl, u.router]),
+        topk: this.bind('topkB', [b.rl, b.sel, u.topk]),
+        gu: this.bind('expertQ4B', [b.xm, this.pool.guQ, this.pool.guS, b.gu, u.gu, b.slots]),
+        act: this.bind('geglu', [b.gu, b.act, u.gegluE]),
+        dn: this.bind('expertQ4B', [b.act, this.pool.dQ, this.pool.dS, b.dn, u.dn, b.slots]),
+        sum: this.bind('moeSumB', [b.dn, b.sel, raw('ffn_down_exps.scale'), b.moe, u.sum, qb]),
+        mpost2: this.bind('rmsnormB', [b.moe, raw('post_ffw_norm_2.weight'), b.moe2, u.rmsH]),
+        post: this.bind('postFfnB', [b.mlp, b.moe2, raw('post_ffw_norm.weight'), raw('layer_output_scale.weight'), b.x, u.rmsH]),
+      };
+    }
+  }
+
+  // Layer l over the chunk's T tokens up to its routing (the batched twin of encodeAttention).
+  encodeTrunkB(pass, l, T, S) {
+    const c = this.cfg, g = this.layers[l].B, d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    const H = c.hidden, hd = c.headDim[l], QN = c.heads * hd, kvn = c.kvHeads[l] * hd, DF = c.denseFf;
+    const tt = Math.ceil(T / 16), mm = (n) => Math.ceil(n / 16);
+    d('rmsnormB', g.rmsA, T);
+    d('matmulQ4T', g.q, mm(QN), tt); d('matmulQ4T', g.k, mm(kvn), tt);
+    if (g.v) d('matmulQ4T', g.v, mm(kvn), tt);
+    d('vNormB', g.vn, c.kvHeads[l], T);
+    d('qkNormRopeB', g.ropeQ, c.heads, T); d('qkNormRopeB', g.ropeK, c.kvHeads[l], T);
+    d('kvStoreB', g.kv, Math.ceil(kvn / 256), T);
+    d('attnScoreWB', g.score, Math.ceil(c.heads * T * S / 256));
+    d('softmaxB', g.soft, c.heads * T);
+    d('attnOutB', g.attOut, Math.ceil(QN / 256), T);
+    d('matmulQ4T', g.o, mm(H), tt);
+    d('rmsnormAddB', g.postA, T);
+    d('rmsnormB', g.rmsF, T);
+    d('matmulQ4T', g.mg, mm(DF), tt); d('matmulQ4T', g.mu, mm(DF), tt);
+    d('gegluSplitB', g.mact, Math.ceil(DF / 256), T);
+    d('matmulQ4T', g.md, mm(H), tt);
+    d('rmsnormB', g.mpost, T);
+    d('rmsnormB', g.xm, T);
+    d('rmsnormKB', g.rp, T);
+    d('matmulF32T', g.router, c.experts, T);
+    d('topkB', g.topk, T);
+  }
+  encodeExpertsB(pass, l, T) {
+    const c = this.cfg, g = this.layers[l].B, d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    d('expertQ4B', g.gu, Math.ceil(2 * c.expertFf / 4), 1, T * c.topK);
+    d('geglu', g.act, Math.ceil(T * c.topK * c.expertFf / 256));
+    d('expertQ4B', g.dn, Math.ceil(c.hidden / 4), 1, T * c.topK);
+    d('moeSumB', g.sum, Math.ceil(c.hidden / 256), T);
+    d('rmsnormB', g.mpost2, T);
+    d('postFfnB', g.post, T);
+  }
+
+  // Feeds T = ids.length tokens at this.position through every layer: one routing readback per layer,
+  // the union of the chunk's experts loaded once. want as in step(), for the last token.
+  async prefillChunk(ids, want = 'none') {
+    const c = this.cfg, dev = this.device, K = c.topK, H = c.hidden, T = ids.length, pos0 = this.position, S = pos0 + T;
+    if (T > this.chunkTokens) throw new Error(`chunk of ${T} > ${this.chunkTokens}`);
+    if (S > this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    const tStart = performance.now();
+    dev.queue.writeBuffer(this.b.ids, 0, Uint32Array.from(ids));
+    dev.queue.writeBuffer(this.qb, 0, new Uint32Array([T, pos0, S, 0]));
+    const ls = c.swa.indexOf(true), lf = c.swa.indexOf(false);
+    const tables = (l, ff, buf) => {
+      if (l < 0) return;
+      const d = c.headDim[l], r = new Float32Array(T * d);
+      for (let t = 0; t < T; t++) r.set(this.ropeTable(d, c.ropeTheta[l], ff, pos0 + t), t * d);
+      dev.queue.writeBuffer(buf, 0, r);
+    };
+    tables(ls, null, this.b.ropeS); tables(lf, this.ropeFreqs, this.b.ropeF);
+    const selBytes = T * 2 * K * 4;
+    let enc = dev.createCommandEncoder(), pass = enc.beginComputePass();
+    this.dispatch(pass, 'embedQ6KB', this.gB.embed, Math.ceil(H / 256), T);
+    this.encodeTrunkB(pass, 0, T, S);
+    pass.end();
+    enc.copyBufferToBuffer(this.b.sel, 0, this.rbSelB, 0, selBytes);
+    dev.queue.submit([enc.finish()]);
+    for (let l = 0; l < c.layers; l++) {
+      const t0 = performance.now();
+      await this.rbSelB.mapAsync(1, 0, selBytes);
+      this.counters.gpuWaitMs += performance.now() - t0;
+      const sel = new Uint32Array(this.rbSelB.getMappedRange(0, selBytes).slice(0));
+      this.rbSelB.unmap();
+      const pairs = new Uint32Array(T * K);
+      for (let t = 0; t < T; t++) for (let j = 0; j < K; j++) pairs[t * K + j] = sel[t * 2 * K + j];
+      const unique = [...new Set(pairs)];
+      const tq = performance.now();
+      const slotsU = await this.xs.ensure(l, unique);
+      this.counters.ensureMs += performance.now() - tq;
+      const slotOf = new Map(unique.map((e, i) => [e, slotsU[i]]));
+      dev.queue.writeBuffer(this.b.slots, 0, pairs.map((e) => slotOf.get(e)));
+      enc = dev.createCommandEncoder(); pass = enc.beginComputePass();
+      this.encodeExpertsB(pass, l, T);
+      if (l + 1 < c.layers) {
+        this.encodeTrunkB(pass, l + 1, T, S);
+        pass.end();
+        enc.copyBufferToBuffer(this.b.sel, 0, this.rbSelB, 0, selBytes);
+      } else {
+        pass.end();
+        enc.copyBufferToBuffer(this.b.x, (T - 1) * H * 4, this.a.x, 0, H * 4);
+        if (want !== 'none') {
+          pass = enc.beginComputePass();
+          this.encodeHead(pass, want);
+          pass.end();
+          if (want === 'argmax') enc.copyBufferToBuffer(this.a.am, 0, this.rbArg, 0, 4);
+          if (want === 'logits') enc.copyBufferToBuffer(this.a.logits, 0, this.rbLogits, 0, c.vocab * 4);
+        }
+      }
+      dev.queue.submit([enc.finish()]);
+      this.xs.release(slotsU);
+    }
+    this.position += T;
+    this.cached.push(...ids);
+    let result = null;
+    if (want === 'argmax') {
+      await this.rbArg.mapAsync(1, 0, 4);
+      result = new Uint32Array(this.rbArg.getMappedRange(0, 4))[0];
+      this.rbArg.unmap();
+    } else if (want === 'logits') {
+      await this.rbLogits.mapAsync(1);
+      result = new Float32Array(this.rbLogits.getMappedRange().slice(0));
+      this.rbLogits.unmap();
+    } else {
+      await dev.queue.onSubmittedWorkDone();
+    }
+    this.counters.tokens += T;
+    this.counters.wallMs += performance.now() - tStart;
+    return result;
+  }
+
+  // Feeds `ids` after the cached prefix they share; KV past the prefix is simply overwritten (no recurrent
+  // state to rewind). Chunks of up to chunkTokens when there are at least two new tokens.
+  async prefill(ids, want = 'argmax') {
+    let common = 0;
+    while (common < ids.length - 1 && common < this.cached.length && this.cached[common] === ids[common]) common++;
+    if (common < this.cached.length) { this.position = common; this.cached.length = common; }
+    const rest = ids.slice(common);
+    if (!this.batchPrefill || rest.length < 2) return super.prefill(ids, want);
+    let r = null;
+    for (let i = 0; i < rest.length; i += this.chunkTokens) {
+      r = await this.prefillChunk(rest.slice(i, i + this.chunkTokens), i + this.chunkTokens >= rest.length ? want : 'none');
+    }
+    return r;
+  }
+
+  encodeEmbed(pass) { this.dispatch(pass, 'embedQ6K', this.g.embed, Math.ceil(this.cfg.hidden / 256)); }
+  encodeHead(pass, want) {
+    const c = this.cfg;
+    this.dispatch(pass, 'rmsnorm', this.g.rmsOut, 1);
+    this.dispatch(pass, 'matmulQ6K', this.g.lm, Math.ceil(c.vocab / 4));
+    if (c.softcap) this.dispatch(pass, 'softcap', this.g.cap, Math.ceil(c.vocab / 256));
+    if (want === 'argmax') this.dispatch(pass, 'argmax', this.g.am, 1);
+  }
+
+  // Attention, the dense MLP and the router of layer l (all before the routing readback).
+  encodeAttention(pass, l, seqLen) {
+    const c = this.cfg, g = this.layers[l], d = (n, gr, x, y, z) => this.dispatch(pass, n, gr, x, y, z);
+    const hd = c.headDim[l], QN = c.heads * hd, kvn = c.kvHeads[l] * hd;
+    const n = c.swa[l] ? Math.min(seqLen, c.window) : seqLen;
+    d('rmsnorm', g.rmsA, 1);
+    d('matmulQ4', g.q, Math.ceil(QN / 4)); d('matmulQ4', g.k, Math.ceil(kvn / 4));
+    if (g.hasV) d('matmulQ4', g.v, Math.ceil(kvn / 4));
+    d('vNorm', g.vn, c.kvHeads[l]);
+    d('qkNormRope', g.ropeQ, c.heads); d('qkNormRope', g.ropeK, c.kvHeads[l]);
+    d('kvStore', g.kv, Math.ceil(kvn / 256));
+    d('attnScoreW', g.score, Math.ceil(c.heads * n / 256));
+    d('softmaxW', g.soft, c.heads);
+    d('attnOutW', g.attOut, Math.ceil(QN / 256));
+    d('matmulQ4', g.o, Math.ceil(c.hidden / 4));
+    d('rmsnormAdd', g.postA, 1);
+    if (g.capA) d('copyAt', g.capA, Math.ceil(c.hidden / 256));
+    d('rmsnorm', g.rmsF, 1);
+    d('matmulQ4', g.mg, Math.ceil(c.denseFf / 4)); d('matmulQ4', g.mu, Math.ceil(c.denseFf / 4));
+    d('geglu', g.mact, Math.ceil(c.denseFf / 256));
+    d('matmulQ4', g.md, Math.ceil(c.hidden / 4));
+    d('rmsnorm', g.mpost, 1);
+    d('rmsnorm', g.xm, 1);
+    if (this.prefetch) for (const p of g.pf) { d('rmsnormK', p.rp, 1); d('matmulF32', p.router, c.experts); d('topk', p.topk, 1); }
+    d('rmsnormK', g.rp, 1);
+    d('matmulF32', g.router, c.experts);
+    d('topk', g.topk, 1);
+  }
+  encodeExperts(pass, l) {
+    const c = this.cfg, g = this.layers[l], d = (n, gr, x, y, z) => this.dispatch(pass, n, gr, x, y, z);
+    d('expertQ4', g.gu, Math.ceil(2 * c.expertFf / 4), 1, c.topK);
+    d('geglu', g.act, Math.ceil(c.topK * c.expertFf / 256));
+    d('expertQ4', g.dn, Math.ceil(c.hidden / 4), 1, c.topK);
+    d('moeSum', g.sum, Math.ceil(c.hidden / 256));
+    d('rmsnorm', g.mpost2, 1);
+    d('postFfn', g.post, 1);
+    if (g.capX) d('copyAt', g.capX, Math.ceil(c.hidden / 256));
+  }
+
+  // NeoX RoPE angles as llama.cpp's Metal kernel forms them: f32 pos × base^(−2i/d), ÷ the frequency factor
+  // on full-attention layers. One table per layer kind; [0, d/2) = cos, [d/2, d) = sin.
+  // KV cache bytes: per-layer head counts and sizes (sliding and full-attention layers differ).
+  kvBytes() { const c = this.cfg; return c.headDim.reduce((sum, d, l) => sum + 2 * 2 * this.maxCtx * c.kvHeads[l] * d, 0); }
+  ropeTable(d, base, ff, pos) {
+    const half = d / 2, r = new Float32Array(d), inv = Math.fround(-1 / d);
+    for (let i = 0; i < half; i++) {
+      let th = Math.fround(pos * Math.fround(Math.pow(base, Math.fround(inv * 2 * i))));
+      if (ff) th = Math.fround(th / ff[i]);
+      r[i] = Math.cos(th); r[half + i] = Math.sin(th);
+    }
+    return r;
+  }
+  writeTokenUniforms(token, pos) {
+    const c = this.cfg;
+    this.device.queue.writeBuffer(this.tok, 0, new Uint32Array([token, pos, pos + 1, 0]));
+    const ls = c.swa.indexOf(true), lf = c.swa.indexOf(false);
+    if (ls >= 0) this.device.queue.writeBuffer(this.a.ropeS, 0, this.ropeTable(c.headDim[ls], c.ropeTheta[ls], null, pos));
+    if (lf >= 0) this.device.queue.writeBuffer(this.a.ropeF, 0, this.ropeTable(c.headDim[lf], c.ropeTheta[lf], this.ropeFreqs, pos));
+  }
+
+  // Debug: the last step's per-layer states — attn_out (after the attention residual) and each layer's output.
+  async readCapture() {
+    const c = this.cfg, n = 2 * c.layers * c.hidden * 4;
+    const rb = this.device.createBuffer({ size: n, usage: MAP_READ | COPY_DST });
+    const enc = this.device.createCommandEncoder();
+    enc.copyBufferToBuffer(this.a.cap, 0, rb, 0, n);
+    this.device.queue.submit([enc.finish()]);
+    await rb.mapAsync(1);
+    const all = new Float32Array(rb.getMappedRange().slice(0));
+    rb.unmap(); rb.destroy();
+    const H = c.hidden, L = c.layers;
+    return { attnOut: Array.from({ length: L }, (_, l) => all.subarray(l * H, (l + 1) * H)), layers: Array.from({ length: L }, (_, l) => all.subarray((L + l) * H, (L + l + 1) * H)) };
+  }
+}

engines/qwen35_moe_ssd.js

@@ -0,0 +1,1231 @@
+/* qwen35_moe_ssd.js — Qwen3.5/3.6 MoE (Qwen3.6-35B-A3B, GGUF arch `qwen35moe`) in a browser tab,
+ * larger than RAM: rung 2b of the SSD-streaming ladder. The routed experts stream from OPFS into
+ * a GPU slot pool exactly as in rung 2a (qwen3_moe_ssd.js, which this module extends); what is new
+ * is the hybrid trunk:
+ *   - 3 of every 4 layers are Gated DeltaNet (linear attention): a 4-tap causal conv over the
+ *     q|k|v projection, L2-normalised q and k, and the gated delta rule on a 128×128 state per
+ *     value head; output = RMSNorm(o)·w · SiLU(z), then a projection.
+ *   - every 4th layer is full attention with a per-head output gate (the q projection carries
+ *     q and gate per head), q/k RMSNorm and NeoX RoPE on the first 64 of 256 dims.
+ *   - each MoE block adds a shared expert, scaled by sigmoid(x·w_gate).
+ * The math follows llama.cpp's qwen35moe graph and its CPU ops (ggml_gated_delta_net, ssm_conv,
+ * rope_multi with text positions), so greedy output can be gated against llama-server on the
+ * same GGUF. Decode is one token at a time (prefill feeds tokens through the same step).
+ *
+ *   const m = await Qwen35MoeSsd.load(null, { url: '…/Qwen3.6-35B-A3B-Q8_0.gguf', poolBytes });
+ */
+
+import { Qwen3MoeSsd, STORAGE, COPY_SRC, COPY_DST, MAP_READ, UNIFORM, I8 } from './qwen3_moe_ssd.js';
+
+export const QWEN36_35B_A3B = {
+  repo: 'unsloth/Qwen3.6-35B-A3B-GGUF',
+  file: 'Qwen3.6-35B-A3B-Q8_0.gguf',
+  revision: 'a483e9e6cbd595906af30beda3187c2663a1118c',
+  sha256: 'd1a395809f65a43a13ad119eb4e7acdef1ac6d68120f39902c8ab96e72794a59',
+  size: 36903140320,
+};
+
+const SIGMOID = 'fn sigm(x: f32) -> f32 { return 1.0 / (1.0 + exp(-x)); }';
+
+const KERNELS = {
+  // Per-head RMSNorm (QK-norm), then NeoX RoPE on the first nRot dims (pairs i, i + nRot/2);
+  // dims ≥ nRot keep the normed value. src rows are srcStride apart (the q projection holds
+  // [q hd | gate hd] per head); with gate = 1 the gate half is copied to gout. One workgroup per head.
+  qkNormRopeP: `
+struct P { hd: u32, srcStride: u32, nRot: u32, gate: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> src: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> rope: array<f32>;
+@group(0) @binding(3) var<storage, read_write> dst: array<f32>;
+@group(0) @binding(4) var<storage, read_write> gout: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let sb = wg.x * p.srcStride; let ob = wg.x * p.hd; let t = l.x; let half = p.nRot / 2u;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = src[sb + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < p.hd; i += 64u) {
+    if (i < half) {
+      let a = (src[sb + i] * scale) * w[i];
+      let b = (src[sb + i + half] * scale) * w[i + half];
+      let c = rope[i]; let sn = rope[half + i];
+      dst[ob + i] = a * c - b * sn;
+      dst[ob + i + half] = a * sn + b * c;
+    } else if (i >= p.nRot) {
+      dst[ob + i] = (src[sb + i] * scale) * w[i];
+    }
+    if (p.gate == 1u) { gout[ob + i] = src[sb + p.hd + i]; }
+  }
+}`,
+  // x[i] *= sigmoid(g[i]) — the full-attention output gate.
+  sigmoidMul: `
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> g: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+${SIGMOID}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let i = gi.x; if (i < p.n) { x[i] = x[i] * sigm(g[i]); }
+}`,
+  // Causal depthwise conv, kernel 4, over the q|k|v projection, then SiLU. state holds each
+  // channel's previous 3 inputs, oldest first (llama.cpp's conv state), and rolls forward.
+  gdnConv: `
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read> mixed: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> st: array<f32>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let c = gi.x; if (c >= p.n) { return; }
+  let s0 = st[c * 3u]; let s1 = st[c * 3u + 1u]; let s2 = st[c * 3u + 2u]; let x = mixed[c];
+  var sum = 0.0;
+  sum += s0 * w[c * 4u]; sum += s1 * w[c * 4u + 1u]; sum += s2 * w[c * 4u + 2u]; sum += x * w[c * 4u + 3u];
+  y[c] = sum / (1.0 + exp(-sum));
+  st[c * 3u] = s1; st[c * 3u + 1u] = s2; st[c * 3u + 2u] = x;
+}`,
+  // The gated delta rule for one token. Workgroup h = value head, thread j = value row j of the
+  // head's state M (M[j][i] = S[i][j], llama.cpp's layout; i runs over the key dim). k-head = h % kH.
+  //   q, k ← L2-normalised (x / sqrt(Σx² + eps));  beta = σ(b);  g = softplus(a + dt) · A
+  //   M ← M·e^g;  d_j = β (v_j − Σ_i M[j][i] k_i);  M[j][i] += k_i d_j;  o_j = (Σ_i M[j][i] q_i) / √dS
+  gdnStep: `
+struct P { kH: u32, dS: u32, keyDim: u32, pad: u32, eps: f32, scale: f32 }
+@group(0) @binding(0) var<storage, read> cv: array<f32>;
+@group(0) @binding(1) var<storage, read> bb: array<f32>;
+@group(0) @binding(2) var<storage, read> al: array<f32>;
+@group(0) @binding(3) var<storage, read> dt: array<f32>;
+@group(0) @binding(4) var<storage, read> aa: array<f32>;
+@group(0) @binding(5) var<storage, read_write> M: array<f32>;
+@group(0) @binding(6) var<storage, read_write> o: array<f32>;
+@group(0) @binding(7) var<uniform> p: P;
+${SIGMOID}
+var<workgroup> kq: array<f32, 128>;
+var<workgroup> qq: array<f32, 128>;
+var<workgroup> rq: array<f32, 128>;
+var<workgroup> rk: array<f32, 128>;
+fn log1p_(u: f32) -> f32 { let y = 1.0 + u; return log(y) - ((y - 1.0) - u) / y; }
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let h = wg.x; let j = l.x; let dS = p.dS; let kh = h % p.kH;
+  let qv = cv[kh * dS + j]; let kv = cv[p.keyDim + kh * dS + j]; let vv = cv[2u * p.keyDim + h * dS + j];
+  rq[j] = qv * qv; rk[j] = kv * kv; workgroupBarrier();
+  for (var s = 64u; s > 0u; s >>= 1u) { if (j < s) { rq[j] += rq[j + s]; rk[j] += rk[j + s]; } workgroupBarrier(); }
+  let n = f32(dS); let inv = 1.0 / sqrt(n);
+  qq[j] = (qv * (1.0 / sqrt(rq[0] / n + p.eps / n))) * inv;
+  kq[j] = (kv * (1.0 / sqrt(rk[0] / n + p.eps / n))) * inv;
+  workgroupBarrier();
+  let beta = sigm(bb[h]);
+  let x = al[h] + dt[h];
+  let sp = select(log1p_(exp(x)), x, x > 20.0);
+  let decay = exp(sp * aa[h]);
+  let row = (h * dS + j) * dS;
+  var sk = 0.0;
+  for (var i = 0u; i < dS; i++) { let m = M[row + i] * decay; M[row + i] = m; sk += m * kq[i]; }
+  let d = (vv - sk) * beta;
+  var acc = 0.0;
+  for (var i = 0u; i < dS; i++) { let m = M[row + i] + kq[i] * d; M[row + i] = m; acc += m * qq[i]; }
+  o[h * dS + j] = acc * p.scale;
+}`,
+  // Per value head: RMSNorm(o)·w · SiLU(z).
+  gdnNormGate: `
+struct P { dS: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> o: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> z: array<f32>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+var<workgroup> red: array<f32, 128>;
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let h = wg.x; let j = l.x; let i = h * p.dS + j;
+  let v = o[i]; red[j] = v * v; workgroupBarrier();
+  for (var s = 64u; s > 0u; s >>= 1u) { if (j < s) { red[j] += red[j + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.dS) + p.eps);
+  let zz = z[i];
+  y[i] = ((v * scale) * w[j]) * (zz / (1.0 + exp(-zz)));
+}`,
+  // x[h] = (Σ_j w_j·out[j·H + h] + sh[h]·σ(sg)) + x[h]: routed experts, the gated shared expert,
+  // then the residual — llama.cpp's order.
+  moeAccumShared: `
+struct P { H: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> out: array<f32>;
+@group(0) @binding(1) var<storage, read> sel: array<u32>;
+@group(0) @binding(2) var<storage, read> sh: array<f32>;
+@group(0) @binding(3) var<storage, read> sg: array<f32>;
+@group(0) @binding(4) var<storage, read_write> x: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+${SIGMOID}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let h = gi.x; if (h >= p.H) { return; }
+  var acc = 0.0;
+  for (var j = 0u; j < p.k; j++) { acc += bitcast<f32>(sel[p.k + j]) * out[j * p.H + h]; }
+  x[h] = (acc + sh[h] * sigm(sg[0])) + x[h];
+}`,
+};
+
+
+// ── Batched prefill: a chunk of T prompt tokens per layer ───────────────────────────────────
+// Every batched buffer is token-major (row t holds token pos0 + t). Q is the per-chunk uniform.
+const QB = 'struct Q { T: u32, pos0: u32, S: u32, pad: u32 }';
+const BATCH_KERNELS = {
+  embedQ8B: `enable f16;
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> q: array<u32>;
+@group(0) @binding(1) var<storage, read> s: array<f16>;
+@group(0) @binding(2) var<storage, read> ids: array<u32>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+${I8}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; let t = g.y; if (i >= p.n || t >= qd.T) { return; }
+  let e = ids[t] * p.n + i;
+  y[t * p.n + i] = i8at(q[e >> 2u], e & 3u) * f32(s[e >> 5u]);
+}`,
+  // One workgroup per token row.
+  rmsnormB: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let b = wg.x * p.n; let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = x[b + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { y[b + i] = (x[b + i] * scale) * w[i]; }
+}`,
+  // Tiled Q8_0 GEMM: y[t·M + m] = Σ_k x[t·N + k]·W[m][k]. A workgroup computes 16 rows × 16 tokens;
+  // each 32-wide k block (one Q8_0 block) of W and x goes through shared memory, so every weight
+  // byte read serves 16 tokens. Dispatch (ceil(M/16), ceil(T/16)).
+  matmulQ8T: `enable f16;
+struct P { M: u32, N: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+${I8}
+var<workgroup> ws: array<f32, 512>;
+var<workgroup> xs: array<f32, 512>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m0 = wg.x * 16u; let t0 = wg.y * 16u; let r = l.x / 16u; let c = l.x % 16u;
+  let nb = p.N / 32u; var acc = 0.0;
+  for (var b = 0u; b < nb; b++) {
+    for (var i = l.x; i < 512u; i += 256u) {
+      let rr = i / 32u; let kk = i % 32u;
+      let m = m0 + rr; var wv = 0.0;
+      if (m < p.M) { let e = m * p.N + b * 32u + kk; wv = i8at(qw[e >> 2u], e & 3u) * f32(qs[m * nb + b]); }
+      ws[i] = wv;
+      let t = t0 + rr; var xv = 0.0;
+      if (t < qd.T) { xv = x[t * p.N + b * 32u + kk]; }
+      xs[i] = xv;
+    }
+    workgroupBarrier();
+    for (var kk = 0u; kk < 32u; kk++) { acc += ws[r * 32u + kk] * xs[c * 32u + kk]; }
+    workgroupBarrier();
+  }
+  let m = m0 + r; let t = t0 + c;
+  if (m < p.M && t < qd.T) { y[t * p.M + m] = acc; }
+}`,
+  // F32 matrix × T vectors, one workgroup per (row, token). Dispatch (M, T).
+  matmulF32T: `
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m = wg.x; let t = wg.y; let i = l.x; var acc = 0.0;
+  for (var k = i; k < p.N; k += 256u) { acc += w[m * p.N + k] * x[t * p.N + k]; }
+  red[i] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (i < s) { red[i] += red[i + s]; } workgroupBarrier(); }
+  if (i == 0u) { y[t * p.M + m] = red[0]; }
+}`,
+  // The router top-k for token wg.x (same picks and weights as the one-token kernel).
+  topkB: `
+struct P { n: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> lg: array<f32>;
+@group(0) @binding(1) var<storage, read_write> sel: array<u32>;
+@group(0) @binding(2) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+var<workgroup> bi: array<u32, 256>;
+var<workgroup> gmax: f32;
+var<workgroup> gsum: f32;
+var<workgroup> picks: array<u32, 32>;
+var<workgroup> probs: array<f32, 32>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; let n = p.n; let lb = wg.x * n; let sb = wg.x * 2u * p.k;
+  red[t] = select(-3.4e38, lg[lb + min(t, n - 1u)], t < n); workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] = max(red[t], red[t + s]); } workgroupBarrier(); }
+  if (t == 0u) { gmax = red[0]; } workgroupBarrier();
+  red[t] = select(0.0, exp(lg[lb + min(t, n - 1u)] - gmax), t < n); workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  if (t == 0u) { gsum = red[0]; } workgroupBarrier();
+  var mine = select(-1.0, exp(lg[lb + min(t, n - 1u)] - gmax) / gsum, t < n);
+  for (var j = 0u; j < p.k; j++) {
+    red[t] = mine; bi[t] = t; workgroupBarrier();
+    for (var s = 128u; s > 0u; s >>= 1u) {
+      if (t < s) { let o = red[t + s]; if (o > red[t] || (o == red[t] && bi[t + s] < bi[t])) { red[t] = o; bi[t] = bi[t + s]; } }
+      workgroupBarrier();
+    }
+    if (t == 0u) { picks[j] = bi[0]; probs[j] = red[0]; }
+    workgroupBarrier();
+    if (t == picks[j]) { mine = -1.0; }
+    workgroupBarrier();
+  }
+  if (t == 0u) {
+    var wsum = 0.0;
+    for (var j = 0u; j < p.k; j++) { wsum += probs[j]; }
+    for (var j = 0u; j < p.k; j++) { sel[sb + j] = picks[j]; sel[sb + p.k + j] = bitcast<u32>(probs[j] / wsum); }
+  }
+}`,
+  // The 4-tap conv over T tokens in order, rolling the state.
+  gdnConvB: `
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> mixed: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> st: array<f32>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let c = gi.x; if (c >= p.n) { return; }
+  var s0 = st[c * 3u]; var s1 = st[c * 3u + 1u]; var s2 = st[c * 3u + 2u];
+  let w0 = w[c * 4u]; let w1 = w[c * 4u + 1u]; let w2 = w[c * 4u + 2u]; let w3 = w[c * 4u + 3u];
+  for (var t = 0u; t < qd.T; t++) {
+    let x = mixed[t * p.n + c];
+    var sum = 0.0;
+    sum += s0 * w0; sum += s1 * w1; sum += s2 * w2; sum += x * w3;
+    y[t * p.n + c] = sum / (1.0 + exp(-sum));
+    s0 = s1; s1 = s2; s2 = x;
+  }
+  st[c * 3u] = s0; st[c * 3u + 1u] = s1; st[c * 3u + 2u] = s2;
+}`,
+  // The gated delta rule over T tokens in order (one workgroup per value head, as gdnStep).
+  gdnStepB: `
+struct P { kH: u32, dS: u32, keyDim: u32, convDim: u32, vH: u32, pad: u32, eps: f32, scale: f32 }
+${QB}
+@group(0) @binding(0) var<storage, read> cv: array<f32>;
+@group(0) @binding(1) var<storage, read> bb: array<f32>;
+@group(0) @binding(2) var<storage, read> al: array<f32>;
+@group(0) @binding(3) var<storage, read> dt: array<f32>;
+@group(0) @binding(4) var<storage, read> aa: array<f32>;
+@group(0) @binding(5) var<storage, read_write> M: array<f32>;
+@group(0) @binding(6) var<storage, read_write> o: array<f32>;
+@group(0) @binding(7) var<uniform> p: P;
+@group(0) @binding(8) var<uniform> qd: Q;
+${SIGMOID}
+var<workgroup> kq: array<f32, 128>;
+var<workgroup> qq: array<f32, 128>;
+var<workgroup> rq: array<f32, 128>;
+var<workgroup> rk: array<f32, 128>;
+fn log1p_(u: f32) -> f32 { let y = 1.0 + u; return log(y) - ((y - 1.0) - u) / y; }
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let h = wg.x; let j = l.x; let dS = p.dS; let kh = h % p.kH;
+  let n = f32(dS); let inv = 1.0 / sqrt(n);
+  let row = (h * dS + j) * dS;
+  let dth = dt[h]; let aah = aa[h];
+  for (var t = 0u; t < qd.T; t++) {
+    let cb = t * p.convDim;
+    let qv = cv[cb + kh * dS + j]; let kv = cv[cb + p.keyDim + kh * dS + j]; let vv = cv[cb + 2u * p.keyDim + h * dS + j];
+    rq[j] = qv * qv; rk[j] = kv * kv; workgroupBarrier();
+    for (var s = 64u; s > 0u; s >>= 1u) { if (j < s) { rq[j] += rq[j + s]; rk[j] += rk[j + s]; } workgroupBarrier(); }
+    qq[j] = (qv * (1.0 / sqrt(rq[0] / n + p.eps / n))) * inv;
+    kq[j] = (kv * (1.0 / sqrt(rk[0] / n + p.eps / n))) * inv;
+    workgroupBarrier();
+    let beta = sigm(bb[t * p.vH + h]);
+    let x = al[t * p.vH + h] + dth;
+    let sp = select(log1p_(exp(x)), x, x > 20.0);
+    let decay = exp(sp * aah);
+    var sk = 0.0;
+    for (var i = 0u; i < dS; i++) { let m = M[row + i] * decay; M[row + i] = m; sk += m * kq[i]; }
+    let d = (vv - sk) * beta;
+    var acc = 0.0;
+    for (var i = 0u; i < dS; i++) { let m = M[row + i] + kq[i] * d; M[row + i] = m; acc += m * qq[i]; }
+    o[t * p.vH * dS + h * dS + j] = acc * p.scale;
+    workgroupBarrier();
+  }
+}`,
+  // RMSNorm(o)·w·SiLU(z) for (value head wg.x, token wg.y).
+  gdnNormGateB: `
+struct P { dS: u32, dInner: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> o: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> z: array<f32>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+var<workgroup> red: array<f32, 128>;
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let j = l.x; let i = wg.y * p.dInner + wg.x * p.dS + j;
+  let v = o[i]; red[j] = v * v; workgroupBarrier();
+  for (var s = 64u; s > 0u; s >>= 1u) { if (j < s) { red[j] += red[j + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.dS) + p.eps);
+  let zz = z[i];
+  y[i] = ((v * scale) * w[j]) * (zz / (1.0 + exp(-zz)));
+}`,
+  // qkNormRopeP for (head wg.x, token wg.y); rope holds nRot values per token.
+  qkNormRopePB: `
+struct P { hd: u32, srcStride: u32, srcRow: u32, dstRow: u32, nRot: u32, gate: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> src: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> rope: array<f32>;
+@group(0) @binding(3) var<storage, read_write> dst: array<f32>;
+@group(0) @binding(4) var<storage, read_write> gout: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let tk = wg.y; let sb = tk * p.srcRow + wg.x * p.srcStride; let ob = tk * p.dstRow + wg.x * p.hd; let rb = tk * p.nRot;
+  let t = l.x; let half = p.nRot / 2u;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = src[sb + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < p.hd; i += 64u) {
+    if (i < half) {
+      let a = (src[sb + i] * scale) * w[i];
+      let b = (src[sb + i + half] * scale) * w[i + half];
+      let c = rope[rb + i]; let sn = rope[rb + half + i];
+      dst[ob + i] = a * c - b * sn;
+      dst[ob + i + half] = a * sn + b * c;
+    } else if (i >= p.nRot) {
+      dst[ob + i] = (src[sb + i] * scale) * w[i];
+    }
+    if (p.gate == 1u) { gout[ob + i] = src[sb + p.hd + i]; }
+  }
+}`,
+  kvStoreB: `enable f16;
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> k: array<f32>;
+@group(0) @binding(1) var<storage, read> v: array<f32>;
+@group(0) @binding(2) var<storage, read_write> kc: array<f16>;
+@group(0) @binding(3) var<storage, read_write> vc: array<f16>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; let t = g.y; if (i >= p.n || t >= qd.T) { return; }
+  let pos = qd.pos0 + t;
+  kc[pos * p.n + i] = f16(k[t * p.n + i]);
+  vc[pos * p.n + i] = f16(v[t * p.n + i]);
+}`,
+  // Causal scores for T queries over S = pos0 + T keys; masked keys get -3.4e38.
+  attnScoreB: `enable f16;
+struct P { heads: u32, kvHeads: u32, hd: u32, scale: f32 }
+${QB}
+@group(0) @binding(0) var<storage, read> q: array<f32>;
+@group(0) @binding(1) var<storage, read> kc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@group(0) @binding(4) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>) {
+  let idx = g.y * ng.x * 256u + g.x; let S = qd.S; let T = qd.T;
+  if (idx >= p.heads * T * S) { return; }
+  let h = idx / (T * S); let rem = idx % (T * S); let t = rem / S; let pos = rem % S;
+  if (pos > qd.pos0 + t) { sc[idx] = -3.4e38; return; }
+  let kvh = h / (p.heads / p.kvHeads);
+  let qo = t * p.heads * p.hd + h * p.hd; let ko = pos * p.kvHeads * p.hd + kvh * p.hd;
+  var acc = 0.0;
+  for (var d = 0u; d < p.hd; d++) { acc += q[qo + d] * f32(kc[ko + d]); }
+  sc[idx] = acc * p.scale;
+}`,
+  softmaxB: `
+${QB}
+@group(0) @binding(0) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(1) var<uniform> qd: Q;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let n = qd.S; let base = wg.x * n; let t = l.x;
+  var mx = -3.4e38;
+  for (var i = t; i < n; i += 256u) { mx = max(mx, sc[base + i]); }
+  red[t] = mx; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] = max(red[t], red[t + s]); } workgroupBarrier(); }
+  let m = red[0]; workgroupBarrier();
+  var sum = 0.0;
+  for (var i = t; i < n; i += 256u) { let e = exp(sc[base + i] - m); sc[base + i] = e; sum += e; }
+  red[t] = sum; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let inv = 1.0 / red[0];
+  for (var i = t; i < n; i += 256u) { sc[base + i] = sc[base + i] * inv; }
+}`,
+  attnOutB: `enable f16;
+struct P { heads: u32, kvHeads: u32, hd: u32, pad: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> pr: array<f32>;
+@group(0) @binding(1) var<storage, read> vc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@group(0) @binding(4) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let QN = p.heads * p.hd; let idx = g.x; let t = g.y;
+  if (idx >= QN || t >= qd.T) { return; }
+  let h = idx / p.hd; let d = idx % p.hd; let kvh = h / (p.heads / p.kvHeads);
+  let stride = p.kvHeads * p.hd; let rb = (h * qd.T + t) * qd.S; let last = qd.pos0 + t;
+  var acc = 0.0;
+  for (var pos = 0u; pos <= last; pos++) { acc += pr[rb + pos] * f32(vc[pos * stride + kvh * p.hd + d]); }
+  y[t * QN + idx] = acc;
+}`,
+  sigmoidMulB: `
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> g: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+@group(0) @binding(3) var<uniform> qd: Q;
+${SIGMOID}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let i = gi.x; let t = gi.y; if (i >= p.n || t >= qd.T) { return; }
+  let k = t * p.n + i; x[k] = x[k] * sigm(g[k]);
+}`,
+  addInPlaceB: `
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> y: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+@group(0) @binding(3) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let i = gi.x; let t = gi.y; if (i >= p.n || t >= qd.T) { return; }
+  let k = t * p.n + i; x[k] = x[k] + y[k];
+}`,
+  // Routed experts for all (token, pick) pairs: z = t·K + j, slots[z] its pool slot. Input is the
+  // token's row (gate/up, inputMode 0) or the pair's own row (down, inputMode 1).
+  expertQ8B: `enable f16;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputMode: u32, K: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+${I8}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let N = p.N; let M = p.M; let nb = N / 32u;
+  if (m0 >= M) { return; }
+  let rb = slots[z] * p.rowsPerExpert;
+  let xb = select((z / p.K) * N, z * N, p.inputMode == 1u);
+  let r0 = rb + min(m0, M - 1u); let r1 = rb + min(m0 + 1u, M - 1u); let r2 = rb + min(m0 + 2u, M - 1u); let r3 = rb + min(m0 + 3u, M - 1u);
+  let q0 = (r0 * N) >> 2u; let q1 = (r1 * N) >> 2u; let q2 = (r2 * N) >> 2u; let q3 = (r3 * N) >> 2u;
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var k = t; k < N; k += 256u) {
+    let xv = x[xb + k]; let wi = k >> 2u; let ln = k & 3u; let b = k >> 5u;
+    a0 += i8at(qw[q0 + wi], ln) * f32(qs[r0 * nb + b]) * xv;
+    a1 += i8at(qw[q1 + wi], ln) * f32(qs[r1 * nb + b]) * xv;
+    a2 += i8at(qw[q2 + wi], ln) * f32(qs[r2 * nb + b]) * xv;
+    a3 += i8at(qw[q3 + wi], ln) * f32(qs[r3 * nb + b]) * xv;
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[z * M + m0 + t] = part[t * 256u]; }
+}`,
+  // act = SiLU(g)·u, elementwise over T × n (the shared expert's separate gate and up).
+  siluMul2B: `
+struct P { n: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> g: array<f32>;
+@group(0) @binding(1) var<storage, read> u: array<f32>;
+@group(0) @binding(2) var<storage, read_write> act: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@group(0) @binding(4) var<uniform> qd: Q;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let i = gi.x; let t = gi.y; if (i >= p.n || t >= qd.T) { return; }
+  let k = t * p.n + i; let gv = g[k];
+  act[k] = (gv / (1.0 + exp(-gv))) * u[k];
+}`,
+  moeAccumSharedB: `
+struct P { H: u32, k: u32 }
+${QB}
+@group(0) @binding(0) var<storage, read> out: array<f32>;
+@group(0) @binding(1) var<storage, read> sel: array<u32>;
+@group(0) @binding(2) var<storage, read> sh: array<f32>;
+@group(0) @binding(3) var<storage, read> sg: array<f32>;
+@group(0) @binding(4) var<storage, read_write> x: array<f32>;
+@group(0) @binding(5) var<uniform> p: P;
+@group(0) @binding(6) var<uniform> qd: Q;
+${SIGMOID}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) gi: vec3<u32>) {
+  let h = gi.x; let t = gi.y; if (h >= p.H || t >= qd.T) { return; }
+  let sb = t * 2u * p.k; var acc = 0.0;
+  for (var j = 0u; j < p.k; j++) { acc += bitcast<f32>(sel[sb + p.k + j]) * out[(t * p.k + j) * p.H + h]; }
+  let r = t * p.H + h;
+  x[r] = (acc + sh[r] * sigm(sg[t])) + x[r];
+}`,
+};
+
+// ── Subgroup Q8_0 GEMV (the LFM2.5 / Gemma 4 kernels' pattern) ──────────────────────────────
+// One 32-lane subgroup per output row, 4 rows per 128-thread workgroup (the same dispatch
+// geometry as matmulQ8/expertQ8). Each lane takes whole Q8_0 blocks: two vec4<u32> of int8
+// codes, unpack4xI8, vec4 dot products against the activations, the block scale applied once;
+// one subgroupAdd reduces the row. Used only when the adapter's subgroups are exactly 32 wide.
+const SG_KERNELS = {
+  matmulQ8: `enable f16;
+enable subgroups;
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> x: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read> qw: array<vec4<u32>>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m = (wg.y * ng.x + wg.x) * 4u + l.x / 32u; let lane = l.x % 32u;
+  let nb = p.N / 32u; let mr = min(m, p.M - 1u);
+  let wb = mr * nb * 2u; let sb = mr * nb;
+  var acc = 0.0;
+  for (var b = lane; b < nb; b += 32u) {
+    let w0 = qw[wb + b * 2u]; let w1 = qw[wb + b * 2u + 1u]; let xb = b * 8u;
+    var s = dot(vec4<f32>(unpack4xI8(w0.x)), x[xb]) + dot(vec4<f32>(unpack4xI8(w0.y)), x[xb + 1u]);
+    s += dot(vec4<f32>(unpack4xI8(w0.z)), x[xb + 2u]) + dot(vec4<f32>(unpack4xI8(w0.w)), x[xb + 3u]);
+    s += dot(vec4<f32>(unpack4xI8(w1.x)), x[xb + 4u]) + dot(vec4<f32>(unpack4xI8(w1.y)), x[xb + 5u]);
+    s += dot(vec4<f32>(unpack4xI8(w1.z)), x[xb + 6u]) + dot(vec4<f32>(unpack4xI8(w1.w)), x[xb + 7u]);
+    acc += s * f32(qs[sb + b]);
+  }
+  let total = subgroupAdd(acc);
+  if (lane == 0u && m < p.M) { y[m] = total; }
+}`,
+  expertQ8: `enable f16;
+enable subgroups;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputPerSlot: u32 }
+@group(0) @binding(0) var<storage, read> x: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read> qw: array<vec4<u32>>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+@compute @workgroup_size(128) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m = (wg.y * ng.x + wg.x) * 4u + l.x / 32u; let lane = l.x % 32u;
+  let nb = p.N / 32u; let r = slots[z] * p.rowsPerExpert + min(m, p.M - 1u);
+  let wb = r * nb * 2u; let sb = r * nb;
+  let xo = select(0u, z * p.N / 4u, p.inputPerSlot == 1u);
+  var acc = 0.0;
+  for (var b = lane; b < nb; b += 32u) {
+    let w0 = qw[wb + b * 2u]; let w1 = qw[wb + b * 2u + 1u]; let xb = xo + b * 8u;
+    var s = dot(vec4<f32>(unpack4xI8(w0.x)), x[xb]) + dot(vec4<f32>(unpack4xI8(w0.y)), x[xb + 1u]);
+    s += dot(vec4<f32>(unpack4xI8(w0.z)), x[xb + 2u]) + dot(vec4<f32>(unpack4xI8(w0.w)), x[xb + 3u]);
+    s += dot(vec4<f32>(unpack4xI8(w1.x)), x[xb + 4u]) + dot(vec4<f32>(unpack4xI8(w1.y)), x[xb + 5u]);
+    s += dot(vec4<f32>(unpack4xI8(w1.z)), x[xb + 6u]) + dot(vec4<f32>(unpack4xI8(w1.w)), x[xb + 7u]);
+    acc += s * f32(qs[sb + b]);
+  }
+  let total = subgroupAdd(acc);
+  if (lane == 0u && m < p.M) { y[z * p.M + m] = total; }
+}`,
+};
+
+// Routing on the GPU (decode): after layer l's top-k, look each pick up in the pool's residency
+// map. All resident → write the slots and carry on; any absent → record l+1 in `st`, after which
+// every guarded kernel returns at once, so the rest of the token costs dispatches, not math.
+const ROUTE_KERNEL = `
+struct P { l: u32, E: u32, K: u32, pad: u32 }
+@group(0) @binding(0) var<storage, read> sel: array<u32>;
+@group(0) @binding(1) var<storage, read> rmap: array<u32>;
+@group(0) @binding(2) var<storage, read_write> slots: array<u32>;
+@group(0) @binding(3) var<storage, read_write> st: array<u32>;
+@group(0) @binding(4) var<storage, read_write> used: array<u32>;
+@group(0) @binding(5) var<uniform> p: P;
+@compute @workgroup_size(1) fn main() {
+  if (st[0] != 0u) { return; }
+  var miss = false;
+  for (var j = 0u; j < p.K; j++) {
+    let e = sel[j]; let s = rmap[p.l * p.E + e];
+    used[p.l * p.K + j] = e;
+    if (s == 0xffffffffu) { miss = true; } else { slots[j] = s; }
+  }
+  if (miss) { st[0] = p.l + 1u; }
+}`;
+const ABSENT = 0xffffffff;
+
+// Adds a read-only `stopF` binding after a kernel's last binding and an early return while it is
+// set. A read-only storage value is uniform, so the return keeps barriers and subgroup ops legal.
+function guarded(src) {
+  let last = -1;
+  for (const m of src.matchAll(/@binding\((\d+)\)/g)) last = Math.max(last, +m[1]);
+  const at = src.indexOf('@compute');
+  const out = `${src.slice(0, at)}@group(0) @binding(${last + 1}) var<storage, read> stopF: array<u32>;\n${src.slice(at)}`;
+  const withReturn = out.replace(/(@compute[^{]*?\bfn main\([\s\S]*?\)\s*\{)/, '$1\n  if (stopF[0] != 0u) { return; }');
+  if (withReturn === out) throw new Error('guarded(): no compute entry point');
+  return withReturn;
+}
+
+export class Qwen35MoeSsd extends Qwen3MoeSsd {
+  // Without a url, the pinned Hugging Face file; with one (a local serve, a layer cut), the OPFS
+  // directory is named after the file, never after rung 2a's model.
+  static async load(modelId = null, opts = {}) {
+    const source = opts.source || (opts.url ? { repo: null, file: opts.url.split('/').pop(), revision: null } : QWEN36_35B_A3B);
+    return super.load(modelId, { ...opts, source });
+  }
+
+  constructor(device, manifest, gguf, opts) {
+    super(device, manifest, gguf, opts);
+    const c = this.cfg;
+    if (c.arch !== 'qwen35moe') throw new Error(`Qwen35MoeSsd needs a qwen35moe GGUF, got ${c.arch}`);
+    if (c.ssm.dConv !== 4) throw new Error(`gdnConv assumes a 4-tap conv, got ${c.ssm.dConv}`);
+    if (c.ssm.dState !== 128 || c.ssm.dInner !== c.ssm.vHeads * c.ssm.dState) throw new Error('gdnStep assumes 128-wide heads');
+    this.recurrent = Array.from({ length: c.layers }, (_, l) => (l + 1) % c.attnInterval !== 0);
+    // Prompts go through in chunks of up to chunkTokens tokens per layer (one routing readback per
+    // layer per chunk); decode stays one token at a time.
+    this.batchPrefill = opts.batchPrefill ?? true;
+    this.chunkTokens = Math.max(2, Math.floor(opts.prefillChunk || 256));
+    // gpuRouting: decode syncs with the CPU only at a layer whose experts are not all in the pool
+    // (and every routeWindow layers), instead of after every layer's routing. Opt-in at load: it
+    // compiles every one-token kernel with a stop guard. Off by default until it is timed on a
+    // quiet machine; at 2026-10-04's miss rate (~18 of 40 layers per token need a load) the counts
+    // put the gain near 5%. Output is token-identical either way.
+    this.routeGuards = !!opts.gpuRouting;
+    this.gpuRouting = this.routeGuards;
+    // A submit runs at most this many layers' experts. After a stop every kernel left in it still
+    // dispatches (about 7 ms for a whole token's worth), so a long submit mostly runs no-ops.
+    // Full model, 48 tokens: window 2 → 29.1 syncs and 17.6 no-op layers per token; 3 → 26.2, 36.6.
+    this.routeWindow = Math.max(1, Math.floor(opts.routeWindow ?? 2));
+  }
+
+  // Subgroup GEMVs replace the scalar ones when subgroups are exactly 32 wide (Apple, most others).
+  get subgroupKernels() {
+    const i = this.device.adapterInfo || this.opts.adapterInfo || {};
+    return this.opts.subgroups !== false && this.device.features.has('subgroups') && i.subgroupMinSize === 32 && i.subgroupMaxSize === 32;
+  }
+  // With gpuRouting, every one-token kernel carries the stop guard (chunked prefill's do not).
+  get kernels() {
+    if (!this._kernels) {
+      const k = { ...super.kernels, ...KERNELS, ...(this.subgroupKernels ? SG_KERNELS : {}) };
+      if (this.routeGuards) for (const n of Object.keys(k)) k[n] = guarded(k[n]);
+      this._kernels = { ...k, ...BATCH_KERNELS, route: ROUTE_KERNEL };
+    }
+    return this._kernels;
+  }
+  isGuarded(name) { return this.routeGuards && name !== 'route' && !(name in BATCH_KERNELS); }
+
+  bind(name, buffers) { return super.bind(name, this.isGuarded(name) ? [...buffers, this.a.stop] : buffers); }
+  // Like bind(), but a resource may be { buffer, offset, size }.
+  bindR(name, resources) {
+    const all = this.isGuarded(name) ? [...resources, this.a.stop] : resources;
+    return this.device.createBindGroup({
+      layout: this.pipeline(name).getBindGroupLayout(0),
+      entries: all.map((r, i) => ({ binding: i, resource: r instanceof GPUBuffer ? { buffer: r } : r })),
+    });
+  }
+
+  // For the GPU budget: f16 KV for the attention layers, conv + delta-rule state for the DeltaNet layers.
+  kvBytes() {
+    const c = this.cfg, s = c.ssm, convDim = 2 * s.kHeads * s.dState + s.dInner;
+    return this.recurrent.reduce((sum, r) => sum + (r ? 3 * convDim * 4 + s.vHeads * s.dState * s.dState * 4 : 2 * 2 * this.maxCtx * c.kvHeads * c.headDim), 0);
+  }
+
+  initBuffers() {
+    const c = this.cfg, s = c.ssm;
+    const H = c.hidden, hd = c.headDim, QN = c.heads * hd, kvn = c.kvHeads * hd, F = c.expertFf, SF = c.shexpFf, K = c.topK;
+    const keyDim = s.kHeads * s.dState, convDim = 2 * keyDim + s.dInner;
+    if (2 * K * 4 > 256) throw new Error(`top-k ${K} > 32: selections would overlap their 256-byte readback regions`);
+    if (c.experts > 256) throw new Error(`${c.experts} experts: the router top-k kernel handles at most 256`);
+    if ((SF * 4) % 256) throw new Error('shared expert gate/up halves must be 256-byte aligned');
+
+    // KV cache (f16) for the attention layers; conv + delta-rule state for the DeltaNet layers.
+    this.kc = []; this.vc = []; this.conv = []; this.ssm = [];
+    for (let l = 0; l < c.layers; l++) {
+      if (this.recurrent[l]) {
+        this.conv[l] = this.buffer(3 * convDim * 4, STORAGE | COPY_DST, 'state');
+        this.ssm[l] = this.buffer(s.vHeads * s.dState * s.dState * 4, STORAGE | COPY_DST, 'state');
+      } else {
+        this.kc[l] = this.buffer(this.maxCtx * kvn * 2, STORAGE, 'kv');
+        this.vc[l] = this.buffer(this.maxCtx * kvn * 2, STORAGE, 'kv');
+      }
+    }
+    const A = (n) => this.buffer(n * 4, STORAGE | COPY_SRC | COPY_DST);
+    this.a = {
+      x: A(H), xn: A(H), qg: A(2 * QN), q: A(QN), gate: A(QN), k: A(kvn), kr: A(kvn), v: A(kvn), att: A(QN), o: A(H),
+      sc: A(c.heads * this.maxCtx), mixed: A(convDim), cv: A(convDim), z: A(s.dInner), bb: A(s.vHeads), al: A(s.vHeads),
+      go: A(s.dInner), gn: A(s.dInner), dummy: A(4),
+      rl: A(c.experts), sel: A(2 * K), pxn: A(H), prl: A(c.experts), psel: A(64 * this.lookahead), slots: A(K),
+      gu: A(K * 2 * F), act: A(K * F), dn: A(K * H), shgu: A(2 * SF), shact: A(SF), sh: A(H), sg: A(4),
+      logits: A(c.vocab), am: A(4), rope: A(c.ropeDims),
+      stop: A(4), used: A(c.layers * K), rmap: A(c.layers * c.experts),
+    };
+    this.tok = this.buffer(16, UNIFORM | COPY_DST);
+    this.rbSel = this.buffer(256 * (1 + this.lookahead), MAP_READ | COPY_DST);
+    this.rbLogits = this.buffer(c.vocab * 4, MAP_READ | COPY_DST);
+    this.rbArg = this.buffer(16, MAP_READ | COPY_DST);
+    // One readback per decode sync: [stop | layer's sel | guesses | every layer's picks | argmax].
+    this.seg = { sel: 256, psel: 512, used: 512 + 256 * this.lookahead };
+    this.seg.am = this.seg.used + Math.ceil(c.layers * K * 4 / 16) * 16;
+    this.seg.bytes = this.seg.am + 16;
+    this.rbSeg = this.buffer(this.seg.bytes, MAP_READ | COPY_DST);
+    this.routeMap = new Uint32Array(c.layers * c.experts);
+
+    const U = (w) => this.uniform(w), eps = { f: c.eps };
+    const u = {
+      nH: U([H]), rmsH: U([H, eps]),
+      qg: U([2 * QN, H]), kv: U([kvn, H]), o: U([H, QN]),
+      ropeQ: U([hd, 2 * hd, c.ropeDims, 1, eps]), ropeK: U([hd, hd, c.ropeDims, 0, eps]), kvn: U([kvn]),
+      att: U([c.heads, c.kvHeads, hd, { f: 1 / Math.sqrt(hd) }]), attOut: U([c.heads, c.kvHeads, hd, 0]), gate: U([QN]),
+      qkv: U([convDim, H]), z: U([s.dInner, H]), ab: U([s.vHeads, H]), gout: U([H, s.dInner]),
+      conv: U([convDim]), step: U([s.kHeads, s.dState, keyDim, 0, eps, { f: 1 / Math.sqrt(s.dState) }]), ng: U([s.dState, eps]),
+      router: U([c.experts, H]), topk: U([c.experts, K]),
+      gu: U([2 * F, H, 2 * F, 0]), dn: U([H, F, H, 1]), silu: U([F, K]), acc: U([H, K]),
+      shgu: U([SF, H]), shsilu: U([SF, 1]), shd: U([H, SF]), shgate: U([1, H]),
+      lm: U([c.vocab, H]), am: U([c.vocab]),
+    };
+    const a = this.a, W = this.w;
+    const q8 = (name, x, y, uni) => { const t = W[name]; if (!t || !t.q) throw new Error(`missing Q8_0 tensor ${name}`); return this.bind('matmulQ8', [x, t.q, t.s, y, uni]); };
+    const raw = (name) => { const t = W[name]; if (!t || !t.raw) throw new Error(`missing F32 tensor ${name}`); return t.raw; };
+    this.g = { embed: this.bind('embedQ8', [W['token_embd.weight'].q, W['token_embd.weight'].s, a.x, this.tok, u.nH]) };
+    this.layers = [];
+    for (let l = 0; l < c.layers; l++) {
+      const n = (t) => `blk.${l}.${t}`;
+      const g = { recur: this.recurrent[l], rmsA: this.bind('rmsnorm', [a.x, raw(n('attn_norm.weight')), a.xn, u.rmsH]) };
+      if (g.recur) {
+        Object.assign(g, {
+          qkv: q8(n('attn_qkv.weight'), a.xn, a.mixed, u.qkv),
+          z: q8(n('attn_gate.weight'), a.xn, a.z, u.z),
+          beta: q8(n('ssm_beta.weight'), a.xn, a.bb, u.ab),
+          alpha: q8(n('ssm_alpha.weight'), a.xn, a.al, u.ab),
+          conv: this.bind('gdnConv', [a.mixed, raw(n('ssm_conv1d.weight')), this.conv[l], a.cv, u.conv]),
+          step: this.bind('gdnStep', [a.cv, a.bb, a.al, raw(n('ssm_dt.bias')), raw(n('ssm_a')), this.ssm[l], a.go, u.step]),
+          norm: this.bind('gdnNormGate', [a.go, raw(n('ssm_norm.weight')), a.z, a.gn, u.ng]),
+          out: q8(n('ssm_out.weight'), a.gn, a.o, u.gout),
+        });
+      } else {
+        Object.assign(g, {
+          q: q8(n('attn_q.weight'), a.xn, a.qg, u.qg),
+          k: q8(n('attn_k.weight'), a.xn, a.k, u.kv),
+          v: q8(n('attn_v.weight'), a.xn, a.v, u.kv),
+          ropeQ: this.bind('qkNormRopeP', [a.qg, raw(n('attn_q_norm.weight')), a.rope, a.q, a.gate, u.ropeQ]),
+          ropeK: this.bind('qkNormRopeP', [a.k, raw(n('attn_k_norm.weight')), a.rope, a.kr, a.dummy, u.ropeK]),
+          kv: this.bind('kvStore', [a.kr, a.v, this.kc[l], this.vc[l], this.tok, u.kvn]),
+          score: this.bind('attnScore', [a.q, this.kc[l], a.sc, this.tok, u.att]),
+          soft: this.bind('softmax', [a.sc, this.tok]),
+          attOut: this.bind('attnOut', [a.sc, this.vc[l], a.att, this.tok, u.attOut]),
+          gate: this.bind('sigmoidMul', [a.att, a.gate, u.gate]),
+          o: q8(n('attn_output.weight'), a.att, a.o, u.o),
+        });
+      }
+      Object.assign(g, {
+        addO: this.bind('addInPlace', [a.x, a.o, u.nH]),
+        rmsF: this.bind('rmsnorm', [a.x, raw(n('post_attention_norm.weight')), a.xn, u.rmsH]),
+        router: this.bind('matmulF32', [a.xn, raw(n('ffn_gate_inp.weight')), a.rl, u.router]),
+        topk: this.bind('topk', [a.rl, a.sel, u.topk]),
+        pf: Array.from({ length: Math.min(this.lookahead, c.layers - 1 - l) }, (_, i) => {
+          const at = (t) => `blk.${l + 1 + i}.${t}`;
+          return {
+            rms: this.bind('rmsnorm', [a.x, raw(at('post_attention_norm.weight')), a.pxn, u.rmsH]),
+            router: this.bind('matmulF32', [a.pxn, raw(at('ffn_gate_inp.weight')), a.prl, u.router]),
+            topk: this.bindR('topk', [a.prl, { buffer: a.psel, offset: 256 * i, size: 8 * K }, u.topk]),
+          };
+        }),
+        // Shared expert: [gate | up] into shgu, SiLU·up, down; its scalar gate logit into sg.
+        shg: this.bindR('matmulQ8', [a.xn, W[n('ffn_gate_shexp.weight')].q, W[n('ffn_gate_shexp.weight')].s, { buffer: a.shgu, offset: 0, size: SF * 4 }, u.shgu]),
+        shu: this.bindR('matmulQ8', [a.xn, W[n('ffn_up_shexp.weight')].q, W[n('ffn_up_shexp.weight')].s, { buffer: a.shgu, offset: SF * 4, size: SF * 4 }, u.shgu]),
+        shsilu: this.bind('siluMulMoe', [a.shgu, a.shact, u.shsilu]),
+        shd: q8(n('ffn_down_shexp.weight'), a.shact, a.sh, u.shd),
+        shgate: this.bind('matmulF32', [a.xn, raw(n('ffn_gate_inp_shexp.weight')), a.sg, u.shgate]),
+        gu: this.bind('expertQ8', [a.xn, this.pool.guQ, this.pool.guS, a.gu, u.gu, a.slots]),
+        silu: this.bind('siluMulMoe', [a.gu, a.act, u.silu]),
+        dn: this.bind('expertQ8', [a.act, this.pool.dQ, this.pool.dS, a.dn, u.dn, a.slots]),
+        acc: this.bind('moeAccumShared', [a.dn, a.sel, a.sh, a.sg, a.x, u.acc]),
+        route: this.bind('route', [a.sel, a.rmap, a.slots, a.stop, a.used, U([l, c.experts, K, 0])]),
+      });
+      this.layers.push(g);
+    }
+    this.g.rmsOut = this.bind('rmsnorm', [a.x, raw('output_norm.weight'), a.xn, u.rmsH]);
+    this.g.lm = this.bind('matmulQ8', [a.xn, W['output.weight'].q, W['output.weight'].s, a.logits, u.lm]);
+    this.g.am = this.bind('argmax', [a.logits, a.am, u.am]);
+    // A chunk pins min(experts, T·K) experts per layer at once; keep that under half the pool.
+    if (Math.min(c.experts, this.chunkTokens * K) > this.poolSlots / 2) this.chunkTokens = Math.max(2, Math.floor(this.poolSlots / 2 / K));
+    if (this.batchPrefill) this.initBatch();
+  }
+
+  // Buffers and bind groups for chunked prefill (rows = tokens of the chunk, token-major).
+  initBatch() {
+    const c = this.cfg, s = c.ssm, B = this.chunkTokens, a = this.a, W = this.w;
+    const H = c.hidden, hd = c.headDim, QN = c.heads * hd, kvn = c.kvHeads * hd, F = c.expertFf, SF = c.shexpFf, K = c.topK;
+    const keyDim = s.kHeads * s.dState, convDim = 2 * keyDim + s.dInner;
+    const A = (n) => this.buffer(n * 4, STORAGE | COPY_SRC | COPY_DST, 'batch');
+    const b = this.b = {
+      ids: A(B), x: A(B * H), xn: A(B * H), qg: A(B * 2 * QN), q: A(B * QN), gate: A(B * QN), k: A(B * kvn), kr: A(B * kvn), v: A(B * kvn),
+      att: A(B * QN), o: A(B * H), sc: A(c.heads * B * this.maxCtx), mixed: A(B * convDim), cv: A(B * convDim), z: A(B * s.dInner),
+      bb: A(B * s.vHeads), al: A(B * s.vHeads), go: A(B * s.dInner), gn: A(B * s.dInner),
+      rl: A(B * c.experts), sel: A(B * 2 * K), slots: A(B * K), gu: A(B * K * 2 * F), act: A(B * K * F), dn: A(B * K * H),
+      shg: A(B * SF), shu: A(B * SF), shact: A(B * SF), sh: A(B * H), sg: A(B), rope: A(B * c.ropeDims), dummy: A(4),
+    };
+    this.qb = this.buffer(16, UNIFORM | COPY_DST, 'batch');
+    this.rbSelB = this.buffer(B * 2 * K * 4, MAP_READ | COPY_DST, 'batch');
+    const U = (w) => this.uniform(w), eps = { f: c.eps }, qb = this.qb;
+    const u = {
+      nH: U([H]), rmsH: U([H, eps]), qg: U([2 * QN, H]), kv: U([kvn, H]), o: U([H, QN]),
+      ropeQ: U([hd, 2 * hd, 2 * QN, QN, c.ropeDims, 1, eps]), ropeK: U([hd, hd, kvn, kvn, c.ropeDims, 0, eps]), kvn: U([kvn]),
+      att: U([c.heads, c.kvHeads, hd, { f: 1 / Math.sqrt(hd) }]), attOut: U([c.heads, c.kvHeads, hd, 0]), gate: U([QN]),
+      qkv: U([convDim, H]), z: U([s.dInner, H]), ab: U([s.vHeads, H]), gout: U([H, s.dInner]), conv: U([convDim]),
+      step: U([s.kHeads, s.dState, keyDim, convDim, s.vHeads, 0, eps, { f: 1 / Math.sqrt(s.dState) }]), ng: U([s.dState, s.dInner, eps]),
+      router: U([c.experts, H]), topk: U([c.experts, K]),
+      gu: U([2 * F, H, 2 * F, 0, K]), dn: U([H, F, H, 1, K]), silu: U([F, B * K]), acc: U([H, K]),
+      shgu: U([SF, H]), shd: U([H, SF]), sh2: U([SF]), shgate: U([1, H]),
+    };
+    const raw = (name) => W[name].raw;
+    const q8 = (name, x, y, uni) => this.bind('matmulQ8T', [x, W[name].q, W[name].s, y, uni, qb]);
+    this.gB = { embed: this.bind('embedQ8B', [W['token_embd.weight'].q, W['token_embd.weight'].s, b.ids, b.x, u.nH, qb]) };
+    for (let l = 0; l < c.layers; l++) {
+      const n = (t) => `blk.${l}.${t}`, g = { rmsA: this.bind('rmsnormB', [b.x, raw(n('attn_norm.weight')), b.xn, u.rmsH]) };
+      if (this.recurrent[l]) {
+        Object.assign(g, {
+          qkv: q8(n('attn_qkv.weight'), b.xn, b.mixed, u.qkv), z: q8(n('attn_gate.weight'), b.xn, b.z, u.z),
+          beta: q8(n('ssm_beta.weight'), b.xn, b.bb, u.ab), alpha: q8(n('ssm_alpha.weight'), b.xn, b.al, u.ab),
+          conv: this.bind('gdnConvB', [b.mixed, raw(n('ssm_conv1d.weight')), this.conv[l], b.cv, u.conv, qb]),
+          step: this.bind('gdnStepB', [b.cv, b.bb, b.al, raw(n('ssm_dt.bias')), raw(n('ssm_a')), this.ssm[l], b.go, u.step, qb]),
+          norm: this.bind('gdnNormGateB', [b.go, raw(n('ssm_norm.weight')), b.z, b.gn, u.ng]),
+          out: q8(n('ssm_out.weight'), b.gn, b.o, u.gout),
+        });
+      } else {
+        Object.assign(g, {
+          q: q8(n('attn_q.weight'), b.xn, b.qg, u.qg), k: q8(n('attn_k.weight'), b.xn, b.k, u.kv), v: q8(n('attn_v.weight'), b.xn, b.v, u.kv),
+          ropeQ: this.bind('qkNormRopePB', [b.qg, raw(n('attn_q_norm.weight')), b.rope, b.q, b.gate, u.ropeQ]),
+          ropeK: this.bind('qkNormRopePB', [b.k, raw(n('attn_k_norm.weight')), b.rope, b.kr, b.dummy, u.ropeK]),
+          kv: this.bind('kvStoreB', [b.kr, b.v, this.kc[l], this.vc[l], u.kvn, qb]),
+          score: this.bind('attnScoreB', [b.q, this.kc[l], b.sc, u.att, qb]),
+          soft: this.bind('softmaxB', [b.sc, qb]),
+          attOut: this.bind('attnOutB', [b.sc, this.vc[l], b.att, u.attOut, qb]),
+          gate: this.bind('sigmoidMulB', [b.att, b.gate, u.gate, qb]),
+          o: q8(n('attn_output.weight'), b.att, b.o, u.o),
+        });
+      }
+      Object.assign(g, {
+        addO: this.bind('addInPlaceB', [b.x, b.o, u.nH, qb]),
+        rmsF: this.bind('rmsnormB', [b.x, raw(n('post_attention_norm.weight')), b.xn, u.rmsH]),
+        router: this.bind('matmulF32T', [b.xn, raw(n('ffn_gate_inp.weight')), b.rl, u.router]),
+        topk: this.bind('topkB', [b.rl, b.sel, u.topk]),
+        shg: q8(n('ffn_gate_shexp.weight'), b.xn, b.shg, u.shgu), shu: q8(n('ffn_up_shexp.weight'), b.xn, b.shu, u.shgu),
+        shact: this.bind('siluMul2B', [b.shg, b.shu, b.shact, u.sh2, qb]),
+        shd: q8(n('ffn_down_shexp.weight'), b.shact, b.sh, u.shd),
+        shgate: this.bind('matmulF32T', [b.xn, raw(n('ffn_gate_inp_shexp.weight')), b.sg, u.shgate]),
+        gu: this.bind('expertQ8B', [b.xn, this.pool.guQ, this.pool.guS, b.gu, u.gu, b.slots]),
+        silu: this.bind('siluMulMoe', [b.gu, b.act, u.silu]),
+        dn: this.bind('expertQ8B', [b.act, this.pool.dQ, this.pool.dS, b.dn, u.dn, b.slots]),
+        acc: this.bind('moeAccumSharedB', [b.dn, b.sel, b.sh, b.sg, b.x, u.acc, qb]),
+      });
+      this.layers[l].B = g;
+    }
+  }
+
+  // Layer l over the chunk's T tokens up to its routing (the batched twin of encodeAttention).
+  encodeTrunkB(pass, l, T, S) {
+    const c = this.cfg, s = c.ssm, g = this.layers[l].B, d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    const H = c.hidden, QN = c.heads * c.headDim, kvn = c.kvHeads * c.headDim, convDim = 2 * s.kHeads * s.dState + s.dInner;
+    const tt = Math.ceil(T / 16), mm = (n) => Math.ceil(n / 16);
+    d('rmsnormB', g.rmsA, T);
+    if (this.recurrent[l]) {
+      d('matmulQ8T', g.qkv, mm(convDim), tt); d('matmulQ8T', g.z, mm(s.dInner), tt);
+      d('matmulQ8T', g.beta, mm(s.vHeads), tt); d('matmulQ8T', g.alpha, mm(s.vHeads), tt);
+      d('gdnConvB', g.conv, Math.ceil(convDim / 256));
+      d('gdnStepB', g.step, s.vHeads);
+      d('gdnNormGateB', g.norm, s.vHeads, T);
+      d('matmulQ8T', g.out, mm(H), tt);
+    } else {
+      d('matmulQ8T', g.q, mm(2 * QN), tt); d('matmulQ8T', g.k, mm(kvn), tt); d('matmulQ8T', g.v, mm(kvn), tt);
+      d('qkNormRopePB', g.ropeQ, c.heads, T); d('qkNormRopePB', g.ropeK, c.kvHeads, T);
+      d('kvStoreB', g.kv, Math.ceil(kvn / 256), T);
+      d('attnScoreB', g.score, Math.ceil(c.heads * T * S / 256));
+      d('softmaxB', g.soft, c.heads * T);
+      d('attnOutB', g.attOut, Math.ceil(QN / 256), T);
+      d('sigmoidMulB', g.gate, Math.ceil(QN / 256), T);
+      d('matmulQ8T', g.o, mm(H), tt);
+    }
+    d('addInPlaceB', g.addO, Math.ceil(H / 256), T);
+    d('rmsnormB', g.rmsF, T);
+    d('matmulF32T', g.router, c.experts, T);
+    d('topkB', g.topk, T);
+    d('matmulQ8T', g.shg, mm(c.shexpFf), tt); d('matmulQ8T', g.shu, mm(c.shexpFf), tt);
+    d('siluMul2B', g.shact, Math.ceil(c.shexpFf / 256), T);
+    d('matmulQ8T', g.shd, mm(H), tt);
+    d('matmulF32T', g.shgate, 1, T);
+  }
+
+  encodeExpertsB(pass, l, T) {
+    const c = this.cfg, g = this.layers[l].B, d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    d('expertQ8B', g.gu, Math.ceil(2 * c.expertFf / 4), 1, T * c.topK);
+    d('siluMulMoe', g.silu, Math.ceil(T * c.topK * c.expertFf / 256));
+    d('expertQ8B', g.dn, Math.ceil(c.hidden / 4), 1, T * c.topK);
+    d('moeAccumSharedB', g.acc, Math.ceil(c.hidden / 256), T);
+  }
+
+  // Feeds T = ids.length tokens at this.position through every layer: one routing readback per
+  // layer, the union of the chunk's experts loaded once. want: 'none' | 'argmax' | 'logits' for
+  // the last token, as in step().
+  async prefillChunk(ids, want = 'none') {
+    const c = this.cfg, dev = this.device, K = c.topK, H = c.hidden, T = ids.length, pos0 = this.position, S = pos0 + T;
+    if (T > this.chunkTokens) throw new Error(`chunk of ${T} > ${this.chunkTokens}`);
+    if (S > this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    const tStart = performance.now();
+    dev.queue.writeBuffer(this.a.stop, 0, new Uint32Array(4));   // the head below uses guarded kernels
+    dev.queue.writeBuffer(this.b.ids, 0, Uint32Array.from(ids));
+    dev.queue.writeBuffer(this.qb, 0, new Uint32Array([T, pos0, S, 0]));
+    const nRot = c.ropeDims, half = nRot / 2, r = new Float32Array(T * nRot), stepR = Math.fround(Math.pow(c.ropeTheta, -2 / nRot));
+    for (let t = 0; t < T; t++) {
+      let th = Math.fround(pos0 + t);
+      for (let i = 0; i < half; i++) { r[t * nRot + i] = Math.cos(th); r[t * nRot + half + i] = Math.sin(th); th = Math.fround(th * stepR); }
+    }
+    dev.queue.writeBuffer(this.b.rope, 0, r);
+    const selBytes = T * 2 * K * 4;
+    let enc = dev.createCommandEncoder(), pass = enc.beginComputePass();
+    this.dispatch(pass, 'embedQ8B', this.gB.embed, Math.ceil(H / 256), T);
+    this.encodeTrunkB(pass, 0, T, S);
+    pass.end();
+    enc.copyBufferToBuffer(this.b.sel, 0, this.rbSelB, 0, selBytes);
+    dev.queue.submit([enc.finish()]);
+    for (let l = 0; l < c.layers; l++) {
+      const t0 = performance.now();
+      await this.rbSelB.mapAsync(1, 0, selBytes);
+      this.counters.gpuWaitMs += performance.now() - t0;
+      const sel = new Uint32Array(this.rbSelB.getMappedRange(0, selBytes).slice(0));
+      this.rbSelB.unmap();
+      const pairs = new Uint32Array(T * K);
+      for (let t = 0; t < T; t++) for (let j = 0; j < K; j++) pairs[t * K + j] = sel[t * 2 * K + j];
+      const unique = [...new Set(pairs)];
+      const tq = performance.now();
+      const slotsU = await this.xs.ensure(l, unique);
+      this.counters.ensureMs += performance.now() - tq;
+      const slotOf = new Map(unique.map((e, i) => [e, slotsU[i]]));
+      const pairSlots = pairs.map((e) => slotOf.get(e));
+      dev.queue.writeBuffer(this.b.slots, 0, pairSlots);
+      enc = dev.createCommandEncoder(); pass = enc.beginComputePass();
+      this.encodeExpertsB(pass, l, T);
+      if (l + 1 < c.layers) {
+        this.encodeTrunkB(pass, l + 1, T, S);
+        pass.end();
+        enc.copyBufferToBuffer(this.b.sel, 0, this.rbSelB, 0, selBytes);
+      } else {
+        pass.end();
+        enc.copyBufferToBuffer(this.b.x, (T - 1) * H * 4, this.a.x, 0, H * 4);
+        if (want !== 'none') {
+          pass = enc.beginComputePass();
+          this.dispatch(pass, 'rmsnorm', this.g.rmsOut, 1);
+          this.dispatch(pass, 'matmulQ8', this.g.lm, Math.ceil(c.vocab / 4));
+          if (want === 'argmax') this.dispatch(pass, 'argmax', this.g.am, 1);
+          pass.end();
+          if (want === 'argmax') enc.copyBufferToBuffer(this.a.am, 0, this.rbArg, 0, 4);
+          if (want === 'logits') enc.copyBufferToBuffer(this.a.logits, 0, this.rbLogits, 0, c.vocab * 4);
+        }
+      }
+      dev.queue.submit([enc.finish()]);
+      this.xs.release(slotsU);
+    }
+    this.position += T;
+    this.cached.push(...ids);
+    let result = null;
+    if (want === 'argmax') {
+      await this.rbArg.mapAsync(1, 0, 4);
+      result = new Uint32Array(this.rbArg.getMappedRange(0, 4))[0];
+      this.rbArg.unmap();
+    } else if (want === 'logits') {
+      await this.rbLogits.mapAsync(1);
+      result = new Float32Array(this.rbLogits.getMappedRange().slice(0));
+      this.rbLogits.unmap();
+    } else {
+      await dev.queue.onSubmittedWorkDone();
+    }
+    this.counters.tokens += T;
+    this.counters.wallMs += performance.now() - tStart;
+    return result;
+  }
+
+  // Layer l up to its routing: the trunk (DeltaNet or gated attention), residual, post-norm,
+  // router + top-k (and the prefetch guesses), and the shared expert, which needs no routing.
+  encodeAttention(pass, l, seqLen) {
+    const c = this.cfg, s = c.ssm, g = this.layers[l], d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    const H = c.hidden, QN = c.heads * c.headDim, kvn = c.kvHeads * c.headDim, convDim = 2 * s.kHeads * s.dState + s.dInner;
+    d('rmsnorm', g.rmsA, 1);
+    if (g.recur) {
+      d('matmulQ8', g.qkv, Math.ceil(convDim / 4)); d('matmulQ8', g.z, Math.ceil(s.dInner / 4));
+      d('matmulQ8', g.beta, Math.ceil(s.vHeads / 4)); d('matmulQ8', g.alpha, Math.ceil(s.vHeads / 4));
+      d('gdnConv', g.conv, Math.ceil(convDim / 256));
+      d('gdnStep', g.step, s.vHeads);
+      d('gdnNormGate', g.norm, s.vHeads);
+      d('matmulQ8', g.out, Math.ceil(H / 4));
+    } else {
+      d('matmulQ8', g.q, Math.ceil(2 * QN / 4)); d('matmulQ8', g.k, Math.ceil(kvn / 4)); d('matmulQ8', g.v, Math.ceil(kvn / 4));
+      d('qkNormRopeP', g.ropeQ, c.heads); d('qkNormRopeP', g.ropeK, c.kvHeads);
+      d('kvStore', g.kv, Math.ceil(kvn / 256));
+      d('attnScore', g.score, Math.ceil(c.heads * seqLen / 256));
+      d('softmax', g.soft, c.heads);
+      d('attnOut', g.attOut, Math.ceil(QN / 256));
+      d('sigmoidMul', g.gate, Math.ceil(QN / 256));
+      d('matmulQ8', g.o, Math.ceil(H / 4));
+    }
+    d('addInPlace', g.addO, Math.ceil(H / 256));
+    if (this.prefetch) for (const p of g.pf) { d('rmsnorm', p.rms, 1); d('matmulF32', p.router, c.experts); d('topk', p.topk, 1); }
+    d('rmsnorm', g.rmsF, 1);
+    d('matmulF32', g.router, c.experts);
+    d('topk', g.topk, 1);
+    d('matmulQ8', g.shg, Math.ceil(c.shexpFf / 4)); d('matmulQ8', g.shu, Math.ceil(c.shexpFf / 4));
+    d('siluMulMoe', g.shsilu, Math.ceil(c.shexpFf / 256));
+    d('matmulQ8', g.shd, Math.ceil(H / 4));
+    d('matmulF32', g.shgate, 1);
+  }
+
+  encodeExperts(pass, l) {
+    const c = this.cfg, g = this.layers[l], d = (nm, gr, x, y, z) => this.dispatch(pass, nm, gr, x, y, z);
+    d('expertQ8', g.gu, Math.ceil(2 * c.expertFf / 4), 1, c.topK);
+    d('siluMulMoe', g.silu, Math.ceil(c.topK * c.expertFf / 256));
+    d('expertQ8', g.dn, Math.ceil(c.hidden / 4), 1, c.topK);
+    d('moeAccumShared', g.acc, Math.ceil(c.hidden / 256));
+  }
+
+  // The pool's residency as the route kernel reads it: slot of (layer, expert), or ABSENT. Built
+  // from the streamer's slot keys, which are set only once an expert's upload has been submitted.
+  // Queue order keeps it safe: an upload into a slot runs after every submit made before it.
+  writeRouteMap() {
+    const map = this.routeMap, key = this.xs.slotKey;
+    map.fill(ABSENT);
+    for (let s = 0; s < key.length; s++) if (key[s] >= 0) map[key[s]] = s;
+    this.device.queue.writeBuffer(this.a.rmap, 0, map);
+  }
+
+  // One token with routing on the GPU. Each submit runs up to routeWindow layers and routes the
+  // layer after them; the route kernel stops it early at the first layer with an expert outside
+  // the pool. Either way the CPU then ensures the next layer's experts (loading any absent ones and
+  // prefetching the guesses for the layers after it) and resumes at that layer's experts:
+  // everything it computed before routing (x, xn, sel, shared expert) is still in place, since
+  // every kernel after a stop returns without writing.
+  async step(token, want = 'argmax') {
+    if (!this.gpuRouting) return super.step(token, want);
+    const c = this.cfg, dev = this.device, K = c.topK, L = c.layers, seg = this.seg;
+    if (this.position >= this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    const tStart = performance.now();
+    const pos = this.position, seqLen = pos + 1;
+    this.writeTokenUniforms(token, pos);
+    // resume: -1 starts at the embedding; l ≥ 0 resumes at layer l's experts (its trunk already ran,
+    // and a DeltaNet trunk must not run twice: it advances the recurrent state).
+    let resume = -1, slots = null, result = null;
+    for (;;) {
+      const te = performance.now();
+      this.writeRouteMap();
+      dev.queue.writeBuffer(this.a.stop, 0, new Uint32Array(4));
+      if (slots) dev.queue.writeBuffer(this.a.slots, 0, slots);
+      const enc = dev.createCommandEncoder(), pass = enc.beginComputePass();
+      if (resume < 0) {
+        this.dispatch(pass, 'embedQ8', this.g.embed, Math.ceil(c.hidden / 256));
+        this.encodeAttention(pass, 0, seqLen);
+        this.dispatch(pass, 'route', this.layers[0].route, 1);
+      }
+      const first = Math.max(0, resume), last = Math.min(L - 1, first + this.routeWindow - 1);
+      for (let l = first; l <= last; l++) {
+        this.encodeExperts(pass, l);
+        if (l + 1 < L) { this.encodeAttention(pass, l + 1, seqLen); this.dispatch(pass, 'route', this.layers[l + 1].route, 1); }
+      }
+      if (last === L - 1 && want !== 'none') {
+        this.dispatch(pass, 'rmsnorm', this.g.rmsOut, 1);
+        this.dispatch(pass, 'matmulQ8', this.g.lm, Math.ceil(c.vocab / 4));
+        if (want === 'argmax') this.dispatch(pass, 'argmax', this.g.am, 1);
+      }
+      pass.end();
+      enc.copyBufferToBuffer(this.a.stop, 0, this.rbSeg, 0, 16);
+      enc.copyBufferToBuffer(this.a.sel, 0, this.rbSeg, seg.sel, 8 * K);
+      if (this.prefetch) enc.copyBufferToBuffer(this.a.psel, 0, this.rbSeg, seg.psel, 256 * this.lookahead);
+      enc.copyBufferToBuffer(this.a.used, 0, this.rbSeg, seg.used, L * K * 4);
+      if (last === L - 1 && want === 'argmax') enc.copyBufferToBuffer(this.a.am, 0, this.rbSeg, seg.am, 4);
+      if (last === L - 1 && want === 'logits') enc.copyBufferToBuffer(this.a.logits, 0, this.rbLogits, 0, c.vocab * 4);
+      dev.queue.submit([enc.finish()]);
+      if (slots) { this.xs.release(slots); slots = null; }
+      this.counters.encodeMs += performance.now() - te;
+      this.counters.syncs++;
+      this.counters.layersEncoded += last - first + 1;
+
+      const tw = performance.now();
+      await this.rbSeg.mapAsync(1, 0, seg.bytes);
+      this.counters.gpuWaitMs += performance.now() - tw;
+      const u = new Uint32Array(this.rbSeg.getMappedRange(0, seg.bytes).slice(0));
+      this.rbSeg.unmap();
+      const stopL = u[0] ? u[0] - 1 : last + 1;
+      // Layers this submit routed and ran on the GPU: refresh them in the LRU. (A resumed layer went
+      // through ensure() already.)
+      for (let l = resume + 1; l < stopL; l++) this.xs.touchUsed(l, u.subarray(seg.used / 4 + l * K, seg.used / 4 + (l + 1) * K));
+      if (stopL === L) {
+        if (want === 'argmax') result = u[seg.am / 4];
+        break;
+      }
+      const ids = u.slice(seg.sel / 4, seg.sel / 4 + K);
+      const tq = performance.now();
+      const ensuring = this.xs.ensure(stopL, ids);
+      if (this.prefetch) {
+        const n = this.layers[stopL].pf.length;
+        for (let i = 0; i < n; i++) this.xs.prefetch(stopL + 1 + i, u.subarray(seg.psel / 4 + 64 * i, seg.psel / 4 + 64 * i + K));
+      }
+      slots = await ensuring;
+      this.counters.ensureMs += performance.now() - tq;
+      resume = stopL;
+    }
+    if (want === 'logits') {
+      const tw = performance.now();
+      await this.rbLogits.mapAsync(1);
+      this.counters.gpuWaitMs += performance.now() - tw;
+      result = new Float32Array(this.rbLogits.getMappedRange().slice(0));
+      this.rbLogits.unmap();
+    }
+    this.position++;
+    this.cached.push(token);
+    this.counters.tokens++;
+    this.counters.wallMs += performance.now() - tStart;
+    return result;
+  }
+
+  resetCounters() { super.resetCounters(); this.counters.syncs = 0; this.counters.layersEncoded = 0; }
+  // layersEncodedPerToken − layers = expert blocks dispatched after a stop (no-ops).
+  stats() {
+    const n = Math.max(1, this.counters.tokens);
+    return { ...super.stats(), gpuRouting: this.gpuRouting, routeWindow: this.routeWindow, syncsPerToken: this.counters.syncs / n, layersEncodedPerToken: this.counters.layersEncoded / n };
+  }
+
+  // RoPE angles as ggml's CPU rope cache forms them for text positions (all M-RoPE sections at
+  // the token position): θ = pos, multiplied by base^(-2/nRot) once per pair, in f32.
+  writeTokenUniforms(token, pos) {
+    const c = this.cfg, nRot = c.ropeDims, half = nRot / 2;
+    this.device.queue.writeBuffer(this.tok, 0, new Uint32Array([token, pos, pos + 1, 0]));
+    const r = new Float32Array(nRot), step = Math.fround(Math.pow(c.ropeTheta, -2 / nRot));
+    let th = Math.fround(pos);
+    for (let i = 0; i < half; i++) { r[i] = Math.cos(th); r[half + i] = Math.sin(th); th = Math.fround(th * step); }
+    this.device.queue.writeBuffer(this.a.rope, 0, r);
+  }
+
+  // Qwen3.5/3.6's template opens the reasoning block in the generation prompt when thinking is on.
+  chatPrompt(messages, { enableThinking = true } = {}) {
+    let p = '';
+    for (const m of messages) p += `<|im_start|>${m.role}\n${m.content}<|im_end|>\n`;
+    return p + '<|im_start|>assistant\n' + (enableThinking ? '<think>\n' : '<think>\n\n</think>\n\n');
+  }
+
+  // The recurrent state cannot rewind to an earlier position, so any change before the cached
+  // end restarts from token 0.
+  reset() {
+    super.reset();
+    if (!this.conv) return;
+    const enc = this.device.createCommandEncoder();
+    for (let l = 0; l < this.cfg.layers; l++) if (this.recurrent[l]) { enc.clearBuffer(this.conv[l]); enc.clearBuffer(this.ssm[l]); }
+    this.device.queue.submit([enc.finish()]);
+  }
+
+  async prefill(ids, want = 'argmax') {
+    let common = 0;
+    while (common < ids.length - 1 && common < this.cached.length && this.cached[common] === ids[common]) common++;
+    if (common < this.cached.length) this.reset();
+    const rest = ids.slice(this.cached.length);
+    if (!this.batchPrefill || rest.length < 2) return super.prefill(ids, want);
+    let r = null;
+    for (let i = 0; i < rest.length; i += this.chunkTokens) {
+      r = await this.prefillChunk(rest.slice(i, i + this.chunkTokens), i + this.chunkTokens >= rest.length ? want : 'none');
+    }
+    return r;
+  }
+}
+
+// For kernel tests (scripts): the WGSL this module adds.
+export { KERNELS as QWEN35_KERNELS, BATCH_KERNELS as QWEN35_BATCH_KERNELS, SG_KERNELS as QWEN35_SG_KERNELS };

engines/qwen3_moe_ssd.js

@@ -0,0 +1,1035 @@
+/* qwen3_moe_ssd.js — Qwen3-MoE (Qwen3-30B-A3B) in a browser tab, larger than RAM: the dense
+ * weights, routers and KV cache live on the GPU; the 6,144 routed experts (≈31 GB at Q8_0)
+ * live in OPFS and stream into a GPU slot pool as the router asks for them.
+ *
+ * Rung 2a of the SSD-streaming ladder (plan/pending.md). From-scratch WebGPU engine; the
+ * kernels are ports of browser-big-fast-lab's custom-kernels engine (an Apache-2.0 fork of
+ * tylerstraub/gemma4-webgpu): in-shader Q8_0 GEMV (int8 + f16 scale per 32-block, f32
+ * accumulate), GPU softmax + top-k router, slot-indexed batched expert GEMVs, MoE combine.
+ *
+ *   const m = await Qwen3MoeSsd.load('Qwen/Qwen3-30B-A3B-GGUF', { fetch, onProgress, poolBytes });
+ *   for await (const { text } of m.generate(messages, { maxNewTokens })) …
+ *
+ * Load = (first time only) ingest the GGUF into OPFS in the engine's own layout, then upload
+ * the dense part to the GPU. OPFS layout under localmind-ssd/<key>/:
+ *   header.bin     the GGUF header bytes (metadata + tokenizer), re-parsed at every load
+ *   dense.bin      every non-expert tensor; Q8_0 split losslessly into int8 + f16-scale planes
+ *   experts.bin    one 5,013,504-byte record per (layer, expert), gate‖up‖down contiguous
+ *   manifest.json  source (repo, revision, sha256, size) + every offset above
+ * Q8_0 is never re-quantized: each block's f16 scale and 32 int8 values are copied bit-exact,
+ * so the engine computes the same dot products llama.cpp does, up to summation order.
+ */
+
+import { OpfsReaderPool, readOpfsText } from '../src/opfs-reader.js';
+import { ExpertStreamer } from '../src/expert-stream.js';
+// The store layer is diskformer.js's (github.com/NakliTechie/diskformer.js), byte-identical copies: gguf.js, ingest.js.
+import { GGML, Q8_BLOCK, Q4_BLOCK, Q6K_BLOCK, parseGguf, tensorBytes } from '../src/gguf.js';
+import { ingestGguf as ingestStore, ingestProgress, storeKey, removeStore } from '../src/ingest.js';
+export { GGML, Q4_BLOCK, Q6K_BLOCK, parseGguf, tensorBytes, splitQ4 } from '../src/gguf.js';
+export { ingestProgress } from '../src/ingest.js';
+
+export const QWEN3_30B_A3B = {
+  repo: 'Qwen/Qwen3-30B-A3B-GGUF',
+  file: 'Qwen3-30B-A3B-Q8_0.gguf',
+  revision: 'e4d4bafdfb96a411a163846265362aceb0b9c63a',
+  sha256: '4ad960d180b16f56024f5b704697e5dd5b0837167c2e515ef0569abfc599743c',
+  size: 32483931648,
+};
+const FORMAT = 'localmind-qwen3moe-ssd/1';
+const OPFS_ROOT = 'localmind-ssd';
+
+// ── GGUF ────────────────────────────────────────────────────────────────────
+// qwen3moe (rung 2a) and qwen35moe (Qwen3.5/3.6 MoE, rung 2b: qwen35_moe_ssd.js) share the
+// expert layout; qwen35moe adds the Gated DeltaNet (ssm.*), partial RoPE and a shared expert.
+export function configFromGguf(kv) {
+  const a = kv['general.architecture'];
+  if (a !== 'qwen3moe' && a !== 'qwen35moe') throw new Error(`expected a qwen3moe or qwen35moe GGUF, got ${a}`);
+  const g = (k) => kv[`${a}.${k}`];
+  const extra = a !== 'qwen35moe' ? {} : {
+    ropeDims: g('rope.dimension_count'), shexpFf: g('expert_shared_feed_forward_length'),
+    attnInterval: g('full_attention_interval') || 4,
+    ssm: { dConv: g('ssm.conv_kernel'), dInner: g('ssm.inner_size'), dState: g('ssm.state_size'), vHeads: g('ssm.time_step_rank'), kHeads: g('ssm.group_count') },
+  };
+  return {
+    ...extra,
+    arch: a,
+    layers: g('block_count'), hidden: g('embedding_length'),
+    heads: g('attention.head_count'), kvHeads: g('attention.head_count_kv'),
+    headDim: g('attention.key_length') || g('embedding_length') / g('attention.head_count'),
+    experts: g('expert_count'), topK: g('expert_used_count'), expertFf: g('expert_feed_forward_length'),
+    ropeTheta: g('rope.freq_base'), eps: g('attention.layer_norm_rms_epsilon'),
+    contextLength: g('context_length'),
+    vocab: kv['tokenizer.ggml.tokens'].length,
+    bos: kv['tokenizer.ggml.bos_token_id'], eos: kv['tokenizer.ggml.eos_token_id'],
+  };
+}
+
+// The engine's OPFS layout, derived from the header alone (ingest and load agree on it).
+export function planLayout(gguf) {
+  const cfg = configFromGguf(gguf.kv);
+  const H = cfg.hidden, F = cfg.expertFf;
+  const qBytes = F * H;                  // one projection's int8 plane
+  const sBytes = (F * H / 32) * 2;       // its f16 scale plane
+  const parts = {
+    guQ: { off: 0, bytes: 2 * qBytes },               // gate rows 0..F-1, up rows F..2F-1
+    guS: { off: 2 * qBytes, bytes: 2 * sBytes },
+    dQ: { off: 2 * qBytes + 2 * sBytes, bytes: qBytes },
+    dS: { off: 3 * qBytes + 2 * sBytes, bytes: sBytes },
+  };
+  const record = 3 * qBytes + 3 * sBytes;
+  const dense = {};
+  let off = 0;
+  const take = (n) => { const o = off; off += Math.ceil(n / 256) * 256; return o; };
+  for (const t of gguf.tensors) {
+    if (/_exps\.weight$/.test(t.name)) continue;
+    const n = t.dims.reduce((a, b) => a * b, 1);
+    if (t.type === GGML.Q8_0) {
+      dense[t.name] = { type: 'q8', dims: t.dims, q: { off: take(n), bytes: n }, s: { off: take(n / 16), bytes: n / 16 } };
+    } else if (t.type === GGML.F32) {
+      dense[t.name] = { type: 'f32', dims: t.dims, raw: { off: take(n * 4), bytes: n * 4 } };
+    } else throw new Error(`dense tensor ${t.name}: unsupported type ${t.type}`);
+  }
+  return {
+    config: cfg,
+    experts: { file: 'experts.bin', record, parts, layers: cfg.layers, perLayer: cfg.experts, bytes: record * cfg.layers * cfg.experts },
+    dense: { file: 'dense.bin', bytes: off, tensors: dense },
+  };
+}
+
+// ── Ingest: GGUF (over HTTP Range) → OPFS, in the engine layout ─────────────
+// Every byte range of the GGUF the engine keeps, as units small enough to transform in
+// memory: one unit per expert slice, row bands for dense Q8_0, whole F32 tensors.
+function planUnits(gguf, layout) {
+  const units = [];
+  const { record, parts, perLayer } = layout.experts;
+  const qBytes = parts.dQ.bytes, sBytes = parts.dS.bytes;
+  for (const t of gguf.tensors) {
+    const abs = gguf.dataStart + t.offset;
+    const m = /^blk\.(\d+)\.ffn_(gate|up|down)_exps\.weight$/.exec(t.name);
+    if (m) {
+      const layer = Number(m[1]), which = m[2];
+      if (t.type !== GGML.Q8_0) throw new Error(`${t.name}: experts must be Q8_0`);
+      const slice = tensorBytes(t) / perLayer;
+      const qOff = which === 'gate' ? parts.guQ.off : which === 'up' ? parts.guQ.off + qBytes : parts.dQ.off;
+      const sOff = which === 'gate' ? parts.guS.off : which === 'up' ? parts.guS.off + sBytes : parts.dS.off;
+      for (let e = 0; e < perLayer; e++) {
+        const rec = (layer * perLayer + e) * record;
+        units.push({ src: abs + e * slice, len: slice, file: 'experts', q: rec + qOff, s: rec + sOff });
+      }
+      continue;
+    }
+    const d = layout.dense.tensors[t.name];
+    if (d.type === 'f32') { units.push({ src: abs, len: d.raw.bytes, file: 'dense', raw: d.raw.off }); continue; }
+    const cols = t.dims[0], rows = d.q.bytes / cols, rowBytes = (cols / 32) * Q8_BLOCK;
+    const band = Math.max(1, Math.floor((8 << 20) / rowBytes));
+    for (let r = 0; r < rows; r += band) {
+      const nr = Math.min(band, rows - r);
+      units.push({ src: abs + r * rowBytes, len: nr * rowBytes, file: 'dense', q: d.q.off + r * cols, s: d.s.off + r * cols / 16 });
+    }
+  }
+  units.sort((a, b) => a.src - b.src);
+  return units;
+}
+
+// The ingest is diskformer's ingestGguf with this engine's store folder and layout tag (kept, so stores written
+// before the split stay valid); `plan` lets another architecture supply its own layout (Gemma 4: gemma4_moe_ssd.js).
+export function ingestGguf(opts) {
+  return ingestStore({ ...opts, root: opts.root || OPFS_ROOT, format: FORMAT, plan: opts.plan || { layout: planLayout, units: planUnits } });
+}
+
+// ── Tokenizer: byte-level BPE from the GGUF vocab (tokenizer.ggml.model = gpt2, pre = qwen2) ──
+// Same pre-tokenizer regex llama.cpp uses for LLAMA_VOCAB_PRE_TYPE_QWEN2.
+const QWEN2_PRE = /(?:'[sS]|'[tT]|'[rR][eE]|'[vV][eE]|'[mM]|'[lL][lL]|'[dD])|[^\r\n\p{L}\p{N}]?\p{L}+|\p{N}| ?[^\s\p{L}\p{N}]+[\r\n]*|\s*[\r\n]+|\s+(?!\S)|\s+/gu;
+// LLAMA_VOCAB_PRE_TYPE_QWEN35 (Qwen3.5/3.6): combining marks (\p{M}) count as part of a word.
+const QWEN35_PRE = /(?:'[sS]|'[tT]|'[rR][eE]|'[vV][eE]|'[mM]|'[lL][lL]|'[dD])|[^\r\n\p{L}\p{N}]?[\p{L}\p{M}]+|\p{N}| ?[^\s\p{L}\p{M}\p{N}]+[\r\n]*|\s*[\r\n]+|\s+(?!\S)|\s+/gu;
+
+function byteToUnicode() {
+  const bs = [];
+  for (let i = 33; i <= 126; i++) bs.push(i);
+  for (let i = 161; i <= 172; i++) bs.push(i);
+  for (let i = 174; i <= 255; i++) bs.push(i);
+  const cs = bs.slice();
+  let n = 0;
+  for (let b = 0; b < 256; b++) if (!bs.includes(b)) { bs.push(b); cs.push(256 + n); n++; }
+  const enc = new Array(256), dec = new Map();
+  bs.forEach((b, i) => { enc[b] = String.fromCodePoint(cs[i]); dec.set(String.fromCodePoint(cs[i]), b); });
+  return { enc, dec };
+}
+
+export class BpeTokenizer {
+  constructor(kv) {
+    this.tokens = kv['tokenizer.ggml.tokens'];
+    this.preRe = kv['tokenizer.ggml.pre'] === 'qwen35' ? QWEN35_PRE : QWEN2_PRE;
+    const types = kv['tokenizer.ggml.token_type'] || [];
+    this.ids = new Map(this.tokens.map((t, i) => [t, i]));
+    this.ranks = new Map((kv['tokenizer.ggml.merges'] || []).map((m, i) => [m, i]));
+    this.special = [];
+    this.isSpecial = new Uint8Array(this.tokens.length);
+    for (let i = 0; i < this.tokens.length; i++) if (types[i] === 3 || types[i] === 4) { this.special.push(this.tokens[i]); this.isSpecial[i] = 1; }
+    this.special.sort((a, b) => b.length - a.length);
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    this.specialRe = this.special.length ? new RegExp(`(${this.special.map(esc).join('|')})`) : null;
+    const { enc, dec } = byteToUnicode();
+    this.byteEnc = enc; this.byteDec = dec;
+    this.cache = new Map();
+    this.utf8 = new TextEncoder();
+  }
+  bpe(word) {
+    const hit = this.cache.get(word);
+    if (hit) return hit;
+    let parts = Array.from(word);
+    while (parts.length > 1) {
+      let best = -1, bestRank = Infinity;
+      for (let i = 0; i < parts.length - 1; i++) {
+        const r = this.ranks.get(parts[i] + ' ' + parts[i + 1]);
+        if (r !== undefined && r < bestRank) { bestRank = r; best = i; }
+      }
+      if (best < 0) break;
+      parts = [...parts.slice(0, best), parts[best] + parts[best + 1], ...parts.slice(best + 2)];
+    }
+    const ids = parts.map((p) => {
+      const id = this.ids.get(p);
+      if (id === undefined) throw new Error(`BPE: no token for ${JSON.stringify(p)}`);
+      return id;
+    });
+    if (this.cache.size < 50000) this.cache.set(word, ids);
+    return ids;
+  }
+  // parseSpecial: special-token text (e.g. <|im_start|>) maps to its single id.
+  encode(text, { parseSpecial = true } = {}) {
+    const out = [];
+    const pieces = parseSpecial && this.specialRe ? text.split(this.specialRe) : [text];
+    for (let i = 0; i < pieces.length; i++) {
+      const piece = pieces[i];
+      if (!piece) continue;
+      if (parseSpecial && i % 2 === 1) { out.push(this.ids.get(piece)); continue; }
+      for (const m of piece.matchAll(this.preRe)) {
+        let s = '';
+        for (const b of this.utf8.encode(m[0])) s += this.byteEnc[b];
+        out.push(...this.bpe(s));
+      }
+    }
+    return out;
+  }
+  tokenBytes(id) {
+    const t = this.tokens[id];
+    if (this.isSpecial[id]) return this.utf8.encode(t);
+    const bytes = [];
+    for (const ch of t) { const b = this.byteDec.get(ch); if (b !== undefined) bytes.push(b); }
+    return Uint8Array.from(bytes);
+  }
+  decode(ids) {
+    const chunks = ids.map((id) => this.tokenBytes(id));
+    const n = chunks.reduce((a, c) => a + c.length, 0), all = new Uint8Array(n);
+    let o = 0; for (const c of chunks) { all.set(c, o); o += c.length; }
+    return new TextDecoder().decode(all);
+  }
+}
+
+export function chatPrompt(messages, { enableThinking = true } = {}) {
+  let s = '';
+  for (const m of messages) s += `<|im_start|>${m.role}\n${m.content}<|im_end|>\n`;
+  s += '<|im_start|>assistant\n';
+  if (!enableThinking) s += '<think>\n\n</think>\n\n';
+  return s;
+}
+
+// ── WGSL ────────────────────────────────────────────────────────────────────
+// Activations f32 throughout; Q8_0 weights as an int8 plane (u32-packed) + an f16 scale per
+// 32 values, dequantized exactly in f32 inside the GEMV; KV cache f16 (llama.cpp's default).
+export const TOK = 'struct Tok { token: u32, pos: u32, seqLen: u32, pad: u32 }';
+export const I8 = `fn i8at(w: u32, lane: u32) -> f32 { let b = (w >> (lane * 8u)) & 0xffu; return f32(select(i32(b), i32(b) - 256, b >= 128u)); }`;
+const WGSL = {
+  embedQ8: `enable f16;
+${TOK}
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read> q: array<u32>;
+@group(0) @binding(1) var<storage, read> s: array<f16>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> tok: Tok;
+@group(0) @binding(4) var<uniform> p: P;
+${I8}
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i >= p.n) { return; }
+  let e = tok.token * p.n + i;
+  y[i] = i8at(q[e >> 2u], e & 3u) * f32(s[e >> 5u]);
+}`,
+  rmsnorm: `
+struct P { n: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; var acc = 0.0;
+  for (var i = t; i < p.n; i += 256u) { let v = x[i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.n) + p.eps);
+  for (var i = t; i < p.n; i += 256u) { y[i] = (x[i] * scale) * w[i]; }
+}`,
+  // 4 output rows per workgroup; input read once per k. Dispatch ceil(M/4) workgroups (2-D ok).
+  matmulQ8: `enable f16;
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+${I8}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let N = p.N; let M = p.M; let nb = N / 32u;
+  if (m0 >= M) { return; }
+  let r0 = min(m0, M - 1u); let r1 = min(m0 + 1u, M - 1u); let r2 = min(m0 + 2u, M - 1u); let r3 = min(m0 + 3u, M - 1u);
+  let q0 = (r0 * N) >> 2u; let q1 = (r1 * N) >> 2u; let q2 = (r2 * N) >> 2u; let q3 = (r3 * N) >> 2u;
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var k = t; k < N; k += 256u) {
+    let xv = x[k]; let wi = k >> 2u; let ln = k & 3u; let b = k >> 5u;
+    a0 += i8at(qw[q0 + wi], ln) * f32(qs[r0 * nb + b]) * xv;
+    a1 += i8at(qw[q1 + wi], ln) * f32(qs[r1 * nb + b]) * xv;
+    a2 += i8at(qw[q2 + wi], ln) * f32(qs[r2 * nb + b]) * xv;
+    a3 += i8at(qw[q3 + wi], ln) * f32(qs[r3 * nb + b]) * xv;
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[m0 + t] = part[t * 256u]; }
+}`,
+  matmulF32: `
+struct P { M: u32, N: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let m = wg.x; let t = l.x; var acc = 0.0;
+  for (var k = t; k < p.N; k += 256u) { acc += w[m * p.N + k] * x[k]; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  if (t == 0u) { y[m] = red[0]; }
+}`,
+  // Per-head RMSNorm (QK-norm) then NeoX RoPE (pairs i, i+hd/2), in place. One workgroup per head.
+  // rope[0..hd/2) = cos, rope[hd/2..hd) = sin for this token's position (computed on the CPU).
+  qkNormRope: `
+struct P { hd: u32, eps: f32 }
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> w: array<f32>;
+@group(0) @binding(2) var<storage, read> rope: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+var<workgroup> red: array<f32, 64>;
+@compute @workgroup_size(64) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let base = wg.x * p.hd; let t = l.x; let half = p.hd / 2u;
+  var acc = 0.0;
+  for (var i = t; i < p.hd; i += 64u) { let v = x[base + i]; acc += v * v; }
+  red[t] = acc; workgroupBarrier();
+  for (var s = 32u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let scale = 1.0 / sqrt(red[0] / f32(p.hd) + p.eps);
+  for (var i = t; i < half; i += 64u) {
+    let a = (x[base + i] * scale) * w[i];
+    let b = (x[base + i + half] * scale) * w[i + half];
+    let c = rope[i]; let sn = rope[half + i];
+    x[base + i] = a * c - b * sn;
+    x[base + i + half] = a * sn + b * c;
+  }
+}`,
+  kvStore: `enable f16;
+${TOK}
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read> k: array<f32>;
+@group(0) @binding(1) var<storage, read> v: array<f32>;
+@group(0) @binding(2) var<storage, read_write> kc: array<f16>;
+@group(0) @binding(3) var<storage, read_write> vc: array<f16>;
+@group(0) @binding(4) var<uniform> tok: Tok;
+@group(0) @binding(5) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i >= p.n) { return; }
+  kc[tok.pos * p.n + i] = f16(k[i]);
+  vc[tok.pos * p.n + i] = f16(v[i]);
+}`,
+  attnScore: `enable f16;
+${TOK}
+struct P { heads: u32, kvHeads: u32, hd: u32, scale: f32 }
+@group(0) @binding(0) var<storage, read> q: array<f32>;
+@group(0) @binding(1) var<storage, read> kc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(3) var<uniform> tok: Tok;
+@group(0) @binding(4) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let n = tok.seqLen; let idx = g.x; if (idx >= p.heads * n) { return; }
+  let h = idx / n; let pos = idx % n; let kvh = h / (p.heads / p.kvHeads);
+  let qo = h * p.hd; let ko = pos * p.kvHeads * p.hd + kvh * p.hd;
+  var acc = 0.0;
+  for (var d = 0u; d < p.hd; d++) { acc += q[qo + d] * f32(kc[ko + d]); }
+  sc[h * n + pos] = acc * p.scale;
+}`,
+  softmax: `
+${TOK}
+@group(0) @binding(0) var<storage, read_write> sc: array<f32>;
+@group(0) @binding(1) var<uniform> tok: Tok;
+var<workgroup> red: array<f32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let n = tok.seqLen; let base = wg.x * n; let t = l.x;
+  var mx = -3.4e38;
+  for (var i = t; i < n; i += 256u) { mx = max(mx, sc[base + i]); }
+  red[t] = mx; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] = max(red[t], red[t + s]); } workgroupBarrier(); }
+  let m = red[0]; workgroupBarrier();
+  var sum = 0.0;
+  for (var i = t; i < n; i += 256u) { let e = exp(sc[base + i] - m); sc[base + i] = e; sum += e; }
+  red[t] = sum; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  let inv = 1.0 / red[0];
+  for (var i = t; i < n; i += 256u) { sc[base + i] = sc[base + i] * inv; }
+}`,
+  attnOut: `enable f16;
+${TOK}
+struct P { heads: u32, kvHeads: u32, hd: u32, pad: u32 }
+@group(0) @binding(0) var<storage, read> pr: array<f32>;
+@group(0) @binding(1) var<storage, read> vc: array<f16>;
+@group(0) @binding(2) var<storage, read_write> y: array<f32>;
+@group(0) @binding(3) var<uniform> tok: Tok;
+@group(0) @binding(4) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let idx = g.x; if (idx >= p.heads * p.hd) { return; }
+  let n = tok.seqLen; let h = idx / p.hd; let d = idx % p.hd; let kvh = h / (p.heads / p.kvHeads);
+  let stride = p.kvHeads * p.hd;
+  var acc = 0.0;
+  for (var pos = 0u; pos < n; pos++) { acc += pr[h * n + pos] * f32(vc[pos * stride + kvh * p.hd + d]); }
+  y[idx] = acc;
+}`,
+  addInPlace: `
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read_write> x: array<f32>;
+@group(0) @binding(1) var<storage, read> y: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i < p.n) { x[i] = x[i] + y[i]; }
+}`,
+  // Router: softmax over n logits (n ≤ 256), greedy top-k (ties → lowest index), weights
+  // renormalized to sum 1 (Qwen3-MoE norm_topk_prob). sel = k ids then k f32 weights (bitcast).
+  // One workgroup; each of the k picks is a parallel argmax over the per-thread probabilities.
+  // Every probability is the same f32 expression the serial version evaluated, so the picks and
+  // weights are the same; the serial version cost ~0.1 ms per call on an M4 Pro.
+  topk: `
+struct P { n: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> lg: array<f32>;
+@group(0) @binding(1) var<storage, read_write> sel: array<u32>;
+@group(0) @binding(2) var<uniform> p: P;
+var<workgroup> red: array<f32, 256>;
+var<workgroup> bi: array<u32, 256>;
+var<workgroup> gmax: f32;
+var<workgroup> gsum: f32;
+var<workgroup> picks: array<u32, 32>;
+var<workgroup> probs: array<f32, 32>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; let n = p.n;
+  red[t] = select(-3.4e38, lg[min(t, n - 1u)], t < n); workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] = max(red[t], red[t + s]); } workgroupBarrier(); }
+  if (t == 0u) { gmax = red[0]; } workgroupBarrier();
+  red[t] = select(0.0, exp(lg[min(t, n - 1u)] - gmax), t < n); workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) { if (t < s) { red[t] += red[t + s]; } workgroupBarrier(); }
+  if (t == 0u) { gsum = red[0]; } workgroupBarrier();
+  var mine = select(-1.0, exp(lg[min(t, n - 1u)] - gmax) / gsum, t < n);
+  for (var j = 0u; j < p.k; j++) {
+    red[t] = mine; bi[t] = t; workgroupBarrier();
+    for (var s = 128u; s > 0u; s >>= 1u) {
+      if (t < s) { let o = red[t + s]; if (o > red[t] || (o == red[t] && bi[t + s] < bi[t])) { red[t] = o; bi[t] = bi[t + s]; } }
+      workgroupBarrier();
+    }
+    if (t == 0u) { picks[j] = bi[0]; probs[j] = red[0]; }
+    workgroupBarrier();
+    if (t == picks[j]) { mine = -1.0; }
+    workgroupBarrier();
+  }
+  if (t == 0u) {
+    var wsum = 0.0;
+    for (var j = 0u; j < p.k; j++) { wsum += probs[j]; }
+    for (var j = 0u; j < p.k; j++) { sel[j] = picks[j]; sel[p.k + j] = bitcast<u32>(probs[j] / wsum); }
+  }
+}`,
+  // Routed experts, all k at once: workgroup z = top-k position, slot = slots[z] picks the
+  // expert's rows in the pool buffer (rows_per_expert per slot). Input is shared (gate/up) or
+  // per-position (down). Output region z × M.
+  expertQ8: `enable f16;
+struct P { M: u32, N: u32, rowsPerExpert: u32, inputPerSlot: u32 }
+@group(0) @binding(0) var<storage, read> x: array<f32>;
+@group(0) @binding(1) var<storage, read> qw: array<u32>;
+@group(0) @binding(2) var<storage, read> qs: array<f16>;
+@group(0) @binding(3) var<storage, read_write> y: array<f32>;
+@group(0) @binding(4) var<uniform> p: P;
+@group(0) @binding(5) var<storage, read> slots: array<u32>;
+${I8}
+var<workgroup> part: array<f32, 1024>;
+@compute @workgroup_size(256) fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(num_workgroups) ng: vec3<u32>, @builtin(local_invocation_id) l: vec3<u32>) {
+  let z = wg.z; let m0 = (wg.y * ng.x + wg.x) * 4u; let t = l.x; let N = p.N; let M = p.M; let nb = N / 32u;
+  if (m0 >= M) { return; }
+  let rb = slots[z] * p.rowsPerExpert;
+  let xb = select(0u, z * N, p.inputPerSlot == 1u);
+  let r0 = rb + min(m0, M - 1u); let r1 = rb + min(m0 + 1u, M - 1u); let r2 = rb + min(m0 + 2u, M - 1u); let r3 = rb + min(m0 + 3u, M - 1u);
+  let q0 = (r0 * N) >> 2u; let q1 = (r1 * N) >> 2u; let q2 = (r2 * N) >> 2u; let q3 = (r3 * N) >> 2u;
+  var a0 = 0.0; var a1 = 0.0; var a2 = 0.0; var a3 = 0.0;
+  for (var k = t; k < N; k += 256u) {
+    let xv = x[xb + k]; let wi = k >> 2u; let ln = k & 3u; let b = k >> 5u;
+    a0 += i8at(qw[q0 + wi], ln) * f32(qs[r0 * nb + b]) * xv;
+    a1 += i8at(qw[q1 + wi], ln) * f32(qs[r1 * nb + b]) * xv;
+    a2 += i8at(qw[q2 + wi], ln) * f32(qs[r2 * nb + b]) * xv;
+    a3 += i8at(qw[q3 + wi], ln) * f32(qs[r3 * nb + b]) * xv;
+  }
+  part[t] = a0; part[256u + t] = a1; part[512u + t] = a2; part[768u + t] = a3;
+  workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { part[t] += part[t + s]; part[256u + t] += part[256u + t + s]; part[512u + t] += part[512u + t + s]; part[768u + t] += part[768u + t + s]; }
+    workgroupBarrier();
+  }
+  if (t < 4u && m0 + t < M) { y[z * M + m0 + t] = part[t * 256u]; }
+}`,
+  // gu = k × [gate F | up F] → act = k × F of SiLU(gate)·up.
+  siluMulMoe: `
+struct P { F: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> gu: array<f32>;
+@group(0) @binding(1) var<storage, read_write> act: array<f32>;
+@group(0) @binding(2) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let i = g.x; if (i >= p.k * p.F) { return; }
+  let z = i / p.F; let j = i % p.F; let g0 = gu[z * 2u * p.F + j];
+  act[i] = (g0 / (1.0 + exp(-g0))) * gu[z * 2u * p.F + p.F + j];
+}`,
+  // x[h] += Σ_j w_j · out[j·H + h]   (the expert sum, then the residual add — llama.cpp's order)
+  moeAccum: `
+struct P { H: u32, k: u32 }
+@group(0) @binding(0) var<storage, read> out: array<f32>;
+@group(0) @binding(1) var<storage, read> sel: array<u32>;
+@group(0) @binding(2) var<storage, read_write> x: array<f32>;
+@group(0) @binding(3) var<uniform> p: P;
+@compute @workgroup_size(256) fn main(@builtin(global_invocation_id) g: vec3<u32>) {
+  let h = g.x; if (h >= p.H) { return; }
+  var acc = 0.0;
+  for (var j = 0u; j < p.k; j++) { acc += bitcast<f32>(sel[p.k + j]) * out[j * p.H + h]; }
+  x[h] = x[h] + acc;
+}`,
+  argmax: `
+struct P { n: u32 }
+@group(0) @binding(0) var<storage, read> lg: array<f32>;
+@group(0) @binding(1) var<storage, read_write> res: array<u32>;
+@group(0) @binding(2) var<uniform> p: P;
+var<workgroup> bv: array<f32, 256>;
+var<workgroup> bi: array<u32, 256>;
+@compute @workgroup_size(256) fn main(@builtin(local_invocation_id) l: vec3<u32>) {
+  let t = l.x; var v = -3.4e38; var ix = 0u;
+  for (var i = t; i < p.n; i += 256u) { let x = lg[i]; if (x > v) { v = x; ix = i; } }
+  bv[t] = v; bi[t] = ix; workgroupBarrier();
+  for (var s = 128u; s > 0u; s >>= 1u) {
+    if (t < s) { let o = bv[t + s]; if (o > bv[t] || (o == bv[t] && bi[t + s] < bi[t])) { bv[t] = o; bi[t] = bi[t + s]; } }
+    workgroupBarrier();
+  }
+  if (t == 0u) { res[0] = bi[0]; }
+}`,
+};
+
+export const STORAGE = 0x80, COPY_SRC = 0x04, COPY_DST = 0x08, UNIFORM = 0x40, MAP_READ = 0x01;
+
+// ── Engine ──────────────────────────────────────────────────────────────────
+export class Qwen3MoeSsd {
+  // A subclass for another architecture overrides these (gemma4_moe_ssd.js).
+  static configFrom(kv) { return configFromGguf(kv); }
+  static get ingestPlan() { return undefined; }
+  static tokenizerFrom(kv) { return new BpeTokenizer(kv); }
+
+  static async load(modelId = QWEN3_30B_A3B.repo, opts = {}) {
+    const { fetch: fetchFn = (u, i) => fetch(u, i), onProgress = () => {}, signal } = opts;
+    const src = opts.source || (modelId === QWEN3_30B_A3B.repo || !modelId ? QWEN3_30B_A3B : { repo: modelId, file: opts.file, revision: opts.revision || 'main' });
+    const url = opts.url || `https://huggingface.co/${src.repo}/resolve/${src.revision}/${src.file}`;
+    const key = opts.key || storeKey(opts.file || src.file || url.split('/').pop());
+    const root = opts.root || OPFS_ROOT;              // the OPFS folder for this engine's stores
+    const dir = `${root}/${key}`;
+
+    onProgress({ status: 'init' });
+    if (!navigator.gpu) throw new Error('WebGPU is not available');
+    const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
+    if (!adapter) throw new Error('no WebGPU adapter');
+    if (!adapter.features.has('shader-f16')) throw new Error('this GPU lacks shader-f16');
+    const L = adapter.limits;
+    // subgroups: optional; an engine may use subgroup kernels when the adapter offers them.
+    const features = ['shader-f16', ...(adapter.features.has('subgroups') ? ['subgroups'] : [])];
+    const device = await adapter.requestDevice({
+      requiredFeatures: features,
+      requiredLimits: { maxBufferSize: L.maxBufferSize, maxStorageBufferBindingSize: L.maxStorageBufferBindingSize, maxStorageBuffersPerShaderStage: L.maxStorageBuffersPerShaderStage, maxComputeWorkgroupsPerDimension: L.maxComputeWorkgroupsPerDimension },
+    });
+    device.lost.then((info) => console.warn('qwen3-moe-ssd: GPU device lost:', info.message));
+
+    let manifest = null;
+    try { manifest = JSON.parse(await readOpfsText(`${dir}/manifest.json`) || 'null'); } catch (_) { manifest = null; }
+    if (opts.reingest || !manifest || !manifest.complete || manifest.format !== FORMAT) {
+      manifest = await ingestGguf({
+        url, key, root, fetch: fetchFn, signal, source: { repo: src.repo, file: src.file, revision: src.revision, sha256: src.sha256, size: src.size },
+        onProgress: (e) => onProgress(ingestProgress(e)),
+        plan: this.ingestPlan,
+      });
+    }
+    const headerFile = await (await (await navigator.storage.getDirectory()).getDirectoryHandle(root)).getDirectoryHandle(key);
+    const headerBytes = new Uint8Array(await (await (await headerFile.getFileHandle('header.bin')).getFile()).arrayBuffer());
+    const gguf = parseGguf(headerBytes);
+    const engine = new this(device, manifest, gguf, { ...opts, dir, key, url, adapterInfo: adapter.info || {} });
+    await engine.init(onProgress);
+    return engine;
+  }
+
+  constructor(device, manifest, gguf, opts) {
+    this.device = device;
+    this.manifest = manifest;
+    this.cfg = this.constructor.configFrom(gguf.kv);
+    this.tokenizer = this.constructor.tokenizerFrom(gguf.kv);
+    this.opts = opts;
+    this.maxCtx = Math.min(opts.maxCtx || 4096, this.cfg.contextLength);
+    this.gpuBytes = { dense: 0, pool: 0, kv: 0, act: 0 };
+    this.pipelines = {};
+    this.position = 0;
+    this.cached = [];          // token ids whose K/V are in the cache, in order
+    // Prefetch: routers of the next `lookahead` layers guess their experts from this layer's
+    // post-attention state. Measured 2026-10-04 (full model, 4 GB pool, M4 Pro): off 4.41,
+    // lookahead 1 5.02, 2 5.48, 4 4.56, 6 3.90 tok/s — guesses beyond 2 layers waste SSD bandwidth.
+    this.prefetch = opts.prefetch ?? true;
+    this.lookahead = Math.max(1, Math.floor(opts.lookahead ?? 2));
+    this.resetCounters();
+  }
+
+  buffer(size, usage, cat = 'act') {
+    const b = this.device.createBuffer({ size: Math.ceil(size / 4) * 4, usage });
+    this.gpuBytes[cat] = (this.gpuBytes[cat] || 0) + b.size;
+    return b;
+  }
+  uniform(words) {
+    const b = this.buffer(Math.max(16, words.length * 4), UNIFORM | COPY_DST, 'act');
+    const ab = new ArrayBuffer(b.size), u = new Uint32Array(ab), f = new Float32Array(ab);
+    words.forEach((w, i) => { if (typeof w === 'object') f[i] = w.f; else u[i] = w; });
+    this.device.queue.writeBuffer(b, 0, ab);
+    return b;
+  }
+  // The kernel sources; a subclass adds its own.
+  get kernels() { return WGSL; }
+  pipeline(name) {
+    if (!this.pipelines[name]) {
+      const code = this.kernels[name];
+      if (!code) throw new Error(`no kernel ${name}`);
+      const module = this.device.createShaderModule({ code, label: name });
+      this.pipelines[name] = this.device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' }, label: name });
+    }
+    return this.pipelines[name];
+  }
+  bind(name, buffers) {
+    return this.device.createBindGroup({
+      layout: this.pipeline(name).getBindGroupLayout(0),
+      entries: buffers.map((b, i) => ({ binding: i, resource: { buffer: b } })),
+    });
+  }
+
+  async init(onProgress) {
+    const dev = this.device;
+    // Fail early on a shader that does not compile.
+    dev.pushErrorScope('validation');
+    for (const k of Object.keys(this.kernels)) this.pipeline(k);
+    const err = await dev.popErrorScope();
+    if (err) throw new Error(`WGSL: ${err.message}`);
+    await this.uploadDense(onProgress);
+    await this.initPool();
+    this.initBuffers();
+    await dev.queue.onSubmittedWorkDone();
+  }
+
+  // Dense weights: OPFS → GPU (this.w[name] = { q, s, rows, cols } or { raw }).
+  async uploadDense(onProgress) {
+    const dev = this.device, m = this.manifest;
+    const t0 = performance.now();
+    const reader = await OpfsReaderPool.open(`${this.opts.dir}/${m.dense.file}`, { workers: 4 });
+    const names = Object.keys(m.dense.tensors);
+    this.w = {};
+    let doneT = 0;
+    const CH = 64 << 20;
+    const upload = async (gbuf, part) => {
+      for (let o = 0; o < part.bytes; o += CH) {
+        const n = Math.min(CH, part.bytes - o);
+        const r = await reader.read(part.off + o, n);
+        if (r.got !== n) throw new Error(`dense read short at ${part.off + o}`);
+        dev.queue.writeBuffer(gbuf, o, r.buf, 0, n);
+      }
+    };
+    const queue = [];
+    for (const name of names) {
+      const d = m.dense.tensors[name];
+      if (d.type === 'q8' || d.type === 'q4') {   // q4: Gemma 4 (two values per byte)
+        const q = this.buffer(d.q.bytes, STORAGE | COPY_DST, 'dense'), s = this.buffer(d.s.bytes, STORAGE | COPY_DST, 'dense');
+        this.w[name] = { q, s, rows: (d.type === 'q4' ? 2 * d.q.bytes : d.q.bytes) / d.dims[0], cols: d.dims[0] };
+        queue.push(() => upload(q, d.q), () => upload(s, d.s));
+      } else {
+        const raw = this.buffer(d.raw.bytes, STORAGE | COPY_DST, 'dense');
+        this.w[name] = { raw };
+        queue.push(() => upload(raw, d.raw));
+      }
+    }
+    let qi = 0;
+    await Promise.all([0, 1, 2, 3].map(async () => {
+      while (qi < queue.length) { await queue[qi++](); doneT++; onProgress({ status: 'weights', kind: 'tensors', loaded: doneT, total: queue.length }); }
+    }));
+    await reader.close();
+    await dev.queue.onSubmittedWorkDone();
+    this.denseUploadSecs = (performance.now() - t0) / 1000;
+  }
+
+  // Bytes for the expert cache. With opts.gpuBudgetBytes, the cache gets what the budget leaves after the weights
+  // that stay on the GPU, the KV cache and working buffers; a budget too small for those is refused. Otherwise
+  // opts.poolBytes, default 4 GiB.
+  poolBudget() {
+    const o = this.opts;
+    if (!o.gpuBudgetBytes) return o.poolBytes || 4 * 2 ** 30;
+    const gb = (n) => (n / 1e9).toFixed(2) + ' GB';
+    const fixed = this.gpuBytes.dense + this.kvBytes() + (o.workBytes ?? 512 * 2 ** 20);
+    const rest = o.gpuBudgetBytes - fixed;
+    const min = this.cfg.topK * 2 * this.manifest.experts.record;
+    if (rest < min) throw new Error(`GPU budget ${gb(o.gpuBudgetBytes)} is too small: weights that stay on the GPU, the KV cache and working buffers need ${gb(fixed)}, and the expert cache at least ${gb(min)} more`);
+    return rest;
+  }
+  // KV cache bytes at this.maxCtx (f16 K and V for every layer); engines with other layouts override it.
+  kvBytes() { const c = this.cfg; return 2 * 2 * c.layers * this.maxCtx * c.kvHeads * c.headDim; }
+
+  // Expert slot pool + the streamer that feeds it.
+  async initPool() {
+    const c = this.cfg, dev = this.device, xp = this.manifest.experts;
+    const maxSlotsByBinding = Math.floor(dev.limits.maxStorageBufferBindingSize / xp.parts.guQ.bytes);
+    this.poolSlots = Math.max(c.topK * 2, Math.min(maxSlotsByBinding, Math.floor(this.poolBudget() / xp.record), c.layers * c.experts));
+    this.pool = {};
+    for (const [k, part] of Object.entries(xp.parts)) this.pool[k] = this.buffer(this.poolSlots * part.bytes, STORAGE | COPY_DST, 'pool');
+    this.expertReader = await OpfsReaderPool.open(`${this.opts.dir}/${xp.file}`, { workers: this.opts.readers || 4 });
+    this.xs = new ExpertStreamer({
+      device: dev, reader: this.expertReader, recordBytes: xp.record,
+      recordOffset: (layer, e) => (layer * xp.perLayer + e) * xp.record,
+      parts: ['guQ', 'guS', 'dQ', 'dS'].map((k) => ({ buffer: this.pool[k], srcOffset: xp.parts[k].off, bytes: xp.parts[k].bytes })),
+      slots: this.poolSlots, numLayers: c.layers, numExperts: c.experts,
+      ...(this.opts.uploadRing !== undefined ? { uploadRing: this.opts.uploadRing } : {}),
+      ...(this.opts.evict ? { evict: this.opts.evict, hotHalfLife: this.opts.hotHalfLife } : {}),
+    });
+    this.gpuBytes.staging = this.xs.ringBytes();
+  }
+
+  // KV cache (f16), activations, uniforms and every layer's bind groups.
+  initBuffers() {
+    const c = this.cfg;
+    const kvn = c.kvHeads * c.headDim;
+    this.kc = []; this.vc = [];
+    for (let l = 0; l < c.layers; l++) {
+      this.kc.push(this.buffer(this.maxCtx * kvn * 2, STORAGE, 'kv'));
+      this.vc.push(this.buffer(this.maxCtx * kvn * 2, STORAGE, 'kv'));
+    }
+    const H = c.hidden, QN = c.heads * c.headDim, F = c.expertFf, K = c.topK;
+    if (2 * K * 4 > 256) throw new Error(`top-k ${K} > 32: selections would overlap their 256-byte readback regions`);
+    if (c.experts > 256) throw new Error(`${c.experts} experts: the router top-k kernel handles at most 256`);
+    const A = (n) => this.buffer(n * 4, STORAGE | COPY_SRC | COPY_DST);
+    this.a = {
+      x: A(H), xn: A(H), q: A(QN), k: A(kvn), v: A(kvn), att: A(QN), o: A(H), sc: A(c.heads * this.maxCtx),
+      rl: A(c.experts), sel: A(2 * K), pxn: A(H), prl: A(c.experts), psel: A(64 * this.lookahead), slots: A(K),
+      gu: A(K * 2 * F), act: A(K * F), dn: A(K * H), logits: A(c.vocab), am: A(4),
+      rope: A(c.headDim),
+    };
+    this.tok = this.buffer(16, UNIFORM | COPY_DST);
+    // Readback: this layer's selection at 0, guess d (layers ahead) at 256 × d bytes.
+    this.rbSel = this.buffer(256 * (1 + this.lookahead), MAP_READ | COPY_DST);
+    this.rbLogits = this.buffer(c.vocab * 4, MAP_READ | COPY_DST);
+    this.rbArg = this.buffer(16, MAP_READ | COPY_DST);
+
+    const u = {
+      nH: this.uniform([H]), rmsH: this.uniform([H, { f: c.eps }]), mmQ: this.uniform([QN, H]), mmKV: this.uniform([kvn, H]),
+      mmO: this.uniform([H, QN]), qk: this.uniform([c.headDim, { f: c.eps }]), kvn: this.uniform([kvn]),
+      att: this.uniform([c.heads, c.kvHeads, c.headDim, { f: 1 / Math.sqrt(c.headDim) }]), attOut: this.uniform([c.heads, c.kvHeads, c.headDim, 0]),
+      router: this.uniform([c.experts, H]), topk: this.uniform([c.experts, K]),
+      gu: this.uniform([2 * F, H, 2 * F, 0]), dn: this.uniform([H, F, H, 1]), silu: this.uniform([F, K]), acc: this.uniform([H, K]),
+      lm: this.uniform([c.vocab, H]), am: this.uniform([c.vocab]),
+    };
+    const a = this.a, W = this.w;
+    this.g = { embed: this.bind('embedQ8', [W['token_embd.weight'].q, W['token_embd.weight'].s, a.x, this.tok, u.nH]) };
+    this.layers = [];
+    for (let l = 0; l < c.layers; l++) {
+      const p = (n) => W[`blk.${l}.${n}.weight`];
+      this.layers.push({
+        rmsA: this.bind('rmsnorm', [a.x, p('attn_norm').raw, a.xn, u.rmsH]),
+        q: this.bind('matmulQ8', [a.xn, p('attn_q').q, p('attn_q').s, a.q, u.mmQ]),
+        k: this.bind('matmulQ8', [a.xn, p('attn_k').q, p('attn_k').s, a.k, u.mmKV]),
+        v: this.bind('matmulQ8', [a.xn, p('attn_v').q, p('attn_v').s, a.v, u.mmKV]),
+        ropeQ: this.bind('qkNormRope', [a.q, p('attn_q_norm').raw, a.rope, u.qk]),
+        ropeK: this.bind('qkNormRope', [a.k, p('attn_k_norm').raw, a.rope, u.qk]),
+        kv: this.bind('kvStore', [a.k, a.v, this.kc[l], this.vc[l], this.tok, u.kvn]),
+        score: this.bind('attnScore', [a.q, this.kc[l], a.sc, this.tok, u.att]),
+        soft: this.bind('softmax', [a.sc, this.tok]),
+        attOut: this.bind('attnOut', [a.sc, this.vc[l], a.att, this.tok, u.attOut]),
+        o: this.bind('matmulQ8', [a.att, p('attn_output').q, p('attn_output').s, a.o, u.mmO]),
+        addO: this.bind('addInPlace', [a.x, a.o, u.nH]),
+        rmsF: this.bind('rmsnorm', [a.x, p('ffn_norm').raw, a.xn, u.rmsH]),
+        router: this.bind('matmulF32', [a.xn, p('ffn_gate_inp').raw, a.rl, u.router]),
+        topk: this.bind('topk', [a.rl, a.sel, u.topk]),
+        // Routers of layers l+1..l+lookahead on this layer's post-attention state: the prefetch
+        // guesses, each written to its own 256-byte region of psel.
+        pf: Array.from({ length: Math.min(this.lookahead, c.layers - 1 - l) }, (_, i) => {
+          const at = (n) => W[`blk.${l + 1 + i}.${n}.weight`];
+          return {
+            rms: this.bind('rmsnorm', [a.x, at('ffn_norm').raw, a.pxn, u.rmsH]),
+            router: this.bind('matmulF32', [a.pxn, at('ffn_gate_inp').raw, a.prl, u.router]),
+            topk: this.device.createBindGroup({ layout: this.pipeline('topk').getBindGroupLayout(0), entries: [
+              { binding: 0, resource: { buffer: a.prl } },
+              { binding: 1, resource: { buffer: a.psel, offset: 256 * i, size: 8 * K } },
+              { binding: 2, resource: { buffer: u.topk } },
+            ] }),
+          };
+        }),
+        gu: this.bind('expertQ8', [a.xn, this.pool.guQ, this.pool.guS, a.gu, u.gu, a.slots]),
+        silu: this.bind('siluMulMoe', [a.gu, a.act, u.silu]),
+        dn: this.bind('expertQ8', [a.act, this.pool.dQ, this.pool.dS, a.dn, u.dn, a.slots]),
+        acc: this.bind('moeAccum', [a.dn, a.sel, a.x, u.acc]),
+      });
+    }
+    this.g.rmsOut = this.bind('rmsnorm', [a.x, W['output_norm.weight'].raw, a.xn, u.rmsH]);
+    this.g.lm = this.bind('matmulQ8', [a.xn, W['output.weight'].q, W['output.weight'].s, a.logits, u.lm]);
+    this.g.am = this.bind('argmax', [a.logits, a.am, u.am]);
+  }
+
+  // ── forward ───────────────────────────────────────────────────────────────
+  dispatch(pass, name, group, x, y = 1, z = 1) {
+    pass.setPipeline(this.pipeline(name));
+    pass.setBindGroup(0, group);
+    if (x > 65535) { y = Math.ceil(x / 32768); x = 32768; }
+    pass.dispatchWorkgroups(x, y, z);
+  }
+  encodeAttention(pass, l, seqLen) {
+    const c = this.cfg, g = this.layers[l], d = (n, gr, x, y, z) => this.dispatch(pass, n, gr, x, y, z);
+    const QN = c.heads * c.headDim, kvn = c.kvHeads * c.headDim;
+    d('rmsnorm', g.rmsA, 1);
+    d('matmulQ8', g.q, Math.ceil(QN / 4)); d('matmulQ8', g.k, Math.ceil(kvn / 4)); d('matmulQ8', g.v, Math.ceil(kvn / 4));
+    d('qkNormRope', g.ropeQ, c.heads); d('qkNormRope', g.ropeK, c.kvHeads);
+    d('kvStore', g.kv, Math.ceil(kvn / 256));
+    d('attnScore', g.score, Math.ceil(c.heads * seqLen / 256));
+    d('softmax', g.soft, c.heads);
+    d('attnOut', g.attOut, Math.ceil(QN / 256));
+    d('matmulQ8', g.o, Math.ceil(c.hidden / 4));
+    d('addInPlace', g.addO, Math.ceil(c.hidden / 256));
+    if (this.prefetch) for (const p of g.pf) { d('rmsnorm', p.rms, 1); d('matmulF32', p.router, c.experts); d('topk', p.topk, 1); }
+    d('rmsnorm', g.rmsF, 1);
+    d('matmulF32', g.router, c.experts);
+    d('topk', g.topk, 1);
+  }
+  // The token's embedding into a.x, and the head (final norm, logits, argmax when wanted): a subclass
+  // with another embedding or head format overrides these two.
+  encodeEmbed(pass) { this.dispatch(pass, 'embedQ8', this.g.embed, Math.ceil(this.cfg.hidden / 256)); }
+  encodeHead(pass, want) {
+    this.dispatch(pass, 'rmsnorm', this.g.rmsOut, 1);
+    this.dispatch(pass, 'matmulQ8', this.g.lm, Math.ceil(this.cfg.vocab / 4));
+    if (want === 'argmax') this.dispatch(pass, 'argmax', this.g.am, 1);
+  }
+  encodeExperts(pass, l) {
+    const c = this.cfg, g = this.layers[l], d = (n, gr, x, y, z) => this.dispatch(pass, n, gr, x, y, z);
+    d('expertQ8', g.gu, Math.ceil(2 * c.expertFf / 4), 1, c.topK);
+    d('siluMulMoe', g.silu, Math.ceil(c.topK * c.expertFf / 256));
+    d('expertQ8', g.dn, Math.ceil(c.hidden / 4), 1, c.topK);
+    d('moeAccum', g.acc, Math.ceil(c.hidden / 256));
+  }
+
+  writeTokenUniforms(token, pos) {
+    const c = this.cfg;
+    this.device.queue.writeBuffer(this.tok, 0, new Uint32Array([token, pos, pos + 1, 0]));
+    // NeoX RoPE angles the way llama.cpp's Metal kernel forms them: f32 pos × base^(-2i/hd).
+    const half = c.headDim / 2, r = new Float32Array(c.headDim), inv = Math.fround(-1 / c.headDim);
+    for (let i = 0; i < half; i++) {
+      const th = Math.fround(pos * Math.fround(Math.pow(c.ropeTheta, Math.fround(inv * 2 * i))));
+      r[i] = Math.cos(th); r[half + i] = Math.sin(th);
+    }
+    this.device.queue.writeBuffer(this.a.rope, 0, r);
+  }
+
+  resetCounters() {
+    this.counters = { tokens: 0, gpuWaitMs: 0, ensureMs: 0, encodeMs: 0, wallMs: 0, predHits: 0, predTotal: 0 };
+    if (this.xs) this.xs.resetStats();
+  }
+
+  // → { ids, preds }: this layer's top-k ids and `nPred` guesses for the layers after it.
+  async readSel(nPred) {
+    const K = this.cfg.topK, bytes = 256 * (1 + nPred);
+    const t0 = performance.now();
+    await this.rbSel.mapAsync(1, 0, bytes);
+    this.counters.gpuWaitMs += performance.now() - t0;
+    const u = new Uint32Array(this.rbSel.getMappedRange(0, bytes).slice(0));
+    this.rbSel.unmap();
+    const preds = [];
+    for (let i = 1; i <= nPred; i++) preds.push(u.subarray(64 * i, 64 * i + K));
+    return { ids: u.subarray(0, K), preds };
+  }
+  // Encodes the readback of layer l's selection and its guesses.
+  copySel(enc, l) {
+    enc.copyBufferToBuffer(this.a.sel, 0, this.rbSel, 0, 8 * this.cfg.topK);
+    const n = this.prefetch ? this.layers[l].pf.length : 0;
+    if (n) enc.copyBufferToBuffer(this.a.psel, 0, this.rbSel, 256, 256 * n);
+    return n;
+  }
+
+  // One token through all layers at position this.position. want: 'none' | 'argmax' | 'logits'.
+  async step(token, want = 'argmax') {
+    const c = this.cfg, dev = this.device, K = c.topK;
+    if (this.position >= this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    const tStart = performance.now();
+    const pos = this.position, seqLen = pos + 1;
+    this.writeTokenUniforms(token, pos);
+    let te = performance.now();
+    let enc = dev.createCommandEncoder(), pass = enc.beginComputePass();
+    this.encodeEmbed(pass);
+    this.encodeAttention(pass, 0, seqLen);
+    pass.end();
+    let nPred = this.copySel(enc, 0);
+    dev.queue.submit([enc.finish()]);
+    this.counters.encodeMs += performance.now() - te;
+    let predIds = null;
+    for (let l = 0; l < c.layers; l++) {
+      const { ids, preds } = await this.readSel(nPred);
+      if (predIds) { // accuracy of the one-layer-ahead guess made one layer earlier
+        let hit = 0; for (const e of ids) if (predIds.includes(e)) hit++;
+        this.counters.predHits += hit; this.counters.predTotal += K;
+      }
+      const tq = performance.now();
+      const ensuring = this.xs.ensure(l, ids);
+      preds.forEach((p, i) => this.xs.prefetch(l + 1 + i, p));   // nearest layer first
+      predIds = preds.length ? Array.from(preds[0]) : null;
+      const slots = await ensuring;
+      this.counters.ensureMs += performance.now() - tq;
+      dev.queue.writeBuffer(this.a.slots, 0, slots);
+      te = performance.now();
+      enc = dev.createCommandEncoder(); pass = enc.beginComputePass();
+      this.encodeExperts(pass, l);
+      if (l + 1 < c.layers) {
+        this.encodeAttention(pass, l + 1, seqLen);
+        pass.end();
+        nPred = this.copySel(enc, l + 1);
+      } else {
+        if (want !== 'none') this.encodeHead(pass, want);
+        pass.end();
+        if (want === 'argmax') enc.copyBufferToBuffer(this.a.am, 0, this.rbArg, 0, 4);
+        if (want === 'logits') enc.copyBufferToBuffer(this.a.logits, 0, this.rbLogits, 0, c.vocab * 4);
+      }
+      dev.queue.submit([enc.finish()]);
+      this.counters.encodeMs += performance.now() - te;
+      this.xs.release(slots);
+    }
+    this.position++;
+    this.cached.push(token);
+    let result = null;
+    const tw = performance.now();
+    if (want === 'argmax') {
+      await this.rbArg.mapAsync(1, 0, 4);
+      result = new Uint32Array(this.rbArg.getMappedRange(0, 4))[0];
+      this.rbArg.unmap();
+    } else if (want === 'logits') {
+      await this.rbLogits.mapAsync(1);
+      result = new Float32Array(this.rbLogits.getMappedRange().slice(0));
+      this.rbLogits.unmap();
+    } else {
+      await dev.queue.onSubmittedWorkDone();
+    }
+    this.counters.gpuWaitMs += performance.now() - tw;
+    this.counters.tokens++;
+    this.counters.wallMs += performance.now() - tStart;
+    return result;
+  }
+
+  reset() { this.position = 0; this.cached = []; }
+
+  // Feeds `ids` after the cached prefix they share (re-prefilling only what changed); returns
+  // the logits/argmax of the last token.
+  async prefill(ids, want = 'argmax') {
+    let common = 0;
+    while (common < ids.length - 1 && common < this.cached.length && this.cached[common] === ids[common]) common++;
+    if (common < this.cached.length) { this.position = common; this.cached.length = common; }
+    let r = null;
+    for (let i = common; i < ids.length; i++) r = await this.step(ids[i], i === ids.length - 1 ? want : 'none');
+    return r;
+  }
+
+  // Diagnostics for the llama.cpp comparison: greedy continuation of raw token ids, with the
+  // top-n logits at every generated position.
+  async greedy(ids, n, { top = 5 } = {}) {
+    this.reset();
+    const out = [], tops = [];
+    let logits = await this.prefill(ids, 'logits');
+    for (let i = 0; i < n; i++) {
+      const order = topN(logits, top);
+      let mx = -Infinity, sum = 0;
+      for (let j = 0; j < logits.length; j++) if (logits[j] > mx) mx = logits[j];
+      for (let j = 0; j < logits.length; j++) sum += Math.exp(logits[j] - mx);
+      const lse = mx + Math.log(sum);
+      for (const o of order) o.logprob = o.logit - lse;
+      tops.push(order);
+      const next = order[0].id;
+      out.push(next);
+      if (i + 1 < n) logits = await this.step(next, 'logits');
+    }
+    return { ids: out, tops };
+  }
+
+  async *generate(messages, { maxNewTokens = 512, signal, enableThinking = true } = {}) {
+    const ids = this.tokenizer.encode(this.chatPrompt(messages, { enableThinking }));
+    const stops = new Set(this.stopTokenIds);
+    let next = await this.prefill(ids, 'argmax');
+    const outIds = [];
+    for (let i = 0; i < maxNewTokens; i++) {
+      if (signal && signal.aborted) break;
+      if (stops.has(next)) break;
+      outIds.push(next);
+      yield { text: this.tokenizer.decode(outIds), token: next, tokens: outIds.length };
+      if (this.position >= this.maxCtx) break;
+      next = await this.step(next, 'argmax');
+    }
+  }
+
+  chatPrompt(messages, opts) { return chatPrompt(messages, opts); }
+  get stopTokenIds() { return [this.cfg.eos, this.tokenizer.ids.get('<|im_end|>'), this.tokenizer.ids.get('<|endoftext|>')].filter((t) => t !== undefined); }
+
+  // Raw ids of the reasoning delimiters, for hosts that re-mark the thought block.
+  get thinkOpenTokenId() { return this.tokenizer.ids.get('<think>') ?? null; }
+  get thinkCloseTokenId() { return this.tokenizer.ids.get('</think>') ?? null; }
+
+  stats() {
+    const s = this.xs.stats, c = this.counters, n = Math.max(1, c.tokens);
+    return {
+      tokens: c.tokens, tokPerSec: c.tokens / (c.wallMs / 1000),
+      msPerToken: c.wallMs / n, gpuWaitMsPerToken: c.gpuWaitMs / n, ensureMsPerToken: c.ensureMs / n, encodeMsPerToken: c.encodeMs / n,
+      readMsPerToken: s.readMs / n, uploadMsPerToken: s.uploadMs / n,
+      hitRate: (s.hits + s.lateHits) / Math.max(1, s.hits + s.lateHits + s.misses),
+      hits: s.hits, lateHits: s.lateHits, misses: s.misses, evictions: s.evictions,
+      bytesReadPerToken: s.bytesRead / n, prefetchIssued: s.prefetchIssued, prefetchUsed: s.prefetchUsed,
+      prefetchAccuracy: c.predTotal ? c.predHits / c.predTotal : null,
+      hitRateByLayer: Array.from(s.hitsByLayer, (h, l) => +(h / Math.max(1, h + s.missesByLayer[l])).toFixed(3)),
+      poolSlots: this.poolSlots, resident: this.xs.resident(), gpuBytes: { ...this.gpuBytes },
+    };
+  }
+
+  async warmup() {}
+
+  async dispose() {
+    try { await this.xs.drain(); } catch (_) {}
+    try { await this.expertReader.close(); } catch (_) {}
+    try { this.device.destroy(); } catch (_) {}
+  }
+}
+
+export function topN(logits, n) {
+  const best = [];
+  for (let i = 0; i < logits.length; i++) {
+    const v = logits[i];
+    if (best.length < n || v > best[best.length - 1].logit) {
+      best.push({ id: i, logit: v });
+      best.sort((a, b) => b.logit - a.logit || a.id - b.id);
+      if (best.length > n) best.pop();
+    }
+  }
+  return best;
+}
+
+export async function removeIngest(key) { await removeStore(key, { root: OPFS_ROOT }); }

examples/chat/index.html

@@ -0,0 +1,236 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>diskformer chat</title>
+<style>
+  :root { --bg: #fafaf9; --fg: #1c1917; --muted: #78716c; --line: #e7e5e4; --card: #fff; --accent: #2563eb; --bad: #b91c1c; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #161514; --fg: #e7e5e4; --muted: #a8a29e; --line: #2e2b29; --card: #1f1d1b; --accent: #60a5fa; --bad: #f87171; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; }
+  main { max-width: 760px; margin: 0 auto; padding: 24px 16px 48px; }
+  h1 { font-size: 22px; margin: 0 0 6px; }
+  p { margin: 0 0 12px; }
+  .muted { color: var(--muted); }
+  .card { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 14px; margin: 14px 0; }
+  .row { display: flex; flex-wrap: wrap; gap: 10px 16px; align-items: end; }
+  label { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--muted); }
+  select, input, textarea, button { font: inherit; color: var(--fg); background: var(--bg); border: 1px solid var(--line); border-radius: 7px; padding: 6px 9px; }
+  input[type=number] { width: 90px; }
+  button { cursor: pointer; }
+  button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+  button:disabled { opacity: .5; cursor: default; }
+  .bar { height: 6px; background: var(--line); border-radius: 3px; overflow: hidden; margin: 10px 0 6px; }
+  .bar span { display: block; height: 100%; width: 0; background: var(--accent); transition: width .3s; }
+  #status.bad { color: var(--bad); }
+  .meter { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; }
+  .meter div { border: 1px solid var(--line); border-radius: 8px; padding: 8px 10px; }
+  .meter b { display: block; font-size: 20px; }
+  .meter span { font-size: 12px; color: var(--muted); }
+  #log { display: flex; flex-direction: column; gap: 10px; margin-bottom: 12px; }
+  .msg { white-space: pre-wrap; overflow-wrap: anywhere; padding: 9px 12px; border-radius: 9px; border: 1px solid var(--line); }
+  .msg.user { align-self: flex-end; background: var(--bg); max-width: 85%; }
+  .msg.model { background: var(--card); }
+  form { display: flex; gap: 8px; align-items: end; }
+  textarea { flex: 1; resize: vertical; min-height: 44px; }
+  footer { font-size: 12px; color: var(--muted); margin-top: 24px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>diskformer chat</h1>
+  <p>A mixture-of-experts model larger than the GPU memory you give it, answering in this tab. The model downloads once
+    into this browser's private storage (OPFS). The GPU holds the dense layers and a small cache of experts; the other
+    experts are read from disk as each token needs them.</p>
+  <p class="muted">Chromium with WebGPU. Nothing leaves this tab except the model download from Hugging Face.</p>
+  <p id="framed" hidden>This page is inside a frame, where browser storage can be partitioned or limited.
+    <a id="ownTab" target="_blank" rel="noopener">Open it in its own tab</a> to keep the model in first-party storage.</p>
+
+  <section class="card">
+    <div class="row">
+      <label>Model <select id="model"></select></label>
+      <label>GPU memory budget (GB) <input id="budget" type="number" min="1" step="0.5"></label>
+      <label>Context (tokens) <select id="ctx"><option>1024</option><option selected>2048</option><option>4096</option></select></label>
+      <button id="load" class="primary">Download and load</button>
+      <button id="remove">Remove from disk</button>
+    </div>
+    <div class="bar"><span id="fill"></span></div>
+    <p id="status" class="muted">Pick a model and a budget. The first load downloads it; later loads take seconds.</p>
+  </section>
+
+  <section class="card" id="meterCard" hidden>
+    <div class="meter">
+      <div><b id="mModel">–</b><span>model in this browser's storage</span></div>
+      <div><b id="mGpu">–</b><span id="mGpuNote">GPU memory used</span></div>
+      <div><b id="mCache">–</b><span>experts cached on the GPU</span></div>
+      <div><b id="mSpeed">–</b><span id="mSpeedNote">decode speed</span></div>
+    </div>
+  </section>
+
+  <section id="chat" hidden>
+    <div id="log"></div>
+    <form id="ask">
+      <textarea id="q" rows="2" placeholder="Ask something"></textarea>
+      <button class="primary" id="send">Send</button>
+      <button type="button" id="stop" disabled>Stop</button>
+    </form>
+  </section>
+
+  <footer>Greedy decoding, so the same question gets the same answer. Engines and store:
+    <a href="https://github.com/NakliTechie/diskformer.js">diskformer.js</a>. Model terms: Gemma (ai.google.dev/gemma/terms), Qwen3.6 (Apache-2.0).</footer>
+</main>
+
+<script type="module">
+import { Gemma4MoeSsd, GEMMA4_26B_A4B } from '../../engines/gemma4_moe_ssd.js';
+import { Qwen35MoeSsd, QWEN36_35B_A3B } from '../../engines/qwen35_moe_ssd.js';
+import { removeStore, storeKey } from '../../src/ingest.js';
+
+// ?model=gemma|qwen  ?budget=GB  ?ctx=tokens  ?url=GGUF (a local copy)  ?root=OPFS folder  ?gate=refs.json
+const MODELS = {
+  gemma: { label: 'Gemma 4 26B-A4B · 14.4 GB', Engine: Gemma4MoeSsd, source: GEMMA4_26B_A4B, budget: 3 },
+  qwen: { label: 'Qwen3.6 35B-A3B · 36.9 GB', Engine: Qwen35MoeSsd, source: QWEN36_35B_A3B, budget: 4 },
+};
+const q = new URLSearchParams(location.search);
+const ROOT = q.get('root') || 'diskformer';
+const $ = (id) => document.getElementById(id);
+const GB = (n) => (n / 1e9).toFixed(2) + ' GB';
+let engine = null, messages = [], ctrl = null, busy = '';     // busy: '' | 'load' | 'remove' | 'reply'
+
+for (const [k, m] of Object.entries(MODELS)) $('model').add(new Option(m.label, k));
+if (MODELS[q.get('model')]) $('model').value = q.get('model');
+const pick = () => MODELS[$('model').value];
+$('budget').value = q.get('budget') || pick().budget;
+if (q.get('ctx')) $('ctx').value = q.get('ctx');
+$('model').onchange = () => { if (!q.get('budget')) $('budget').value = pick().budget; };
+
+const status = (text, bad = false) => { $('status').textContent = text; $('status').className = bad ? 'bad' : 'muted'; window.progressText = text; };
+const fill = (f) => { $('fill').style.width = `${Math.round(100 * f)}%`; };
+addEventListener('error', (e) => status(`Error: ${e.message}`, true));
+addEventListener('unhandledrejection', (e) => status(`Error: ${e.reason && e.reason.message || e.reason}`, true));
+const controls = () => {
+  for (const id of ['load', 'remove', 'model']) $(id).disabled = !!busy;
+  $('send').disabled = !!busy || !engine; $('stop').disabled = busy !== 'reply';
+};
+// The OPFS folder a model's store lives in: the loaded engine's, else the name the engine would give it.
+const keyOf = (m) => (engine && engine.constructor === m.Engine ? engine.opts.key : storeKey(m === MODELS.qwen && q.get('url') ? q.get('url').split('/').pop() : m.source.file));
+controls();
+if (window.self !== window.top) { $('framed').hidden = false; $('ownTab').href = location.href; }
+if (!navigator.gpu) status('This page needs WebGPU: Chrome or Edge 121 or later, on a GPU with shader-f16.', true);
+
+async function load() {
+  if (busy) return null;
+  busy = 'load'; controls();
+  const m = pick(), budgetGB = Number($('budget').value), maxCtx = Number($('ctx').value);
+  $('chat').hidden = true;
+  const t0 = performance.now();
+  try {
+    if (engine) { const old = engine; engine = null; await old.dispose(); }
+    engine = await m.Engine.load(null, {
+      url: q.get('url') || undefined, root: ROOT, gpuBudgetBytes: budgetGB * 1e9, maxCtx,
+      onProgress: (e) => {
+        if (e.status === 'ingest-plan' && e.quota && e.quota - (e.usage || 0) < e.needed)
+          status(`Needs ${GB(e.needed)} of storage; the browser grants ${GB(e.quota - (e.usage || 0))} so far and raises that as the download writes, while the disk has room.`);
+        else if (e.status === 'ingest-resume') { fill(e.loaded / e.total); status(`Resuming the download at ${GB(e.loaded)} of ${GB(e.total)}`); }
+        else if (e.status === 'weights' && e.kind === 'tensors') { fill(e.loaded / e.total); status(`Loading the dense layers onto the GPU: ${e.loaded} of ${e.total} tensors`); }
+        else if (e.status === 'weights') {
+          fill(e.loaded / e.total);
+          const rate = e.secs ? (e.loaded - (e.resumedFrom || 0)) / e.secs : 0, left = rate ? (e.total - e.loaded) / rate : 0;
+          status(`Downloading into this browser's storage (once): ${GB(e.loaded)} of ${GB(e.total)}${rate ? ` · ${(rate / 1e6).toFixed(0)} MB/s · ${Math.ceil(left / 60)} min left` : ''}`);
+        } else if (e.status === 'init') status('Starting WebGPU');
+      },
+    });
+    engine.device.lost.then((info) => status(`The GPU device was lost: ${info.message}. Reload the page.`, true));
+    fill(1);
+    const used = Object.values(engine.gpuBytes).reduce((a, b) => a + b, 0), c = engine.cfg;
+    const disk = engine.manifest.experts.bytes + engine.manifest.dense.bytes;
+    $('mModel').textContent = GB(disk);
+    $('mGpu').textContent = GB(used);
+    $('mGpuNote').textContent = `GPU memory used, budget ${budgetGB} GB`;
+    $('mCache').textContent = `${engine.poolSlots.toLocaleString()} of ${(c.layers * c.experts).toLocaleString()}`;
+    $('meterCard').hidden = false; $('chat').hidden = false;
+    status(`Loaded in ${((performance.now() - t0) / 1000).toFixed(1)} s. ${GB(disk)} in OPFS; ${GB(used)} on the GPU.`);
+    messages = []; $('log').replaceChildren();
+    return { model: $('model').value, budgetGB, maxCtx, modelBytes: m.source.size, diskBytes: disk, gpuBytes: used, gpuBytesByKind: { ...engine.gpuBytes }, poolSlots: engine.poolSlots, experts: c.layers * c.experts };
+  } catch (e) { status(`Could not load: ${e.message}`, true); throw e; }
+  finally { busy = ''; controls(); }
+}
+
+// One reply, streamed into onText. Returns the text, its timing, and whether `signal` stopped it.
+async function reply(history, { maxNewTokens = 1024, onText = () => {}, signal } = {}) {
+  const t0 = performance.now();
+  let text = '', tokens = 0, tFirst = 0;
+  for await (const r of engine.generate(history, { maxNewTokens, signal, enableThinking: false })) {
+    if (!tokens) tFirst = performance.now();
+    text = r.text; tokens = r.tokens; onText(text);
+  }
+  const decodeSecs = (performance.now() - tFirst) / 1000;
+  return { text, tokens, stopped: !!(signal && signal.aborted), firstTokenMs: tokens ? Math.round(tFirst - t0) : null, decodeTokPerSec: tokens > 1 ? +((tokens - 1) / decodeSecs).toFixed(2) : null };
+}
+
+function bubble(role, text) { const d = document.createElement('div'); d.className = `msg ${role}`; d.textContent = text; $('log').append(d); return d; }
+
+$('load').onclick = () => load().catch(() => {});
+$('remove').onclick = async () => {
+  if (busy) return;
+  busy = 'remove'; controls();
+  const m = pick(), key = keyOf(m), name = m.label.split(' · ')[0];
+  try {
+    if (engine) { const old = engine; engine = null; await old.dispose(); }
+    $('chat').hidden = true; $('meterCard').hidden = true; fill(0);
+    await removeStore(key, { root: ROOT });
+    status(`Removed ${name} from this browser's storage.`);
+  } catch (e) {
+    if (e.name === 'NotFoundError') status(`${name} is not in this browser's storage.`);
+    else status(`Could not remove ${name}: ${e.message}`, true);
+  } finally { busy = ''; controls(); }
+};
+$('stop').onclick = () => { if (ctrl) ctrl.abort(); };
+$('q').onkeydown = (e) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); $('ask').requestSubmit(); } };
+$('ask').onsubmit = async (e) => {
+  e.preventDefault();
+  const text = $('q').value.trim();
+  if (!text || !engine || busy) return;
+  busy = 'reply'; ctrl = new AbortController(); controls();
+  $('q').value = '';
+  messages.push({ role: 'user', content: text });
+  bubble('user', text);
+  const out = bubble('model', '…');
+  try {
+    const r = await reply(messages, { signal: ctrl.signal, onText: (t) => { out.textContent = t; } });
+    if (r.stopped) out.textContent = r.text ? `${r.text} [stopped]` : '[stopped before the reply]';
+    if (r.text) messages.push({ role: 'assistant', content: r.text });
+    else messages.pop();                       // no reply: drop the turn so the next one is not two user turns
+    if (r.decodeTokPerSec) { $('mSpeed').textContent = `${r.decodeTokPerSec} tok/s`; $('mSpeedNote').textContent = `decode speed · first token ${(r.firstTokenMs / 1000).toFixed(1)} s`; }
+  } catch (err) { out.textContent = `Error: ${err.message}`; messages.pop(); }
+  finally { busy = ''; ctrl = null; controls(); }
+};
+
+// Gate: load, then replay each reference conversation and compare the text with llama.cpp's.
+async function gate(url) {
+  const ref = await (await fetch(url, { cache: 'no-store' })).json();
+  const info = await load();
+  const PREFIX = '<|channel>thought\n<channel|>';
+  const rows = [];
+  for (const c of ref.conversations) {
+    status(`Gate: ${c.name} (${rows.length + 1} of ${ref.conversations.length})`);
+    const r = await reply(c.messages, { maxNewTokens: c.tokens || 64 });
+    if (c.content === undefined) { rows.push({ name: c.name, text: r.text, tokens: r.tokens, decodeTokPerSec: r.decodeTokPerSec, firstTokenMs: r.firstTokenMs }); continue; }
+    const theirs = c.content.startsWith(PREFIX) ? c.content.slice(PREFIX.length) : c.content;
+    let at = 0; while (at < r.text.length && at < theirs.length && r.text[at] === theirs[at]) at++;
+    rows.push({ name: c.name, identical: r.text === theirs, sameUpTo: at, chars: r.text.length, tokens: r.tokens, decodeTokPerSec: r.decodeTokPerSec, firstTokenMs: r.firstTokenMs, ...(r.text === theirs ? {} : { ours: r.text, theirs }) });
+  }
+  // A conversation without reference text (no llama.cpp run to compare with) only has to produce a reply.
+  const compared = rows.filter((r) => 'identical' in r), identical = compared.filter((r) => r.identical).length;
+  const speeds = rows.map((r) => r.decodeTokPerSec).filter(Boolean).sort((a, b) => a - b);
+  const ok = identical === compared.length && rows.every((r) => r.tokens > 0);
+  window.result = { ok, identical, compared: compared.length, of: rows.length, ...info, medianDecodeTokPerSec: speeds[speeds.length >> 1], rows };
+  status(`Gate: ${identical} of ${compared.length} replies identical to the reference; ${rows.length - compared.length} without one.`);
+}
+
+window.demo = { load, reply, get engine() { return engine; } };
+if (q.get('gate')) gate(q.get('gate')).catch((e) => { window.result = { ok: false, error: e.message, stack: e.stack }; });
+else if (q.get('auto')) load().catch(() => {});
+</script>
+</body>
+</html>

examples/chat/refs/gemma.json

@@ -0,0 +1,137 @@
+{
+ "about": "llama.cpp b9830 (c1a1c8ee9), Metal, -ngl 99: llama-server /v1/chat/completions, temperature 0, max_tokens 64, on google/gemma-4-26B-A4B-it-qat-q4_0-gguf @ d1c082be (gemma-4-26B_q4_0-it.gguf, sha256 3eca3b8f...eca51d). Recorded 2026-10-05 for LocalMind's parity revalidation.",
+ "conversations": [
+  {
+   "name": "explain-tcp",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Explain the difference between TCP and UDP to a new programmer."
+    }
+   ],
+   "prompt": "<|turn>user\nExplain the difference between TCP and UDP to a new programmer.<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>To understand the difference between **TCP** and **UDP**, forget about code for a second and imagine you are sending messages to a friend.\n\n### 1. TCP (Transmission Control Protocol)\n**The \"Certified Mail\" Approach**\n\nImagine you are sending a very important legal document via certified mail. You want",
+   "finish": "length",
+   "tokens": 64
+  },
+  {
+   "name": "json-extract",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Extract the name, city and age from this sentence as JSON: \"Priya, 34, moved from Pune to Lisbon last year.\""
+    }
+   ],
+   "prompt": "<|turn>user\nExtract the name, city and age from this sentence as JSON: \"Priya, 34, moved from Pune to Lisbon last year.\"<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>```json\n{\n  \"name\": \"Priya\",\n  \"city\": \"Lisbon\",\n  \"age\": 34\n}\n```",
+   "finish": "stop",
+   "tokens": 35
+  },
+  {
+   "name": "translate-hi",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Translate into Hindi: \"The library opens at nine and closes at six.\""
+    }
+   ],
+   "prompt": "<|turn>user\nTranslate into Hindi: \"The library opens at nine and closes at six.\"<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>The translation of \"The library opens at nine and closes at six\" in Hindi is:\n\n**पुस्तकालय नौ बजे खुलता है और छह बजे बंद होता है।**\n\n**Transliteration:** \n*Pustakalay nau baje khulta hai aur chhah baje band hota hai.*",
+   "finish": "length",
+   "tokens": 64
+  },
+  {
+   "name": "word-problem",
+   "messages": [
+    {
+     "role": "user",
+     "content": "A train leaves at 14:10 and arrives at 17:45. How long is the journey? Show the steps briefly."
+    }
+   ],
+   "prompt": "<|turn>user\nA train leaves at 14:10 and arrives at 17:45. How long is the journey? Show the steps briefly.<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>To find the duration of the journey, follow these steps:\n\n1.  **Subtract the hours:**\n    17:00 - 14:00 = **3 hours**\n\n2.  **Subtract the minutes:**\n    45 minutes - 10 minutes = **35 minutes",
+   "finish": "length",
+   "tokens": 64
+  },
+  {
+   "name": "sql",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Write a SQL query that returns the five customers with the highest total order value from tables customers(id, name) and orders(id, customer_id, amount)."
+    }
+   ],
+   "prompt": "<|turn>user\nWrite a SQL query that returns the five customers with the highest total order value from tables customers(id, name) and orders(id, customer_id, amount).<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>To get the five customers with the highest total order value, you need to `JOIN` the two tables, group the results by the customer, and then sum their order amounts.\n\nHere is the SQL query:\n\n```sql\nSELECT \n    c.name, \n    SUM(o.amount)",
+   "finish": "length",
+   "tokens": 64
+  },
+  {
+   "name": "list-rivers",
+   "messages": [
+    {
+     "role": "user",
+     "content": "List five major rivers of Africa, one per line, with the country where each reaches the sea."
+    }
+   ],
+   "prompt": "<|turn>user\nList five major rivers of Africa, one per line, with the country where each reaches the sea.<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>Nile, Egypt\nCongo, Democratic Republic of the Congo\nNiger, Nigeria\nZambezi, Mozambique\nOrange, South Africa",
+   "finish": "stop",
+   "tokens": 29
+  },
+  {
+   "name": "unicode",
+   "messages": [
+    {
+     "role": "user",
+     "content": "What do these emoji usually mean in a text message: 🙏 🔥 💀 ?"
+    }
+   ],
+   "prompt": "<|turn>user\nWhat do these emoji usually mean in a text message: 🙏 🔥 💀 ?<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>The meaning of these emojis can change depending on the context and the age of the person sending them, but here is the general breakdown of how they are used in text messages:\n\n### 1. 🙏 (Folded Hands)\nThis emoji is the most versatile and its meaning depends entirely on the tone of the conversation",
+   "finish": "length",
+   "tokens": 64
+  },
+  {
+   "name": "haiku-autumn",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Write a haiku about autumn leaves in a city."
+    }
+   ],
+   "prompt": "<|turn>user\nWrite a haiku about autumn leaves in a city.<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>Gold leaves drift on stone,\nDancing through the concrete maze,\nStreetlights catch the glow.",
+   "finish": "stop",
+   "tokens": 21
+  },
+  {
+   "name": "system-pirate",
+   "messages": [
+    {
+     "role": "system",
+     "content": "Answer like a cheerful pirate, in two sentences."
+    },
+    {
+     "role": "user",
+     "content": "What is the boiling point of water at sea level?"
+    }
+   ],
+   "prompt": "<|turn>system\nAnswer like a cheerful pirate, in two sentences.<turn|>\n<|turn>user\nWhat is the boiling point of water at sea level?<turn|>\n<|turn>model\n<|channel>thought\n<channel|>",
+   "content": "<|channel>thought\n<channel|>Ahoy there, matey, the waters reach a boil at a sweltering 212 degrees Fahrenheit! Keep a weather eye on that pot so ye don't scald yer treasure!",
+   "finish": "stop",
+   "tokens": 41
+  }
+ ],
+ "speed": {
+  "cache_n": 0,
+  "prompt_n": 24,
+  "prompt_ms": 117.416,
+  "prompt_per_token_ms": 4.892333333333333,
+  "prompt_per_second": 204.40144443687404,
+  "predicted_n": 128,
+  "predicted_ms": 1812.329,
+  "predicted_per_token_ms": 14.1588203125,
+  "predicted_per_second": 70.62735298061224
+ }
+}

examples/chat/refs/qwen.json

@@ -0,0 +1,35 @@
+{
+ "about": "No reference text: llama.cpp's Metal path cannot hold the 36.9 GB model on the 24 GB Mac these runs used, and its CPU path rounds differently. The gate only checks that each conversation gets a reply, and records speed.",
+ "conversations": [
+  {
+   "name": "explain-tcp",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Explain the difference between TCP and UDP to a new programmer."
+    }
+   ],
+   "tokens": 64
+  },
+  {
+   "name": "json-extract",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Extract the name, city and age from this sentence as JSON: \"Priya, 34, moved from Pune to Lisbon last year.\""
+    }
+   ],
+   "tokens": 64
+  },
+  {
+   "name": "translate-hi",
+   "messages": [
+    {
+     "role": "user",
+     "content": "Translate into Hindi: \"The library opens at nine and closes at six.\""
+    }
+   ],
+   "tokens": 64
+  }
+ ]
+}

index.html

@@ -1,19 +1,5 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
-</html>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0; url=examples/chat/">
+<title>diskformer chat</title>
+<a href="examples/chat/">diskformer chat</a>

src/expert-stream.js

@@ -0,0 +1,265 @@
+/* moe-expert-stream.js — keep a mixture-of-experts model's routed experts on SSD (OPFS) and
+ * page them into a fixed GPU slot pool on demand. Model-agnostic: an engine describes one
+ * expert record (its byte layout in the OPFS file and which GPU pool buffer each part goes
+ * to); this module owns the slot LRU, the reads, the uploads, the pins and the counters.
+ *
+ *   const xs = new ExpertStreamer({ device, reader, recordBytes, recordOffset, parts, slots,
+ *                                   numLayers, numExperts });
+ *   const slots = await xs.ensure(layer, expertIds);   // resident + pinned, in id order
+ *   …write `slots` into the kernel's slot table, encode, queue.submit()…
+ *   xs.release(slots);                                  // after the submit
+ *   xs.prefetch(layer + 1, predictedIds);               // optional, never blocks
+ *
+ * `parts`: [{ buffer: GPUBuffer, srcOffset, bytes }]. Slot s of a part lives at s × bytes in
+ * that part's buffer, so a kernel finds expert row r of slot s at s × rowsPerExpert + r.
+ *
+ * Safety of reuse: an upload (a staging-ring copy, or queue.writeBuffer) is ordered after every
+ * earlier queue.submit, so a slot may be overwritten as soon as the work that reads it has been
+ * submitted, even if the GPU has not run it yet. Until then the slot is pinned and never chosen
+ * for eviction.
+ */
+
+export class ExpertStreamer {
+  constructor({ device, reader, recordBytes, recordOffset, parts, slots, numLayers, numExperts, maxStaging = 32, uploadRing = 16, evict = 'lru', hotHalfLife = 8, maxPrefetchInflight = 8 }) {
+    Object.assign(this, { device, reader, recordBytes, recordOffset, parts, slots, numLayers, numExperts, maxStaging, evict, maxPrefetchInflight });
+    // Prefetches wait in pfQueue (nearest layer first) and at most maxPrefetchInflight of them
+    // read at once, so a demand read never queues behind a long run of guesses in the workers.
+    this.pfQueue = [];
+    this.pfInflight = 0;
+    // evict 'hot': drop the unpinned expert with the lowest decaying route count, oldest first
+    // on ties (llama.cpp PR #25294's policy). One tick per ensure() call, so the half-life is in
+    // tokens × layers. 'lru' (default): plain least recently used.
+    this.heat = new Float32Array(numLayers * numExperts);
+    this.heatTick = new Float64Array(numLayers * numExperts);
+    this.tick = 0;
+    this.decayPerTick = Math.pow(0.5, 1 / Math.max(1, hotHalfLife * numLayers));
+    // Uploads go through a ring of mapped MAP_WRITE buffers + copyBufferToBuffer: measured
+    // 2026-10-04 on an M4 Pro (Chrome 154) at 27.5 GB/s for 5 MB records with depth 4, against
+    // 1.88 GB/s for queue.writeBuffer. uploadRing = 0 keeps writeBuffer (A/B measurement only).
+    this.ring = [];
+    for (let i = 0; i < uploadRing; i++) {
+      this.ring.push({ buf: device.createBuffer({ size: Math.ceil(recordBytes / 4) * 4, usage: 0x02 | 0x04, mappedAtCreation: true }), ready: null });
+    }
+    this.ringNext = 0;
+    this.slotKey = new Int32Array(slots).fill(-1);
+    this.pinCount = new Int32Array(slots);
+    this.free = [];
+    for (let s = slots - 1; s >= 0; s--) this.free.push(s);
+    this.lru = new Map();        // key → slot, least recently used first
+    this.inflight = new Map();   // key → { p: Promise<slot>, pins }
+    this.staging = [];
+    this.resetStats();
+  }
+
+  resetStats() {
+    const L = this.numLayers;
+    this.stats = {
+      hits: 0, misses: 0, lateHits: 0, prefetchIssued: 0, prefetchUsed: 0, evictions: 0,
+      bytesRead: 0, readMs: 0, uploadMs: 0, waitMs: 0,
+      hitsByLayer: new Uint32Array(L), missesByLayer: new Uint32Array(L),
+    };
+    this.prefetched = new Set();  // keys loaded by prefetch() and not yet demanded
+  }
+
+  key(layer, expert) { return layer * this.numExperts + expert; }
+  resident() { return this.lru.size; }
+
+  pin(s) { this.pinCount[s]++; }
+  release(slots) { for (const s of slots) if (this.pinCount[s] > 0) this.pinCount[s]--; }
+
+  takeStaging() { return this.staging.pop() || new ArrayBuffer(this.recordBytes); }
+  giveStaging(buf) { if (this.staging.length < this.maxStaging && buf.byteLength >= this.recordBytes) this.staging.push(buf); }
+
+  heatOf(key) { return this.heat[key] * Math.pow(this.decayPerTick, this.tick - this.heatTick[key]); }
+  touch(key) { this.heat[key] = this.heatOf(key) + 1; this.heatTick[key] = this.tick; }
+
+  allocSlot() {
+    if (this.free.length) return this.free.pop();
+    if (this.evict === 'hot') {
+      let bestK = -1, bestS = -1, bestH = Infinity;
+      for (const [k, s] of this.lru) {          // LRU order, so the first minimum is the oldest
+        if (this.pinCount[s] !== 0) continue;
+        const h = this.heatOf(k);
+        if (h < bestH) { bestH = h; bestK = k; bestS = s; }
+      }
+      if (bestS >= 0) {
+        this.lru.delete(bestK); this.prefetched.delete(bestK); this.slotKey[bestS] = -1; this.stats.evictions++;
+        return bestS;
+      }
+      throw new Error(`expert pool exhausted: all ${this.slots} slots pinned — raise the pool size`);
+    }
+    for (const [k, s] of this.lru) {
+      if (this.pinCount[s] === 0) {
+        this.lru.delete(k);
+        this.prefetched.delete(k);
+        this.slotKey[s] = -1;
+        this.stats.evictions++;
+        return s;
+      }
+    }
+    throw new Error(`expert pool exhausted: all ${this.slots} slots pinned — raise the pool size`);
+  }
+
+  // Starts the read + upload of one expert into a newly allocated slot. The slot stays pinned
+  // while the load is in flight; `entry.pins` demands registered meanwhile are converted into
+  // pins in the same synchronous step that publishes the slot, so no eviction can slip
+  // between "loaded" and "pinned by its user". Returns the in-flight entry { p, pins }.
+  load(layer, expert, pins = 0) {
+    const key = this.key(layer, expert);
+    const s = this.allocSlot();
+    this.pin(s);
+    const entry = { pins, p: null };
+    entry.p = (async () => {
+      let ok = false;
+      try {
+        const r = await this.reader.read(this.recordOffset(layer, expert), this.recordBytes, this.takeStaging());
+        if (r.got !== this.recordBytes) throw new Error(`short expert read L${layer} E${expert}: ${r.got} of ${this.recordBytes} bytes`);
+        this.stats.readMs += r.ms;
+        this.stats.bytesRead += r.got;
+        const t0 = performance.now();
+        await this.upload(r.buf, s);
+        this.stats.uploadMs += performance.now() - t0;
+        this.giveStaging(r.buf);
+        this.slotKey[s] = key;
+        this.lru.set(key, s);
+        this.pinCount[s] += entry.pins;
+        ok = true;
+        return s;
+      } catch (err) {
+        if (err && err.buf) this.giveStaging(err.buf);
+        throw err;
+      } finally {
+        this.inflight.delete(key);
+        this.pinCount[s]--;
+        if (!ok) { this.pinCount[s] = 0; this.free.push(s); }
+      }
+    })();
+    this.inflight.set(key, entry);
+    return entry;
+  }
+
+  // Copies one record into slot `s` of every part. Queue order makes this as safe as
+  // writeBuffer: the copy is submitted after the work that last read the slot and before the
+  // work that will read the new expert.
+  async upload(buf, s) {
+    if (!this.ring.length) {
+      for (const part of this.parts) this.device.queue.writeBuffer(part.buffer, s * part.bytes, buf, part.srcOffset, part.bytes);
+      return;
+    }
+    const r = this.ring[this.ringNext];
+    this.ringNext = (this.ringNext + 1) % this.ring.length;
+    while (r.ready) { const p = r.ready; await p; if (r.ready === p) r.ready = null; }
+    new Uint8Array(r.buf.getMappedRange(0, r.buf.size)).set(new Uint8Array(buf, 0, this.recordBytes));
+    r.buf.unmap();
+    const enc = this.device.createCommandEncoder();
+    for (const part of this.parts) enc.copyBufferToBuffer(r.buf, part.srcOffset, part.buffer, s * part.bytes, part.bytes);
+    this.device.queue.submit([enc.finish()]);
+    r.ready = r.buf.mapAsync(2);
+  }
+
+  // Makes every expert in `ids` resident for `layer` and pins its slot. Returns the slots in
+  // the same order as `ids`. The caller must release() them after submitting the GPU work.
+  async ensure(layer, ids) {
+    this.tick++;
+    if (this.pfQueue.length) this.pfQueue = this.pfQueue.filter((q) => q.layer > layer);   // not sorted by layer once lookahead >= 3
+    const out = new Uint32Array(ids.length);
+    const waits = [];
+    const st = this.stats;
+    for (let i = 0; i < ids.length; i++) {
+      const key = this.key(layer, ids[i]);
+      this.touch(key);
+      if (this.prefetched.delete(key)) st.prefetchUsed++;
+      const s = this.lru.get(key);
+      if (s !== undefined) {
+        this.lru.delete(key); this.lru.set(key, s);  // most recently used
+        this.pin(s);
+        out[i] = s;
+        st.hits++; st.hitsByLayer[layer]++;
+        continue;
+      }
+      const flying = this.inflight.get(key);
+      if (flying) {
+        st.lateHits++; st.hitsByLayer[layer]++;
+        flying.pins++;
+        waits.push(flying.p.then((slot) => { out[i] = slot; }));
+        continue;
+      }
+      st.misses++; st.missesByLayer[layer]++;
+      waits.push(this.load(layer, ids[i], 1).p.then((slot) => { out[i] = slot; }));
+    }
+    if (waits.length) {
+      const t0 = performance.now();
+      await Promise.all(waits);
+      st.waitMs += performance.now() - t0;
+    }
+    return out;
+  }
+
+  // For an engine that routes on the GPU against a residency map: `ids` of `layer` were found
+  // resident and used without an ensure(). Refreshes their recency and counts them as hits; an
+  // expert evicted since (its slot was reused after that work was submitted) is skipped.
+  touchUsed(layer, ids) {
+    this.tick++;
+    const st = this.stats;
+    for (const e of ids) {
+      const key = this.key(layer, e);
+      const s = this.lru.get(key);
+      if (s === undefined) continue;
+      this.touch(key);
+      if (this.prefetched.delete(key)) st.prefetchUsed++;
+      this.lru.delete(key); this.lru.set(key, s);
+      st.hits++; st.hitsByLayer[layer]++;
+    }
+  }
+
+  // Queues loads for experts that are neither resident, in flight nor queued; never awaits.
+  // Call with the nearest layer first: the queue is served in order, and entries for a layer
+  // are dropped once that layer's demand (ensure) arrives. Returns how many loads it started.
+  prefetch(layer, ids) {
+    const before = this.stats.prefetchIssued;
+    for (const e of ids) {
+      const key = this.key(layer, e);
+      if (this.lru.has(key) || this.inflight.has(key) || this.pfQueue.some((q) => q.key === key)) continue;
+      this.pfQueue.push({ layer, e, key });
+    }
+    this.pump();
+    return this.stats.prefetchIssued - before;
+  }
+
+  // Starts queued prefetches while fewer than maxPrefetchInflight are reading. Stops when the
+  // pool has nothing evictable left.
+  pump() {
+    while (this.pfInflight < this.maxPrefetchInflight && this.pfQueue.length) {
+      const { layer, e, key } = this.pfQueue.shift();
+      if (this.lru.has(key) || this.inflight.has(key)) continue;
+      let entry;
+      try { entry = this.load(layer, e); } catch (_) { this.pfQueue.length = 0; break; }
+      this.prefetched.add(key);
+      this.stats.prefetchIssued++;
+      this.pfInflight++;
+      entry.p.catch(() => {}).finally(() => { this.pfInflight--; this.pump(); });
+    }
+  }
+
+  // Waits for every in-flight load and staging-ring map (before teardown and between runs).
+  async drain() {
+    await Promise.allSettled([...this.inflight.values()].map((f) => f.p));
+    await Promise.allSettled(this.ring.map((r) => r.ready).filter(Boolean));
+  }
+  ringBytes() { return this.ring.reduce((a, r) => a + r.buf.size, 0); }
+
+  // Empties the pool. Waits for loads still reading first: a load that finished after the
+  // reset would claim a slot that is back on the free list.
+  async clear() {
+    this.pfQueue = [];
+    await this.drain();
+    this.lru.clear();
+    this.inflight.clear();
+    this.prefetched.clear();
+    this.slotKey.fill(-1);
+    this.pinCount.fill(0);
+    this.free = [];
+    for (let s = this.slots - 1; s >= 0; s--) this.free.push(s);
+  }
+
+}

src/gguf.js

@@ -0,0 +1,96 @@
+/* gguf.js — read a GGUF header and split quantized blocks into GPU-friendly planes. No dependencies.
+ * Extracted unchanged from LocalMind's qwen3_moe_ssd.js (2026-10-05).
+ *
+ *   const { kv, tensors, dataStart } = parseGguf(headerBytes);   // throws { needBytes } if too short
+ *   tensorBytes(tensor)                                            // bytes of one tensor in the file
+ *   splitQ8(src, q, s) / splitQ4(src, q, s)                        // blocks → value plane + f16-scale plane, bit-exact
+ */
+
+export const GGML = { F32: 0, F16: 1, Q4_0: 2, Q8_0: 8, Q6_K: 14 };
+export const Q8_BLOCK = 34;  // f16 scale + 32 × int8
+export const Q4_BLOCK = 18;  // f16 scale + 32 × 4-bit (16 bytes)
+export const Q6K_BLOCK = 210; // 256 values: ql[128] + qh[64] + scales[16] + f16 d
+
+// Parses a GGUF header. Throws { needBytes } when `u8` stops before the header ends.
+export function parseGguf(u8) {
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  let p = 0;
+  const need = (n) => { if (p + n > u8.byteLength) { const e = new Error('GGUF header truncated'); e.needBytes = Math.max(u8.byteLength * 2, p + n + (1 << 20)); throw e; } };
+  const u32 = () => { need(4); const v = dv.getUint32(p, true); p += 4; return v; };
+  const u64 = () => { need(8); const v = Number(dv.getBigUint64(p, true)); p += 8; return v; };
+  // ignoreBOM: keep a leading U+FEFF (Gemma 4's vocab has '#', '//' and '<?' twice, once with a byte-order mark).
+  const dec = new TextDecoder('utf-8', { ignoreBOM: true });
+  const str = () => { const n = u64(); need(n); const s = dec.decode(u8.subarray(p, p + n)); p += n; return s; };
+  const scalar = {
+    0: () => { need(1); return dv.getUint8(p++); }, 1: () => { need(1); return dv.getInt8(p++); },
+    2: () => { need(2); const v = dv.getUint16(p, true); p += 2; return v; }, 3: () => { need(2); const v = dv.getInt16(p, true); p += 2; return v; },
+    4: u32, 5: () => { need(4); const v = dv.getInt32(p, true); p += 4; return v; },
+    6: () => { need(4); const v = dv.getFloat32(p, true); p += 4; return v; },
+    7: () => { need(1); return dv.getUint8(p++) !== 0; },
+    10: u64, 11: () => { need(8); const v = Number(dv.getBigInt64(p, true)); p += 8; return v; },
+    12: () => { need(8); const v = dv.getFloat64(p, true); p += 8; return v; },
+  };
+  const value = (t) => {
+    if (t === 8) return str();
+    if (t === 9) { const at = u32(), n = u64(); const a = new Array(n); for (let i = 0; i < n; i++) a[i] = value(at); return a; }
+    const f = scalar[t];
+    if (!f) throw new Error(`GGUF: unknown value type ${t}`);
+    return f();
+  };
+  need(4);
+  if (dec.decode(u8.subarray(0, 4)) !== 'GGUF') throw new Error('not a GGUF file');
+  p = 4;
+  const version = u32(), nTensors = u64(), nKv = u64();
+  const kv = {};
+  for (let i = 0; i < nKv; i++) { const k = str(); kv[k] = value(u32()); }
+  const tensors = [];
+  for (let i = 0; i < nTensors; i++) {
+    const name = str(), nd = u32(), dims = [];
+    for (let d = 0; d < nd; d++) dims.push(u64());
+    const type = u32(), offset = u64();
+    tensors.push({ name, dims, type, offset });
+  }
+  const align = kv['general.alignment'] || 32;
+  const dataStart = Math.ceil(p / align) * align;
+  return { version, kv, tensors, headerBytes: p, dataStart };
+}
+
+export function tensorBytes(t) {
+  const n = t.dims.reduce((a, b) => a * b, 1);
+  if (t.type === GGML.F32) return n * 4;
+  if (t.type === GGML.F16) return n * 2;
+  if (t.type === GGML.Q8_0) return (n / 32) * Q8_BLOCK;
+  if (t.type === GGML.Q4_0) return (n / 32) * Q4_BLOCK;
+  if (t.type === GGML.Q6_K) return (n / 256) * Q6K_BLOCK;
+  throw new Error(`unsupported tensor type ${t.type} (${t.name})`);
+}
+
+// Q8_0 blocks → an int8 plane + an f16-scale plane, bit-exact. `src` holds whole blocks and
+// starts at an even byte offset, so both planes copy as u16 lanes.
+export function splitQ8(src, q, s) {
+  const nb = src.byteLength / Q8_BLOCK;
+  const a = new Uint16Array(src.buffer, src.byteOffset, nb * 17);
+  const qd = new Uint16Array(q.buffer, q.byteOffset, nb * 16);
+  const sd = new Uint16Array(s.buffer, s.byteOffset, nb);
+  for (let b = 0, i = 0, o = 0; b < nb; b++, i += 17, o += 16) {
+    sd[b] = a[i];
+    qd[o] = a[i + 1]; qd[o + 1] = a[i + 2]; qd[o + 2] = a[i + 3]; qd[o + 3] = a[i + 4];
+    qd[o + 4] = a[i + 5]; qd[o + 5] = a[i + 6]; qd[o + 6] = a[i + 7]; qd[o + 7] = a[i + 8];
+    qd[o + 8] = a[i + 9]; qd[o + 9] = a[i + 10]; qd[o + 10] = a[i + 11]; qd[o + 11] = a[i + 12];
+    qd[o + 12] = a[i + 13]; qd[o + 13] = a[i + 14]; qd[o + 14] = a[i + 15]; qd[o + 15] = a[i + 16];
+  }
+}
+
+// Q4_0 blocks → a nibble plane (16 bytes per 32 values, ggml's order: low nibbles are values 0..15,
+// high nibbles 16..31) + an f16-scale plane, bit-exact.
+export function splitQ4(src, q, s) {
+  const nb = src.byteLength / Q4_BLOCK;
+  const a = new Uint16Array(src.buffer, src.byteOffset, nb * 9);
+  const qd = new Uint16Array(q.buffer, q.byteOffset, nb * 8);
+  const sd = new Uint16Array(s.buffer, s.byteOffset, nb);
+  for (let b = 0, i = 0, o = 0; b < nb; b++, i += 9, o += 8) {
+    sd[b] = a[i];
+    qd[o] = a[i + 1]; qd[o + 1] = a[i + 2]; qd[o + 2] = a[i + 3]; qd[o + 3] = a[i + 4];
+    qd[o + 4] = a[i + 5]; qd[o + 5] = a[i + 6]; qd[o + 6] = a[i + 7]; qd[o + 7] = a[i + 8];
+  }
+}

src/ingest.js

@@ -0,0 +1,177 @@
+/* ingest.js — copy a GGUF from a URL into OPFS in an engine's own layout, streaming: HTTP Range requests of
+ * ≤1 GiB, each unit transformed and written while the next bytes arrive (at most 8 writes in flight). OPFS quota
+ * grows with what is written, so files grow by writes rather than one up-front truncate. The manifest is written
+ * incomplete first and complete last, so an interrupted ingest is never taken as valid. After each range request the
+ * manifest records the first unit not yet written; a later call with the same key and the same GGUF header resumes
+ * from there instead of from byte 0.
+ * Extracted from LocalMind's qwen3_moe_ssd.js (2026-10-05); `root` and `format` are new options (LocalMind
+ * passes 'localmind-ssd' and its own format string).
+ *
+ *   const manifest = await ingestGguf({ url, key, plan: { layout, units }, onProgress });
+ *   // OPFS: <root>/<key>/{header.bin, dense.bin, experts.bin, manifest.json}
+ */
+
+import { OpfsWriter, readOpfsText, writeOpfsText, removeOpfs } from './opfs-reader.js';
+import { parseGguf, splitQ8, splitQ4, Q8_BLOCK, Q4_BLOCK } from './gguf.js';
+
+export const ROOT = 'diskformer';
+export const FORMAT = 'diskformer-gguf/1';
+
+// ── Ingest: GGUF (over HTTP Range) → OPFS, in the engine layout ─────────────
+export const storeKey = (file) => file.replace(/\.gguf$/i, '').toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
+
+export async function readHeader(url, fetchFn, signal) {
+  let n = 16 << 20;
+  for (;;) {
+    const r = await fetchFn(url, { headers: { Range: `bytes=0-${n - 1}` }, signal, cache: 'no-store' });
+    if (!r.ok) throw new Error(`GGUF header fetch: HTTP ${r.status}`);
+    const h = (name) => (r.headers && r.headers.get ? r.headers.get(name) : null);
+    const total = /\/(\d+)\s*$/.exec(h('content-range') || '');
+    const file = { size: total ? Number(total[1]) : null, etag: h('etag') };   // for the resume identity
+    const u8 = new Uint8Array(await r.arrayBuffer());
+    try { return { gguf: parseGguf(u8), bytes: u8, file }; } catch (e) { if (!e.needBytes) throw e; n = e.needBytes; }
+  }
+}
+
+// FNV-1a, for the resume identity: over bytes (the GGUF header) or a string (the plan's output layout).
+const fnv = (at, n) => { let h = 0x811c9dc5; for (let i = 0; i < n; i++) h = Math.imul(h ^ at(i), 0x01000193) >>> 0; return `${n}:${h.toString(16)}`; };
+const bytesId = (u8) => fnv((i) => u8[i], u8.length);
+const textId = (s) => fnv((i) => s.charCodeAt(i), s.length);
+
+// plan.layout(gguf) → { experts: { file, bytes, … }, dense: { file, bytes, tensors } }: where every kept byte goes.
+// plan.units(gguf, layout) → sorted units { src, len, file: 'dense' | 'experts', raw } or { …, kind?: 'q4', q, s }:
+// byte ranges of the GGUF, each small enough to transform in memory (raw copies, or Q8_0 / Q4_0 blocks split
+// into a value plane at q and an f16-scale plane at s).
+// An interrupted ingest resumes only when the GGUF header, the plan's output layout, and the source's size and ETag
+// (when the server sends them) match its checkpoint; otherwise it starts over. `rangeBytes` and `io` are for tests:
+// smaller range requests, and fake OPFS files.
+export async function ingestGguf({ url, key, plan, root = ROOT, format = FORMAT, fetch: fetchFn = fetch, onProgress = () => {}, signal, source = {},
+  rangeBytes = 1 << 30, io = { OpfsWriter, readOpfsText, writeOpfsText } }) {
+  if (!plan || !plan.layout || !plan.units) throw new Error('ingestGguf: plan { layout, units } is required');
+  const t0 = performance.now();
+  const { gguf, bytes: headerBuf, file } = await readHeader(url, fetchFn, signal);
+  const layout = plan.layout(gguf);
+  const dir = `${root}/${key}`;
+  const storage = typeof navigator !== 'undefined' && navigator.storage;
+  const est = storage && storage.estimate ? await storage.estimate() : {};
+  const persisted = storage && storage.persist ? await storage.persist().catch(() => false) : false;
+  const needed = layout.experts.bytes + layout.dense.bytes;
+  onProgress({ status: 'ingest-plan', needed, quota: est.quota, usage: est.usage, persisted });
+  const quotaLog = [{ written: 0, quota: est.quota, usage: est.usage }];
+  const units = plan.units(gguf, layout);
+  const identity = [bytesId(headerBuf.subarray(0, gguf.dataStart)), textId(JSON.stringify([layout, units])), file.size ?? '', file.etag ?? ''].join('|');
+  let prior = null;
+  try { prior = JSON.parse(await io.readOpfsText(`${dir}/manifest.json`) || 'null'); } catch (_) { prior = null; }
+  const r0 = prior && !prior.complete && prior.format === format && prior.resume;
+  const startUnit = r0 && r0.identity === identity && r0.unit > 0 && r0.unit < units.length ? r0.unit : 0;
+  const checkpoint = (unit) => io.writeOpfsText(`${dir}/manifest.json`, JSON.stringify({ format, complete: false, resume: { identity, unit } }));
+
+  // Stream the data section in order. Units are filled from the response chunks, transformed,
+  // and written while the next bytes arrive (at most `maxWrites` writes in flight).
+  const first = units[0].src, last = units[units.length - 1].src + units[units.length - 1].len;
+  const resumedFrom = units[startUnit].src - first;
+  const maxUnit = units.reduce((m, u) => Math.max(m, u.len), 0);
+  let ui = startUnit, fill = 0, unitBuf = new Uint8Array(maxUnit);
+  const writers = {};
+  const release = async (name) => { const w = writers[name]; delete writers[name]; await w.close(); };
+  const inflight = new Set(); const maxWrites = 8;
+  const spare = [];
+  const getBuf = (n) => { const i = spare.findIndex((b) => b.byteLength >= n); return i >= 0 ? spare.splice(i, 1)[0] : new ArrayBuffer(n); };
+  const queue = async (w, buf, len, at) => {
+    while (inflight.size >= maxWrites) await Promise.race(inflight);
+    const p = w.writeOwned(buf, len, at).then((b) => { inflight.delete(p); if (spare.length < 16) spare.push(b); });
+    p.catch(() => {});       // a failed write surfaces through the race above or the final Promise.all
+    inflight.add(p);
+  };
+  let done = resumedFrom, written = 0;
+  const flushUnit = async (u) => {
+    const src = unitBuf.subarray(0, u.len);
+    const w = writers[u.file];
+    if (u.raw !== undefined) {
+      const b = getBuf(u.len); new Uint8Array(b, 0, u.len).set(src);
+      await queue(w, b, u.len, u.raw); written += u.len; return;
+    }
+    const q4 = u.kind === 'q4', blk = q4 ? Q4_BLOCK : Q8_BLOCK, qPer = q4 ? 16 : 32;
+    const nb = u.len / blk;
+    const qb = getBuf(nb * qPer), sb = getBuf(nb * 2);
+    (q4 ? splitQ4 : splitQ8)(src, new Uint8Array(qb, 0, nb * qPer), new Uint8Array(sb, 0, nb * 2));
+    await queue(w, qb, nb * qPer, u.q);
+    await queue(w, sb, nb * 2, u.s);
+    written += nb * blk;
+  };
+  try {
+    if (!startUnit) {
+      await checkpoint(0);
+      // Header bytes, for the tokenizer and metadata at every later load.
+      writers.header = await io.OpfsWriter.open(`${dir}/header.bin`, { truncate: true });
+      await writers.header.write(headerBuf.subarray(0, gguf.dataStart), 0);
+      await release('header');
+    } else {
+      onProgress({ status: 'ingest-resume', unit: startUnit, units: units.length, loaded: resumedFrom, total: last - first });
+    }
+    // No up-front truncate to full size: a fresh origin's quota is ~10 GiB and grows with what is
+    // actually written (measured 2026-10-02), so a single 30.8 GB extension would be refused. The
+    // writes below grow each file by at most one layer's records (~642 MB) at a time.
+    writers.dense = await io.OpfsWriter.open(`${dir}/dense.bin`, { truncate: !startUnit });
+    writers.experts = await io.OpfsWriter.open(`${dir}/experts.bin`, { truncate: !startUnit });
+    // Sequential range requests of rangeBytes (1 GiB) keep any one response bounded.
+    let pos = units[startUnit].src;
+    for (let start = pos; start < last; start += rangeBytes) {
+      const end = Math.min(last, start + rangeBytes) - 1;
+      const r = await fetchFn(url, { headers: { Range: `bytes=${start}-${end}` }, signal, cache: 'no-store' });
+      if (r.status !== 206) throw new Error(`GGUF range ${start}-${end}: HTTP ${r.status}`);
+      const reader = r.body.getReader();
+      for (;;) {
+        const { done: eof, value } = await reader.read();
+        if (eof) break;
+        let off = 0;
+        while (off < value.byteLength && ui < units.length) {
+          const u = units[ui];
+          if (pos < u.src) { const skip = Math.min(u.src - pos, value.byteLength - off); pos += skip; off += skip; continue; }
+          const take = Math.min(u.len - fill, value.byteLength - off);
+          unitBuf.set(value.subarray(off, off + take), fill);
+          fill += take; off += take; pos += take;
+          if (fill === u.len) { await flushUnit(u); ui++; fill = 0; }
+        }
+        done = pos - first;
+        onProgress({ status: 'ingest', loaded: done, total: last - first, resumedFrom, written, secs: (performance.now() - t0) / 1000 });
+        if (written - quotaLog[quotaLog.length - 1].written > 4 * 2 ** 30 && storage && storage.estimate) {
+          const e = await storage.estimate();
+          quotaLog.push({ written, quota: e.quota, usage: e.usage });
+        }
+      }
+      // Every unit before ui is written: flush, then record ui as the resume point.
+      if (ui < units.length) {
+        await Promise.all(inflight);
+        await writers.dense.flush(); await writers.experts.flush();
+        await checkpoint(ui);
+      }
+    }
+    if (ui !== units.length) throw new Error(`ingest ended early: ${ui} of ${units.length} units`);
+    await Promise.all(inflight);
+    await release('dense');
+    await release('experts');
+  } catch (e) {
+    // Release every file still open, so a retry in this page can reopen them and resume.
+    await Promise.allSettled([...inflight]);
+    await Promise.allSettled(Object.keys(writers).map(release));
+    throw e;
+  }
+  const manifest = {
+    format, complete: true, ingestedAt: new Date().toISOString(),
+    source: { url, ...source, dataStart: gguf.dataStart, headerBytes: gguf.headerBytes },
+    ingestSecs: (performance.now() - t0) / 1000, resumedAtUnit: startUnit || undefined, quotaBefore: est.quota, persisted, quotaLog,
+    ...layout,
+  };
+  await io.writeOpfsText(`${dir}/manifest.json`, JSON.stringify(manifest));
+  return manifest;
+}
+
+// Ingest progress as hosts read it: a 'weights' event with byte counts. The spread goes first, so the
+// event's own status ('ingest') cannot overwrite 'weights' (LocalMind's 2026-10-04 bug: a host's load
+// watchdog, seeing no progress, killed a 37 GB first download).
+export function ingestProgress(e) {
+  return e && e.status === 'ingest' ? { ...e, status: 'weights', loaded: e.loaded, total: e.total } : e;
+}
+
+export async function removeStore(key, { root = ROOT } = {}) { await removeOpfs(`${root}/${key}`); }

src/measure.js

@@ -0,0 +1,61 @@
+/* measure.js — how fast this machine reads an OPFS file the way a disk tier does. Run it where the tier will run
+ * (a page or a worker); OPFS speed varies a lot between machines and browsers.
+ *
+ *   const r = await measure();                         // writes a 256 MB probe, measures, removes it
+ *   const r = await measure({ path: 'diskformer/<key>/experts.bin', recordBytes: 3345408 });   // an existing store
+ *   // → { bytes, sequentialMBps, random: { recordBytes, reads, p50Ms, p90Ms, MBps }, burst8: { p50Ms, MBps } }
+ *
+ * A probe the call just wrote is likely in the OS page cache, so its numbers are an upper bound; point `path` at a
+ * store larger than RAM to see the disk itself.
+ */
+import { OpfsReaderPool, OpfsWriter, removeOpfs } from './opfs-reader.js';
+
+const pct = (a, q) => { const s = [...a].sort((x, y) => x - y); return s[Math.min(s.length - 1, Math.floor(q * s.length))]; };
+
+export async function measure({ path = null, bytes = 256 << 20, recordBytes = 3 << 20, reads = 64, workers = 4, chunkBytes = 64 << 20 } = {}) {
+  const probe = !path;
+  if (probe) {
+    path = 'diskformer/.measure/probe.bin';
+    const w = await OpfsWriter.open(path, { truncate: true });
+    const chunk = new Uint8Array(Math.min(chunkBytes, bytes));
+    for (let i = 0; i < chunk.length; i += 4096) chunk[i] = i & 255;
+    for (let at = 0; at < bytes; at += chunk.length) await w.write(chunk.subarray(0, Math.min(chunk.length, bytes - at)), at);
+    await w.close();
+  }
+  const pool = await OpfsReaderPool.open(path, { workers });
+  try {
+    const size = pool.size;
+    // Sequential: the load pattern (64 MB chunks, one at a time per worker).
+    let t0 = performance.now(), done = 0, inflight = [];
+    for (let at = 0; at < size; at += chunkBytes) {
+      inflight.push(pool.read(at, Math.min(chunkBytes, size - at)).then((r) => { done += r.got; }));
+      if (inflight.length >= workers) { await Promise.all(inflight); inflight = []; }
+    }
+    await Promise.all(inflight);
+    const sequentialMBps = done / 1e6 / ((performance.now() - t0) / 1000);
+    // Random whole records: the per-token pattern, one at a time, then bursts of 8 (one MoE layer's misses).
+    const n = Math.max(1, Math.floor(size / recordBytes));
+    const at = () => Math.floor(Math.random() * n) * recordBytes;
+    // Throughput comes from the total time: browsers coarsen performance.now() (0.1 ms in a worker without
+    // cross-origin isolation), which rounds a single small read to zero.
+    const one = []; let t1 = performance.now();
+    for (let i = 0; i < reads; i++) { const s = performance.now(); await pool.read(at(), recordBytes); one.push(performance.now() - s); }
+    const oneMs = performance.now() - t1;
+    const burst = [], bursts = Math.max(1, Math.round(reads / 8)); t1 = performance.now();
+    for (let i = 0; i < bursts; i++) {
+      const s = performance.now();
+      await Promise.all(Array.from({ length: 8 }, () => pool.read(at(), recordBytes)));
+      burst.push(performance.now() - s);
+    }
+    const burstMs = performance.now() - t1;
+    const mbps = (count, ms) => Math.round((count * recordBytes) / 1e6 / (Math.max(ms, 0.1) / 1000));
+    return {
+      path, bytes: size, workers, sequentialMBps: Math.round(sequentialMBps),
+      random: { recordBytes, reads, p50Ms: +pct(one, 0.5).toFixed(2), p90Ms: +pct(one, 0.9).toFixed(2), MBps: mbps(reads, oneMs) },
+      burst8: { bursts, p50Ms: +pct(burst, 0.5).toFixed(2), MBps: mbps(8 * bursts, burstMs) },
+    };
+  } finally {
+    await pool.close();
+    if (probe) await removeOpfs('diskformer/.measure').catch(() => {});
+  }
+}

src/opfs-reader.js

@@ -0,0 +1,258 @@
+/* opfs-reader.js — read model weights from the Origin Private File System (OPFS) fast.
+ *
+ * Only OPFS has the fast path: FileSystemSyncAccessHandle, which exists only in dedicated
+ * workers. Measured 2026-10-02 on an M4 Pro, Chrome 153: 1.51 GB/s per worker for 1.3 MB
+ * random reads, 4.3–5.9 GB/s with 4 read-only workers; File.slice().arrayBuffer() reached
+ * only 0.39 GB/s. (~/Code/knowledge/notes/browser-tab-can-stream-weights-from-ssd.md)
+ *
+ * Shared by the SSD-streaming engines (Qwen3-MoE experts, Gemma 4 PLE rows). No engine
+ * dependencies. Works from a page or from inside an engine worker: the reader and writer
+ * workers are spawned from inlined Blob URLs, so there is no extra file to vendor.
+ *
+ *   const pool = await OpfsReaderPool.open('localmind-ssd/<model>/experts.bin', { workers: 4 });
+ *   const { buf } = await pool.read(offset, length, recycled);      // one contiguous range
+ *   const { buf } = await pool.readv([{ offset, length }, …], into); // many small ranges, packed
+ *   pool.close();
+ *
+ *   const w = await OpfsWriter.open('localmind-ssd/<model>/experts.bin', { truncate: true });
+ *   await w.write(u8, at); await w.close();   // a read-write handle is exclusive: close it first
+ *
+ * Buffers move by transfer, never by copy; pass a previously returned buffer back in to
+ * recycle it.
+ *
+ * Inside a dedicated worker, `{ inline: true }` (see canInline()) skips the worker hop: the
+ * sync handle lives in the calling thread, and the pool gains readSync() for a per-token
+ * critical path where a postMessage round trip would cost more than the read.
+ */
+
+// The file operations, shared by the worker and the inline (same-thread) mode. Kept
+// self-contained: it is stringified into the worker's Blob source.
+function makeOps() {
+  let handle = null;
+  const openFile = async (path, create) => {
+    const parts = path.split('/').filter(Boolean);
+    let dir = await navigator.storage.getDirectory();
+    for (const p of parts.slice(0, -1)) dir = await dir.getDirectoryHandle(p, { create });
+    return dir.getFileHandle(parts[parts.length - 1], { create });
+  };
+  const readFull = (u8, at) => {
+    let got = 0;
+    while (got < u8.byteLength) {
+      const n = handle.read(u8.subarray(got), { at: at + got });
+      if (n <= 0) break;
+      got += n;
+    }
+    return got;
+  };
+  // → [reply, transferList]
+  const run = async (m) => {
+    try {
+      if (m.op === 'open') {
+        const fh = await openFile(m.path, !!m.create);
+        handle = await fh.createSyncAccessHandle(m.mode === 'readwrite' ? {} : { mode: 'read-only' });
+        if (m.truncate) handle.truncate(0);
+        return [{ id: m.id, size: handle.getSize() }, []];
+      }
+      if (m.op === 'read') {
+        const t0 = performance.now();
+        const got = readFull(new Uint8Array(m.buf, 0, m.length), m.at);
+        return [{ id: m.id, buf: m.buf, got, ms: performance.now() - t0 }, [m.buf]];
+      }
+      if (m.op === 'readv') {
+        const t0 = performance.now();
+        let pos = 0, got = 0;
+        for (let i = 0; i < m.ranges.length; i += 2) {
+          const len = m.ranges[i + 1];
+          got += readFull(new Uint8Array(m.buf, pos, len), m.ranges[i]);
+          pos += len;
+        }
+        return [{ id: m.id, buf: m.buf, got, ms: performance.now() - t0 }, [m.buf]];
+      }
+      if (m.op === 'write') {
+        const u8 = new Uint8Array(m.buf, 0, m.length);
+        let put = 0;
+        while (put < u8.byteLength) put += handle.write(u8.subarray(put), { at: m.at + put });
+        return [{ id: m.id, buf: m.buf, put }, [m.buf]];
+      }
+      if (m.op === 'truncate') { handle.truncate(m.size); return [{ id: m.id, size: handle.getSize() }, []]; }
+      if (m.op === 'flush') { handle.flush(); return [{ id: m.id, size: handle.getSize() }, []]; }
+      if (m.op === 'close') {
+        if (handle) { if (m.flush) handle.flush(); handle.close(); }
+        handle = null;
+        return [{ id: m.id, closed: true }, []];
+      }
+      return [{ id: m.id, error: `unknown op ${m.op}` }, []];
+    } catch (err) {
+      return [{ id: m.id, error: `${(err && err.name) || 'Error'}: ${(err && err.message) || err}`, buf: m.buf }, m.buf ? [m.buf] : []];
+    }
+  };
+  run.sync = {
+    read: (buf, length, at) => readFull(new Uint8Array(buf, 0, length), at),
+    write: (u8, at) => { let put = 0; while (put < u8.byteLength) put += handle.write(u8.subarray(put), { at: at + put }); return put; },
+  };
+  return run;
+}
+
+let workerUrl = null;
+const spawn = () => {
+  if (!workerUrl) {
+    const src = `const run = (${makeOps.toString()})();\nself.onmessage = async (e) => { const [r, t] = await run(e.data); self.postMessage(r, t); };`;
+    workerUrl = URL.createObjectURL(new Blob([src], { type: 'text/javascript' }));
+  }
+  return new Worker(workerUrl);
+};
+
+// Inline mode needs a sync access handle in this thread: only a dedicated worker has one.
+export const canInline = () => typeof FileSystemSyncAccessHandle !== 'undefined'
+  && typeof DedicatedWorkerGlobalScope !== 'undefined' && self instanceof DedicatedWorkerGlobalScope;
+
+// Same interface as Channel, but the file operations run in this thread.
+class InlineChannel {
+  constructor() { this.run = makeOps(); this.inflight = 0; this.nextId = 1; }
+  async call(msg) {
+    this.inflight++;
+    try {
+      const [r] = await this.run({ ...msg, id: this.nextId++ });
+      if (r.error) { const err = new Error(r.error); err.buf = r.buf; throw err; }
+      return r;
+    } finally { this.inflight--; }
+  }
+  terminate() {}
+}
+
+// One worker, request/response matched by id; requests run in arrival order.
+class Channel {
+  constructor() {
+    this.worker = spawn();
+    this.pending = new Map();
+    this.nextId = 1;
+    this.inflight = 0;
+    this.worker.onmessage = (e) => {
+      const m = e.data, p = this.pending.get(m.id);
+      if (!p) return;
+      this.pending.delete(m.id);
+      this.inflight--;
+      if (m.error) { const err = new Error(m.error); err.buf = m.buf; p.reject(err); } else p.resolve(m);
+    };
+    this.worker.onerror = (e) => {
+      for (const p of this.pending.values()) p.reject(new Error(`OPFS worker failed: ${e.message || e}`));
+      this.pending.clear();
+    };
+  }
+  call(msg, transfer = []) {
+    const id = this.nextId++;
+    this.inflight++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.worker.postMessage({ ...msg, id }, transfer);
+    });
+  }
+  terminate() { this.worker.terminate(); }
+}
+
+const bufferFor = (into, length) => (into && into.byteLength >= length ? into : new ArrayBuffer(length));
+
+export class OpfsReaderPool {
+  // inline: true → no workers; reads run on this thread's own sync handle (dedicated
+  // worker only, see canInline()), and readSync() is available for a critical path.
+  static async open(path, { workers = 4, inline = false } = {}) {
+    const pool = new OpfsReaderPool();
+    pool.path = path;
+    pool.inline = inline;
+    pool.channels = [];
+    if (inline) pool.channels.push(new InlineChannel());
+    else for (let i = 0; i < workers; i++) pool.channels.push(new Channel());
+    const sizes = await Promise.all(pool.channels.map((c) => c.call({ op: 'open', path })));
+    pool.size = sizes[0].size;
+    return pool;
+  }
+  pick() {
+    let best = this.channels[0];
+    for (const c of this.channels) if (c.inflight < best.inflight) best = c;
+    return best;
+  }
+  // → { buf, got, ms }; `buf` is `into` when it was large enough, else a new ArrayBuffer.
+  read(offset, length, into) {
+    const buf = bufferFor(into, length);
+    return this.pick().call({ op: 'read', at: offset, length, buf }, [buf]);
+  }
+  // Inline mode only: a synchronous read, no promise. → bytes read.
+  readSync(offset, length, into) {
+    if (!this.inline) throw new Error('readSync needs OpfsReaderPool.open(path, { inline: true })');
+    return this.channels[0].run.sync.read(into, length, offset);
+  }
+  // ranges: [{ offset, length }]. The bytes land back-to-back in `buf`, in order.
+  readv(ranges, into) {
+    let total = 0;
+    const flat = new Array(ranges.length * 2);
+    ranges.forEach((r, i) => { flat[2 * i] = r.offset; flat[2 * i + 1] = r.length; total += r.length; });
+    const buf = bufferFor(into, total);
+    return this.pick().call({ op: 'readv', ranges: flat, buf }, [buf]);
+  }
+  async close() {
+    await Promise.all(this.channels.map((c) => c.call({ op: 'close' }).catch(() => {})));
+    for (const c of this.channels) c.terminate();
+    this.channels = [];
+  }
+}
+
+export class OpfsWriter {
+  // inline: true → the read-write sync handle lives in this thread (dedicated worker only).
+  static async open(path, { truncate = false, inline = false } = {}) {
+    const w = new OpfsWriter();
+    w.path = path;
+    w.ch = inline ? new InlineChannel() : new Channel();
+    w.size = (await w.ch.call({ op: 'open', path, create: true, mode: 'readwrite', truncate })).size;
+    return w;
+  }
+  // Copies `u8` into a transferable buffer only when it is a view on part of a larger one.
+  // Resolves with the (recycled) ArrayBuffer once the bytes are written.
+  async write(u8, at) {
+    let buf = u8.buffer, length = u8.byteLength;
+    if (this.ch instanceof InlineChannel) { this.ch.run.sync.write(u8, at); return buf; }
+    if (u8.byteOffset !== 0 || buf.byteLength !== length || (typeof SharedArrayBuffer !== 'undefined' && buf instanceof SharedArrayBuffer)) {
+      buf = new ArrayBuffer(length);
+      new Uint8Array(buf).set(u8);
+    }
+    const r = await this.ch.call({ op: 'write', at, length, buf }, [buf]);
+    return r.buf;
+  }
+  // Like write(), but takes ownership of `buf` (no copy) — the caller gets it back when done.
+  async writeOwned(buf, length, at) {
+    const r = await this.ch.call({ op: 'write', at, length, buf }, [buf]);
+    return r.buf;
+  }
+  async truncate(size) { return (await this.ch.call({ op: 'truncate', size })).size; }
+  async flush() { return (await this.ch.call({ op: 'flush' })).size; }
+  async close() { await this.ch.call({ op: 'close', flush: true }); this.ch.terminate(); }
+}
+
+export async function opfsDir(path, { create = false } = {}) {
+  let dir = await navigator.storage.getDirectory();
+  for (const p of path.split('/').filter(Boolean)) dir = await dir.getDirectoryHandle(p, { create });
+  return dir;
+}
+
+export async function readOpfsText(path) {
+  const parts = path.split('/').filter(Boolean);
+  try {
+    const dir = await opfsDir(parts.slice(0, -1).join('/'));
+    const f = await (await dir.getFileHandle(parts[parts.length - 1])).getFile();
+    return await f.text();
+  } catch (_) { return null; }
+}
+
+export async function writeOpfsText(path, text) {
+  const parts = path.split('/').filter(Boolean);
+  const dir = await opfsDir(parts.slice(0, -1).join('/'), { create: true });
+  const fh = await dir.getFileHandle(parts[parts.length - 1], { create: true });
+  const w = await fh.createWritable();
+  await w.write(text);
+  await w.close();
+}
+
+export async function removeOpfs(path) {
+  const parts = path.split('/').filter(Boolean);
+  const dir = await opfsDir(parts.slice(0, -1).join('/'));
+  await dir.removeEntry(parts[parts.length - 1], { recursive: true });
+}

src/rows.js

@@ -0,0 +1,230 @@
+/* rows.js — rows of a large lookup table (an embedding-style table) served from OPFS into a small GPU-resident
+ * cache. Extracted from LocalMind's ple-opfs.js (2026-10-05), where it serves Gemma 4 E2B/E4B's per-layer embedding
+ * table from disk; the Gemma-specific helpers stay in LocalMind. `root` is a new option (LocalMind passes
+ * 'localmind-ssd').
+ *
+ *   RowFile   fixed-size rows in one OPFS file plus manifest.json; synchronous reads through opfs-reader.js in
+ *             inline mode, so it must live in a dedicated worker.
+ *   RowCache  `slots` rows on the GPU, split into planes (byte ranges of a row that live in separate GPU buffers),
+ *             an O(1) LRU, and a CPU id→slot mirror (optionally a GPU u32 map). lookup(ids) makes every id
+ *             resident and returns its slot, writing missing rows with queue.writeBuffer.
+ */
+
+import { OpfsReaderPool, OpfsWriter, canInline, readOpfsText, writeOpfsText, removeOpfs } from './opfs-reader.js';
+
+export const ROOT = 'diskformer';
+const FORMAT = 'localmind-rows/1';   // unchanged from LocalMind, so a store it wrote stays valid
+
+// FNV-1a over a few samples of each source buffer and their lengths: cheap enough to run on every
+// load, and it changes when the model's weights change.
+export function fingerprint(buffers, sample = 1 << 16) {
+  let h = 0x811c9dc5;
+  const mix = (b) => { h ^= b; h = Math.imul(h, 0x01000193) >>> 0; };
+  for (const u8 of buffers) {
+    for (const v of [u8.length & 0xff, (u8.length >>> 8) & 0xff, (u8.length >>> 16) & 0xff, (u8.length >>> 24) & 0xff]) mix(v);
+    const starts = [0, Math.max(0, (u8.length >> 1) - (sample >> 1)), Math.max(0, u8.length - sample)];
+    for (const s of starts) for (let i = s, e = Math.min(u8.length, s + sample); i < e; i++) mix(u8[i]);
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+// Fixed-size rows in one OPFS file, <root>/<key>/<name>, with manifest.json beside it.
+// The file I/O is opfs-reader.js in inline mode: the sync handle lives in this dedicated worker,
+// so a row read is a plain synchronous call with no worker hop.
+export class RowFile {
+  #reader = null;
+
+  constructor({ key, name, rowBytes, rows, root = ROOT }) {
+    this.path = `${root}/${key}/${name}`;
+    this.manifestPath = `${root}/${key}/manifest.json`;
+    this.name = name;
+    this.rowBytes = rowBytes;
+    this.rows = rows;
+    this.manifest = null;
+  }
+
+  static async open({ key, name = 'rows.bin', rowBytes, rows, root = ROOT }) {
+    if (!canInline()) throw new Error('RowFile needs a dedicated worker (FileSystemSyncAccessHandle)');
+    const f = new RowFile({ key, name, rowBytes, rows, root });
+    try { f.manifest = JSON.parse(await readOpfsText(f.manifestPath)); } catch (_) { f.manifest = null; }
+    return f;
+  }
+
+  matches(fp) {
+    const m = this.manifest;
+    return !!m && m.format === FORMAT && m.complete === true && m.name === this.name &&
+      m.rowBytes === this.rowBytes && m.rows === this.rows && m.fingerprint === fp;
+  }
+
+  // fill(row0, count, dst) writes `count` rows starting at `row0` into dst (count * rowBytes bytes).
+  // The manifest is removed first and written last, so an interrupted write is never taken as valid.
+  async write(fp, fill, { batchRows = 8192, extra = {} } = {}) {
+    this.close();
+    await removeOpfs(this.manifestPath).catch(() => {});
+    this.manifest = null;
+    const total = this.rows * this.rowBytes;
+    const t0 = performance.now();
+    const w = await OpfsWriter.open(this.path, { truncate: true, inline: true });
+    try {
+      const buf = new Uint8Array(batchRows * this.rowBytes);
+      for (let row0 = 0; row0 < this.rows; row0 += batchRows) {
+        const n = Math.min(batchRows, this.rows - row0);
+        const view = buf.subarray(0, n * this.rowBytes);
+        fill(row0, n, view);
+        await w.write(view, row0 * this.rowBytes);
+      }
+    } finally { await w.close(); }
+    const writeMs = performance.now() - t0;
+    this.manifest = { format: FORMAT, name: this.name, rowBytes: this.rowBytes, rows: this.rows, bytes: total,
+      fingerprint: fp, complete: true, writtenAt: new Date().toISOString(), writeMs: Math.round(writeMs), ...extra };
+    await writeOpfsText(this.manifestPath, JSON.stringify(this.manifest, null, 1));
+    return writeMs;
+  }
+
+  async openRead() {
+    if (this.#reader) return;
+    const r = await OpfsReaderPool.open(this.path, { inline: true });
+    if (r.size !== this.rows * this.rowBytes) {
+      await r.close();
+      throw new Error(`RowFile ${this.name}: size ${r.size} != ${this.rows * this.rowBytes}`);
+    }
+    this.#reader = r;
+  }
+
+  // Reads rows [row, row + count) to the start of dst (a Uint8Array that starts its buffer).
+  readRows(row, count, dst) {
+    if (dst.byteOffset !== 0) throw new Error('RowFile.readRows: dst must start at offset 0 of its buffer');
+    const len = count * this.rowBytes;
+    const got = this.#reader.readSync(row * this.rowBytes, len, dst.buffer);
+    if (got !== len) throw new Error(`RowFile ${this.name}: read ${got} of ${len} bytes at row ${row}`);
+  }
+
+  // Closes the read handle. In inline mode the handle closes synchronously inside this call.
+  close() {
+    if (this.#reader) { this.#reader.close(); this.#reader = null; }
+  }
+}
+
+export class RowCache {
+  // file: an open RowFile. slots: rows held on the GPU. planes: [{ offset, bytes, buffer }], each
+  // row byte range [offset, offset + bytes) is stored at buffer[slot * bytes]. queue: GPUQueue.
+  // mapBuffer (optional): a GPU u32[file.rows] copy of the id->slot map, 0xFFFFFFFF when absent.
+  constructor({ file, slots, planes, queue, mapBuffer = null }) {
+    this.file = file;
+    this.slots = slots;
+    this.planes = planes;
+    this.queue = queue;
+    this.mapBuffer = mapBuffer;
+    this.slotOf = new Int32Array(file.rows).fill(-1);
+    this.idOf = new Int32Array(slots).fill(-1);
+    // LRU as a doubly linked list over slots; head = least recently used. Starts as 0..slots-1.
+    this.prev = new Int32Array(slots);
+    this.next = new Int32Array(slots);
+    for (let s = 0; s < slots; s++) { this.prev[s] = s - 1; this.next[s] = s + 1 < slots ? s + 1 : -1; }
+    this.head = 0;
+    this.tail = slots - 1;
+    this.stamp = new Uint32Array(slots);
+    this.clock = 0;
+    this.row = new Uint8Array(file.rowBytes);
+    this.u32 = new Uint32Array(1);
+    this.stats = { lookups: 0, ids: 0, misses: 0, readMs: 0, replays: 0 };
+    this.missLog = []; // the first 4,096 ids installed after load, for analysis
+  }
+
+  #touch(s) {
+    if (s === this.tail) return;
+    const p = this.prev[s], n = this.next[s];
+    if (p >= 0) this.next[p] = n; else this.head = n;
+    this.prev[n] = p;
+    this.prev[s] = this.tail;
+    this.next[s] = -1;
+    this.next[this.tail] = s;
+    this.tail = s;
+  }
+
+  #mapWrite(id, slot) {
+    if (!this.mapBuffer) return;
+    this.u32[0] = slot >>> 0;
+    this.queue.writeBuffer(this.mapBuffer, id * 4, this.u32);
+  }
+
+  #install(id, s) {
+    const old = this.idOf[s];
+    if (old >= 0) { this.slotOf[old] = -1; this.#mapWrite(old, 0xffffffff); }
+    const t0 = performance.now();
+    this.file.readRows(id, 1, this.row);
+    this.stats.readMs += performance.now() - t0;
+    for (const p of this.planes) this.queue.writeBuffer(p.buffer, s * p.bytes, this.row, p.offset, p.bytes);
+    this.idOf[s] = id;
+    this.slotOf[id] = s;
+    this.#mapWrite(id, s);
+    this.stats.misses++;
+    if (this.missLog.length < 4096) this.missLog.push(id);
+  }
+
+  // Makes every id resident and returns its slot. Rows one call uses are never evicted by the same
+  // call, so a call may name at most `slots` distinct ids.
+  lookup(ids, out = new Uint32Array(ids.length)) {
+    const call = ++this.clock;
+    this.stats.lookups++;
+    this.stats.ids += ids.length;
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      let s = this.slotOf[id];
+      if (s < 0) {
+        s = this.head;
+        if (this.stamp[s] === call) throw new Error(`RowCache: one lookup needs more than ${this.slots} rows`);
+        this.#install(id, s);
+      }
+      this.stamp[s] = call;
+      this.#touch(s);
+      out[i] = s;
+    }
+    return out;
+  }
+
+  has(id) { return this.slotOf[id] >= 0; }
+
+  // Loads rows [row0, row0 + count) into the least recently used slots in large reads (for a warm
+  // set at load), then uploads the whole id->slot map once. Returns the milliseconds spent.
+  warm(row0, count, batch = 4096) {
+    const t0 = performance.now();
+    count = Math.min(count, this.slots);
+    const rb = this.file.rowBytes;
+    const buf = new Uint8Array(batch * rb);
+    const planeBufs = this.planes.map((p) => new Uint8Array(batch * p.bytes));
+    for (let r = row0; r < row0 + count; r += batch) {
+      const n = Math.min(batch, row0 + count - r);
+      this.file.readRows(r, n, buf);
+      // Fresh slots come from the LRU head in order; collect them and write contiguous runs.
+      const slots = new Int32Array(n);
+      for (let i = 0; i < n; i++) {
+        const id = r + i;
+        let s = this.slotOf[id];
+        if (s < 0) {
+          s = this.head;
+          const old = this.idOf[s];
+          if (old >= 0) this.slotOf[old] = -1;
+          this.idOf[s] = id;
+          this.slotOf[id] = s;
+        }
+        this.#touch(s);
+        slots[i] = s;
+      }
+      for (let pi = 0; pi < this.planes.length; pi++) {
+        const p = this.planes[pi], dst = planeBufs[pi];
+        for (let i = 0; i < n; i++) dst.set(buf.subarray(i * rb + p.offset, i * rb + p.offset + p.bytes), i * p.bytes);
+        let i = 0;
+        while (i < n) {
+          let j = i + 1;
+          while (j < n && slots[j] === slots[j - 1] + 1) j++;
+          this.queue.writeBuffer(p.buffer, slots[i] * p.bytes, dst, i * p.bytes, (j - i) * p.bytes);
+          i = j;
+        }
+      }
+    }
+    // slotOf's bytes are the GPU map: -1 as an Int32 is 0xFFFFFFFF as a u32.
+    if (this.mapBuffer) this.queue.writeBuffer(this.mapBuffer, 0, this.slotOf);
+    return performance.now() - t0;
+  }
+}

style.css

@@ -1,28 +0,0 @@
-body {
-	padding: 2rem;
-	font-family: -apple-system, BlinkMacSystemFont, "Arial", sans-serif;
-}
-
-h1 {
-	font-size: 16px;
-	margin-top: 0;
-}
-
-p {
-	color: rgb(107, 114, 128);
-	font-size: 15px;
-	margin-bottom: 10px;
-	margin-top: 5px;
-}
-
-.card {
-	max-width: 620px;
-	margin: 0 auto;
-	padding: 16px;
-	border: 1px solid lightgray;
-	border-radius: 16px;
-}
-
-.card p:last-child {
-	margin-bottom: 0;
-}