cdp-toolkit 1.0.0

package/src/tools/recorder.ts

@@ -0,0 +1,265 @@
+/**
+ * recorder.ts — the stateful console+network capture engine.
+ *
+ * RECORDER MODEL
+ * ==============
+ * A recorder holds ONE persistent page connection (via `openPage`, never closed
+ * until `stop()`), enables the relevant CDP domains, and appends every relevant
+ * event as a single-line JSON object ("JSON Lines") to a per-target buffer file:
+ *
+ *     ${ARTIFACT_DIR}/rec-<targetId>.jsonl
+ *
+ * Each line is one CDP event, wrapped with a discriminator so the console/network
+ * readers can cheaply filter the same file:
+ *
+ *     { "kind": "network" | "console", "method": "<CDP event>", "ts": <ms>, "params": { ... } }
+ *
+ * Domains enabled per option:
+ *   - network: Network.enable        -> Network.requestWillBeSent, .responseReceived,
+ *                                       .loadingFinished, .loadingFailed
+ *   - console: Runtime.enable        -> Runtime.consoleAPICalled, .exceptionThrown
+ *              Log.enable            -> Log.entryAdded   (browser-surfaced messages)
+ *
+ * CAPTURE MODEL (what the tool surface actually uses)
+ * ---------------------------------------------------
+ * The console/network tools drive `captureWindow()` — a one-shot reload capture
+ * that records BOTH domains into a UNIQUE per-capture file
+ * (`rec-<targetId>-<captureId>.jsonl`) and, on stop, publishes that capture as
+ * the target's shared "latest" buffer (`rec-<targetId>.jsonl`). Capturing both
+ * domains every time means a network capture never clobbers console history
+ * (and vice-versa); the per-capture file means two concurrent captures against
+ * the same target can't interleave into one another's results.
+ *
+ * BACKGROUND RECORDING (library-only)
+ * -----------------------------------
+ * `startRecorder({ truncate: false })` opens a long-lived appending recorder.
+ * This is reachable from the library API but NOT wired to a CLI tool (a stateless
+ * CLI process can't keep it alive across invocations); the CLI surface is
+ * reload-driven via `captureWindow`. `startRecorder` resolves only AFTER the CDP
+ * domains are enabled, so a caller can trigger navigation/reload immediately and
+ * be sure events are caught.
+ */
+import { mkdir, appendFile, writeFile, copyFile } from "node:fs/promises";
+import { openPage, resolveTarget } from "../client.ts";
+import type { CdpConnection } from "../client.ts";
+import type { Target, TargetSelector } from "../types.ts";
+
+/** Artifact / buffer directory (shared with the rest of the toolkit). */
+export const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+
+/** Compute the shared "latest" JSONL buffer path for a given targetId. */
+export function recFile(targetId: string): string {
+  return `${ARTIFACT_DIR}/rec-${targetId}.jsonl`;
+}
+
+/** Compute a unique per-capture JSONL buffer path (isolates concurrent captures). */
+export function captureFile(targetId: string, captureId: string): string {
+  return `${ARTIFACT_DIR}/rec-${targetId}-${captureId}.jsonl`;
+}
+
+/** Sleep helper (module runtime only; not the workflow-script sandbox). */
+function delay(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Network CDP events we persist. */
+const NETWORK_EVENTS = [
+  "Network.requestWillBeSent",
+  "Network.responseReceived",
+  "Network.loadingFinished",
+  "Network.loadingFailed",
+] as const;
+
+/** Console / log CDP events we persist. */
+const CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Log.entryAdded"] as const;
+
+/** A single persisted line in a rec-<targetId>.jsonl buffer. */
+export interface RecLine {
+  kind: "network" | "console";
+  method: string;
+  ts: number;
+  params: Record<string, unknown>;
+}
+
+export interface RecorderOptions {
+  /** Capture Network.* events (default true). */
+  network?: boolean;
+  /** Capture Runtime/Log console events (default true). */
+  console?: boolean;
+  /** Truncate the buffer file before recording (fresh capture window). */
+  truncate?: boolean;
+  /** Override the buffer file path (defaults to the shared recFile(targetId)). */
+  file?: string;
+  /** Per-command timeout override forwarded to the connection. */
+  timeoutMs?: number;
+}
+
+export interface RecorderHandle {
+  /** Await all in-flight appends WITHOUT closing the connection (so bodies stay fetchable). */
+  flush(): Promise<void>;
+  /** Flush, then close the connection (events stop, file stays). */
+  stop(): Promise<void>;
+  /** The JSONL buffer file being written. */
+  file: string;
+  /** The resolved target this recorder is attached to. */
+  target: Target;
+  /** The live connection (exposed so a one-shot caller can drive Page.reload on it). */
+  conn: CdpConnection;
+  /** Count of buffer-write failures observed (0 on a healthy capture). */
+  droppedWrites(): number;
+}
+
+/**
+ * Start a persistent recorder against `target`. Enables the requested domains
+ * and begins appending matching events to the per-target JSONL buffer. The
+ * returned handle's `stop()` closes the connection (events stop, file stays).
+ */
+export async function startRecorder(target: TargetSelector, opts: RecorderOptions = {}): Promise<RecorderHandle> {
+  const network = opts.network ?? true;
+  const consoleCap = opts.console ?? true;
+
+  await mkdir(ARTIFACT_DIR, { recursive: true });
+  const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
+  const file = opts.file ?? recFile(resolved.id);
+
+  if (opts.truncate) {
+    await writeFile(file, "");
+  }
+
+  // Serialize appends so concurrent events never interleave a partial line.
+  let chain: Promise<void> = Promise.resolve();
+  let dropped = 0;
+  const persist = (kind: RecLine["kind"], method: string, params: Record<string, unknown>): void => {
+    const line: RecLine = { kind, method, ts: Date.now(), params };
+    const text = `${JSON.stringify(line)}\n`;
+    chain = chain.then(() => appendFile(file, text)).catch(() => {
+      // Buffer-write failures are tolerated (capture is best-effort) but counted
+      // so callers can surface under-capture instead of silently returning fewer rows.
+      dropped += 1;
+    });
+  };
+
+  const unsubs: Array<() => void> = [];
+
+  try {
+    if (network) {
+      await conn.send("Network.enable");
+      for (const ev of NETWORK_EVENTS) {
+        unsubs.push(conn.on(ev, (params) => persist("network", ev, params)));
+      }
+    }
+    if (consoleCap) {
+      await conn.send("Runtime.enable");
+      // Log domain is optional on some targets; tolerate failure.
+      try {
+        await conn.send("Log.enable");
+      } catch {
+        /* Log not supported on this target type — Runtime events still flow */
+      }
+      for (const ev of CONSOLE_EVENTS) {
+        unsubs.push(conn.on(ev, (params) => persist("console", ev, params)));
+      }
+    }
+  } catch (err) {
+    conn.close();
+    throw err;
+  }
+
+  // Stop accepting new events, then let queued appends settle — without closing
+  // the connection (response bodies stay fetchable on `conn`).
+  const flush = async (): Promise<void> => {
+    for (const off of unsubs) off();
+    await chain;
+  };
+
+  return {
+    file,
+    target: resolved,
+    conn,
+    droppedWrites: () => dropped,
+    flush,
+    async stop(): Promise<void> {
+      await flush();
+      conn.close();
+    },
+  };
+}
+
+/**
+ * One-shot reload capture used by the console/network tools. Records BOTH
+ * domains into a unique per-capture file, reloads the page, waits `durationMs`,
+ * and (on stop) publishes the capture as the target's shared "latest" buffer.
+ * The returned handle keeps the connection open until `stop()`, so a caller can
+ * `flush()` then fetch response bodies before closing.
+ */
+export interface CaptureWindow {
+  /** The unique per-capture buffer file (read this for isolated results). */
+  file: string;
+  /** Live connection (open until stop) — for Network.getResponseBody etc. */
+  conn: CdpConnection;
+  /** Resolved target identity. */
+  resolved: { id: string; url: string; title: string };
+  /** Buffer-write failure count. */
+  droppedWrites(): number;
+  /** Await in-flight appends without closing (bodies stay fetchable). */
+  flush(): Promise<void>;
+  /** Flush, publish to the shared latest buffer, and close the connection. */
+  stop(): Promise<void>;
+}
+
+export async function captureWindow(
+  target: TargetSelector,
+  durationMs: number,
+  opts: { timeoutMs?: number } = {},
+): Promise<CaptureWindow> {
+  const resolved = await resolveTarget(target);
+  const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const file = captureFile(resolved.id, captureId);
+  // Record both domains so neither tool clobbers the other's history.
+  const rec = await startRecorder(resolved.id, {
+    network: true,
+    console: true,
+    truncate: true,
+    file,
+    timeoutMs: opts.timeoutMs,
+  });
+  await rec.conn.send("Page.enable");
+  await rec.conn.send("Page.reload", { ignoreCache: false });
+  await delay(durationMs);
+  return {
+    file: rec.file,
+    conn: rec.conn,
+    resolved: { id: rec.target.id, url: rec.target.url, title: rec.target.title },
+    droppedWrites: rec.droppedWrites,
+    flush: () => rec.flush(),
+    async stop(): Promise<void> {
+      await rec.stop();
+      // Publish this capture as the target's shared "latest" buffer (best-effort),
+      // so a later default (reload:false) read surfaces the most recent capture.
+      try {
+        await copyFile(rec.file, recFile(rec.target.id));
+      } catch {
+        /* shared-buffer publish is best-effort */
+      }
+    },
+  };
+}
+
+/*
+ * CDP methods / domains used:
+ *   Network.enable
+ *   Network.requestWillBeSent (event)
+ *   Network.responseReceived (event)
+ *   Network.loadingFinished (event)
+ *   Network.loadingFailed (event)
+ *   Runtime.enable
+ *   Runtime.consoleAPICalled (event)
+ *   Runtime.exceptionThrown (event)
+ *   Log.enable
+ *   Log.entryAdded (event)
+ *
+ * Parity gaps vs chrome-devtools-mcp:
+ *   - Buffering is to a per-target JSONL file on disk, not an in-memory ring; the
+ *     MCP keeps an in-process buffer scoped to its single managed page.
+ *   - No automatic resource-type / initiator enrichment beyond raw CDP params.
+ */

package/src/tools/screenshot.ts

@@ -0,0 +1,180 @@
+/**
+ * screenshot tool — `take_screenshot` over raw CDP.
+ *
+ * Captures the viewport, the full scrollable page, or a single element via
+ * Page.captureScreenshot. Full-page support computes the content size from
+ * Page.getLayoutMetrics and passes an explicit clip + captureBeyondViewport so
+ * we don't depend on Headless-only conveniences (Arc is headful). Element
+ * capture resolves the node (uid -> backendNodeId, or CSS selector) and clips
+ * to its box. Artifacts are written under ARTIFACT_DIR; the base64 bytes are
+ * only returned when explicitly requested.
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { CdpConnection } from "../client.ts";
+import { CdpError, withPage } from "../client.ts";
+import type { Target, TargetSelector, Uid } from "../types.ts";
+
+const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+
+export interface ScreenshotArgs {
+  target?: TargetSelector;
+  format?: "png" | "jpeg";
+  /** JPEG/quality 0-100. Ignored for png. */
+  quality?: number;
+  /** Capture the full scrollable content height, not just the viewport. */
+  fullPage?: boolean;
+  /** Element to clip to (a backendDOMNodeId). Mutually exclusive with selector. */
+  uid?: Uid;
+  /** CSS selector to clip to. Mutually exclusive with uid. */
+  selector?: string;
+  /** Override the artifact path. Default: ARTIFACT_DIR/<stamp>.<ext>. */
+  savePath?: string;
+  /** Also return the raw base64 image in the result. */
+  returnBase64?: boolean;
+}
+
+export interface ScreenshotResult {
+  path: string;
+  bytes: number;
+  format: "png" | "jpeg";
+  target: { id: string; url: string; title: string };
+  base64?: string;
+}
+
+interface Viewport {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  scale: number;
+}
+
+interface LayoutMetrics {
+  cssContentSize?: { x: number; y: number; width: number; height: number };
+  contentSize?: { x: number; y: number; width: number; height: number };
+  cssLayoutViewport?: { clientWidth: number; clientHeight: number };
+}
+
+interface BoxModel {
+  model: {
+    /** content quad: [x1,y1,x2,y2,x3,y3,x4,y4] (top-left, top-right, bottom-right, bottom-left). */
+    content: number[];
+    width: number;
+    height: number;
+  };
+}
+
+function shortId(id: string): string {
+  return id.slice(0, 8);
+}
+
+function stamp(): string {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+
+/** Compute a full-content clip from layout metrics (CSS pixels). */
+async function fullPageClip(conn: CdpConnection): Promise<Viewport> {
+  const m = await conn.send<LayoutMetrics>("Page.getLayoutMetrics");
+  const size = m.cssContentSize ?? m.contentSize;
+  if (!size) throw new CdpError("Page.getLayoutMetrics returned no content size");
+  return { x: 0, y: 0, width: Math.ceil(size.width), height: Math.ceil(size.height), scale: 1 };
+}
+
+/** Compute an element clip from its box model (uid or CSS selector). */
+async function elementClip(conn: CdpConnection, uid: Uid | undefined, selector: string | undefined): Promise<Viewport> {
+  let backendNodeId: number;
+  if (uid != null) {
+    backendNodeId = uid;
+  } else if (selector) {
+    const { root } = await conn.send<{ root: { nodeId: number } }>("DOM.getDocument", { depth: 0 });
+    const { nodeId } = await conn.send<{ nodeId: number }>("DOM.querySelector", {
+      nodeId: root.nodeId,
+      selector,
+    });
+    if (!nodeId) throw new CdpError(`selector matched no element: ${selector}`);
+    const desc = await conn.send<{ node: { backendNodeId: number } }>("DOM.describeNode", { nodeId });
+    backendNodeId = desc.node.backendNodeId;
+  } else {
+    throw new CdpError("elementClip requires uid or selector");
+  }
+
+  // Scroll the element into view so the clip is within the captured region.
+  try {
+    await conn.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
+  } catch {
+    /* not all builds expose this; box-model coordinates are absolute regardless */
+  }
+
+  const box = await conn.send<BoxModel>("DOM.getBoxModel", { backendNodeId });
+  const q = box.model.content;
+  const q0 = q[0];
+  const q1 = q[1];
+  if (q0 == null || q1 == null) throw new CdpError("DOM.getBoxModel returned an empty content quad");
+  const xs = [q[0], q[2], q[4], q[6]].filter((n): n is number => n != null);
+  const ys = [q[1], q[3], q[5], q[7]].filter((n): n is number => n != null);
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  const maxX = Math.max(...xs);
+  const maxY = Math.max(...ys);
+  const width = Math.ceil(maxX - minX);
+  const height = Math.ceil(maxY - minY);
+  if (width <= 0 || height <= 0) throw new CdpError("resolved element has zero area");
+  return { x: minX, y: minY, width, height, scale: 1 };
+}
+
+/**
+ * take_screenshot — capture viewport / full page / element to a file.
+ * Returns { path, bytes, format } (+ base64 when requested).
+ */
+export async function takeScreenshot(args: ScreenshotArgs = {}): Promise<ScreenshotResult> {
+  const { target, fullPage, uid, selector, savePath, returnBase64 } = args;
+  if (uid != null && selector) throw new CdpError("provide exactly one of uid or selector, not both");
+  const format: "png" | "jpeg" = args.format ?? "png";
+  const quality = format === "jpeg" ? (args.quality ?? 80) : undefined;
+
+  return withPage(target, async (conn: CdpConnection, t: Target) => {
+    await conn.send("Page.enable");
+
+    const params: Record<string, unknown> = { format, captureBeyondViewport: true };
+    if (quality != null) params.quality = quality;
+
+    if (uid != null || selector) {
+      params.clip = await elementClip(conn, uid, selector);
+    } else if (fullPage) {
+      params.clip = await fullPageClip(conn);
+    }
+
+    const { data } = await conn.send<{ data: string }>("Page.captureScreenshot", params);
+    const buf = Buffer.from(data, "base64");
+    if (buf.byteLength === 0) throw new CdpError("Page.captureScreenshot returned empty data");
+
+    await mkdir(ARTIFACT_DIR, { recursive: true });
+    const ext = format === "jpeg" ? "jpg" : "png";
+    const path = savePath ?? join(ARTIFACT_DIR, `screenshot-${shortId(t.id)}-${stamp()}.${ext}`);
+    await writeFile(path, buf);
+
+    const result: ScreenshotResult = {
+      path,
+      bytes: buf.byteLength,
+      format,
+      target: { id: t.id, url: t.url, title: t.title },
+    };
+    if (returnBase64) result.base64 = data;
+    return result;
+  });
+}
+
+/*
+ * CDP methods/domains used:
+ *   - Page.enable
+ *   - Page.captureScreenshot { format, quality, clip, captureBeyondViewport }
+ *   - Page.getLayoutMetrics            (full-page content clip)
+ *   - DOM.getDocument / DOM.querySelector / DOM.describeNode  (selector -> backendNodeId)
+ *   - DOM.scrollIntoViewIfNeeded       (best-effort, ignored if unsupported)
+ *   - DOM.getBoxModel                  (element clip)
+ * Parity gaps vs chrome-devtools-mcp take_screenshot:
+ *   - MCP refs are its own snapshot uids; here uid IS a backendDOMNodeId (toolkit ref scheme).
+ *   - No device-pixel upscaling control beyond emulation-set deviceScaleFactor (clip scale fixed at 1).
+ *   - Full-page on headful Arc relies on captureBeyondViewport + layout-metrics clip rather than headless auto-sizing.
+ */

package/src/tools/snapshot.ts

@@ -0,0 +1,206 @@
+/**
+ * Accessibility snapshot + the shared element-reference helper.
+ *
+ * The reference scheme (CONTRACT.md "The element-reference scheme"):
+ *   A `Uid` IS a CDP `backendDOMNodeId` (a number). Refs are therefore
+ *   stateless — `take_snapshot` emits them straight from the a11y tree, and
+ *   every interaction tool resolves them back to a live DOM node via
+ *   `DOM.resolveNode({ backendNodeId: uid })`. There is no server-side ref
+ *   table to drift or expire.
+ */
+import type { CdpConnection } from "../client.ts";
+import { withPage } from "../client.ts";
+import type { Target, TargetSelector, Uid } from "../types.ts";
+
+/* --------------------------- Accessibility AX types --------------------------- */
+
+interface AxValue {
+  type?: string;
+  value?: unknown;
+}
+
+interface AxProperty {
+  name: string;
+  value?: AxValue;
+}
+
+interface AxNode {
+  nodeId: string;
+  ignored?: boolean;
+  role?: AxValue;
+  name?: AxValue;
+  value?: AxValue;
+  description?: AxValue;
+  properties?: AxProperty[];
+  childIds?: string[];
+  backendDOMNodeId?: number;
+  parentId?: string;
+}
+
+/** Roles that are meaningful to a downstream agent driving the page. */
+const INTERACTIVE_ROLES = new Set<string>([
+  "button",
+  "link",
+  "textbox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "option",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "switch",
+  "slider",
+  "spinbutton",
+  "textfield",
+  "MenuItem",
+  "Button",
+]);
+
+function axString(v: AxValue | undefined): string | undefined {
+  if (!v) return undefined;
+  const raw = v.value;
+  if (raw === undefined || raw === null) return undefined;
+  const s = String(raw).trim();
+  return s.length ? s : undefined;
+}
+
+function propValue(node: AxNode, name: string): string | undefined {
+  const p = node.properties?.find((x) => x.name === name);
+  return axString(p?.value);
+}
+
+function isInteractive(role: string | undefined): boolean {
+  if (!role) return false;
+  return INTERACTIVE_ROLES.has(role) || INTERACTIVE_ROLES.has(role.toLowerCase());
+}
+
+/** Build the single-line summary for one AX node, or undefined to skip it. */
+function formatNode(node: AxNode, interactiveOnly: boolean): string | undefined {
+  const role = axString(node.role);
+  const name = axString(node.name);
+  const uid = node.backendDOMNodeId;
+
+  // Nodes without a backend DOM id cannot be referenced by interaction tools.
+  if (uid === undefined) return undefined;
+
+  if (interactiveOnly && !isInteractive(role)) return undefined;
+
+  // In full mode, skip structurally-empty generic containers (no role/name).
+  if (!interactiveOnly && !role && !name) return undefined;
+
+  const extras: string[] = [];
+  const value = axString(node.value);
+  if (value) extras.push(`value=${JSON.stringify(value)}`);
+  const checked = propValue(node, "checked");
+  if (checked && checked !== "false") extras.push(`checked=${checked}`);
+  const expanded = propValue(node, "expanded");
+  if (expanded) extras.push(`expanded=${expanded}`);
+  const disabled = propValue(node, "disabled");
+  if (disabled === "true") extras.push("disabled");
+  const url = propValue(node, "url");
+  if (url) extras.push(`url=${url}`);
+  const focused = propValue(node, "focused");
+  if (focused === "true") extras.push("focused");
+
+  const label = name ? ` ${JSON.stringify(name)}` : "";
+  const extra = extras.length ? ` [${extras.join(" ")}]` : "";
+  return `[${uid}] ${role ?? "generic"}${label}${extra}`;
+}
+
+export interface TakeSnapshotArgs {
+  target?: TargetSelector;
+  /** When true, emit only interactive/meaningful nodes (default false = full tree). */
+  interactiveOnly?: boolean;
+}
+
+export interface TakeSnapshotResult {
+  snapshot: string;
+  target: { id: string; url: string; title: string };
+  nodeCount: number;
+}
+
+/**
+ * take_snapshot — Accessibility.getFullAXTree walked into a compact indented
+ * text tree. Each emitted line carries the node's backendDOMNodeId as [uid],
+ * which interaction tools feed straight back to resolveUid.
+ */
+export async function takeSnapshot(args: TakeSnapshotArgs = {}): Promise<TakeSnapshotResult> {
+  const interactiveOnly = args.interactiveOnly ?? false;
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Accessibility.enable");
+    const { nodes } = await conn.send<{ nodes: AxNode[] }>("Accessibility.getFullAXTree");
+
+    const byId = new Map<string, AxNode>();
+    for (const n of nodes) byId.set(n.nodeId, n);
+
+    // Find roots: a node whose parentId is absent or not present in the set.
+    const roots = nodes.filter((n) => !n.parentId || !byId.has(n.parentId));
+
+    const lines: string[] = [];
+    let nodeCount = 0;
+
+    const walk = (node: AxNode, depth: number): void => {
+      const line = node.ignored ? undefined : formatNode(node, interactiveOnly);
+      // In interactiveOnly mode we keep tree depth flat for emitted nodes so the
+      // output stays readable; in full mode we preserve hierarchy via indent.
+      if (line !== undefined) {
+        const indent = interactiveOnly ? "" : "  ".repeat(depth);
+        lines.push(`${indent}${line}`);
+        nodeCount++;
+      }
+      const childDepth = line !== undefined && !interactiveOnly ? depth + 1 : depth;
+      for (const childId of node.childIds ?? []) {
+        const child = byId.get(childId);
+        if (child) walk(child, childDepth);
+      }
+    };
+
+    for (const root of roots) walk(root, 0);
+
+    return {
+      snapshot: lines.join("\n"),
+      target: { id: target.id, url: target.url, title: target.title },
+      nodeCount,
+    } satisfies TakeSnapshotResult;
+  });
+}
+
+/* ------------------------------ shared ref helper ------------------------------ */
+
+/**
+ * Resolve a Uid (backendDOMNodeId) to a live JS object handle. Shared by every
+ * interaction tool in input.ts. Throws if the node no longer exists.
+ */
+export async function resolveUid(conn: CdpConnection, uid: Uid): Promise<{ objectId: string }> {
+  const { object } = await conn.send<{ object: { objectId?: string } }>("DOM.resolveNode", {
+    backendNodeId: uid,
+  });
+  if (!object?.objectId) {
+    throw new Error(`resolveUid: DOM.resolveNode returned no objectId for uid ${uid}`);
+  }
+  return { objectId: object.objectId };
+}
+
+/**
+ * Internal helper exposed for input.ts: load the active page target so input
+ * tools can echo it back without re-resolving. Not part of the public tool set.
+ */
+export type SnapshotTarget = Pick<Target, "id" | "url" | "title">;
+
+/* ------------------------------------------------------------------------------
+ * CDP methods used:
+ *   Accessibility.enable, Accessibility.getFullAXTree (take_snapshot)
+ *   DOM.resolveNode                                   (resolveUid helper)
+ * Parity gaps vs chrome-devtools-mcp take_snapshot:
+ *   - MCP assigns sequential ref ids (1,2,3...) backed by a server-side handle
+ *     table; we instead expose the raw backendDOMNodeId as the uid (stateless,
+ *     but ids are larger / non-sequential and not human-friendly).
+ *   - MCP's snapshot includes a per-frame structure and a "more nodes" cursor;
+ *     this returns the full tree in one shot (frames flattened into one tree).
+ *   - interactiveOnly is our addition (flattens to interactive nodes only);
+ *     MCP always returns the structured tree.
+ * ---------------------------------------------------------------------------- */