@triscope/mcp 0.4.0

package/src/server.ts

@@ -0,0 +1,2678 @@
+// Triscope MCP server.
+//
+// Exposes tools that talk to a running triscope dev server (default
+// http://localhost:5173) and the on-disk telemetry sink it writes:
+//   - list_elements    : GET /__manifest
+//   - read_telemetry   : read /tmp/<project>-state.json, optional jq-style path
+//   - set_knob         : POST /__knob (harness polls and applies live)
+//   - capture_views    : drives a fresh headed Chromium via CDP, calls
+//                        window.__TRISCOPE__.captureViews(), writes per-camera
+//                        PNGs to /tmp/<project>-capture-<element>/<camera>.png
+//   - run_smoke        : spawns `triscope smoke <element>` and returns pass/fail
+//
+// Configuration env vars:
+//   TRISCOPE_URL          (default http://localhost:5173)
+//   TRISCOPE_PROJECT      (default: derived from process.cwd()/package.json#name)
+//   TRISCOPE_DEBUG_PORT   (default 9230)
+//   CHROME_BIN            (default 'chromium')
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { PNG } from 'pngjs';
+import { z } from 'zod';
+import { createBrowserPool } from './browser.js';
+import { createLogger } from './logger.js';
+import { coordinateDescent, knobMatches } from './optimize.js';
+import {
+  composeFilmstrip,
+  diffReference,
+  diffReferenceMotion,
+  motionMagnitudeFromFrames,
+  refsMotionPaths,
+  refsPath,
+  setReference,
+  setReferenceMotion,
+} from './refs.js';
+import { evaluateTargets } from './targets.js';
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function readProjectName(cwd) {
+  if (process.env.TRISCOPE_PROJECT) return process.env.TRISCOPE_PROJECT;
+  try {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p)) return 'triscope-project';
+    const pkg = JSON.parse(readFileSync(p, 'utf8'));
+    return String(pkg.name ?? 'triscope-project').replace(/[^A-Za-z0-9._-]/g, '-');
+  } catch {
+    return 'triscope-project';
+  }
+}
+
+const DEV_URL = (process.env.TRISCOPE_URL ?? 'http://localhost:5173').replace(/\/$/, '');
+const PROJECT = readProjectName(process.cwd());
+const STATE_PATH = join(tmpdir(), `${PROJECT}-state.json`);
+// Inline image payload safety cap. MCP stdio JSON-RPC has practical message
+// size limits and ours exceeded them at 12 cameras × 1280×720 PNG base64 →
+// the server process got OOM-killed mid-response. Override with
+// TRISCOPE_INLINE_PAYLOAD_BUDGET (bytes) if you really need bigger.
+const INLINE_PAYLOAD_BUDGET = Number(process.env.TRISCOPE_INLINE_PAYLOAD_BUDGET ?? 1024 * 1024);
+
+// ---- Resilience: ring buffer of recent errors + process-level handlers --
+// A single rogue async exception used to crash the entire MCP server (the
+// process died, Claude Code didn't auto-restart it, and subsequent calls
+// timed out with cryptic "Connection closed"). Now we log and continue so
+// individual tool failures stay isolated from the server lifecycle.
+const SERVER_START_TIME = Date.now();
+const RECENT_ERRORS_CAP = 16;
+const recentErrors: string[] = [];
+const logger = createLogger(PROJECT);
+const browserPool = createBrowserPool({ logger });
+const shutdown = () => browserPool.dispose();
+process.on('exit', shutdown);
+process.on('SIGINT', () => {
+  shutdown();
+  process.exit(130);
+});
+process.on('SIGTERM', () => {
+  shutdown();
+  process.exit(143);
+});
+export function recordError(source: string, err: unknown) {
+  const detail = (err as any)?.stack ?? (err as any)?.message ?? String(err);
+  const msg = `[${new Date().toISOString()}] ${source}: ${detail}`;
+  logger.error(source, String((err as any)?.message ?? err), { stack: (err as any)?.stack });
+  recentErrors.push(msg);
+  if (recentErrors.length > RECENT_ERRORS_CAP) recentErrors.shift();
+}
+process.on('uncaughtException', (err) => recordError('uncaughtException', err));
+process.on('unhandledRejection', (err) => recordError('unhandledRejection', err));
+
+export function applyPath(data, path) {
+  if (!path) return data;
+  const segs = path.replace(/^\./, '').split('.').filter(Boolean);
+  let cur = data;
+  for (const s of segs) {
+    if (cur == null) return undefined;
+    cur = cur[s];
+  }
+  return cur;
+}
+
+async function fetchManifest(devUrl: string = DEV_URL): Promise<any> {
+  try {
+    const r = await fetch(`${devUrl}/__manifest`);
+    if (!r.ok) return null;
+    const m = await r.json();
+    // Shape: { elements: { [name]: { element, labUrl, cameras, knobs } } }
+    return m && typeof m === 'object' ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+// Short-TTL manifest cache so a batch of set_knob calls (e.g. auto_tune's
+// inner loop) doesn't fire one GET /__manifest per knob just to look up specs.
+// Keyed by devUrl so cross-project calls don't read each other's manifest.
+const _manifestCache = new Map<string, { value: any; at: number }>();
+async function fetchManifestCached(devUrl: string = DEV_URL, ttlMs = 1000): Promise<any> {
+  const now = Date.now();
+  const hit = _manifestCache.get(devUrl);
+  if (hit && now - hit.at < ttlMs) return hit.value;
+  const value = await fetchManifest(devUrl);
+  _manifestCache.set(devUrl, { value, at: now });
+  return value;
+}
+
+/**
+ * Resolve the dev-server origin for a per-call request. Precedence: explicit
+ * `devUrl` → the origin of `labUrl` → the boot DEV_URL. Lets the
+ * dev-server-bound tools (read_telemetry/set_knob/list_elements/get_scene/
+ * auto_tune/multi_tune) target a lab/project other than the one the MCP booted
+ * against, mirroring the per-call `labUrl` the browser tools already accept.
+ */
+export function resolveDevUrl({ devUrl, labUrl }: { devUrl?: string; labUrl?: string }): string {
+  if (devUrl) return devUrl.replace(/\/$/, '');
+  if (labUrl) {
+    try {
+      return new URL(labUrl).origin;
+    } catch {
+      /* not an absolute URL — fall through to default */
+    }
+  }
+  return DEV_URL;
+}
+
+/**
+ * Fetch the LAST telemetry the harness posted, live over HTTP from the dev
+ * server (GET /__state), regardless of which /tmp file it was written to. The
+ * harness stamps `postedAt` so the caller can tell how stale the snapshot is
+ * (the lab tab may be backgrounded/closed). Returns null on any failure.
+ */
+async function fetchState(devUrl: string): Promise<{ data: any; staleMs: number | null } | null> {
+  try {
+    const r = await fetch(`${devUrl}/__state`, { signal: AbortSignal.timeout(2000) });
+    if (!r.ok) return null;
+    const data = (await r.json()) as any;
+    // GET /__state returns the literal `{}` (HTTP 200) when no lab tab has posted
+    // yet (telemetry.ts). Treat an empty object as "no telemetry" → null, so the
+    // caller falls through to the disk read / the actionable "open a lab page"
+    // error instead of silently returning undefined for every path.
+    if (!data || typeof data !== 'object' || Object.keys(data).length === 0) return null;
+    const staleMs = typeof data.postedAt === 'number' ? Date.now() - data.postedAt : null;
+    return { data, staleMs };
+  } catch {
+    return null;
+  }
+}
+
+const STALE_MS = Number(process.env.TRISCOPE_STALE_MS ?? 1500);
+
+/**
+ * Server-local mirror of @triscope/core's `clampKnob` (kept here to preserve
+ * the node-only MCP / browser-only core boundary — the same reason
+ * probeStatsFromPng mirrors the harness's sampleGpuProbes rather than importing
+ * it). The harness clamp is authoritative; clamping here too means out-of-range
+ * values are corrected *before* they persist in /__knob and the agent gets
+ * immediate `{requested, final}` feedback instead of having to read telemetry.
+ */
+export function clampKnobValue(
+  spec: any,
+  value: number | string | boolean,
+): { clamped: boolean; final: number | string | boolean } {
+  if (!spec || typeof spec !== 'object') return { clamped: false, final: value };
+  switch (spec.type) {
+    case 'number': {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return { clamped: true, final: spec.default };
+      let next = n;
+      if (typeof spec.step === 'number' && spec.step > 0) {
+        next = spec.min + Math.round((next - spec.min) / spec.step) * spec.step;
+      }
+      next = Math.min(spec.max, Math.max(spec.min, next));
+      return { clamped: Math.abs(next - n) >= 1e-9, final: next };
+    }
+    case 'int': {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return { clamped: true, final: spec.default };
+      const next = Math.min(spec.max, Math.max(spec.min, Math.round(n)));
+      return { clamped: next !== n, final: next };
+    }
+    case 'color':
+      return /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(String(value))
+        ? { clamped: false, final: value }
+        : { clamped: true, final: spec.default };
+    case 'boolean':
+      return { clamped: typeof value !== 'boolean', final: Boolean(value) };
+    default:
+      return { clamped: false, final: value }; // trigger / unknown → passthrough
+  }
+}
+
+/** Build {element: {knobKey: spec}} from the live manifest's knob arrays. */
+export function knobSpecMapFromManifest(manifest: any): Record<string, Record<string, any>> {
+  const out: Record<string, Record<string, any>> = {};
+  for (const [el, entry] of Object.entries((manifest?.elements ?? {}) as Record<string, any>)) {
+    const byKey: Record<string, any> = {};
+    for (const k of entry?.knobs ?? []) {
+      if (!k?.name) continue;
+      // Index by the advertised name (the display key `element.knob` in a
+      // namespaced scene) AND by the element-local key, so set_knob's clamp
+      // feedback resolves whether the caller passes `cube.spin` or `spin`.
+      byKey[k.name] = k;
+      const local = el && k.name.startsWith(`${el}.`) ? k.name.slice(el.length + 1) : k.name;
+      if (!(local in byKey)) byKey[local] = k;
+    }
+    out[el] = byKey;
+  }
+  return out;
+}
+
+export function readProjectLabMap(cwd) {
+  try {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p)) return {};
+    const pkg = JSON.parse(readFileSync(p, 'utf8'));
+    const m = pkg?.triscope?.labs;
+    return m && typeof m === 'object' ? m : {};
+  } catch {
+    return {};
+  }
+}
+
+const PROJECT_LABS = readProjectLabMap(process.cwd());
+
+export function absolutize(maybePath, base: string = DEV_URL) {
+  if (!maybePath) return null;
+  if (/^https?:\/\//.test(maybePath)) return maybePath;
+  return `${base}${maybePath.startsWith('/') ? '' : '/'}${maybePath}`;
+}
+
+async function resolveLabUrl({
+  element,
+  labUrl,
+  devUrl,
+}: {
+  element?: string;
+  labUrl?: string;
+  devUrl?: string;
+}): Promise<string> {
+  // 1. Explicit arg wins.
+  if (labUrl) return absolutize(labUrl);
+  const base = resolveDevUrl({ devUrl });
+  if (!element) return base;
+  // 2. Live manifest from a running lab (on the target dev server).
+  const manifest = await fetchManifest(base);
+  const entry = manifest?.elements?.[element];
+  if (entry?.labUrl) return absolutize(entry.labUrl, base);
+  // 3. Per-project escape hatch in package.json#triscope.labs.
+  if (PROJECT_LABS[element]) return absolutize(PROJECT_LABS[element], base);
+  // 4. Convention fallback.
+  return `${base}/labs/${element}.html`;
+}
+
+async function listElements({ devUrl, labUrl }: { devUrl?: string; labUrl?: string } = {}) {
+  const m = await fetchManifest(resolveDevUrl({ devUrl, labUrl }));
+  if (!m || !m.elements || Object.keys(m.elements).length === 0) {
+    return {
+      manifest: null,
+      note: 'Dev server is up but no manifest has been posted yet. Load a lab page first.',
+    };
+  }
+  return { manifest: m };
+}
+
+async function readTelemetry(
+  path?: string,
+  { devUrl, labUrl }: { devUrl?: string; labUrl?: string } = {},
+) {
+  const url = resolveDevUrl({ devUrl, labUrl });
+  // Live-first: GET ${url}/__state fetches the dev server's OWN state file over
+  // HTTP — works for any project/port without the MCP knowing the /tmp path
+  // (the original "No telemetry at /tmp/...-state.json" cross-project failure).
+  // Fall back to the local file only for the default dev server (a non-default
+  // project's state-file path is unknown to this process).
+  let data: any = null;
+  let source: 'live' | 'disk' | null = null;
+  let staleMs: number | null = null;
+  const live = await fetchState(url);
+  if (live) {
+    data = live.data;
+    source = 'live';
+    staleMs = live.staleMs;
+  } else if (url === DEV_URL && existsSync(STATE_PATH)) {
+    data = safeReadState();
+    source = 'disk';
+    staleMs = typeof data?.postedAt === 'number' ? Date.now() - data.postedAt : null;
+  }
+  if (data == null) {
+    throw new Error(
+      `No telemetry from ${url}/__state (and no local file). Is the dev server running with a lab page open?`,
+    );
+  }
+  const sliced = applyPath(data, path);
+  // Back-compat: a `path` query returns the BARE sliced value (what every
+  // existing consumer + the E2E expect). For the FULL snapshot (no path) we
+  // annotate freshness via non-colliding `__source`/`__staleMs` keys so a stale
+  // tab (backgrounded/closed) is detectable without changing the value shape.
+  if (path == null && sliced && typeof sliced === 'object' && !Array.isArray(sliced)) {
+    return {
+      ...sliced,
+      __source: source,
+      ...(staleMs != null ? { __staleMs: staleMs } : {}),
+      ...(staleMs != null && staleMs > STALE_MS
+        ? { __warning: `telemetry is ${staleMs}ms old — the lab tab may be backgrounded or closed` }
+        : {}),
+    };
+  }
+  return sliced;
+}
+
+async function setKnob(payload) {
+  // `payload` is either a single {element,key,value} or {updates:[...]}.
+  // The /__knob endpoint accepts arrays natively (telemetry.ts line 94).
+  const batched = Array.isArray(payload?.updates);
+  const updates: Array<{ element: string; key: string; value: unknown }> = batched
+    ? payload.updates
+    : [payload];
+  const url = resolveDevUrl({ devUrl: payload?.devUrl, labUrl: payload?.labUrl });
+
+  // Best-effort clamp against the live manifest's knob specs so out-of-range
+  // values are corrected before they persist + the agent learns what applied.
+  const specs = knobSpecMapFromManifest(await fetchManifestCached(url));
+  const clampedReports: Array<{
+    element: string;
+    key: string;
+    requested: unknown;
+    final: unknown;
+  }> = [];
+  const outgoing = updates.map((u) => {
+    const spec = specs[u.element]?.[u.key];
+    if (!spec) return u;
+    const c = clampKnobValue(spec, u.value as number | string | boolean);
+    if (c.clamped) {
+      clampedReports.push({ element: u.element, key: u.key, requested: u.value, final: c.final });
+    }
+    return { ...u, value: c.final };
+  });
+
+  const body = JSON.stringify(batched ? outgoing : outgoing[0]);
+  const r = await fetch(`${url}/__knob`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  });
+  if (!r.ok) throw new Error(`__knob returned ${r.status}`);
+  return {
+    ok: true,
+    count: outgoing.length,
+    ...(clampedReports.length ? { clamped: clampedReports } : {}),
+  };
+}
+
+/**
+ * Trim + annotate the telemetry snapshot embedded in a capture response:
+ *  - flag that `perf.fps` is sampled right after the navigate, so it can read
+ *    low while WebGPU warms (use read_telemetry for steady-state) — otherwise
+ *    the capture's fps looks catastrophic vs reality;
+ *  - drop the per-probe `samples` arrays (the payload bulk — a busy scene's full
+ *    motion history burns context for nothing; keep the stats + a count).
+ * Never throws — a capture must not fail over telemetry cosmetics.
+ */
+function trimCaptureTelemetry(sample: any): any {
+  if (!sample || typeof sample !== 'object') return sample;
+  try {
+    if (sample.perf && typeof sample.perf === 'object') {
+      sample.perf = {
+        ...sample.perf,
+        note: 'capture-time fps — reads low right after a navigate while WebGPU warms; use read_telemetry for steady-state',
+      };
+    }
+    for (const el of Object.values(sample.elements ?? {}) as any[]) {
+      for (const probe of Object.values(el?.motion ?? {}) as any[]) {
+        if (probe && Array.isArray(probe.samples)) {
+          probe.sampleCount = probe.samples.length;
+          delete probe.samples;
+        }
+      }
+    }
+  } catch {
+    /* leave the snapshot as-is */
+  }
+  return sample;
+}
+
+async function captureViews({
+  element,
+  labUrl,
+  inline = true,
+  fresh = false,
+}: {
+  element?: string;
+  labUrl?: string;
+  inline?: boolean;
+  fresh?: boolean;
+}) {
+  // Persistent Chromium: first call cold-starts (~3s), subsequent calls
+  // reuse the same browser/page and just navigate if the URL changed.
+  const target = await resolveLabUrl({ element, labUrl });
+  const outDir = join(tmpdir(), `${PROJECT}-capture-${element ?? 'scene'}`);
+  mkdirSync(outDir, { recursive: true });
+
+  const t0 = Date.now();
+  const timings: Record<string, number> = {};
+  const tNavStart = Date.now();
+  const { call } = await browserPool.getPage(target, { reload: fresh });
+  timings.navigate = Date.now() - tNavStart;
+  const tRenderStart = Date.now();
+  const result = await call('Runtime.evaluate', {
+    expression: 'window.__TRISCOPE__.captureViews()',
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  timings.render = Date.now() - tRenderStart;
+  const views = result.result.result.value;
+  if (!views || typeof views !== 'object') {
+    // By the time we get here browserPool.getPage has already proven the
+    // harness mounted, so an empty result means the Element declared zero
+    // cameras OR captureViews itself errored without returning.
+    throw new Error(
+      `captureViews returned no images for element="${element ?? '(scene)'}" at ${target}. ` +
+        `Most likely the Element declares no cameras — check the manifest: ` +
+        `mcp__triscope__list_elements.`,
+    );
+  }
+  const written = {};
+  const base64ByCam = {};
+  const tWriteStart = Date.now();
+  for (const [cam, dataUrl] of Object.entries(views)) {
+    if (typeof dataUrl !== 'string') continue;
+    const b64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+    const path = join(outDir, `${cam}.png`);
+    writeFileSync(path, Buffer.from(b64, 'base64'));
+    written[cam] = path;
+    base64ByCam[cam] = b64;
+  }
+  timings.writePngs = Date.now() - tWriteStart;
+  const tTelStart = Date.now();
+  const telemetry = await call('Runtime.evaluate', {
+    expression: 'JSON.stringify(window.__TRISCOPE__.sampleTelemetry())',
+    returnByValue: true,
+  });
+  const sample = trimCaptureTelemetry(JSON.parse(telemetry.result.result.value));
+  timings.telemetry = Date.now() - tTelStart;
+
+  // captureViews() populates window.__TRISCOPE__.lastGpuProbes as a side
+  // effect (per-camera luminance/p5/p95/dynamicRange). Surface it in the
+  // tool response so consumers don't have to do a second CDP eval.
+  // If the harness didn't populate it (lab page that doesn't use
+  // @triscope/core runLab — e.g. water3d's scene lab which has a custom
+  // capture path), we decode the captured PNGs server-side with pngjs
+  // and compute the same scalars. Slower (~5 ms per camera) but means
+  // GPU probes are available for any captured PNG.
+  const tProbeStart = Date.now();
+  let gpuProbes: Record<string, any> | null = null;
+  let gpuProbesSource: 'harness' | 'server-fallback' | 'unavailable' = 'unavailable';
+  try {
+    const probesResp = await call('Runtime.evaluate', {
+      expression: 'JSON.stringify(window.__TRISCOPE__.lastGpuProbes ?? null)',
+      returnByValue: true,
+    });
+    const fromHarness = JSON.parse(probesResp.result.result.value);
+    if (fromHarness && Object.keys(fromHarness).length > 0) {
+      gpuProbes = fromHarness;
+      gpuProbesSource = 'harness';
+    }
+  } catch {
+    /* old core — fall through to server-side */
+  }
+  if (!gpuProbes) {
+    gpuProbes = {};
+    for (const [cam, b64] of Object.entries(base64ByCam) as [string, string][]) {
+      try {
+        gpuProbes[cam] = probeStatsFromPng(Buffer.from(b64, 'base64'));
+      } catch {
+        /* skip cameras whose PNGs fail to decode */
+      }
+    }
+    if (Object.keys(gpuProbes).length === 0) gpuProbes = null;
+    else gpuProbesSource = 'server-fallback';
+  }
+  timings.probes = Date.now() - tProbeStart;
+
+  // Cameras the GPU drew black (luminance < threshold) — set by the harness
+  // probe or the server-side fallback. Surfaced top-level so the agent sees a
+  // dead pane immediately instead of inspecting per-camera gpuProbes.
+  const blackFrames = gpuProbes
+    ? Object.entries(gpuProbes)
+        .filter(([, s]) => (s as any)?.blackFrame)
+        .map(([cam]) => cam)
+    : [];
+  // Cameras that rendered a (near-)UNIFORM frame — dynamicRange ≈ 1 means p95≈p5,
+  // i.e. nothing but the flat clear-color is in view (the element drifted out of
+  // frame / wasn't drawn). blackFrames misses this when the clear-color sits
+  // above the black threshold (the "empty but not black" case), so it reads as a
+  // false OK. Excludes genuinely black panes (already in blackFrames).
+  const flatFrames = gpuProbes
+    ? Object.entries(gpuProbes)
+        .filter(([, s]) => {
+          const p = s as any;
+          return p && !p.blackFrame && typeof p.dynamicRange === 'number' && p.dynamicRange <= 1.05;
+        })
+        .map(([cam]) => cam)
+    : [];
+
+  return {
+    element: element ?? null,
+    dir: outDir,
+    files: written,
+    cameraOrder: Object.keys(written),
+    telemetry: sample,
+    gpuProbes,
+    gpuProbesSource,
+    blackFrames,
+    flatFrames,
+    inline,
+    captureMs: Date.now() - t0,
+    timings,
+    _base64ByCam: base64ByCam,
+  };
+}
+
+/** Server-side fallback: same math the harness does, but starting from a
+ *  decoded PNG buffer instead of a 2D canvas. Stride-samples to ~2300 px
+ *  so the cost is bounded (~5 ms per 1280×720 PNG). */
+// Mean Rec.709 luminance below which a pane counts as a black render. Matches
+// @triscope/core's BLACK_FRAME_LUMINANCE (mirrored across the node boundary).
+const BLACK_FRAME_LUMINANCE = 0.004;
+
+export function probeStatsFromPng(pngBuf: Buffer): {
+  luminance: number;
+  p5: number;
+  p95: number;
+  dynamicRange: number;
+  samples: number;
+  blackFrame?: boolean;
+} {
+  const img = PNG.sync.read(pngBuf);
+  const stride = Math.max(1, Math.floor(Math.sqrt((img.width * img.height) / 2304)));
+  const lums: number[] = [];
+  let sum = 0;
+  for (let y = 0; y < img.height; y += stride) {
+    for (let x = 0; x < img.width; x += stride) {
+      const i = (y * img.width + x) * 4;
+      const r = img.data[i] / 255;
+      const g = img.data[i + 1] / 255;
+      const b = img.data[i + 2] / 255;
+      const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+      lums.push(lum);
+      sum += lum;
+    }
+  }
+  lums.sort((a, b) => a - b);
+  const n = lums.length;
+  const p5 = lums[Math.floor(n * 0.05)];
+  const p95 = lums[Math.floor(n * 0.95)];
+  const luminance = +(sum / n).toFixed(4);
+  return {
+    luminance,
+    p5: +p5.toFixed(4),
+    p95: +p95.toFixed(4),
+    dynamicRange: +(p95 / Math.max(p5, 1 / 255)).toFixed(2),
+    samples: n,
+    ...(luminance < BLACK_FRAME_LUMINANCE ? { blackFrame: true } : {}),
+  };
+}
+
+async function captureMotionFramesRaw({
+  element,
+  camera,
+  frames,
+  dt,
+  mode,
+  labUrl,
+}: any): Promise<string[]> {
+  // Like captureMotion but for ONE camera, returns the raw base64 PNG frames.
+  // Used internally by set_reference_motion + diff_reference_motion.
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target);
+  const result = await call('Runtime.evaluate', {
+    expression: `window.__TRISCOPE__.captureMotionFrames(${JSON.stringify(camera)}, ${JSON.stringify({ frames, dt, mode })})`,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  const frames_ = result.result.result.value;
+  if (!Array.isArray(frames_) || frames_.length === 0) {
+    throw new Error(`captureMotionFrames returned empty for camera "${camera}"`);
+  }
+  return frames_.map((du) => du.replace(/^data:image\/png;base64,/, ''));
+}
+
+async function captureMotion({
+  element,
+  camera,
+  frames = 6,
+  dt = 0.25,
+  mode = 'time',
+  labUrl,
+  fresh = false,
+}: any) {
+  // Multi-frame capture per camera through the persistent browser pool.
+  // Returns per-camera filmstrip base64 + motionMagnitude scalar + telemetry.
+  const target = await resolveLabUrl({ element, labUrl });
+  const outDir = join(tmpdir(), `${PROJECT}-motion-${element ?? 'scene'}`);
+  mkdirSync(outDir, { recursive: true });
+  const t0 = Date.now();
+  const { call } = await browserPool.getPage(target, { reload: fresh });
+
+  // Pick the camera set: explicit single name or all cameras for the element.
+  let cameraOrder: string[];
+  if (camera) {
+    cameraOrder = [camera];
+  } else {
+    const camsProbe = await call('Runtime.evaluate', {
+      expression: 'Object.keys(window.__TRISCOPE__.cameras)',
+      returnByValue: true,
+    });
+    cameraOrder = camsProbe.result.result.value ?? [];
+  }
+  if (!Array.isArray(cameraOrder) || cameraOrder.length === 0) {
+    throw new Error('no cameras available — is the harness mounted?');
+  }
+
+  const filmstripPaths = {};
+  const filmstripBase64 = {};
+  const magnitudeByCam = {};
+  for (const camName of cameraOrder) {
+    const result = await call('Runtime.evaluate', {
+      expression: `window.__TRISCOPE__.captureMotionFrames(${JSON.stringify(camName)}, ${JSON.stringify({ frames, dt, mode })})`,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const dataUrls = result.result.result.value;
+    if (!Array.isArray(dataUrls) || dataUrls.length === 0) {
+      throw new Error(`captureMotionFrames returned empty for camera "${camName}"`);
+    }
+    const strip = composeFilmstrip(dataUrls);
+    const stripPath = join(outDir, `${camName}.filmstrip.png`);
+    writeFileSync(stripPath, strip);
+    filmstripPaths[camName] = stripPath;
+    filmstripBase64[camName] = strip.toString('base64');
+    magnitudeByCam[camName] = motionMagnitudeFromFrames(dataUrls);
+  }
+
+  const telemetry = await call('Runtime.evaluate', {
+    expression: 'JSON.stringify(window.__TRISCOPE__.sampleTelemetry())',
+    returnByValue: true,
+  });
+  const sample = trimCaptureTelemetry(JSON.parse(telemetry.result.result.value));
+
+  return {
+    element: element ?? null,
+    frames,
+    dt,
+    mode,
+    dir: outDir,
+    filmstrips: filmstripPaths,
+    cameraOrder,
+    motionMagnitude: magnitudeByCam,
+    captureMs: Date.now() - t0,
+    telemetry: sample,
+    _filmstripBase64: filmstripBase64,
+  };
+}
+
+/**
+ * auto_tune (1D): golden-section search over one knob, minimising
+ * (1 - SSIM) between the captured target_camera view and the stored
+ * reference for that (element, camera). Each iteration: set_knob → wait
+ * for the harness to apply (knobPollMs + telemetry tick + margin) →
+ * captureViews → diff_reference. Returns the best knob value found,
+ * the final SSIM, the iteration history, and total ms.
+ *
+ * Why golden-section: derivative-free, deterministic, converges
+ * exponentially (range × 1/φ per iter ≈ 0.618). 12 iterations narrow a
+ * range to ~0.7% — plenty for shader tuning. Robust to noise because we
+ * use SSIM (perceptual) rather than meanAbsDiff (pixel-level).
+ */
+/**
+ * Snapshot / restore via git tags.
+ *
+ * A snapshot freezes a moment in the iteration loop: the git commit you
+ * were on + the knob values applied at that moment. Restoring checks out
+ * that commit and re-posts the knobs, so a careful tuning state can be
+ * recovered after a risky shader rewrite. Tags live under
+ * `triscope/snapshot/<name>` so they don't pollute the user's namespace.
+ *
+ * Guard rails:
+ *   - snapshot refuses on a dirty working tree — the commit you'd point
+ *     at wouldn't actually contain your in-progress edits, so the
+ *     restore would silently revert them.
+ *   - restore refuses on a dirty WT too, for the same reason in reverse.
+ *   - PNG refs are intentionally not bundled into the snapshot for the
+ *     MVP — they live next to the project as before (refs/<el>/<cam>.png)
+ *     and are recovered with the git checkout. Keeping the JSON small.
+ */
+const SNAPSHOT_TAG_PREFIX = 'triscope/snapshot/';
+
+// Windows portability: npm/git/code are .cmd scripts on Win32. child_process
+// .spawn refuses to invoke them without `shell: true`. On Linux/macOS the
+// real binaries are on PATH and shell isn't needed. We set the flag
+// conditionally everywhere we spawn one of those tools.
+const NEED_SHELL = process.platform === 'win32';
+
+// For tools that forward an agent-supplied argument to the `triscope` CLI we
+// spawn the binary WITHOUT a shell (explicit .cmd on Windows) so there's no
+// shell to inject into, and we reject any argument that would smuggle a flag.
+const TRISCOPE_BIN = process.platform === 'win32' ? 'triscope.cmd' : 'triscope';
+function rejectFlagArg(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0 || value.startsWith('-')) {
+    throw new Error(
+      `unsafe ${label}: ${JSON.stringify(value)} (must be a non-empty value not starting with '-')`,
+    );
+  }
+}
+
+function git(
+  args: string[],
+  cwd: string = process.cwd(),
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], shell: NEED_SHELL });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', reject);
+    child.on('exit', (code) =>
+      resolve({ code: code ?? 1, stdout: stdout.trim(), stderr: stderr.trim() }),
+    );
+  });
+}
+
+async function assertCleanWt(cwd: string, action: string): Promise<void> {
+  const status = await git(['status', '--porcelain'], cwd);
+  if (status.stdout.length > 0) {
+    throw new Error(
+      `${action} refuses to run with a dirty working tree. Commit, stash, or revert your in-progress edits first.\nDirty paths:\n${status.stdout.split('\n').slice(0, 10).join('\n')}`,
+    );
+  }
+}
+
+/**
+ * Wait until the harness telemetry confirms a knob took the requested value,
+ * polling the on-disk state every 50 ms. Replaces fixed sleeps in the tuning
+ * loops: a knob usually lands in ~100-600 ms (knob poll + telemetry tick), so
+ * this returns as soon as it's applied instead of always sleeping the worst
+ * case. Returns false on timeout (caller does a short settle fallback).
+ */
+async function waitForKnobApplied(
+  key: string,
+  value: number | string | boolean,
+  timeoutMs = 2500,
+  element?: string,
+  devUrl?: string,
+): Promise<boolean> {
+  // Telemetry exposes knobs by DISPLAY key. In a namespaced scene the caller may
+  // pass the element-local key (`spin`) while telemetry holds `cube.spin`, so
+  // also probe the namespaced form — otherwise this never confirms and the
+  // tuning loop burns the full timeout every iteration.
+  const ns = element ? `${element}.${key}` : null;
+  // For the default dev server poll the local file (fast); for a non-default
+  // devUrl the file path is unknown here, so poll its /__state over HTTP — else
+  // cross-project tuning never confirms and burns the full timeout each round.
+  const url = resolveDevUrl({ devUrl });
+  const useHttp = url !== DEV_URL;
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      let st: any = null;
+      if (useHttp) {
+        st = (await fetchState(url))?.data ?? null;
+      } else if (existsSync(STATE_PATH)) {
+        st = JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+      }
+      const applied = st?.knobs?.[key] ?? (ns ? st?.knobs?.[ns] : undefined);
+      if (applied !== undefined && knobMatches(value, applied)) return true;
+    } catch {
+      /* state file mid-write / transient fetch — retry */
+    }
+    await wait(50);
+  }
+  return false;
+}
+
+async function fetchPersistedKnobs(): Promise<Record<string, Record<string, unknown>>> {
+  try {
+    const r = await fetch(`${DEV_URL}/__knob/current`);
+    if (!r.ok) return {};
+    return (await r.json()) as Record<string, Record<string, unknown>>;
+  } catch {
+    return {};
+  }
+}
+
+async function snapshot({ name, message }: { name: string; message?: string }) {
+  if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+    throw new Error(`snapshot name must be [A-Za-z0-9._-]+ (got "${name}")`);
+  }
+  const cwd = process.cwd();
+  await assertCleanWt(cwd, 'snapshot');
+  const head = await git(['rev-parse', 'HEAD'], cwd);
+  if (head.code !== 0) throw new Error(`git rev-parse failed: ${head.stderr}`);
+  const knobs = await fetchPersistedKnobs();
+  const payload = {
+    name,
+    createdAt: new Date().toISOString(),
+    commit: head.stdout,
+    message: message ?? '',
+    knobs, // { [element]: { [knobKey]: value, ... } }
+  };
+  const tagName = `${SNAPSHOT_TAG_PREFIX}${name}`;
+  // Annotated tag stores the JSON payload as the tag message — no extra
+  // working-tree files, no rebase noise, easy to list+read with `git tag`.
+  const tagBody = `triscope snapshot v1\n\n${JSON.stringify(payload, null, 2)}`;
+  const tag = await git(['tag', '-a', tagName, '-m', tagBody, payload.commit], cwd);
+  if (tag.code !== 0) {
+    if (tag.stderr.includes('already exists')) {
+      throw new Error(
+        `snapshot "${name}" already exists. Pick a different name or delete the existing tag: git tag -d ${tagName}`,
+      );
+    }
+    throw new Error(`git tag failed: ${tag.stderr}`);
+  }
+  return {
+    ok: true,
+    tag: tagName,
+    ...payload,
+    hint: 'Restore later with mcp__triscope__restore name=' + name,
+  };
+}
+
+async function listSnapshots() {
+  const cwd = process.cwd();
+  const list = await git(
+    [
+      'tag',
+      '--list',
+      `${SNAPSHOT_TAG_PREFIX}*`,
+      '--format=%(refname:short)|%(creatordate:iso)|%(subject)',
+    ],
+    cwd,
+  );
+  if (list.code !== 0) throw new Error(`git tag --list failed: ${list.stderr}`);
+  const snapshots: Array<{ name: string; tag: string; created: string; subject: string }> = [];
+  for (const line of list.stdout.split('\n').filter(Boolean)) {
+    const [tag, created, ...subj] = line.split('|');
+    snapshots.push({
+      name: tag.replace(SNAPSHOT_TAG_PREFIX, ''),
+      tag,
+      created,
+      subject: subj.join('|'),
+    });
+  }
+  return { count: snapshots.length, snapshots };
+}
+
+async function restore({ name }: { name: string }) {
+  if (!/^[A-Za-z0-9._-]+$/.test(name)) throw new Error(`invalid snapshot name`);
+  const cwd = process.cwd();
+  await assertCleanWt(cwd, 'restore');
+  const tagName = `${SNAPSHOT_TAG_PREFIX}${name}`;
+  const show = await git(['cat-file', '-p', tagName], cwd);
+  if (show.code !== 0) throw new Error(`snapshot "${name}" not found (tag ${tagName})`);
+  // Annotated tag object body: header lines, blank line, then the message
+  // we wrote in snapshot(). Find the JSON block.
+  const bodyMatch = show.stdout.match(/\n\n([\s\S]*)/);
+  const body = bodyMatch?.[1] ?? '';
+  const jsonStart = body.indexOf('{');
+  if (jsonStart < 0) throw new Error(`snapshot ${name} has no JSON payload`);
+  let payload: any;
+  try {
+    payload = JSON.parse(body.slice(jsonStart));
+  } catch {
+    throw new Error(`snapshot ${name} payload is not valid JSON`);
+  }
+  // Checkout the commit the snapshot pointed at (detached HEAD — safe,
+  // user can create a branch from there if they want to keep working).
+  const checkout = await git(['checkout', payload.commit], cwd);
+  if (checkout.code !== 0)
+    throw new Error(`git checkout ${payload.commit} failed: ${checkout.stderr}`);
+  // Re-post knobs. The harness will pick them up via its 100ms poll once
+  // it next mounts (or immediately if already mounted on the same commit).
+  const updates: Array<{ element: string; key: string; value: unknown }> = [];
+  for (const [elName, kv] of Object.entries(payload.knobs ?? {})) {
+    for (const [k, v] of Object.entries(kv as Record<string, unknown>)) {
+      updates.push({ element: elName, key: k, value: v });
+    }
+  }
+  if (updates.length > 0) {
+    try {
+      await setKnob({ updates });
+    } catch {
+      /* dev server may be down — knobs will re-hydrate on next runLab */
+    }
+  }
+  return {
+    ok: true,
+    tag: tagName,
+    restoredCommit: payload.commit,
+    knobUpdates: updates.length,
+    payload,
+  };
+}
+
+async function autoTune({
+  element,
+  knob,
+  range,
+  target_camera,
+  max_iterations = 12,
+  labUrl,
+}: {
+  element: string;
+  knob: string;
+  range: [number, number];
+  target_camera: string;
+  max_iterations?: number;
+  labUrl?: string;
+}) {
+  const refPath = refsPath(process.cwd(), element, target_camera);
+  if (!existsSync(refPath)) {
+    throw new Error(
+      `auto_tune needs a reference image at ${refPath}. Call set_reference ` +
+        `with element=${element}, camera=${target_camera} first (or paste a PNG path/base64).`,
+    );
+  }
+  const target = await resolveLabUrl({ element, labUrl });
+  // Derive the knob origin from the RESOLVED page, not the raw labUrl arg, so
+  // an element whose manifest advertises an absolute cross-origin labUrl still
+  // tunes the page we capture (capture + knob origins must agree).
+  const devUrl = resolveDevUrl({ labUrl: target });
+  const { call } = await browserPool.getPage(target);
+
+  const phi = (1 + Math.sqrt(5)) / 2;
+  const invPhi = 1 / phi;
+  let [a, b] = range;
+  if (!(b > a))
+    throw new Error(`auto_tune range must be [min, max] with max > min, got [${a}, ${b}]`);
+
+  const cache = new Map<string, number>(); // memoize SSIM by knob value
+  const history: Array<{ iter: number; knob: number; ssim: number; ms: number }> = [];
+  const t0 = Date.now();
+
+  async function evalAt(x: number): Promise<number> {
+    const key = x.toFixed(6);
+    if (cache.has(key)) return cache.get(key)!;
+    const iterStart = Date.now();
+    // 1. Post knob via the harness's /__knob endpoint (same origin as capture).
+    await setKnob({ element, key: knob, value: x, devUrl });
+    // 2. Wait (event-driven) for the harness to confirm it applied — returns as
+    // soon as telemetry reflects the value instead of always sleeping 800ms.
+    const applied = await waitForKnobApplied(knob, x, 2500, element, devUrl);
+    if (!applied) await wait(300); // settle fallback if telemetry didn't confirm
+    // 3. Capture target camera in-tab.
+    const cap = await call('Runtime.evaluate', {
+      expression: 'window.__TRISCOPE__.captureViews()',
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const views = cap.result.result.value ?? {};
+    const b64 = String(views[target_camera] ?? '').replace(/^data:image\/png;base64,/, '');
+    if (!b64)
+      throw new Error(`auto_tune: captureViews returned no PNG for camera "${target_camera}"`);
+    // 4. Diff against reference; we minimise (1 - SSIM).
+    const diff = diffReference({
+      cwd: process.cwd(),
+      element,
+      camera: target_camera,
+      currentBase64: b64,
+    });
+    const score = diff.ssim;
+    cache.set(key, score);
+    history.push({ iter: history.length, knob: x, ssim: score, ms: Date.now() - iterStart });
+    return score;
+  }
+
+  // Initial bracket.
+  let c = b - (b - a) * invPhi;
+  let d = a + (b - a) * invPhi;
+  let fc = await evalAt(c);
+  let fd = await evalAt(d);
+
+  for (let i = 0; i < max_iterations - 2; i++) {
+    // Maximise SSIM ⇔ minimise (1 - SSIM): keep the side with higher SSIM.
+    if (fc > fd) {
+      b = d;
+      d = c;
+      fd = fc;
+      c = b - (b - a) * invPhi;
+      fc = await evalAt(c);
+    } else {
+      a = c;
+      c = d;
+      fc = fd;
+      d = a + (b - a) * invPhi;
+      fd = await evalAt(d);
+    }
+    // Early stop when the bracket is below 1% of the original range.
+    if (Math.abs(b - a) < (range[1] - range[0]) * 0.01) break;
+  }
+
+  const best = [...cache.entries()]
+    .map(([k, v]) => ({ knob: Number(k), ssim: v }))
+    .sort((x, y) => y.ssim - x.ssim)[0];
+
+  // Leave the knob at the best value so the user sees the converged state.
+  // Must target the same origin as the tuned page (D5: omitting devUrl would
+  // commit `best` to the boot DEV_URL, leaving the actual lab at the last
+  // evaluated value and falsely reporting "left at best").
+  await setKnob({ element, key: knob, value: best.knob, devUrl });
+
+  return {
+    element,
+    knob,
+    target_camera,
+    bestKnobValue: best.knob,
+    bestSsim: best.ssim,
+    iterations: history.length,
+    history,
+    totalMs: Date.now() - t0,
+    hint: 'SSIM 1.0 = identical to reference, 0.9+ = visually close, <0.7 = clearly different. The knob has been left at bestKnobValue in the live lab.',
+  };
+}
+
+/**
+ * multi_tune: coordinate-descent over 2-N knobs against a reference (SSIM),
+ * reusing the event-driven evalAt loop. Greedy but robust for the smooth,
+ * weakly-coupled knobs shader tuning involves. Hard-capped on total evaluations
+ * so worst-case wall time stays bounded.
+ */
+async function multiTune({
+  element,
+  knobs,
+  target_camera,
+  max_cycles = 2,
+  per_knob_iters = 8,
+  compute_interactions = false,
+  max_evaluations,
+  labUrl,
+}: {
+  element: string;
+  knobs: Array<{ key: string; range: [number, number]; start?: number }>;
+  target_camera: string;
+  max_cycles?: number;
+  per_knob_iters?: number;
+  compute_interactions?: boolean;
+  max_evaluations?: number;
+  labUrl?: string;
+}) {
+  const cwd = process.cwd();
+  const refPath = refsPath(cwd, element, target_camera);
+  if (!existsSync(refPath)) {
+    throw new Error(
+      `multi_tune needs a reference image at ${refPath}. Call set_reference (element=${element}, camera=${target_camera}) first.`,
+    );
+  }
+  const target = await resolveLabUrl({ element, labUrl });
+  // Knob origin derived from the resolved page (see autoTune) — capture + knob
+  // must agree even for an absolute cross-origin manifest labUrl.
+  const devUrl = resolveDevUrl({ labUrl: target });
+  const { call } = await browserPool.getPage(target);
+  const t0 = Date.now();
+  const cache = new Map<string, number>();
+
+  const evalAt = async (values: Record<string, number>): Promise<number> => {
+    const ck = JSON.stringify(values);
+    const hit = cache.get(ck);
+    if (hit !== undefined) return hit;
+    const updates = Object.entries(values).map(([key, value]) => ({ element, key, value }));
+    await setKnob({ updates, devUrl });
+    const last = updates[updates.length - 1];
+    const ok = await waitForKnobApplied(last.key, last.value, 2500, element, devUrl);
+    if (!ok) await wait(300);
+    const cap = await call('Runtime.evaluate', {
+      expression: 'window.__TRISCOPE__.captureViews()',
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const views = cap.result.result.value ?? {};
+    const b64 = String(views[target_camera] ?? '').replace(/^data:image\/png;base64,/, '');
+    if (!b64) throw new Error(`multi_tune: captureViews returned no PNG for "${target_camera}"`);
+    const diff = diffReference({ cwd, element, camera: target_camera, currentBase64: b64 });
+    cache.set(ck, diff.ssim);
+    return diff.ssim;
+  };
+
+  const specs = knobs.map((kn) => ({
+    key: kn.key,
+    min: kn.range[0],
+    max: kn.range[1],
+    start: kn.start ?? (kn.range[0] + kn.range[1]) / 2,
+  }));
+  const hardCap = max_evaluations ?? Math.min(specs.length * per_knob_iters * max_cycles + 4, 64);
+  const result = await coordinateDescent({
+    knobs: specs,
+    evalAt,
+    maxCycles: max_cycles,
+    perKnobIters: per_knob_iters,
+    maxEvaluations: hardCap,
+  });
+
+  // Optional pairwise interaction matrix (2nd-order mixed difference at the
+  // optimum). Off by default — it adds ~3 evals per knob pair.
+  let interactions: Array<{ a: string; b: string; interaction: number }> | undefined;
+  if (compute_interactions && specs.length >= 2) {
+    interactions = [];
+    const base = await evalAt({ ...result.best });
+    for (let i = 0; i < specs.length; i++) {
+      for (let j = i + 1; j < specs.length; j++) {
+        const A = specs[i];
+        const B = specs[j];
+        const dA = (A.max - A.min) * 0.05;
+        const dB = (B.max - B.min) * 0.05;
+        const clamp = (v: number, s: typeof A) => Math.min(s.max, Math.max(s.min, v));
+        const fa = await evalAt({ ...result.best, [A.key]: clamp(result.best[A.key] + dA, A) });
+        const fb = await evalAt({ ...result.best, [B.key]: clamp(result.best[B.key] + dB, B) });
+        const fab = await evalAt({
+          ...result.best,
+          [A.key]: clamp(result.best[A.key] + dA, A),
+          [B.key]: clamp(result.best[B.key] + dB, B),
+        });
+        interactions.push({ a: A.key, b: B.key, interaction: +(fab - fa - fb + base).toFixed(4) });
+      }
+    }
+  }
+
+  // Leave the lab at the converged values (same origin as the tuned page — D5).
+  await setKnob({
+    updates: Object.entries(result.best).map(([key, value]) => ({ element, key, value })),
+    devUrl,
+  });
+
+  return {
+    element,
+    target_camera,
+    best: result.best,
+    bestSsim: +result.bestScore.toFixed(4),
+    cycles: result.cycles,
+    evaluations: result.evaluations,
+    totalMs: Date.now() - t0,
+    interactions,
+    hint: 'SSIM 1.0 = identical, 0.9+ = close. Knobs left at best values in the live lab. interaction>0 = the two knobs reinforce, <0 = they fight (only present when compute_interactions=true).',
+  };
+}
+
+/**
+ * check_targets: load .claude/element-targets.json and evaluate the per-camera
+ * convergence constraints against the current capture — a machine-readable
+ * "definition of done". SSIM/meanAbsDiff constraints need a stored reference
+ * (else they're skipped, not failed); luminance/dynamicRange come from the GPU
+ * probe and are always evaluable.
+ */
+async function checkTargets({ element, labUrl }: { element: string; labUrl?: string }) {
+  const cwd = process.cwd();
+  const file = join(cwd, '.claude', 'element-targets.json');
+  if (!existsSync(file)) {
+    return { checked: 0, allPassed: true, note: `no targets file at ${file}` };
+  }
+  let all: any;
+  try {
+    all = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e: any) {
+    throw new Error(`invalid ${file}: ${e?.message ?? e}`);
+  }
+  const targetsByCamera = all?.[element];
+  if (!targetsByCamera || typeof targetsByCamera !== 'object') {
+    return { checked: 0, allPassed: true, note: `no targets for element "${element}" in ${file}` };
+  }
+  const cap = await captureViews({ element, labUrl, inline: true });
+  const capturedByCamera: Record<string, any> = {};
+  for (const [camera, probe] of Object.entries((cap.gpuProbes ?? {}) as Record<string, any>)) {
+    capturedByCamera[camera] = { luminance: probe.luminance, dynamicRange: probe.dynamicRange };
+  }
+  // For cameras with an ssim/meanAbsDiff constraint AND a stored reference, diff.
+  for (const camera of Object.keys(targetsByCamera)) {
+    const c = targetsByCamera[camera] ?? {};
+    const wantsRefMetric = c.ssim !== undefined || c.meanAbsDiff !== undefined;
+    if (wantsRefMetric && existsSync(refsPath(cwd, element, camera))) {
+      const b64 = cap._base64ByCam?.[camera];
+      if (b64) {
+        const d = diffReference({ cwd, element, camera, currentBase64: b64 });
+        capturedByCamera[camera] = {
+          ...(capturedByCamera[camera] ?? {}),
+          ssim: d.ssim,
+          meanAbsDiff: d.meanAbsDiff,
+        };
+      }
+    }
+  }
+  const report = evaluateTargets(targetsByCamera, capturedByCamera);
+  return {
+    element,
+    file,
+    ...report,
+    hint: report.allPassed
+      ? 'All evaluated constraints pass — this view meets its target.'
+      : 'Some constraints fail (see results[].pass=false). Skipped constraints need a set_reference to evaluate.',
+  };
+}
+
+async function inspect({ element, camera }: { element: string; camera?: string }) {
+  // Resolve the lab URL the same way capture_views does, then append the
+  // ?inspect=<el>&camera=<name> query so the harness boots in solo view.
+  const baseUrl = await resolveLabUrl({ element });
+  const sep = baseUrl.includes('?') ? '&' : '?';
+  const inspectUrl = `${baseUrl}${sep}inspect=${encodeURIComponent(element)}${camera ? `&camera=${encodeURIComponent(camera)}` : ''}`;
+  const t0 = Date.now();
+  await browserPool.getPage(inspectUrl);
+  return {
+    element,
+    camera: camera ?? null,
+    url: inspectUrl,
+    navMs: Date.now() - t0,
+    hint: 'Right-drag to orbit, scroll to zoom, left-click to pick a mesh. Read .selection from telemetry after the user clicks.',
+  };
+}
+
+async function addElement({
+  name,
+  element,
+  labUrl,
+}: {
+  name: string;
+  element?: string;
+  labUrl?: string;
+}) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('add_element requires a non-empty `name`');
+  }
+  // `element`/`labUrl` only locate the running scene page (any mounted element
+  // resolves to it); `name` is the registry element to mount.
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target);
+  const res = await call('Runtime.evaluate', {
+    expression: `JSON.stringify((function(){var t=window.__TRISCOPE__;if(!t||!t.addElement)return{ok:false,error:'addElement unavailable — rebuild the lab against newer @triscope/core'};var ok=t.addElement(${JSON.stringify(name)});return{ok:ok,name:${JSON.stringify(name)},mounted:t.mountedElements?t.mountedElements():[],available:t.availableElements?t.availableElements():[]};})())`,
+    returnByValue: true,
+  });
+  return JSON.parse(res.result.result.value);
+}
+
+async function removeElement({
+  name,
+  element,
+  labUrl,
+}: {
+  name: string;
+  element?: string;
+  labUrl?: string;
+}) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('remove_element requires a non-empty `name`');
+  }
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target);
+  const res = await call('Runtime.evaluate', {
+    expression: `JSON.stringify((function(){var t=window.__TRISCOPE__;if(!t||!t.removeElement)return{ok:false,error:'removeElement unavailable — rebuild the lab against newer @triscope/core'};var ok=t.removeElement(${JSON.stringify(name)});return{ok:ok,name:${JSON.stringify(name)},mounted:t.mountedElements?t.mountedElements():[],available:t.availableElements?t.availableElements():[]};})())`,
+    returnByValue: true,
+  });
+  return JSON.parse(res.result.result.value);
+}
+
+async function inspectScene({
+  element,
+  maxNodes,
+  labUrl,
+  fresh = false,
+}: {
+  element?: string;
+  maxNodes?: number;
+  labUrl?: string;
+  fresh?: boolean;
+}) {
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target, { reload: fresh });
+  const n = Number.isFinite(maxNodes) ? maxNodes : 500;
+  const res = await call('Runtime.evaluate', {
+    expression: `JSON.stringify(window.__TRISCOPE__ && window.__TRISCOPE__.queryScene ? window.__TRISCOPE__.queryScene(${n}) : { error: 'queryScene unavailable — the lab is on an older @triscope/core; rebuild it' })`,
+    returnByValue: true,
+  });
+  return JSON.parse(res.result.result.value);
+}
+
+async function readUniform({
+  element,
+  path,
+  labUrl,
+}: {
+  element?: string;
+  path: string;
+  labUrl?: string;
+}) {
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target);
+  const res = await call('Runtime.evaluate', {
+    expression: `JSON.stringify(window.__TRISCOPE__ && window.__TRISCOPE__.readUniform ? window.__TRISCOPE__.readUniform(${JSON.stringify(path)}) : { kind: 'not-found', error: 'readUniform unavailable — rebuild the lab against newer @triscope/core' })`,
+    returnByValue: true,
+  });
+  return JSON.parse(res.result.result.value);
+}
+
+async function setUniform({
+  element,
+  path,
+  value,
+  labUrl,
+}: {
+  element?: string;
+  path: string;
+  value: unknown;
+  labUrl?: string;
+}) {
+  const target = await resolveLabUrl({ element, labUrl });
+  const { call } = await browserPool.getPage(target);
+  const res = await call('Runtime.evaluate', {
+    expression: `JSON.stringify(window.__TRISCOPE__ && window.__TRISCOPE__.setUniform ? window.__TRISCOPE__.setUniform(${JSON.stringify(path)}, ${JSON.stringify(value)}) : { ok: false, kind: 'not-found', error: 'setUniform unavailable — rebuild the lab against newer @triscope/core' })`,
+    returnByValue: true,
+  });
+  return JSON.parse(res.result.result.value);
+}
+
+async function setSceneParam({
+  cameras,
+  knobs,
+  elements,
+}: {
+  cameras?: Record<string, { position?: number[]; target?: number[]; fov?: number }>;
+  knobs?: Record<string, unknown>;
+  elements?: Record<string, { enabled?: boolean }>;
+}) {
+  const delta: Record<string, unknown> = {};
+  if (cameras && Object.keys(cameras).length) delta.cameras = cameras;
+  if (knobs && Object.keys(knobs).length) delta.knobs = knobs;
+  if (elements && Object.keys(elements).length) delta.elements = elements;
+  if (!delta.cameras && !delta.knobs && !delta.elements) {
+    throw new Error('set_scene_param needs `cameras`, `knobs`, and/or `elements`');
+  }
+  const r = await fetch(`${DEV_URL}/__scene`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(delta),
+  });
+  if (!r.ok) throw new Error(`/__scene returned ${r.status}`);
+  return {
+    ok: true,
+    applied: delta,
+    note: 'Applied by the harness within ~100 ms (no reload) and persisted via /__scene so it survives a reload. Read back with get_scene or read_telemetry .cameras.',
+  };
+}
+
+async function getScene({ devUrl, labUrl }: { devUrl?: string; labUrl?: string } = {}) {
+  const url = resolveDevUrl({ devUrl, labUrl });
+  let sceneSpec: unknown = {};
+  let live: unknown = {};
+  try {
+    const r = await fetch(`${url}/__scene/current`);
+    if (r.ok) sceneSpec = await r.json();
+  } catch {
+    /* dev server down */
+  }
+  // Live scene state from the dev server's telemetry over HTTP (works for any
+  // project/port; falls back to the local file only for the default dev server).
+  const state = await fetchState(url);
+  const st = state?.data ?? (url === DEV_URL && existsSync(STATE_PATH) ? safeReadState() : null);
+  if (st) live = { cameras: st.cameras, knobs: st.knobs, elements: st.sceneElements };
+  return { sceneSpec, live };
+}
+
+function safeReadState(): any {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function openSelection({ editor }: { editor?: string }) {
+  // Read the current selection from the telemetry snapshot. The selection
+  // is written by the inspect-mode click handler in the browser, then
+  // surfaced into /tmp/<project>-state.json on the next telemetry tick.
+  if (!existsSync(STATE_PATH)) {
+    throw new Error(`No telemetry at ${STATE_PATH} — is the dev server running with a lab open?`);
+  }
+  const state: any = JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  const sel = state?.selection;
+  if (!sel?.source?.file) {
+    throw new Error(
+      'No mesh selected yet. Open the lab in inspect mode and left-click something first.',
+    );
+  }
+  // Convert vite-served URL to a filesystem path: strip protocol+host so
+  // `code --goto` resolves it relative to cwd (the project the dev server
+  // is serving). Falls through if `file` is already a path.
+  const rawFile = String(sel.source.file);
+  const fsPath = rawFile
+    .replace(/^https?:\/\/[^/]+\//, '') // strip http://host:port/
+    .replace(/^file:\/\//, '') // strip file://
+    .replace(/[?#].*$/, ''); // strip query/hash
+  const absPath = fsPath.startsWith('/') ? fsPath : join(process.cwd(), fsPath);
+  const line = Number(sel.source.line ?? 1);
+  const col = Number(sel.source.col ?? 1);
+  // Editor resolution: explicit arg → $EDITOR → `code --goto`. We assume
+  // `code` is on PATH for VS Code / Cursor / VSCodium users; others can
+  // export $EDITOR (e.g. EDITOR="zed --goto") to override.
+  const cmd = editor ?? process.env.EDITOR ?? 'code';
+  // `code --goto file:line:col` is the standard VSCode invocation.
+  const usesGoto = /code\b/.test(cmd);
+  const args = usesGoto ? ['--goto', `${absPath}:${line}:${col}`] : [`${absPath}:${line}:${col}`];
+  return await new Promise<{
+    ok: boolean;
+    cmd: string;
+    args: string[];
+    file: string;
+    line: number;
+    col: number;
+    stderr?: string;
+  }>((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+      shell: NEED_SHELL,
+    });
+    let stderr = '';
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (err) => reject(new Error(`failed to spawn ${cmd}: ${err.message}`)));
+    // Editor commands usually fork-and-detach; don't wait for exit, just
+    // confirm we spawned without immediate error.
+    setTimeout(() => {
+      try {
+        child.unref();
+      } catch {}
+      resolve({ ok: true, cmd, args, file: absPath, line, col, stderr: stderr || undefined });
+    }, 200);
+  });
+}
+
+async function runSmoke({ element }) {
+  return new Promise((resolve, reject) => {
+    const args = ['smoke'];
+    if (element) args.push(element);
+    const child = spawn('triscope', args, { stdio: ['ignore', 'pipe', 'pipe'], shell: NEED_SHELL });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', reject);
+    child.on('exit', (code) => resolve({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+
+async function importElement({ source, name }: { source: string; name?: string }) {
+  rejectFlagArg(source, 'source');
+  if (name !== undefined) rejectFlagArg(name, 'name');
+  return new Promise((resolve, reject) => {
+    const args = ['import', source];
+    if (name) args.push('--name', name);
+    const child = spawn(TRISCOPE_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', reject);
+    child.on('exit', (code) => resolve({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+
+async function scaffoldFromGltf({ file, name }: { file: string; name?: string }) {
+  rejectFlagArg(file, 'file');
+  if (name !== undefined) rejectFlagArg(name, 'name');
+  return new Promise((resolve, reject) => {
+    const args = ['new-gltf', file];
+    if (name) args.push('--name', name);
+    const child = spawn(TRISCOPE_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', reject);
+    child.on('exit', (code) => resolve({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+
+const tools = [
+  {
+    name: 'list_elements',
+    description:
+      'List elements registered with the running triscope dev server. Cameras + current knob values appear per element ONLY after a browser has mounted that lab (the harness POSTs the full manifest on mount); a cold call returns just the seeded `{element, labUrl}` from package.json#triscope.labs. Pass devUrl/labUrl to target a different dev server than the one the MCP booted against.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        devUrl: {
+          type: 'string',
+          description: 'Target dev-server origin (default: the boot one).',
+        },
+        labUrl: { type: 'string', description: 'A lab URL; its origin is used as devUrl.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'read_telemetry',
+    description:
+      'Read the latest telemetry snapshot (live over GET /__state, falling back to the on-disk file — so it now works cross-project). Optional jq-style "path" (e.g. ".elements.ship.triangles", ".perf.fps") returns that slice VERBATIM. The FULL snapshot (no path) is annotated with `__source` ("live"/"disk") + `__staleMs` + a `__warning` when old (the lab tab may be backgrounded/closed). Use for hidden numeric state where screenshots lie. Pass devUrl/labUrl to read a different dev server/project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Dot-separated jq-style path into the snapshot.' },
+        devUrl: {
+          type: 'string',
+          description: 'Target dev-server origin (default: the boot one).',
+        },
+        labUrl: { type: 'string', description: 'A lab URL; its origin is used as devUrl.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'set_knob',
+    description:
+      'Live-update one or many knobs in a single round trip. Either pass {element,key,value} for a single update OR {updates:[{element,key,value},...]} to batch. Use absolute values, never deltas. Changes take effect in the running browser within ~100 ms. Out-of-range / wrong-type values are clamped to the knob spec before they apply; when that happens the response includes clamped:[{element,key,requested,final}] so you know what actually took effect. Pass devUrl/labUrl to target a different dev server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element name (single-update form).' },
+        key: { type: 'string', description: 'Knob key (single-update form).' },
+        value: { description: 'Absolute value (number, "#aabbcc" color, boolean).' },
+        updates: {
+          type: 'array',
+          description: 'Batch form: array of {element,key,value} entries applied atomically.',
+          items: {
+            type: 'object',
+            properties: {
+              element: { type: 'string' },
+              key: { type: 'string' },
+              value: {},
+            },
+            required: ['element', 'key', 'value'],
+          },
+        },
+        devUrl: {
+          type: 'string',
+          description: 'Target dev-server origin (default: the boot one).',
+        },
+        labUrl: { type: 'string', description: 'A lab URL; its origin is used as devUrl.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'capture_views',
+    description:
+      'Spawn Chromium against a lab page (resolved via Element.labUrl in the manifest, package.json#triscope.labs, or /labs/<element>.html as fallback) and render every named camera. Writes PNGs to /tmp/<project>-capture-<element>/<camera>.png AND returns each image inline as MCP image content blocks (so the model sees them directly without a Read call). Set inline=false to return paths only (smaller payload). The response includes blackFrames:[camera,...] (panes the GPU drew black — luminance below threshold, a render failure) AND flatFrames:[camera,...] (panes with dynamicRange≈1, i.e. only the flat clear-color is in view — the element drifted out of frame or was not drawn; blackFrames misses this when the clear-color is above the black threshold).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: {
+          type: 'string',
+          description: 'Element name. URL is resolved via manifest/config.',
+        },
+        labUrl: {
+          type: 'string',
+          description: 'Override the lab URL entirely (highest precedence).',
+        },
+        inline: {
+          type: 'boolean',
+          description:
+            'Return images as inline content blocks. Default false — safer for many-camera elements where the inline base64 payload can blow the MCP stdio message budget. Set true only when you specifically want inline.',
+          default: false,
+        },
+        fresh: {
+          type: 'boolean',
+          description:
+            'Force a full page reload before capturing, so a source edit the pooled page would otherwise miss (e.g. a *.lab.ts change) is picked up. Costs a reload (~1-3s) and drops transient set_uniform writes. Default false.',
+          default: false,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'set_reference',
+    description:
+      'Save a reference image for an (element, camera) pair under <project>/refs/<element>/<camera>.png. Accepts EITHER a `path` to a file on disk (e.g. a chat-attachment path) OR `base64` inline PNG data. Use this when the user pastes a reference image they want the AI to converge toward.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element name.' },
+        camera: { type: 'string', description: 'Camera name (must match Element.cameras key).' },
+        path: {
+          type: 'string',
+          description: 'Filesystem path to a PNG/JPEG (one of path or base64 required).',
+        },
+        base64: {
+          type: 'string',
+          description: 'Base64-encoded PNG (with or without data: prefix).',
+        },
+      },
+      required: ['element', 'camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'diff_reference',
+    description:
+      'Capture the current view at (element, camera), diff it against the stored reference, and return: numeric meanAbsDiff (0-255) + ssim (1=identical); an 8×8 per-tile SSIM grid + the worstTile {row,col,ssim} so you know WHERE they differ; the side-by-side composite (left=ref, right=current); and a black→blue→yellow→red difference heatmap (hot = divergent region) as a second image. Requires a prior set_reference for the same (element, camera).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element name.' },
+        camera: { type: 'string', description: 'Camera name.' },
+        labUrl: {
+          type: 'string',
+          description: 'Override the lab URL (otherwise resolved like capture_views).',
+        },
+        fresh: {
+          type: 'boolean',
+          description:
+            'Force a full reload before capturing (pick up source edits). Default false.',
+        },
+      },
+      required: ['element', 'camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'set_reference_motion',
+    description:
+      'Capture the CURRENT motion sequence at (element, camera) and save it as the animated reference. Writes <project>/refs/<element>/<camera>.motion.png (filmstrip) + <camera>.motion.json (frames/dt/mode metadata). Use to lock in a known-good animation before risky shader/uniform edits, then diff_reference_motion confirms regressions visually + numerically.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        camera: { type: 'string' },
+        frames: { type: 'number', description: 'Default 6.' },
+        dt: { type: 'number', description: 'Seconds between frames. Default 0.25.' },
+        mode: { type: 'string', enum: ['time', 'real'], description: 'Default "time".' },
+        labUrl: { type: 'string' },
+      },
+      required: ['element', 'camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'diff_reference_motion',
+    description:
+      'Capture current motion at (element, camera), diff against the saved animated reference. Returns a vertically-stacked composite (reference filmstrip on top, current on bottom) inline AND a scalar motionDiff (0=identical animation, >5=visible drift, >30=clearly different). Requires a prior set_reference_motion for the same (element, camera).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        camera: { type: 'string' },
+        frames: { type: 'number' },
+        dt: { type: 'number' },
+        mode: { type: 'string', enum: ['time', 'real'] },
+        labUrl: { type: 'string' },
+      },
+      required: ['element', 'camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'capture_motion',
+    description:
+      'Capture N frames per camera spaced by dt seconds, compose each into an inline filmstrip image (frames tiled left-to-right), and return a numeric motionMagnitude per camera (0-255 scale; <1 = static, >5 = visible motion, >20 = vigorous). Use this WHEN THE ELEMENT HAS ANIMATION (shader-driven motion, sail billow, particle systems, oscillation) — a single capture_views frame cannot reveal whether motion is happening. For complementary numeric verification of hidden animated state, read_telemetry .elements.<name>.motion (if the Element declared motionProbes).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        camera: {
+          type: 'string',
+          description: 'Single camera. Omit to capture all cameras (one filmstrip each).',
+        },
+        frames: { type: 'number', description: 'Frames per filmstrip. Default 6.' },
+        dt: { type: 'number', description: 'Seconds between captured frames. Default 0.25.' },
+        mode: {
+          type: 'string',
+          enum: ['time', 'real'],
+          description:
+            '"time" (default) is deterministic (steps time.value, fast). "real" runs wall-clock (slower; needed for CPU-integrated state).',
+        },
+        labUrl: {
+          type: 'string',
+          description: 'Override the lab URL (otherwise resolved like capture_views).',
+        },
+        inline: {
+          type: 'boolean',
+          description: 'Include filmstrips as inline images. Default true.',
+        },
+        fresh: {
+          type: 'boolean',
+          description:
+            'Force a full reload before capturing (pick up source edits). Default false.',
+        },
+      },
+      required: ['element'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'health',
+    description:
+      'Server health snapshot. Returns uptime, dev-server reachability, browser-pool state, pid, recent errors (last 16). Call this when other tools misbehave: a "Connection closed" error from a capture tool followed by a healthy health() call means the MCP server is alive but the browser pool needs to recover; a failed health() means the server itself is sick.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'run_smoke',
+    description:
+      'Run the headed-Chromium smoke harness against a lab page. Returns exit code, stdout, stderr. Use as a CI gate after a batch of knob changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: {
+          type: 'string',
+          description: 'Element lab to test (defaults to the scene lab).',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'import_element',
+    description:
+      'Install a published element package (naming convention `triscope-element-<name>`, or `github:user/repo`) into the current project and wire its lab page + vite input + package.json#triscope.labs. Runs `triscope import`; returns exit code + output. After it succeeds, capture_views/inspect_scene the new element by name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'npm package or github:user/repo[#ref].' },
+        name: { type: 'string', description: 'Override the local element/lab name.' },
+      },
+      required: ['source'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'scaffold_from_gltf',
+    description:
+      'Generate a wired triscope Element from a glTF/GLB asset path: auto-detects bounds + animation clips, copies the asset to /public, and writes src/elements/<name>.ts (GLTFLoader + AnimationMixer + fitted cameras + scale knob + dispose). Runs `triscope new-gltf`; returns exit code + output. Saves ~40-100 lines of loader/dispose boilerplate when bringing in a model.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to a .glb or .gltf file.' },
+        name: {
+          type: 'string',
+          description: 'Override the element name (default: file basename).',
+        },
+      },
+      required: ['file'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'inspect_scene',
+    description:
+      'Snapshot the live scene graph: every mesh/light/group with triangleCount, worldPosition, materialKind + materialColor, uniformNames, and the file:line `source` where it was added. Answers "what is in this scene / which object is X / where is its code" in ONE call instead of many capture_views probes. Returns `nodes` (sorted by triangle count, capped at maxNodes — default 120; `truncated`+`total` flag the rest, raise maxNodes to see it) PLUS a separate `lights` array — every light with type/intensity/color/position, ALWAYS included regardless of the cap (a named light is then read/writable via read_uniform/set_uniform "name.intensity").',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: {
+          type: 'string',
+          description:
+            'Element/lab to introspect (resolved like capture_views). Omit for the scene lab.',
+        },
+        maxNodes: { type: 'number', description: 'Cap on returned nodes. Default 500.' },
+        labUrl: { type: 'string', description: 'Override the lab URL.' },
+        fresh: {
+          type: 'boolean',
+          description: 'Force a full reload first (pick up source edits). Default false.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'read_uniform',
+    description:
+      'Read ANY live material uniform / material property / object property by "objectName|uuid.key" path — even values never declared as knobs (e.g. "ship.metalness", "sun.intensity", a shader uniform "ocean.uChoppiness"). Use inspect_scene first to discover object names + uniformNames. Returns {kind, value} (colors as #hex, vectors as arrays); kind="not-found" if the path doesn\'t resolve.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element/lab (resolved like capture_views).' },
+        path: { type: 'string', description: '"<objectName|uuid>.<key>" — split on the last dot.' },
+        labUrl: { type: 'string' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'set_uniform',
+    description:
+      'Write ANY live material uniform / material property / object property by "objectName|uuid.key" path WITHOUT a source edit or reload — for probing a shader parameter that isn\'t a declared knob. Colors accept "#rrggbb" or a number; vectors accept [x,y,z]. TRANSIENT: not persisted across reloads (use set_knob for values you want to keep). Returns {ok, previous, current}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        path: { type: 'string', description: '"<objectName|uuid>.<key>".' },
+        value: { description: 'Number, "#hex" / numeric color, boolean, or [x,y,z] vector.' },
+        labUrl: { type: 'string' },
+      },
+      required: ['path', 'value'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'inspect',
+    description:
+      'Open the lab for an element in interactive inspect mode (solo full-canvas camera + OrbitControls + click-to-pick). Navigates the running browser via CDP to ?inspect=<element>&camera=<name>. Use when the user asks to "inspect" or "open" an element so they can rotate and click parts of it; subsequent clicks populate .selection in telemetry with source file:line.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element to inspect (must match the manifest).' },
+        camera: {
+          type: 'string',
+          description: "Starting camera (defaults to the element's first declared camera).",
+        },
+      },
+      required: ['element'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'open_selection',
+    description:
+      'Open the file:line of the currently selected mesh (from inspect mode) in the user\'s editor. Reads .selection.source from the telemetry snapshot and spawns $EDITOR (or `code --goto` by default). Use after the user clicks a mesh and says "open this" / "show me the code".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        editor: {
+          type: 'string',
+          description: 'Override the editor command. Default: $EDITOR or `code`.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'snapshot',
+    description:
+      "Freeze the current tuning state as a git tag (triscope/snapshot/<name>). Stores the HEAD commit + every persisted knob value across all elements, as JSON inside the tag's annotated message — no working-tree files written, no rebase noise. Refuses on a dirty working tree (would silently lose the in-progress edits on restore).",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Snapshot name. Must match [A-Za-z0-9._-]+.' },
+        message: {
+          type: 'string',
+          description: 'Optional human note for `git show triscope/snapshot/<name>`.',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'restore',
+    description:
+      'Restore a snapshot: git checkout the recorded commit and re-post every knob value via /__knob. Refuses on a dirty working tree. Leaves HEAD detached — branch from there if you want to keep iterating.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Snapshot name (matches `mcp__triscope__list_snapshots`).',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'list_snapshots',
+    description:
+      'List every triscope snapshot tag in this repo (name, creation date, message subject). Use to find which one to restore.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'auto_tune',
+    description:
+      'Find the knob value that maximises SSIM (perceptual similarity) between the captured view and a stored reference image, using derivative-free golden-section search. Requires a prior set_reference for (element, target_camera). Iterations: post_knob → wait → captureViews → diff_reference. Use to converge a single shader parameter on a reference photo without manual bisection.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Element whose knob to tune.' },
+        knob: {
+          type: 'string',
+          description: 'Knob key (must exist on Element.knobs and be type=number).',
+        },
+        range: {
+          type: 'array',
+          description:
+            "Inclusive [min, max] search bracket. Should cover the knob's declared min/max.",
+          items: { type: 'number' },
+          minItems: 2,
+          maxItems: 2,
+        },
+        target_camera: {
+          type: 'string',
+          description:
+            'Camera the SSIM is computed on. Must have a stored reference (set_reference first).',
+        },
+        max_iterations: {
+          type: 'number',
+          description:
+            'Cap on knob evaluations. Default 12 (golden section converges to ~0.7% of range).',
+        },
+        labUrl: {
+          type: 'string',
+          description: 'Override the lab URL (otherwise resolved like capture_views).',
+        },
+      },
+      required: ['element', 'knob', 'range', 'target_camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'multi_tune',
+    description:
+      'Converge 2-N coupled knobs on a reference image at once via coordinate descent (golden-section per knob, repeated cycles) maximising SSIM. Use when several knobs jointly shape the look (e.g. choppiness + foamThreshold + exposure) — beats chaining single-knob auto_tune. Requires a prior set_reference for (element, target_camera). Hard-capped on total captures so wall time stays bounded; best with <=4 knobs. Leaves the lab at the converged values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        knobs: {
+          type: 'array',
+          minItems: 1,
+          description:
+            'Knobs to co-tune: [{key, range:[min,max], start?}]. Keep to <=4 for reasonable wall time.',
+          items: {
+            type: 'object',
+            properties: {
+              key: { type: 'string' },
+              range: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 },
+              start: { type: 'number' },
+            },
+            required: ['key', 'range'],
+            additionalProperties: false,
+          },
+        },
+        target_camera: {
+          type: 'string',
+          description: 'Camera the SSIM is computed on (needs a stored reference).',
+        },
+        max_cycles: { type: 'number', description: 'Passes over all knobs. Default 2.' },
+        per_knob_iters: {
+          type: 'number',
+          description: 'Golden-section evals per knob per cycle. Default 8.',
+        },
+        compute_interactions: {
+          type: 'boolean',
+          description:
+            'Also return a pairwise knob-interaction matrix (extra evals). Default false.',
+        },
+        max_evaluations: {
+          type: 'number',
+          description: 'Hard cap on total captures. Default min(knobs*iters*cycles+4, 64).',
+        },
+        labUrl: { type: 'string' },
+      },
+      required: ['element', 'knobs', 'target_camera'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'check_targets',
+    description:
+      'Evaluate per-camera convergence constraints from .claude/element-targets.json against the current capture — a machine-readable "is this view done?". Constraints per camera: ssim (min), meanAbsDiff (max), luminance {min,max}, dynamicRange {min,max}. ssim/meanAbsDiff need a stored reference (skipped, not failed, when absent); luminance/dynamicRange come from the GPU probe. Returns per-constraint pass/fail + allPassed. No targets file → no-op pass.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string' },
+        labUrl: { type: 'string' },
+      },
+      required: ['element'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'set_scene_param',
+    description:
+      'Live-mutate the scene WITHOUT a code edit or reload (Scene Description Layer): repoint cameras (position/target/fov), override knobs, and show/hide composed elements (enabled true/false — the "solo a track" model). Applied by the harness within ~100 ms and persisted so it survives a reload. NOTE: `elements` toggles visibility of elements already composed into the scene; instantiating a brand-new element type still needs a code edit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cameras: {
+          type: 'object',
+          description: 'Map of cameraName → {position:[x,y,z], target:[x,y,z], fov} (any subset).',
+          additionalProperties: {
+            type: 'object',
+            properties: {
+              position: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3 },
+              target: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3 },
+              fov: { type: 'number' },
+            },
+            additionalProperties: false,
+          },
+        },
+        knobs: {
+          type: 'object',
+          description:
+            'Map of knobKey → value (same effect as set_knob; here for one-call scene edits).',
+        },
+        elements: {
+          type: 'object',
+          description:
+            'Map of elementName → {enabled:boolean} to show/hide a composed element live.',
+          additionalProperties: {
+            type: 'object',
+            properties: { enabled: { type: 'boolean' } },
+            additionalProperties: false,
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_scene',
+    description:
+      'Return the current scene: `sceneSpec` (the persisted SDL overrides from set_scene_param) and `live` (the camera positions/targets/fov + knob values from telemetry). Use to see what a viewpoint currently is before repointing it. Pass devUrl/labUrl to target a different dev server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        devUrl: {
+          type: 'string',
+          description: 'Target dev-server origin (default: the boot one).',
+        },
+        labUrl: { type: 'string', description: 'A lab URL; its origin is used as devUrl.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'add_element',
+    description:
+      'Instantiate a registered element into a runSceneLab scene LIVE (no reload): mounts it, adds its namespaced `<element>.<camera>` cameras + `<element>.<knob>` knobs, and rebuilds the grid. Returns {ok, mounted, available}. Only works on a multi-element scene booted with runSceneLab — on a single-element runLab page it returns {ok:false}. Use `available` from a prior add/remove (or list_elements) to see mountable names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Registered element name to mount.' },
+        element: {
+          type: 'string',
+          description: 'Any element in the scene, used only to locate the lab page.',
+        },
+        labUrl: { type: 'string', description: 'Explicit lab URL (alternative to element).' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remove_element',
+    description:
+      'Dispose a mounted element from a runSceneLab scene LIVE (no reload): drops its cameras/knobs/telemetry and rebuilds the grid. The element stays in the registry and can be re-added with add_element. Returns {ok, mounted, available}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Mounted element name to dispose.' },
+        element: {
+          type: 'string',
+          description: 'Any element in the scene, used only to locate the lab page.',
+        },
+        labUrl: { type: 'string', description: 'Explicit lab URL (alternative to element).' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function jsonResult(value) {
+  let text: string;
+  if (value === undefined) text = 'undefined';
+  else if (typeof value === 'string') text = value;
+  else text = JSON.stringify(value, null, 2);
+  return {
+    content: [{ type: 'text', text }],
+  };
+}
+
+export async function startServer() {
+  const server = new Server(
+    // Reported to every MCP client in the `initialize` handshake — keep in sync
+    // with packages/mcp/package.json version on each release.
+    { name: 'triscope-mcp', version: '0.4.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    // One info log per tool entry; on the way out either 'succeeded' or
+    // 'failed' so a hung/dropped call leaves a half-pair in the log (no
+    // succeeded/failed entry → the response never returned, e.g. the
+    // process was OOM-killed during JSON encoding).
+    const toolStart = Date.now();
+    logger.info(`tool:${name}`, 'invoked', { args });
+    const finish = (outcome: 'succeeded' | 'failed', extra?: Record<string, unknown>) =>
+      logger.info(`tool:${name}`, outcome, { ms: Date.now() - toolStart, ...(extra ?? {}) });
+    try {
+      const result = await (async () => {
+        switch (name) {
+          case 'list_elements':
+            return jsonResult(
+              await listElements({
+                devUrl: args.devUrl as string | undefined,
+                labUrl: args.labUrl as string | undefined,
+              }),
+            );
+          case 'read_telemetry':
+            return jsonResult(
+              await readTelemetry(args.path as string | undefined, {
+                devUrl: args.devUrl as string | undefined,
+                labUrl: args.labUrl as string | undefined,
+              }),
+            );
+          case 'set_knob': {
+            const value = z.union([z.number(), z.string(), z.boolean()]);
+            const update = z.object({ element: z.string(), key: z.string(), value });
+            const schema = z.union([z.object({ updates: z.array(update).min(1) }), update]);
+            const parsed = schema.parse(args);
+            const loc = z
+              .object({ devUrl: z.string().optional(), labUrl: z.string().optional() })
+              .parse(args);
+            return jsonResult(await setKnob({ ...parsed, ...loc }));
+          }
+          case 'capture_views': {
+            const res = await captureViews({
+              element: args.element as string | undefined,
+              labUrl: args.labUrl as string | undefined,
+              inline: (args.inline ?? false) as boolean,
+              fresh: (args.fresh ?? false) as boolean,
+            });
+            const { _base64ByCam, ...summary } = res;
+            // Cap inline payload: 12-camera scenes can produce ~20 MB of base64
+            // in a single JSON-RPC message over stdio, which OOM-kills the
+            // server process (no catch, no log — Claude Code then auto-respawns
+            // us and tools are temporarily unavailable). Auto-downgrade to
+            // file paths when over budget and surface a warning so the model
+            // knows to Read the files instead.
+            let inlineBytes = 0;
+            for (const b64 of Object.values(_base64ByCam) as string[]) inlineBytes += b64.length;
+            const inlineCapped = res.inline && inlineBytes > INLINE_PAYLOAD_BUDGET;
+            const finalInline = res.inline && !inlineCapped;
+            const summaryWithWarn = inlineCapped
+              ? {
+                  ...summary,
+                  inline: false,
+                  inlineCapped: true,
+                  inlineWarning: `inline payload would have been ${(inlineBytes / 1048576).toFixed(1)} MB (limit ${(INLINE_PAYLOAD_BUDGET / 1048576).toFixed(0)} MB) — files are on disk, Read them by path.`,
+                }
+              : summary;
+            const text = JSON.stringify(summaryWithWarn, null, 2);
+            if (!finalInline) return { content: [{ type: 'text', text }] };
+            const content: any[] = [{ type: 'text', text }];
+            for (const cam of res.cameraOrder) {
+              const data = _base64ByCam[cam];
+              if (!data) continue;
+              content.push({ type: 'image', data, mimeType: 'image/png' });
+            }
+            return { content };
+          }
+          case 'set_reference': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string(),
+                path: z.string().optional(),
+                base64: z.string().optional(),
+              })
+              .parse(args);
+            const result = setReference({ cwd: process.cwd(), ...parsed } as any);
+            return jsonResult(result);
+          }
+          case 'diff_reference': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string(),
+                labUrl: z.string().optional(),
+                fresh: z.boolean().optional(),
+              })
+              .parse(args);
+            const refExists = existsSync(refsPath(process.cwd(), parsed.element, parsed.camera));
+            if (!refExists) {
+              return {
+                isError: true,
+                content: [
+                  {
+                    type: 'text',
+                    text: `no reference at ${refsPath(process.cwd(), parsed.element, parsed.camera)}. Call set_reference first.`,
+                  },
+                ],
+              };
+            }
+            const cap = await captureViews({
+              element: parsed.element,
+              labUrl: parsed.labUrl,
+              inline: true,
+              fresh: parsed.fresh ?? false,
+            });
+            const currentBase64 = cap._base64ByCam?.[parsed.camera];
+            if (!currentBase64) {
+              return {
+                isError: true,
+                content: [
+                  {
+                    type: 'text',
+                    text: `camera "${parsed.camera}" not found on element "${parsed.element}". Available: ${cap.cameraOrder.join(', ')}`,
+                  },
+                ],
+              };
+            }
+            const diff = diffReference({
+              cwd: process.cwd(),
+              element: parsed.element,
+              camera: parsed.camera,
+              currentBase64,
+            });
+            // Two images: the side-by-side composite (always) and the
+            // difference heatmap (when it fits the inline budget). The heatmap
+            // is what makes the worstTile/tileGrid spatially legible.
+            const compositeBytes = diff.compositeBase64.length;
+            const heatmapBytes = diff.heatmapBase64?.length ?? 0;
+            const heatmapFits = compositeBytes + heatmapBytes <= INLINE_PAYLOAD_BUDGET;
+            const content: any[] = [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    camera: diff.camera,
+                    refPath: diff.refPath,
+                    meanAbsDiff: diff.meanAbsDiff,
+                    ssim: diff.ssim,
+                    worstTile: diff.worstTile,
+                    tileStats: diff.tileStats,
+                    tileGrid: diff.tileGrid,
+                    heatmapIncluded: heatmapFits,
+                    hint: 'meanAbsDiff: 0 = identical, ~30 = visibly close, >80 = clearly different. ssim: 1.0 = identical, 0.9+ = visually close, <0.7 = clearly different (prefer SSIM, robust to AA noise). tileGrid is an 8×8 SSIM map (row 0 = top); worstTile points at the most divergent region. The second image is a black→blue→yellow→red difference heatmap — hot = where the frames differ.',
+                  },
+                  null,
+                  2,
+                ),
+              },
+              { type: 'image', data: diff.compositeBase64, mimeType: 'image/png' },
+            ];
+            if (heatmapFits && diff.heatmapBase64) {
+              content.push({ type: 'image', data: diff.heatmapBase64, mimeType: 'image/png' });
+            }
+            return { content };
+          }
+          case 'set_reference_motion': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string(),
+                frames: z.number().int().min(2).max(32).optional(),
+                dt: z.number().positive().max(5).optional(),
+                mode: z.enum(['time', 'real']).optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            const opts = {
+              frames: parsed.frames ?? 6,
+              dt: parsed.dt ?? 0.25,
+              mode: parsed.mode ?? 'time',
+            };
+            const frameB64s = await captureMotionFramesRaw({ ...parsed, ...opts });
+            const r = setReferenceMotion({
+              cwd: process.cwd(),
+              element: parsed.element,
+              camera: parsed.camera,
+              frameBase64s: frameB64s,
+              meta: opts,
+            });
+            return jsonResult(r);
+          }
+          case 'diff_reference_motion': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string(),
+                frames: z.number().int().min(2).max(32).optional(),
+                dt: z.number().positive().max(5).optional(),
+                mode: z.enum(['time', 'real']).optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            const { filmstrip, meta } = refsMotionPaths(
+              process.cwd(),
+              parsed.element,
+              parsed.camera,
+            );
+            if (!existsSync(filmstrip)) {
+              return {
+                isError: true,
+                content: [
+                  {
+                    type: 'text',
+                    text: `no motion reference at ${filmstrip}. Call set_reference_motion first.`,
+                  },
+                ],
+              };
+            }
+            // Inherit frame/dt/mode from saved metadata so the comparison is fair.
+            let savedMeta: any = {};
+            try {
+              savedMeta = existsSync(meta) ? JSON.parse(readFileSync(meta, 'utf8')) : {};
+            } catch {}
+            const opts = {
+              frames: parsed.frames ?? savedMeta.frames ?? 6,
+              dt: parsed.dt ?? savedMeta.dt ?? 0.25,
+              mode: parsed.mode ?? savedMeta.mode ?? 'time',
+            };
+            const frameB64s = await captureMotionFramesRaw({ ...parsed, ...opts });
+            const diff = diffReferenceMotion({
+              cwd: process.cwd(),
+              element: parsed.element,
+              camera: parsed.camera,
+              currentFrames: frameB64s,
+            });
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify(
+                    {
+                      camera: parsed.camera,
+                      refFilmstripPath: diff.refFilmstripPath,
+                      refMeta: diff.refMeta,
+                      motionDiff: diff.motionDiff,
+                      hint: '0 = identical animation, >5 = visible drift, >30 = clearly different',
+                    },
+                    null,
+                    2,
+                  ),
+                },
+                { type: 'image', data: diff.compositeBase64, mimeType: 'image/png' },
+              ],
+            };
+          }
+          case 'capture_motion': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string().optional(),
+                frames: z.number().int().min(2).max(32).optional(),
+                dt: z.number().positive().max(5).optional(),
+                mode: z.enum(['time', 'real']).optional(),
+                labUrl: z.string().optional(),
+                inline: z.boolean().optional(),
+                fresh: z.boolean().optional(),
+              })
+              .parse(args);
+            const res = await captureMotion(parsed);
+            const { _filmstripBase64, ...summary } = res;
+            // Same inline budget guard as capture_views — filmstrips can be
+            // even bigger (N frames per camera) so easier to blow the cap.
+            let filmstripBytes = 0;
+            for (const b64 of Object.values(_filmstripBase64) as string[])
+              filmstripBytes += b64.length;
+            const userWantsInline = parsed.inline !== false;
+            const filmstripCapped = userWantsInline && filmstripBytes > INLINE_PAYLOAD_BUDGET;
+            const finalInline = userWantsInline && !filmstripCapped;
+            const text = JSON.stringify(
+              {
+                ...summary,
+                ...(filmstripCapped
+                  ? {
+                      inlineCapped: true,
+                      inlineWarning: `filmstrip payload would have been ${(filmstripBytes / 1048576).toFixed(1)} MB (limit ${(INLINE_PAYLOAD_BUDGET / 1048576).toFixed(0)} MB) — files are on disk, Read them by path.`,
+                    }
+                  : {}),
+                hint: '<1 = static, >5 = visible motion, >20 = vigorous (in motionMagnitude)',
+              },
+              null,
+              2,
+            );
+            if (!finalInline) return { content: [{ type: 'text', text }] };
+            const content: any[] = [{ type: 'text', text }];
+            for (const cam of res.cameraOrder) {
+              const data = _filmstripBase64[cam];
+              if (data) content.push({ type: 'image', data, mimeType: 'image/png' });
+            }
+            return { content };
+          }
+          case 'health': {
+            let devServerOk = false;
+            let manifestElements = [];
+            try {
+              const r = await fetch(`${DEV_URL}/__manifest`, { signal: AbortSignal.timeout(2000) });
+              if (r.ok) {
+                const m: any = await r.json();
+                devServerOk = true;
+                manifestElements = Object.keys(m?.elements ?? {});
+              }
+            } catch {}
+            const mem = process.memoryUsage();
+            return jsonResult({
+              uptimeSec: Math.round((Date.now() - SERVER_START_TIME) / 1000),
+              pid: process.pid,
+              nodeVersion: process.version,
+              project: PROJECT,
+              devServer: { url: DEV_URL, reachable: devServerOk, manifestElements },
+              memoryMB: {
+                rss: +(mem.rss / 1048576).toFixed(1),
+                heapUsed: +(mem.heapUsed / 1048576).toFixed(1),
+                external: +(mem.external / 1048576).toFixed(1),
+              },
+              logPath: logger.logPath,
+              recentErrors,
+            });
+          }
+          case 'run_smoke':
+            return jsonResult(await runSmoke({ element: args.element }));
+          case 'import_element': {
+            const parsed = z
+              .object({ source: z.string(), name: z.string().optional() })
+              .parse(args);
+            return jsonResult(
+              await importElement({ source: parsed.source as string, name: parsed.name }),
+            );
+          }
+          case 'scaffold_from_gltf': {
+            const parsed = z.object({ file: z.string(), name: z.string().optional() }).parse(args);
+            return jsonResult(
+              await scaffoldFromGltf({ file: parsed.file as string, name: parsed.name }),
+            );
+          }
+          case 'read_uniform': {
+            const parsed = z
+              .object({
+                element: z.string().optional(),
+                path: z.string(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await readUniform({
+                element: parsed.element,
+                path: parsed.path as string,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          case 'set_uniform': {
+            const parsed = z
+              .object({
+                element: z.string().optional(),
+                path: z.string(),
+                value: z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await setUniform({
+                element: parsed.element,
+                path: parsed.path as string,
+                value: parsed.value,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          case 'inspect_scene': {
+            const parsed = z
+              .object({
+                element: z.string().optional(),
+                maxNodes: z.number().int().min(1).max(5000).optional(),
+                labUrl: z.string().optional(),
+                fresh: z.boolean().optional(),
+              })
+              .parse(args);
+            return jsonResult(await inspectScene(parsed));
+          }
+          case 'inspect': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                camera: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(await inspect({ element: parsed.element, camera: parsed.camera }));
+          }
+          case 'open_selection': {
+            const parsed = z
+              .object({
+                editor: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(await openSelection(parsed));
+          }
+          case 'snapshot': {
+            const parsed = z
+              .object({
+                name: z.string(),
+                message: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(await snapshot({ name: parsed.name, message: parsed.message }));
+          }
+          case 'restore': {
+            const parsed = z.object({ name: z.string() }).parse(args);
+            return jsonResult(await restore({ name: parsed.name }));
+          }
+          case 'list_snapshots':
+            return jsonResult(await listSnapshots());
+          case 'auto_tune': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                knob: z.string(),
+                range: z.tuple([z.number(), z.number()]),
+                target_camera: z.string(),
+                max_iterations: z.number().int().min(2).max(50).optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await autoTune({
+                element: parsed.element,
+                knob: parsed.knob,
+                range: [parsed.range[0], parsed.range[1]],
+                target_camera: parsed.target_camera,
+                max_iterations: parsed.max_iterations,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          case 'multi_tune': {
+            const parsed = z
+              .object({
+                element: z.string(),
+                knobs: z
+                  .array(
+                    z.object({
+                      key: z.string(),
+                      range: z.tuple([z.number(), z.number()]),
+                      start: z.number().optional(),
+                    }),
+                  )
+                  .min(1),
+                target_camera: z.string(),
+                max_cycles: z.number().int().min(1).max(6).optional(),
+                per_knob_iters: z.number().int().min(2).max(20).optional(),
+                compute_interactions: z.boolean().optional(),
+                max_evaluations: z.number().int().min(2).max(300).optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await multiTune({
+                element: parsed.element as string,
+                knobs: (
+                  parsed.knobs as Array<{ key: string; range: [number, number]; start?: number }>
+                ).map((k) => ({
+                  key: k.key,
+                  range: [k.range[0], k.range[1]] as [number, number],
+                  start: k.start,
+                })),
+                target_camera: parsed.target_camera as string,
+                max_cycles: parsed.max_cycles,
+                per_knob_iters: parsed.per_knob_iters,
+                compute_interactions: parsed.compute_interactions,
+                max_evaluations: parsed.max_evaluations,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          case 'check_targets': {
+            const parsed = z
+              .object({ element: z.string(), labUrl: z.string().optional() })
+              .parse(args);
+            return jsonResult(
+              await checkTargets({ element: parsed.element as string, labUrl: parsed.labUrl }),
+            );
+          }
+          case 'set_scene_param': {
+            const parsed = z
+              .object({
+                cameras: z
+                  .record(
+                    z.object({
+                      position: z.array(z.number()).optional(),
+                      target: z.array(z.number()).optional(),
+                      fov: z.number().optional(),
+                    }),
+                  )
+                  .optional(),
+                knobs: z.record(z.union([z.number(), z.string(), z.boolean()])).optional(),
+                elements: z.record(z.object({ enabled: z.boolean().optional() })).optional(),
+              })
+              .parse(args);
+            return jsonResult(await setSceneParam(parsed));
+          }
+          case 'get_scene':
+            return jsonResult(
+              await getScene({
+                devUrl: args.devUrl as string | undefined,
+                labUrl: args.labUrl as string | undefined,
+              }),
+            );
+          case 'add_element': {
+            const parsed = z
+              .object({
+                name: z.string(),
+                element: z.string().optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await addElement({
+                name: parsed.name,
+                element: parsed.element,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          case 'remove_element': {
+            const parsed = z
+              .object({
+                name: z.string(),
+                element: z.string().optional(),
+                labUrl: z.string().optional(),
+              })
+              .parse(args);
+            return jsonResult(
+              await removeElement({
+                name: parsed.name,
+                element: parsed.element,
+                labUrl: parsed.labUrl,
+              }),
+            );
+          }
+          default:
+            return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+        }
+      })();
+      finish('succeeded');
+      return result;
+    } catch (err: any) {
+      finish('failed');
+      recordError(`tool:${name}`, err);
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `${name} failed: ${err?.message ?? String(err)}` }],
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // eslint-disable-next-line no-console
+  console.error(`[triscope-mcp] connected. dev server: ${DEV_URL}, project: ${PROJECT}`);
+}