feat(browser): add DOM inspection commands

src/browser/cdp.test.ts

@@ -3,7 +3,7 @@ import { createServer } from "node:http";
 import { afterEach, describe, expect, it } from "vitest";
 import { WebSocketServer } from "ws";
 
-import { createTargetViaCdp } from "./cdp.js";
+import { createTargetViaCdp, evaluateJavaScript, snapshotAria } from "./cdp.js";
 
 describe("cdp", () => {
   let httpServer: ReturnType<typeof createServer> | null = null;
@@ -70,4 +70,93 @@ describe("cdp", () => {
 
     expect(created.targetId).toBe("TARGET_123");
   });
+
+  it("evaluates javascript via CDP", async () => {
+    wsServer = new WebSocketServer({ port: 0, host: "127.0.0.1" });
+    await new Promise<void>((resolve) => wsServer?.once("listening", resolve));
+    const wsPort = (wsServer.address() as { port: number }).port;
+
+    wsServer.on("connection", (socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(String(data)) as {
+          id?: number;
+          method?: string;
+          params?: { expression?: string };
+        };
+        if (msg.method === "Runtime.enable") {
+          socket.send(JSON.stringify({ id: msg.id, result: {} }));
+          return;
+        }
+        if (msg.method === "Runtime.evaluate") {
+          expect(msg.params?.expression).toBe("1+1");
+          socket.send(
+            JSON.stringify({
+              id: msg.id,
+              result: { result: { type: "number", value: 2 } },
+            }),
+          );
+        }
+      });
+    });
+
+    const res = await evaluateJavaScript({
+      wsUrl: `ws://127.0.0.1:${wsPort}`,
+      expression: "1+1",
+    });
+
+    expect(res.result.type).toBe("number");
+    expect(res.result.value).toBe(2);
+  });
+
+  it("captures an aria snapshot via CDP", async () => {
+    wsServer = new WebSocketServer({ port: 0, host: "127.0.0.1" });
+    await new Promise<void>((resolve) => wsServer?.once("listening", resolve));
+    const wsPort = (wsServer.address() as { port: number }).port;
+
+    wsServer.on("connection", (socket) => {
+      socket.on("message", (data) => {
+        const msg = JSON.parse(String(data)) as {
+          id?: number;
+          method?: string;
+        };
+        if (msg.method === "Accessibility.enable") {
+          socket.send(JSON.stringify({ id: msg.id, result: {} }));
+          return;
+        }
+        if (msg.method === "Accessibility.getFullAXTree") {
+          socket.send(
+            JSON.stringify({
+              id: msg.id,
+              result: {
+                nodes: [
+                  {
+                    nodeId: "1",
+                    role: { value: "RootWebArea" },
+                    name: { value: "" },
+                    childIds: ["2"],
+                  },
+                  {
+                    nodeId: "2",
+                    role: { value: "button" },
+                    name: { value: "OK" },
+                    backendDOMNodeId: 42,
+                    childIds: [],
+                  },
+                ],
+              },
+            }),
+          );
+          return;
+        }
+      });
+    });
+
+    const snap = await snapshotAria({ wsUrl: `ws://127.0.0.1:${wsPort}` });
+    expect(snap.nodes.length).toBe(2);
+    expect(snap.nodes[0]?.role).toBe("RootWebArea");
+    expect(snap.nodes[1]?.role).toBe("button");
+    expect(snap.nodes[1]?.name).toBe("OK");
+    expect(snap.nodes[1]?.backendDOMNodeId).toBe(42);
+    expect(snap.nodes[1]?.depth).toBe(1);
+  });
 });

src/browser/cdp.ts

@@ -78,6 +78,34 @@ async function fetchJson<T>(url: string, timeoutMs = 1500): Promise<T> {
   }
 }
 
+async function withCdpSocket<T>(
+  wsUrl: string,
+  fn: (send: CdpSendFn) => Promise<T>,
+): Promise<T> {
+  const ws = new WebSocket(wsUrl, { handshakeTimeout: 5000 });
+  const { send, closeWithError } = createCdpSender(ws);
+
+  const openPromise = new Promise<void>((resolve, reject) => {
+    ws.once("open", () => resolve());
+    ws.once("error", (err) => reject(err));
+  });
+
+  await openPromise;
+
+  try {
+    return await fn(send);
+  } catch (err) {
+    closeWithError(err instanceof Error ? err : new Error(String(err)));
+    throw err;
+  } finally {
+    try {
+      ws.close();
+    } catch {
+      // ignore
+    }
+  }
+}
+
 export async function captureScreenshotPng(opts: {
   wsUrl: string;
   fullPage?: boolean;
@@ -95,61 +123,43 @@ export async function captureScreenshot(opts: {
   format?: "png" | "jpeg";
   quality?: number; // jpeg only (0..100)
 }): Promise<Buffer> {
-  const ws = new WebSocket(opts.wsUrl, { handshakeTimeout: 5000 });
-  const { send, closeWithError } = createCdpSender(ws);
+  return await withCdpSocket(opts.wsUrl, async (send) => {
+    await send("Page.enable");
 
-  const openPromise = new Promise<void>((resolve, reject) => {
-    ws.once("open", () => resolve());
-    ws.once("error", (err) => reject(err));
-  });
-
-  await openPromise;
-
-  await send("Page.enable");
-
-  let clip:
-    | { x: number; y: number; width: number; height: number; scale: number }
-    | undefined;
-  if (opts.fullPage) {
-    const metrics = (await send("Page.getLayoutMetrics")) as {
-      cssContentSize?: { width?: number; height?: number };
-      contentSize?: { width?: number; height?: number };
-    };
-    const size = metrics?.cssContentSize ?? metrics?.contentSize;
-    const width = Number(size?.width ?? 0);
-    const height = Number(size?.height ?? 0);
-    if (width > 0 && height > 0) {
-      clip = { x: 0, y: 0, width, height, scale: 1 };
+    let clip:
+      | { x: number; y: number; width: number; height: number; scale: number }
+      | undefined;
+    if (opts.fullPage) {
+      const metrics = (await send("Page.getLayoutMetrics")) as {
+        cssContentSize?: { width?: number; height?: number };
+        contentSize?: { width?: number; height?: number };
+      };
+      const size = metrics?.cssContentSize ?? metrics?.contentSize;
+      const width = Number(size?.width ?? 0);
+      const height = Number(size?.height ?? 0);
+      if (width > 0 && height > 0) {
+        clip = { x: 0, y: 0, width, height, scale: 1 };
+      }
     }
-  }
 
-  const format = opts.format ?? "png";
-  const quality =
-    format === "jpeg"
-      ? Math.max(0, Math.min(100, Math.round(opts.quality ?? 85)))
-      : undefined;
+    const format = opts.format ?? "png";
+    const quality =
+      format === "jpeg"
+        ? Math.max(0, Math.min(100, Math.round(opts.quality ?? 85)))
+        : undefined;
 
-  const result = (await send("Page.captureScreenshot", {
-    format,
-    ...(quality !== undefined ? { quality } : {}),
-    fromSurface: true,
-    captureBeyondViewport: true,
-    ...(clip ? { clip } : {}),
-  })) as { data?: string };
+    const result = (await send("Page.captureScreenshot", {
+      format,
+      ...(quality !== undefined ? { quality } : {}),
+      fromSurface: true,
+      captureBeyondViewport: true,
+      ...(clip ? { clip } : {}),
+    })) as { data?: string };
 
-  const base64 = result?.data;
-  if (!base64) {
-    closeWithError(new Error("Screenshot failed: missing data"));
-    throw new Error("Screenshot failed: missing data");
-  }
-
-  try {
-    ws.close();
-  } catch {
-    // ignore
-  }
-
-  return Buffer.from(base64, "base64");
+    const base64 = result?.data;
+    if (!base64) throw new Error("Screenshot failed: missing data");
+    return Buffer.from(base64, "base64");
+  });
 }
 
 export async function createTargetViaCdp(opts: {
@@ -163,30 +173,348 @@ export async function createTargetViaCdp(opts: {
   const wsUrl = String(version?.webSocketDebuggerUrl ?? "").trim();
   if (!wsUrl) throw new Error("CDP /json/version missing webSocketDebuggerUrl");
 
-  const ws = new WebSocket(wsUrl, { handshakeTimeout: 5000 });
-  const { send, closeWithError } = createCdpSender(ws);
-
-  const openPromise = new Promise<void>((resolve, reject) => {
-    ws.once("open", () => resolve());
-    ws.once("error", (err) => reject(err));
+  return await withCdpSocket(wsUrl, async (send) => {
+    const created = (await send("Target.createTarget", { url: opts.url })) as {
+      targetId?: string;
+    };
+    const targetId = String(created?.targetId ?? "").trim();
+    if (!targetId)
+      throw new Error("CDP Target.createTarget returned no targetId");
+    return { targetId };
   });
-
-  await openPromise;
-
-  const created = (await send("Target.createTarget", { url: opts.url })) as {
-    targetId?: string;
-  };
-  const targetId = String(created?.targetId ?? "").trim();
-  if (!targetId) {
-    closeWithError(new Error("CDP Target.createTarget returned no targetId"));
-    throw new Error("CDP Target.createTarget returned no targetId");
-  }
-
-  try {
-    ws.close();
-  } catch {
-    // ignore
-  }
-
-  return { targetId };
 }
+
+export type CdpRemoteObject = {
+  type: string;
+  subtype?: string;
+  value?: unknown;
+  description?: string;
+  unserializableValue?: string;
+  preview?: unknown;
+};
+
+export type CdpExceptionDetails = {
+  text?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+  exception?: CdpRemoteObject;
+  stackTrace?: unknown;
+};
+
+export async function evaluateJavaScript(opts: {
+  wsUrl: string;
+  expression: string;
+  awaitPromise?: boolean;
+  returnByValue?: boolean;
+}): Promise<{
+  result: CdpRemoteObject;
+  exceptionDetails?: CdpExceptionDetails;
+}> {
+  return await withCdpSocket(opts.wsUrl, async (send) => {
+    await send("Runtime.enable").catch(() => {});
+    const evaluated = (await send("Runtime.evaluate", {
+      expression: opts.expression,
+      awaitPromise: Boolean(opts.awaitPromise),
+      returnByValue: opts.returnByValue ?? true,
+      userGesture: true,
+      includeCommandLineAPI: true,
+    })) as {
+      result?: CdpRemoteObject;
+      exceptionDetails?: CdpExceptionDetails;
+    };
+
+    const result = evaluated?.result;
+    if (!result) throw new Error("CDP Runtime.evaluate returned no result");
+    return { result, exceptionDetails: evaluated.exceptionDetails };
+  });
+}
+
+export type AriaSnapshotNode = {
+  ref: string;
+  role: string;
+  name: string;
+  value?: string;
+  description?: string;
+  backendDOMNodeId?: number;
+  depth: number;
+};
+
+type RawAXNode = {
+  nodeId?: string;
+  role?: { value?: string };
+  name?: { value?: string };
+  value?: { value?: string };
+  description?: { value?: string };
+  childIds?: string[];
+  backendDOMNodeId?: number;
+};
+
+function axValue(v: unknown): string {
+  if (!v || typeof v !== "object") return "";
+  const value = (v as { value?: unknown }).value;
+  return typeof value === "string" ? value : String(value ?? "");
+}
+
+function formatAriaSnapshot(
+  nodes: RawAXNode[],
+  limit: number,
+): AriaSnapshotNode[] {
+  const byId = new Map<string, RawAXNode>();
+  for (const n of nodes) {
+    if (n.nodeId) byId.set(n.nodeId, n);
+  }
+
+  // Heuristic: pick a root-ish node (one that is not referenced as a child), else first.
+  const referenced = new Set<string>();
+  for (const n of nodes) {
+    for (const c of n.childIds ?? []) referenced.add(c);
+  }
+  const root =
+    nodes.find((n) => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
+  if (!root?.nodeId) return [];
+
+  const out: AriaSnapshotNode[] = [];
+  const stack: Array<{ id: string; depth: number }> = [
+    { id: root.nodeId, depth: 0 },
+  ];
+  while (stack.length && out.length < limit) {
+    const popped = stack.pop();
+    if (!popped) break;
+    const { id, depth } = popped;
+    const n = byId.get(id);
+    if (!n) continue;
+    const role = axValue(n.role);
+    const name = axValue(n.name);
+    const value = axValue(n.value);
+    const description = axValue(n.description);
+    const ref = `ax${out.length + 1}`;
+    out.push({
+      ref,
+      role: role || "unknown",
+      name: name || "",
+      ...(value ? { value } : {}),
+      ...(description ? { description } : {}),
+      ...(typeof n.backendDOMNodeId === "number"
+        ? { backendDOMNodeId: n.backendDOMNodeId }
+        : {}),
+      depth,
+    });
+
+    const children = (n.childIds ?? []).filter((c) => byId.has(c));
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+      if (child) stack.push({ id: child, depth: depth + 1 });
+    }
+  }
+
+  return out;
+}
+
+export async function snapshotAria(opts: {
+  wsUrl: string;
+  limit?: number;
+}): Promise<{ nodes: AriaSnapshotNode[] }> {
+  const limit = Math.max(1, Math.min(2000, Math.floor(opts.limit ?? 500)));
+  return await withCdpSocket(opts.wsUrl, async (send) => {
+    await send("Accessibility.enable").catch(() => {});
+    const res = (await send("Accessibility.getFullAXTree")) as {
+      nodes?: RawAXNode[];
+    };
+    const nodes = Array.isArray(res?.nodes) ? res.nodes : [];
+    return { nodes: formatAriaSnapshot(nodes, limit) };
+  });
+}
+
+export async function snapshotDom(opts: {
+  wsUrl: string;
+  limit?: number;
+  maxTextChars?: number;
+}): Promise<{
+  nodes: DomSnapshotNode[];
+}> {
+  const limit = Math.max(1, Math.min(5000, Math.floor(opts.limit ?? 800)));
+  const maxTextChars = Math.max(
+    0,
+    Math.min(5000, Math.floor(opts.maxTextChars ?? 220)),
+  );
+
+  const expression = `(() => {
+    const maxNodes = ${JSON.stringify(limit)};
+    const maxText = ${JSON.stringify(maxTextChars)};
+    const nodes = [];
+    const root = document.documentElement;
+    if (!root) return { nodes };
+    const stack = [{ el: root, depth: 0, parentRef: null }];
+    while (stack.length && nodes.length < maxNodes) {
+      const cur = stack.pop();
+      const el = cur.el;
+      if (!el || el.nodeType !== 1) continue;
+      const ref = "n" + String(nodes.length + 1);
+      const tag = (el.tagName || "").toLowerCase();
+      const id = el.id ? String(el.id) : undefined;
+      const className = el.className ? String(el.className).slice(0, 300) : undefined;
+      const role = el.getAttribute && el.getAttribute("role") ? String(el.getAttribute("role")) : undefined;
+      const name = el.getAttribute && el.getAttribute("aria-label") ? String(el.getAttribute("aria-label")) : undefined;
+      let text = "";
+      try { text = String(el.innerText || "").trim(); } catch {}
+      if (maxText && text.length > maxText) text = text.slice(0, maxText) + "…";
+      const href = (el.href !== undefined && el.href !== null) ? String(el.href) : undefined;
+      const type = (el.type !== undefined && el.type !== null) ? String(el.type) : undefined;
+      const value = (el.value !== undefined && el.value !== null) ? String(el.value).slice(0, 500) : undefined;
+      nodes.push({
+        ref,
+        parentRef: cur.parentRef,
+        depth: cur.depth,
+        tag,
+        ...(id ? { id } : {}),
+        ...(className ? { className } : {}),
+        ...(role ? { role } : {}),
+        ...(name ? { name } : {}),
+        ...(text ? { text } : {}),
+        ...(href ? { href } : {}),
+        ...(type ? { type } : {}),
+        ...(value ? { value } : {}),
+      });
+      const children = el.children ? Array.from(el.children) : [];
+      for (let i = children.length - 1; i >= 0; i--) {
+        stack.push({ el: children[i], depth: cur.depth + 1, parentRef: ref });
+      }
+    }
+    return { nodes };
+  })()`;
+
+  const evaluated = await evaluateJavaScript({
+    wsUrl: opts.wsUrl,
+    expression,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  const value = evaluated.result?.value as unknown;
+  if (!value || typeof value !== "object") return { nodes: [] };
+  const nodes = (value as { nodes?: unknown }).nodes;
+  return { nodes: Array.isArray(nodes) ? (nodes as DomSnapshotNode[]) : [] };
+}
+
+export type DomSnapshotNode = {
+  ref: string;
+  parentRef: string | null;
+  depth: number;
+  tag: string;
+  id?: string;
+  className?: string;
+  role?: string;
+  name?: string;
+  text?: string;
+  href?: string;
+  type?: string;
+  value?: string;
+};
+
+export async function getDomText(opts: {
+  wsUrl: string;
+  format: "html" | "text";
+  maxChars?: number;
+  selector?: string;
+}): Promise<{ text: string }> {
+  const maxChars = Math.max(
+    0,
+    Math.min(5_000_000, Math.floor(opts.maxChars ?? 200_000)),
+  );
+  const selectorExpr = opts.selector ? JSON.stringify(opts.selector) : "null";
+  const expression = `(() => {
+    const fmt = ${JSON.stringify(opts.format)};
+    const max = ${JSON.stringify(maxChars)};
+    const sel = ${selectorExpr};
+    const pick = sel ? document.querySelector(sel) : null;
+    let out = "";
+    if (fmt === "text") {
+      const el = pick || document.body || document.documentElement;
+      try { out = String(el && el.innerText ? el.innerText : ""); } catch { out = ""; }
+    } else {
+      const el = pick || document.documentElement;
+      try { out = String(el && el.outerHTML ? el.outerHTML : ""); } catch { out = ""; }
+    }
+    if (max && out.length > max) out = out.slice(0, max) + "\\n<!-- …truncated… -->";
+    return out;
+  })()`;
+
+  const evaluated = await evaluateJavaScript({
+    wsUrl: opts.wsUrl,
+    expression,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  const text = String(evaluated.result?.value ?? "");
+  return { text };
+}
+
+export async function querySelector(opts: {
+  wsUrl: string;
+  selector: string;
+  limit?: number;
+  maxTextChars?: number;
+  maxHtmlChars?: number;
+}): Promise<{
+  matches: QueryMatch[];
+}> {
+  const limit = Math.max(1, Math.min(200, Math.floor(opts.limit ?? 20)));
+  const maxText = Math.max(
+    0,
+    Math.min(5000, Math.floor(opts.maxTextChars ?? 500)),
+  );
+  const maxHtml = Math.max(
+    0,
+    Math.min(20000, Math.floor(opts.maxHtmlChars ?? 1500)),
+  );
+
+  const expression = `(() => {
+    const sel = ${JSON.stringify(opts.selector)};
+    const lim = ${JSON.stringify(limit)};
+    const maxText = ${JSON.stringify(maxText)};
+    const maxHtml = ${JSON.stringify(maxHtml)};
+    const els = Array.from(document.querySelectorAll(sel)).slice(0, lim);
+    return els.map((el, i) => {
+      const tag = (el.tagName || "").toLowerCase();
+      const id = el.id ? String(el.id) : undefined;
+      const className = el.className ? String(el.className).slice(0, 300) : undefined;
+      let text = "";
+      try { text = String(el.innerText || "").trim(); } catch {}
+      if (maxText && text.length > maxText) text = text.slice(0, maxText) + "…";
+      const value = (el.value !== undefined && el.value !== null) ? String(el.value).slice(0, 500) : undefined;
+      const href = (el.href !== undefined && el.href !== null) ? String(el.href) : undefined;
+      let outerHTML = "";
+      try { outerHTML = String(el.outerHTML || ""); } catch {}
+      if (maxHtml && outerHTML.length > maxHtml) outerHTML = outerHTML.slice(0, maxHtml) + "…";
+      return {
+        index: i + 1,
+        tag,
+        ...(id ? { id } : {}),
+        ...(className ? { className } : {}),
+        ...(text ? { text } : {}),
+        ...(value ? { value } : {}),
+        ...(href ? { href } : {}),
+        ...(outerHTML ? { outerHTML } : {}),
+      };
+    });
+  })()`;
+
+  const evaluated = await evaluateJavaScript({
+    wsUrl: opts.wsUrl,
+    expression,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  const matches = evaluated.result?.value;
+  return { matches: Array.isArray(matches) ? (matches as QueryMatch[]) : [] };
+}
+
+export type QueryMatch = {
+  index: number;
+  tag: string;
+  id?: string;
+  className?: string;
+  text?: string;
+  value?: string;
+  href?: string;
+  outerHTML?: string;
+};

src/browser/client.ts

@@ -28,6 +28,83 @@ export type ScreenshotResult = {
   url: string;
 };
 
+export type EvalResult = {
+  ok: true;
+  targetId: string;
+  url: string;
+  result: {
+    type: string;
+    subtype?: string;
+    value?: unknown;
+    description?: string;
+    unserializableValue?: string;
+    preview?: unknown;
+  };
+};
+
+export type QueryResult = {
+  ok: true;
+  targetId: string;
+  url: string;
+  matches: Array<{
+    index: number;
+    tag: string;
+    id?: string;
+    className?: string;
+    text?: string;
+    value?: string;
+    href?: string;
+    outerHTML?: string;
+  }>;
+};
+
+export type DomResult = {
+  ok: true;
+  targetId: string;
+  url: string;
+  format: "html" | "text";
+  text: string;
+};
+
+export type SnapshotAriaNode = {
+  ref: string;
+  role: string;
+  name: string;
+  value?: string;
+  description?: string;
+  backendDOMNodeId?: number;
+  depth: number;
+};
+
+export type SnapshotResult =
+  | {
+      ok: true;
+      format: "aria";
+      targetId: string;
+      url: string;
+      nodes: SnapshotAriaNode[];
+    }
+  | {
+      ok: true;
+      format: "domSnapshot";
+      targetId: string;
+      url: string;
+      nodes: Array<{
+        ref: string;
+        parentRef: string | null;
+        depth: number;
+        tag: string;
+        id?: string;
+        className?: string;
+        role?: string;
+        name?: string;
+        text?: string;
+        href?: string;
+        type?: string;
+        value?: string;
+      }>;
+    };
+
 function unwrapCause(err: unknown): unknown {
   if (!err || typeof err !== "object") return null;
   const cause = (err as { cause?: unknown }).cause;
@@ -172,3 +249,80 @@ export async function browserScreenshot(
     timeoutMs: 20000,
   });
 }
+
+export async function browserEval(
+  baseUrl: string,
+  opts: {
+    js: string;
+    targetId?: string;
+    awaitPromise?: boolean;
+  },
+): Promise<EvalResult> {
+  return await fetchJson<EvalResult>(`${baseUrl}/eval`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      js: opts.js,
+      targetId: opts.targetId,
+      await: Boolean(opts.awaitPromise),
+    }),
+    timeoutMs: 15000,
+  });
+}
+
+export async function browserQuery(
+  baseUrl: string,
+  opts: {
+    selector: string;
+    targetId?: string;
+    limit?: number;
+  },
+): Promise<QueryResult> {
+  const q = new URLSearchParams();
+  q.set("selector", opts.selector);
+  if (opts.targetId) q.set("targetId", opts.targetId);
+  if (typeof opts.limit === "number") q.set("limit", String(opts.limit));
+  return await fetchJson<QueryResult>(`${baseUrl}/query?${q.toString()}`, {
+    timeoutMs: 15000,
+  });
+}
+
+export async function browserDom(
+  baseUrl: string,
+  opts: {
+    format: "html" | "text";
+    targetId?: string;
+    maxChars?: number;
+    selector?: string;
+  },
+): Promise<DomResult> {
+  const q = new URLSearchParams();
+  q.set("format", opts.format);
+  if (opts.targetId) q.set("targetId", opts.targetId);
+  if (typeof opts.maxChars === "number")
+    q.set("maxChars", String(opts.maxChars));
+  if (opts.selector) q.set("selector", opts.selector);
+  return await fetchJson<DomResult>(`${baseUrl}/dom?${q.toString()}`, {
+    timeoutMs: 20000,
+  });
+}
+
+export async function browserSnapshot(
+  baseUrl: string,
+  opts: {
+    format: "aria" | "domSnapshot";
+    targetId?: string;
+    limit?: number;
+  },
+): Promise<SnapshotResult> {
+  const q = new URLSearchParams();
+  q.set("format", opts.format);
+  if (opts.targetId) q.set("targetId", opts.targetId);
+  if (typeof opts.limit === "number") q.set("limit", String(opts.limit));
+  return await fetchJson<SnapshotResult>(
+    `${baseUrl}/snapshot?${q.toString()}`,
+    {
+      timeoutMs: 20000,
+    },
+  );
+}

src/browser/server.ts

@@ -10,6 +10,11 @@ import {
   captureScreenshot,
   captureScreenshotPng,
   createTargetViaCdp,
+  evaluateJavaScript,
+  getDomText,
+  querySelector,
+  snapshotAria,
+  snapshotDom,
 } from "./cdp.js";
 import {
   isChromeReachable,
@@ -178,6 +183,34 @@ async function ensureBrowserAvailable(runtime: RuntimeEnv): Promise<void> {
   return;
 }
 
+async function ensureTabAvailable(runtime: RuntimeEnv, targetId?: string) {
+  if (!state) throw new Error("Browser server not started");
+  await ensureBrowserAvailable(runtime);
+
+  const tabs1 = await listTabs(state.cdpPort);
+  if (tabs1.length === 0) {
+    await openTab(state.cdpPort, "about:blank");
+  }
+
+  const tabs = await listTabs(state.cdpPort);
+  const chosen = targetId
+    ? (() => {
+        const resolved = resolveTargetIdFromTabs(targetId, tabs);
+        if (!resolved.ok) {
+          if (resolved.reason === "ambiguous") return "AMBIGUOUS" as const;
+          return null;
+        }
+        return tabs.find((t) => t.targetId === resolved.targetId) ?? null;
+      })()
+    : (tabs.at(0) ?? null);
+
+  if (chosen === "AMBIGUOUS") {
+    throw new Error("ambiguous target id prefix");
+  }
+  if (!chosen?.wsUrl) throw new Error("tab not found");
+  return chosen;
+}
+
 export async function startBrowserControlServerFromConfig(
   runtime: RuntimeEnv = defaultRuntime,
 ): Promise<BrowserServerState | null> {
@@ -374,6 +407,160 @@ export async function startBrowserControlServerFromConfig(
     }
   });
 
+  function mapTabError(err: unknown) {
+    const msg = String(err);
+    if (msg.includes("ambiguous target id prefix")) {
+      return { status: 409, message: "ambiguous target id prefix" };
+    }
+    if (msg.includes("tab not found")) {
+      return { status: 404, message: "tab not found" };
+    }
+    return null;
+  }
+
+  app.post("/eval", async (req, res) => {
+    if (!state) return jsonError(res, 503, "browser server not started");
+    const js = String((req.body as { js?: unknown })?.js ?? "").trim();
+    const targetId = String(
+      (req.body as { targetId?: unknown })?.targetId ?? "",
+    ).trim();
+    const awaitPromise = Boolean((req.body as { await?: unknown })?.await);
+
+    if (!js) return jsonError(res, 400, "js is required");
+
+    try {
+      const tab = await ensureTabAvailable(runtime, targetId || undefined);
+      const evaluated = await evaluateJavaScript({
+        wsUrl: tab.wsUrl ?? "",
+        expression: js,
+        awaitPromise,
+        returnByValue: true,
+      });
+
+      if (evaluated.exceptionDetails) {
+        const msg =
+          evaluated.exceptionDetails.exception?.description ||
+          evaluated.exceptionDetails.text ||
+          "JavaScript evaluation failed";
+        return jsonError(res, 400, msg);
+      }
+
+      res.json({
+        ok: true,
+        targetId: tab.targetId,
+        url: tab.url,
+        result: evaluated.result,
+      });
+    } catch (err) {
+      const mapped = mapTabError(err);
+      if (mapped) return jsonError(res, mapped.status, mapped.message);
+      jsonError(res, 500, String(err));
+    }
+  });
+
+  app.get("/query", async (req, res) => {
+    if (!state) return jsonError(res, 503, "browser server not started");
+    const selector =
+      typeof req.query.selector === "string" ? req.query.selector.trim() : "";
+    const targetId =
+      typeof req.query.targetId === "string" ? req.query.targetId.trim() : "";
+    const limit =
+      typeof req.query.limit === "string" ? Number(req.query.limit) : undefined;
+
+    if (!selector) return jsonError(res, 400, "selector is required");
+
+    try {
+      const tab = await ensureTabAvailable(runtime, targetId || undefined);
+      const result = await querySelector({
+        wsUrl: tab.wsUrl ?? "",
+        selector,
+        limit,
+      });
+      res.json({ ok: true, targetId: tab.targetId, url: tab.url, ...result });
+    } catch (err) {
+      const mapped = mapTabError(err);
+      if (mapped) return jsonError(res, mapped.status, mapped.message);
+      jsonError(res, 500, String(err));
+    }
+  });
+
+  app.get("/dom", async (req, res) => {
+    if (!state) return jsonError(res, 503, "browser server not started");
+    const targetId =
+      typeof req.query.targetId === "string" ? req.query.targetId.trim() : "";
+    const format = req.query.format === "text" ? "text" : "html";
+    const selector =
+      typeof req.query.selector === "string" ? req.query.selector.trim() : "";
+    const maxChars =
+      typeof req.query.maxChars === "string"
+        ? Number(req.query.maxChars)
+        : undefined;
+
+    try {
+      const tab = await ensureTabAvailable(runtime, targetId || undefined);
+      const result = await getDomText({
+        wsUrl: tab.wsUrl ?? "",
+        format,
+        maxChars,
+        selector: selector || undefined,
+      });
+      res.json({
+        ok: true,
+        targetId: tab.targetId,
+        url: tab.url,
+        format,
+        ...result,
+      });
+    } catch (err) {
+      const mapped = mapTabError(err);
+      if (mapped) return jsonError(res, mapped.status, mapped.message);
+      jsonError(res, 500, String(err));
+    }
+  });
+
+  app.get("/snapshot", async (req, res) => {
+    if (!state) return jsonError(res, 503, "browser server not started");
+    const targetId =
+      typeof req.query.targetId === "string" ? req.query.targetId.trim() : "";
+    const format = req.query.format === "domSnapshot" ? "domSnapshot" : "aria";
+    const limit =
+      typeof req.query.limit === "string" ? Number(req.query.limit) : undefined;
+
+    try {
+      const tab = await ensureTabAvailable(runtime, targetId || undefined);
+
+      if (format === "aria") {
+        const snap = await snapshotAria({
+          wsUrl: tab.wsUrl ?? "",
+          limit,
+        });
+        return res.json({
+          ok: true,
+          format,
+          targetId: tab.targetId,
+          url: tab.url,
+          ...snap,
+        });
+      }
+
+      const snap = await snapshotDom({
+        wsUrl: tab.wsUrl ?? "",
+        limit,
+      });
+      return res.json({
+        ok: true,
+        format,
+        targetId: tab.targetId,
+        url: tab.url,
+        ...snap,
+      });
+    } catch (err) {
+      const mapped = mapTabError(err);
+      if (mapped) return jsonError(res, mapped.status, mapped.message);
+      jsonError(res, 500, String(err));
+    }
+  });
+
   const port = resolved.controlPort;
   const server = await new Promise<Server>((resolve, reject) => {
     const s = app.listen(port, "127.0.0.1", () => resolve(s));