pi-browser-harness 0.10.2 → 0.11.0

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);
 };
 
@@ -108,6 +162,7 @@ export const readPageTool = defineBrowserTool({
     "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 },

package/src/domains/screenshot-capture.ts

@@ -0,0 +1,80 @@
+import { rename, writeFile } from "node:fs/promises";
+import type { BrowserClient } from "../client";
+import { type Result, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { screenshotPath } from "../util/paths";
+import { loadSharp } from "../util/sharp-shim";
+import { safeJs } from "../util/js-template";
+import { cdpCall, evalJs } from "./cdp-call";
+
+export type CaptureArgs = {
+  readonly fullPage?: boolean;
+  readonly format?: "png" | "jpeg";
+  readonly quality?: number;
+};
+
+export const captureBase = async (
+  client: BrowserClient,
+  args: CaptureArgs,
+): Promise<Result<{ readonly path: string; readonly format: "png" | "jpeg" }, ToolErr>> => {
+  const format = args.format ?? "png";
+  const quality = args.quality ?? 80;
+  const path = screenshotPath(client.namespace, format);
+  const r = await cdpCall(client, "Page.captureScreenshot", {
+    format,
+    captureBeyondViewport: args.fullPage ?? false,
+    ...(format === "jpeg" ? { quality } : {}),
+  });
+  if (!r.success) return r;
+  await writeFile(path, Buffer.from(r.data.data, "base64"));
+  return ok({ path, format });
+};
+
+export const resizeIfNeeded = async (
+  path: string,
+  maxDim: number,
+): Promise<{ readonly note: string }> => {
+  const load = await loadSharp();
+  if (load.kind === "missing") return { note: " (maxDim ignored: install sharp for auto-resize)" };
+  if (load.kind === "error") return { note: ` (maxDim ignored: sharp failed to load: ${load.message})` };
+  try {
+    const meta = await load.sharp(path).metadata();
+    const w = meta.width ?? 0;
+    const h = meta.height ?? 0;
+    if (Math.max(w, h) <= maxDim) return { note: "" };
+    const tmp = `${path}.resized`;
+    await load.sharp(path).resize(maxDim, maxDim, { fit: "inside" }).toFile(tmp);
+    await rename(tmp, path);
+    return { note: ` (resized to fit ${maxDim}px)` };
+  } catch (e) {
+    return { note: ` (maxDim ignored: sharp threw: ${e instanceof Error ? e.message : String(e)})` };
+  }
+};
+
+export const captureWithCrosshair = async (
+  client: BrowserClient,
+  args: { readonly x: number; readonly y: number; readonly format?: "png" | "jpeg"; readonly quality?: number },
+): Promise<Result<{ readonly path: string }, ToolErr>> => {
+  const cap = await captureBase(client, args);
+  if (!cap.success) return cap;
+  const load = await loadSharp();
+  if (load.kind !== "ok") return ok({ path: cap.data.path });
+  try {
+    const dprR = await evalJs(client, safeJs`window.devicePixelRatio`);
+    const dpr = dprR.success && typeof dprR.data === "number" ? dprR.data : 1;
+    const meta = await load.sharp(cap.data.path).metadata();
+    const w = meta.width ?? 0;
+    const h = meta.height ?? 0;
+    const px = Math.round(args.x * dpr);
+    const py = Math.round(args.y * dpr);
+    const r = Math.round(15 * dpr);
+    const stroke = Math.max(2, Math.round(3 * dpr));
+    const svg = `<svg width="${w}" height="${h}"><circle cx="${px}" cy="${py}" r="${r}" fill="none" stroke="red" stroke-width="${stroke}" opacity="0.8"/><line x1="${px - r - 5}" y1="${py}" x2="${px + r + 5}" y2="${py}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/><line x1="${px}" y1="${py - r - 5}" x2="${px}" y2="${py + r + 5}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/></svg>`;
+    const tmp = `${cap.data.path}.debug`;
+    await load.sharp(cap.data.path).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).toFile(tmp);
+    await rename(tmp, cap.data.path);
+    return ok({ path: cap.data.path });
+  } catch {
+    return ok({ path: cap.data.path });
+  }
+};

package/src/domains/screenshot.ts

@@ -1,13 +1,10 @@
 import { readFileSync } from "node:fs";
-import { writeFile, rename } from "node:fs/promises";
 import { Type } from "typebox";
 import { Image, type ImageTheme, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { BrowserClient } from "../client";
-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 { screenshotPath } from "../util/paths";
-import { loadSharp } from "../util/sharp-shim";
-import { safeJs } from "../util/js-template";
+import { asRecord, asString } from "../util/guards";
+import { captureBase, resizeIfNeeded } from "./screenshot-capture";
 
 const ScreenshotArgs = Type.Object({
   fullPage: Type.Optional(Type.Boolean({ default: false, description: "Capture beyond viewport" })),
@@ -16,50 +13,6 @@ const ScreenshotArgs = Type.Object({
   maxDim: Type.Optional(Type.Integer({ minimum: 100, maximum: 8000, description: "If max(w,h) exceeds this, resize via sharp." })),
 });
 
-type CaptureArgs = {
-  readonly fullPage?: boolean;
-  readonly format?: "png" | "jpeg";
-  readonly quality?: number;
-};
-
-const captureBase = async (
-  client: BrowserClient,
-  args: CaptureArgs,
-): Promise<Result<{ readonly path: string; readonly format: "png" | "jpeg" }, ToolErr>> => {
-  const format = args.format ?? "png";
-  const quality = args.quality ?? 80;
-  const path = screenshotPath(client.namespace, format);
-  const params: Record<string, unknown> = { format, captureBeyondViewport: args.fullPage ?? false };
-  if (format === "jpeg") params["quality"] = quality;
-  const r = await client.session().call("Page.captureScreenshot", params);
-  if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-  // Page.captureScreenshot returns { data: base64 }
-  const data = (r.data as { data: string }).data;
-  await writeFile(path, Buffer.from(data, "base64"));
-  return ok({ path, format });
-};
-
-const resizeIfNeeded = async (
-  path: string,
-  maxDim: number,
-): Promise<{ readonly note: string }> => {
-  const load = await loadSharp();
-  if (load.kind === "missing") return { note: " (maxDim ignored: install sharp for auto-resize)" };
-  if (load.kind === "error") return { note: ` (maxDim ignored: sharp failed to load: ${load.message})` };
-  try {
-    const meta = await load.sharp(path).metadata();
-    const w = meta.width ?? 0;
-    const h = meta.height ?? 0;
-    if (Math.max(w, h) <= maxDim) return { note: "" };
-    const tmp = `${path}.resized`;
-    await load.sharp(path).resize(maxDim, maxDim, { fit: "inside" }).toFile(tmp);
-    await rename(tmp, path);
-    return { note: ` (resized to fit ${maxDim}px)` };
-  } catch (e) {
-    return { note: ` (maxDim ignored: sharp threw: ${e instanceof Error ? e.message : String(e)})` };
-  }
-};
-
 export const screenshotTool = defineBrowserTool({
   name: "browser_screenshot",
   label: "Browser Screenshot",
@@ -74,6 +27,7 @@ export const screenshotTool = defineBrowserTool({
     "format='jpeg' with quality 60-90 keeps screenshots small for photo-heavy pages. Use maxDim if the page is huge.",
   ],
   parameters: ScreenshotArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cap = await captureBase(client, args);
     if (!cap.success) return cap;
@@ -89,15 +43,16 @@ export const screenshotTool = defineBrowserTool({
   },
 
   renderResult(result, _expanded, theme) {
-    const details = result.details as { path?: string; format?: string } | undefined;
-    const filePath = details?.path;
+    const raw = asRecord(result.details);
+    const filePath = raw === undefined ? undefined : asString(raw["path"]);
     if (!filePath) {
       return new Text(theme.fg("error", "Screenshot path missing"), 0, 0);
     }
+    const format = raw === undefined ? undefined : asString(raw["format"]);
     try {
       const buf = readFileSync(filePath);
       const b64 = buf.toString("base64");
-      const mimeType = details?.format === "jpeg" ? "image/jpeg" : "image/png";
+      const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
       const imageTheme: ImageTheme = {
         fallbackColor: (str: string) => theme.fg("dim", str),
       };
@@ -106,10 +61,7 @@ export const screenshotTool = defineBrowserTool({
         maxHeightCells: 24,
         filename: filePath,
       });
-      // Image's text fallback (when terminal lacks inline-image support) does
-      // not respect the rendered width, so a long file path can blow past the
-      // terminal width and crash the host TUI. Wrap the component to truncate
-      // each rendered line to fit.
+      // Image's text fallback does not respect the rendered width, so an unwrapped long path can blow past the terminal width and crash the host TUI.
       return {
         invalidate: () => image.invalidate(),
         render: (width: number) =>
@@ -122,32 +74,3 @@ export const screenshotTool = defineBrowserTool({
     }
   },
 });
-
-export const captureWithCrosshair = async (
-  client: BrowserClient,
-  args: { readonly x: number; readonly y: number; readonly format?: "png" | "jpeg"; readonly quality?: number },
-): Promise<Result<{ readonly path: string }, ToolErr>> => {
-  const cap = await captureBase(client, args);
-  if (!cap.success) return cap;
-  const load = await loadSharp();
-  if (load.kind !== "ok") return ok({ path: cap.data.path });
-  try {
-    const dprR = await client.evaluateJs(safeJs`window.devicePixelRatio`);
-    const dpr = dprR.success && typeof dprR.data === "number" ? dprR.data : 1;
-    const meta = await load.sharp(cap.data.path).metadata();
-    const w = meta.width ?? 0;
-    const h = meta.height ?? 0;
-    const px = Math.round(args.x * dpr);
-    const py = Math.round(args.y * dpr);
-    const r = Math.round(15 * dpr);
-    const stroke = Math.max(2, Math.round(3 * dpr));
-    const svg = `<svg width="${w}" height="${h}"><circle cx="${px}" cy="${py}" r="${r}" fill="none" stroke="red" stroke-width="${stroke}" opacity="0.8"/><line x1="${px - r - 5}" y1="${py}" x2="${px + r + 5}" y2="${py}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/><line x1="${px}" y1="${py - r - 5}" x2="${px}" y2="${py + r + 5}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/></svg>`;
-    const tmp = `${cap.data.path}.debug`;
-    await load.sharp(cap.data.path).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).toFile(tmp);
-    await rename(tmp, cap.data.path);
-    return ok({ path: cap.data.path });
-  } catch {
-    // Crosshair overlay is best-effort; on failure return the plain screenshot.
-    return ok({ path: cap.data.path });
-  }
-};

package/src/domains/scroll.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 { cdpCall } from "./cdp-call";
 
 const ScrollArgs = Type.Object({
   x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
@@ -23,6 +24,7 @@ export const scrollTool = defineBrowserTool({
     "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
   ],
   parameters: ScrollArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const info = await client.pageInfo();
     if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
@@ -36,22 +38,19 @@ export const scrollTool = defineBrowserTool({
     const cy = args.y ?? Math.round(info.data.height / 2);
     const dx = args.deltaX ?? 0;
     const dy = args.deltaY ?? 300;
-    // The page target must be focused or Input events are dropped silently
-    // (mouseWheel hangs; synthesizeScrollGesture returns ok but no scroll).
-    // Page.bringToFront makes the target the active one in the browser.
-    const front = await client.session().call("Page.bringToFront", {});
-    if (!front.success) return err({ kind: "cdp_error", message: front.error.message });
-    // Establish compositor mouse position before mouseWheel; without this,
-    // CDP sometimes drops the wheel event with a timeout.
-    const moved = await client.session().call("Input.dispatchMouseEvent", {
+    // The page target must be focused or Input events are dropped silently: mouseWheel hangs and synthesizeScrollGesture returns ok without scrolling.
+    const front = await cdpCall(client, "Page.bringToFront", {});
+    if (!front.success) return front;
+    // Establish compositor mouse position first, or CDP sometimes drops the wheel event with a timeout.
+    const moved = await cdpCall(client, "Input.dispatchMouseEvent", {
       type: "mouseMoved", x: cx, y: cy, button: "none", buttons: 0,
     });
-    if (!moved.success) return err({ kind: "cdp_error", message: moved.error.message });
-    const wheel = await client.session().call("Input.dispatchMouseEvent", {
+    if (!moved.success) return moved;
+    const wheel = await cdpCall(client, "Input.dispatchMouseEvent", {
       type: "mouseWheel", x: cx, y: cy, deltaX: dx, deltaY: dy,
       button: "none", buttons: 0, pointerType: "mouse",
     });
-    if (!wheel.success) return err({ kind: "cdp_error", message: wheel.error.message });
+    if (!wheel.success) return wheel;
     return ok({
       text: `Scrolled at (${cx}, ${cy}) by (${dx}, ${dy})`,
       details: { x: cx, y: cy, deltaX: dx, deltaY: dy },