@triscope/mcp 0.4.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,31 @@
+# @triscope/mcp
+
+The triscope **MCP server** (stdio JSON-RPC) — gives an AI agent structured,
+machine-readable control of a running [`@triscope/core`](https://www.npmjs.com/package/@triscope/core)
+lab over a headless Chromium/WebGPU pool.
+
+## What it exposes
+
+Tools for the full converge-a-3D-scene loop, including:
+
+- **`capture_views`** / **`capture_motion`** — render the lab's cameras to PNGs
+  (the only reliable WebGPU readback path) with GPU + flat/black-frame probes.
+- **`inspect_scene`** / **`read_uniform`** / **`set_uniform`** — scene-graph
+  introspection and live uniform/material/light read-write.
+- **`read_telemetry`** / **`set_knob`** / **`list_elements`** — observe and tune,
+  with per-call `devUrl`/`labUrl` so one server can target any running lab.
+- **`set_reference`** / **`diff_reference`** / **`check_targets`** — per-tile SSIM
+  + diff heatmaps and target gating.
+- **`add_element`** / **`remove_element`** / **`set_scene_param`** — drive a
+  `runSceneLab` scene live.
+- **`auto_tune`** / **`multi_tune`**, **`snapshot`** / **`restore`**,
+  **`import_element`**, **`scaffold_from_gltf`**.
+
+## Run
+
+```jsonc
+// in your MCP client config
+{ "command": "npx", "args": ["-y", "@triscope/mcp"] }
+```
+
+Part of the [triscope](https://github.com/tedin7/triscope) monorepo. MIT.

package/bin/triscope-mcp-supervised.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Supervisor wrapper for triscope-mcp.
+ *
+ * Claude Code spawns this bin as a stdio MCP server. The wrapper itself
+ * doesn't speak MCP — it spawns the real triscope-mcp.mjs as a child with
+ * inherited stdio (so the child's stdin/stdout are the wrapper's, which
+ * are Claude Code's pipes). When the child exits unexpectedly the wrapper
+ * respawns it with exponential backoff, keeping the wrapper PID alive and
+ * stable from Claude Code's perspective.
+ *
+ * Why this exists: `claude mcp list` reports "Connected" based on config,
+ * not on the actual subprocess being alive. If the real server crashes
+ * mid-session (rogue exception, memory blow-up, signal), Claude Code does
+ * NOT auto-restart it — subsequent tool calls return cryptic "Connection
+ * closed" errors and the user has to exit + relaunch the whole CLI.
+ *
+ * To use, re-register the MCP pointing at THIS bin instead of the bare
+ * server:
+ *
+ *   claude mcp add triscope-supervised \
+ *     --scope user \
+ *     --env TRISCOPE_URL=http://localhost:5173 \
+ *     -- node /home/.../packages/mcp/bin/triscope-mcp-supervised.mjs
+ *
+ * Exit semantics:
+ *   - Child exits with code 0 or by SIGTERM/SIGINT → wrapper exits too
+ *     (clean shutdown, no respawn).
+ *   - Child crashes → wrapper respawns with 0.5s → 30s exponential backoff.
+ *   - Wrapper's stdin closes → Claude Code disconnected → kill child + exit.
+ */
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REAL_BIN = join(HERE, 'triscope-mcp.mjs');
+const MAX_BACKOFF_MS = 30000;
+const RESET_BACKOFF_AFTER_MS = 5000;
+
+let child = null;
+let backoff = 0;
+let shuttingDown = false;
+let resetTimer = null;
+
+function startChild() {
+  if (shuttingDown) return;
+  // eslint-disable-next-line no-console
+  console.error(`[triscope-supervisor] spawning ${REAL_BIN} (backoff=${backoff}ms)`);
+  child = spawn('node', [REAL_BIN], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    env: process.env,
+  });
+  child.on('exit', (code, sig) => {
+    child = null;
+    if (resetTimer) {
+      clearTimeout(resetTimer);
+      resetTimer = null;
+    }
+    if (shuttingDown) {
+      process.exit(code ?? 0);
+      return;
+    }
+    if (sig === 'SIGTERM' || sig === 'SIGINT' || code === 0) {
+      // Treat clean exits as "shutdown intent" — don't respawn.
+      process.exit(code ?? 0);
+      return;
+    }
+    // eslint-disable-next-line no-console
+    console.error(
+      `[triscope-supervisor] child exited code=${code} sig=${sig}, respawning in ${backoff || 500}ms`,
+    );
+    backoff = Math.min(backoff === 0 ? 500 : backoff * 2, MAX_BACKOFF_MS);
+    setTimeout(startChild, backoff);
+  });
+  child.on('error', (err) => {
+    // eslint-disable-next-line no-console
+    console.error('[triscope-supervisor] child spawn error:', err?.message ?? err);
+  });
+  // If the child lives more than 5 s, reset the backoff so the next crash
+  // gets a fresh 500ms start (avoids permanent slow-restart on a single
+  // late crash after a long healthy stretch).
+  resetTimer = setTimeout(() => {
+    backoff = 0;
+  }, RESET_BACKOFF_AFTER_MS);
+}
+
+function shutdown(code = 0) {
+  shuttingDown = true;
+  if (child && !child.killed) {
+    try {
+      child.kill('SIGTERM');
+    } catch {}
+  }
+  // Give the child a moment to flush before exiting the wrapper.
+  setTimeout(() => process.exit(code), 200);
+}
+
+// Parent (Claude Code) closed stdin → we should die.
+process.stdin.on('end', () => shutdown(0));
+process.stdin.on('close', () => shutdown(0));
+process.on('SIGINT', () => shutdown(130));
+process.on('SIGTERM', () => shutdown(143));
+// Don't crash on our own rogue errors either.
+process.on('uncaughtException', (err) => {
+  // eslint-disable-next-line no-console
+  console.error('[triscope-supervisor] uncaughtException:', err?.stack ?? err);
+});
+process.on('unhandledRejection', (err) => {
+  // eslint-disable-next-line no-console
+  console.error('[triscope-supervisor] unhandledRejection:', err?.stack ?? err);
+});
+
+startChild();

package/bin/triscope-mcp.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Triscope MCP server entry. Stdio JSON-RPC.
+// Imports the tsup-built ESM bundle so we ship a single dist artifact and
+// don't have to keep src/ in published tarballs for runtime.
+import { startServer } from '../dist/server.mjs';
+
+startServer().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('[triscope-mcp] fatal:', err);
+  process.exit(1);
+});

package/dist/browser.mjs

@@ -0,0 +1,348 @@
+// 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((resolve, 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 resolve(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 = 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) {
+      logger?.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();
+    logger?.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 };
+      logger?.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)}`;
+      logger?.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();
+    }
+  };
+}
+export {
+  cdpClient,
+  createBrowserPool,
+  defaultChromeBinary,
+  inferGraphicalEnv,
+  parseExtraChromeArgs,
+  tailLines
+};
+//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["// Persistent Chromium pool. The MCP server keeps one Chromium child +\n// one CDP websocket alive across capture_views / diff_reference calls so\n// subsequent captures skip the 3-5 s cold start. First call lazy-spawns;\n// later calls navigate the existing page if the URL changed, otherwise reuse.\n//\n// One pool per MCP process. Disposed on process exit (kill -9 also clears\n// the user-data-dir via the OS, since /tmp is volatile).\n\nimport type { ChildProcessWithoutNullStreams } from 'node:child_process';\nimport { spawn } from 'node:child_process';\nimport { existsSync, readdirSync } from 'node:fs';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\nimport type { Logger } from './logger.js';\n\nconst wait = (ms) => new Promise((r) => setTimeout(r, ms));\n\nconst DEFAULT_CHROME_ARGS = [\n  '--enable-unsafe-webgpu',\n  '--ignore-gpu-blocklist',\n  // Suppress the first-run wizard and the default-browser banner: both\n  // can block the new window from rendering or trigger a different code\n  // path that ignores --remote-debugging-port until dismissed. Both have\n  // been seen to leave Chromium \"running\" but with no CDP endpoint open,\n  // which manifests as a \"DevTools endpoint did not become ready\" error.\n  '--no-first-run',\n  '--no-default-browser-check',\n];\n\nexport function parseExtraChromeArgs(): string[] {\n  const raw = process.env.TRISCOPE_CHROME_ARGS ?? '';\n  if (!raw.trim()) return [];\n  // Keep this intentionally simple: env-configured args are whitespace split.\n  // Flags containing spaces should be wrapped in a tiny launcher script and\n  // provided via CHROME_BIN instead.\n  return raw.trim().split(/\\s+/).filter(Boolean);\n}\n\nexport function tailLines(text: string, maxLines = 24): string {\n  const lines = text.trim().split(/\\r?\\n/).filter(Boolean);\n  return lines.slice(-maxLines).join('\\n');\n}\n\nasync function readDevtoolsPages(port: number): Promise<any[] | null> {\n  try {\n    const pages = await fetch(`http://127.0.0.1:${port}/json`, {\n      signal: AbortSignal.timeout(1000),\n    }).then((r) => r.json());\n    return Array.isArray(pages) && pages.length > 0 ? pages : null;\n  } catch {\n    return null;\n  }\n}\n\nexport function cdpClient(ws) {\n  const pending = new Map();\n  let nextId = 0;\n  ws.onmessage = (event) => {\n    const msg = JSON.parse(event.data);\n    if (msg.id && pending.has(msg.id)) {\n      pending.get(msg.id)(msg);\n      pending.delete(msg.id);\n    }\n  };\n  // When the socket closes or errors mid-call, every pending request would\n  // otherwise sit until its 20s timeout, blocking the next tool call for up to\n  // 20s × N. Drain them immediately with a synthetic error so the failing tool\n  // call rejects fast (and health() can report a sick pool).\n  const drain = (reason: string) => {\n    for (const cb of pending.values()) cb({ error: { message: reason } });\n    pending.clear();\n  };\n  ws.onclose = (event) =>\n    drain(`CDP WebSocket closed (code ${event?.code ?? '?'}) before the response arrived`);\n  ws.onerror = (event) =>\n    drain(`CDP WebSocket error (${event?.message ?? 'unknown'}) before the response arrived`);\n  const call = (method, params = {}) =>\n    new Promise((resolve, reject) => {\n      const id = ++nextId;\n      ws.send(JSON.stringify({ id, method, params }));\n      const t = setTimeout(() => {\n        pending.delete(id);\n        reject(new Error(`CDP timeout for ${method}`));\n      }, 20000);\n      pending.set(id, (msg) => {\n        clearTimeout(t);\n        if (msg.error) reject(new Error(`${method}: ${msg.error.message}`));\n        else resolve(msg);\n      });\n    });\n  return call;\n}\n\n/**\n * Locate a Chromium-family browser on disk. Resolution order matches\n * puppeteer/playwright so users who already set one of these for their\n * existing tooling don't have to duplicate config:\n *   1. explicit arg\n *   2. CHROME_BIN\n *   3. PUPPETEER_EXECUTABLE_PATH\n *   4. OS-typical defaults (Windows: Program Files\\Google\\Chrome; macOS:\n *      /Applications/Google Chrome.app; Linux: PATH-relative `chromium`)\n */\n\nexport function inferGraphicalEnv(): NodeJS.ProcessEnv {\n  if (process.platform !== 'linux') return process.env;\n\n  const env: NodeJS.ProcessEnv = { ...process.env };\n  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;\n  const runtimeDir = env.XDG_RUNTIME_DIR || (uid !== undefined ? `/run/user/${uid}` : undefined);\n\n  if (runtimeDir && existsSync(runtimeDir)) {\n    env.XDG_RUNTIME_DIR = runtimeDir;\n    if (!env.WAYLAND_DISPLAY) {\n      try {\n        const waylandSocket = readdirSync(runtimeDir).find((name) => /^wayland-\\d+$/.test(name));\n        if (waylandSocket) env.WAYLAND_DISPLAY = waylandSocket;\n      } catch {\n        /* best-effort */\n      }\n    }\n  }\n\n  if (!env.DISPLAY && existsSync('/tmp/.X11-unix/X0')) env.DISPLAY = ':0';\n  return env;\n}\n\nexport function defaultChromeBinary(): string {\n  if (process.platform === 'win32') {\n    // Windows users normally install Chrome under Program Files. We don't\n    // touch the filesystem to verify — Chrome's own startup will surface\n    // an ENOENT clearly enough — but we pick the typical 64-bit path so\n    // most installs Just Work without setting CHROME_BIN.\n    return 'C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe';\n  }\n  if (process.platform === 'darwin') {\n    return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';\n  }\n  return 'chromium';\n}\n\nexport function createBrowserPool({\n  chromeBin = process.env.CHROME_BIN ??\n    process.env.PUPPETEER_EXECUTABLE_PATH ??\n    defaultChromeBinary(),\n  port = Number(process.env.TRISCOPE_DEBUG_PORT ?? 9230),\n  logger = undefined as Logger | undefined,\n} = {}) {\n  let chrome: ChildProcessWithoutNullStreams | null = null;\n  let chromeExit: { code: number | null; signal: NodeJS.Signals | null } | null = null;\n  let chromeStderr = '';\n  let ws = null;\n  let call = null;\n  let currentUrl = null;\n  // URL last confirmed to have rendered ≥1 real frame. Lets getPage skip the\n  // warm-frame wait for an already-warm page (so e.g. auto_tune's capture loop\n  // isn't slowed); reset whenever we navigate or force a reload.\n  let lastWarmUrl: string | null = null;\n\n  async function connectToPage(initialUrl: string, pages: any[]) {\n    const page =\n      pages.find((p) => p.url === initialUrl || p.url?.startsWith(initialUrl)) ?? pages[0];\n    ws = new WebSocket(page.webSocketDebuggerUrl);\n    await new Promise((res, rej) => {\n      ws.onopen = res;\n      ws.onerror = (e) => rej(new Error(`ws error: ${e?.message ?? 'unknown'}`));\n    });\n    call = cdpClient(ws);\n    await call('Runtime.enable');\n    await call('Page.enable');\n    currentUrl = page.url ?? initialUrl;\n    if (currentUrl !== initialUrl) await navigateIfNeeded(initialUrl);\n  }\n\n  function chromeLaunchArgs(profile: string, initialUrl: string): string[] {\n    return [\n      ...DEFAULT_CHROME_ARGS,\n      ...parseExtraChromeArgs(),\n      `--user-data-dir=${profile}`,\n      `--remote-debugging-port=${port}`,\n      '--window-size=1600,900',\n      initialUrl,\n    ];\n  }\n\n  async function ensureBrowser(initialUrl: string) {\n    if (chrome && !chrome.killed && ws && ws.readyState === 1) return;\n\n    // First attach to an already-running browser on the configured port. This\n    // is the reliable path in sandboxed agents where opening a headed GUI may\n    // require a user-approved launcher outside the MCP process.\n    const existingPages = await readDevtoolsPages(port);\n    if (existingPages) {\n      logger?.info('browser', 'attaching to existing DevTools endpoint', {\n        port,\n        pages: existingPages.length,\n      });\n      await connectToPage(initialUrl, existingPages);\n      return;\n    }\n\n    // Profile dir: pid + monotonic timestamp + random suffix → unique per\n    // spawn so two concurrent MCP servers (or one that respawned after a\n    // crash, leaving SingletonLock pointing at a dead PID) can never share\n    // the same dir. Chromium's singleton check is path-based — same dir =\n    // forwards URL to the \"running\" instance and exits without binding\n    // --remote-debugging-port, which is the silent-fail mode that's hard\n    // to diagnose.\n    const profile = join(\n      tmpdir(),\n      `triscope-mcp-profile-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,\n    );\n    const args = chromeLaunchArgs(profile, initialUrl);\n    chromeExit = null;\n    chromeStderr = '';\n    const browserEnv = inferGraphicalEnv();\n    logger?.info('browser', 'spawning chromium', {\n      chromeBin,\n      port,\n      profile,\n      args,\n      env: {\n        DISPLAY: browserEnv.DISPLAY,\n        WAYLAND_DISPLAY: browserEnv.WAYLAND_DISPLAY,\n        XDG_RUNTIME_DIR: browserEnv.XDG_RUNTIME_DIR,\n      },\n    });\n    chrome = spawn(chromeBin, args, { stdio: ['ignore', 'ignore', 'pipe'], env: browserEnv });\n    chrome.stderr.on('data', (d) => {\n      chromeStderr += String(d);\n      if (chromeStderr.length > 12000) chromeStderr = chromeStderr.slice(-12000);\n    });\n    chrome.on('exit', (code, signal) => {\n      chromeExit = { code, signal };\n      logger?.warn('browser', 'chromium exited', { code, signal, stderr: tailLines(chromeStderr) });\n    });\n    chrome.on('error', (err) => {\n      chromeExit = { code: 1, signal: null };\n      chromeStderr += `\\nspawn error: ${(err as any)?.message ?? String(err)}`;\n      logger?.error('browser', 'chromium spawn error', {\n        message: (err as any)?.message ?? String(err),\n      });\n    });\n\n    let pages: any[] | null = null;\n    const start = Date.now();\n    while (Date.now() - start < 10000) {\n      pages = await readDevtoolsPages(port);\n      if (pages) break;\n      if (chromeExit) break;\n      await wait(250);\n    }\n    if (!pages) {\n      const stderr = tailLines(chromeStderr);\n      const exit = chromeExit ? ` chromiumExit=${JSON.stringify(chromeExit)}` : '';\n      // Silent-exit pattern: chromiumExit is null (process didn't die) but\n      // port stayed closed. Almost always: sandboxed Chromium can't bind\n      // network ports, or the singleton check forwarded the URL to a\n      // (non-debuggable) sibling instance.\n      const silentExit = !chromeExit && !pages;\n      const hint = silentExit\n        ? 'Chromium process is alive but DevTools never opened — 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=' +\n          port +\n          ' --enable-unsafe-webgpu — the MCP server auto-attaches to an existing endpoint when present; (2) set TRISCOPE_DEBUG_PORT to a port the sandbox permits.'\n        : 'If this runs under Codex/Claude and headed launch still fails, pre-launch Chrome with --remote-debugging-port=' +\n          port +\n          ' or set TRISCOPE_CHROME_ARGS=--headless=new for non-interactive capture.';\n      throw new Error(\n        `DevTools endpoint did not become ready on 127.0.0.1:${port}.${exit}${stderr ? `\\nstderr:\\n${stderr}` : ''}\\n${hint}`,\n      );\n    }\n    await connectToPage(initialUrl, pages);\n  }\n\n  function harnessNotMountedError(url: string) {\n    return new Error(\n      `window.__TRISCOPE__ did not mount within 10s on ${url}. ` +\n        `Common causes: ` +\n        `(1) the page never loaded — confirm the dev server is up and the URL is right (open it in a real browser tab); ` +\n        `(2) WebGPU init failed — Linux Chrome needs --enable-unsafe-webgpu and either xvfb or a real display; ` +\n        `(3) runLab() threw before mounting — check the #boot overlay text or the page console; ` +\n        `(4) the lab page doesn't call runLab() at all — verify its entry script imports @triscope/core.`,\n    );\n  }\n\n  // When the harness never mounts, check whether runLab() recorded a precise\n  // mount failure (bad element / mount() threw) and surface THAT instead of the\n  // generic timeout — turns \"not mounted within 10s\" into \"element X failed to\n  // mount: <real error at line N>\".\n  async function mountErrorOrTimeout(url: string): Promise<Error> {\n    try {\n      const r = await call('Runtime.evaluate', {\n        expression: 'JSON.stringify(window.__TRISCOPE_MOUNT_ERROR__ ?? null)',\n        returnByValue: true,\n      });\n      const me = JSON.parse(r.result.result.value);\n      if (me?.message) {\n        const probs = me.problems?.length\n          ? `\\nContract problems:\\n - ${me.problems.join('\\n - ')}`\n          : '';\n        return new Error(`element \"${me.element ?? '?'}\" failed to mount: ${me.message}${probs}`);\n      }\n    } catch {\n      /* fall through to the generic message */\n    }\n    return harnessNotMountedError(url);\n  }\n\n  async function navigateIfNeeded(url) {\n    if (url === currentUrl) return;\n    await call('Page.navigate', { url });\n    lastWarmUrl = null; // new document → not warm until a frame renders\n    // Wait for the harness to remount on the new page.\n    const start = Date.now();\n    while (Date.now() - start < 10000) {\n      try {\n        const probe = await call('Runtime.evaluate', {\n          expression:\n            '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === \"function\")',\n          returnByValue: true,\n        });\n        if (probe.result.result.value) {\n          currentUrl = url;\n          return;\n        }\n      } catch {}\n      await wait(200);\n    }\n    throw await mountErrorOrTimeout(url);\n  }\n\n  async function waitForHarness() {\n    for (let i = 0; i < 40; i++) {\n      try {\n        const probe = await call('Runtime.evaluate', {\n          expression:\n            '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === \"function\")',\n          returnByValue: true,\n        });\n        if (probe.result.result.value) return;\n      } catch {\n        // Transient \"execution context destroyed\" while a reload tears down the\n        // old document — retry (mirrors navigateIfNeeded). Without this a probe\n        // landing mid-teardown throws raw out of a fresh:true call.\n      }\n      await wait(250);\n    }\n    throw await mountErrorOrTimeout(currentUrl ?? '(initial page)');\n  }\n\n  // Wait for the harness to render a REAL frame before a capture. The mount\n  // probe (waitForHarness/navigateIfNeeded) only proves window.__TRISCOPE__\n  // exists — not that anything was drawn. Capturing in that gap yields a black\n  // pre-render frame (observed: diff_reference came back black right after a\n  // fresh navigate while a warmed capture_views rendered fine). Polls the\n  // harness's monotonic framesRendered() (true on the first RAF), falling back\n  // to fps>0 for older labs. Skips entirely when the page is already warm.\n  async function waitForWarmFrame() {\n    if (currentUrl && currentUrl === lastWarmUrl) return;\n    for (let i = 0; i < 20; i++) {\n      try {\n        const probe = await call('Runtime.evaluate', {\n          expression:\n            '(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;}})()',\n          returnByValue: true,\n        });\n        if ((probe.result.result.value ?? 0) >= 2) {\n          lastWarmUrl = currentUrl;\n          return;\n        }\n      } catch {\n        /* transient eval failure — retry */\n      }\n      await wait(100);\n    }\n    // Timed out without a confirmed frame — proceed anyway; per-camera\n    // blackFrames detection in capture_views is the backstop. Cache as \"warm\"\n    // so a perpetually-slow page doesn't re-block every capture.\n    lastWarmUrl = currentUrl;\n  }\n\n  async function isAlive() {\n    if (!chrome || chrome.killed || !ws || ws.readyState !== 1) return false;\n    // Even with WS open, the page may be hung. Probe with a fast no-op\n    // CDP call and short timeout so a stalled Chromium is detected here\n    // rather than at the much heavier Page.navigate that follows.\n    try {\n      await Promise.race([\n        call('Runtime.evaluate', { expression: '1', returnByValue: true }),\n        new Promise((_, rej) => setTimeout(() => rej(new Error('alive probe timeout')), 1500)),\n      ]);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  function disposeQuiet() {\n    try {\n      ws?.close();\n    } catch {}\n    try {\n      if (chrome && !chrome.killed) chrome.kill();\n    } catch {}\n    ws = null;\n    chrome = null;\n    call = null;\n    currentUrl = null;\n    lastWarmUrl = null;\n    chromeExit = null;\n    chromeStderr = '';\n  }\n\n  return {\n    /** Lazy-spawn Chromium (first call) or reuse it (subsequent). Always\n     *  guarantees the page is sitting on `url` with the harness mounted.\n     *  Self-heals: if the previous Chromium died externally (manual kill,\n     *  crash) the next call disposes the stale state and respawns. */\n    async getPage(url, opts: { reload?: boolean } = {}) {\n      const reload = opts?.reload === true;\n      if (chrome && !(await isAlive())) {\n        disposeQuiet();\n      }\n      if (!chrome) {\n        await ensureBrowser(url);\n        await waitForHarness();\n        lastWarmUrl = null;\n      } else if (reload && url === currentUrl) {\n        // Force a fresh load of the SAME url to pick up source edits the pool's\n        // cached page would otherwise miss (e.g. a *.lab.ts edit that doesn't\n        // match the dev plugin's forceReloadOn regex).\n        //\n        // Page.reload resolves on *initiation*, not load — the old execution\n        // context stays scriptable briefly, so waitForHarness/waitForWarmFrame\n        // would otherwise confirm the STALE page (its __TRISCOPE__ + monotonic\n        // framesRendered both still satisfy the probes) and we'd capture the\n        // pre-edit content. Invalidate the old global first so the probes only\n        // pass once the NEW document has mounted a fresh harness.\n        try {\n          await call('Runtime.evaluate', {\n            expression: 'try { window.__TRISCOPE__ = undefined; } catch (e) {}',\n            returnByValue: true,\n          });\n        } catch {\n          /* old context already gone — fine */\n        }\n        lastWarmUrl = null;\n        await call('Page.reload', { ignoreCache: true });\n        await waitForHarness();\n      } else {\n        await navigateIfNeeded(url); // navigates only when url changed\n      }\n      await waitForWarmFrame();\n      return { call };\n    },\n    /** Synchronous teardown. Safe to call multiple times. */\n    dispose() {\n      disposeQuiet();\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/logger.mjs

@@ -0,0 +1,51 @@
+// src/logger.ts
+import { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+var MAX_LOG_BYTES = 1024 * 1024;
+function createLogger(project) {
+  const logPath = join(tmpdir(), `${project}-mcp.log`);
+  function rotateIfNeeded() {
+    try {
+      if (!existsSync(logPath)) return;
+      const size = statSync(logPath).size;
+      if (size < MAX_LOG_BYTES) return;
+      const rolled = `${logPath}.1`;
+      if (existsSync(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
+  };
+}
+export {
+  createLogger
+};
+//# sourceMappingURL=logger.mjs.map

package/dist/logger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts"],"sourcesContent":["/**\n * Structured logger for the MCP server.\n *\n * Two output sinks:\n *   - console.error (the existing convention — readable when run under\n *     Claude Code, doesn't pollute stdout which is the MCP transport)\n *   - /tmp/<project>-mcp.log with naive 1 MB rotation (rename to .1 then\n *     truncate), so a long-running server keeps a persistent error trail\n *     without leaking disk.\n *\n * Each entry is one JSON line:\n *   {\"ts\":\"2026-05-17T15:00:00.000Z\",\"level\":\"error\",\"scope\":\"capture\",\n *    \"msg\":\"…\",\"meta\":{…}}\n *\n * Designed for grep / jq, not for fancy log libraries.\n */\nimport { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from 'node:fs';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\nexport type LogLevel = 'info' | 'warn' | 'error' | 'debug';\n\nexport interface LogEntry {\n  ts: string;\n  level: LogLevel;\n  scope: string;\n  msg: string;\n  meta?: Record<string, unknown>;\n}\n\nexport interface Logger {\n  info(scope: string, msg: string, meta?: Record<string, unknown>): void;\n  warn(scope: string, msg: string, meta?: Record<string, unknown>): void;\n  error(scope: string, msg: string, meta?: Record<string, unknown>): void;\n  debug(scope: string, msg: string, meta?: Record<string, unknown>): void;\n  readonly logPath: string;\n}\n\nconst MAX_LOG_BYTES = 1024 * 1024; // 1 MB\n\nexport function createLogger(project: string): Logger {\n  const logPath = join(tmpdir(), `${project}-mcp.log`);\n\n  function rotateIfNeeded(): void {\n    try {\n      if (!existsSync(logPath)) return;\n      const size = statSync(logPath).size;\n      if (size < MAX_LOG_BYTES) return;\n      const rolled = `${logPath}.1`;\n      if (existsSync(rolled)) {\n        try {\n          unlinkSync(rolled);\n        } catch {\n          /* best-effort */\n        }\n      }\n      renameSync(logPath, rolled);\n    } catch {\n      /* never let logging crash the server */\n    }\n  }\n\n  function write(entry: LogEntry): void {\n    // console (stderr — stdout is taken by MCP stdio transport)\n    const tag = `[triscope-mcp:${entry.level}:${entry.scope}]`;\n    if (entry.level === 'error' || entry.level === 'warn') {\n      // eslint-disable-next-line no-console\n      console.error(tag, entry.msg, entry.meta ?? '');\n    } else if (process.env.TRISCOPE_MCP_DEBUG) {\n      // eslint-disable-next-line no-console\n      console.error(tag, entry.msg, entry.meta ?? '');\n    }\n    // file\n    try {\n      rotateIfNeeded();\n      appendFileSync(logPath, JSON.stringify(entry) + '\\n');\n    } catch {\n      /* swallow */\n    }\n  }\n\n  function make(level: LogLevel) {\n    return (scope: string, msg: string, meta?: Record<string, unknown>) =>\n      write({ ts: new Date().toISOString(), level, scope, msg, meta });\n  }\n\n  return {\n    info: make('info'),\n    warn: make('warn'),\n    error: make('error'),\n    debug: make('debug'),\n    logPath,\n  };\n}\n"],"mappings":";AAgBA,SAAS,gBAAgB,YAAY,YAAY,UAAU,kBAAkB;AAC7E,SAAS,cAAc;AACvB,SAAS,YAAY;AAoBrB,IAAM,gBAAgB,OAAO;AAEtB,SAAS,aAAa,SAAyB;AACpD,QAAM,UAAU,KAAK,OAAO,GAAG,GAAG,OAAO,UAAU;AAEnD,WAAS,iBAAuB;AAC9B,QAAI;AACF,UAAI,CAAC,WAAW,OAAO,EAAG;AAC1B,YAAM,OAAO,SAAS,OAAO,EAAE;AAC/B,UAAI,OAAO,cAAe;AAC1B,YAAM,SAAS,GAAG,OAAO;AACzB,UAAI,WAAW,MAAM,GAAG;AACtB,YAAI;AACF,qBAAW,MAAM;AAAA,QACnB,QAAQ;AAAA,QAER;AAAA,MACF;AACA,iBAAW,SAAS,MAAM;AAAA,IAC5B,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,WAAS,MAAM,OAAuB;AAEpC,UAAM,MAAM,iBAAiB,MAAM,KAAK,IAAI,MAAM,KAAK;AACvD,QAAI,MAAM,UAAU,WAAW,MAAM,UAAU,QAAQ;AAErD,cAAQ,MAAM,KAAK,MAAM,KAAK,MAAM,QAAQ,EAAE;AAAA,IAChD,WAAW,QAAQ,IAAI,oBAAoB;AAEzC,cAAQ,MAAM,KAAK,MAAM,KAAK,MAAM,QAAQ,EAAE;AAAA,IAChD;AAEA,QAAI;AACF,qBAAe;AACf,qBAAe,SAAS,KAAK,UAAU,KAAK,IAAI,IAAI;AAAA,IACtD,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,WAAS,KAAK,OAAiB;AAC7B,WAAO,CAAC,OAAe,KAAa,SAClC,MAAM,EAAE,KAAI,oBAAI,KAAK,GAAE,YAAY,GAAG,OAAO,OAAO,KAAK,KAAK,CAAC;AAAA,EACnE;AAEA,SAAO;AAAA,IACL,MAAM,KAAK,MAAM;AAAA,IACjB,MAAM,KAAK,MAAM;AAAA,IACjB,OAAO,KAAK,OAAO;AAAA,IACnB,OAAO,KAAK,OAAO;AAAA,IACnB;AAAA,EACF;AACF;","names":[]}