pi-browser-harness 0.10.2 → 0.12.0

package/src/domains/snapshot.ts

@@ -2,11 +2,23 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Type } from "typebox";
 import { Container, Image, type ImageTheme, Markdown, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
-import type { CdpSession } from "../cdp/session";
+import { boxOf } from "./box";
+import { cdpCall } from "./cdp-call";
+import {
+  buildTree,
+  collectInteractiveTargets,
+  countNodes,
+  INTERACTIVE_ROLES,
+  liveValue,
+  type SlimNode,
+  stripInternals,
+  VALUE_ROLES,
+} from "./ax-tree";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 import { screenshotPath } from "../util/paths";
+import { asBoolean, asNumber, asRecord, asString } from "../util/guards";
 
 const SnapshotArgs = Type.Object({
   includeScreenshot: Type.Optional(
@@ -26,168 +38,6 @@ const SnapshotArgs = Type.Object({
   ),
 });
 
-// Raw shapes from CDP Accessibility.getFullAXTree. Cast at this boundary only.
-type AxValue = { value?: unknown };
-export type RawAxNode = {
-  nodeId: string;
-  parentId?: string;
-  childIds?: ReadonlyArray<string>;
-  ignored?: boolean;
-  role?: AxValue;
-  name?: AxValue;
-  value?: AxValue;
-  description?: AxValue;
-  properties?: ReadonlyArray<{ name?: string; value?: AxValue }>;
-  backendDOMNodeId?: number;
-};
-
-type Box = { x: number; y: number; width: number; height: number; cx: number; cy: number };
-
-export type SlimNode = {
-  role: string;
-  name?: string;
-  value?: string;
-  description?: string;
-  state?: string;
-  children: SlimNode[];
-  /** Internal: kept for the post-build box fetch. Stripped before returning to the LLM. */
-  _backendId?: number;
-  /** Stable handle (e.g. "e12") for interaction tools. Survives re-renders via backendNodeId. */
-  ref?: string;
-  /** Click target — center of the element's bounding box, in viewport CSS pixels. */
-  box?: Box;
-};
-
-const INTERACTIVE_ROLES = new Set([
-  "button",
-  "link",
-  "textbox",
-  "checkbox",
-  "radio",
-  "combobox",
-  "menuitem",
-  "tab",
-  "switch",
-  "slider",
-  "searchbox",
-  "spinbutton",
-]);
-
-// Roles whose live DOM value/checked state should override the (often stale)
-// AX-tree value. The AX `value` is unreliable for freshly-typed or controlled
-// inputs, so for these we read the real DOM property at snapshot time.
-const VALUE_ROLES = new Set([
-  "textbox",
-  "searchbox",
-  "spinbutton",
-  "combobox",
-  "checkbox",
-  "radio",
-  "switch",
-  "slider",
-]);
-
-const stringOf = (v: AxValue | undefined): string | undefined => {
-  const x = v?.value;
-  if (typeof x === "string" && x !== "") return x;
-  if (typeof x === "number") return String(x);
-  return undefined;
-};
-
-const collectState = (props: RawAxNode["properties"]): string | undefined => {
-  if (!props || props.length === 0) return undefined;
-  const flags: string[] = [];
-  for (const p of props) {
-    const name = p.name;
-    if (!name) continue;
-    const raw = p.value?.value;
-    // Boolean flags worth surfacing in the outline.
-    if (raw === true && (name === "focused" || name === "required" || name === "disabled" || name === "checked" || name === "expanded" || name === "selected" || name === "pressed" || name === "modal")) {
-      flags.push(name);
-    }
-    if (typeof raw === "number" && name === "level") flags.push(`level ${raw}`);
-  }
-  return flags.length > 0 ? flags.join(", ") : undefined;
-};
-
-export const buildTree = (
-  rawNodes: ReadonlyArray<RawAxNode>,
-  opts: { interestingOnly: boolean; maxNodes: number },
-): SlimNode[] => {
-  // Index for parent/child lookups.
-  const byId = new Map<string, RawAxNode>();
-  for (const n of rawNodes) byId.set(n.nodeId, n);
-
-  // CDP doesn't mark a single root explicitly; the root nodes are the ones
-  // whose parentId isn't in the index (typically just one — RootWebArea).
-  const rootIds: string[] = [];
-  for (const n of rawNodes) {
-    if (!n.parentId || !byId.has(n.parentId)) rootIds.push(n.nodeId);
-  }
-
-  let budget = opts.maxNodes;
-
-  const slim = (node: RawAxNode): SlimNode | undefined => {
-    if (budget <= 0) return undefined;
-    if (opts.interestingOnly && node.ignored) {
-      // Skip the ignored node but recurse through its children — Chrome often
-      // ignores wrapper divs but the meaningful descendants are still there.
-      const out: SlimNode[] = [];
-      for (const cid of node.childIds ?? []) {
-        const child = byId.get(cid);
-        if (!child) continue;
-        const slimChild = slim(child);
-        if (slimChild) out.push(slimChild);
-      }
-      // Hoist children into the parent. We return undefined; the parent's
-      // recursion will see them by re-walking — but that double-counts. Instead
-      // we handle hoisting at the parent level. So here just signal "skip me"
-      // by returning undefined; the parent will hoist by checking ignored flag.
-      return out.length > 0 ? { role: "_hoist", children: out } : undefined;
-    }
-    budget--;
-    const role = stringOf(node.role) ?? "unknown";
-    const name = stringOf(node.name);
-    const value = stringOf(node.value);
-    const description = stringOf(node.description);
-    const state = collectState(node.properties);
-    const children: SlimNode[] = [];
-    for (const cid of node.childIds ?? []) {
-      const child = byId.get(cid);
-      if (!child) continue;
-      const slimChild = slim(child);
-      if (!slimChild) continue;
-      // Hoist any synthetic _hoist nodes' children into this level.
-      if (slimChild.role === "_hoist") children.push(...slimChild.children);
-      else children.push(slimChild);
-    }
-    const out: SlimNode = { role, children };
-    if (name !== undefined) out.name = name;
-    if (value !== undefined) out.value = value;
-    if (description !== undefined) out.description = description;
-    if (state !== undefined) out.state = state;
-    if (node.backendDOMNodeId !== undefined) out._backendId = node.backendDOMNodeId;
-    return out;
-  };
-
-  const result: SlimNode[] = [];
-  for (const rid of rootIds) {
-    const root = byId.get(rid);
-    if (!root) continue;
-    const s = slim(root);
-    if (!s) continue;
-    if (s.role === "_hoist") result.push(...s.children);
-    else result.push(s);
-  }
-  return result;
-};
-
-const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
-  let n = 0;
-  for (const node of nodes) n += 1 + countNodes(node.children);
-  return n;
-};
-
 const summarize = (nodes: ReadonlyArray<SlimNode>): string => {
   const counts = new Map<string, number>();
   const walk = (ns: ReadonlyArray<SlimNode>): void => {
@@ -197,7 +47,6 @@ const summarize = (nodes: ReadonlyArray<SlimNode>): string => {
     }
   };
   walk(nodes);
-  // Group landmarks (roles that are top-level structural).
   const landmarkRoles = new Set(["banner", "navigation", "main", "complementary", "contentinfo", "search", "form", "region"]);
   let landmarks = 0;
   for (const [role, c] of counts) if (landmarkRoles.has(role)) landmarks += c;
@@ -221,8 +70,6 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
       if (n.name) line += ` "${n.name}"`;
       if (n.value && n.value !== n.name) line += ` = ${JSON.stringify(n.value)}`;
       if (n.state) line += ` (${n.state})`;
-      // Surface the stable ref + click coordinates for interactive nodes. Agents
-      // pass `ref` to interaction tools (survives re-renders); @(x,y) is a fallback.
       if (n.ref) line += ` [${n.ref}]`;
       if (n.box && INTERACTIVE_ROLES.has(n.role)) {
         line += ` @(${n.box.cx},${n.box.cy})`;
@@ -235,61 +82,6 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
   return lines.join("\n");
 };
 
-/** Strip internal _backendId from a slim tree before returning to callers. */
-const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
-  nodes.map((n) => {
-    const { _backendId: _bid, ...rest } = n;
-    return { ...rest, children: stripInternals(n.children) };
-  });
-
-/**
- * Walk all slim nodes and collect (slimNode, backendId) pairs for interactive
- * roles. Caller fetches DOM.getBoxModel for each and writes box back into the
- * slim node by reference.
- */
-export const collectInteractiveTargets = (
-  nodes: ReadonlyArray<SlimNode>,
-): Array<{ node: SlimNode; backendId: number }> => {
-  const out: Array<{ node: SlimNode; backendId: number }> = [];
-  const walk = (ns: ReadonlyArray<SlimNode>): void => {
-    for (const n of ns) {
-      if (n._backendId !== undefined && INTERACTIVE_ROLES.has(n.role)) {
-        out.push({ node: n, backendId: n._backendId });
-      }
-      walk(n.children);
-    }
-  };
-  walk(nodes);
-  return out;
-};
-
-/**
- * Read the live DOM value for a form control by backend node id. Resolves the
- * node to a JS object then reads the property that matters for its type:
- * `.value` for inputs/selects/textareas, `.checked` (→ "checked"/"unchecked")
- * for checkboxes/radios. Returns undefined on any failure so the caller falls
- * back to the AX value. Mirrors the box-fetch error handling: never throws.
- */
-const liveValue = async (session: CdpSession, backendId: number): Promise<string | undefined> => {
-  const resolved = await session.call("DOM.resolveNode", { backendNodeId: backendId });
-  if (!resolved.success) return undefined;
-  const objectId = (resolved.data as { object?: { objectId?: string } }).object?.objectId;
-  if (!objectId) return undefined;
-  const fn = `function () {
-    if (this.type === "checkbox" || this.type === "radio") return this.checked ? "checked" : "unchecked";
-    if (typeof this.value === "string") return this.value;
-    return null;
-  }`;
-  const r = await session.call("Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: fn,
-    returnByValue: true,
-  });
-  if (!r.success) return undefined;
-  const value = (r.data as { result?: { value?: unknown } }).result?.value;
-  return typeof value === "string" ? value : undefined;
-};
-
 type SnapshotDetails = {
   nodeCount: number;
   truncated: boolean;
@@ -306,45 +98,32 @@ export const snapshotTool = defineBrowserTool({
     "DEFAULT tool for understanding what is on the page. Returns the structured accessibility tree (roles, names, states, hierarchy). Every interactive element gets a stable ref shown as [eN] plus click coordinates @(x,y). Pass the ref to browser_click/browser_fill/etc. — refs survive re-renders, coordinates don't. Use this BEFORE deciding whether you need a screenshot. Pair with browser_execute_js for surgical reads of specific element values.",
   promptSnippet: "Get accessibility-tree snapshot with stable element refs (default for page inspection)",
   promptGuidelines: [
-    "DEFAULT — use this whenever you need to know what's on a page, what's clickable, or how the page is structured.",
-    "Refs come for free: every interactive element shows '[eN]' in the outline. Pass eN as `ref` to browser_click/browser_fill/browser_select_option/browser_focus/browser_upload_file — refs survive re-renders, so prefer them over the '@(x,y)' coordinates (a fallback).",
-    "DO NOT call browser_screenshot just to understand the page. This tool already gives you structure, labels, states, refs, and click targets.",
-    "Re-run after a navigation or a major re-render to get fresh refs; a 'ref is stale' error from an interaction tool means you need a new snapshot.",
+    "Re-run browser_snapshot after a navigation or a major re-render to get fresh refs.",
     "Pass includeScreenshot:true ONLY if you also need to verify visual rendering (rare).",
     "format:'json' returns the raw slim structure (with `ref` and `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
   ],
   parameters: SnapshotArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
 
-    // 1. AX tree
-    const axRes = await session.call("Accessibility.getFullAXTree", {});
-    if (!axRes.success) return err({ kind: "cdp_error", message: axRes.error.message });
-    const rawNodes = (axRes.data as { nodes: ReadonlyArray<RawAxNode> }).nodes;
+    const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
+    if (!axRes.success) return axRes;
+    const rawNodes = axRes.data.nodes;
 
-    // 2. Page url/title
     const piRes = await client.pageInfo();
     if (!piRes.success) return err({ kind: "cdp_error", message: piRes.error.message });
     const pageUrl = "dialog" in piRes.data ? "" : piRes.data.url;
     const pageTitle = "dialog" in piRes.data ? "" : piRes.data.title;
 
-    // 3. Slim + format
     const slim = buildTree(rawNodes, {
       interestingOnly: args.interestingOnly ?? true,
       maxNodes: args.maxNodes ?? 1000,
     });
 
-    // 4. Fetch bounding boxes for interactive nodes so the agent can click
-    //    without a screenshot round-trip. Capped budget so a slow page can't
-    //    wedge the call.
     const targets = collectInteractiveTargets(slim);
 
-    // Assign stable refs (e1, e2, …) to every interactive target. Interaction
-    // tools resolve these refs to backendNodeIds at call time, so they stay
-    // valid across re-renders. The ref → backendNodeId map (and the per-ref
-    // signature baseline for the post-mutation diff) is published below, after
-    // the box/live-value fetch so the signature reflects the live DOM value.
     const refMap = new Map<string, number>();
     targets.forEach(({ node, backendId }, i) => {
       const ref = `e${i + 1}`;
@@ -358,42 +137,18 @@ export const snapshotTool = defineBrowserTool({
       await Promise.allSettled(
         targets.map(async ({ node, backendId }) => {
           if (ac.signal.aborted) return;
-          const r = await session.call("DOM.getBoxModel", { backendNodeId: backendId });
-          if (!r.success) return;
-          // CDP boundary cast: DOM.getBoxModel
-          const data = r.data as { model?: { content?: ReadonlyArray<number>; width?: number; height?: number } };
-          const content = data.model?.content;
-          if (!content || content.length < 8) return;
-          // content is [x1,y1, x2,y1, x2,y2, x1,y2] in viewport CSS pixels.
-          const x = content[0]!;
-          const y = content[1]!;
-          const width = data.model!.width ?? 0;
-          const height = data.model!.height ?? 0;
-          // Skip zero-size and off-viewport boxes — they can't be clicked.
-          if (width <= 0 || height <= 0 || x < 0 || y < 0) return;
-          node.box = {
-            x: Math.round(x),
-            y: Math.round(y),
-            width: Math.round(width),
-            height: Math.round(height),
-            cx: Math.round(x + width / 2),
-            cy: Math.round(y + height / 2),
-          };
-          // Override the AX value with the live DOM property for form controls.
-          // The AX `value` is stale for freshly-typed / controlled inputs, so the
-          // agent can't trust it as a read-back signal. Reading .value/.checked
-          // from the actual element fixes that.
+          const box = await boxOf(client, backendId);
+          if (!box.success) return;
+          if (box.data.x < 0 || box.data.y < 0) return;
+          node.box = box.data;
           if (ac.signal.aborted || !VALUE_ROLES.has(node.role)) return;
-          const live = await liveValue(session, backendId);
+          const live = await liveValue(client, backendId);
           if (live !== undefined) node.value = live;
         }),
       );
       clearTimeout(timer);
     }
 
-    // Publish refs to the active tab. The signature (role|name|value|state) is
-    // the baseline the post-mutation auto-diff compares against, so it must use
-    // the live values resolved above.
     const refSig = new Map<string, string>();
     for (const { node } of targets) {
       if (node.ref === undefined) continue;
@@ -405,14 +160,12 @@ export const snapshotTool = defineBrowserTool({
     const text = (args.format ?? "outline") === "outline" ? renderOutline(slim) : JSON.stringify(stripped, null, 2);
     const trunc = await applyTruncation(text, "snapshot");
 
-    // 4. Optional screenshot — JPEG q=80 to match screenshotTool's default.
     let shotPath: string | undefined;
     if (args.includeScreenshot) {
-      const shot = await session.call("Page.captureScreenshot", { format: "jpeg", quality: 80 });
+      const shot = await cdpCall(client, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
       if (shot.success) {
-        const data = (shot.data as { data: string }).data;
         shotPath = screenshotPath(client.namespace, "jpeg");
-        writeFileSync(shotPath, Buffer.from(data, "base64"));
+        writeFileSync(shotPath, Buffer.from(shot.data.data, "base64"));
       }
     }
 
@@ -429,10 +182,17 @@ export const snapshotTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as
-      | (SnapshotDetails & { summary?: string; ok?: boolean })
-      | undefined;
-    if (!details) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const raw = asRecord(result.details);
+    if (raw === undefined) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const details = {
+      nodeCount: asNumber(raw["nodeCount"]),
+      truncated: asBoolean(raw["truncated"]),
+      fullOutputPath: asString(raw["fullOutputPath"]),
+      screenshotPath: asString(raw["screenshotPath"]),
+      url: asString(raw["url"]),
+      title: asString(raw["title"]),
+      summary: asString(raw["summary"]),
+    };
 
     const titleLine = details.title ? ` "${details.title}"` : "";
     const summary = details.summary ?? "";
@@ -449,9 +209,6 @@ export const snapshotTool = defineBrowserTool({
       return new Markdown(md, 0, 0, getMarkdownTheme());
     }
 
-    // Expanded view: read truncated text from result.content (the spilled file
-    // is too large to inline) — the same `text` we returned from handler is in
-    // result.content[0]. Fall back to a placeholder if shape is unexpected.
     const content = result.content[0];
     const treeText = content && content.type === "text" ? content.text : "";
 
@@ -471,7 +228,6 @@ export const snapshotTool = defineBrowserTool({
 
     if (!details.screenshotPath) return treeBlock;
 
-    // Mirror screenshotTool's width-clamp wrapper for the inline image.
     try {
       const buf = readFileSync(details.screenshotPath);
       const b64 = buf.toString("base64");

package/src/domains/tabs.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCallBrowser } from "./cdp-call";
 
 const ListTabsArgs = Type.Object({
   includeInternal: Type.Optional(Type.Boolean({ default: true, description: "Include chrome:// pages" })),
@@ -18,12 +19,10 @@ export const listTabsTool = defineBrowserTool({
   description: "List browser tabs. Defaults to tabs this harness session opened (scope:'owned'). Pass scope:'all' to see the user's other tabs too.",
   promptSnippet: "List browser tabs",
   promptGuidelines: [
-    "Defaults to scope:'owned' — only tabs this session created. Pass scope:'all' to inspect the user's other tabs.",
-    "browser_switch_tab and browser_close_tab refuse non-owned tabs; use browser_new_tab to open one this session controls.",
     "Each tab shows its full 32-char hex targetId — use the exact value with browser_switch_tab.",
-    "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
   ],
   parameters: ListTabsArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.listTabs(args.includeInternal ?? true);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -50,12 +49,13 @@ export const currentTabTool = defineBrowserTool({
   promptSnippet: "Get current tab info",
   promptGuidelines: ["Returns targetId, url, title, and whether the tab is owned by this harness session."],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cur = client.current();
     if (!cur) return err({ kind: "invalid_state", message: "No tab attached." });
-    const ti = await client.session().callBrowser("Target.getTargetInfo", { targetId: cur.targetId });
-    if (!ti.success) return err({ kind: "cdp_error", message: ti.error.message });
-    const info = (ti.data as { targetInfo: { targetId: string; url: string; title: string } }).targetInfo; // CDP boundary cast: Target.getTargetInfo returns { targetInfo: { targetId, url, title } }
+    const ti = await cdpCallBrowser(client, "Target.getTargetInfo", { targetId: cur.targetId });
+    if (!ti.success) return ti;
+    const info = ti.data.targetInfo;
     const owned = client.owns(info.targetId);
     return ok({
       text: `Current tab${owned ? " (owned)" : " (NOT owned by this session)"}:\n  ${info.targetId}\n  ${info.url}\n  ${info.title}`,
@@ -80,12 +80,10 @@ export const switchTabTool = defineBrowserTool({
   promptGuidelines: [
     "Get a targetId via browser_list_tabs first.",
     "Accepts exact targetId or a unique prefix of at least 8 hex characters.",
-    "Refuses tabs not owned by this session — use browser_new_tab to open a controllable tab instead.",
   ],
   parameters: SwitchTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    // Resolve to a concrete targetId (exact, or unique hex prefix). We resolve
-    // first so the ownership check sees the canonical id, not the prefix.
     let resolved = args.targetId;
     if (!client.owns(resolved)) {
       const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
@@ -104,7 +102,9 @@ export const switchTabTool = defineBrowserTool({
             details: { matches: matches.map((t) => ({ targetId: t.targetId, url: t.url })) },
           });
         }
-        resolved = matches[0]!.targetId;
+        const first = matches[0];
+        if (first === undefined) return err({ kind: "invalid_state", message: "no matching tab" });
+        resolved = first.targetId;
       }
       if (!client.owns(resolved)) {
         return err({
@@ -134,11 +134,9 @@ export const newTabTool = defineBrowserTool({
   label: "Browser New Tab",
   description: "Open a new tab in the harness's dedicated Chrome window and switch to it. Optionally navigate to a URL.",
   promptSnippet: "Open a new tab",
-  promptGuidelines: [
-    "All tabs opened by this tool live in a single dedicated Chrome window separate from the user's main browsing.",
-    "Pass url to navigate immediately.",
-  ],
+  promptGuidelines: [],
   parameters: NewTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.newTab(args.url);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -161,10 +159,10 @@ export const closeTabTool = defineBrowserTool({
   description: "Close a tab the harness owns. Refuses tabs not opened by this session.",
   promptSnippet: "Close an owned tab",
   promptGuidelines: [
-    "Only closes tabs this session opened (visible in browser_list_tabs default scope).",
     "Accepts exact targetId or a unique hex prefix (>=8 chars).",
   ],
   parameters: CloseTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     let resolved = args.targetId;
     if (!client.owns(resolved)) {
@@ -172,7 +170,8 @@ export const closeTabTool = defineBrowserTool({
       if (isHexPrefix) {
         const owned = client.ownership().list();
         const matches = owned.filter((id) => id.startsWith(args.targetId));
-        if (matches.length === 1) resolved = matches[0]!;
+        const first = matches[0];
+        if (matches.length === 1 && first !== undefined) resolved = first;
         else if (matches.length > 1) {
           return err({
             kind: "invalid_state",

package/src/domains/target.ts

@@ -0,0 +1,35 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { resolveRefToBox } from "./ref-resolve";
+
+export type PointArgs = {
+  readonly ref?: string | undefined;
+  readonly x?: number | undefined;
+  readonly y?: number | undefined;
+};
+
+export type ResolvedTarget = {
+  readonly x: number;
+  readonly y: number;
+  readonly label: string;
+};
+
+export const resolveTarget = async (
+  client: BrowserClient,
+  args: PointArgs,
+): Promise<Result<ResolvedTarget, ToolErr>> => {
+  if (args.ref !== undefined) {
+    const box = await resolveRefToBox(client, args.ref);
+    if (!box.success) return box;
+    return ok({
+      x: box.data.cx,
+      y: box.data.cy,
+      label: `[${args.ref}] (${box.data.cx}, ${box.data.cy})`,
+    });
+  }
+  if (args.x !== undefined && args.y !== undefined) {
+    return ok({ x: args.x, y: args.y, label: `(${args.x}, ${args.y})` });
+  }
+  return err({ kind: "invalid_state", message: "Provide either `ref` or both `x` and `y`." });
+};

package/src/domains/viewport.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
-import { type Result, err, ok } from "../util/result";
+import { type Result, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
 
 const ViewportArgs = Type.Object({
   width: Type.Integer({ minimum: 100, maximum: 8000, description: "Viewport CSS pixel width" }),
@@ -16,18 +17,18 @@ export const viewportResizeTool = defineBrowserTool({
   description: "Override the viewport size and device pixel ratio for responsive testing.",
   promptSnippet: "Resize the viewport (responsive testing)",
   promptGuidelines: [
-    "Width/height in CSS pixels (e.g., 375x667 for iPhone SE).",
     "Pass deviceScaleFactor=2 to simulate retina displays.",
   ],
   parameters: ViewportArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await client.session().call("Emulation.setDeviceMetricsOverride", {
+    const r = await cdpCall(client, "Emulation.setDeviceMetricsOverride", {
       width: args.width,
       height: args.height,
       deviceScaleFactor: args.deviceScaleFactor ?? 1,
       mobile: false,
     });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    if (!r.success) return r;
     return ok({
       text: `Viewport set to ${args.width}x${args.height} @${args.deviceScaleFactor ?? 1}x`,
       details: {