@triscope/mcp 0.4.0

package/dist/server.mjs

@@ -0,0 +1,3125 @@
+// src/server.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir as tmpdir3 } from "os";
+import { join as join4 } from "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 as PNG2 } from "pngjs";
+import { z } from "zod";
+
+// src/browser.ts
+import { spawn } from "child_process";
+import { existsSync, readdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+var wait = (ms) => new Promise((r) => setTimeout(r, ms));
+var DEFAULT_CHROME_ARGS = [
+  "--enable-unsafe-webgpu",
+  "--ignore-gpu-blocklist",
+  // Suppress the first-run wizard and the default-browser banner: both
+  // can block the new window from rendering or trigger a different code
+  // path that ignores --remote-debugging-port until dismissed. Both have
+  // been seen to leave Chromium "running" but with no CDP endpoint open,
+  // which manifests as a "DevTools endpoint did not become ready" error.
+  "--no-first-run",
+  "--no-default-browser-check"
+];
+function parseExtraChromeArgs() {
+  const raw = process.env.TRISCOPE_CHROME_ARGS ?? "";
+  if (!raw.trim()) return [];
+  return raw.trim().split(/\s+/).filter(Boolean);
+}
+function tailLines(text, maxLines = 24) {
+  const lines = text.trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(-maxLines).join("\n");
+}
+async function readDevtoolsPages(port) {
+  try {
+    const pages = await fetch(`http://127.0.0.1:${port}/json`, {
+      signal: AbortSignal.timeout(1e3)
+    }).then((r) => r.json());
+    return Array.isArray(pages) && pages.length > 0 ? pages : null;
+  } catch {
+    return null;
+  }
+}
+function cdpClient(ws) {
+  const pending = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    if (msg.id && pending.has(msg.id)) {
+      pending.get(msg.id)(msg);
+      pending.delete(msg.id);
+    }
+  };
+  const drain = (reason) => {
+    for (const cb of pending.values()) cb({ error: { message: reason } });
+    pending.clear();
+  };
+  ws.onclose = (event) => drain(`CDP WebSocket closed (code ${event?.code ?? "?"}) before the response arrived`);
+  ws.onerror = (event) => drain(`CDP WebSocket error (${event?.message ?? "unknown"}) before the response arrived`);
+  const call = (method, params = {}) => new Promise((resolve2, reject) => {
+    const id = ++nextId;
+    ws.send(JSON.stringify({ id, method, params }));
+    const t = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`CDP timeout for ${method}`));
+    }, 2e4);
+    pending.set(id, (msg) => {
+      clearTimeout(t);
+      if (msg.error) reject(new Error(`${method}: ${msg.error.message}`));
+      else resolve2(msg);
+    });
+  });
+  return call;
+}
+function inferGraphicalEnv() {
+  if (process.platform !== "linux") return process.env;
+  const env = { ...process.env };
+  const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  const runtimeDir = env.XDG_RUNTIME_DIR || (uid !== void 0 ? `/run/user/${uid}` : void 0);
+  if (runtimeDir && existsSync(runtimeDir)) {
+    env.XDG_RUNTIME_DIR = runtimeDir;
+    if (!env.WAYLAND_DISPLAY) {
+      try {
+        const waylandSocket = readdirSync(runtimeDir).find((name) => /^wayland-\d+$/.test(name));
+        if (waylandSocket) env.WAYLAND_DISPLAY = waylandSocket;
+      } catch {
+      }
+    }
+  }
+  if (!env.DISPLAY && existsSync("/tmp/.X11-unix/X0")) env.DISPLAY = ":0";
+  return env;
+}
+function defaultChromeBinary() {
+  if (process.platform === "win32") {
+    return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+  }
+  if (process.platform === "darwin") {
+    return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  }
+  return "chromium";
+}
+function createBrowserPool({
+  chromeBin = process.env.CHROME_BIN ?? process.env.PUPPETEER_EXECUTABLE_PATH ?? defaultChromeBinary(),
+  port = Number(process.env.TRISCOPE_DEBUG_PORT ?? 9230),
+  logger: logger2 = void 0
+} = {}) {
+  let chrome = null;
+  let chromeExit = null;
+  let chromeStderr = "";
+  let ws = null;
+  let call = null;
+  let currentUrl = null;
+  let lastWarmUrl = null;
+  async function connectToPage(initialUrl, pages) {
+    const page = pages.find((p) => p.url === initialUrl || p.url?.startsWith(initialUrl)) ?? pages[0];
+    ws = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      ws.onopen = res;
+      ws.onerror = (e) => rej(new Error(`ws error: ${e?.message ?? "unknown"}`));
+    });
+    call = cdpClient(ws);
+    await call("Runtime.enable");
+    await call("Page.enable");
+    currentUrl = page.url ?? initialUrl;
+    if (currentUrl !== initialUrl) await navigateIfNeeded(initialUrl);
+  }
+  function chromeLaunchArgs(profile, initialUrl) {
+    return [
+      ...DEFAULT_CHROME_ARGS,
+      ...parseExtraChromeArgs(),
+      `--user-data-dir=${profile}`,
+      `--remote-debugging-port=${port}`,
+      "--window-size=1600,900",
+      initialUrl
+    ];
+  }
+  async function ensureBrowser(initialUrl) {
+    if (chrome && !chrome.killed && ws && ws.readyState === 1) return;
+    const existingPages = await readDevtoolsPages(port);
+    if (existingPages) {
+      logger2?.info("browser", "attaching to existing DevTools endpoint", {
+        port,
+        pages: existingPages.length
+      });
+      await connectToPage(initialUrl, existingPages);
+      return;
+    }
+    const profile = join(
+      tmpdir(),
+      `triscope-mcp-profile-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    );
+    const args = chromeLaunchArgs(profile, initialUrl);
+    chromeExit = null;
+    chromeStderr = "";
+    const browserEnv = inferGraphicalEnv();
+    logger2?.info("browser", "spawning chromium", {
+      chromeBin,
+      port,
+      profile,
+      args,
+      env: {
+        DISPLAY: browserEnv.DISPLAY,
+        WAYLAND_DISPLAY: browserEnv.WAYLAND_DISPLAY,
+        XDG_RUNTIME_DIR: browserEnv.XDG_RUNTIME_DIR
+      }
+    });
+    chrome = spawn(chromeBin, args, { stdio: ["ignore", "ignore", "pipe"], env: browserEnv });
+    chrome.stderr.on("data", (d) => {
+      chromeStderr += String(d);
+      if (chromeStderr.length > 12e3) chromeStderr = chromeStderr.slice(-12e3);
+    });
+    chrome.on("exit", (code, signal) => {
+      chromeExit = { code, signal };
+      logger2?.warn("browser", "chromium exited", { code, signal, stderr: tailLines(chromeStderr) });
+    });
+    chrome.on("error", (err) => {
+      chromeExit = { code: 1, signal: null };
+      chromeStderr += `
+spawn error: ${err?.message ?? String(err)}`;
+      logger2?.error("browser", "chromium spawn error", {
+        message: err?.message ?? String(err)
+      });
+    });
+    let pages = null;
+    const start = Date.now();
+    while (Date.now() - start < 1e4) {
+      pages = await readDevtoolsPages(port);
+      if (pages) break;
+      if (chromeExit) break;
+      await wait(250);
+    }
+    if (!pages) {
+      const stderr = tailLines(chromeStderr);
+      const exit = chromeExit ? ` chromiumExit=${JSON.stringify(chromeExit)}` : "";
+      const silentExit = !chromeExit && !pages;
+      const hint = silentExit ? "Chromium process is alive but DevTools never opened \u2014 usually the host sandbox is blocking the bind on TRISCOPE_DEBUG_PORT, or another Chromium instance is reusing the same profile dir. Workarounds: (1) pre-launch Chrome yourself with --remote-debugging-port=" + port + " --enable-unsafe-webgpu \u2014 the MCP server auto-attaches to an existing endpoint when present; (2) set TRISCOPE_DEBUG_PORT to a port the sandbox permits." : "If this runs under Codex/Claude and headed launch still fails, pre-launch Chrome with --remote-debugging-port=" + port + " or set TRISCOPE_CHROME_ARGS=--headless=new for non-interactive capture.";
+      throw new Error(
+        `DevTools endpoint did not become ready on 127.0.0.1:${port}.${exit}${stderr ? `
+stderr:
+${stderr}` : ""}
+${hint}`
+      );
+    }
+    await connectToPage(initialUrl, pages);
+  }
+  function harnessNotMountedError(url) {
+    return new Error(
+      `window.__TRISCOPE__ did not mount within 10s on ${url}. Common causes: (1) the page never loaded \u2014 confirm the dev server is up and the URL is right (open it in a real browser tab); (2) WebGPU init failed \u2014 Linux Chrome needs --enable-unsafe-webgpu and either xvfb or a real display; (3) runLab() threw before mounting \u2014 check the #boot overlay text or the page console; (4) the lab page doesn't call runLab() at all \u2014 verify its entry script imports @triscope/core.`
+    );
+  }
+  async function mountErrorOrTimeout(url) {
+    try {
+      const r = await call("Runtime.evaluate", {
+        expression: "JSON.stringify(window.__TRISCOPE_MOUNT_ERROR__ ?? null)",
+        returnByValue: true
+      });
+      const me = JSON.parse(r.result.result.value);
+      if (me?.message) {
+        const probs = me.problems?.length ? `
+Contract problems:
+ - ${me.problems.join("\n - ")}` : "";
+        return new Error(`element "${me.element ?? "?"}" failed to mount: ${me.message}${probs}`);
+      }
+    } catch {
+    }
+    return harnessNotMountedError(url);
+  }
+  async function navigateIfNeeded(url) {
+    if (url === currentUrl) return;
+    await call("Page.navigate", { url });
+    lastWarmUrl = null;
+    const start = Date.now();
+    while (Date.now() - start < 1e4) {
+      try {
+        const probe = await call("Runtime.evaluate", {
+          expression: '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === "function")',
+          returnByValue: true
+        });
+        if (probe.result.result.value) {
+          currentUrl = url;
+          return;
+        }
+      } catch {
+      }
+      await wait(200);
+    }
+    throw await mountErrorOrTimeout(url);
+  }
+  async function waitForHarness() {
+    for (let i = 0; i < 40; i++) {
+      try {
+        const probe = await call("Runtime.evaluate", {
+          expression: '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === "function")',
+          returnByValue: true
+        });
+        if (probe.result.result.value) return;
+      } catch {
+      }
+      await wait(250);
+    }
+    throw await mountErrorOrTimeout(currentUrl ?? "(initial page)");
+  }
+  async function waitForWarmFrame() {
+    if (currentUrl && currentUrl === lastWarmUrl) return;
+    for (let i = 0; i < 20; i++) {
+      try {
+        const probe = await call("Runtime.evaluate", {
+          expression: '(function(){var t=window.__TRISCOPE__;if(!t)return 0;if(typeof t.framesRendered==="function")return t.framesRendered();try{return (t.sampleTelemetry&&t.sampleTelemetry().perf&&t.sampleTelemetry().perf.fps>0)?2:0;}catch(e){return 0;}})()',
+          returnByValue: true
+        });
+        if ((probe.result.result.value ?? 0) >= 2) {
+          lastWarmUrl = currentUrl;
+          return;
+        }
+      } catch {
+      }
+      await wait(100);
+    }
+    lastWarmUrl = currentUrl;
+  }
+  async function isAlive() {
+    if (!chrome || chrome.killed || !ws || ws.readyState !== 1) return false;
+    try {
+      await Promise.race([
+        call("Runtime.evaluate", { expression: "1", returnByValue: true }),
+        new Promise((_, rej) => setTimeout(() => rej(new Error("alive probe timeout")), 1500))
+      ]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function disposeQuiet() {
+    try {
+      ws?.close();
+    } catch {
+    }
+    try {
+      if (chrome && !chrome.killed) chrome.kill();
+    } catch {
+    }
+    ws = null;
+    chrome = null;
+    call = null;
+    currentUrl = null;
+    lastWarmUrl = null;
+    chromeExit = null;
+    chromeStderr = "";
+  }
+  return {
+    /** Lazy-spawn Chromium (first call) or reuse it (subsequent). Always
+     *  guarantees the page is sitting on `url` with the harness mounted.
+     *  Self-heals: if the previous Chromium died externally (manual kill,
+     *  crash) the next call disposes the stale state and respawns. */
+    async getPage(url, opts = {}) {
+      const reload = opts?.reload === true;
+      if (chrome && !await isAlive()) {
+        disposeQuiet();
+      }
+      if (!chrome) {
+        await ensureBrowser(url);
+        await waitForHarness();
+        lastWarmUrl = null;
+      } else if (reload && url === currentUrl) {
+        try {
+          await call("Runtime.evaluate", {
+            expression: "try { window.__TRISCOPE__ = undefined; } catch (e) {}",
+            returnByValue: true
+          });
+        } catch {
+        }
+        lastWarmUrl = null;
+        await call("Page.reload", { ignoreCache: true });
+        await waitForHarness();
+      } else {
+        await navigateIfNeeded(url);
+      }
+      await waitForWarmFrame();
+      return { call };
+    },
+    /** Synchronous teardown. Safe to call multiple times. */
+    dispose() {
+      disposeQuiet();
+    }
+  };
+}
+
+// src/logger.ts
+import { appendFileSync, existsSync as existsSync2, renameSync, statSync, unlinkSync } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join2 } from "path";
+var MAX_LOG_BYTES = 1024 * 1024;
+function createLogger(project) {
+  const logPath = join2(tmpdir2(), `${project}-mcp.log`);
+  function rotateIfNeeded() {
+    try {
+      if (!existsSync2(logPath)) return;
+      const size = statSync(logPath).size;
+      if (size < MAX_LOG_BYTES) return;
+      const rolled = `${logPath}.1`;
+      if (existsSync2(rolled)) {
+        try {
+          unlinkSync(rolled);
+        } catch {
+        }
+      }
+      renameSync(logPath, rolled);
+    } catch {
+    }
+  }
+  function write(entry) {
+    const tag = `[triscope-mcp:${entry.level}:${entry.scope}]`;
+    if (entry.level === "error" || entry.level === "warn") {
+      console.error(tag, entry.msg, entry.meta ?? "");
+    } else if (process.env.TRISCOPE_MCP_DEBUG) {
+      console.error(tag, entry.msg, entry.meta ?? "");
+    }
+    try {
+      rotateIfNeeded();
+      appendFileSync(logPath, JSON.stringify(entry) + "\n");
+    } catch {
+    }
+  }
+  function make(level) {
+    return (scope, msg, meta) => write({ ts: (/* @__PURE__ */ new Date()).toISOString(), level, scope, msg, meta });
+  }
+  return {
+    info: make("info"),
+    warn: make("warn"),
+    error: make("error"),
+    debug: make("debug"),
+    logPath
+  };
+}
+
+// src/optimize.ts
+var PHI = (1 + Math.sqrt(5)) / 2;
+var INV_PHI = 1 / PHI;
+async function goldenSectionMax(f, a, b, maxIter = 12, tol = 1e-4) {
+  const history = [];
+  const cache = /* @__PURE__ */ new Map();
+  let budget = maxIter;
+  const evalAt = async (x) => {
+    const k = x.toFixed(6);
+    const hit = cache.get(k);
+    if (hit !== void 0) return hit;
+    if (budget <= 0) return Number.NEGATIVE_INFINITY;
+    budget--;
+    const fx = await f(x);
+    cache.set(k, fx);
+    history.push({ x, fx });
+    return fx;
+  };
+  let lo = a;
+  let hi = b;
+  let c = hi - (hi - lo) * INV_PHI;
+  let d = lo + (hi - lo) * INV_PHI;
+  let fc = await evalAt(c);
+  let fd = await evalAt(d);
+  while (budget > 0 && Math.abs(hi - lo) > tol * (b - a)) {
+    if (fc > fd) {
+      hi = d;
+      d = c;
+      fd = fc;
+      c = hi - (hi - lo) * INV_PHI;
+      fc = await evalAt(c);
+    } else {
+      lo = c;
+      c = d;
+      fc = fd;
+      d = lo + (hi - lo) * INV_PHI;
+      fd = await evalAt(d);
+    }
+  }
+  let best = history[0] ?? { x: (a + b) / 2, fx: Number.NEGATIVE_INFINITY };
+  for (const h of history) if (h.fx > best.fx) best = h;
+  return { x: best.x, fx: best.fx, history };
+}
+async function coordinateDescent(opts) {
+  const { knobs, evalAt } = opts;
+  const maxCycles = opts.maxCycles ?? 3;
+  const perKnobIters = opts.perKnobIters ?? 12;
+  const maxEvaluations = opts.maxEvaluations ?? Number.POSITIVE_INFINITY;
+  const tol = opts.tol ?? 1e-3;
+  const current = {};
+  for (const k of knobs) current[k.key] = k.start;
+  const history = [];
+  let evaluations = 0;
+  let bestScore = await evalAt({ ...current });
+  evaluations++;
+  let cycles = 0;
+  for (let cycle = 0; cycle < maxCycles; cycle++) {
+    cycles = cycle + 1;
+    const cycleStart = bestScore;
+    for (const k of knobs) {
+      if (evaluations >= maxEvaluations)
+        return { best: current, bestScore, cycles, evaluations, history };
+      const f = async (x) => {
+        if (evaluations >= maxEvaluations) return Number.NEGATIVE_INFINITY;
+        evaluations++;
+        const score = await evalAt({ ...current, [k.key]: x });
+        history.push({ cycle, knob: k.key, value: x, score });
+        return score;
+      };
+      const r = await goldenSectionMax(f, k.min, k.max, perKnobIters);
+      if (r.fx >= bestScore) {
+        current[k.key] = r.x;
+        bestScore = r.fx;
+      }
+    }
+    if (bestScore - cycleStart < tol) break;
+  }
+  return { best: current, bestScore, cycles, evaluations, history };
+}
+function knobMatches(requested, applied, tol = 1e-4) {
+  if (typeof requested === "number" && typeof applied === "number") {
+    return Math.abs(requested - applied) <= tol;
+  }
+  if (typeof requested === "string" && typeof applied === "string") {
+    return requested.toLowerCase() === applied.toLowerCase();
+  }
+  return requested === applied;
+}
+
+// src/refs.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join as join3, resolve } from "path";
+import { PNG } from "pngjs";
+var stripPrefix = (s) => s.replace(/^data:image\/png;base64,/, "");
+function refsRoot(cwd) {
+  return resolve(cwd, "refs");
+}
+function refsPath(cwd, element, camera) {
+  const safeCam = String(camera).replace(/[^A-Za-z0-9._-]/g, "_");
+  return join3(refsRoot(cwd), element, `${safeCam}.png`);
+}
+function refsMotionPaths(cwd, element, camera) {
+  const safeCam = String(camera).replace(/[^A-Za-z0-9._-]/g, "_");
+  const base = join3(refsRoot(cwd), element);
+  return {
+    filmstrip: join3(base, `${safeCam}.motion.png`),
+    meta: join3(base, `${safeCam}.motion.json`)
+  };
+}
+function setReference({
+  cwd,
+  element,
+  camera,
+  path,
+  base64
+}) {
+  if (!element || !camera) throw new Error("element and camera are required");
+  let bytes;
+  if (path) {
+    if (!existsSync3(path)) throw new Error(`reference file not found: ${path}`);
+    bytes = readFileSync(path);
+  } else if (base64) {
+    bytes = Buffer.from(stripPrefix(base64), "base64");
+  } else {
+    throw new Error("provide either path or base64");
+  }
+  const dest = refsPath(cwd, element, camera);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, bytes);
+  return { path: dest, bytes: bytes.length };
+}
+function decodePng(buffer) {
+  return PNG.sync.read(buffer);
+}
+function nearestNeighborResize(src, targetW, targetH) {
+  if (src.width === targetW && src.height === targetH) return src;
+  const dst = new PNG({ width: targetW, height: targetH });
+  for (let y = 0; y < targetH; y++) {
+    const sy = Math.min(src.height - 1, Math.floor(y * src.height / targetH));
+    for (let x = 0; x < targetW; x++) {
+      const sx = Math.min(src.width - 1, Math.floor(x * src.width / targetW));
+      const si = (sy * src.width + sx) * 4;
+      const di = (y * targetW + x) * 4;
+      dst.data[di] = src.data[si];
+      dst.data[di + 1] = src.data[si + 1];
+      dst.data[di + 2] = src.data[si + 2];
+      dst.data[di + 3] = 255;
+    }
+  }
+  return dst;
+}
+function composeSideBySide(left, right) {
+  const h = Math.min(left.height, right.height);
+  const sep = 4;
+  const lw = Math.round(left.width * h / left.height);
+  const rw = Math.round(right.width * h / right.height);
+  const w = lw + sep + rw;
+  const L = nearestNeighborResize(left, lw, h);
+  const R = nearestNeighborResize(right, rw, h);
+  const out = new PNG({ width: w, height: h });
+  for (let i = 0; i < out.data.length; i += 4) out.data[i + 3] = 255;
+  for (let y = 0; y < h; y++) {
+    const orow = y * w * 4;
+    const lrow = y * lw * 4;
+    const rrow = y * rw * 4;
+    L.data.copy(out.data, orow, lrow, lrow + lw * 4);
+    R.data.copy(out.data, orow + (lw + sep) * 4, rrow, rrow + rw * 4);
+  }
+  return out;
+}
+function meanAbsDiff(a, b) {
+  const W = 256;
+  const H = 256;
+  const A = nearestNeighborResize(a, W, H);
+  const B = nearestNeighborResize(b, W, H);
+  let sum = 0;
+  const pixels = W * H * 3;
+  for (let i = 0; i < W * H; i++) {
+    const j = i * 4;
+    sum += Math.abs(A.data[j] - B.data[j]);
+    sum += Math.abs(A.data[j + 1] - B.data[j + 1]);
+    sum += Math.abs(A.data[j + 2] - B.data[j + 2]);
+  }
+  return +(sum / pixels).toFixed(2);
+}
+function ssim(a, b) {
+  const W = 256;
+  const H = 256;
+  const A = nearestNeighborResize(a, W, H);
+  const B = nearestNeighborResize(b, W, H);
+  const lumA = new Float32Array(W * H);
+  const lumB = new Float32Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const j = i * 4;
+    lumA[i] = 0.2126 * A.data[j] + 0.7152 * A.data[j + 1] + 0.0722 * A.data[j + 2];
+    lumB[i] = 0.2126 * B.data[j] + 0.7152 * B.data[j + 1] + 0.0722 * B.data[j + 2];
+  }
+  const L = 255;
+  const C1 = (0.01 * L) ** 2;
+  const C2 = (0.03 * L) ** 2;
+  const WIN = 8;
+  let total = 0;
+  let count = 0;
+  for (let wy = 0; wy < H; wy += WIN) {
+    for (let wx = 0; wx < W; wx += WIN) {
+      let muA = 0, muB = 0;
+      for (let dy = 0; dy < WIN; dy++)
+        for (let dx = 0; dx < WIN; dx++) {
+          const i = (wy + dy) * W + (wx + dx);
+          muA += lumA[i];
+          muB += lumB[i];
+        }
+      muA /= WIN * WIN;
+      muB /= WIN * WIN;
+      let varA = 0, varB = 0, covAB = 0;
+      for (let dy = 0; dy < WIN; dy++)
+        for (let dx = 0; dx < WIN; dx++) {
+          const i = (wy + dy) * W + (wx + dx);
+          const da = lumA[i] - muA;
+          const db = lumB[i] - muB;
+          varA += da * da;
+          varB += db * db;
+          covAB += da * db;
+        }
+      varA /= WIN * WIN - 1;
+      varB /= WIN * WIN - 1;
+      covAB /= WIN * WIN - 1;
+      const num = (2 * muA * muB + C1) * (2 * covAB + C2);
+      const den = (muA * muA + muB * muB + C1) * (varA + varB + C2);
+      total += num / den;
+      count += 1;
+    }
+  }
+  return +(total / count).toFixed(4);
+}
+function ssimTileGrid(a, b, gridSize = 8) {
+  const W = 256;
+  const H = 256;
+  const A = nearestNeighborResize(a, W, H);
+  const B = nearestNeighborResize(b, W, H);
+  const lumA = new Float32Array(W * H);
+  const lumB = new Float32Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const j = i * 4;
+    lumA[i] = 0.2126 * A.data[j] + 0.7152 * A.data[j + 1] + 0.0722 * A.data[j + 2];
+    lumB[i] = 0.2126 * B.data[j] + 0.7152 * B.data[j + 1] + 0.0722 * B.data[j + 2];
+  }
+  const L = 255;
+  const C1 = (0.01 * L) ** 2;
+  const C2 = (0.03 * L) ** 2;
+  const tile = Math.floor(W / gridSize);
+  const grid = [];
+  let worst = { row: 0, col: 0, ssim: Number.POSITIVE_INFINITY };
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  let sum = 0;
+  let count = 0;
+  for (let r = 0; r < gridSize; r++) {
+    const rowArr = [];
+    for (let c = 0; c < gridSize; c++) {
+      const x0 = c * tile;
+      const y0 = r * tile;
+      const n = tile * tile;
+      let muA = 0;
+      let muB = 0;
+      for (let dy = 0; dy < tile; dy++)
+        for (let dx = 0; dx < tile; dx++) {
+          const i = (y0 + dy) * W + (x0 + dx);
+          muA += lumA[i];
+          muB += lumB[i];
+        }
+      muA /= n;
+      muB /= n;
+      let vA = 0;
+      let vB = 0;
+      let cov = 0;
+      for (let dy = 0; dy < tile; dy++)
+        for (let dx = 0; dx < tile; dx++) {
+          const i = (y0 + dy) * W + (x0 + dx);
+          const da = lumA[i] - muA;
+          const db = lumB[i] - muB;
+          vA += da * da;
+          vB += db * db;
+          cov += da * db;
+        }
+      vA /= n - 1;
+      vB /= n - 1;
+      cov /= n - 1;
+      const s = (2 * muA * muB + C1) * (2 * cov + C2) / ((muA * muA + muB * muB + C1) * (vA + vB + C2));
+      const sr = +s.toFixed(4);
+      rowArr.push(sr);
+      sum += sr;
+      count += 1;
+      if (sr < min) min = sr;
+      if (sr > max) max = sr;
+      if (sr < worst.ssim) worst = { row: r, col: c, ssim: sr };
+    }
+    grid.push(rowArr);
+  }
+  return {
+    grid,
+    worst,
+    min: +min.toFixed(4),
+    max: +max.toFixed(4),
+    mean: +(sum / count).toFixed(4),
+    gridSize
+  };
+}
+function heatColor(t) {
+  const x = Math.max(0, Math.min(1, t));
+  const stops = [
+    [0, [0, 0, 0]],
+    [0.33, [0, 0, 255]],
+    [0.66, [255, 255, 0]],
+    [1, [255, 0, 0]]
+  ];
+  for (let i = 1; i < stops.length; i++) {
+    if (x <= stops[i][0]) {
+      const [t0, c0] = stops[i - 1];
+      const [t1, c1] = stops[i];
+      const f = (x - t0) / (t1 - t0 || 1);
+      return [
+        Math.round(c0[0] + f * (c1[0] - c0[0])),
+        Math.round(c0[1] + f * (c1[1] - c0[1])),
+        Math.round(c0[2] + f * (c1[2] - c0[2]))
+      ];
+    }
+  }
+  return [255, 0, 0];
+}
+function composeDiffHeatmap(a, b, size = 256) {
+  const A = nearestNeighborResize(a, size, size);
+  const B = nearestNeighborResize(b, size, size);
+  const out = new PNG({ width: size, height: size });
+  for (let p = 0; p < size * size; p++) {
+    const j = p * 4;
+    const d = (Math.abs(A.data[j] - B.data[j]) + Math.abs(A.data[j + 1] - B.data[j + 1]) + Math.abs(A.data[j + 2] - B.data[j + 2])) / (3 * 255);
+    const [r, g, bl] = heatColor(d);
+    out.data[j] = r;
+    out.data[j + 1] = g;
+    out.data[j + 2] = bl;
+    out.data[j + 3] = 255;
+  }
+  return PNG.sync.write(out);
+}
+function composeFilmstrip(frameBase64s, opts = {}) {
+  if (!Array.isArray(frameBase64s) || frameBase64s.length === 0) {
+    throw new Error("composeFilmstrip: no frames");
+  }
+  const sep = opts.sep ?? 2;
+  const frames = frameBase64s.map((b) => decodePng(Buffer.from(stripPrefix(b), "base64")));
+  const h = Math.min(...frames.map((f) => f.height));
+  const resized = frames.map(
+    (f) => nearestNeighborResize(f, Math.round(f.width * h / f.height), h)
+  );
+  const totalW = resized.reduce((acc, f, i) => acc + f.width + (i > 0 ? sep : 0), 0);
+  const out = new PNG({ width: totalW, height: h });
+  for (let i = 0; i < out.data.length; i += 4) out.data[i + 3] = 255;
+  let x = 0;
+  for (let f = 0; f < resized.length; f++) {
+    const img = resized[f];
+    for (let y = 0; y < h; y++) {
+      const srcRow = y * img.width * 4;
+      const dstRow = (y * totalW + x) * 4;
+      img.data.copy(out.data, dstRow, srcRow, srcRow + img.width * 4);
+    }
+    x += img.width + sep;
+  }
+  return PNG.sync.write(out);
+}
+function motionMagnitudeFromFrames(frameBase64s) {
+  if (!Array.isArray(frameBase64s) || frameBase64s.length < 2) return 0;
+  const decoded = frameBase64s.map((b) => decodePng(Buffer.from(stripPrefix(b), "base64")));
+  let total = 0;
+  for (let i = 1; i < decoded.length; i++) {
+    total += meanAbsDiff(decoded[i - 1], decoded[i]);
+  }
+  return +(total / (decoded.length - 1)).toFixed(2);
+}
+function setReferenceMotion({ cwd, element, camera, frameBase64s, meta }) {
+  if (!Array.isArray(frameBase64s) || frameBase64s.length < 2) {
+    throw new Error("setReferenceMotion: need at least 2 frames");
+  }
+  const filmstrip = composeFilmstrip(frameBase64s);
+  const { filmstrip: fpath, meta: mpath } = refsMotionPaths(cwd, element, camera);
+  mkdirSync(dirname(fpath), { recursive: true });
+  writeFileSync(fpath, filmstrip);
+  writeFileSync(
+    mpath,
+    JSON.stringify(
+      {
+        frames: frameBase64s.length,
+        ...meta,
+        savedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )
+  );
+  return { filmstripPath: fpath, metaPath: mpath, frames: frameBase64s.length };
+}
+function diffReferenceMotion({ cwd, element, camera, currentFrames }) {
+  const { filmstrip: fpath, meta: mpath } = refsMotionPaths(cwd, element, camera);
+  if (!existsSync3(fpath)) {
+    throw new Error(`no motion reference at ${fpath} \u2014 call set_reference_motion first`);
+  }
+  if (!Array.isArray(currentFrames) || currentFrames.length === 0) {
+    throw new Error("currentFrames must be a non-empty array of base64 PNGs");
+  }
+  const refFilmstrip = decodePng(readFileSync(fpath));
+  const curFilmstrip = decodePng(composeFilmstrip(currentFrames));
+  const h = Math.min(refFilmstrip.height, curFilmstrip.height);
+  const lw = Math.round(refFilmstrip.width * h / refFilmstrip.height);
+  const rw = Math.round(curFilmstrip.width * h / curFilmstrip.height);
+  const w = Math.max(lw, rw);
+  const sep = 4;
+  const composite = new PNG({ width: w, height: h * 2 + sep });
+  for (let i = 0; i < composite.data.length; i += 4) composite.data[i + 3] = 255;
+  const refResized = nearestNeighborResize(refFilmstrip, w, h);
+  const curResized = nearestNeighborResize(curFilmstrip, w, h);
+  for (let y = 0; y < h; y++) {
+    refResized.data.copy(composite.data, y * w * 4, y * w * 4, (y + 1) * w * 4);
+    curResized.data.copy(composite.data, (y + h + sep) * w * 4, y * w * 4, (y + 1) * w * 4);
+  }
+  let meta = null;
+  try {
+    meta = existsSync3(mpath) ? JSON.parse(readFileSync(mpath, "utf8")) : null;
+  } catch {
+  }
+  const motionDiff = meanAbsDiff(refFilmstrip, curFilmstrip);
+  return {
+    refFilmstripPath: fpath,
+    refMeta: meta,
+    motionDiff,
+    compositeBase64: PNG.sync.write(composite).toString("base64")
+  };
+}
+function diffReference({ cwd, element, camera, currentBase64 }) {
+  const refPath = refsPath(cwd, element, camera);
+  if (!existsSync3(refPath)) {
+    throw new Error(`no reference at ${refPath} \u2014 call set_reference first`);
+  }
+  if (!currentBase64) throw new Error("currentBase64 is required");
+  const refPng = decodePng(readFileSync(refPath));
+  const curPng = decodePng(Buffer.from(stripPrefix(currentBase64), "base64"));
+  const composite = composeSideBySide(refPng, curPng);
+  const compositeBuf = PNG.sync.write(composite);
+  const meanAbs = meanAbsDiff(refPng, curPng);
+  const ssimScore = ssim(refPng, curPng);
+  const tiles = ssimTileGrid(refPng, curPng);
+  const heatmap = composeDiffHeatmap(refPng, curPng);
+  return {
+    camera,
+    refPath,
+    meanAbsDiff: meanAbs,
+    // 0 = identical, 255 = max difference
+    ssim: ssimScore,
+    // 1 = identical, lower = more different
+    // Spatial localization: 8×8 SSIM map + the single worst tile, so the agent
+    // knows WHERE the divergence is without re-reading the composite image.
+    tileGrid: tiles.grid,
+    worstTile: tiles.worst,
+    tileStats: { min: tiles.min, max: tiles.max, mean: tiles.mean },
+    compositeBase64: compositeBuf.toString("base64"),
+    heatmapBase64: heatmap.toString("base64")
+  };
+}
+
+// src/targets.ts
+function evaluateTargets(targetsByCamera, capturedByCamera) {
+  const results = [];
+  for (const [camera, c] of Object.entries(targetsByCamera ?? {})) {
+    const cap = capturedByCamera?.[camera];
+    if (!cap) {
+      results.push({
+        camera,
+        constraint: "capture",
+        op: "present",
+        expected: "captured view",
+        actual: void 0,
+        pass: false,
+        skipped: true,
+        reason: "camera not captured"
+      });
+      continue;
+    }
+    if (typeof c.ssim === "number") {
+      if (typeof cap.ssim === "number") {
+        results.push({
+          camera,
+          constraint: "ssim",
+          op: ">=",
+          expected: c.ssim,
+          actual: cap.ssim,
+          pass: cap.ssim >= c.ssim
+        });
+      } else {
+        results.push({
+          camera,
+          constraint: "ssim",
+          op: ">=",
+          expected: c.ssim,
+          actual: void 0,
+          pass: true,
+          skipped: true,
+          reason: "no reference image \u2014 set_reference to enable"
+        });
+      }
+    }
+    if (typeof c.meanAbsDiff === "number") {
+      if (typeof cap.meanAbsDiff === "number") {
+        results.push({
+          camera,
+          constraint: "meanAbsDiff",
+          op: "<=",
+          expected: c.meanAbsDiff,
+          actual: cap.meanAbsDiff,
+          pass: cap.meanAbsDiff <= c.meanAbsDiff
+        });
+      } else {
+        results.push({
+          camera,
+          constraint: "meanAbsDiff",
+          op: "<=",
+          expected: c.meanAbsDiff,
+          actual: void 0,
+          pass: true,
+          skipped: true,
+          reason: "no reference image \u2014 set_reference to enable"
+        });
+      }
+    }
+    pushBand(results, camera, "luminance", c.luminance, cap.luminance);
+    pushBand(results, camera, "dynamicRange", c.dynamicRange, cap.dynamicRange);
+  }
+  const evaluated = results.filter((r) => !r.skipped);
+  const passed = evaluated.filter((r) => r.pass).length;
+  return {
+    checked: evaluated.length,
+    passed,
+    allPassed: evaluated.every((r) => r.pass),
+    results
+  };
+}
+function pushBand(out, camera, constraint, band, actual) {
+  if (!band) return;
+  if (typeof actual !== "number") {
+    out.push({
+      camera,
+      constraint,
+      op: "range",
+      expected: band,
+      actual: void 0,
+      pass: true,
+      skipped: true,
+      reason: "probe unavailable"
+    });
+    return;
+  }
+  if (typeof band.min === "number") {
+    out.push({
+      camera,
+      constraint: `${constraint}.min`,
+      op: ">=",
+      expected: band.min,
+      actual,
+      pass: actual >= band.min
+    });
+  }
+  if (typeof band.max === "number") {
+    out.push({
+      camera,
+      constraint: `${constraint}.max`,
+      op: "<=",
+      expected: band.max,
+      actual,
+      pass: actual <= band.max
+    });
+  }
+}
+
+// src/server.ts
+var wait2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function readProjectName(cwd) {
+  if (process.env.TRISCOPE_PROJECT) return process.env.TRISCOPE_PROJECT;
+  try {
+    const p = join4(cwd, "package.json");
+    if (!existsSync4(p)) return "triscope-project";
+    const pkg = JSON.parse(readFileSync2(p, "utf8"));
+    return String(pkg.name ?? "triscope-project").replace(/[^A-Za-z0-9._-]/g, "-");
+  } catch {
+    return "triscope-project";
+  }
+}
+var DEV_URL = (process.env.TRISCOPE_URL ?? "http://localhost:5173").replace(/\/$/, "");
+var PROJECT = readProjectName(process.cwd());
+var STATE_PATH = join4(tmpdir3(), `${PROJECT}-state.json`);
+var INLINE_PAYLOAD_BUDGET = Number(process.env.TRISCOPE_INLINE_PAYLOAD_BUDGET ?? 1024 * 1024);
+var SERVER_START_TIME = Date.now();
+var RECENT_ERRORS_CAP = 16;
+var recentErrors = [];
+var logger = createLogger(PROJECT);
+var browserPool = createBrowserPool({ logger });
+var shutdown = () => browserPool.dispose();
+process.on("exit", shutdown);
+process.on("SIGINT", () => {
+  shutdown();
+  process.exit(130);
+});
+process.on("SIGTERM", () => {
+  shutdown();
+  process.exit(143);
+});
+function recordError(source, err) {
+  const detail = err?.stack ?? err?.message ?? String(err);
+  const msg = `[${(/* @__PURE__ */ new Date()).toISOString()}] ${source}: ${detail}`;
+  logger.error(source, String(err?.message ?? err), { stack: err?.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));
+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 void 0;
+    cur = cur[s];
+  }
+  return cur;
+}
+async function fetchManifest(devUrl = DEV_URL) {
+  try {
+    const r = await fetch(`${devUrl}/__manifest`);
+    if (!r.ok) return null;
+    const m = await r.json();
+    return m && typeof m === "object" ? m : null;
+  } catch {
+    return null;
+  }
+}
+var _manifestCache = /* @__PURE__ */ new Map();
+async function fetchManifestCached(devUrl = DEV_URL, ttlMs = 1e3) {
+  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;
+}
+function resolveDevUrl({ devUrl, labUrl }) {
+  if (devUrl) return devUrl.replace(/\/$/, "");
+  if (labUrl) {
+    try {
+      return new URL(labUrl).origin;
+    } catch {
+    }
+  }
+  return DEV_URL;
+}
+async function fetchState(devUrl) {
+  try {
+    const r = await fetch(`${devUrl}/__state`, { signal: AbortSignal.timeout(2e3) });
+    if (!r.ok) return null;
+    const data = await r.json();
+    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;
+  }
+}
+var STALE_MS = Number(process.env.TRISCOPE_STALE_MS ?? 1500);
+function clampKnobValue(spec, value) {
+  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 };
+  }
+}
+function knobSpecMapFromManifest(manifest) {
+  const out = {};
+  for (const [el, entry] of Object.entries(manifest?.elements ?? {})) {
+    const byKey = {};
+    for (const k of entry?.knobs ?? []) {
+      if (!k?.name) continue;
+      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;
+}
+function readProjectLabMap(cwd) {
+  try {
+    const p = join4(cwd, "package.json");
+    if (!existsSync4(p)) return {};
+    const pkg = JSON.parse(readFileSync2(p, "utf8"));
+    const m = pkg?.triscope?.labs;
+    return m && typeof m === "object" ? m : {};
+  } catch {
+    return {};
+  }
+}
+var PROJECT_LABS = readProjectLabMap(process.cwd());
+function absolutize(maybePath, base = DEV_URL) {
+  if (!maybePath) return null;
+  if (/^https?:\/\//.test(maybePath)) return maybePath;
+  return `${base}${maybePath.startsWith("/") ? "" : "/"}${maybePath}`;
+}
+async function resolveLabUrl({
+  element,
+  labUrl,
+  devUrl
+}) {
+  if (labUrl) return absolutize(labUrl);
+  const base = resolveDevUrl({ devUrl });
+  if (!element) return base;
+  const manifest = await fetchManifest(base);
+  const entry = manifest?.elements?.[element];
+  if (entry?.labUrl) return absolutize(entry.labUrl, base);
+  if (PROJECT_LABS[element]) return absolutize(PROJECT_LABS[element], base);
+  return `${base}/labs/${element}.html`;
+}
+async function listElements({ devUrl, labUrl } = {}) {
+  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, { devUrl, labUrl } = {}) {
+  const url = resolveDevUrl({ devUrl, labUrl });
+  let data = null;
+  let source = null;
+  let staleMs = null;
+  const live = await fetchState(url);
+  if (live) {
+    data = live.data;
+    source = "live";
+    staleMs = live.staleMs;
+  } else if (url === DEV_URL && existsSync4(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);
+  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 \u2014 the lab tab may be backgrounded or closed` } : {}
+    };
+  }
+  return sliced;
+}
+async function setKnob(payload) {
+  const batched = Array.isArray(payload?.updates);
+  const updates = batched ? payload.updates : [payload];
+  const url = resolveDevUrl({ devUrl: payload?.devUrl, labUrl: payload?.labUrl });
+  const specs = knobSpecMapFromManifest(await fetchManifestCached(url));
+  const clampedReports = [];
+  const outgoing = updates.map((u) => {
+    const spec = specs[u.element]?.[u.key];
+    if (!spec) return u;
+    const c = clampKnobValue(spec, u.value);
+    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 } : {}
+  };
+}
+function trimCaptureTelemetry(sample) {
+  if (!sample || typeof sample !== "object") return sample;
+  try {
+    if (sample.perf && typeof sample.perf === "object") {
+      sample.perf = {
+        ...sample.perf,
+        note: "capture-time fps \u2014 reads low right after a navigate while WebGPU warms; use read_telemetry for steady-state"
+      };
+    }
+    for (const el of Object.values(sample.elements ?? {})) {
+      for (const probe of Object.values(el?.motion ?? {})) {
+        if (probe && Array.isArray(probe.samples)) {
+          probe.sampleCount = probe.samples.length;
+          delete probe.samples;
+        }
+      }
+    }
+  } catch {
+  }
+  return sample;
+}
+async function captureViews({
+  element,
+  labUrl,
+  inline = true,
+  fresh = false
+}) {
+  const target = await resolveLabUrl({ element, labUrl });
+  const outDir = join4(tmpdir3(), `${PROJECT}-capture-${element ?? "scene"}`);
+  mkdirSync2(outDir, { recursive: true });
+  const t0 = Date.now();
+  const timings = {};
+  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") {
+    throw new Error(
+      `captureViews returned no images for element="${element ?? "(scene)"}" at ${target}. Most likely the Element declares no cameras \u2014 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 = join4(outDir, `${cam}.png`);
+    writeFileSync2(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;
+  const tProbeStart = Date.now();
+  let gpuProbes = null;
+  let gpuProbesSource = "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 {
+  }
+  if (!gpuProbes) {
+    gpuProbes = {};
+    for (const [cam, b64] of Object.entries(base64ByCam)) {
+      try {
+        gpuProbes[cam] = probeStatsFromPng(Buffer.from(b64, "base64"));
+      } catch {
+      }
+    }
+    if (Object.keys(gpuProbes).length === 0) gpuProbes = null;
+    else gpuProbesSource = "server-fallback";
+  }
+  timings.probes = Date.now() - tProbeStart;
+  const blackFrames = gpuProbes ? Object.entries(gpuProbes).filter(([, s]) => s?.blackFrame).map(([cam]) => cam) : [];
+  const flatFrames = gpuProbes ? Object.entries(gpuProbes).filter(([, s]) => {
+    const p = s;
+    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
+  };
+}
+var BLACK_FRAME_LUMINANCE = 4e-3;
+function probeStatsFromPng(pngBuf) {
+  const img = PNG2.sync.read(pngBuf);
+  const stride = Math.max(1, Math.floor(Math.sqrt(img.width * img.height / 2304)));
+  const lums = [];
+  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
+}) {
+  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
+}) {
+  const target = await resolveLabUrl({ element, labUrl });
+  const outDir = join4(tmpdir3(), `${PROJECT}-motion-${element ?? "scene"}`);
+  mkdirSync2(outDir, { recursive: true });
+  const t0 = Date.now();
+  const { call } = await browserPool.getPage(target, { reload: fresh });
+  let cameraOrder;
+  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 \u2014 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 = join4(outDir, `${camName}.filmstrip.png`);
+    writeFileSync2(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
+  };
+}
+var SNAPSHOT_TAG_PREFIX = "triscope/snapshot/";
+var NEED_SHELL = process.platform === "win32";
+var TRISCOPE_BIN = process.platform === "win32" ? "triscope.cmd" : "triscope";
+function rejectFlagArg(value, label) {
+  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, cwd = process.cwd()) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn2("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) => resolve2({ code: code ?? 1, stdout: stdout.trim(), stderr: stderr.trim() })
+    );
+  });
+}
+async function assertCleanWt(cwd, action) {
+  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.
+Dirty paths:
+${status.stdout.split("\n").slice(0, 10).join("\n")}`
+    );
+  }
+}
+async function waitForKnobApplied(key, value, timeoutMs = 2500, element, devUrl) {
+  const ns = element ? `${element}.${key}` : null;
+  const url = resolveDevUrl({ devUrl });
+  const useHttp = url !== DEV_URL;
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      let st = null;
+      if (useHttp) {
+        st = (await fetchState(url))?.data ?? null;
+      } else if (existsSync4(STATE_PATH)) {
+        st = JSON.parse(readFileSync2(STATE_PATH, "utf8"));
+      }
+      const applied = st?.knobs?.[key] ?? (ns ? st?.knobs?.[ns] : void 0);
+      if (applied !== void 0 && knobMatches(value, applied)) return true;
+    } catch {
+    }
+    await wait2(50);
+  }
+  return false;
+}
+async function fetchPersistedKnobs() {
+  try {
+    const r = await fetch(`${DEV_URL}/__knob/current`);
+    if (!r.ok) return {};
+    return await r.json();
+  } catch {
+    return {};
+  }
+}
+async function snapshot({ name, message }) {
+  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: (/* @__PURE__ */ new Date()).toISOString(),
+    commit: head.stdout,
+    message: message ?? "",
+    knobs
+    // { [element]: { [knobKey]: value, ... } }
+  };
+  const tagName = `${SNAPSHOT_TAG_PREFIX}${name}`;
+  const tagBody = `triscope snapshot v1
+
+${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 = [];
+  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 }) {
+  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})`);
+  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;
+  try {
+    payload = JSON.parse(body.slice(jsonStart));
+  } catch {
+    throw new Error(`snapshot ${name} payload is not valid JSON`);
+  }
+  const checkout = await git(["checkout", payload.commit], cwd);
+  if (checkout.code !== 0)
+    throw new Error(`git checkout ${payload.commit} failed: ${checkout.stderr}`);
+  const updates = [];
+  for (const [elName, kv] of Object.entries(payload.knobs ?? {})) {
+    for (const [k, v] of Object.entries(kv)) {
+      updates.push({ element: elName, key: k, value: v });
+    }
+  }
+  if (updates.length > 0) {
+    try {
+      await setKnob({ updates });
+    } catch {
+    }
+  }
+  return {
+    ok: true,
+    tag: tagName,
+    restoredCommit: payload.commit,
+    knobUpdates: updates.length,
+    payload
+  };
+}
+async function autoTune({
+  element,
+  knob,
+  range,
+  target_camera,
+  max_iterations = 12,
+  labUrl
+}) {
+  const refPath = refsPath(process.cwd(), element, target_camera);
+  if (!existsSync4(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 });
+  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 = /* @__PURE__ */ new Map();
+  const history = [];
+  const t0 = Date.now();
+  async function evalAt(x) {
+    const key = x.toFixed(6);
+    if (cache.has(key)) return cache.get(key);
+    const iterStart = Date.now();
+    await setKnob({ element, key: knob, value: x, devUrl });
+    const applied = await waitForKnobApplied(knob, x, 2500, element, devUrl);
+    if (!applied) await wait2(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(`auto_tune: captureViews returned no PNG for camera "${target_camera}"`);
+    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;
+  }
+  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++) {
+    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);
+    }
+    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];
+  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."
+  };
+}
+async function multiTune({
+  element,
+  knobs,
+  target_camera,
+  max_cycles = 2,
+  per_knob_iters = 8,
+  compute_interactions = false,
+  max_evaluations,
+  labUrl
+}) {
+  const cwd = process.cwd();
+  const refPath = refsPath(cwd, element, target_camera);
+  if (!existsSync4(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 });
+  const devUrl = resolveDevUrl({ labUrl: target });
+  const { call } = await browserPool.getPage(target);
+  const t0 = Date.now();
+  const cache = /* @__PURE__ */ new Map();
+  const evalAt = async (values) => {
+    const ck = JSON.stringify(values);
+    const hit = cache.get(ck);
+    if (hit !== void 0) 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 wait2(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
+  });
+  let interactions;
+  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, s) => 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) });
+      }
+    }
+  }
+  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)."
+  };
+}
+async function checkTargets({ element, labUrl }) {
+  const cwd = process.cwd();
+  const file = join4(cwd, ".claude", "element-targets.json");
+  if (!existsSync4(file)) {
+    return { checked: 0, allPassed: true, note: `no targets file at ${file}` };
+  }
+  let all;
+  try {
+    all = JSON.parse(readFileSync2(file, "utf8"));
+  } catch (e) {
+    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 = {};
+  for (const [camera, probe] of Object.entries(cap.gpuProbes ?? {})) {
+    capturedByCamera[camera] = { luminance: probe.luminance, dynamicRange: probe.dynamicRange };
+  }
+  for (const camera of Object.keys(targetsByCamera)) {
+    const c = targetsByCamera[camera] ?? {};
+    const wantsRefMetric = c.ssim !== void 0 || c.meanAbsDiff !== void 0;
+    if (wantsRefMetric && existsSync4(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 \u2014 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 }) {
+  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
+}) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("add_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.addElement)return{ok:false,error:'addElement unavailable \u2014 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
+}) {
+  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 \u2014 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
+}) {
+  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 \u2014 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
+}) {
+  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 \u2014 rebuild the lab against newer @triscope/core' })`,
+    returnByValue: true
+  });
+  return JSON.parse(res.result.result.value);
+}
+async function setUniform({
+  element,
+  path,
+  value,
+  labUrl
+}) {
+  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 \u2014 rebuild the lab against newer @triscope/core' })`,
+    returnByValue: true
+  });
+  return JSON.parse(res.result.result.value);
+}
+async function setSceneParam({
+  cameras,
+  knobs,
+  elements
+}) {
+  const delta = {};
+  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 } = {}) {
+  const url = resolveDevUrl({ devUrl, labUrl });
+  let sceneSpec = {};
+  let live = {};
+  try {
+    const r = await fetch(`${url}/__scene/current`);
+    if (r.ok) sceneSpec = await r.json();
+  } catch {
+  }
+  const state = await fetchState(url);
+  const st = state?.data ?? (url === DEV_URL && existsSync4(STATE_PATH) ? safeReadState() : null);
+  if (st) live = { cameras: st.cameras, knobs: st.knobs, elements: st.sceneElements };
+  return { sceneSpec, live };
+}
+function safeReadState() {
+  try {
+    return JSON.parse(readFileSync2(STATE_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function openSelection({ editor }) {
+  if (!existsSync4(STATE_PATH)) {
+    throw new Error(`No telemetry at ${STATE_PATH} \u2014 is the dev server running with a lab open?`);
+  }
+  const state = JSON.parse(readFileSync2(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."
+    );
+  }
+  const rawFile = String(sel.source.file);
+  const fsPath = rawFile.replace(/^https?:\/\/[^/]+\//, "").replace(/^file:\/\//, "").replace(/[?#].*$/, "");
+  const absPath = fsPath.startsWith("/") ? fsPath : join4(process.cwd(), fsPath);
+  const line = Number(sel.source.line ?? 1);
+  const col = Number(sel.source.col ?? 1);
+  const cmd = editor ?? process.env.EDITOR ?? "code";
+  const usesGoto = /code\b/.test(cmd);
+  const args = usesGoto ? ["--goto", `${absPath}:${line}:${col}`] : [`${absPath}:${line}:${col}`];
+  return await new Promise((resolve2, reject) => {
+    const child = spawn2(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}`)));
+    setTimeout(() => {
+      try {
+        child.unref();
+      } catch {
+      }
+      resolve2({ ok: true, cmd, args, file: absPath, line, col, stderr: stderr || void 0 });
+    }, 200);
+  });
+}
+async function runSmoke({ element }) {
+  return new Promise((resolve2, reject) => {
+    const args = ["smoke"];
+    if (element) args.push(element);
+    const child = spawn2("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) => resolve2({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+async function importElement({ source, name }) {
+  rejectFlagArg(source, "source");
+  if (name !== void 0) rejectFlagArg(name, "name");
+  return new Promise((resolve2, reject) => {
+    const args = ["import", source];
+    if (name) args.push("--name", name);
+    const child = spawn2(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) => resolve2({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+async function scaffoldFromGltf({ file, name }) {
+  rejectFlagArg(file, "file");
+  if (name !== void 0) rejectFlagArg(name, "name");
+  return new Promise((resolve2, reject) => {
+    const args = ["new-gltf", file];
+    if (name) args.push("--name", name);
+    const child = spawn2(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) => resolve2({ exitCode: code ?? 0, stdout: out, stderr: err }));
+  });
+}
+var 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 \u2014 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 \u2014 luminance below threshold, a render failure) AND flatFrames:[camera,...] (panes with dynamicRange\u22481, i.e. only the flat clear-color is in view \u2014 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 \u2014 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\xD78 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\u2192blue\u2192yellow\u2192red 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) \u2014 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 \u2014 default 120; `truncated`+`total` flag the rest, raise maxNodes to see it) PLUS a separate `lights` array \u2014 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 \u2014 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>" \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2192 wait \u2192 captureViews \u2192 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) \u2014 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 \u2014 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 \u2192 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 \u2014 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 \u2192 {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 \u2192 value (same effect as set_knob; here for one-call scene edits)."
+        },
+        elements: {
+          type: "object",
+          description: "Map of elementName \u2192 {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 \u2014 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
+    }
+  }
+];
+function jsonResult(value) {
+  let text;
+  if (value === void 0) text = "undefined";
+  else if (typeof value === "string") text = value;
+  else text = JSON.stringify(value, null, 2);
+  return {
+    content: [{ type: "text", text }]
+  };
+}
+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;
+    const toolStart = Date.now();
+    logger.info(`tool:${name}`, "invoked", { args });
+    const finish = (outcome, extra) => 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,
+                labUrl: args.labUrl
+              })
+            );
+          case "read_telemetry":
+            return jsonResult(
+              await readTelemetry(args.path, {
+                devUrl: args.devUrl,
+                labUrl: args.labUrl
+              })
+            );
+          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,
+              labUrl: args.labUrl,
+              inline: args.inline ?? false,
+              fresh: args.fresh ?? false
+            });
+            const { _base64ByCam, ...summary } = res;
+            let inlineBytes = 0;
+            for (const b64 of Object.values(_base64ByCam)) 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) \u2014 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 = [{ 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 result2 = setReference({ cwd: process.cwd(), ...parsed });
+            return jsonResult(result2);
+          }
+          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 = existsSync4(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
+            });
+            const compositeBytes = diff.compositeBase64.length;
+            const heatmapBytes = diff.heatmapBase64?.length ?? 0;
+            const heatmapFits = compositeBytes + heatmapBytes <= INLINE_PAYLOAD_BUDGET;
+            const content = [
+              {
+                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\xD78 SSIM map (row 0 = top); worstTile points at the most divergent region. The second image is a black\u2192blue\u2192yellow\u2192red difference heatmap \u2014 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 (!existsSync4(filmstrip)) {
+              return {
+                isError: true,
+                content: [
+                  {
+                    type: "text",
+                    text: `no motion reference at ${filmstrip}. Call set_reference_motion first.`
+                  }
+                ]
+              };
+            }
+            let savedMeta = {};
+            try {
+              savedMeta = existsSync4(meta) ? JSON.parse(readFileSync2(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;
+            let filmstripBytes = 0;
+            for (const b64 of Object.values(_filmstripBase64))
+              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) \u2014 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 = [{ 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(2e3) });
+              if (r.ok) {
+                const m = 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) / 1e3),
+              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, 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, 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,
+                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,
+                value: parsed.value,
+                labUrl: parsed.labUrl
+              })
+            );
+          }
+          case "inspect_scene": {
+            const parsed = z.object({
+              element: z.string().optional(),
+              maxNodes: z.number().int().min(1).max(5e3).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,
+                knobs: parsed.knobs.map((k) => ({
+                  key: k.key,
+                  range: [k.range[0], k.range[1]],
+                  start: k.start
+                })),
+                target_camera: parsed.target_camera,
+                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, 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,
+                labUrl: args.labUrl
+              })
+            );
+          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) {
+      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);
+  console.error(`[triscope-mcp] connected. dev server: ${DEV_URL}, project: ${PROJECT}`);
+}
+export {
+  absolutize,
+  applyPath,
+  clampKnobValue,
+  jsonResult,
+  knobSpecMapFromManifest,
+  probeStatsFromPng,
+  readProjectLabMap,
+  readProjectName,
+  recordError,
+  resolveDevUrl,
+  startServer
+};
+//# sourceMappingURL=server.mjs.map