@sightmap/mcp 0.8.0 → 0.9.0

package/dist/index.js

@@ -347,30 +347,388 @@ async function handleInitProject(input) {
 }
 
 // src/tools/runtime/snapshot.ts
-async function handleRuntimeSnapshot(input) {
+async function handleRuntimeSnapshot(input, deps = {}) {
   if (input.source.kind === "endpoint") {
-    const res = await fetch(input.source.url);
-    if (res.status === 404) {
-      let detail = "";
-      try {
-        const body = await res.json();
-        detail = body.error ?? "";
-      } catch {
-      }
+    return runEndpoint(input.source);
+  }
+  if (input.source.kind === "literal") {
+    return runLiteral(input.source);
+  }
+  return runBrowser(input.source, deps);
+}
+async function runEndpoint(source) {
+  const res = await fetch(source.url);
+  if (res.status === 404) {
+    let detail = "";
+    try {
+      const body = await res.json();
+      detail = body.error ?? "";
+    } catch {
+    }
+    throw new Error(
+      `no snapshot cached yet at ${source.url}${detail ? `: ${detail}` : ""}`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`snapshot fetch failed: HTTP ${res.status}`);
+  }
+  const snapshot = await res.json();
+  return { ok: true, snapshot, source };
+}
+var REQUIRED_SNAPSHOT_FIELDS = [
+  "capturedAt",
+  "route",
+  "components",
+  "markers",
+  "unmarkedCandidates"
+];
+function runLiteral(source) {
+  validateSnapshotShape(source.snapshot, "literal");
+  return { ok: true, snapshot: source.snapshot, source };
+}
+function validateSnapshotShape(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `${label} snapshot: expected an object with fields { capturedAt, route, components, markers, unmarkedCandidates }; got ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+    );
+  }
+  const s = value;
+  for (const field of REQUIRED_SNAPSHOT_FIELDS) {
+    if (!(field in s)) {
+      throw new Error(`${label} snapshot: missing required field \`${field}\``);
+    }
+  }
+  if (!Array.isArray(s["components"])) {
+    throw new Error(`${label} snapshot: \`components\` must be an array`);
+  }
+  if (!Array.isArray(s["markers"])) {
+    throw new Error(`${label} snapshot: \`markers\` must be an array`);
+  }
+  if (!Array.isArray(s["unmarkedCandidates"])) {
+    throw new Error(`${label} snapshot: \`unmarkedCandidates\` must be an array`);
+  }
+}
+async function runBrowser(source, deps) {
+  if (deps.upstream === void 0) {
+    throw new Error(
+      "browser-mode snapshot requires an upstream MCP server (e.g., @playwright/mcp). Run sightmap-mcp without `--curate-only` so the @playwright/mcp passthrough is wired up."
+    );
+  }
+  const upstream = deps.upstream;
+  const wantInject = source.inject === true;
+  const allowAutoInject = source.inject === void 0;
+  const urls = source.routes !== void 0 && source.routes.length > 0 ? source.routes.map((r) => absolutize(r, source.url)) : [source.url];
+  const captures = [];
+  for (const targetUrl of urls) {
+    const captureOpts = {
+      forceInject: wantInject,
+      autoInject: allowAutoInject
+    };
+    if (deps.getInjectScript !== void 0) {
+      captureOpts.getInjectScript = deps.getInjectScript;
+    }
+    const cap = await captureOneUrl(upstream, targetUrl, captureOpts);
+    validateSnapshotShape(cap, "browser");
+    captures.push({ url: targetUrl, snapshot: cap });
+  }
+  if (source.routes === void 0 || source.routes.length === 0) {
+    return { ok: true, snapshot: captures[0].snapshot, source };
+  }
+  return { ok: true, snapshots: captures, source };
+}
+function absolutize(routeOrUrl, baseUrl) {
+  try {
+    return new URL(routeOrUrl).toString();
+  } catch {
+    const base = new URL(baseUrl);
+    return new URL(routeOrUrl, base).toString();
+  }
+}
+async function captureOneUrl(upstream, url, opts) {
+  const navResult = await upstream.callTool("browser_navigate", { url });
+  if (navResult.isError === true) {
+    throw new Error(
+      `browser_navigate to ${url} failed: ${navResult.content[0]?.text ?? "unknown error"}`
+    );
+  }
+  const probe = await evalAndDecode(
+    upstream,
+    `() => typeof (window.__sightmap__ && window.__sightmap__.snapshot)`
+  );
+  const hasHook = probe === "function";
+  if (!hasHook && (opts.forceInject || opts.autoInject)) {
+    if (opts.getInjectScript === void 0) {
       throw new Error(
-        `no snapshot cached yet at ${input.source.url}${detail ? `: ${detail}` : ""}`
+        "browser-mode snapshot: page has no window.__sightmap__ and no inject script provider was configured. Install @sightmap/react in the target app, or wire `getInjectScript` into the MCP server."
       );
     }
-    if (!res.ok) {
-      throw new Error(`snapshot fetch failed: HTTP ${res.status}`);
+    const script = await opts.getInjectScript();
+    const wrapped = `() => { ${script}
+; return typeof (window.__sightmap__ && window.__sightmap__.snapshot); }`;
+    const injectResult = await evalAndDecode(upstream, wrapped);
+    if (injectResult !== "function") {
+      throw new Error(
+        `browser-mode snapshot: inject script did not install window.__sightmap__.snapshot (typeof after inject: ${String(injectResult)}). The target page may not be a React app.`
+      );
     }
-    const snapshot = await res.json();
-    return { ok: true, snapshot, source: input.source };
+  } else if (!hasHook && opts.forceInject === false && opts.autoInject === false) {
+    throw new Error(
+      "browser-mode snapshot: page has no window.__sightmap__.snapshot and `inject: false` was set. Either install @sightmap/react in the app or pass `inject: true`."
+    );
   }
-  throw new Error(
-    "browser-driven snapshot capture is not implemented in 1.0-rc; use { kind: 'endpoint' } with the Vite plugin endpoint instead"
+  const snap = await evalAndDecode(
+    upstream,
+    `() => JSON.parse(JSON.stringify(window.__sightmap__.snapshot()))`
   );
+  return snap;
+}
+async function evalAndDecode(upstream, fnSource) {
+  const r = await upstream.callTool("browser_evaluate", { function: fnSource });
+  if (r.isError === true) {
+    throw new Error(
+      `browser_evaluate failed: ${r.content[0]?.text ?? "unknown error"}`
+    );
+  }
+  const text = r.content.map((b) => b.text).join("\n");
+  return decodeEvalText(text);
 }
+function decodeEvalText(text) {
+  const afterResult = text.split(/^###\s*Result/im)[1] ?? text;
+  const trimmed = afterResult.trim();
+  if (trimmed.length === 0) return void 0;
+  for (let end = trimmed.length; end > 0; end--) {
+    try {
+      return JSON.parse(trimmed.slice(0, end));
+    } catch {
+    }
+  }
+  return void 0;
+}
+
+// src/runtime/inject-script.ts
+import { createRequire } from "module";
+import { readFile as readFile6 } from "fs/promises";
+import { dirname, resolve as resolve3 } from "path";
+var cachedScript;
+async function getInjectScript() {
+  if (cachedScript !== void 0) return cachedScript;
+  const bippyIife = await loadBippyIife();
+  cachedScript = `${bippyIife}
+${BOOTSTRAP_SRC}`;
+  return cachedScript;
+}
+async function loadBippyIife() {
+  const require2 = createRequire(import.meta.url);
+  const bippyPkgJson = require2.resolve("bippy/package.json");
+  const iifePath = resolve3(dirname(bippyPkgJson), "dist/index.iife.js");
+  return readFile6(iifePath, "utf8");
+}
+var BOOTSTRAP_SRC = String.raw`
+(function () {
+  if (typeof window === "undefined") return;
+  if (!window.Bippy || typeof window.Bippy.instrument !== "function") return;
+  if (window.__sightmap__ && typeof window.__sightmap__.snapshot === "function") {
+    // Already installed (e.g. @sightmap/react is present). Don't double-wire.
+    return;
+  }
+
+  var trackedRoots = new Set();
+  window.Bippy.instrument({
+    onCommitFiberRoot: function (_id, root) {
+      trackedRoots.add(root);
+    },
+  });
+
+  var FRAMEWORK_NOISE = new Set([
+    "Routes", "Route", "RenderedRoute", "Outlet", "BrowserRouter",
+    "Router", "RouterProvider", "DataRouterProvider", "RouterProviderImpl",
+    "LinkWithRef", "StrictMode", "SightmapProvider", "Fragment", "Anonymous",
+    "Suspense", "ErrorBoundary", "Provider", "Consumer",
+    "ThemeProvider", "Hydration", "HydrateFallback",
+    "RemixErrorBoundary", "HydratedRouter", "DataRoutes",
+    "WithHydrateFallbackProps2", "RenderErrorBoundary", "Layout",
+  ]);
+
+  var HOST_PORTAL_TAG = 4;
+
+  function cssEsc(v) { return String(v).replace(/"/g, '\\"'); }
+  function isHumanShapedId(id) {
+    if (/[0-9]{6,}/.test(id)) return false;
+    if (/^[a-z]+-[a-f0-9]{8,}/i.test(id)) return false;
+    if (/:r[0-9a-z]+:/i.test(id)) return false;
+    return true;
+  }
+  function rankSelectors(el) {
+    var out = [];
+    var dsm = el.getAttribute("data-sightmap");
+    if (dsm !== null) {
+      out.push({ selector: '[data-sightmap="' + cssEsc(dsm) + '"]', stability: "high", source: "data-sightmap" });
+    }
+    ["data-testid", "data-cy", "data-test"].forEach(function (attr) {
+      var v = el.getAttribute(attr);
+      if (v !== null) {
+        out.push({ selector: "[" + attr + '="' + cssEsc(v) + '"]', stability: "high", source: attr });
+      }
+    });
+    var role = el.getAttribute("role");
+    var aria = el.getAttribute("aria-label");
+    if (role && aria) {
+      out.push({ selector: '[role="' + cssEsc(role) + '"][aria-label="' + cssEsc(aria) + '"]', stability: "medium", source: "aria" });
+    } else if (aria) {
+      out.push({ selector: '[aria-label="' + cssEsc(aria) + '"]', stability: "medium", source: "aria-label" });
+    }
+    var name = el.getAttribute("name");
+    if (name !== null && /^(form|input|button|select|textarea|nav)$/i.test(el.tagName)) {
+      out.push({ selector: el.tagName.toLowerCase() + '[name="' + cssEsc(name) + '"]', stability: "medium", source: "semantic-name" });
+    }
+    if (el.id && isHumanShapedId(el.id)) {
+      out.push({ selector: "#" + cssEsc(el.id), stability: "high", source: "id" });
+    }
+    return out;
+  }
+
+  function findHostElementForFiber(fiber) {
+    if (!fiber.child) return null;
+    var stack = [fiber.child];
+    var walks = 0;
+    while (stack.length > 0 && walks < 5000) {
+      walks++;
+      var f = stack.pop();
+      if (!f) continue;
+      if (f.sibling) stack.push(f.sibling);
+      if (f.tag === HOST_PORTAL_TAG) continue;
+      var sn = f.stateNode;
+      if (sn && typeof sn === "object" && "tagName" in sn && document.contains(sn)) {
+        return sn;
+      }
+      if (f.child) stack.push(f.child);
+    }
+    return null;
+  }
+
+  function bridgeDomToFiber(el) {
+    for (var i = 0, keys = Object.keys(el); i < keys.length; i++) {
+      if (keys[i].indexOf("__reactFiber$") === 0) return el[keys[i]] || null;
+    }
+    return null;
+  }
+
+  function nearestCompositeName(fiber) {
+    var f = fiber, walks = 0;
+    while (f && walks < 50) {
+      if (window.Bippy.isCompositeFiber(f)) {
+        var n = window.Bippy.getDisplayName(f);
+        if (n) return n;
+      }
+      f = f.return;
+      walks++;
+    }
+    return undefined;
+  }
+
+  function domDepth(el) {
+    var d = 0, cur = el.parentElement;
+    while (cur && cur !== document.body) { d++; cur = cur.parentElement; }
+    return d;
+  }
+
+  function collectComponents(rootFiber) {
+    var out = [];
+    var depthByFiber = new Map();
+    depthByFiber.set(rootFiber, 0);
+    window.Bippy.traverseFiber(rootFiber, function (f) {
+      var depth = depthByFiber.get(f) || 0;
+      var c = f.child;
+      while (c) { depthByFiber.set(c, depth + 1); c = c.sibling; }
+      if (!window.Bippy.isCompositeFiber(f)) return false;
+      var name = window.Bippy.getDisplayName(f);
+      if (!name) return false;
+      var childNames = [];
+      var cc = f.child;
+      while (cc) {
+        if (window.Bippy.isCompositeFiber(cc)) {
+          var n = window.Bippy.getDisplayName(cc);
+          if (n) childNames.push(n);
+        }
+        cc = cc.sibling;
+      }
+      out.push({ displayName: name, depth: depth, children: childNames });
+      return false;
+    });
+    return out;
+  }
+
+  function collectMarkers() {
+    var out = [];
+    if (typeof document === "undefined") return out;
+    var els = document.querySelectorAll("[data-sightmap]");
+    for (var i = 0; i < els.length; i++) {
+      var el = els[i];
+      var name = el.getAttribute("data-sightmap") || "";
+      var fiber = bridgeDomToFiber(el);
+      var nc = nearestCompositeName(fiber);
+      var marker = {
+        name: name,
+        hostTag: el.tagName.toLowerCase(),
+        domDepth: domDepth(el),
+        candidateSelectors: rankSelectors(el),
+      };
+      if (nc !== undefined) marker.nearestComponent = nc;
+      out.push(marker);
+    }
+    return out;
+  }
+
+  function collectUnmarkedCandidates(rootFiber) {
+    var out = [];
+    var seen = new Set();
+    window.Bippy.traverseFiber(rootFiber, function (f) {
+      if (!window.Bippy.isCompositeFiber(f)) return false;
+      var name = window.Bippy.getDisplayName(f);
+      if (!name || seen.has(name) || FRAMEWORK_NOISE.has(name)) return false;
+      seen.add(name);
+      var hostEl = findHostElementForFiber(f);
+      if (!hostEl) return false;
+      var selectors = rankSelectors(hostEl);
+      if (selectors.length === 0) return false;
+      out.push({
+        displayName: name,
+        hostTag: hostEl.tagName.toLowerCase(),
+        selectors: selectors,
+        domDepth: domDepth(hostEl),
+      });
+      return false;
+    });
+    return out;
+  }
+
+  function snapshot() {
+    var roots = Array.from(trackedRoots);
+    var now = new Date().toISOString();
+    var loc = (typeof window !== "undefined" && window.location)
+      ? (window.location.pathname + (window.location.search || ""))
+      : "?";
+    if (roots.length === 0) {
+      return { capturedAt: now, route: loc === "?" ? "?" : loc, commits: 0, components: [], markers: [], unmarkedCandidates: [] };
+    }
+    var root = roots.find(function (r) { return r.current && r.current.child !== null; }) || roots[0];
+    if (!root) {
+      return { capturedAt: now, route: loc === "?" ? "?" : loc, commits: 0, components: [], markers: [], unmarkedCandidates: [] };
+    }
+    var rootFiber = root.current;
+    return {
+      capturedAt: now,
+      route: loc,
+      commits: roots.length,
+      components: collectComponents(rootFiber),
+      markers: collectMarkers(),
+      unmarkedCandidates: collectUnmarkedCandidates(rootFiber),
+    };
+  }
+
+  window.__sightmap__ = { snapshot: snapshot };
+})();
+`;
 
 // src/tools/propose/store.ts
 var ProposalStore = class {
@@ -796,19 +1154,52 @@ var SIGHTMAP_ADD_VIEW = {
 };
 var SIGHTMAP_RUNTIME_SNAPSHOT = {
   name: "sightmap_runtime_snapshot",
-  description: "Fetch the live SightmapSnapshot from a running Vite dev server's /__sightmap__/snapshot.json endpoint. Pass { source: { kind: 'endpoint', url: 'http://localhost:5173/__sightmap__/snapshot.json' } }. The browser-driven (kind: 'browser') mode is reserved for future Playwright bridge support.",
+  description: "Fetch a SightmapSnapshot (fiber-tree introspection from bippy). Three sources:\n  - { kind: 'endpoint', url } \u2014 HTTP GET against the @sightmap/react Vite plugin endpoint (zero-config for Vite users).\n  - { kind: 'browser', url, routes?, inject? } \u2014 drive the live browser via @playwright/mcp; works on any React app (Webpack, RR 5.x, etc.) and, with `inject: true`, on apps that haven't installed @sightmap/react.\n  - { kind: 'literal', snapshot } \u2014 accept a pre-captured snapshot from any source (subtext live-eval-script, devtools console paste, custom Playwright scripts, CI capture). Validates the shape; returns it.",
   inputSchema: {
     type: "object",
     properties: {
       source: {
         type: "object",
-        properties: {
-          kind: { type: "string", enum: ["endpoint", "browser"] },
-          url: { type: "string" },
-          routes: { type: "array", items: { type: "string" } }
-        },
-        required: ["kind", "url"],
-        additionalProperties: false
+        oneOf: [
+          {
+            type: "object",
+            properties: {
+              kind: { type: "string", const: "endpoint" },
+              url: { type: "string", description: "Plugin endpoint URL, e.g. http://localhost:5173/__sightmap__/snapshot.json." }
+            },
+            required: ["kind", "url"],
+            additionalProperties: false
+          },
+          {
+            type: "object",
+            properties: {
+              kind: { type: "string", const: "browser" },
+              url: { type: "string", description: "Target URL to navigate to." },
+              routes: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of routes (absolute or relative to `url`) to capture in sequence."
+              },
+              inject: {
+                type: "boolean",
+                description: "When true, inject bippy + the snapshot bootstrap before navigation so non-@sightmap/react apps work. Omit to auto-inject only when the page lacks window.__sightmap__."
+              }
+            },
+            required: ["kind", "url"],
+            additionalProperties: false
+          },
+          {
+            type: "object",
+            properties: {
+              kind: { type: "string", const: "literal" },
+              snapshot: {
+                description: "A pre-captured SightmapSnapshot object. Must include capturedAt, route, components, markers, unmarkedCandidates."
+              }
+            },
+            required: ["kind", "snapshot"],
+            additionalProperties: false
+          }
+        ]
       }
     },
     required: ["source"],
@@ -1318,25 +1709,53 @@ var SightmapMcpServer = class {
       );
     }
     const s = source;
-    if (s["kind"] !== "endpoint" && s["kind"] !== "browser") {
-      return errorResult(
-        "sightmap_runtime_snapshot: `source.kind` must be 'endpoint' or 'browser'."
-      );
-    }
-    if (typeof s["url"] !== "string" || s["url"].length === 0) {
+    const kind = s["kind"];
+    if (kind !== "endpoint" && kind !== "browser" && kind !== "literal") {
       return errorResult(
-        "sightmap_runtime_snapshot: `source.url` (string) is required."
+        "sightmap_runtime_snapshot: `source.kind` must be 'endpoint', 'browser', or 'literal'."
       );
     }
-    const input = s["kind"] === "endpoint" ? { source: { kind: "endpoint", url: s["url"] } } : {
-      source: {
+    let input;
+    if (kind === "endpoint") {
+      if (typeof s["url"] !== "string" || s["url"].length === 0) {
+        return errorResult(
+          "sightmap_runtime_snapshot: endpoint mode requires `source.url` (string)."
+        );
+      }
+      input = { source: { kind: "endpoint", url: s["url"] } };
+    } else if (kind === "browser") {
+      if (typeof s["url"] !== "string" || s["url"].length === 0) {
+        return errorResult(
+          "sightmap_runtime_snapshot: browser mode requires `source.url` (string)."
+        );
+      }
+      const browserSrc = {
         kind: "browser",
-        url: s["url"],
-        ...Array.isArray(s["routes"]) ? { routes: s["routes"].filter((r) => typeof r === "string") } : {}
+        url: s["url"]
+      };
+      if (Array.isArray(s["routes"])) {
+        browserSrc.routes = s["routes"].filter(
+          (r) => typeof r === "string"
+        );
       }
-    };
+      if (typeof s["inject"] === "boolean") {
+        browserSrc.inject = s["inject"];
+      }
+      input = { source: browserSrc };
+    } else {
+      if (!("snapshot" in s)) {
+        return errorResult(
+          "sightmap_runtime_snapshot: literal mode requires `source.snapshot`."
+        );
+      }
+      input = { source: { kind: "literal", snapshot: s["snapshot"] } };
+    }
     try {
-      const result = await handleRuntimeSnapshot(input);
+      const deps = {
+        getInjectScript
+      };
+      if (this.upstream !== void 0) deps.upstream = this.upstream;
+      const result = await handleRuntimeSnapshot(input, deps);
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };