pi-browser-harness 0.10.2 → 0.12.0

package/src/domains/network.ts

@@ -2,8 +2,11 @@ import { Type } from "typebox";
 import { Markdown, Text } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { type Result, err, ok } from "../util/result";
+import { formatBytes } from "../util/truncate";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
 import { applyTruncation } from "../util/truncate";
+import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
 import type { NetworkRecord } from "../cdp/network-buffer";
 
 const HttpGetArgs = Type.Object({
@@ -21,10 +24,10 @@ export const httpGetTool = defineBrowserTool({
     "Fetch a URL outside the browser (faster than browser_navigate for APIs and static pages). Timeout covers headers AND body read.",
   promptSnippet: "HTTP GET (outside browser; for APIs/static pages)",
   promptGuidelines: [
-    "Faster than navigate+execute_js for JSON/HTML APIs.",
     "No JS rendering — for SPAs use browser_navigate.",
   ],
   parameters: HttpGetArgs,
+  concurrency: "parallel",
   ensureAlive: false,
   async handler(args): Promise<Result<ToolOk, ToolErr>> {
     const ac = new AbortController();
@@ -96,11 +99,6 @@ const renderNetworkMarkdown = (
 
   const failed = records.filter((r) => r.failed || (r.status !== undefined && r.status >= 500)).length;
   const totalBytes = records.reduce((s, r) => s + (r.responseBodySize ?? 0), 0);
-  const formatBytes = (n: number): string => {
-    if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
-    if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
-    return `${n} B`;
-  };
   const showWindow = (() => {
     const finished = records.filter((r) => r.durationMs !== undefined);
     if (finished.length === 0) return "";
@@ -129,7 +127,6 @@ const renderNetworkMarkdown = (
     return `${headerLines.join("\n")}\n\n${rows}${more}`;
   }
 
-  // Expanded: full table + optional body sections.
   const tableHeader = `| # | Method | Status | URL | Type | ms |\n|---|---|---|---|---|---|`;
   const tableRows = records
     .map((r, i) => {
@@ -167,6 +164,57 @@ type NetworkDetails = {
   includeBodies: boolean;
 };
 
+const asNetworkRecord = (v: unknown): NetworkRecord | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const method = asString(o["method"]);
+  const url = asString(o["url"]);
+  const type = asString(o["type"]);
+  if (method === undefined || url === undefined || type === undefined) return undefined;
+  const status = asNumber(o["status"]);
+  const statusText = asString(o["statusText"]);
+  const mimeType = asString(o["mimeType"]);
+  const durationMs = asNumber(o["durationMs"]);
+  const responseBodySize = asNumber(o["responseBodySize"]);
+  const failed = asBoolean(o["failed"]);
+  const errorText = asString(o["errorText"]);
+  const bodyRaw = o["body"];
+  const body = typeof bodyRaw === "string" || bodyRaw === null ? bodyRaw : undefined;
+  return {
+    requestId: asString(o["requestId"]) ?? "",
+    method,
+    url,
+    type,
+    requestStartedMs: asNumber(o["requestStartedMs"]) ?? 0,
+    requestBodySize: asNumber(o["requestBodySize"]) ?? 0,
+    ...(status !== undefined ? { status } : {}),
+    ...(statusText !== undefined ? { statusText } : {}),
+    ...(mimeType !== undefined ? { mimeType } : {}),
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    ...(responseBodySize !== undefined ? { responseBodySize } : {}),
+    ...(failed !== undefined ? { failed } : {}),
+    ...(errorText !== undefined ? { errorText } : {}),
+    ...(body !== undefined ? { body } : {}),
+  };
+};
+
+const asNetworkDetails = (v: unknown): NetworkDetails | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const requests = asArrayOf(o["requests"], asNetworkRecord);
+  if (requests === undefined) return undefined;
+  const fullOutputPath = asString(o["fullOutputPath"]);
+  return {
+    total: asNumber(o["total"]) ?? requests.length,
+    returned: asNumber(o["returned"]) ?? requests.length,
+    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
+    truncated: asBoolean(o["truncated"]) ?? false,
+    requests,
+    includeBodies: asBoolean(o["includeBodies"]) ?? false,
+    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+  };
+};
+
 export const networkRequestsTool = defineBrowserTool({
   name: "browser_network_requests",
   label: "Browser Network Requests",
@@ -175,11 +223,11 @@ export const networkRequestsTool = defineBrowserTool({
   promptSnippet: "Inspect recent network requests on the current page",
   promptGuidelines: [
     "Buffer is reset on tab switch — only requests on the current tab since attach are visible.",
-    'urlPattern is a substring; wrap in slashes for regex (e.g. "/\\\\.json$/").',
-    "includeResponseBodies:true costs an extra CDP call per matched request — use only when you need payloads.",
+    "Pass includeResponseBodies:true to browser_network_requests only when you need payloads.",
     "If bufferOverflowed:true in the result, older events were dropped (capacity 500 records/tab).",
   ],
   parameters: NetworkRequestsArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
@@ -197,12 +245,12 @@ export const networkRequestsTool = defineBrowserTool({
       const timer = setTimeout(() => ac.abort(), BODY_BUDGET_MS);
       const fills = drained.records.map(async (r) => {
         if (ac.signal.aborted) return;
-        const bodyRes = await session.call("Network.getResponseBody", { requestId: r.requestId });
+        const bodyRes = await cdpCall(client, "Network.getResponseBody", { requestId: r.requestId });
         if (!bodyRes.success) {
           r.body = null;
           return;
         }
-        const b = bodyRes.data as { body: string; base64Encoded?: boolean };
+        const b = bodyRes.data;
         let body = b.base64Encoded ? Buffer.from(b.body, "base64").toString("utf8") : b.body;
         if (body.length > PER_BODY_CAP) body = body.slice(0, PER_BODY_CAP) + "…";
         r.body = body;
@@ -215,7 +263,7 @@ export const networkRequestsTool = defineBrowserTool({
       includeBodies: args.includeResponseBodies ?? false,
       total: drained.total,
       bufferOverflowed: drained.bufferOverflowed,
-      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+      expanded: true,
     });
     const trunc = await applyTruncation(text, "network");
 
@@ -233,7 +281,7 @@ export const networkRequestsTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as NetworkDetails | undefined;
+    const details = asNetworkDetails(result.details);
     if (!details) return new Text(theme.fg("error", "network: no details"), 0, 0);
 
     const md = renderNetworkMarkdown(details.requests, {

package/src/domains/page.ts

@@ -1,9 +1,26 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { sleep } from "../util/time";
+import { evalJs } from "./cdp-call";
 import { safeJs } from "../util/js-template";
 
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+
 export const pageInfoTool = defineBrowserTool({
   name: "browser_page_info",
   label: "Browser Page Info",
@@ -11,12 +28,10 @@ export const pageInfoTool = defineBrowserTool({
     "Get current page state: URL, title, viewport size, scroll position, page dimensions. If a JS dialog is open, returns dialog info instead.",
   promptSnippet: "Get current page URL, title, viewport, and scroll position",
   promptGuidelines: [
-    "Use browser_page_info to quickly check what page you're on and whether a JS dialog is blocking interaction.",
-    "If browser_page_info returns a dialog, use browser_handle_dialog before any other browser actions.",
-    "JS dialogs freeze the page's JS thread, so no other interaction works until the dialog is handled.",
-    "browser_page_info auto-detects alert, confirm, prompt, and beforeunload dialogs.",
+    "If browser_page_info returns a dialog, call browser_handle_dialog before any other browser actions: dialogs freeze the page's JS thread.",
   ],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.pageInfo();
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -46,6 +61,7 @@ export const waitTool = defineBrowserTool({
   promptSnippet: "Wait N seconds",
   promptGuidelines: ["Use sparingly — prefer browser_wait_for_load when waiting for a page load."],
   parameters: WaitArgs,
+  concurrency: "parallel",
   async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
     try {
       await sleep(Math.round(args.seconds * 1000), signal);
@@ -68,15 +84,15 @@ export const waitForLoadTool = defineBrowserTool({
   promptSnippet: "Wait for the page to finish loading",
   promptGuidelines: [
     "Call after browser_navigate / browser_open_urls before extracting data.",
-    "Returns when readyState becomes 'complete' OR the timeout elapses.",
   ],
   parameters: WaitForLoadArgs,
+  concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const timeoutMs = (args.timeout ?? 15) * 1000;
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
-      const r = await client.evaluateJs(safeJs`document.readyState`);
+      const r = await evalJs(client, safeJs`document.readyState`);
       if (r.success && r.data === "complete") {
         const ms = Date.now() - start;
         return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
@@ -102,10 +118,9 @@ export const waitForTool = defineBrowserTool({
   promptSnippet: "Wait for an element or text to appear (or an element to disappear)",
   promptGuidelines: [
     "Use before browser_fill / browser_click on dynamic pages so you act after the element renders.",
-    "Provide selector (default: wait until present; gone:true: wait until absent) or text.",
-    "Returns a typed timeout error if the condition isn't met within the timeout.",
   ],
   parameters: WaitForArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.selector === undefined && args.text === undefined) {
       return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
@@ -119,7 +134,7 @@ export const waitForTool = defineBrowserTool({
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
-      const r = await client.evaluateJs(expr);
+      const r = await evalJs(client, expr);
       if (r.success && r.data === true) {
         const ms = Date.now() - start;
         const what = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;

package/src/domains/readpage/read-page.ts

@@ -1,17 +1,20 @@
 import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../../schemas/parse";
 import { type Result, err, ok } from "../../util/result";
 import { applyTruncation } from "../../util/truncate";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
+import { cdpCallBrowser, evalJs } from "../cdp-call";
 import {
   closeIsolatedTab,
   evalInIsolatedTab,
+  isJsonText,
   type IsolatedTab,
   navigateIsolatedTab,
   openIsolatedTab,
   waitForIsolatedLoad,
 } from "../isolated-tab";
 import { renderExpandableText } from "../render";
-import { buildPageCaptureExpr } from "./capture";
 import { extractReadable, type PageCapture, type ReadablePage } from "./readability";
 
 const LOAD_TIMEOUT_MS = 15_000;
@@ -23,23 +26,74 @@ const ReadPageArgs = Type.Object({
   ),
 });
 
-const isPageCapture = (value: unknown): value is PageCapture => {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return typeof v["url"] === "string" && typeof v["title"] === "string" && Array.isArray(v["blocks"]) && typeof v["bodyText"] === "string";
-};
+const ContentBlockSchema = Type.Object({
+  kind: Type.Union([
+    Type.Literal("paragraph"),
+    Type.Literal("heading"),
+    Type.Literal("listitem"),
+    Type.Literal("blockquote"),
+    Type.Literal("other"),
+  ]),
+  text: Type.String(),
+  linkTextLength: Type.Number(),
+  inBoilerplate: Type.Boolean(),
+});
 
-const safeParse = (text: string): unknown => {
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return undefined;
+const PageCaptureSchema = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  blocks: Type.Array(ContentBlockSchema),
+  bodyText: Type.String(),
+});
+
+const pageCaptureValidator = Compile(PageCaptureSchema);
+
+const BODY_TEXT_LIMIT = 20_000;
+
+const buildPageCaptureExpr = (): string => `
+  (() => {
+    const BOILERPLATE = new Set(['NAV', 'HEADER', 'FOOTER', 'ASIDE']);
+    const inBoilerplate = (el) => {
+      for (let n = el; n; n = n.parentElement) {
+        if (BOILERPLATE.has(n.tagName)) return true;
+        const role = n.getAttribute && n.getAttribute('role');
+        if (role === 'navigation' || role === 'banner' || role === 'contentinfo') return true;
+      }
+      return false;
+    };
+    const kindOf = (tag) => {
+      if (/^H[1-6]$/.test(tag)) return 'heading';
+      if (tag === 'LI') return 'listitem';
+      if (tag === 'BLOCKQUOTE') return 'blockquote';
+      if (tag === 'P') return 'paragraph';
+      return 'other';
+    };
+    const selector = 'p, h1, h2, h3, h4, h5, h6, li, blockquote';
+    const root = document.querySelector('article, main, [role=main]') || document.body;
+    const blocks = [];
+    for (const el of root.querySelectorAll(selector)) {
+      const text = (el.innerText || '').replace(/\\s+/g, ' ').trim();
+      if (!text) continue;
+      let linkTextLength = 0;
+      for (const a of el.querySelectorAll('a')) linkTextLength += (a.innerText || '').length;
+      blocks.push({ kind: kindOf(el.tagName), text, linkTextLength, inBoilerplate: inBoilerplate(el) });
+    }
+    const bodyText = (document.body.innerText || '').replace(/\\n{3,}/g, '\\n\\n').slice(0, ${BODY_TEXT_LIMIT});
+    return JSON.stringify({ url: location.href, title: document.title, blocks, bodyText });
+  })()
+`;
+
+const toPageCapture = (raw: unknown): PageCapture | undefined => {
+  if (typeof raw === "string") {
+    const parsed = parseJson(raw, pageCaptureValidator);
+    return parsed.success ? parsed.data : undefined;
   }
+  return pageCaptureValidator.Check(raw) ? raw : undefined;
 };
 
 const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> => {
-  const parsed = typeof raw === "string" ? safeParse(raw) : raw;
-  if (!isPageCapture(parsed)) return err({ kind: "internal", message: "page capture returned an unexpected shape" });
+  const parsed = toPageCapture(raw);
+  if (parsed === undefined) return err({ kind: "internal", message: "page capture returned an unexpected shape" });
   const page: ReadablePage = extractReadable(parsed);
   const header = `# ${page.title}\n${page.url}\n(${page.wordCount} words)\n\n`;
   const truncated = await applyTruncation(header + page.text, "readpage");
@@ -73,7 +127,7 @@ const readOpenedUrl = async (
     if (!navigated.success) return err(navigated.error);
     const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
     if (!loaded.success) return err(loaded.error);
-    const captured = await evalInIsolatedTab(client, tab, buildPageCaptureExpr());
+    const captured = await evalInIsolatedTab(client, tab, buildPageCaptureExpr(), isJsonText);
     if (!captured.success) return err(captured.error);
     return captureToResult(captured.data);
   } finally {
@@ -88,11 +142,11 @@ const readOwnedTab = async (
   if (!client.owns(targetId)) {
     return err({ kind: "invalid_state", message: `Tab ${targetId} is not owned by this session.` });
   }
-  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
-  if (!attached.success) return err({ kind: "cdp_error", message: attached.error.message });
-  const sessionId = (attached.data as { sessionId: string }).sessionId;
-  const captured = await client.evaluateJs(buildPageCaptureExpr(), sessionId);
-  if (!captured.success) return err({ kind: "cdp_error", message: captured.error.message });
+  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) return attached;
+  const sessionId = attached.data.sessionId;
+  const captured = await evalJs(client, buildPageCaptureExpr(), sessionId);
+  if (!captured.success) return captured;
   return captureToResult(captured.data);
 };
 
@@ -103,11 +157,11 @@ export const readPageTool = defineBrowserTool({
     "Read a page as clean article text — main content with nav/ads/boilerplate stripped. Pass a url (opened in an isolated tab, read, then closed) or a targetId of an owned tab. Reader-mode counterpart to browser_web_search.",
   promptSnippet: "Read a page's main content as clean text",
   promptGuidelines: [
-    "Pass url to read an arbitrary page (opened + closed in its own tab, never disturbing your current tab), or targetId to read an already-open owned tab.",
     "Returns readable main-article text — use this over browser_snapshot/browser_execute_js when you want an article's content for reading or research.",
     "Boilerplate-heavy or structure-less pages fall back to bounded body text rather than erroring.",
   ],
   parameters: ReadPageArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.url !== undefined && args.url.length > 0) return readOpenedUrl(client, args.url, signal);
     if (args.targetId !== undefined && args.targetId.length > 0) return readOwnedTab(client, args.targetId);

package/src/domains/readpage/readability.ts

@@ -1,35 +1,17 @@
-/**
- * Pure reader-mode extraction — no CDP, no DOM. The in-page script
- * (see capture.ts) serializes candidate content blocks; these pure functions
- * score them and assemble clean article text, so the selection logic is
- * unit-testable against saved fixtures (test/deep-research/readability-test.ts).
- *
- * Dependency-free by design (no jsdom / Readability): the harness ships no new
- * runtime deps. The heuristic favors blocks with high text density and low link
- * density, which is what separates article body from nav/ads/boilerplate.
- */
-
-/** One candidate content block captured in-page. */
 export type ContentBlock = {
-  /** Semantic tag: paragraph | heading | listitem | blockquote | other. */
   readonly kind: "paragraph" | "heading" | "listitem" | "blockquote" | "other";
   readonly text: string;
-  /** Chars of text that sit inside <a> tags — high ratio ⇒ nav/menu, not prose. */
   readonly linkTextLength: number;
-  /** True when an ancestor is nav/header/footer/aside — structural boilerplate. */
   readonly inBoilerplate: boolean;
 };
 
-/** The JSON payload capture.ts returns from the page. */
 export type PageCapture = {
   readonly url: string;
   readonly title: string;
   readonly blocks: ReadonlyArray<ContentBlock>;
-  /** Bounded innerText fallback when block extraction finds nothing usable. */
   readonly bodyText: string;
 };
 
-/** The tool's public output shape. */
 export type ReadablePage = {
   readonly title: string;
   readonly url: string;
@@ -46,7 +28,6 @@ const linkDensity = (block: ContentBlock): number => {
   return block.linkTextLength / block.text.length;
 };
 
-/** A block is article prose if it is substantive, text-dense, and not chrome. */
 const isArticleBlock = (block: ContentBlock): boolean => {
   if (block.inBoilerplate) return false;
   if (linkDensity(block) > MAX_LINK_DENSITY) return false;
@@ -69,11 +50,6 @@ const wordCountOf = (text: string): number => {
   return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
 };
 
-/**
- * Assemble readable article text from a page capture. Keeps text-dense,
- * non-boilerplate blocks; falls back to the bounded body text when the article
- * is too thin (e.g. a page with no clear content structure).
- */
 export const extractReadable = (capture: PageCapture): ReadablePage => {
   const articleText = capture.blocks.filter(isArticleBlock).map(render).join("\n\n").replace(/\n{3,}/g, "\n\n").trim();
 

package/src/domains/ref-resolve.ts

@@ -1,9 +1,9 @@
 import type { BrowserClient } from "../client";
 import { type Result, err, ok } from "../util/result";
 import type { ToolErr } from "../util/tool";
-import { buildTree, collectInteractiveTargets, type RawAxNode, type SlimNode } from "./snapshot";
-
-type Box = { x: number; y: number; width: number; height: number; cx: number; cy: number };
+import { type Box, boxOf } from "./box";
+import { cdpCall } from "./cdp-call";
+import { buildTree, collectInteractiveTargets, type SlimNode } from "./ax-tree";
 
 const staleErr = (ref: string): ToolErr => ({
   kind: "invalid_state",
@@ -11,106 +11,72 @@ const staleErr = (ref: string): ToolErr => ({
   details: { ref },
 });
 
-/**
- * Resolve a ref to its CDP objectId (a handle to the live JS node). Use when a
- * tool needs to run JS against the element (fill, focus, select, dispatch_key).
- * Re-resolves through the backendNodeId at call time, so it reflects the current
- * DOM even after re-renders — and fails loudly if the node was detached.
- */
 export const resolveRefToObjectId = async (
   client: BrowserClient,
   ref: string,
 ): Promise<Result<string, ToolErr>> => {
   const backendId = client.session().resolveRef(ref);
   if (backendId === undefined) return err(staleErr(ref));
-  const resolved = await client.session().call("DOM.resolveNode", { backendNodeId: backendId });
+  const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
   if (!resolved.success) {
-    // A detached node (removed by a re-render) fails to resolve — surface it as
-    // a stale ref rather than a raw CDP error so the agent knows to re-snapshot.
     return err(staleErr(ref));
   }
-  const objectId = (resolved.data as { object?: { objectId?: string } }).object?.objectId;
+  const objectId = resolved.data.object.objectId;
   if (!objectId) return err(staleErr(ref));
   return ok(objectId);
 };
 
-/** Resolve a ref to its current backendNodeId (for CDP calls that take one, e.g. DOM.setFileInputFiles). */
 export const resolveRefToBackendId = (client: BrowserClient, ref: string): Result<number, ToolErr> => {
   const backendId = client.session().resolveRef(ref);
   if (backendId === undefined) return err(staleErr(ref));
   return ok(backendId);
 };
 
-/**
- * Resolve a ref to the current center of its bounding box, in viewport CSS
- * pixels. Use for browser_click. Fetched fresh via DOM.getBoxModel, so a
- * re-rendered/moved element is clicked at its new position.
- */
 export const resolveRefToBox = async (
   client: BrowserClient,
   ref: string,
 ): Promise<Result<Box, ToolErr>> => {
   const backendId = client.session().resolveRef(ref);
   if (backendId === undefined) return err(staleErr(ref));
-  const r = await client.session().call("DOM.getBoxModel", { backendNodeId: backendId });
-  if (!r.success) return err(staleErr(ref));
-  const data = r.data as { model?: { content?: ReadonlyArray<number>; width?: number; height?: number } };
-  const content = data.model?.content;
-  if (!content || content.length < 8) return err(staleErr(ref));
-  const x = content[0]!;
-  const y = content[1]!;
-  const width = data.model!.width ?? 0;
-  const height = data.model!.height ?? 0;
-  if (width <= 0 || height <= 0) return err(staleErr(ref));
-  return ok({
-    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),
-  });
+  const box = await boxOf(client, backendId);
+  if (!box.success) return err(staleErr(ref));
+  return ok(box.data);
 };
 
 const sigOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}|${n.value ?? ""}|${n.state ?? ""}`;
 const keyOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}`;
 
-/**
- * Recompute the interactive elements after a mutation and return a compact,
- * human/LLM-readable diff vs. the prior snapshot's baseline — changed values,
- * newly-appeared elements (marked `*`), and removed ones. Re-publishes the fresh
- * ref map so subsequent ref-based calls target the post-mutation DOM.
- *
- * Deliberately cheap: it re-reads the AX tree (no per-node box fetch — the
- * expensive part of a full snapshot) and emits a few lines, not a full tree, so
- * a long action sequence doesn't blow up the context.
- *
- * Returns "" on any failure or when nothing changed — callers append it only if
- * non-empty, so a diff is best-effort and never blocks the primary action.
- */
 export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
   const session = client.session();
   const prev = session.refSignatures();
 
-  const axRes = await session.call("Accessibility.getFullAXTree", {});
+  const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
   if (!axRes.success) return "";
-  const rawNodes = (axRes.data as { nodes: ReadonlyArray<RawAxNode> }).nodes;
+  const rawNodes = axRes.data.nodes;
   const slim = buildTree(rawNodes, { interestingOnly: true, maxNodes: 1000 });
   const targets = collectInteractiveTargets(slim);
 
-  // Re-publish fresh refs so later ref calls resolve against the new DOM.
+  const priorRefs = session.refMappings();
+  const refByBackendId = new Map<number, string>();
+  for (const [ref, backendId] of priorRefs) refByBackendId.set(backendId, ref);
+  let nextIndex = 1;
+  for (const ref of priorRefs.keys()) {
+    const digits = /^e(\d+)$/.exec(ref)?.[1];
+    if (digits !== undefined) nextIndex = Math.max(nextIndex, Number(digits) + 1);
+  }
   const refMap = new Map<string, number>();
   const refSig = new Map<string, string>();
-  targets.forEach(({ node, backendId }, i) => {
-    const ref = `e${i + 1}`;
+  const taken = new Set<string>();
+  for (const { node, backendId } of targets) {
+    const prior = refByBackendId.get(backendId);
+    const ref = prior !== undefined && !taken.has(prior) ? prior : `e${nextIndex++}`;
+    taken.add(ref);
     node.ref = ref;
     refMap.set(ref, backendId);
     refSig.set(ref, sigOf(node));
-  });
+  }
   session.setRefMap(refMap, refSig);
 
-  // Compare by stable identity (role|name) rather than ref position, since refs
-  // renumber when the element set changes. Build prev/current identity → value.
   const prevByKey = new Map<string, string>();
   for (const sig of prev.values()) {
     const parts = sig.split("|");

package/src/domains/render.ts

@@ -1,44 +1,23 @@
-/**
- * Shared TUI renderer for text-heavy tool output (browser_web_search,
- * browser_read_page). Gives the native pi expand/collapse (Ctrl+O) behavior:
- * a compact preview by default, the full body when expanded — mirroring the
- * pattern in browser_execute_js (src/domains/js.ts:81-109).
- *
- * The full text always goes to the LLM via ToolOk.text; this only governs the
- * human-facing TUI view.
- */
 import { Markdown, Text } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import type { Component } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
+import { isRecord } from "../util/guards";
 
 const COMPACT_PREVIEW_LINES = 6;
 
-/** Structured payload a text-heavy tool stores so renderResult can rebuild views. */
-export type ExpandableText = {
-  /** One-line summary shown above the body in both states (e.g. "5 results · google"). */
+type ExpandableText = {
   readonly summary: string;
-  /** The full rendered body (markdown/plain). */
   readonly body: string;
-  /** Path to the on-disk full output when the LLM text was truncated, if any. */
   readonly fullOutputPath?: string;
 };
 
-const isExpandableText = (value: unknown): value is ExpandableText => {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return typeof v["summary"] === "string" && typeof v["body"] === "string";
-};
+const isExpandableText = (value: unknown): value is ExpandableText =>
+  isRecord(value) && typeof value["summary"] === "string" && typeof value["body"] === "string";
 
-const extractRender = (details: unknown): unknown => {
-  if (typeof details !== "object" || details === null) return undefined;
-  return (details as Record<string, unknown>)["render"];
-};
+const extractRender = (details: unknown): unknown =>
+  isRecord(details) ? details["render"] : undefined;
 
-/**
- * Build a renderResult over an ExpandableText stored in `details.render`.
- * `label` names the tool for the error fallback (e.g. "web_search").
- */
 export const renderExpandableText = (
   label: string,
   result: { readonly details?: unknown },