pi-browser-harness 0.14.1 → 0.16.0

package/src/domains/keyboard.ts

@@ -7,6 +7,11 @@ import { cdpCall, evalJs } from "./cdp-call";
 import { runOnElement } from "./element-call";
 import { elementFunctionSource } from "./page/inject";
 import { dispatchKeyEvent, type KeyEventSpec } from "./page/keyboard.page";
+import { prepareTyping, readTypedValue, type TypePrep, type TypedValue } from "./page/fill.page";
+import { nativeFill } from "./form";
+import { interactiveDiff } from "./ref-resolve";
+import { isRecord } from "../util/guards";
+import type { BrowserClient } from "../client";
 
 const DISPATCH_KEY_FN = elementFunctionSource(dispatchKeyEvent);
 
@@ -19,53 +24,180 @@ const VIRTUAL_KEY_CODES: Readonly<Record<string, number>> = {
   F7: 118, F8: 119, F9: 120, F10: 121, F11: 122, F12: 123,
 };
 
-const virtualKeyCode = (key: string): number =>
-  VIRTUAL_KEY_CODES[key] ?? (key.length === 1 ? key.charCodeAt(0) : 0);
+// Windows virtual-key codes for letters and digits are the upper-case ASCII code ("a" and "A" are both 65).
+export const virtualKeyCode = (key: string): number => {
+  const named = VIRTUAL_KEY_CODES[key];
+  if (named !== undefined) return named;
+  if (/^[a-z0-9]$/i.test(key)) return key.toUpperCase().charCodeAt(0);
+  return key.length === 1 ? key.charCodeAt(0) : 0;
+};
+
+// KeyboardEvent.code: the physical key. Pages that check `code` (shortcut handlers) need "KeyA", not "a".
+export const physicalCode = (key: string): string => {
+  if (/^[a-z]$/i.test(key)) return `Key${key.toUpperCase()}`;
+  if (/^[0-9]$/.test(key)) return `Digit${key}`;
+  if (key === " ") return "Space";
+  return key;
+};
+
+// Chrome only runs an editing shortcut sent over CDP when the event names the command (macOS does not map Cmd+A to
+// select-all for synthetic events), so Ctrl/Cmd + A/C/X/V/Z/Y carry it explicitly.
+export const editingCommands = (key: string, modifiers: number): ReadonlyArray<string> => {
+  const ctrlOrMeta = (modifiers & (2 | 4)) !== 0;
+  if (!ctrlOrMeta || (modifiers & 1) !== 0) return [];
+  const shift = (modifiers & 8) !== 0;
+  switch (key.toLowerCase()) {
+    case "a": return shift ? [] : ["selectAll"];
+    case "c": return shift ? [] : ["copy"];
+    case "x": return shift ? [] : ["cut"];
+    case "v": return shift ? [] : ["paste"];
+    case "z": return shift ? ["redo"] : ["undo"];
+    case "y": return shift ? [] : ["redo"];
+    default: return [];
+  }
+};
 
 const TypeArgs = Type.Object({
-  text: Type.String({ description: "Text to type" }),
+  ref: Type.Optional(
+    Type.String({ description: "Stable element ref from browser_snapshot (e.g. 'e7'). PREFERRED. The field is focused for you." }),
+  ),
+  selector: Type.Optional(Type.String({ description: "CSS selector of the field (fallback when no ref)." })),
+  text: Type.String({ description: "Text to enter. With `clear` (the default when a field is named) it replaces the field's value; \"\" empties it." }),
+  clear: Type.Optional(
+    Type.Boolean({
+      description:
+        "Replace the field's current value (true) or add to it at the cursor (false). Default: true when ref/selector is given, false when typing into the already-focused element.",
+    }),
+  ),
 });
 
-type FocusProbe = { readonly ok: boolean; readonly tag: string | null };
+type TypeTarget = { readonly ref?: string | undefined; readonly selector?: string | undefined };
 
-const isFocusProbe = (v: unknown): v is FocusProbe =>
-  typeof v === "object" && v !== null
-  && "ok" in v && typeof v.ok === "boolean"
-  && "tag" in v && (typeof v.tag === "string" || v.tag === null);
+const PREP_FN = elementFunctionSource(prepareTyping);
+const READ_FN = elementFunctionSource(readTypedValue);
+
+const isTypePrep = (v: unknown): v is TypePrep => {
+  if (!isRecord(v) || typeof v["ok"] !== "boolean") return false;
+  if (v["ok"]) return typeof v["kind"] === "string" && typeof v["value"] === "string" && typeof v["tag"] === "string";
+  return typeof v["code"] === "string" && typeof v["reason"] === "string";
+};
+
+const isTypedValue = (v: unknown): v is TypedValue =>
+  isRecord(v) && typeof v["value"] === "string" && typeof v["focused"] === "boolean";
+
+const hasTarget = (t: TypeTarget): boolean => t.ref !== undefined || t.selector !== undefined;
+
+const labelOf = (t: TypeTarget): string => (t.ref !== undefined ? `[${t.ref}]` : t.selector ?? "the focused element");
+
+// Runs an element function on the named field, or on document.activeElement when none is named.
+const onField = async (
+  client: BrowserClient,
+  t: TypeTarget,
+  fn: string,
+  args: ReadonlyArray<unknown>,
+): Promise<Result<unknown, ToolErr>> => {
+  if (hasTarget(t)) {
+    const r = await runOnElement(client, { ref: t.ref, selector: t.selector, functionDeclaration: fn, args });
+    if (!r.success) return r;
+    if (!r.data.found) return err({ kind: "invalid_state", message: `No element matched: ${labelOf(t)}` });
+    return ok(r.data.value);
+  }
+  return evalJs(client, "(" + fn + ").apply(document.activeElement, " + safeJs`${args}` + ")");
+};
+
+const prepErr = (t: TypeTarget, prep: Extract<TypePrep, { readonly ok: false }>): ToolErr => {
+  const where = labelOf(t);
+  const hint =
+    prep.code === "select" ? " For a <select> use browser_select_option."
+    : prep.code === "checkable" ? " For a checkbox or radio use browser_set_checked."
+    : prep.code === "not_element" ? " Pass the field's ref, or click it first so it has focus."
+    : "";
+  return { kind: "invalid_state", message: `Cannot type into ${where}: ${prep.reason}.${hint}`, details: { code: prep.code, ...(prep.tag !== undefined ? { tag: prep.tag } : {}) } };
+};
+
+// Backspace with the field's content selected deletes it, the way a user empties a field.
+const pressBackspace = async (client: BrowserClient): Promise<Result<void, ToolErr>> => {
+  const key = { key: "Backspace", code: "Backspace", windowsVirtualKeyCode: 8, nativeVirtualKeyCode: 8 };
+  const down = await cdpCall(client, "Input.dispatchKeyEvent", { type: "keyDown", ...key });
+  if (!down.success) return down;
+  const up = await cdpCall(client, "Input.dispatchKeyEvent", { type: "keyUp", ...key });
+  if (!up.success) return up;
+  return ok(undefined);
+};
 
 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",
+  description:
+    "Enter text into a field the way a user types: focuses it, replaces its value (or appends with clear:false), fires real input events so autocomplete/suggestion lists open and React/Vue controlled inputs update, then reads the value back. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`; with neither, types into the focused element. If typing does not produce the value (date/masked inputs), it falls back to setting the value directly and says so.",
+  promptSnippet: "Type text into a field by ref (preferred), selector, or the focused element",
   promptGuidelines: [
-    "For special keys (Enter, Tab, Escape, arrows), use browser_press_key instead.",
+    "One tool for all text entry: browser_type({ ref, text }) replaces the field's value; pass clear:false to append; text \"\" empties the field.",
+    "Check the value it reports — a page can reformat or reject what was typed.",
+    "Suggestion lists open as you type: after browser_type, run browser_snapshot and browser_click the option's ref.",
+    "For a <select> use browser_select_option; for a checkbox/radio use browser_set_checked.",
+    "For special keys (Enter, Tab, Escape, arrows) use browser_press_key.",
   ],
   parameters: TypeArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const focused = await evalJs(client, safeJs`
-      (() => {
-        const el = document.activeElement;
-        const ok = !!el && el !== document.body &&
-          (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable);
-        return { ok, tag: el ? el.tagName : null };
-      })()
-    `);
-    if (focused.success) {
-      const f: FocusProbe = isFocusProbe(focused.data) ? focused.data : { ok: false, tag: null };
-      if (!f.ok) {
+    const t: TypeTarget = { ref: args.ref, selector: args.selector };
+    const named = hasTarget(t);
+    const clear = args.clear ?? named;
+    const where = labelOf(t);
+
+    const prepRaw = await onField(client, t, PREP_FN, [clear]);
+    if (!prepRaw.success) return prepRaw;
+    if (!isTypePrep(prepRaw.data)) {
+      if (named) return err({ kind: "internal", message: "unexpected page result shape from browser_type", details: { target: where } });
+      return err({
+        kind: "invalid_state",
+        message: "No editable element is focused — typed text would be lost. Pass the field's ref, or click it first.",
+      });
+    }
+    const prep = prepRaw.data;
+    if (!prep.ok) {
+      if (!named && prep.code !== "disabled" && prep.code !== "readonly") {
         return err({
           kind: "invalid_state",
-          message:
-            "No editable element is focused — typed text would be lost. Click the field with browser_click first, or use browser_fill with a selector.",
-          details: { activeElement: f.tag },
+          message: "No editable element is focused — typed text would be lost. Pass the field's ref, or click it first.",
+          details: { activeElement: prep.tag ?? null },
         });
       }
+      return err(prepErr(t, prep));
     }
-    const r = await cdpCall(client, "Input.insertText", { text: args.text });
-    if (!r.success) return r;
-    return ok({ text: `Typed: "${args.text}"` });
+
+    const typed = clear && args.text === "" ? await pressBackspace(client) : await cdpCall(client, "Input.insertText", { text: args.text });
+    if (!typed.success) return typed;
+
+    const readRaw = await onField(client, t, READ_FN, []);
+    const after = readRaw.success && isTypedValue(readRaw.data) ? readRaw.data : undefined;
+    const expected = clear ? args.text : prep.value + args.text;
+    let value = after?.value;
+    let note = "";
+    if (value !== undefined && value !== expected && clear && named && prep.kind !== "contenteditable") {
+      // Typing did not produce the value (a date or masked input, or a handler that swallowed the keys): set it.
+      const filled = await nativeFill(client, t, args.text);
+      if (filled.success && "value" in filled.data) {
+        value = filled.data.value;
+        note = " (typing did not take; value set directly)";
+      }
+    }
+    if (value !== undefined && value !== expected) note += ` ⚠ the field holds ${JSON.stringify(value)}, not what was typed — the page reformatted or rejected it`;
+    if (after !== undefined && !after.focused && note === "") note = " (the field lost focus after typing)";
+
+    const diff = await interactiveDiff(client);
+    const shown = value !== undefined ? ` → value ${JSON.stringify(value)}` : "";
+    return ok({
+      text: `Typed "${args.text}" into ${where}${shown}${note}${diff}`,
+      details: {
+        ...(args.ref !== undefined ? { ref: args.ref } : {}),
+        ...(args.selector !== undefined ? { selector: args.selector } : {}),
+        text: args.text,
+        clear,
+        ...(value !== undefined ? { value } : {}),
+      },
+    });
   },
 });
 
@@ -100,23 +232,26 @@ export const pressKeyTool = defineBrowserTool({
     const code = virtualKeyCode(k);
     const modifiers = args.modifiers ?? 0;
     const isChar = k.length === 1;
+    const physical = physicalCode(k);
+    // A printable character needs a `char` event for the page to receive keypress/textInput and actually insert it; Shift (8) still counts as printable.
+    const hasCommandModifier = (modifiers & (1 | 2 | 4)) !== 0;
+    const commands = editingCommands(k, modifiers);
     const downParams: ParamsOf<"Input.dispatchKeyEvent"> = {
-      type: "keyDown",
+      type: isChar && hasCommandModifier ? "rawKeyDown" : "keyDown",
       key: k,
-      code: k,
+      code: physical,
       modifiers,
       ...(code ? { windowsVirtualKeyCode: code, nativeVirtualKeyCode: code } : {}),
-      ...(isChar ? { text: k, unmodifiedText: k } : {}),
+      ...(isChar && !hasCommandModifier ? { text: k, unmodifiedText: k } : {}),
+      ...(commands.length > 0 ? { commands: [...commands] } : {}),
     };
     const down = await cdpCall(client, "Input.dispatchKeyEvent", downParams);
     if (!down.success) return down;
-    // A printable character needs a `char` event for the page to receive keypress/textInput and actually insert it; Shift (8) still counts as printable.
-    const hasCommandModifier = (modifiers & (1 | 2 | 4)) !== 0;
     if (isChar && !hasCommandModifier) {
       const charEv = await cdpCall(client, "Input.dispatchKeyEvent", { type: "char", text: k, key: k });
       if (!charEv.success) return charEv;
     }
-    const up = await cdpCall(client, "Input.dispatchKeyEvent", { type: "keyUp", key: k, code: k, modifiers });
+    const up = await cdpCall(client, "Input.dispatchKeyEvent", { type: "keyUp", key: k, code: physical, modifiers });
     if (!up.success) return up;
     return ok({ text: `Pressed: ${k}${modifiers ? ` (modifiers=${modifiers})` : ""}` });
   },
@@ -153,7 +288,8 @@ export const dispatchKeyTool = defineBrowserTool({
     const eventType = args.eventType ?? "keydown";
     const target = args.ref ?? args.selector ?? "";
     // Legacy handlers branch on e.keyCode/e.which rather than e.key, so populate both.
-    const code = virtualKeyCode(args.key);
+    // keypress carries the character code ("a" = 97); keydown/keyup carry the key code ("a" = 65).
+    const code = eventType === "keypress" && args.key.length === 1 ? args.key.charCodeAt(0) : virtualKeyCode(args.key);
     if (args.ref !== undefined) {
       // Through runOnElement so the resolved RemoteObject is released after the call.
       const spec: KeyEventSpec = { type: eventType, key: args.key, code };

package/src/domains/page/click.page.ts

@@ -0,0 +1,22 @@
+// Page-side code for browser_click; see fill.page.ts for the rules every `*.page.ts` module follows.
+
+// What sits under the click point, relative to the element the click was aimed at.
+export type HitInfo = {
+  // The point lands on the target, inside it, or on an ancestor that wraps it (a label around an icon).
+  readonly onTarget: boolean;
+  // A short description of the element actually under the point, e.g. `div.modal-overlay "Close"`.
+  readonly hit: string;
+};
+
+// `target` is the element the click aims at (Runtime.callFunctionOn's `this`), `hit` the element hit-testing found.
+export function hitInfo(target: Element | null, hit: Element | null): HitInfo {
+  if (hit?.nodeType !== 1) return { onTarget: false, hit: "nothing" };
+  const onTarget = target !== null && (target === hit || target.contains(hit) || hit.contains(target));
+  const tag = hit.tagName.toLowerCase();
+  const id = hit.id ? "#" + hit.id : "";
+  const cls = typeof hit.className === "string" && hit.className.trim() !== ""
+    ? "." + hit.className.trim().split(/\s+/).slice(0, 2).join(".")
+    : "";
+  const label = (hit.getAttribute("aria-label") ?? hit.textContent).replace(/\s+/g, " ").trim().slice(0, 40);
+  return { onTarget, hit: tag + id + cls + (label !== "" ? ' "' + label + '"' : "") };
+}

package/src/domains/page/fill.page.ts

@@ -10,7 +10,7 @@
 export type PageOption = { readonly value: string; readonly text: string };
 
 export type FillOptions = {
-  // browser_fill refuses a <select> (its documented error points at browser_select_option); browser_fill_form fills it.
+  // The recipe-only browser_fill refuses a <select> (its documented error points at browser_select_option); browser_fill_form fills it.
   readonly rejectSelect: boolean;
   readonly focusFirst: boolean;
 };
@@ -37,6 +37,8 @@ export type FormControl = HTMLElement & {
   value?: string;
   checked?: boolean;
   disabled?: boolean;
+  readOnly?: boolean;
+  select?: () => void;
   options?: HTMLOptionsCollection;
 };
 
@@ -137,3 +139,70 @@ export function fillField(el: FormControl | null, value: unknown, opts: FillOpti
 
   return { ok: false, reason: "element is not a fillable field (tag=" + tag + ")", tag: tagName };
 }
+
+// What browser_type learns about its field before typing: whether it can take text, and its value right now.
+export type TypePrep =
+  | { readonly ok: true; readonly kind: "input" | "textarea" | "contenteditable"; readonly value: string; readonly tag: string }
+  | {
+      readonly ok: false;
+      readonly code: "not_element" | "disabled" | "readonly" | "select" | "checkable" | "not_editable";
+      readonly reason: string;
+      readonly tag?: string;
+    };
+
+// Focuses `el` and, when `clear` is set, selects everything in it, so the text typed next replaces the old value the
+// way select-all + typing does for a user. Refuses fields that cannot take typed text, naming the tool that can.
+export function prepareTyping(el: FormControl | null, clear: boolean): TypePrep {
+  if (el?.nodeType !== 1) return { ok: false, code: "not_element", reason: "no element to type into" };
+  const tagName = el.tagName;
+  const tag = tagName.toLowerCase();
+  const type = (el.type ?? "").toLowerCase();
+  if (tag === "select") return { ok: false, code: "select", reason: "element is a <select>", tag: tagName };
+  if (tag === "input" && (type === "checkbox" || type === "radio")) {
+    return { ok: false, code: "checkable", reason: "element is a " + type, tag: tagName };
+  }
+  const editableTag = (tag === "input" && type !== "button" && type !== "submit" && type !== "file" && type !== "image" && type !== "reset")
+    || tag === "textarea";
+  if (!editableTag && !el.isContentEditable) {
+    return { ok: false, code: "not_editable", reason: "element is not a text field (tag=" + tag + ")", tag: tagName };
+  }
+  if (el.disabled) return { ok: false, code: "disabled", reason: "element is disabled", tag: tagName };
+  if (editableTag && el.readOnly === true) {
+    return { ok: false, code: "readonly", reason: "element is read-only", tag: tagName };
+  }
+  try {
+    el.focus();
+  } catch {
+    /* focus throws on some detached or shadow nodes; the caller checks where the text landed */
+  }
+  if (editableTag) {
+    if (clear) {
+      try {
+        el.select?.();
+      } catch {
+        /* select() is a no-op or throws on a few input types (date, color); the caller verifies and falls back */
+      }
+    }
+    return { ok: true, kind: tag === "textarea" ? "textarea" : "input", value: el.value ?? "", tag: tagName };
+  }
+  if (clear) {
+    const sel = window.getSelection();
+    if (sel) {
+      sel.removeAllRanges();
+      const rng = document.createRange();
+      rng.selectNodeContents(el);
+      sel.addRange(rng);
+    }
+  }
+  return { ok: true, kind: "contenteditable", value: el.textContent, tag: tagName };
+}
+
+// The field's value after typing, and whether it still has focus (a blur handler may have moved it elsewhere).
+export type TypedValue = { readonly value: string; readonly focused: boolean };
+
+export function readTypedValue(el: FormControl | null): TypedValue {
+  if (el?.nodeType !== 1) return { value: "", focused: false };
+  const tag = el.tagName.toLowerCase();
+  const value = tag === "input" || tag === "textarea" ? (el.value ?? "") : el.textContent;
+  return { value, focused: document.activeElement === el };
+}

package/src/domains/page/serp.page.ts

@@ -1,4 +1,5 @@
-// Page-side code for browser_web_search: pulls the organic result anchors off a Google results page. See fill.page.ts for the rules.
+// Page-side code for browser_web_search: pulls the organic result anchors off a search engine's results page, driven
+// by the engine's selectors. See fill.page.ts for the rules.
 
 export type SerpAnchor = {
   readonly href: string;
@@ -12,29 +13,41 @@ export type SerpExtraction = {
   readonly pageText: string;
 };
 
+export type SerpSelectors = {
+  readonly root: string;
+  readonly heading: string;
+  readonly containers: ReadonlyArray<string>;
+  readonly snippet?: string;
+  readonly cite: string;
+};
+
 // Returns the extraction as JSON text (not an object) so the isolated-tab evaluator can keep its string guard.
-export function extractSerp(pageTextLimit: number): string {
-  const main = document.querySelector<HTMLElement>("#search, #rso, #main") ?? document.body;
-  const headings = Array.from(main.querySelectorAll<HTMLElement>("a h3"));
+export function extractSerp(selectors: SerpSelectors, pageTextLimit: number): string {
+  const main = document.querySelector<HTMLElement>(selectors.root) ?? document.body;
+  const headings = Array.from(main.querySelectorAll<HTMLElement>(selectors.heading));
   const seen = new Set<string>();
   const anchors: SerpAnchor[] = [];
-  for (const h3 of headings) {
-    const a = h3.closest<HTMLAnchorElement>("a[href]");
+  for (const heading of headings) {
+    // The heading is the link (DuckDuckGo), sits inside it (Google, Brave) or wraps it (Bing).
+    const a = heading.closest<HTMLAnchorElement>("a[href]") ?? heading.querySelector<HTMLAnchorElement>("a[href]");
     if (!a) continue;
     const href = a.href;
     if (!href || seen.has(href)) continue;
     seen.add(href);
-    const container: HTMLElement | null =
-      a.closest<HTMLElement>("div.g") ??
-      a.closest<HTMLElement>("div[data-hveid]") ??
-      a.parentElement?.parentElement ??
-      a.parentElement;
-    const containerText = container ? container.innerText : "";
-    const heading = h3.innerText || h3.textContent;
-    const snippet = containerText.replace(heading, "").replace(/\s+/g, " ").trim().slice(0, 500);
-    const citeEl = container ? container.querySelector<HTMLElement>("cite") : null;
+    let container: HTMLElement | null = null;
+    for (const selector of selectors.containers) {
+      container = a.closest<HTMLElement>(selector);
+      if (container) break;
+    }
+    container = container ?? a.parentElement?.parentElement ?? a.parentElement;
+    const title = heading.innerText || heading.textContent || "";
+    const snippetEl =
+      selectors.snippet !== undefined && container ? container.querySelector<HTMLElement>(selectors.snippet) : null;
+    const snippetSource = snippetEl ? snippetEl.innerText : container ? container.innerText.replace(title, "") : "";
+    const snippet = snippetSource.replace(/\s+/g, " ").trim().slice(0, 500);
+    const citeEl = container ? container.querySelector<HTMLElement>(selectors.cite) : null;
     const cite = citeEl ? (citeEl.innerText || citeEl.textContent || "").trim() : "";
-    anchors.push({ href, heading, snippet, cite });
+    anchors.push({ href, heading: title, snippet, cite });
   }
   const pageText = document.body.innerText.slice(0, pageTextLimit);
   const extraction: SerpExtraction = { anchors, pageText };

package/src/domains/page.ts

@@ -91,7 +91,7 @@ export const waitForTool = defineBrowserTool({
     "Poll until a condition holds: a selector appears (or disappears with gone:true), or text appears in the page. Returns a typed timeout error if the deadline elapses. Use to wait for SPA content to render before interacting.",
   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.",
+    "Use before browser_type / browser_click on dynamic pages so you act after the element renders.",
   ],
   parameters: WaitForArgs,
   concurrency: "parallel",

package/src/domains/screenshot.ts

@@ -1,4 +1,8 @@
 import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import type { BrowserClient } from "../client";
+import { imageWidth } from "../util/image-size";
+import { evalJs } from "./cdp-call";
 import { Type } from "typebox";
 import { Image, type ImageTheme, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { type Result, ok } from "../util/result";
@@ -20,6 +24,21 @@ const ScreenshotDetailsSchema = Type.Object({
 
 export type ScreenshotDetails = DetailsOf<typeof ScreenshotDetailsSchema>;
 
+// Screenshots come out in device pixels (2x on a Retina display) and maxDim may shrink them again, so a point read
+// off the image is not a browser_click coordinate. Say how to convert, whenever the two differ.
+const scaleNote = async (client: BrowserClient, path: string, fullPage: boolean): Promise<string> => {
+  try {
+    const width = imageWidth(await readFile(path));
+    const css = await evalJs(client, fullPage ? "document.documentElement.scrollWidth" : "window.innerWidth");
+    if (width === undefined || !css.success || typeof css.data !== "number" || css.data <= 0) return "";
+    const ratio = width / css.data;
+    if (Math.abs(ratio - 1) < 0.05) return "";
+    return `\nImage scale: ${ratio.toFixed(2)} image px per CSS px — divide coordinates read off this image by ${ratio.toFixed(2)} before passing them to browser_click (or use refs from browser_snapshot).`;
+  } catch {
+    return "";
+  }
+};
+
 export const screenshotTool = defineBrowserTool({
   name: "browser_screenshot",
   label: "Browser Screenshot",
@@ -40,8 +59,9 @@ export const screenshotTool = defineBrowserTool({
       const resized = await resizeIfNeeded(cap.data.path, args.maxDim);
       note = resized.note;
     }
+    const scale = await scaleNote(client, cap.data.path, args.fullPage ?? false);
     return ok({
-      text: `Screenshot saved: ${cap.data.path}${note}`,
+      text: `Screenshot saved: ${cap.data.path}${note}${scale}`,
       details: { path: cap.data.path, format: cap.data.format, attached: false },
     });
   },

package/src/domains/search/engines/bing.ts

@@ -0,0 +1,47 @@
+import { externalResult, isWebUrl, type SearchEngine, type SerpAnchor, urlFromCite } from "../serp";
+
+const BING_PROPERTY = /(?:^|\.)bing\.(?:com|net)$/;
+const isExternalResult = externalResult((host) => BING_PROPERTY.test(host));
+
+// Bing wraps organic links as bing.com/ck/a?...&u=a1<base64url(target)>. The "a1" prefix tags the encoding.
+export const decodeBingClick = (href: string): string | undefined => {
+  try {
+    const u = new URL(href);
+    if (!BING_PROPERTY.test(u.hostname.toLowerCase()) || u.pathname !== "/ck/a") return undefined;
+    const encoded = u.searchParams.get("u");
+    if (!encoded?.startsWith("a1")) return undefined;
+    const decoded = Buffer.from(encoded.slice(2), "base64url").toString("utf8");
+    return isWebUrl(decoded) ? decoded : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const resultUrl = (anchor: SerpAnchor): string | undefined => {
+  const target = decodeBingClick(anchor.href) ?? anchor.href;
+  if (isExternalResult(target)) return target;
+  if (anchor.cite !== undefined && anchor.cite.trim() !== "") return urlFromCite(anchor.cite, isExternalResult);
+  return undefined;
+};
+
+export const bing: SearchEngine = {
+  id: "bing",
+  name: "Bing",
+  buildUrl: (query, limit) =>
+    `https://www.bing.com/search?q=${encodeURIComponent(query)}&count=${limit}&setlang=en`,
+  selectors: {
+    root: "#b_results, #b_content",
+    heading: "li.b_algo h2",
+    containers: ["li.b_algo"],
+    snippet: ".b_caption p, p[class*='b_lineclamp'], .b_snippet",
+    cite: "cite",
+  },
+  captchaMarkers: [
+    "one last step",
+    "solve the challenge",
+    "verify you are a human",
+    "unusual traffic",
+    "are you a robot",
+  ],
+  resultUrl,
+};

package/src/domains/search/engines/brave.ts

@@ -0,0 +1,23 @@
+import { externalResult, type SearchEngine, type SerpAnchor } from "../serp";
+
+const BRAVE_PROPERTY = /(?:^|\.)brave\.com$/;
+const isExternalResult = externalResult((host) => BRAVE_PROPERTY.test(host));
+
+// Brave links straight to the target; there is no redirect wrapper to undo.
+const resultUrl = (anchor: SerpAnchor): string | undefined =>
+  isExternalResult(anchor.href) ? anchor.href : undefined;
+
+export const brave: SearchEngine = {
+  id: "brave",
+  name: "Brave Search",
+  buildUrl: (query) => `https://search.brave.com/search?q=${encodeURIComponent(query)}&source=web`,
+  selectors: {
+    root: "#results, main",
+    heading: "[data-type='web'] a .title",
+    containers: ["[data-type='web']"],
+    snippet: ".generic-snippet .content, .snippet-description",
+    cite: "cite",
+  },
+  captchaMarkers: ["captcha", "verify you are human", "unusual activity", "not a robot"],
+  resultUrl,
+};

package/src/domains/search/engines/duckduckgo.ts

@@ -0,0 +1,42 @@
+import { externalResult, type SearchEngine, type SerpAnchor, urlFromCite } from "../serp";
+
+const DDG_PROPERTY = /(?:^|\.)duckduckgo\.com$/;
+const isExternalResult = externalResult((host) => DDG_PROPERTY.test(host));
+
+// Results normally link straight to the target; a duckduckgo.com/l/?uddg=<encoded target> wrapper is undone, and ads
+// (routed through /y.js) are dropped by the own-property filter.
+export const unwrapDuckDuckGo = (href: string): string => {
+  try {
+    const u = new URL(href);
+    if (!DDG_PROPERTY.test(u.hostname.toLowerCase()) || u.pathname !== "/l/") return href;
+    return u.searchParams.get("uddg") ?? href;
+  } catch {
+    return href;
+  }
+};
+
+const resultUrl = (anchor: SerpAnchor): string | undefined => {
+  const target = unwrapDuckDuckGo(anchor.href);
+  if (isExternalResult(target)) return target;
+  if (anchor.cite !== undefined && anchor.cite.trim() !== "") return urlFromCite(anchor.cite, isExternalResult);
+  return undefined;
+};
+
+// The main results page. It renders results with JavaScript after the load event, hence readySelector. (The no-JS
+// html.duckduckgo.com endpoint serves a bot challenge even to a real Chrome, so it is not used.)
+export const duckduckgo: SearchEngine = {
+  id: "duckduckgo",
+  name: "DuckDuckGo",
+  buildUrl: (query) => `https://duckduckgo.com/?q=${encodeURIComponent(query)}&kl=us-en&ia=web`,
+  selectors: {
+    // The page has two mainline containers and the first is empty, so the root is the results list itself.
+    root: ".react-results--main, #react-layout",
+    heading: "article[data-testid='result'] a[data-testid='result-title-a']",
+    containers: ["article[data-testid='result']"],
+    snippet: "[data-result='snippet']",
+    cite: "a[data-testid='result-extras-url-link']",
+  },
+  captchaMarkers: ["bots use duckduckgo too", "complete the following challenge"],
+  readySelector: "article[data-testid='result']",
+  resultUrl,
+};