create-triscope 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 triscope contributors
+
+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.

package/README.md

@@ -0,0 +1,26 @@
+# create-triscope
+
+Scaffold a new [triscope](https://github.com/tedin7/triscope) project — a
+Three.js + WebGPU lab wired for the triscope MCP tool chain.
+
+```sh
+npm init triscope my-app
+# or with a starter preset:
+npm init triscope my-app -- --preset wave
+```
+
+Then:
+
+```sh
+cd my-app
+npm install
+npm run dev          # open the lab in a WebGPU browser (Chrome/Edge)
+```
+
+The generated project ships a sample `cube` element, a lab page, the telemetry
+Vite plugin, a `.gitignore`, and the `triscope-iteration-loop` skill so an agent
+can drive the converge loop immediately.
+
+Already have a Three.js app? Use `npx triscope adopt` (from
+[`@triscope/cli`](https://www.npmjs.com/package/@triscope/cli)) to retrofit it
+instead. MIT.

package/bin/create.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// `npm init triscope <dir>` — scaffold a new triscope project.
+//
+// Copies packages/create-triscope/template/ to <dir>, doing literal
+// `__PROJECT_NAME__` substitution in package.json and the example skill.
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATE = resolve(__dirname, '../template');
+const PRESETS = resolve(__dirname, '../presets');
+
+// create-triscope is released in lockstep with the @triscope/* packages, so its
+// own version is exactly the range to pin a scaffolded project's deps to. The
+// template ships `^__TRISCOPE_VERSION__`; without this substitution it would keep
+// the placeholder `^0.0.0` and the new project's `npm install` would fail to
+// resolve the real published @triscope/core / @triscope/cli (ETARGET).
+const SELF_VERSION = JSON.parse(
+  readFileSync(resolve(__dirname, '../package.json'), 'utf8'),
+).version;
+
+/** Parse `<dir> [--preset <name>]` from create-triscope's argv. */
+export function parseCreateArgs(argv) {
+  let dir;
+  let preset;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--preset') preset = argv[++i];
+    else if (!dir && !argv[i].startsWith('--')) dir = argv[i];
+  }
+  return { dir, preset };
+}
+
+/** Add `<name>: 'labs/<name>.html'` to vite's rollupOptions.input (idempotent,
+ *  additive — never clobbers existing entries). */
+export function injectLabInput(viteText, name) {
+  if (viteText.includes(`labs/${name}.html`)) return viteText;
+  const line = `        ${name}: 'labs/${name}.html',`;
+  return viteText.replace(/(\n[ \t]*index: 'index\.html',)/, `$1\n${line}`);
+}
+
+/** Overlay a preset onto an already-scaffolded project (additive copy + vite input). */
+export function applyPreset(target, preset, subs) {
+  const src = join(PRESETS, preset);
+  if (!existsSync(src)) {
+    const avail = existsSync(PRESETS) ? readdirSync(PRESETS).join(', ') : '(none)';
+    throw new Error(`unknown preset "${preset}". Available: ${avail || '(none)'}`);
+  }
+  copyDir(src, target, subs);
+  const vitePath = join(target, 'vite.config.js');
+  if (existsSync(vitePath)) {
+    writeFileSync(vitePath, injectLabInput(readFileSync(vitePath, 'utf8'), preset));
+  }
+}
+
+export function copyDir(src, dst, subs) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const sPath = join(src, entry);
+    const stat = statSync(sPath);
+    if (stat.isDirectory()) {
+      copyDir(sPath, join(dst, entry), subs);
+    } else {
+      // npm refuses to publish a literal `.gitignore` (it strips/renames it on
+      // pack), so the template ships it as `gitignore` and we restore the dot at
+      // scaffold time — otherwise every generated project would lack a .gitignore.
+      const outName = entry === 'gitignore' ? '.gitignore' : entry;
+      let content = readFileSync(sPath);
+      // Apply substitutions only to text files
+      if (/\.(json|md|html|ts|js|mjs|cjs|css)$/.test(entry)) {
+        let text = content.toString('utf8');
+        for (const [k, v] of Object.entries(subs)) {
+          text = text.split(k).join(v);
+        }
+        content = Buffer.from(text, 'utf8');
+      }
+      writeFileSync(join(dst, outName), content);
+    }
+  }
+}
+
+export function main() {
+  const { dir: arg, preset } = parseCreateArgs(process.argv.slice(2));
+  if (!arg) {
+    console.error('Usage: npm init triscope <project-dir> [--preset <name>]');
+    process.exit(2);
+  }
+  const target = resolve(process.cwd(), arg);
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`Refusing to scaffold into non-empty directory: ${target}`);
+    process.exit(2);
+  }
+  const projectName = basename(target).replace(/[^A-Za-z0-9._-]/g, '-');
+  const subs = { __PROJECT_NAME__: projectName, __TRISCOPE_VERSION__: SELF_VERSION };
+  copyDir(TEMPLATE, target, subs);
+  if (preset) applyPreset(target, preset, subs);
+  console.log(`Scaffolded ${projectName}${preset ? ` (+${preset} preset)` : ''} at ${target}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  cd ${arg}`);
+  console.log('  npm install');
+  console.log('  npm run dev        # open the lab in Chrome/Edge with WebGPU');
+  if (preset) console.log(`  # open /labs/${preset}.html for the ${preset} preset`);
+  console.log('  # then from another shell:');
+  console.log('  npx triscope state .perf.fps');
+  console.log('  npx triscope list');
+}
+
+// Only auto-run when invoked as a script (not when imported by tests).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main();
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-triscope",
+  "version": "0.4.0",
+  "description": "Scaffold a new Triscope project: Vite + Three.js WebGPU + lab harness + .claude/skills/.",
+  "type": "module",
+  "bin": {
+    "create-triscope": "./bin/create.mjs"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html"
+  },
+  "keywords": [
+    "triscope",
+    "scaffold",
+    "create",
+    "three.js",
+    "webgpu"
+  ]
+}

package/template/.claude/hooks.example.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "Optional Claude Code hook config for triscope. Copy the 'hooks' block into your .claude/settings.local.json (or settings.json) to enable. The hook runs `triscope auto-capture` after every Edit/Write — it reads /tmp/<project>-state.json from the dev server and prints a one-line motion summary so Claude sees current FPS + probe activity in its next turn, without having to call capture_views.",
+  "_what_you_get": "After editing src/triscope/ship-element.ts, the next message to Claude includes a line like: '[triscope] ship motion: sailWanderEnvelope p2p=0.59 freq=0.22Hz'. If peakToPeak is ~0 and windPressure>0, Claude sees the regression immediately without prompting.",
+  "_requirements": "1) `triscope` CLI on PATH (npm i -g @triscope/cli, or `node ./node_modules/@triscope/cli/bin/triscope.mjs`). 2) Dev server running (npm run dev). 3) The element you're iterating on has motionProbes declared (otherwise this hook stays silent).",
+
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "triscope auto-capture --file \"${TOOL_INPUT_file_path:-}\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/adopt-triscope/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: adopt-triscope
+description: Use when ADDING triscope to an existing 3D / Three.js project (retrofit), or wrapping an already-built scene/object so the triscope MCP tools (capture_views, inspect_scene, set_knob, read_telemetry, set_uniform) can drive it. Covers `triscope adopt`, runSceneView, and promoting to a full Element. NOT for a fresh project (use `npm create triscope`).
+---
+
+# Adopting triscope into an existing project
+
+triscope's MCP tools don't observe arbitrary Three.js code — the project must expose `window.__TRISCOPE__` via the harness. The contract: (1) `triscopeTelemetryPlugin()` in vite.config; (2) boot via `runLab`/`runSceneLab`/`runSceneView`; (3) a lab HTML page + `package.json#triscope.labs`. Your mesh/shader/geometry code stays normal Three.js — you just *wrap* it.
+
+## Step 1 — run the retrofit
+
+```
+triscope adopt              # or: triscope adopt --name myscene
+triscope dev --check        # verify Node/deps/chromium/MCP/port
+```
+
+`adopt` injects the Vite plugin (or prints the manual patch if it can't place it — apply it), scaffolds `labs/<name>.html` + `src/labs/<name>.ts` (a `runSceneView` entry with a **placeholder box** so the lab is alive immediately), and wires `rollupOptions.input` + `triscope.labs`. If it warns about a missing dep: `npm i @triscope/core three`.
+
+## Step 2 — point it at YOUR content (decision tree)
+
+Open `src/labs/<name>.ts` and replace the placeholder `getRoot()`.
+
+**A) "I just want to look at / tweak it" → `runSceneView` (stop here for most cases).**
+Wrap any `THREE.Object3D` (or a builder) in ~1 line. Cameras auto-fit from bounds; `autoKnobs:true` reflects named materials/lights into sliders; `set_uniform` tweaks anything else live.
+
+```ts
+import { runSceneView } from '@triscope/core';
+import { buildScene } from '../scene.js'; // your existing function returning a Group/Object3D
+runSceneView(buildScene(), { name: 'myscene', autoKnobs: true });
+```
+
+This unlocks `capture_views`, `inspect_scene` (with a `lights[]` array), `read_uniform`/`set_uniform`, and autoKnobs `set_knob`. Done.
+
+**B) "I need curated camera angles / named knobs / telemetry" → promote to a full Element.**
+Extract the scene build into `mount`, then add intent:
+- **Name your meshes & lights** (`mesh.name = 'hull'`, `light.name = 'sun'`) — that's how `set_uniform`/autoKnobs/`inspect_scene` address them. Unnamed objects are reachable only by uuid.
+- Choose 2–4 **intent** cameras (run `inspect_scene` first to read world positions/bounds), or keep `cameras: 'auto'`.
+- Declare `knobs` + `onKnob` for the params you'll actually tune (auto-derived state isn't tunable unless exposed).
+- Add `telemetry`/`motionProbes` only for hidden state you'll verify (FPS is automatic).
+
+```ts
+// from runSceneView(buildScene()) ... to:
+export const myElement: Element = {
+  name: 'myscene',
+  bounds: { min: [-2,-2,-2], max: [2,2,2] },   // or omit + cameras:'auto'
+  cameras: 'auto',                              // or hand-pick presets
+  knobs: { roughness: { type: 'number', min: 0, max: 1, step: 0.01, default: 0.5 } },
+  onKnob: (h, k, v) => { if (k === 'roughness') h.userData.mat.roughness = Number(v); },
+  telemetry: (h) => ({ tris: h.userData.triCount }),
+  mount: ({ parent }) => { const root = buildScene(); parent.add(root); return { root, dispose: () => parent.remove(root), userData: {} }; },
+};
+// then in the lab entry: runLab({ element: myElement, canvas, ... }) — or mountLabDom() for the DOM.
+```
+
+## Step 3 — iterate
+
+Use **[[triscope-iteration-loop]]** for the edit → reload → telemetry/capture → adjust loop (don't re-derive it here). Key: after editing a `*.lab.ts`-style entry, `capture_views { fresh: true }` to pick up the change.
+
+## Gotchas (learned the hard way)
+
+- **Name things you want to tune.** `set_uniform "sun.intensity"` / autoKnobs only work on NAMED objects.
+- **TSL node-material params aren't reflectable** by autoKnobs — use `set_uniform` (it reaches any material prop by `objectName|uuid.key`).
+- **If your object moves in world space** (physics/animation), fixed cameras lose it → capture goes empty (watch `flatFrames` in `capture_views`). Keep the render centered (treadmill) or use follow-cameras in the lab.
+- **Non-Vite projects:** triscope's plugin is Vite-only; you'd need an equivalent dev-server middleware exposing `/__state`,`/__knob`,`/__manifest`,`/__scene`. Easiest path: a tiny Vite lab page that imports your built scene module.

package/template/.claude/skills/glsl-pitfalls/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: glsl-pitfalls
+description: TSL / WebGPU shader gotchas that cost half a day if you don't know them up front. Use when writing or editing TSL node materials, custom shaders, or debugging "my edit had no effect / the frame went black / the animation froze".
+---
+
+# TSL / WebGPU pitfalls
+
+## 1. Material edits need a full reload, not HMR
+
+A `THREE.Material` (especially a TSL `NodeMaterial`) is baked into the
+renderer's node graph when the scene mounts. Re-running the module after an
+edit does **not** reach the live material, so the edit looks invisible. The
+triscope Vite plugin forces a full page reload for files matching
+`(\.tsl|Element|Mesh|Material|Shader)\.(ts|tsx|js|mjs)$`. If your shader lives
+in a file that doesn't match, rename it or widen `forceReloadOn` in
+`vite.config`. Symptom: "I edited the shader and nothing changed."
+
+## 2. The TSL `time` node overwrites itself every render
+
+`three/tsl`'s `time` is `uniform(0).onRenderUpdate((frame) => frame.time)` — it
+re-reads `renderer.nodeFrame.time` on every render. So if you pause the RAF
+loop and step `ctx.time.value` by hand (e.g. for deterministic capture), any
+shader using `time` will look **frozen** unless you also set
+`renderer.nodeFrame.time`. The harness's `captureMotionFrames('...', {mode:'time'})`
+already does this; hand-rolled capture loops must too.
+
+## 3. Black frame ≠ dark scene
+
+If `captureViews` reports `blackFrame: true` / `luminance < 0.004`, the GPU drew
+nothing — a shader compile error, an unbound uniform, or a NaN, **not** a
+lighting problem. Check the page console for WGSL compile errors before tuning
+exposure. A single NaN in a position/normal computation discards the whole
+primitive.
+
+## 4. Update uniforms, don't rebuild pipelines
+
+Tune via `uniform.value = x` (what knobs + `onKnob` do) — this is live and
+cheap. Re-creating the material or geometry rebuilds the WebGPU pipeline
+(stutter, lost state, possible device churn). Reserve rebuilds for structural
+changes only.
+
+## 5. Color space
+
+Author colors in sRGB and let three convert: set `color.set('#rrggbb')` /
+`THREE.ColorManagement` defaults. Mixing raw linear values with sRGB inputs is
+the usual cause of "too dark" or "washed out" that screenshots can't diagnose —
+confirm with the `luminance` / `dynamicRange` GPU probes, not your eyes.
+
+## 6. Clamp knob inputs you forward to shaders
+
+The harness clamps declared knobs to their spec, but if you forward a value
+into a shader that divides or `pow()`s by it, guard against 0 / negative /
+huge values yourself — a wild uniform yields NaN → black frame (pitfall 3).
+
+See also: [[threejs-telemetry-sink]], [[water-shader-convergence]].

package/template/.claude/skills/threejs-telemetry-sink/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: threejs-telemetry-sink
+description: The read-pixel-into-JSON pattern triscope is built on. Use when you need to verify hidden render state (FPS, uniforms, luminance, dynamic range) instead of squinting at a screenshot, or when adding telemetry() / motionProbes to an element.
+---
+
+# Three.js telemetry sink (numbers beat screenshots)
+
+Triscope's core bet: a still screenshot lies about hidden state (HDR tone,
+exact uniform values, whether anything is animating, whether the GPU even
+drew). **Numbers don't.** The harness publishes a JSON snapshot every ~500 ms
+and exposes per-camera GPU probes on capture.
+
+## The two readback channels
+
+1. **Telemetry sink.** The harness POSTs a snapshot to `/__state`, which the
+   Vite plugin writes to `/tmp/<project>-state.json`. Read it with
+   `triscope state [<jq.path>]` or MCP `read_telemetry`. Contains:
+   `perf.fps`, `knobs`, per-camera `cameras.<name>.{position,target,fov}`,
+   `elements.<name>` (your `telemetry()` return), `elements.<name>.motion`
+   (motion-probe stats), `events`, `selection`/`selections` (inspect mode),
+   and **`warnings`** (recent swallowed failures — knob clamps, black frames,
+   telemetry/probe exceptions; check this first when something seems off).
+
+2. **GPU probes on capture.** `captureViews()` decodes each rendered pane and
+   reports per-camera `{ luminance, p5, p95, dynamicRange, blackFrame }`. A
+   `blackFrame: true` (or a camera in the response's `blackFrames[]`) means the
+   GPU drew nothing — that's a wiring/compile failure, not a dark scene.
+
+## Why `captureViews()` and not a normal screenshot
+
+WebGPU renders into a swap-chain texture the spec implicitly destroys at
+composite time (gpuweb/gpuweb#1781). So `canvas.toDataURL()` called out-of-band
+and CDP `Page.captureScreenshot` both miss the surface and return black/empty.
+The harness's `captureViews()` renders + reads back **inside the same task**,
+which is the only reliable path. Always capture through it (MCP `capture_views`
+does this for you).
+
+## Adding telemetry to an element
+
+```ts
+telemetry: (handle, ctx) => ({
+  // anything JSON-serialisable; merged under elements.<name>
+  triangles: handle.userData.triCount,
+  exposure: handle.userData.uExposure.value,
+}),
+
+// per-frame scalars → ring-buffered stats (latest/mean/min/max/peakToPeak):
+motionProbes: {
+  sailFlutter: (handle, ctx) => handle.userData.uWind.value * Math.sin(ctx.time.value * 4),
+},
+```
+
+## The rule
+
+- Hidden numeric/HDR state → **telemetry** (`read_telemetry`, GPU probes).
+- Shape / composition / silhouette / occlusion → **`capture_views`**.
+- "Is it actually animating?" → **`capture_motion`** or a `motionProbes`
+  `peakToPeak` > 0, never a single still.
+
+See also: [[glsl-pitfalls]], [[water-shader-convergence]].

package/template/.claude/skills/triscope-iteration-loop/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: triscope-iteration-loop
+description: Use when iterating on a 3D element in this triscope project (shader tuning, mesh adjustments, lighting). Lays out the edit → reload → telemetry/capture → adjust loop with the right tools at each step. Prefer numbers over screenshots for hidden state; use capture_views to look at all camera angles in one call.
+---
+
+# Triscope iteration loop
+
+This project is built on triscope: every 3D element lives in
+`src/elements/<name>.ts` and renders in its own multi-camera lab at
+`/labs/<name>.html`. Each element declares cameras, knobs, and telemetry —
+the framework handles the rest.
+
+## The loop
+
+```
+  edit src/elements/<name>.ts            (e.g. drop roughness 0.4 → 0.2)
+        │
+        ▼  Vite HMR
+  browser remounts element in the lab grid
+        │
+        ▼  ~500 ms
+  /tmp/<project>-state.json updates
+        │
+        ▼  you ↓
+  triscope state .elements.<name>        (numeric truth — FPS, uniforms)
+  mcp:capture_views <name>               (visual truth — all N angles)
+        │
+        ▼  judge per-camera
+  triscope smoke <name>                  (CI/sign-off gate)
+```
+
+## Rules learned the hard way (from water3d sessions)
+
+- **Numbers beat screenshots for hidden state.** JPEG compression and the
+  fact that a still can't show motion mean shader tuning by image alone is
+  unreliable. Use `triscope state` to pull FPS, uniform values, lum stats.
+- **Screenshots still win for shape and composition.** Use `capture_views`
+  for layout, silhouette, glint placement, occlusion. Don't try to judge
+  HDR tone from a screenshot — use numbers.
+- **Set knobs with absolute values, not deltas.** Say "drop roughness 0.4 →
+  0.2", not "decrease roughness slightly". The MCP `set_knob` tool takes an
+  absolute value.
+- **Verify per-camera.** A change can fix one pane and break another.
+  "CHASE CAM looks right now" is not "all 8 panes look right now". Walk
+  each named camera.
+- **Reference photos beat memory.** If you have a reference image of what
+  the element should look like, drop it into `refs/<name>/<camera>.png` so
+  diffs are easy.
+
+## Tools in this loop
+
+- `triscope state [<jq.path>]`  — read /tmp/<project>-state.json
+- `triscope list`               — registered elements + cameras + knobs
+- `triscope smoke [<element>]`  — headed Chromium smoke test
+- MCP `read_telemetry`          — same data, accessible to Claude
+- MCP `set_knob`                — live update without reload (single or batched via {updates:[...]})
+- MCP `capture_views`           — render every named camera; inline PNGs in the tool response
+- MCP `set_reference` / `diff_reference` — store a reference photo, get a side-by-side + meanAbsDiff
+- MCP `capture_motion`          — multi-frame filmstrips + motionMagnitude per camera (use for animated elements)
+- MCP `run_smoke`               — `triscope smoke` as a tool
+
+## When the element has motion
+
+A single `capture_views` frame **cannot reveal whether motion is happening** —
+sails could be at amplitude 0 just because you captured at the wrong phase, or
+because windPressure isn't actually wired to deformation. Use these instead:
+
+- **`capture_motion({ element, camera?, frames=6, dt=0.25, mode='time' })`** —
+  returns one filmstrip image per camera (6 frames tiled left-to-right) plus a
+  numeric `motionMagnitude[camera]` (0-255). Read the rule: <1 = static, >5 =
+  visible motion, >20 = vigorous. If you expect motion (windPressure > 0) and
+  magnitude is <1, the wiring is broken — not a tuning problem.
+- **`read_telemetry .elements.<name>.motion`** — if the Element declared
+  `motionProbes`, each probe exposes `{ latest, mean, min, max, peakToPeak,
+  samples: lastN }`. peakToPeak ≈ 0 with non-zero input means the probe isn't
+  changing — the animation isn't propagating to the state you're measuring.
+- **Mode choice.** `mode: 'time'` is deterministic (steps `time.value`
+  forward, ~instant) — use it for shader-driven motion (TSL uniforms, vertex
+  displacement keyed to `ctx.time`). `mode: 'real'` waits dt seconds between
+  frames — use it for CPU-integrated state (springs, particles).
+
+## Editing shaders / TSL materials: full-reload, not HMR
+
+The triscope vite plugin forces a **full page reload** instead of HMR when
+files matching `(\.tsl|Element|Mesh|Material|Shader)\.(ts|tsx|js|mjs)$`
+change. Reason: TSL materials end up baked into the renderer's node graph
+when the scene mounts, so re-running the module after an edit has no
+effect on the running THREE.Material — the new code never reaches the
+renderer. Full-reload is the only reliable way to see shader edits.
+
+Cost: ~1-2 s vs. ~50 ms HMR. Acceptable trade — the failure mode (edits
+silently invisible) costs much more. Plain `.ts` files outside the
+pattern still HMR normally.
+
+To override the pattern or disable: pass `forceReloadOn` to the plugin in
+your `vite.config.ts`:
+
+```ts
+triscopeTelemetryPlugin({
+  forceReloadOn: /custom-pattern/i,   // or pass null to disable entirely
+})
+```
+
+## Cold-start manifest: declare your labs in package.json
+
+If your lab pages don't follow the `/labs/<element>.html` convention,
+declare them in `package.json` so `mcp__triscope__capture_views` works
+on the first call without `labUrl`:
+
+```json
+"triscope": {
+  "labs": {
+    "ship": "/triscope-ship.html",
+    "ocean": "/triscope-ocean.html"
+  }
+}
+```
+
+The vite plugin reads this at boot and seeds `/__manifest` so the MCP
+URL resolver returns the right URL immediately.
+
+## Multi-element scenes: runSceneLab + live add/remove
+
+Two lab shapes:
+
+- **`runLab(element)`** — the single-element lab: one element, **bare** camera/knob
+  names (`bow`, `windPressure`). Most `/labs/<name>.html` pages use this; nothing
+  about it changed.
+- **`runSceneLab({ elements: [a, b, …], mounted? })`** — a SCENE of N elements in
+  one lab grid. Cameras and knobs are **namespaced** `<element>.<key>`, so two
+  elements that both declare `top`/`speed` never collide. Compose ship + sea + sky
+  together and tune them in one page.
+
+In a scene you can instantiate or dispose an element **type** *live, with no
+reload* — the thing a plain edit-reload loop can't do for a brand-new element:
+
+- `mcp__triscope__add_element name=<el> element=<any-mounted-el>` — mount a
+  registered-but-unmounted element. Its `<el>.<camera>` panes appear in the grid,
+  its `<el>.<knob>` knobs appear in the editor, the manifest is re-advertised.
+  Returns `{ ok, mounted:[…], available:[…] }`.
+- `mcp__triscope__remove_element name=<el> element=<any-mounted-el>` — dispose it
+  live; it stays in the registry and is re-addable.
+
+**Rules for scenes (learned from the rewrite):**
+- **Use the namespaced key.** `list_elements` / the manifest advertise
+  `ship.windPressure`, `ship.bow`. Use those with `set_knob` / `capture_views` /
+  `auto_tune`. (set_knob and the tuners also accept the bare local key as a
+  fallback, but the `element.key` form is canonical and avoids surprises.)
+- **add/remove need a page locator.** A scene usually lives on its own page (e.g.
+  `/lab.html`). Pass `element=<a mounted element>` (or `labUrl=…`) so the tool
+  attaches to the right tab — otherwise it targets the default lab and returns
+  `{ ok:false }`.
+- **Single-element labs ignore these.** `add_element`/`remove_element` on a plain
+  `runLab` page return `{ ok:false }`: nothing to add, and removing the only
+  element is blocked on purpose.
+- **`available` minus `mounted`** (in any add/remove response, or `list_elements`)
+  is exactly what you can still mount.
+
+## Reactive loop (optional): the PostToolUse hook
+
+`.claude/hooks.example.json` is a ready-to-paste hook config that wires
+`triscope auto-capture` to run after every Edit/Write. The effect: the next
+message to Claude includes a line like
+
+  `[triscope] ship motion: sailWanderEnvelope p2p=0.59 freq=0.22Hz`
+
+so Claude sees current FPS + probe activity automatically, without calling
+`capture_views` or `read_telemetry`. If you edit shader code and the next
+turn shows `p2p≈0` for a probe that was non-zero before, you broke motion.
+To enable: copy the `"hooks"` block from `.claude/hooks.example.json` into
+your `.claude/settings.local.json`.
+
+## Inspect mode: click-to-select sub-meshes (no grep)
+
+Open a lab with `?inspect=<element>` and the harness flips to a single
+full-canvas camera with OrbitControls. Right-drag to orbit, scroll to
+zoom, **left-click on a part of the mesh** to lock a selection. The
+selection lands in `telemetry.selection` with the *exact source file
+and line* where that mesh was added to the scene — no grep needed.
+
+**From chat:** "ispeziona la nave" → Claude calls
+`mcp__triscope__inspect element=ship`. The running browser flips into
+inspect mode. The user clicks a sail; the next message has
+`selection.source = { file: 'PirateShipMesh.ts', line: 1415, ... }`.
+
+**Open the file at line:** `mcp__triscope__open_selection` reads
+`telemetry.selection.source` and spawns `code --goto file:line:col` (or
+honors $EDITOR). Use after the user says "open this" / "show me the
+code". Sub-second: editor jumps to the right spot.
+
+How it works without code changes: triscope monkey-patches
+`Object3D.prototype.add` at runtime and tags every added object with
+the user-code stack frame from `new Error().stack`. Element authors do
+not modify their code — existing meshes get tagged on the next reload.
+Vite source-maps make the frames resolve to original `.ts` files in
+dev. The selection survives full-reload via localStorage (matched by
+file:line, not Mesh UUID).
+
+## Auto-tune: converge a knob on a reference
+
+When you have a stored reference image for `(element, target_camera)`
+and want to find the knob value that matches it visually:
+
+```
+mcp__triscope__auto_tune element=ship knob=windPressure
+                          range=[0,2] target_camera=bow max_iterations=12
+```
+
+Golden-section search over the range, maximising SSIM (perceptual
+similarity) against the reference. Each iteration: set_knob → 800ms
+wait → captureViews → diff_reference. Converges to ~0.7% of the range
+in 12 iters. Returns best knob value, final SSIM, full history. Leaves
+the lab at the converged value so you see the result.
+
+SSIM > meanAbsDiff as the objective: pixel-level diff chases anti-
+aliasing noise and rewards "darken everything" as fake convergence;
+SSIM tracks actual structural match.
+
+## Snapshot / restore: cheap rollback via git tags
+
+When a tuning pass lands somewhere good and you want to checkpoint
+before a risky rewrite:
+
+```
+mcp__triscope__snapshot name=ship-mast-pass-v3 message="happy w/ sail bulge"
+```
+
+Refuses on a dirty WT (would silently lose your in-progress edits on
+restore). Otherwise creates an annotated tag `triscope/snapshot/<name>`
+whose message stores: HEAD commit + every persisted knob value across
+all elements, as JSON. No working-tree files written, no rebase noise.
+
+Restore later:
+```
+mcp__triscope__restore name=ship-mast-pass-v3
+```
+Checks out the commit (detached HEAD — branch from there if you want
+to keep iterating) and re-posts every knob via `/__knob`. The live lab
+snaps back to the recorded state within ~100 ms.
+
+List what you have: `mcp__triscope__list_snapshots`.
+
+## See also
+
+- [[threejs-telemetry-sink]] — the read-pixel-into-JSON pattern triscope is built on.
+- [[water-shader-convergence]] — for sea/water elements, the
+  Tessendorf/Bruneton/Sea-of-Thieves checklist.
+- [[glsl-pitfalls]] — when writing TSL/GLSL, the gotchas that cost half a
+  day if you don't know about them up front.

package/template/.claude/skills/water-shader-convergence/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: water-shader-convergence
+description: Checklist for converging a believable ocean/water element (waves, foam, refraction, glint, tone). Opt-in — use only when iterating on a sea/water/fluid element. Order the passes; verify each with telemetry + per-camera capture before moving on.
+---
+
+# Water / ocean shader convergence
+
+Water is the element where "tune by screenshot" fails hardest: foam, glint, and
+HDR tone all read wrong in a still. Converge in this order, locking each pass
+with numbers (`read_telemetry`, GPU `luminance`/`dynamicRange`) and a
+multi-angle `capture_views` before touching the next.
+
+## 1. Geometry / wave field first
+
+- Choppiness / steepness and macro amplitude set the silhouette. Get the
+  horizon line and wave scale right at a grazing camera **before** any
+  shading — a `motionProbes` peak-to-peak confirms the surface is actually
+  displacing (a flat `peakToPeak ≈ 0` with non-zero wind = broken wiring, not a
+  tuning problem).
+- FFT (Tessendorf) vs sum-of-Gerstner: FFT gives richer detail but watch the
+  tiling period; Gerstner is cheaper and easier to art-direct.
+
+## 2. Normals / detail
+
+- Normal-map scale and the cascade of detail frequencies drive sparkle. Too
+  strong → noisy glitter that pixel-diff metrics chase (use SSIM, not
+  meanAbsDiff, when converging on a reference).
+
+## 3. Refraction / depth absorption / scattering
+
+- Depth-absorption tint and scattering give water its body. Verify caustics /
+  seafloor legibility through the tinted column at a top-down camera.
+
+## 4. Foam
+
+- Foam threshold + strength, keyed to wave Jacobian / crest steepness. Check it
+  reads at distance (drone/chase cameras), not just close up.
+
+## 5. Sun glint + sky + tone last
+
+- Glint width/intensity from sun azimuth/elevation; then exposure /
+  tonemapping. Judge HDR with the `luminance`, `p95`, and `dynamicRange` GPU
+  probes — a screenshot cannot show clipping. Aim for `dynamicRange` well above
+  1 (real contrast) without `p95` pinned at 1.0 (blown highlights).
+
+## Knobs worth exposing
+
+choppiness, macroAmplitude, normalScale, foamThreshold, foamStrength,
+depthAbsorption, scatterIntensity, sunAzimuth, sunElevation, glintWidth,
+exposure, envMapIntensity. Keep them nested/named per your element — triscope
+imposes no flat schema.
+
+## Convergence loop
+
+When you have a reference photo for a camera, `set_reference` then `auto_tune`
+(SSIM, golden-section) converges a single knob hands-free; for several coupled
+knobs, tune them in the pass order above rather than all at once.
+
+See also: [[threejs-telemetry-sink]], [[glsl-pitfalls]].

package/template/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.vite/
+*.log
+.DS_Store
+/tmp-*/

package/template/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>__PROJECT_NAME__</title>
+    <style>
+      body { font: 14px/1.5 ui-monospace, monospace; background: #0a1218; color: #d2dee5; padding: 24px; max-width: 720px; }
+      a { color: #8fc7d9; }
+      code { background: rgba(255,255,255,0.06); padding: 1px 5px; border-radius: 3px; }
+    </style>
+  </head>
+  <body>
+    <h1>__PROJECT_NAME__</h1>
+    <p>A triscope project. Open a lab page to start iterating:</p>
+    <ul>
+      <li><a href="/labs/cube.html">/labs/cube.html</a> — example rotating cube</li>
+    </ul>
+    <p>From a terminal:</p>
+    <pre><code>npx triscope state .perf.fps
+npx triscope list
+npx triscope smoke cube</code></pre>
+  </body>
+</html>

package/template/labs/cube.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>__PROJECT_NAME__ · cube lab</title>
+    <style>
+      html, body { margin: 0; padding: 0; overflow: hidden; background: #000; color: #cfd6db; font-family: ui-monospace, monospace; }
+      #app { position: fixed; inset: 0; }
+      canvas { display: block; width: 100%; height: 100%; }
+      .triscope-label { position: absolute; background: rgba(0,0,0,.55); color: #cfd6db; padding: 4px 8px; font-size: 11px; font-weight: 600; letter-spacing: .05em; pointer-events: none; border-radius: 3px; z-index: 5; }
+      #hud { position: fixed; bottom: 8px; left: 8px; z-index: 10; font-size: 11px; padding: 4px 8px; background: rgba(0,0,0,.55); border-radius: 3px; }
+      #boot { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; background: #0a1a20; color: #cfd6db; font-size: 14px; z-index: 50; }
+      #lab-controls { position: fixed; right: 8px; bottom: 8px; z-index: 20; width: min(320px, calc(100vw - 24px)); padding: 10px 12px; background: rgba(5,12,16,.78); border: 1px solid rgba(210,230,240,.16); border-radius: 6px; box-sizing: border-box; }
+      .triscope-editor__row { display: grid; grid-template-columns: 110px 1fr 56px; align-items: center; gap: 6px; font-size: 11px; margin: 4px 0; }
+      .triscope-editor__row input { width: 100%; accent-color: #8fc7d9; }
+      .triscope-editor__row output { text-align: right; color: #f0f5f7; }
+    </style>
+  </head>
+  <body>
+    <div id="boot">Initialising Triscope · WebGPU...</div>
+    <div id="app"><canvas id="canvas"></canvas></div>
+    <div id="hud">- fps · WebGPU</div>
+    <div id="lab-controls"></div>
+    <script type="module" src="/src/labs/cube.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "state": "triscope state",
+    "list": "triscope list",
+    "smoke": "node smoke.mjs"
+  },
+  "dependencies": {
+    "@triscope/core": "^__TRISCOPE_VERSION__",
+    "three": "^0.176.0"
+  },
+  "devDependencies": {
+    "@triscope/cli": "^__TRISCOPE_VERSION__",
+    "vite": "^5.4.0",
+    "typescript": "^5.6.0",
+    "ws": "^8.18.0"
+  }
+}

package/template/smoke.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * End-to-end smoke test for your triscope project.
+ *
+ * Boots vite, drives Chromium with WebGPU via CDP, asks the harness to render,
+ * and asserts the loop is alive:
+ *   1. window.__TRISCOPE__ mounts within 30s.
+ *   2. The element declares at least one camera.
+ *   3. Telemetry reports fps > 1 (the RAF loop is stepping).
+ *   4. captureViews() returns a non-empty PNG per camera (the only reliable
+ *      WebGPU readback path — see README), and no camera rendered black.
+ *   5. A knob change propagates into telemetry (best-effort — warns, doesn't
+ *      fail, if your element has no plain `number` knob to flip).
+ *
+ * Exit 0 on pass, non-zero with a structured JSON error on failure.
+ *
+ *   node smoke.mjs           # smoke the default element ("cube")
+ *   node smoke.mjs myElement # smoke /labs/myElement.html
+ *
+ * This file is yours to edit — tighten the assertions for your element
+ * (expected camera count, specific knob → telemetry checks, motion probes).
+ * Honors $CHROME_BIN / $PUPPETEER_EXECUTABLE_PATH (falls back to `chromium`).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ELEMENT = process.argv[2] || 'cube';
+// Random high port so we never collide with a dev server already on 5173.
+const SMOKE_PORT = 5300 + Math.floor(Math.random() * 100);
+const BASE = `http://127.0.0.1:${SMOKE_PORT}/`;
+const TARGET = `${BASE}labs/${ELEMENT}.html`;
+const DEBUG_PORT = 9244;
+const OUT = join(tmpdir(), `triscope-smoke-${ELEMENT}`);
+const CHROME = process.env.CHROME_BIN ?? process.env.PUPPETEER_EXECUTABLE_PATH ?? 'chromium';
+
+const PROJECT = readProjectName();
+const STATE_FILES = [
+  join(tmpdir(), `${PROJECT}-state.json`),
+  join(tmpdir(), `${PROJECT.replace(/[^A-Za-z0-9._-]/g, '-')}-state.json`),
+];
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function readProjectName() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'));
+    return String(pkg.name ?? 'triscope-project');
+  } catch {
+    return 'triscope-project';
+  }
+}
+
+function readState() {
+  for (const p of STATE_FILES) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+      } catch {}
+    }
+  }
+  return null;
+}
+
+function fail(stage, detail) {
+  console.error(JSON.stringify({ ok: false, stage, detail }, null, 2));
+  process.exit(1);
+}
+
+function cdpFactory(ws, consoleLog) {
+  const pending = new Map();
+  let id = 0;
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pending.has(m.id)) {
+      pending.get(m.id)(m);
+      pending.delete(m.id);
+      return;
+    }
+    if (consoleLog && m.method === 'Runtime.exceptionThrown') {
+      consoleLog.push(`[exception] ${m.params?.exceptionDetails?.text ?? ''}`);
+    }
+  };
+  return (method, params = {}) =>
+    new Promise((resolve, reject) => {
+      const n = ++id;
+      ws.send(JSON.stringify({ id: n, method, params }));
+      const t = setTimeout(() => {
+        pending.delete(n);
+        reject(new Error(`cdp timeout: ${method}`));
+      }, 20000);
+      pending.set(n, (m) => {
+        clearTimeout(t);
+        if (m.error) reject(new Error(`${method}: ${m.error.message}`));
+        else resolve(m);
+      });
+    });
+}
+
+async function waitForServer() {
+  const start = Date.now();
+  while (Date.now() - start < 45000) {
+    try {
+      if ((await fetch(BASE)).ok) return;
+    } catch {}
+    await wait(250);
+  }
+  throw new Error(`vite dev server never became reachable on ${BASE}`);
+}
+
+async function main() {
+  mkdirSync(OUT, { recursive: true });
+  for (const p of STATE_FILES) {
+    try {
+      rmSync(p, { force: true });
+    } catch {}
+  }
+
+  // 1. Boot vite on a strict random port (detached so finally{} kills the tree).
+  // --host 127.0.0.1 so the bind matches the IPv4 address we poll/attach on
+  // (Vite 5 otherwise binds localhost/::1 and 127.0.0.1 can refuse).
+  const vite = spawn(
+    'npx',
+    ['--no-install', 'vite', '--port', String(SMOKE_PORT), '--strictPort', '--host', '127.0.0.1'],
+    {
+      cwd: HERE,
+      env: { ...process.env, BROWSER: 'none' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+    },
+  );
+  let viteLog = '';
+  vite.stdout.on('data', (c) => (viteLog += c));
+  vite.stderr.on('data', (c) => (viteLog += c));
+
+  let chrome = null;
+  try {
+    await waitForServer();
+
+    // 2. Boot Chromium with CDP + WebGPU. Headed by default (WebGPU in headless
+    // Chrome is unreliable on Linux); SMOKE_HEADLESS=1 opts into headless.
+    const profileDir = join(tmpdir(), `triscope-smoke-${Date.now()}`);
+    const headlessArgs = process.env.SMOKE_HEADLESS
+      ? ['--headless=new', '--use-angle=vulkan', '--enable-features=Vulkan']
+      : ['--ozone-platform=x11'];
+    chrome = spawn(
+      CHROME,
+      [
+        ...headlessArgs,
+        '--enable-unsafe-webgpu',
+        '--ignore-gpu-blocklist',
+        `--user-data-dir=${profileDir}`,
+        `--remote-debugging-port=${DEBUG_PORT}`,
+        '--window-size=1600,900',
+        TARGET,
+      ],
+      { stdio: 'ignore' },
+    );
+
+    // 3. Attach CDP to the lab tab.
+    let page = null;
+    const start = Date.now();
+    while (Date.now() - start < 45000) {
+      try {
+        const pages = await fetch(`http://127.0.0.1:${DEBUG_PORT}/json`).then((r) => r.json());
+        page = Array.isArray(pages)
+          ? pages.find((p) => p.type === 'page' && p.url?.startsWith(BASE))
+          : null;
+        if (page) break;
+      } catch {}
+      await wait(250);
+    }
+    if (!page) fail('cdp-attach', { error: 'lab tab never appeared within 15s', viteLog });
+
+    const { default: WebSocketCtor } = await import('ws')
+      .then((m) => ({ default: m.WebSocket }))
+      .catch(() => ({ default: globalThis.WebSocket }));
+    const ws = new WebSocketCtor(page.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      ws.onopen = res;
+      ws.onerror = (e) => rej(new Error(`ws open failed: ${e?.message ?? e}`));
+    });
+    const consoleLog = [];
+    const call = cdpFactory(ws, consoleLog);
+    await call('Runtime.enable');
+
+    // 4. Wait for the harness to mount.
+    let mounted = false;
+    for (let i = 0; i < 60; i++) {
+      const p = await call('Runtime.evaluate', {
+        expression: '!!(window.__TRISCOPE__ && window.__TRISCOPE__.captureViews)',
+        returnByValue: true,
+      });
+      if (p.result.result.value) {
+        mounted = true;
+        break;
+      }
+      await wait(500);
+    }
+    if (!mounted) {
+      const boot = await call('Runtime.evaluate', {
+        expression: 'document.getElementById("boot")?.textContent ?? ""',
+        returnByValue: true,
+      });
+      fail('mount', {
+        error: 'window.__TRISCOPE__ never appeared within 30s',
+        bootMsg: boot.result.result.value,
+        viteLog,
+        consoleAll: consoleLog,
+      });
+    }
+
+    // 5. Wait for telemetry with fps > 1.
+    let tel = null;
+    const t0 = Date.now();
+    while (Date.now() - t0 < 15000) {
+      tel = readState();
+      if (tel?.perf?.fps > 1) break;
+      await wait(200);
+    }
+    if (!(tel?.perf?.fps > 1)) {
+      fail('telemetry-warmup', {
+        error: 'no telemetry with fps>1 within 15s',
+        tel,
+        consoleAll: consoleLog,
+      });
+    }
+
+    const camNames = await call('Runtime.evaluate', {
+      expression: 'Object.keys(window.__TRISCOPE__.cameras ?? {})',
+      returnByValue: true,
+    });
+    const cameras = camNames.result.result.value ?? [];
+    if (cameras.length < 1) fail('manifest', { error: 'element declares no cameras', cameras });
+
+    // 6. captureViews — the only reliable WebGPU readback path. Asserts each
+    // camera produced bytes; collects black-frame flags from the harness.
+    const viewsResp = await call('Runtime.evaluate', {
+      expression: 'window.__TRISCOPE__.captureViews()',
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const views = viewsResp.result.result.value ?? {};
+    let captured = 0;
+    let fullSize = 0;
+    for (const cam of Object.keys(views)) {
+      const dataUrl = views[cam];
+      if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) continue;
+      const buf = Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64');
+      writeFileSync(join(OUT, `${cam}.png`), buf);
+      captured += 1;
+      if (buf.readUInt32BE(16) >= 200 && buf.readUInt32BE(20) >= 100) fullSize += 1;
+    }
+    if (captured === 0) fail('capture', { error: 'captureViews returned no PNGs', cameras });
+
+    // Black-frame check via the harness GPU probes (full-size captures only).
+    const probesResp = await call('Runtime.evaluate', {
+      expression: 'JSON.stringify(window.__TRISCOPE__.lastGpuProbes ?? {})',
+      returnByValue: true,
+    });
+    const gpuProbes = JSON.parse(probesResp.result.result.value || '{}');
+    const black = Object.entries(gpuProbes).filter(
+      ([, s]) => s?.blackFrame || s?.luminance < 0.004,
+    );
+    // Render-quality is hard-gated only when HEADED — headless WebGPU readback
+    // is unreliable on Linux (can return black frames). Under headless we still
+    // proved the chain (mount + cameras + captureViews returned bytes).
+    if (!process.env.SMOKE_HEADLESS && fullSize > 0 && black.length > 0) {
+      fail('black-frame', {
+        error: `camera(s) rendered black: ${black.map(([c]) => c).join(', ')}`,
+        gpuProbes,
+      });
+    }
+
+    // 7. Best-effort knob propagation: flip the first plain number knob and
+    // confirm telemetry reflects it. Soft — warns if the element has none.
+    let knobCheck = { skipped: true };
+    const manifest = await fetch(`${BASE}__manifest`)
+      .then((r) => r.json())
+      .catch(() => null);
+    const knobs = manifest?.elements?.[ELEMENT]?.knobs ?? [];
+    const numberKnob = knobs.find((k) => k.type === 'number');
+    if (numberKnob) {
+      const targetVal = +(((numberKnob.min ?? 0) + (numberKnob.max ?? 1)) / 2).toFixed(3);
+      await fetch(`${BASE}__knob`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify([{ element: ELEMENT, key: numberKnob.name, value: targetVal }]),
+      });
+      await wait(1200); // knob poll (100ms) + telemetry tick (500ms) + margin
+      const after = readState();
+      const got = after?.elements?.[ELEMENT]?.[numberKnob.name];
+      knobCheck = { knob: numberKnob.name, set: targetVal, got };
+      if (typeof got === 'number' && Math.abs(got - targetVal) > 0.05) {
+        fail('knob-propagation', {
+          ...knobCheck,
+          error: 'telemetry did not reflect the knob change',
+        });
+      }
+    }
+
+    const warnings = readState()?.warnings ?? [];
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          element: ELEMENT,
+          cameras: cameras.length,
+          captured,
+          fullSize,
+          fps: tel.perf.fps,
+          knobCheck,
+          warnings,
+          outDir: OUT,
+        },
+        null,
+        2,
+      ),
+    );
+  } finally {
+    if (chrome && !chrome.killed) chrome.kill();
+    if (!vite.killed) {
+      try {
+        process.kill(-vite.pid, 'SIGTERM');
+      } catch {}
+      vite.kill('SIGTERM');
+    }
+  }
+}
+
+main().catch((e) => {
+  console.error(
+    JSON.stringify({ ok: false, stage: 'unhandled', error: String(e?.stack ?? e) }, null, 2),
+  );
+  process.exit(1);
+});

package/template/src/elements/cube.ts

@@ -0,0 +1,90 @@
+import type { Element } from '@triscope/core';
+import * as THREE from 'three/webgpu';
+
+/**
+ * Example triscope element: a rotating PBR cube with three exposed knobs.
+ * Replace this with your own element(s).
+ */
+interface CubeUserData {
+  mesh: THREE.Mesh;
+  material: THREE.MeshStandardMaterial;
+  spin: number;
+}
+
+export const cube: Element = {
+  name: 'cube',
+  bounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+
+  mount: ({ parent, ctx }) => {
+    const sun = new THREE.DirectionalLight(0xffffff, 1.4);
+    sun.position.set(2, 3, 1);
+    parent.add(sun);
+    const amb = new THREE.AmbientLight(0xb0c0ce, 0.4);
+    parent.add(amb);
+
+    const geo = new THREE.BoxGeometry(1, 1, 1);
+    const mat = new THREE.MeshStandardMaterial({
+      color: '#d8a85a',
+      roughness: 0.4,
+      metalness: 0.1,
+    });
+    const mesh = new THREE.Mesh(geo, mat);
+    parent.add(mesh);
+
+    const userData: CubeUserData = { mesh, material: mat, spin: 0.8 };
+
+    const tick = () => {
+      mesh.rotation.y += ctx.dt.value * userData.spin;
+      mesh.rotation.x = Math.sin(ctx.time.value * 0.3) * 0.2;
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+
+    return {
+      root: mesh,
+      userData: userData as unknown as Record<string, unknown>,
+      dispose: () => {
+        parent.remove(mesh);
+        parent.remove(sun);
+        parent.remove(amb);
+        geo.dispose();
+        mat.dispose();
+      },
+    };
+  },
+
+  cameras: {
+    front: { position: [0, 0, 3], target: [0, 0, 0] },
+    back: { position: [0, 0, -3], target: [0, 0, 0] },
+    left: { position: [-3, 0, 0], target: [0, 0, 0] },
+    right: { position: [3, 0, 0], target: [0, 0, 0] },
+    top: { position: [0, 3, 0], target: [0, 0, 0] },
+    'three-quarter': { position: [2, 2, 2], target: [0, 0, 0] },
+  },
+
+  knobs: {
+    color: { type: 'color', default: '#d8a85a', label: 'color' },
+    roughness: { type: 'number', min: 0, max: 1, step: 0.01, default: 0.4, label: 'roughness' },
+    metalness: { type: 'number', min: 0, max: 1, step: 0.01, default: 0.1, label: 'metalness' },
+    spin: { type: 'number', min: -3, max: 3, step: 0.05, default: 0.8, label: 'spin (rad/s)' },
+  },
+
+  onKnob: (handle, key, value) => {
+    const u = handle.userData as unknown as CubeUserData;
+    if (key === 'color') u.material.color.set(String(value));
+    else if (key === 'roughness') u.material.roughness = Number(value);
+    else if (key === 'metalness') u.material.metalness = Number(value);
+    else if (key === 'spin') u.spin = Number(value);
+  },
+
+  telemetry: (handle) => {
+    const u = handle.userData as unknown as CubeUserData;
+    return {
+      rotationY: u.mesh.rotation.y,
+      color: '#' + u.material.color.getHexString(),
+      roughness: u.material.roughness,
+      metalness: u.material.metalness,
+      spin: u.spin,
+    };
+  },
+};

package/template/src/labs/cube.ts

@@ -0,0 +1,25 @@
+import { runLab } from '@triscope/core';
+import { cube } from '../elements/cube';
+
+async function boot() {
+  const canvas = document.getElementById('canvas') as HTMLCanvasElement | null;
+  const boot = document.getElementById('boot');
+  const hud = document.getElementById('hud');
+  const labels = document.getElementById('app');
+  const editor = document.getElementById('lab-controls');
+  if (!canvas) return;
+  try {
+    await runLab({
+      element: cube,
+      canvas,
+      hud,
+      labelContainer: labels,
+      editorContainer: editor,
+      bootOverlay: boot,
+    });
+  } catch (err: any) {
+    if (boot) boot.textContent = `Init failed: ${err?.message ?? err}`;
+    console.error(err);
+  }
+}
+boot();

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": false,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.js"]
+}

package/template/vite.config.js

@@ -0,0 +1,33 @@
+import { triscopeTelemetryPlugin } from '@triscope/core/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    // The triscope telemetry sink. Adds dev-server routes the harness talks to:
+    //   POST /__state   → writes /tmp/<project>-state.json (read by `triscope
+    //                     state` / MCP read_telemetry)
+    //   POST /__knob    → queues live knob changes (MCP set_knob)
+    //   GET  /__manifest→ the registered elements/cameras/knobs
+    // Options (all optional):
+    //   project       string — name used for the /tmp state files. Default:
+    //                 package.json#name (sanitized).
+    //   forceReloadOn RegExp|null — files that trigger a full page reload
+    //                 instead of HMR (TSL materials can't hot-swap). Default
+    //                 matches /(\.tsl|Element|Mesh|Material|Shader)\.(ts|tsx|js|mjs)$/i.
+    //                 Pass null to disable; pass your own RegExp to customize.
+    triscopeTelemetryPlugin(),
+  ],
+  server: { port: 5173, open: false },
+  build: {
+    target: 'es2022',
+    sourcemap: true,
+    rollupOptions: {
+      // One entry per lab page. `triscope init --preset` and `triscope new`
+      // add more here; keep `index` and add `<name>: 'labs/<name>.html'`.
+      input: {
+        index: 'index.html',
+        cube: 'labs/cube.html',
+      },
+    },
+  },
+});