pi-browser-harness 0.1.0 → 0.3.1

package/src/domains/keyboard.ts

@@ -0,0 +1,127 @@
+import { Type } from "typebox";
+import { safeJs } from "../util/js-template";
+import { virtualKeyCode } from "../util/keycodes";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const TypeArgs = Type.Object({
+  text: Type.String({ description: "Text to type" }),
+});
+
+export const typeTool = defineBrowserTool({
+  name: "browser_type",
+  label: "Browser Type",
+  description: "Type text into the currently focused element. Use browser_click first to focus an input field.",
+  promptSnippet: "Type text into the focused element",
+  promptGuidelines: [
+    "Use browser_type to enter text. Click on an input field with browser_click first to focus it.",
+    "For special keys (Enter, Tab, Escape, arrows), use browser_press_key instead.",
+  ],
+  parameters: TypeArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.session().call("Input.insertText", { text: args.text });
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    return ok({ text: `Typed: "${args.text}"` });
+  },
+});
+
+const PressKeyArgs = Type.Object({
+  key: Type.String({
+    description:
+      'Key to press. Special keys: Enter, Tab, Backspace, Escape, Delete, ArrowLeft/Up/Right/Down, Home, End, PageUp, PageDown. Space as " "',
+  }),
+  modifiers: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: 15,
+      description: "Modifier bitfield: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift. Combine with OR.",
+    }),
+  ),
+});
+
+export const pressKeyTool = defineBrowserTool({
+  name: "browser_press_key",
+  label: "Browser Press Key",
+  description:
+    "Press a keyboard key. Supports special keys (Enter, Tab, Backspace, Escape, Delete, arrows, Home, End, PageUp, PageDown, Space as ' ') and regular characters. Optional modifier bitfield: 1=Alt, 2=Ctrl, 4=Meta/Cmd, 8=Shift.",
+  promptSnippet: "Press a key (Enter, Tab, Escape, arrows, or any character)",
+  promptGuidelines: [
+    "Use browser_press_key for keyboard shortcuts and navigation keys.",
+    "Special key names: Enter, Tab, Backspace, Escape, Delete, ArrowLeft, ArrowUp, ArrowRight, ArrowDown, Home, End, PageUp, PageDown.",
+    "Use Space as ' ' (a single space character).",
+    "Modifiers: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift. Combine with bitwise OR: Ctrl+Shift = 2|8 = 10.",
+  ],
+  parameters: PressKeyArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const k = args.key;
+    const code = virtualKeyCode(k);
+    const modifiers = args.modifiers ?? 0;
+    const isChar = k.length === 1;
+    const downParams: Record<string, unknown> = {
+      type: "keyDown",
+      key: k,
+      code: k,
+      modifiers,
+      ...(code ? { windowsVirtualKeyCode: code, nativeVirtualKeyCode: code } : {}),
+      ...(isChar ? { text: k, unmodifiedText: k } : {}),
+    };
+    const down = await client.session().call("Input.dispatchKeyEvent", downParams);
+    if (!down.success) return err({ kind: "cdp_error", message: down.error.message });
+    const up = await client.session().call("Input.dispatchKeyEvent", { type: "keyUp", key: k, code: k, modifiers });
+    if (!up.success) return err({ kind: "cdp_error", message: up.error.message });
+    return ok({ text: `Pressed: ${k}${modifiers ? ` (modifiers=${modifiers})` : ""}` });
+  },
+});
+
+const DispatchKeyArgs = Type.Object({
+  selector: Type.String({ description: "CSS selector of the target element" }),
+  key: Type.String({ description: "Key value (e.g., 'Enter', 'a')" }),
+  eventType: Type.Optional(
+    Type.Union(
+      [Type.Literal("keydown"), Type.Literal("keyup"), Type.Literal("keypress")],
+      { default: "keydown", description: "Event type to dispatch. Default: keydown" },
+    ),
+  ),
+});
+
+export const dispatchKeyTool = defineBrowserTool({
+  name: "browser_dispatch_key",
+  label: "Browser Dispatch Key",
+  description:
+    "Dispatch a DOM KeyboardEvent on a specific element via JS injection. Use for React/Vue components that listen to synthetic events more reliably than CDP input.",
+  promptSnippet: "Dispatch a DOM KeyboardEvent on a specific element",
+  promptGuidelines: [
+    "Dispatches a synthetic DOM KeyboardEvent — for React/Vue synthetic event listeners. Does NOT insert text into inputs (use browser_type or browser_press_key for actual typing).",
+    "Try browser_press_key first; only use browser_dispatch_key when the page ignores raw CDP key events.",
+    "The selector must match exactly one or more elements; zero matches is reported as an error.",
+    "eventType defaults to 'keydown'.",
+  ],
+  parameters: DispatchKeyArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const eventType = args.eventType ?? "keydown";
+    const expr = safeJs`
+      (() => {
+        const els = document.querySelectorAll(${args.selector});
+        if (els.length === 0) return 0;
+        for (const el of els) {
+          el.dispatchEvent(new KeyboardEvent(${eventType}, { key: ${args.key}, bubbles: true, cancelable: true }));
+        }
+        return els.length;
+      })()
+    `;
+    const r = await client.evaluateJs(expr);
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const matched = Number(r.data ?? 0);
+    if (matched === 0) {
+      return err({
+        kind: "invalid_state",
+        message: `Selector matched 0 elements: ${args.selector}`,
+        details: { matched: 0, selector: args.selector },
+      });
+    }
+    return ok({
+      text: `Dispatched ${eventType}('${args.key}') on ${matched} element(s)`,
+      details: { matched, selector: args.selector },
+    });
+  },
+});

package/src/domains/navigate.ts

@@ -0,0 +1,146 @@
+import { Type } from "typebox";
+import { Text } from "@mariozechner/pi-tui";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+
+const NavigateArgs = Type.Object({
+  url: Type.String({ description: "Full URL to navigate to (e.g. https://github.com)" }),
+});
+
+export type NavOutcome =
+  | { readonly kind: "in_place"; readonly targetId: string }
+  | { readonly kind: "new_tab_created"; readonly targetId: string; readonly reason: "no_tabs" };
+
+export const navigateTool = defineBrowserTool({
+  name: "browser_navigate",
+  label: "Browser Navigate",
+  description:
+    "Navigate to a URL. Creates a new tab on first call (when no real tabs exist). Otherwise navigates the current tab in place.",
+  promptSnippet: "Navigate to a URL",
+  promptGuidelines: [
+    "Use browser_navigate to go to URLs.",
+    "Use browser_wait_for_load after browser_navigate to wait for the page to finish loading.",
+    "For extracting data from a page you already navigated to, use browser_execute_js or browser_http_get (faster for APIs).",
+    "Note: Google and some sites with strict anti-bot detection may reject CDP navigation. Use browser_http_get for search results.",
+  ],
+  parameters: NavigateArgs,
+  renderCall: (a) => new Text(`🌐 Navigate to ${a.url}`, 0, 0),
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const tabs = await client.listTabs(false);
+    if (!tabs.success) return err({ kind: "cdp_error", message: tabs.error.message });
+    let outcome: NavOutcome;
+    if (tabs.data.length === 0) {
+      const created = await client.newTab(args.url);
+      if (!created.success) return err({ kind: "cdp_error", message: created.error.message });
+      outcome = { kind: "new_tab_created", targetId: created.data, reason: "no_tabs" };
+    } else {
+      const nav = await client.session().call("Page.navigate", { url: args.url });
+      if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+      const cur = client.current();
+      if (!cur) return err({ kind: "internal", message: "navigate succeeded but no current target tracked" });
+      outcome = { kind: "in_place", targetId: cur.targetId };
+    }
+    const info = await client.pageInfo();
+    if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
+    if ("dialog" in info.data) {
+      return ok({
+        text: `Navigated to ${args.url}\nTarget: ${outcome.targetId}\n⚠️  Dialog open: ${info.data.dialog.type} — "${info.data.dialog.message}"\nUse browser_handle_dialog.`,
+        details: { outcome, dialog: info.data.dialog },
+      });
+    }
+    const prefix = outcome.kind === "new_tab_created" ? "New tab: " : "";
+    return ok({
+      text: `${prefix}Navigated to: ${info.data.url}\nTitle: ${info.data.title}\nViewport: ${info.data.width}x${info.data.height}\nTarget: ${outcome.targetId}`,
+      details: { outcome, page: info.data },
+    });
+  },
+});
+
+const OpenUrlsArgs = Type.Object({
+  urls: Type.Array(Type.String(), { description: "Array of URLs to open in new tabs" }),
+});
+
+type TabResult = {
+  readonly url: string;
+  readonly targetId: string;
+  readonly ok: boolean;
+  readonly error?: string;
+};
+
+export const openUrlsTool = defineBrowserTool({
+  name: "browser_open_urls",
+  label: "Browser Open URLs",
+  description: "Open multiple URLs in parallel new tabs. Returns per-URL outcomes.",
+  promptSnippet: "Open multiple URLs in new tabs (parallel)",
+  promptGuidelines: [
+    "Use after web_search to open citations in parallel.",
+    "After opening, use browser_list_tabs / browser_switch_tab / browser_screenshot to interact.",
+    "Use browser_wait_for_load on a tab before extracting data from SPAs.",
+  ],
+  parameters: OpenUrlsArgs,
+  renderCall: (a) => new Text(`🌐 Opening ${a.urls.length} URL${a.urls.length !== 1 ? "s" : ""}…`, 0, 0),
+  async handler(args, { client, onUpdate }): Promise<Result<ToolOk, ToolErr>> {
+    const total = args.urls.length;
+    // Phase 1: create tabs in parallel.
+    const created = await Promise.all(args.urls.map(async (url): Promise<TabResult> => {
+      const r = await client.session().callBrowser("Target.createTarget", { url: "about:blank" });
+      if (!r.success) return { url, targetId: "", ok: false, error: r.error.message };
+      const c = r.data as { targetId: string }; // CDP boundary cast: Target.createTarget returns { targetId: string }
+      return { url, targetId: c.targetId, ok: true };
+    }));
+    // Phase 2: attach + navigate each created tab in parallel.
+    let completed = 0;
+    const settled = await Promise.all(
+      created.filter((t) => t.ok).map(async (tab): Promise<TabResult> => {
+        try {
+          const attached = await client.session().callBrowser("Target.attachToTarget", { targetId: tab.targetId, flatten: true });
+          if (!attached.success) return { ...tab, ok: false, error: attached.error.message };
+          const sid = (attached.data as { sessionId: string }).sessionId; // CDP boundary cast: Target.attachToTarget returns { sessionId: string }
+          const enabled = await client.session().callOnTarget("Page.enable", {}, sid);
+          if (!enabled.success) return { ...tab, ok: false, error: enabled.error.message };
+          const nav = await client.session().callOnTarget("Page.navigate", { url: tab.url }, sid);
+          if (!nav.success) return { ...tab, ok: false, error: nav.error.message };
+          return tab;
+        } finally {
+          completed++;
+          // onUpdate must never escape: a renderer crash would otherwise
+          // tear down the tool call.
+          try {
+            onUpdate({ text: `Opening URLs… ${completed}/${created.filter((t) => t.ok).length} navigated` });
+          } catch { /* swallow */ }
+        }
+      }),
+    );
+    const failures = created.filter((t) => !t.ok);
+    const all: ReadonlyArray<TabResult> = [...settled, ...failures];
+    const okTabs = all.filter((r) => r.ok);
+    const failTabs = all.filter((r) => !r.ok);
+    // Phase 3: activate the last successfully-opened tab so the user sees something.
+    if (okTabs.length > 0) {
+      const last = okTabs[okTabs.length - 1];
+      if (last) {
+        await client.session().callBrowser("Target.activateTarget", { targetId: last.targetId });
+      }
+    }
+    const lines: string[] = [];
+    if (okTabs.length) {
+      lines.push(`✅ ${okTabs.length}/${total} tabs opened:`, ...okTabs.map((t, i) => `  [${i}] ${t.url} → ${t.targetId}`));
+    }
+    if (failTabs.length) {
+      lines.push(`❌ ${failTabs.length}/${total} failed:`, ...failTabs.map((t) => `  ${t.url}: ${t.error ?? "unknown"}`));
+    }
+    const truncated = await applyTruncation(lines.join("\n"), "urls");
+    if (okTabs.length === 0) {
+      return err({
+        kind: "cdp_error",
+        message: `All ${total} URLs failed`,
+        ...(truncated.fullOutputPath ? { details: { tabs: all, fullOutputPath: truncated.fullOutputPath } } : { details: { tabs: all } }),
+      });
+    }
+    return ok({
+      text: truncated.text,
+      ...(truncated.fullOutputPath ? { details: { tabs: all, fullOutputPath: truncated.fullOutputPath } } : { details: { tabs: all } }),
+    });
+  },
+});

package/src/domains/network.ts

@@ -0,0 +1,80 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+
+const HttpGetArgs = Type.Object({
+  url: Type.String({ description: "URL to GET" }),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Optional HTTP headers" })),
+  timeout: Type.Optional(
+    Type.Number({ default: 20, minimum: 1, maximum: 120, description: "Total seconds (covers headers AND body)" }),
+  ),
+});
+
+export const httpGetTool = defineBrowserTool({
+  name: "browser_http_get",
+  label: "Browser HTTP GET",
+  description:
+    "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,
+  ensureAlive: false,
+  async handler(args): Promise<Result<ToolOk, ToolErr>> {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), (args.timeout ?? 20) * 1000);
+    try {
+      const fetchInit: RequestInit = { signal: ac.signal };
+      if (args.headers !== undefined) fetchInit.headers = args.headers;
+      const res = await fetch(args.url, fetchInit);
+      const body = await res.text();
+      clearTimeout(timer);
+      const ct = res.headers.get("content-type") ?? "";
+      const truncated = await applyTruncation(body, "http");
+      return ok({
+        text: `HTTP ${res.status} ${ct}\n${truncated.text}`,
+        details: truncated.fullOutputPath !== undefined
+          ? { status: res.status, contentType: ct, length: body.length, fullOutputPath: truncated.fullOutputPath, wasTruncated: truncated.wasTruncated }
+          : { status: res.status, contentType: ct, length: body.length, wasTruncated: truncated.wasTruncated },
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const msg = e instanceof Error ? e.message : String(e);
+      const kind: ToolErr["kind"] = msg.toLowerCase().includes("abort") ? "timeout" : "io_error";
+      return err({ kind, message: msg });
+    }
+  },
+});
+
+const NetLogArgs = Type.Object({
+  eventTypes: Type.Optional(
+    Type.Array(Type.String(), { description: "CDP event names to filter (e.g., ['Network.requestWillBeSent'])" }),
+  ),
+  limit: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 500 })),
+});
+
+export const getNetworkLogTool = defineBrowserTool({
+  name: "browser_get_network_log",
+  label: "Browser Get Network Log",
+  description:
+    "Read buffered Network.* CDP events. NOTE: in v0.3 the event stream is consumed internally by the session manager; this tool is a placeholder. Use browser_execute_js with PerformanceObserver as a workaround.",
+  promptSnippet: "Get buffered network events (DEPRECATED in v0.3 — use browser_execute_js with PerformanceObserver instead)",
+  promptGuidelines: [
+    "v0.3 routes CDP events through an internal AsyncIterable; a synchronous drain API isn't exposed yet.",
+    "For now, use browser_execute_js with PerformanceObserver, performance.getEntries(), or fetch interceptors.",
+  ],
+  parameters: NetLogArgs,
+  async handler(args): Promise<Result<ToolOk, ToolErr>> {
+    return ok({
+      text: "browser_get_network_log: in v0.3 the CDP event stream is consumed by the session; use browser_execute_js with PerformanceObserver or performance.getEntries() to inspect network activity.",
+      details: {
+        deprecated: true,
+        eventTypes: args.eventTypes ?? null,
+        limit: args.limit ?? null,
+      },
+    });
+  },
+});

package/src/domains/page.ts

@@ -0,0 +1,88 @@
+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 { safeJs } from "../util/js-template";
+
+export const pageInfoTool = defineBrowserTool({
+  name: "browser_page_info",
+  label: "Browser Page Info",
+  description:
+    "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.",
+  ],
+  parameters: Type.Object({}),
+  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 });
+    if ("dialog" in r.data) {
+      const d = r.data.dialog;
+      return ok({
+        text: `⚠️  DIALOG OPEN: ${d.type}\nMessage: ${d.message}${d.defaultPrompt ? `\nDefault: ${d.defaultPrompt}` : ""}\n\nUse browser_handle_dialog to accept or dismiss.`,
+        details: { dialog: d },
+      });
+    }
+    const i = r.data;
+    return ok({
+      text: `URL: ${i.url}\nTitle: ${i.title}\nViewport: ${i.width}x${i.height}\nScroll: (${i.scrollX}, ${i.scrollY})\nPage size: ${i.pageWidth}x${i.pageHeight}`,
+      details: { ...i },
+    });
+  },
+});
+
+const WaitArgs = Type.Object({
+  seconds: Type.Number({ minimum: 0, maximum: 60, description: "Seconds to wait" }),
+});
+
+export const waitTool = defineBrowserTool({
+  name: "browser_wait",
+  label: "Browser Wait",
+  description: "Wait N seconds before continuing.",
+  promptSnippet: "Wait N seconds",
+  promptGuidelines: ["Use sparingly — prefer browser_wait_for_load when waiting for a page load."],
+  parameters: WaitArgs,
+  async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
+    try {
+      await sleep(Math.round(args.seconds * 1000), signal);
+      return ok({ text: `Waited ${args.seconds}s` });
+    } catch (e) {
+      return err({ kind: "internal", message: e instanceof Error ? e.message : String(e) });
+    }
+  },
+});
+
+const WaitForLoadArgs = Type.Object({
+  timeout: Type.Optional(Type.Number({ default: 15, minimum: 1, maximum: 120, description: "Max seconds to wait. Default: 15." })),
+});
+
+export const waitForLoadTool = defineBrowserTool({
+  name: "browser_wait_for_load",
+  label: "Browser Wait For Load",
+  description:
+    "Poll until the current page reports document.readyState === 'complete'. Returns a typed timeout error if the deadline elapses.",
+  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,
+  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`);
+      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 } });
+      }
+      await new Promise((res) => setTimeout(res, 50));
+    }
+    return err({ kind: "timeout", message: `Page did not finish loading in ${args.timeout ?? 15}s` });
+  },
+});

package/src/domains/screenshot.ts

@@ -0,0 +1,114 @@
+import { writeFile, rename } from "node:fs/promises";
+import { Type } from "typebox";
+import type { BrowserClient } from "../client";
+import { type Result, err, 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";
+
+const ScreenshotArgs = Type.Object({
+  fullPage: Type.Optional(Type.Boolean({ default: false, description: "Capture beyond viewport" })),
+  format: Type.Optional(Type.Union([Type.Literal("png"), Type.Literal("jpeg")], { default: "png" })),
+  quality: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, default: 80, description: "JPEG quality 1-100" })),
+  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",
+  description: "Capture the current page as PNG or JPEG. JPEG is 2-5x smaller — prefer it for photo-heavy pages.",
+  promptSnippet: "Capture a screenshot of the current page",
+  promptGuidelines: [
+    "Use BEFORE clicks/scrolls to find coordinates; AFTER to verify the action.",
+    "Pass format='jpeg' with a quality (60-90) for smaller files on photo-heavy pages.",
+    "Set maxDim if the page is huge and you want to fit under LLM image-size limits.",
+  ],
+  parameters: ScreenshotArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const cap = await captureBase(client, args);
+    if (!cap.success) return cap;
+    let note = "";
+    if (args.maxDim !== undefined) {
+      const resized = await resizeIfNeeded(cap.data.path, args.maxDim);
+      note = resized.note;
+    }
+    return ok({
+      text: `Screenshot saved: ${cap.data.path}${note}`,
+      details: { path: cap.data.path, format: cap.data.format, attached: false },
+    });
+  },
+});
+
+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

@@ -0,0 +1,53 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const ScrollArgs = Type.Object({
+  x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
+  y: Type.Optional(Type.Number({ description: "Y coordinate where to scroll. Default: viewport center" })),
+  deltaX: Type.Optional(Type.Number({ default: 0, description: "Horizontal scroll delta (CSS pixels). Positive = right." })),
+  deltaY: Type.Optional(Type.Number({
+    default: -300,
+    description: "Vertical scroll delta (CSS pixels). Positive = up (matches W3C wheel events). Default: -300 (scroll down).",
+  })),
+});
+
+export const scrollTool = defineBrowserTool({
+  name: "browser_scroll",
+  label: "Browser Scroll",
+  description:
+    "Scroll the page at given coordinates. deltaY follows W3C wheel-event convention: positive = scroll up, negative = scroll down. Default scrolls down (deltaY = -300).",
+  promptSnippet: "Scroll the page (deltaY positive=up, negative=down)",
+  promptGuidelines: [
+    "Default behavior scrolls down 300px (deltaY=-300). Pass a positive deltaY to scroll up.",
+    "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
+  ],
+  parameters: ScrollArgs,
+  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 });
+    if ("dialog" in info.data) {
+      return err({
+        kind: "invalid_state",
+        message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,
+      });
+    }
+    const cx = args.x ?? Math.round(info.data.width / 2);
+    const cy = args.y ?? Math.round(info.data.height / 2);
+    const dx = args.deltaX ?? 0;
+    const dy = args.deltaY ?? -300;
+    // Establish compositor mouse position before mouseWheel; without this,
+    // CDP sometimes drops the wheel event with a timeout. Fix preserved
+    // from v0.2.0.
+    const moved = await client.session().call("Input.dispatchMouseEvent", { type: "mouseMoved", x: cx, y: cy });
+    if (!moved.success) return err({ kind: "cdp_error", message: moved.error.message });
+    const wheel = await client.session().call("Input.dispatchMouseEvent", {
+      type: "mouseWheel", x: cx, y: cy, deltaX: dx, deltaY: dy,
+    });
+    if (!wheel.success) return err({ kind: "cdp_error", message: wheel.error.message });
+    return ok({
+      text: `Scrolled at (${cx}, ${cy}) by (${dx}, ${dy})`,
+      details: { x: cx, y: cy, deltaX: dx, deltaY: dy },
+    });
+  },
+});