@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/voice-first-agent/files/main.ts

@@ -0,0 +1,160 @@
+// Voice agent browser runtime.
+//
+// Round-trip: press → MediaRecorder captures mic → release → POST blob to
+// /api/stt → POST transcript to /api/llm → POST reply to /api/tts → play
+// returned audio blob. All three backend routes are contracts documented in
+// api/README.md — wire them to Whisper / any LLM via router.tangle.tools /
+// ElevenLabs or swap in the provider of your choice.
+
+const talk = document.getElementById('talk') as HTMLButtonElement
+const playback = document.getElementById('playback') as HTMLAudioElement
+const log = document.getElementById('log') as HTMLPreElement
+
+type State = 'idle' | 'recording' | 'thinking'
+let mediaRecorder: MediaRecorder | null = null
+let chunks: Blob[] = []
+let currentStream: MediaStream | null = null
+
+function say(line: string): void {
+  const ts = new Date().toLocaleTimeString()
+  log.textContent = `[${ts}] ${line}\n${log.textContent ?? ''}`.slice(0, 4000)
+}
+
+function setState(next: State): void {
+  talk.dataset.state = next
+  talk.textContent = next === 'recording' ? 'Release to send' : next === 'thinking' ? 'Thinking…' : 'Hold to talk'
+  talk.disabled = next === 'thinking'
+}
+
+/**
+ * Pick a MIME type MediaRecorder will actually accept on this browser.
+ * Safari ≤16 rejects `audio/webm` entirely and requires `audio/mp4`;
+ * Chrome/Firefox prefer `audio/webm;codecs=opus`. Always feature-detect.
+ */
+function pickMimeType(): string | undefined {
+  const candidates = [
+    'audio/webm;codecs=opus',
+    'audio/webm',
+    'audio/mp4;codecs=mp4a.40.2',
+    'audio/mp4',
+    'audio/ogg;codecs=opus',
+  ]
+  for (const mime of candidates) {
+    if (MediaRecorder.isTypeSupported(mime)) return mime
+  }
+  // Let MediaRecorder pick its default — still works on some browsers.
+  return undefined
+}
+
+async function startRecording(): Promise<void> {
+  if (mediaRecorder?.state === 'recording') return
+
+  // getUserMedia prompts the OS permission dialog on first call. The prompt
+  // is user-gesture gated: if we're not in a click/touch handler context
+  // Safari silently rejects even before showing the prompt.
+  try {
+    currentStream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+      },
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    say(`mic denied: ${message}. Check browser permissions and that the page is served over HTTPS.`)
+    setState('idle')
+    return
+  }
+
+  const mimeType = pickMimeType()
+  chunks = []
+  mediaRecorder = new MediaRecorder(currentStream, mimeType ? { mimeType } : undefined)
+
+  mediaRecorder.addEventListener('dataavailable', (ev) => {
+    if (ev.data.size > 0) chunks.push(ev.data)
+  })
+
+  mediaRecorder.addEventListener('stop', async () => {
+    // Release the mic — otherwise the tab-indicator light stays on and on
+    // iOS the device mic stays locked to this page until tab close.
+    currentStream?.getTracks().forEach((t) => t.stop())
+    currentStream = null
+
+    const mime = mediaRecorder?.mimeType ?? mimeType ?? 'application/octet-stream'
+    const blob = new Blob(chunks, { type: mime })
+    chunks = []
+    await roundTrip(blob)
+  })
+
+  mediaRecorder.start()
+  setState('recording')
+  say(`recording (${mimeType ?? 'default mime'})…`)
+}
+
+function stopRecording(): void {
+  if (mediaRecorder?.state === 'recording') {
+    mediaRecorder.stop()
+    setState('thinking')
+  }
+}
+
+async function roundTrip(audio: Blob): Promise<void> {
+  try {
+    // 1. STT — raw audio body, never base64 (1.33× bloat).
+    say(`→ /api/stt (${audio.size} bytes ${audio.type})`)
+    const sttRes = await fetch('/api/stt', {
+      method: 'POST',
+      headers: { 'content-type': audio.type || 'application/octet-stream' },
+      body: audio,
+    })
+    if (!sttRes.ok) throw new Error(`stt failed: ${sttRes.status}`)
+    const { text } = (await sttRes.json()) as { text: string }
+    say(`user: ${text}`)
+
+    // 2. LLM — transcript in, reply out.
+    const llmRes = await fetch('/api/llm', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ transcript: text }),
+    })
+    if (!llmRes.ok) throw new Error(`llm failed: ${llmRes.status}`)
+    const { reply } = (await llmRes.json()) as { reply: string }
+    say(`agent: ${reply}`)
+
+    // 3. TTS — text in, audio bytes out.
+    const ttsRes = await fetch('/api/tts', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: reply }),
+    })
+    if (!ttsRes.ok) throw new Error(`tts failed: ${ttsRes.status}`)
+    const audioBlob = await ttsRes.blob()
+
+    // Playback must start from a same-gesture path on Safari. The button
+    // press -> release flow satisfies that — we're still inside the pointer
+    // gesture context that started the recording.
+    playback.src = URL.createObjectURL(audioBlob)
+    await playback.play()
+  } catch (err) {
+    say(`error: ${err instanceof Error ? err.message : String(err)}`)
+  } finally {
+    setState('idle')
+  }
+}
+
+// Pointer events unify mouse + touch + pen without the iOS 300ms tap delay.
+talk.addEventListener('pointerdown', (ev) => {
+  ev.preventDefault()
+  void startRecording()
+})
+talk.addEventListener('pointerup', (ev) => {
+  ev.preventDefault()
+  stopRecording()
+})
+talk.addEventListener('pointerleave', () => {
+  // Cancel if the user drags off the button rather than releasing on it.
+  stopRecording()
+})
+
+setState('idle')

package/registry/layers/framework/voice-first-agent/files/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/registry/layers/framework/voice-first-agent/manifest.json

@@ -0,0 +1,48 @@
+{
+  "id": "voice-first-agent",
+  "description": "Push-to-talk voice agent browser runtime — MediaRecorder → /api/stt → /api/llm → /api/tts round-trip with Safari/Chrome/Firefox MIME negotiation.",
+  "appliesTo": ["voice-first-agent"],
+  "files": [
+    { "source": "files/main.ts", "target": "src/main.ts" },
+    { "source": "files/vite-env.d.ts", "target": "src/vite-env.d.ts" }
+  ],
+  "packageDeps": {
+    "devDependencies": {
+      "typescript": "^5.9.0",
+      "vite": "^6.4.2"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Browser-native push-to-talk agents — mic capture, STT → LLM → TTS round-trips — where zero SDK lock-in and cross-browser compatibility matter more than server-side streaming.",
+    "firstSteps": [
+      "Run `pnpm install` then `pnpm dev` — Vite serves on port 4180 (configured in vite.config.ts). The push-to-talk UI renders immediately; mic permission is requested on first button press.",
+      "Wire the three API routes documented in `api/README.md`: POST /api/stt (audio blob → { text }), POST /api/llm ({ transcript } → { reply }), POST /api/tts ({ text } → audio bytes). All logic lives in `src/main.ts`.",
+      "Run `node validate-voice.mjs` (or `pnpm validate`) to verify scaffold coherence before wiring backends.",
+      "Run `pnpm build` to emit a static bundle to `dist/` — deploy behind any CDN that serves HTTPS (required for getUserMedia outside localhost)."
+    ],
+    "gotchas": [
+      "getUserMedia requires HTTPS outside localhost — any plain-HTTP deployment gets NotAllowedError before the mic prompt even appears.",
+      "MediaRecorder MIME support varies by browser: Safari prefers audio/mp4, Chrome/Firefox prefer audio/webm;codecs=opus. pickMimeType() in main.ts handles this via isTypeSupported() — do not bypass it.",
+      "Safari autoplay blocks Audio.play() without a prior user gesture. The pointerdown → roundTrip() path satisfies the requirement; do not move playback into a setTimeout or async callback that escapes the gesture context.",
+      "Call track.stop() on each MediaStreamTrack when recording ends to release the mic-active indicator. main.ts does this in the 'stop' event handler — preserve that pattern if you refactor.",
+      "The /api proxy in vite.config.ts only works during `pnpm dev`. For production, route /api/* through your deployment platform (Cloudflare Workers, Vercel rewrite rules, etc.)."
+    ],
+    "architectureNotes": [
+      "main.ts is an intentionally single-file, no-framework runtime. All state (mediaRecorder, chunks, currentStream) is module-level — there is no component tree to wire.",
+      "The three API contracts (/api/stt, /api/llm, /api/tts) are the only integration surface — swap any backend without touching browser code.",
+      "Audio is POSTed as a raw Blob body with Content-Type from recorder.mimeType — never base64 in JSON. This keeps the STT payload at native size (~80 KB / 10 s of opus)."
+    ],
+    "placeholders": [
+      {
+        "path": "src/main.ts",
+        "description": "Full push-to-talk runtime. API endpoints (/api/stt, /api/llm, /api/tts) return 500 until you wire real backends — see api/README.md for contracts."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm dev", "pnpm build", "pnpm validate"],
+    "entrypoints": ["src/main.ts", "index.html"],
+    "preview": { "path": "/" },
+    "extensionPoints": ["src/main.ts", "api/"]
+  }
+}

package/registry/layers/framework/wasm-rust/files/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{{headline}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/registry/layers/framework/wasm-rust/files/lib.rs

@@ -0,0 +1,43 @@
+use wasm_bindgen::prelude::*;
+
+// Every function annotated with `#[wasm_bindgen]` becomes callable from JS
+// after `pnpm run build:wasm`. Types are auto-translated — &str → string,
+// Vec<u8> → Uint8Array, primitives passthrough.
+
+#[wasm_bindgen]
+pub fn greet(name: &str) -> String {
+    format!("Hello from Rust+WASM, {name}!")
+}
+
+#[wasm_bindgen]
+pub fn fibonacci(n: u32) -> u64 {
+    if n < 2 {
+        return n as u64;
+    }
+    let mut a: u64 = 0;
+    let mut b: u64 = 1;
+    for _ in 2..=n {
+        let next = a + b;
+        a = b;
+        b = next;
+    }
+    b
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn greet_works() {
+        assert_eq!(greet("world"), "Hello from Rust+WASM, world!");
+    }
+
+    #[test]
+    fn fibonacci_matches_known_values() {
+        assert_eq!(fibonacci(0), 0);
+        assert_eq!(fibonacci(1), 1);
+        assert_eq!(fibonacci(10), 55);
+        assert_eq!(fibonacci(50), 12586269025);
+    }
+}

package/registry/layers/framework/wasm-rust/files/main.ts

@@ -0,0 +1,24 @@
+// Entry point — initializes the WASM module and wires two samples to the
+// DOM. `init()` is synchronous because vite-plugin-top-level-await lets us
+// await the wasm-pack loader at the module level.
+
+import init, { greet, fibonacci } from './pkg/{{crateName}}.js'
+
+await init()
+
+const root = document.getElementById('root')!
+const n = 40
+root.innerHTML = `
+  <section style="padding:2rem;font-family:system-ui,sans-serif;max-width:640px;margin:0 auto">
+    <h1 style="margin:0 0 0.5rem 0">{{headline}}</h1>
+    <p style="margin:0 0 2rem 0;color:#666">{{subheadline}}</p>
+    <pre style="background:#f4f4f4;padding:1rem;border-radius:4px">
+${greet('{{projectName}}')}
+fibonacci(${n}) = ${fibonacci(n)}
+    </pre>
+    <p style="color:#666;font-size:0.85rem">
+      Both lines above were computed by Rust compiled to WASM. Edit
+      <code>src/lib.rs</code> and re-run <code>pnpm run build:wasm</code>.
+    </p>
+  </section>
+`

package/registry/layers/framework/wasm-rust/files/pkg/starter_foundry_wasm.d.ts

@@ -0,0 +1,7 @@
+// Ambient type stub for wasm-pack output. The real module is generated by
+// `pnpm run build:wasm` (via wasm-bindgen). This stub lets `tsc --noEmit`
+// succeed before the wasm has been built. Keep the signatures in sync with
+// the #[wasm_bindgen] exports in src/lib.rs.
+export default function init(input?: unknown): Promise<unknown>
+export function greet(name: string): string
+export function fibonacci(n: number): number

package/registry/layers/framework/wasm-rust/manifest.json

@@ -0,0 +1,23 @@
+{
+  "id": "wasm-rust",
+  "description": "Rust-to-WASM framework layer: sample #[wasm_bindgen] exports, TS loader, index.html, and a minimal DOM wire-up.",
+  "appliesTo": ["wasm-rust"],
+  "files": [
+    {
+      "source": "files/lib.rs",
+      "target": "src/lib.rs"
+    },
+    {
+      "source": "files/main.ts",
+      "target": "src/main.ts"
+    },
+    {
+      "source": "files/pkg/starter_foundry_wasm.d.ts",
+      "target": "src/pkg/starter_foundry_wasm.d.ts"
+    },
+    {
+      "source": "files/index.html",
+      "target": "index.html"
+    }
+  ]
+}

package/registry/layers/framework/webgpu-inference/files/src/main.ts

@@ -0,0 +1,167 @@
+// WebGPU compute bootstrap — runs a matmul WGSL kernel end-to-end:
+// adapter → device → buffers → bind group → pipeline → dispatch → readback.
+//
+// Alternative production path (commented below): Transformers.js auto-
+// detects WebGPU and serves ONNX models via `pipeline()`. Swap in when
+// you need real models instead of a hand-written kernel.
+
+import matmulWgsl from './shaders/matmul.wgsl?raw'
+
+const statusEl = document.getElementById('status') as HTMLDivElement
+const outputEl = document.getElementById('output') as HTMLPreElement
+
+function setStatus(msg: string, cls: 'ok' | 'err' | '' = ''): void {
+  statusEl.textContent = msg
+  statusEl.className = cls
+}
+
+async function run(): Promise<void> {
+  if (!('gpu' in navigator)) {
+    throw new Error('navigator.gpu unavailable — use Chrome 113+, Edge 113+, Safari 18+, or enable dom.webgpu.enabled in Firefox.')
+  }
+
+  const adapter = await navigator.gpu.requestAdapter()
+  if (!adapter) {
+    throw new Error('requestAdapter() returned null — GPU may be blocklisted or disabled in this browser profile.')
+  }
+
+  const device = await adapter.requestDevice()
+  device.lost.then((info) => {
+    setStatus(`GPUDevice lost: ${info.reason} — ${info.message}`, 'err')
+  })
+
+  // --- Inputs: a 4x4 identity-ish matrix @ a 4x4 ramp. Result should be
+  // predictable: for the identity case, C == B.
+  const M = 4, N = 4, K = 4
+  const a = new Float32Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+  ])
+  const b = new Float32Array([
+    1, 2, 3, 4,
+    5, 6, 7, 8,
+    9, 10, 11, 12,
+    13, 14, 15, 16,
+  ])
+
+  // --- Buffers. STORAGE for shader access, COPY_SRC on the output so we
+  // can read it back via a staging buffer.
+  const dimsBuffer = device.createBuffer({
+    size: 16,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  })
+  device.queue.writeBuffer(dimsBuffer, 0, new Uint32Array([M, N, K, 0]))
+
+  const aBuffer = device.createBuffer({
+    size: a.byteLength,
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+  })
+  device.queue.writeBuffer(aBuffer, 0, a)
+
+  const bBuffer = device.createBuffer({
+    size: b.byteLength,
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+  })
+  device.queue.writeBuffer(bBuffer, 0, b)
+
+  const cByteLength = M * N * 4
+  const cBuffer = device.createBuffer({
+    size: cByteLength,
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+  })
+
+  const stagingBuffer = device.createBuffer({
+    size: cByteLength,
+    usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+  })
+
+  // --- Shader + pipeline. Surface WGSL compile errors loudly; silent
+  // NaNs are the worst failure mode when the shader is broken.
+  const shaderModule = device.createShaderModule({ code: matmulWgsl })
+  const compilation = await shaderModule.getCompilationInfo()
+  for (const msg of compilation.messages) {
+    if (msg.type === 'error') {
+      throw new Error(`WGSL compile error at ${msg.lineNum}:${msg.linePos}: ${msg.message}`)
+    }
+  }
+
+  const pipeline = device.createComputePipeline({
+    layout: 'auto',
+    compute: { module: shaderModule, entryPoint: 'main' },
+  })
+
+  const bindGroup = device.createBindGroup({
+    layout: pipeline.getBindGroupLayout(0),
+    entries: [
+      { binding: 0, resource: { buffer: dimsBuffer } },
+      { binding: 1, resource: { buffer: aBuffer } },
+      { binding: 2, resource: { buffer: bBuffer } },
+      { binding: 3, resource: { buffer: cBuffer } },
+    ],
+  })
+
+  // --- Dispatch. Workgroup size (8,8,1) covers an 8x8 tile; ceilDiv so
+  // partial tiles still run with the in-shader bounds check.
+  const WG_X = 8, WG_Y = 8
+  const gx = Math.ceil(M / WG_X)
+  const gy = Math.ceil(N / WG_Y)
+
+  const encoder = device.createCommandEncoder()
+  const pass = encoder.beginComputePass()
+  pass.setPipeline(pipeline)
+  pass.setBindGroup(0, bindGroup)
+  pass.dispatchWorkgroups(gx, gy, 1)
+  pass.end()
+  encoder.copyBufferToBuffer(cBuffer, 0, stagingBuffer, 0, cByteLength)
+  device.queue.submit([encoder.finish()])
+
+  await stagingBuffer.mapAsync(GPUMapMode.READ)
+  const result = new Float32Array(stagingBuffer.getMappedRange().slice(0))
+  stagingBuffer.unmap()
+
+  const adapterInfo = (adapter as GPUAdapter & { info?: GPUAdapterInfo }).info
+  const vendor = adapterInfo?.vendor ?? 'unknown'
+  const arch = adapterInfo?.architecture ?? 'unknown'
+
+  setStatus(`WebGPU ready — adapter ${vendor}/${arch}. Matmul dispatched (${gx}x${gy} workgroups).`, 'ok')
+
+  const rows: string[] = []
+  rows.push(`A (${M}x${K}):\n${formatMatrix(a, M, K)}`)
+  rows.push(`B (${K}x${N}):\n${formatMatrix(b, K, N)}`)
+  rows.push(`C = A @ B (${M}x${N}):\n${formatMatrix(result, M, N)}`)
+  outputEl.textContent = rows.join('\n\n')
+}
+
+function formatMatrix(m: Float32Array, rows: number, cols: number): string {
+  const lines: string[] = []
+  for (let r = 0; r < rows; r++) {
+    const row: string[] = []
+    for (let c = 0; c < cols; c++) {
+      row.push(m[r * cols + c].toFixed(2).padStart(7))
+    }
+    lines.push(row.join(' '))
+  }
+  return lines.join('\n')
+}
+
+// --- Alternative production path: Transformers.js over WebGPU.
+// Uncomment after `pnpm add @huggingface/transformers`. It auto-detects
+// WebGPU and falls back to WASM SIMD when unavailable, so you get one
+// code path across every browser.
+//
+// import { pipeline } from '@huggingface/transformers'
+// const classifier = await pipeline(
+//   'sentiment-analysis',
+//   'Xenova/distilbert-base-uncased-finetuned-sst-2-english',
+//   { device: 'webgpu' },
+// )
+// const out = await classifier('WebGPU in the browser is a game changer.')
+// console.log(out)
+
+run().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err)
+  setStatus(`Fatal: ${message}`, 'err')
+  console.error(err)
+})

package/registry/layers/framework/webgpu-inference/files/src/shaders/matmul.wgsl

@@ -0,0 +1,30 @@
+// Tiled matmul: C = A @ B where A is MxK, B is KxN, C is MxN.
+// Dimensions are injected via the Dims uniform so one pipeline handles
+// any shape. Workgroup 8x8 gives good occupancy on most consumer GPUs;
+// tune to 16x16 for large matrices on desktop, 4x4 for mobile.
+
+struct Dims {
+  M: u32,
+  N: u32,
+  K: u32,
+  _pad: u32,
+}
+
+@group(0) @binding(0) var<uniform> dims: Dims;
+@group(0) @binding(1) var<storage, read> a: array<f32>;
+@group(0) @binding(2) var<storage, read> b: array<f32>;
+@group(0) @binding(3) var<storage, read_write> c: array<f32>;
+
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let row = gid.x;
+  let col = gid.y;
+  if (row >= dims.M || col >= dims.N) {
+    return;
+  }
+  var acc: f32 = 0.0;
+  for (var k: u32 = 0u; k < dims.K; k = k + 1u) {
+    acc = acc + a[row * dims.K + k] * b[k * dims.N + col];
+  }
+  c[row * dims.N + col] = acc;
+}

package/registry/layers/framework/webgpu-inference/manifest.json

@@ -0,0 +1,55 @@
+{
+  "id": "webgpu-inference",
+  "description": "WebGPU inference framework layer — src/main.ts with adapter + device + compute pipeline driving a real matmul WGSL kernel, plus the matmul shader itself.",
+  "appliesTo": ["webgpu-inference"],
+  "files": [
+    { "source": "files/src/main.ts", "target": "src/main.ts" },
+    { "source": "files/src/shaders/matmul.wgsl", "target": "src/shaders/matmul.wgsl" }
+  ],
+  "packageDeps": {
+    "devDependencies": {
+      "@webgpu/types": "^0.1.52",
+      "typescript": "^5.9.0",
+      "vite": "^6.4.2"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Any product that needs to run ML inference inside the browser tab with GPU acceleration — small transformers, embeddings, classifiers, or custom WGSL compute kernels. Pick this over server inference when the workload is latency-sensitive, privacy-sensitive, or must work offline.",
+    "firstSteps": [
+      "Install: `pnpm install` then `pnpm dev` — Vite serves on 5173. Open Chrome 113+, Edge 113+, or Safari 18+; the page prints the output matrix from a GPU matmul.",
+      "The compute pipeline lives in `src/main.ts` — adapter → device → buffers → bind group → pipeline → dispatch → readback. It runs a 4x4 @ 4x4 matmul end-to-end on the GPU.",
+      "The WGSL kernel is in `src/shaders/matmul.wgsl` — edit the workgroup size, tiling, or the inner dot product to benchmark different strategies against a CPU reference.",
+      "For production ML, uncomment the Transformers.js path in `src/main.ts` and `pnpm add @huggingface/transformers` — it auto-detects WebGPU and runs ONNX models with a single `pipeline()` call.",
+      "Build: `pnpm build` emits static assets to `dist/` — deploy to any static host. WebGPU requires HTTPS in production (localhost is exempt)."
+    ],
+    "gotchas": [
+      "WebGPU is Chrome/Edge 113+ and Safari 18+ stable. Firefox ships it behind `dom.webgpu.enabled` — always feature-detect `navigator.gpu` and fall back to WebAssembly SIMD (Transformers.js does this automatically).",
+      "`requestAdapter()` returns `null` on iGPU-blocklisted devices and in private/incognito on some platforms — do not assume adapter is non-null. Surface a user-visible fallback message.",
+      "Buffer sizes must be multiples of 4 bytes and declared with the right `usage` flags — STORAGE for shader-writable, COPY_SRC to read back via a staging buffer, COPY_DST to upload input. Missing COPY_SRC silently produces zeros on readback.",
+      "`mapAsync(GPUMapMode.READ)` requires a buffer created with MAP_READ | COPY_DST — you cannot map a STORAGE buffer directly. Always copy STORAGE → staging → map.",
+      "Workgroup size in the WGSL (`@workgroup_size(x,y,z)`) must match the `dispatchWorkgroups(a,b,c)` call such that `a*x`, `b*y`, `c*z` cover the output tensor dimensions. Off-by-one here produces partial outputs with zero-filled tails.",
+      "Shader compilation errors are async — call `await shaderModule.getCompilationInfo()` and check `.messages` during development; a broken shader otherwise produces silent NaN outputs."
+    ],
+    "architectureNotes": [
+      "Create one GPUDevice per page and reuse it across inference calls — `requestDevice()` is expensive and each device has its own command queue and buffer pool.",
+      "Keep bind group layouts explicit (not auto-generated) once the model stabilizes — auto layouts regenerate on each pipeline creation and fragment the cache, hurting cold-start latency.",
+      "For multi-kernel pipelines (attention + MLP + layernorm), batch commands into a single GPUCommandEncoder before submitting — each `queue.submit` incurs a kernel-launch roundtrip."
+    ],
+    "placeholders": [
+      {
+        "path": "src/main.ts",
+        "description": "WebGPU bootstrap — adapter, device, input/output/staging buffers, bind group, compute pipeline, dispatch, readback, DOM print. Replace the 4x4 matmul with the product's real kernel (attention QK^T, GEMM, convolution) or flip to the Transformers.js branch for ONNX models."
+      },
+      {
+        "path": "src/shaders/matmul.wgsl",
+        "description": "Minimal tiled matmul compute shader. Extend for fused kernels (matmul + bias + activation), different dtypes (f16 via the shader-f16 feature), or quantization (int8 dot-product via DP4a)."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm dev", "pnpm build", "pnpm run validate"],
+    "entrypoints": ["src/main.ts", "src/shaders/matmul.wgsl"],
+    "preview": { "path": "/" },
+    "extensionPoints": ["src/main.ts", "src/shaders/matmul.wgsl"]
+  }
+}