pi-browser-harness 0.11.0 → 0.13.0

package/src/domains/ax-tree.ts

@@ -2,6 +2,8 @@ import type { AxNodeResult } from "../cdp/commands";
 import type { BrowserClient } from "../client";
 import type { Box } from "./box";
 import { cdpCall } from "./cdp-call";
+import { elementFunctionSource } from "./page/inject";
+import { liveValue as liveValueInPage } from "./page/live-value.page";
 
 export type RawAxNode = AxNodeResult;
 type AxValue = NonNullable<RawAxNode["role"]>;
@@ -138,8 +140,9 @@ export const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
 
 export const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
   nodes.map((n) => {
-    const { _backendId: _bid, ...rest } = n;
-    return { ...rest, children: stripInternals(n.children) };
+    const stripped: SlimNode = { ...n, children: stripInternals(n.children) };
+    delete stripped._backendId;
+    return stripped;
   });
 
 export const collectInteractiveTargets = (
@@ -158,19 +161,16 @@ export const collectInteractiveTargets = (
   return out;
 };
 
+const LIVE_VALUE_FN = elementFunctionSource(liveValueInPage);
+
 export const liveValue = async (client: BrowserClient, backendId: number): Promise<string | undefined> => {
   const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
   if (!resolved.success) return undefined;
   const objectId = resolved.data.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 cdpCall(client, "Runtime.callFunctionOn", {
     objectId,
-    functionDeclaration: fn,
+    functionDeclaration: LIVE_VALUE_FN,
     returnByValue: true,
   });
   if (!r.success) return undefined;

package/src/domains/cdp-call.ts

@@ -1,6 +1,7 @@
 import type { BrowserClient } from "../client";
 import type { CdpMethod, ParamsOf, ResultOf } from "../cdp/commands";
 import type { CdpError } from "../cdp/errors";
+import type { CallArgs, CallOpts } from "../cdp/session";
 import { type Result, err } from "../util/result";
 import type { ToolErr } from "../util/tool";
 
@@ -10,13 +11,20 @@ export const cdpErrToToolErr = (e: CdpError, method: string): ToolErr => ({
   details: { method },
 });
 
+// Maps a BrowserClient-level Result (listTabs, newTab, pageInfo, …) to the tool error shape without losing the
+// timeout kind or the CDP method the error carries. `fallbackMethod` names the operation when the error has none.
+export const fromClient = <T>(r: Result<T, CdpError>, fallbackMethod = "client"): Result<T, ToolErr> => {
+  if (r.success) return r;
+  return err(cdpErrToToolErr(r.error, r.error.method ?? fallbackMethod));
+};
+
+// Params are required only when the method has a required key, mirroring CdpSession.call.
 export const cdpCall = async <M extends CdpMethod>(
   client: BrowserClient,
   method: M,
-  params: ParamsOf<M>,
-  opts?: { timeoutMs?: number },
+  ...args: CallArgs<M>
 ): Promise<Result<ResultOf<M>, ToolErr>> => {
-  const r = await client.session().call(method, params, opts);
+  const r = await client.session().call(method, ...args);
   if (!r.success) return err(cdpErrToToolErr(r.error, method));
   return r;
 };
@@ -26,7 +34,7 @@ export const cdpCallOnTarget = async <M extends CdpMethod>(
   method: M,
   params: ParamsOf<M>,
   sessionId: string,
-  opts?: { timeoutMs?: number },
+  opts?: CallOpts,
 ): Promise<Result<ResultOf<M>, ToolErr>> => {
   const r = await client.session().callOnTarget(method, params, sessionId, opts);
   if (!r.success) return err(cdpErrToToolErr(r.error, method));
@@ -36,10 +44,9 @@ export const cdpCallOnTarget = async <M extends CdpMethod>(
 export const cdpCallBrowser = async <M extends CdpMethod>(
   client: BrowserClient,
   method: M,
-  params?: ParamsOf<M>,
-  opts?: { timeoutMs?: number },
+  ...args: CallArgs<M>
 ): Promise<Result<ResultOf<M>, ToolErr>> => {
-  const r = await client.session().callBrowser(method, params, opts);
+  const r = await client.session().callBrowser(method, ...args);
   if (!r.success) return err(cdpErrToToolErr(r.error, method));
   return r;
 };

package/src/domains/click.ts

@@ -58,11 +58,6 @@ export const clickTool = defineBrowserTool({
     "Click an element. PREFERRED: pass `ref` (e.g. 'e12') from browser_snapshot — it re-resolves the element's position at click time, so it works even after the page re-renders and moves things. Fallback: pass viewport CSS-pixel `x`/`y`. Compositor-level click works through iframes, shadow DOM, and cross-origin content. After clicking, a compact diff of page changes is appended.",
   promptSnippet: "Click an element by ref (preferred) or pixel coordinates",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot (the outline shows '[eN]' for every interactive element) — it survives re-renders, unlike coordinates which go stale after a save/edit reflows the page.",
-    "Fallback: pass (x, y) from the snapshot's '@(x,y)' hint when there's no ref.",
-    "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
-    "After clicking, read the appended page-changes diff to confirm the action landed before moving on (no separate snapshot needed for a quick check).",
-    "Coordinates are viewport CSS pixels (not device pixels). Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content.",
     "If a click doesn't register, run pi with --browser-debug-clicks (or set BH_DEBUG_CLICKS=1) to get annotated screenshots. For React/Vue components ignoring clicks, try browser_dispatch_key.",
   ],
   parameters: ClickArgs,
@@ -85,13 +80,13 @@ export const clickTool = defineBrowserTool({
       if (debug.success) {
         return ok({
           text: `Clicked at ${target}\n[DEBUG] Overlay screenshot: ${debug.data.path}${diff}`,
-          details: { debugScreenshotPath: debug.data.path, x, y, ref: args.ref },
+          details: { debugScreenshotPath: debug.data.path, x, y, ...(args.ref !== undefined ? { ref: args.ref } : {}) },
         });
       }
     }
     return ok({
       text: `Clicked at ${target}${diff}`,
-      details: { x, y, ref: args.ref },
+      details: { x, y, ...(args.ref !== undefined ? { ref: args.ref } : {}) },
     });
   },
 });

package/src/domains/concurrency.ts

@@ -0,0 +1,50 @@
+// A bounded fan-out runner: at most `limit` tasks in flight, nothing started once `signal` aborts, and a task
+// still running at abort time is abandoned (its slot resolves to undefined) so the caller returns on the deadline.
+export const runLimited = async <T, R>(
+  items: ReadonlyArray<T>,
+  opts: { readonly limit: number; readonly signal: AbortSignal },
+  fn: (item: T, signal: AbortSignal) => Promise<R>,
+): Promise<ReadonlyArray<R | undefined>> => {
+  const out: Array<R | undefined> = items.map(() => undefined);
+  const { signal } = opts;
+  const aborted = new Promise<undefined>((resolve) => {
+    if (signal.aborted) resolve(undefined);
+    else signal.addEventListener("abort", () => { resolve(undefined); }, { once: true });
+  });
+  const queue = items.entries();
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const next = queue.next();
+      if (next.done) return;
+      const [i, item] = next.value;
+      if (signal.aborted) continue;
+      try {
+        out[i] = await Promise.race([fn(item, signal), aborted]);
+      } catch {
+        out[i] = undefined;
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.max(1, Math.min(opts.limit, items.length)) }, worker);
+  await Promise.all(workers);
+  return out;
+};
+
+// A signal that fires after `ms`, or earlier if `parent` aborts; `clear` releases the timer once the work is done.
+export const deadlineSignal = (
+  ms: number,
+  parent?: AbortSignal,
+): { readonly signal: AbortSignal; readonly clear: () => void } => {
+  const ac = new AbortController();
+  const onParentAbort = (): void => { ac.abort(); };
+  const timer = setTimeout(() => { ac.abort(); }, ms);
+  if (parent?.aborted) ac.abort();
+  else parent?.addEventListener("abort", onParentAbort, { once: true });
+  return {
+    signal: ac.signal,
+    clear: () => {
+      clearTimeout(timer);
+      parent?.removeEventListener("abort", onParentAbort);
+    },
+  };
+};

package/src/domains/console.ts

@@ -1,11 +1,10 @@
 import { Type } from "typebox";
-import { Markdown, Text } from "@mariozechner/pi-tui";
+import { Markdown } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { type Result, ok } from "../util/result";
-import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
-import type { ConsoleRecord, ConsoleLevel } from "../cdp/console-buffer";
-import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
+import { type ConsoleRecord, type ConsoleLevel, ConsoleRecordSchema } from "../cdp/console-buffer";
 
 const ConsoleArgs = Type.Object({
   levels: Type.Optional(
@@ -42,7 +41,7 @@ const levelTag = (lvl: ConsoleLevel): string => {
     case "warn":  return "[warn] ";
     case "info":  return "[info] ";
     case "debug": return "[debug]";
-    default:      return "[log]  ";
+    case "log":   return "[log]  ";
   }
 };
 
@@ -97,59 +96,17 @@ const renderConsoleMarkdown = (
   return `${headerLines.join("\n")}\n\n${rows}${more}${cursor}`;
 };
 
-type ConsoleDetails = {
-  total: number;
-  returned: number;
-  bufferOverflowed: boolean;
-  truncated: boolean;
-  fullOutputPath?: string;
-  records: ReadonlyArray<ConsoleRecord>;
-  nextCursor?: number;
-};
-
-const CONSOLE_LEVELS: ReadonlyArray<ConsoleLevel> = ["log", "info", "warn", "error", "debug"];
-
-const asConsoleLevel = (v: unknown): ConsoleLevel | undefined =>
-  CONSOLE_LEVELS.find((l) => l === v);
-
-const asConsoleRecord = (v: unknown): ConsoleRecord | undefined => {
-  const o = asRecord(v);
-  if (o === undefined) return undefined;
-  const level = asConsoleLevel(o["level"]);
-  const text = asString(o["text"]);
-  if (level === undefined || text === undefined) return undefined;
-  const url = asString(o["url"]);
-  const lineNumber = asNumber(o["lineNumber"]);
-  const stackTrace = asString(o["stackTrace"]);
-  return {
-    seq: asNumber(o["seq"]) ?? 0,
-    timestampMs: asNumber(o["timestampMs"]) ?? 0,
-    level,
-    text,
-    source: o["source"] === "log-entry" ? "log-entry" : "console-api",
-    ...(url !== undefined ? { url } : {}),
-    ...(lineNumber !== undefined ? { lineNumber } : {}),
-    ...(stackTrace !== undefined ? { stackTrace } : {}),
-  };
-};
+const ConsoleDetailsSchema = Type.Object({
+  total: Type.Number(),
+  returned: Type.Number(),
+  bufferOverflowed: Type.Boolean(),
+  truncated: Type.Boolean(),
+  fullOutputPath: Type.Optional(Type.String()),
+  records: Type.Array(ConsoleRecordSchema),
+  nextCursor: Type.Optional(Type.Number()),
+});
 
-const asConsoleDetails = (v: unknown): ConsoleDetails | undefined => {
-  const o = asRecord(v);
-  if (o === undefined) return undefined;
-  const records = asArrayOf(o["records"], asConsoleRecord);
-  if (records === undefined) return undefined;
-  const fullOutputPath = asString(o["fullOutputPath"]);
-  const nextCursor = asNumber(o["nextCursor"]);
-  return {
-    total: asNumber(o["total"]) ?? records.length,
-    returned: asNumber(o["returned"]) ?? records.length,
-    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
-    truncated: asBoolean(o["truncated"]) ?? false,
-    records,
-    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
-    ...(nextCursor !== undefined ? { nextCursor } : {}),
-  };
-};
+export type ConsoleDetails = DetailsOf<typeof ConsoleDetailsSchema>;
 
 export const consoleTool = defineBrowserTool({
   name: "browser_console",
@@ -158,15 +115,14 @@ export const consoleTool = defineBrowserTool({
     "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
   promptSnippet: "Read JS errors / console output on the current tab",
   promptGuidelines: [
-    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
-    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
     "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
     "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
   ],
   parameters: ConsoleArgs,
+  details: ConsoleDetailsSchema,
   concurrency: "parallel",
 
-  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+  async handler(args, { client }): Promise<Result<ToolOk<ConsoleDetails>, ToolErr>> {
     const session = client.session();
     const drained = session.drainConsoleBuffer({
       ...(args.levels !== undefined ? { levels: args.levels } : {}),
@@ -194,16 +150,14 @@ export const consoleTool = defineBrowserTool({
       truncated: trunc.wasTruncated,
       records: drained.records,
       ...(nextCursor !== undefined ? { nextCursor } : {}),
+      ...(trunc.fullOutputPath !== undefined ? { fullOutputPath: trunc.fullOutputPath } : {}),
     };
-    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
 
     return ok({ text: trunc.text, details });
   },
 
-  renderResult(result, expanded, theme) {
-    const details = asConsoleDetails(result.details);
-    if (!details) return new Text(theme.fg("error", "console: no details"), 0, 0);
-
+  renderResult(result, expanded) {
+    const details = result.details;
     const md = renderConsoleMarkdown(details.records, {
       total: details.total,
       bufferOverflowed: details.bufferOverflowed,
@@ -211,7 +165,7 @@ export const consoleTool = defineBrowserTool({
       nextCursor: details.nextCursor,
     });
     const tail = expanded
-      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
+      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath !== undefined ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
       : `\n\n${keyHint("app.tools.expand", "to expand")}`;
 
     return new Markdown(md + tail, 0, 0, getMarkdownTheme());

package/src/domains/drag.ts

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import type { ParamsOf } from "../cdp/commands";
 import { type Result, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { cdpCall } from "./cdp-call";
@@ -27,37 +28,34 @@ export const dragAndDropTool = defineBrowserTool({
   parameters: DragArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const data = args.dataTransfer
-      ? {
-          items: Object.entries(args.dataTransfer).map(([mimeType, payload]) => ({
-            mimeType,
-            data: Buffer.from(payload).toString("base64"),
-          })),
-          dragOperationsMask: 1,
-        }
-      : { items: [], dragOperationsMask: 1 };
-    type InputCall = readonly ["Input.dispatchMouseEvent" | "Input.dispatchDragEvent", Record<string, unknown>];
-    const calls: ReadonlyArray<InputCall> = [
-      ["Input.dispatchMouseEvent", { type: "mousePressed", x: args.startX, y: args.startY, button: "left", clickCount: 1 }],
-      ["Input.dispatchDragEvent", { type: "dragEnter", x: args.startX, y: args.startY, data, modifiers: 0 }],
-      ...Array.from({ length: 5 }, (_, i): InputCall => {
+    const data: ParamsOf<"Input.dispatchDragEvent">["data"] = {
+      items: Object.entries(args.dataTransfer ?? {}).map(([mimeType, payload]) => ({
+        mimeType,
+        data: Buffer.from(payload).toString("base64"),
+      })),
+      dragOperationsMask: 1,
+    };
+    // Each step is a thunk so the whole sequence is typed against the real Input schemas and still runs in order.
+    const mouse = (p: ParamsOf<"Input.dispatchMouseEvent">) => () => cdpCall(client, "Input.dispatchMouseEvent", p);
+    const drag = (p: ParamsOf<"Input.dispatchDragEvent">) => () => cdpCall(client, "Input.dispatchDragEvent", p);
+    const steps = [
+      mouse({ type: "mousePressed", x: args.startX, y: args.startY, button: "left", clickCount: 1 }),
+      drag({ type: "dragEnter", x: args.startX, y: args.startY, data, modifiers: 0 }),
+      ...Array.from({ length: 5 }, (_, i) => {
         const t = (i + 1) / 5;
-        return [
-          "Input.dispatchDragEvent",
-          {
-            type: "dragOver",
-            x: Math.round(args.startX + (args.endX - args.startX) * t),
-            y: Math.round(args.startY + (args.endY - args.startY) * t),
-            data,
-            modifiers: 0,
-          },
-        ];
+        return drag({
+          type: "dragOver",
+          x: Math.round(args.startX + (args.endX - args.startX) * t),
+          y: Math.round(args.startY + (args.endY - args.startY) * t),
+          data,
+          modifiers: 0,
+        });
       }),
-      ["Input.dispatchDragEvent", { type: "drop", x: args.endX, y: args.endY, data, modifiers: 0 }],
-      ["Input.dispatchMouseEvent", { type: "mouseReleased", x: args.endX, y: args.endY, button: "left", clickCount: 1 }],
+      drag({ type: "drop", x: args.endX, y: args.endY, data, modifiers: 0 }),
+      mouse({ type: "mouseReleased", x: args.endX, y: args.endY, button: "left", clickCount: 1 }),
     ];
-    for (const [method, params] of calls) {
-      const r = await cdpCall(client, method, params);
+    for (const step of steps) {
+      const r = await step();
       if (!r.success) return r;
     }
     return ok({

package/src/domains/element-call.ts

@@ -1,82 +1,120 @@
+import { isRecord } from "../util/guards";
 import type { BrowserClient } from "../client";
 import { safeJs } from "../util/js-template";
 import { type Result, err, ok } from "../util/result";
-import type { ToolErr } from "../util/tool";
+import type { JsonObject, ToolErr } from "../util/tool";
 import { cdpCall, evalJs } from "./cdp-call";
+import type { PageOption, PageResult } from "./page/fill.page";
 import { resolveRefToObjectId } from "./ref-resolve";
 
-export type PageResult = {
-  readonly ok: boolean;
-  readonly reason?: string;
-  readonly kind?: string;
-  readonly value?: unknown;
-  readonly text?: string;
-  readonly checked?: boolean;
-  readonly changed?: boolean;
-  readonly tag?: string;
-  readonly options?: ReadonlyArray<{ value: string; text: string }>;
-};
+// PageResult is declared once, in the page module that produces it (page/fill.page.ts), so the guard below is checked
+// against the same declaration the page function returns.
+export type { PageOption, PageResult };
 
-const isOption = (v: unknown): v is { readonly value: string; readonly text: string } =>
+const isOption = (v: unknown): v is PageOption =>
   typeof v === "object" && v !== null
   && "value" in v && typeof v.value === "string"
   && "text" in v && typeof v.text === "string";
 
+const hasTag = (v: object): v is { readonly tag: string } => "tag" in v && typeof v.tag === "string";
+
 export const isPageResult = (v: unknown): v is PageResult => {
   if (typeof v !== "object" || v === null) return false;
   if (!("ok" in v) || typeof v.ok !== "boolean") return false;
-  if ("reason" in v && typeof v.reason !== "string") return false;
-  if ("kind" in v && typeof v.kind !== "string") return false;
-  if ("text" in v && typeof v.text !== "string") return false;
-  if ("checked" in v && typeof v.checked !== "boolean") return false;
-  if ("changed" in v && typeof v.changed !== "boolean") return false;
-  if ("tag" in v && typeof v.tag !== "string") return false;
-  if ("options" in v && !(Array.isArray(v.options) && v.options.every(isOption))) return false;
-  return true;
+  if (!v.ok) {
+    if (!("reason" in v) || typeof v.reason !== "string") return false;
+    if ("tag" in v && typeof v.tag !== "string") return false;
+    if ("code" in v && v.code !== "select_rejected" && v.code !== "no_match") return false;
+    if ("options" in v && !(Array.isArray(v.options) && v.options.every(isOption))) return false;
+    return true;
+  }
+  if (!("kind" in v) || typeof v.kind !== "string" || !hasTag(v)) return false;
+  switch (v.kind) {
+    case "select":
+      return "value" in v && typeof v.value === "string" && "text" in v && typeof v.text === "string";
+    case "checkbox":
+    case "radio":
+      return "checked" in v && typeof v.checked === "boolean" && "changed" in v && typeof v.changed === "boolean";
+    case "input":
+    case "textarea":
+    case "contenteditable":
+      return "value" in v && typeof v.value === "string";
+    default:
+      return false;
+  }
+};
+
+// The one not-found shape for element lookups: the page never reports it, the harness does.
+export type ElementOutcome =
+  | { readonly found: false }
+  | { readonly found: true; readonly value: unknown };
+
+const isElementOutcome = (v: unknown): v is ElementOutcome => {
+  if (!isRecord(v)) return false;
+  if (v["found"] === false) return true;
+  return v["found"] === true && "value" in v;
+};
+
+const callOnObject = async (
+  client: BrowserClient,
+  objectId: string,
+  functionDeclaration: string,
+  args: ReadonlyArray<unknown>,
+  ref: string,
+): Promise<Result<unknown, ToolErr>> => {
+  try {
+    const called = await cdpCall(client, "Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration,
+      arguments: args.map((v) => ({ value: v })),
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    if (!called.success) return err({ ...called.error, details: { ...(called.error.details ?? {}), ref } });
+    if (called.data.exceptionDetails !== undefined) {
+      return err({ kind: "cdp_error", message: `page function threw: ${JSON.stringify(called.data.exceptionDetails)}`, details: { ref } });
+    }
+    return ok(called.data.result.value);
+  } finally {
+    await cdpCall(client, "Runtime.releaseObject", { objectId });
+  }
 };
 
+// Runs an element function (its declaration from page/inject.ts elementFunctionSource) on the element a ref or
+// selector names. A ref goes through Runtime.callFunctionOn; a selector is looked up in one Runtime.evaluate round trip.
 export const runOnElement = async (
   client: BrowserClient,
   opts: {
     ref?: string | undefined;
     selector?: string | undefined;
-    fnBody: string;
-    arg: unknown;
-    notFound?: unknown;
+    functionDeclaration: string;
+    args: ReadonlyArray<unknown>;
   },
-): Promise<Result<unknown, ToolErr>> => {
+): Promise<Result<ElementOutcome, ToolErr>> => {
   if (opts.ref !== undefined) {
     const objectId = await resolveRefToObjectId(client, opts.ref);
     if (!objectId.success) return objectId;
-    const r = await cdpCall(client, "Runtime.callFunctionOn", {
-      objectId: objectId.data,
-      functionDeclaration: `function (arg) { ${opts.fnBody} }`,
-      arguments: [{ value: opts.arg }],
-      returnByValue: true,
-    });
+    const r = await callOnObject(client, objectId.data, opts.functionDeclaration, opts.args, opts.ref);
     if (!r.success) return r;
-    if (r.data.exceptionDetails !== undefined) {
-      return err({
-        kind: "cdp_error",
-        message: `page function threw: ${r.data.exceptionDetails.text}`,
-        details: { ref: opts.ref },
-      });
-    }
-    return ok(r.data.result.value);
+    return ok({ found: true, value: r.data });
   }
   if (opts.selector === undefined) {
-    return err({ kind: "invalid_state", message: "Provide either `ref` or `selector`." });
+    return err({ kind: "invalid_args", message: "Provide either `ref` or `selector`." });
   }
-  // fnBody is harness-authored, not user input; only the selector and value are interpolated, and those go through safeJs.
+  // The function source is harness-authored, not user input; only the selector and the arguments are interpolated,
+  // and those go through safeJs.
   const prelude = safeJs`
     (() => {
       const el = document.querySelector(${opts.selector});
-      if (!el) return ${opts.notFound ?? { status: "not_found" }};
-      const __arg = ${opts.arg};
-      return (function (arg) {`;
-  const expr = `${prelude} ${opts.fnBody} }).call(el, __arg); })()`;
+      if (!el) return { found: false };
+      const __args = ${opts.args};
+      return { found: true, value: (`;
+  const expr = prelude + opts.functionDeclaration + ").apply(el, __args) }; })()";
   const r = await evalJs(client, expr);
   if (!r.success) return r;
+  if (!isElementOutcome(r.data)) {
+    return err({ kind: "internal", message: "unexpected page result shape from element lookup", details: { selector: opts.selector } });
+  }
   return ok(r.data);
 };
 
@@ -88,30 +126,26 @@ export const resolveAndCall = async (
 ): Promise<Result<PageResult, ToolErr>> => {
   const objectId = await resolveRefToObjectId(client, ref);
   if (!objectId.success) return objectId;
-  const handle = objectId.data;
-  try {
-    const called = await cdpCall(client, "Runtime.callFunctionOn", {
-      objectId: handle,
-      functionDeclaration,
-      arguments: args.map((v) => ({ value: v })),
-      returnByValue: true,
-      awaitPromise: true,
-    });
-    if (!called.success) return err({ ...called.error, details: { ref } });
-    if (called.data.exceptionDetails !== undefined) {
-      return err({ kind: "cdp_error", message: `page function threw: ${JSON.stringify(called.data.exceptionDetails)}`, details: { ref } });
-    }
-    const value = called.data.result.value;
-    if (!isPageResult(value)) {
-      return err({ kind: "internal", message: "page function returned no result object", details: { ref } });
-    }
-    return ok(value);
-  } finally {
-    await cdpCall(client, "Runtime.releaseObject", { objectId: handle });
+  const r = await callOnObject(client, objectId.data, functionDeclaration, args, ref);
+  if (!r.success) return r;
+  if (!isPageResult(r.data)) {
+    return err({ kind: "internal", message: "unexpected page result shape", details: { ref } });
   }
+  return ok(r.data);
 };
 
-export const detailsOf = (ref: string, res: PageResult, extra?: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> => {
-  const { ok: _ok, ...rest } = res;
-  return { ref, ...rest, ...(extra ?? {}) };
+// The page result minus its `ok` flag (the caller has already branched on it), as JSON for a tool's details.
+export const detailsOf = (ref: string, res: PageResult): JsonObject => {
+  if (!res.ok) {
+    return {
+      ref,
+      reason: res.reason,
+      ...(res.tag !== undefined ? { tag: res.tag } : {}),
+      ...(res.code !== undefined ? { code: res.code } : {}),
+      ...(res.options !== undefined ? { options: res.options } : {}),
+    };
+  }
+  if ("checked" in res) return { ref, kind: res.kind, checked: res.checked, changed: res.changed, tag: res.tag };
+  if (res.kind === "select") return { ref, kind: res.kind, value: res.value, text: res.text, tag: res.tag };
+  return { ref, kind: res.kind, value: res.value, tag: res.tag };
 };