pi-browser-harness 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.14.0 — 2026-11-01
+
+### Added
+
+- **Browser recipes: journal and save.** Every page-changing browser call is journaled per session, and `browser_save_recipe` saves the agent's last browser task as a YAML recipe with `{{params}}`, after the user confirms it.
+- **Browser recipes: replay.** `browser_run_recipe` and `/browser-recipe NAME key=value` replay a saved recipe with no model calls, finding each element by role and name and checking each step's recorded outcome. Downloads and status/alert toasts are now recorded, so a step can expect them.
+- **Browser recipes: finish and repair.** A failed replay hands the agent the failed step and a snapshot; the agent finishes the task, then `browser_save_recipe` with `repair_step` rewrites the recipe from that step, keeping the previous version. An auth wall stops the replay without typing anything.
+- **Browser recipes: project recipes need approval.** A recipe from the project's `.pi/browser-recipes/` asks for confirmation, listing its URLs, uploads and downloads, before its first run and again whenever its file changes.
+- **Browser recipes: read steps return data.** `browser_http_get` and `browser_read_page` of a URL are kept as recipe steps, and a replay returns what they fetched: in `browser_run_recipe`'s result, and as a session message from `/browser-recipe` that starts no model turn. A read made with request headers or a tab id is left out.
+- **Browser recipes: bot checks.** A replay waits up to 30s while Cloudflare's "Just a moment..." check is showing; if it never clears, the replay stops and the agent asks the user to complete it.
+
+### Fixed
+
+- **`browser_execute_js` with a top-level `return` returns its value.** Any body with a top-level `return` runs inside an async function that is awaited, and scripts run in REPL mode, so a later call may declare the same `const` or `let` again.
+- **`browser_close_tab` is fast and confirms the close.** Closing the current tab no longer waits 10s, and a tab Chrome keeps open (one closed while still loading) is closed again, or reported as still open, instead of being reported closed.
+- **Every element gets a ref.** `browser_snapshot`'s `maxNodes` caps only what is shown, so a ref the agent read from a long page still resolves.
+- **`browser_page_info` reports the new page right after a navigation**, not the cached previous one.
+- **`browser_web_search` resolves Google `/goto` result links**, and treats every Google TLD as Google's own, not a result.
+- **The agent calls `browser_setup` before it has connected** instead of falling back to `curl`: the prompt now says the `browser_*` tools are available and the browser is just not connected yet.
+
 ## 0.13.0 — 2026-10-20
 
 ### Fixed

package/README.md

@@ -182,6 +182,8 @@ tabs or navigating the tab to another origin.
 | Tool | Purpose |
 |---|---|
 | `browser_run_script` | Run a temporary script with raw CDP and full Node access. See [Extending](#extending). |
+| `browser_save_recipe` | Save the browser task the agent just finished as a replayable recipe. See [Saved recipes](#saved-recipes). |
+| `browser_run_recipe` | Replay a saved recipe with no model calls, or list recipes when called with no name. |
 | `browser_setup` | Agent-callable setup. Idempotent — how the agent recovers from `not initialized` on its own. |
 
 `browser_snapshot`, `browser_network_requests`, `browser_console`, `browser_execute_js`,
@@ -257,6 +259,49 @@ browser_press_key({ key: "T", modifiers: 10 })   // Ctrl+Shift+T
 
 ---
 
+## Saved recipes
+
+Every page-changing browser call is journaled to `~/.pi/agent/browser-harness/journal/<session>.jsonl`
+(user-only permissions, pruned after 30 days). Password values are never written.
+
+After a multi-step task the agent offers to save it. `browser_save_recipe` turns that task into a YAML
+file under `~/.pi/agent/browser-recipes/<site>/<name>.yaml` (or `.pi/browser-recipes/` in the project
+with `project: true`), replacing the values you name as params with `{{param}}`. You confirm the recipe
+before it is written. Saving over a name bumps `version` and keeps the old file under `.history/`.
+
+Run one yourself with `/browser-recipe vendor-invoices-export month=2026-10` (no model involved), or ask
+the agent ("run the invoices recipe for October"), which calls `browser_run_recipe`. `/browser-recipe`
+with no name lists recipes; names tab-complete. Each step finds its element by role and name, waits up to
+5s for it, and checks that the page changed the way the recorded run did. A status or alert message the
+recorded run saw counts when its first words match, so "Exported 43 rows" satisfies "Exported 42 rows".
+
+When a step fails, the replay stops and hands the agent the step, what it expected and a fresh snapshot.
+The agent finishes your task from that step first, then calls `browser_save_recipe` with `repair_step`,
+which replaces that step onward with what it just did, bumps `version` and keeps the old file. A failed
+`/browser-recipe` goes to the agent the same way. If the page asks you to sign in, the replay stops and the
+agent asks you to sign in; it never types credentials.
+
+A recipe in the project's `.pi/browser-recipes/` comes from whoever wrote the repo, so it needs your
+approval before its first run: you see its file, site, the URLs it opens, the files it uploads and its
+downloads. The approval holds for those exact file bytes (kept in
+`~/.pi/agent/browser-harness/trusted-recipes.json`); if the file changes, you are asked again. Without a UI
+an unapproved project recipe does not run.
+
+Reads are kept too: a `browser_http_get`, or a `browser_read_page` of a URL, becomes a read step, and a
+replay returns what each one fetched (`browser_run_recipe` in its result, `/browser-recipe` as a message in
+the session that starts no model turn). A read made with request headers or a tab id is left out, since
+headers can carry credentials and a tab id means nothing next run. A `browser_execute_js` that changed
+nothing is left out as well, so a replay does not return what it read; read data with `browser_http_get`
+or `browser_read_page` when the recipe should hand it back.
+
+If the site shows Cloudflare's "Just a moment..." check, a replay waits up to 30s for it to clear; if it
+does not, the replay stops and the agent asks you to complete the check in the browser.
+
+A task that typed into a password field, or used a `browser_execute_js` that changed the page or
+`browser_run_script`, cannot be saved.
+
+---
+
 ## Concurrency and isolation
 
 **Parallel reads, serialized writes.** Observation tools run concurrently with each other and with
@@ -398,6 +443,7 @@ listed with each.
 | `/browser-profile` | Pick which browser profile the agent works in. Remembered across sessions. |
 | `/browser-status` | Connection state, selected profile, and current page. |
 | `/browser-reload-daemon` | Force a client restart. Rarely needed — the transport reconnects on its own. |
+| `/browser-recipe` | Replay a saved recipe: `/browser-recipe NAME key=value`. No name lists recipes. |
 
 | Flag / variable | Effect |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -60,7 +60,7 @@
   },
   "scripts": {
     "typecheck": "tsc -b tsconfig.page.json && tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util,types}/**/*-test.ts\"",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util,types,recipes}/**/*-test.ts\"",
     "boundaries": "tsx scripts/check-boundaries.ts",
     "gen:skill": "node --conditions=import --import tsx scripts/gen-skill.ts",
     "check": "npm run typecheck && npm run boundaries && npm run lint && npm test",
@@ -75,7 +75,9 @@
     "sharp": "^0.33.0"
   },
   "dependencies": {
+    "acorn": "^8.19.0",
     "tsx": "^4.22.4",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "yaml": "^2.8.3"
   }
 }

package/skills/pi-browser-harness/SKILL.md

@@ -78,7 +78,9 @@ Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
 | `browser_print_to_pdf` | serialized | Print the current page to PDF |
 | `browser_read_page` | parallel | Read a page's main content as clean text |
 | `browser_reload` | serialized | Reload the page |
+| `browser_run_recipe` | parallel | Replay a saved browser recipe, or list recipes |
 | `browser_run_script` | parallel | Run a temporary script with daemon + Node access (security-bounded) |
+| `browser_save_recipe` | parallel | Save the last browser task as a replayable recipe |
 | `browser_screenshot` | parallel | Capture a screenshot — visual verification only |
 | `browser_scroll` | serialized | Scroll the page (deltaY positive=down, negative=up) |
 | `browser_select_option` | serialized | Select an option in a native <select> by ref (preferred) or selector |
@@ -131,6 +133,36 @@ it by opening tabs elsewhere — a different profile means different accounts.
 
 You're attached to the user's real Chrome — never launch your own. If auth is required, stop and ask the user. If `browser_page_info` returns a dialog, handle it first with `browser_handle_dialog`.
 
+## Saved recipes
+
+`browser_save_recipe` compiles your last browser task into a YAML recipe; `browser_run_recipe` replays one with no model calls. What a recipe keeps:
+
+- **Page actions**: navigate, new_tab, click, fill, select_option, type, press_key, scroll, wait_for, close_tab and the other replayable tools. Each step finds its element by role and name and checks the page changed as it did when recorded.
+- **Reads**: `browser_http_get` and `browser_read_page` with a `url`. A replay returns what each one fetched, so a recipe can hand back data, not only a page. A read with `headers` or a `targetId` is left out.
+- **Left out**: a `browser_execute_js` that changed nothing. A replay does not return what it read, so when the user wants data back, fetch it with `browser_http_get` (an API, a JSON endpoint) or `browser_read_page` before saving.
+- **Refused**: typing into a password field, a `browser_execute_js` that changed the page, `browser_run_script`.
+
+Params replace values you pass: each value must appear, as written, in a step's args or element name (a URL, typed text, a selected label). Its URL forms count too: `{{topic|url}}`, `{{topic|plus}}`, `{{topic|underscore}}`. A value that only appeared in a left-out call cannot be a param.
+
+The file format, for reading a recipe; repair it with `browser_save_recipe` `repair_step`, not by editing it, so the repair is replayed before it is written:
+
+```yaml
+name: npm-downloads
+site: api.npmjs.org
+version: 1
+params:
+  package: { type: string, example: pi-browser-harness }
+steps:
+  - navigate: { url: "https://www.npmjs.com/package/{{package}}" }
+    expect: { url: "https://www.npmjs.com/package/{{package}}" }   # origin and path only
+  - http_get: { url: "https://api.npmjs.org/downloads/range/last-month/{{package}}" }
+  - click: { role: button, name: Export CSV, nth: 0 }              # the element: role+name+nth, or { css: "#export" }
+    expect: { appeared: [{ role: status, name: Exported 42 rows }] }
+recorded: { at: "2026-11-01T15:14:25.918Z", session: 01a197ab }
+```
+
+At a sign-in page or a bot check (Cloudflare's "Just a moment...", waited out for 30s first) the replay stops: ask the user to sign in or complete the check; never do either yourself.
+
 ## Downloads land in the user's context
 
 `browser_download` calls `Browser.setDownloadBehavior` with no `browserContextId`, which Chrome applies to its **default browser context** — the same one the user's own tabs are in. The override redirects the user's manual downloads too, and it lives on the browser connection the daemon keeps open, so it outlives the tab and the pi session. Symptom the user reports: *"I download things in Chrome and nothing appears in Downloads."*

package/src/cdp/commands.ts

@@ -283,6 +283,7 @@ export const COMMANDS = {
         returnByValue: Type.Optional(Type.Boolean()),
         awaitPromise: Type.Optional(Type.Boolean()),
         userGesture: Type.Optional(Type.Boolean()),
+        replMode: Type.Optional(Type.Boolean()),
       },
       { additionalProperties: true },
     ),
@@ -325,6 +326,10 @@ export const COMMANDS = {
     Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
     Type.Object({ object: RemoteObject }),
   ),
+  "DOM.describeNode": cmd(
+    Type.Object({ objectId: Type.String() }),
+    Type.Object({ node: Type.Object({ backendNodeId: Type.Number() }, { additionalProperties: true }) }),
+  ),
   "DOM.setFileInputFiles": cmd(
     Type.Object({
       files: Type.Array(Type.String()),

package/src/cdp/events.ts

@@ -57,6 +57,7 @@ export const EVENTS = {
   ),
   "Page.loadEventFired": ev(Anything),
   "Page.frameNavigated": ev(Anything),
+  "Page.downloadWillBegin": ev(Anything),
 
   "Runtime.consoleAPICalled": ev(
     Type.Object(

package/src/cdp/session.ts

@@ -1,4 +1,5 @@
 import { map, type Result, err, ok } from "../util/result";
+import { isRecord } from "../util/guards";
 import { type CdpError, cdpError } from "./errors";
 import type { CdpEvent, DialogInfo, RefSignature } from "./types";
 import { type OwnershipRegistry, reconcileOwnership } from "./ownership";
@@ -26,12 +27,24 @@ type TabSession = {
   pageInfoDirty: boolean;
   readonly networkBuffer: NetworkBuffer;
   readonly consoleBuffer: ConsoleBuffer;
+  downloads: number;
+  writes: number;
   refMap: ReadonlyMap<string, number>;
   refSig: ReadonlyMap<string, RefSignature>;
 };
 
 type PageTarget = { readonly targetId: string; readonly type: string };
 
+const NAVIGATES: ReadonlySet<string> = new Set(["Page.navigate", "Page.reload", "Page.navigateToHistoryEntry"]);
+
+const SAFE_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"]);
+
+const requestMethod = (params: unknown): string => {
+  const request = isRecord(params) ? params["request"] : undefined;
+  const method = isRecord(request) ? request["method"] : undefined;
+  return typeof method === "string" ? method.toUpperCase() : "";
+};
+
 const ENABLED_DOMAINS: ReadonlyArray<string> = ["Page", "DOM", "Runtime", "Network", "Accessibility", "Log"];
 
 const dialogType = (raw: string): DialogInfo["type"] =>
@@ -53,6 +66,10 @@ export type CdpSession = {
   resolveRef(ref: string): number | undefined;
   refSignatures(): ReadonlyMap<string, RefSignature>;
   refMappings(): ReadonlyMap<string, number>;
+  // Downloads Chrome has started from the current tab; compare before and after an action to see whether it began one.
+  downloadCount(): number;
+  // Requests the current tab has sent with a method that can change server state (anything but GET, HEAD, OPTIONS).
+  writeRequestCount(): number;
   // Sends on the current page session. Params are required only when the method has a required key (see CallArgs).
   call<M extends CdpMethod>(method: M, ...args: CallArgs<M>): Promise<Result<ResultOf<M>, CdpError>>;
   // Sends on an explicit session id (a borrowed or background tab). Params always come first because the session id follows them.
@@ -97,6 +114,8 @@ export const createCdpSession = (
     pageInfoDirty,
     networkBuffer: createNetworkBuffer(),
     consoleBuffer: createConsoleBuffer(),
+    downloads: 0,
+    writes: 0,
     refMap: new Map(),
     refSig: new Map(),
   });
@@ -172,6 +191,11 @@ export const createCdpSession = (
         if (tab) tab.pageInfoDirty = true;
         break;
       }
+      case "Page.downloadWillBegin": {
+        const tab = resolveTab(ev.sessionId);
+        if (tab) tab.downloads += 1;
+        break;
+      }
       case "Target.targetCreated": {
         if (!ownership) break;
         const decoded = decodeEvent(ev.method, ev.params);
@@ -201,7 +225,10 @@ export const createCdpSession = (
       }
       case "Network.requestWillBeSent": {
         const tab = resolveTab(ev.sessionId);
-        if (tab) tab.networkBuffer.ingestRequestWillBeSent(ev.params);
+        if (tab) {
+          tab.networkBuffer.ingestRequestWillBeSent(ev.params);
+          if (!SAFE_METHODS.has(requestMethod(ev.params))) tab.writes += 1;
+        }
         break;
       }
       case "Network.responseReceived": {
@@ -277,6 +304,12 @@ export const createCdpSession = (
       sessionId: sid,
       ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
     });
+    // A navigation command can return before its Page.frameNavigated event arrives, and a page info cached just
+    // before it would then still describe the page it left.
+    if (NAVIGATES.has(method)) {
+      const tab = resolveTab(sid ?? undefined);
+      if (tab) tab.pageInfoDirty = true;
+    }
     if (!raw.success) return raw;
     return decodeResult(method, raw.data);
   };
@@ -439,6 +472,12 @@ export const createCdpSession = (
       const tab = currentTab();
       return tab?.refMap ?? new Map();
     },
+    downloadCount() {
+      return currentTab()?.downloads ?? 0;
+    },
+    writeRequestCount() {
+      return currentTab()?.writes ?? 0;
+    },
     call(method, ...args) {
       const [params, opts] = args;
       return req(method, params, sessionId, opts);

package/src/client.ts

@@ -14,6 +14,21 @@ import { ensureHarnessWindow, openHarnessTab } from "./cdp/target-factory";
 import { seedProfileWindow } from "./profile/bind";
 import type { ProfilePin } from "./profile/store";
 import type { DaemonStatus, DialogInfo, PageInfo, PageInfoResult, TabInfo } from "./cdp/types";
+import { pageExpression } from "./util/js-source";
+
+// REPL mode lets a later call declare the same const or let again, as the console does.
+export const evaluateParams = (
+  expression: string,
+): { readonly expression: string; readonly returnByValue: true; readonly awaitPromise: true; readonly replMode: true } => ({
+  expression: pageExpression(expression),
+  returnByValue: true,
+  awaitPromise: true,
+  replMode: true,
+});
+
+const CLOSE_ATTEMPTS = 2;
+const CLOSE_CONFIRM_MS = 2_500;
+const CLOSE_POLL_MS = 100;
 
 export type BrowserClientOptions = {
   readonly namespace: string;
@@ -25,6 +40,8 @@ export type BrowserClientOptions = {
     readonly harnessWindowId?: number;
   };
   readonly profilePin?: ProfilePin | null;
+  // How long one close may take to show in Chrome's target list before it is sent again; tests shorten it.
+  readonly closeConfirmMs?: number;
   readonly onOwnershipChange?: (snapshot: {
     readonly ownedTargetIds: ReadonlyArray<string>;
     readonly harnessWindowTargetId: string | undefined;
@@ -244,13 +261,8 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
-    // Wrap only when the trimmed source *starts with* `return` — matching the substring anywhere silently turned expressions mentioning it into `undefined`.
-    const trimmed = expression.trim();
-    const isReturnStatement = /^return[\s(]/.test(trimmed);
-    const wrapped = isReturnStatement ? `(function(){${expression}})()` : expression;
-    const r = sessionId
-      ? await session.callOnTarget("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true }, sessionId)
-      : await session.call("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true });
+    const params = evaluateParams(expression);
+    const r = sessionId ? await session.callOnTarget("Runtime.evaluate", params, sessionId) : await session.call("Runtime.evaluate", params);
     if (!r.success) return r;
     if (r.data.exceptionDetails !== undefined) {
       return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(r.data.exceptionDetails)}`, "Runtime.evaluate"));
@@ -332,11 +344,39 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(tabId);
   };
 
+  // True once Chrome no longer lists the target, false if it still does at the deadline, undefined when the list
+  // cannot be read (then the close is taken at its word, as before).
+  const targetGone = async (targetId: string, timeoutMs: number): Promise<boolean | undefined> => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const r = await session.callBrowser("Target.getTargets", {}, { timeoutMs: 2_000 });
+      if (!r.success) return undefined;
+      if (!r.data.targetInfos.some((t) => t.targetId === targetId)) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise((resolve) => setTimeout(resolve, CLOSE_POLL_MS));
+    }
+  };
+
+  // Chrome answers Target.closeTarget with success even when it then keeps the tab: a tab closed while its page is
+  // still loading stays open. So the close is checked against Chrome's own target list and sent once more if the
+  // tab is still there; the tab leaves the owned list only once it is gone, so a tab left open is not lost track of.
   const closeTab = async (targetId: string): Promise<Result<void, CdpError>> => {
-    const r = await session.callBrowser("Target.closeTarget", { targetId });
-    if (!r.success) return r;
-    ownership.remove(targetId);
-    return ok(undefined);
+    for (let attempt = 1; attempt <= CLOSE_ATTEMPTS; attempt++) {
+      const r = await session.callBrowser("Target.closeTarget", { targetId });
+      if (!r.success) return r;
+      const gone = await targetGone(targetId, opts.closeConfirmMs ?? CLOSE_CONFIRM_MS);
+      if (gone !== false) {
+        ownership.remove(targetId);
+        return ok(undefined);
+      }
+    }
+    return err(
+      cdpError(
+        "timeout",
+        `Chrome accepted the close but tab ${targetId} is still open after ${CLOSE_ATTEMPTS} attempts (a page that is still loading can ignore a close); wait for it to load, then close it again`,
+        "Target.closeTarget",
+      ),
+    );
   };
 
   const closeOwnedTabs = async (): Promise<void> => {

package/src/domains/ax-tree.ts

@@ -145,6 +145,25 @@ export const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
     return stripped;
   });
 
+// The first `max` nodes in document order, counted the way buildTree's budget counts them. A kept node's ancestors
+// come before it, so they are always kept too.
+export const firstNodes = (nodes: ReadonlyArray<SlimNode>, max: number): ReadonlySet<SlimNode> => {
+  const kept = new Set<SlimNode>();
+  const walk = (ns: ReadonlyArray<SlimNode>): void => {
+    for (const n of ns) {
+      if (kept.size >= max) return;
+      kept.add(n);
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return kept;
+};
+
+// A copy of the tree holding only the kept nodes; each node keeps its own fields, refs and boxes included.
+export const keepOnly = (nodes: ReadonlyArray<SlimNode>, kept: ReadonlySet<SlimNode>): SlimNode[] =>
+  nodes.filter((n) => kept.has(n)).map((n) => ({ ...n, children: keepOnly(n.children, kept) }));
+
 export const collectInteractiveTargets = (
   nodes: ReadonlyArray<SlimNode>,
 ): Array<{ node: SlimNode; backendId: number }> => {

package/src/domains/js.ts

@@ -38,7 +38,7 @@ const prettyJson = (text: string): string => {
 };
 
 const ExecuteJsArgs = Type.Object({
-  expression: Type.String({ description: "JavaScript expression. `return X` is auto-wrapped in an IIFE." }),
+  expression: Type.String({ description: "A JavaScript expression, or a function body: a body with a top-level `return` (after any statements) runs inside an async function and returns that value." }),
   targetId: Type.Optional(Type.String({ description: "Optional iframe targetId; default = current page." })),
 });
 
@@ -55,7 +55,7 @@ export const executeJsTool = defineBrowserTool({
   name: "browser_execute_js",
   label: "Browser Execute JS",
   description:
-    "Surgical reads from the DOM. The cheapest, most precise way to extract a specific element's text, attribute, value, or geometry. Prefer over browser_screenshot for ANY data extraction or coordinate lookup. `return X` is auto-wrapped in an IIFE. Always use safeJs / JSON.stringify when interpolating untrusted strings.",
+    "Surgical reads from the DOM. The cheapest, most precise way to extract a specific element's text, attribute, value, or geometry. Prefer over browser_screenshot for ANY data extraction or coordinate lookup. A body with a top-level `return` runs inside an async function; `const`/`let` names can be declared again in later calls. Always use safeJs / JSON.stringify when interpolating untrusted strings.",
   promptSnippet: "Execute JS in the page — surgical DOM reads (preferred over screenshot)",
   promptGuidelines: [
     "DEFAULT for extracting a specific value: `document.querySelector('.price').innerText`, `input.value`, `el.getAttribute('aria-label')`, etc.",

package/src/domains/page/recipe.page.ts

@@ -0,0 +1,82 @@
+// Page-side checks for the recipe journal and replay. See fill.page.ts for the rules.
+
+// True for an <input type="password">, the one field whose value the journal must never store.
+export function isPasswordInput(el: Element): boolean {
+  return el instanceof HTMLInputElement && el.type === "password";
+}
+
+// The same check for whatever has focus, which is where browser_type writes.
+export function focusedIsPassword(): boolean {
+  const el = document.activeElement;
+  return el instanceof HTMLInputElement && el.type === "password";
+}
+
+// The interactive element under a point, so an x/y click can be journaled by role and name.
+export function interactiveAt(x: number, y: number): Element | null {
+  const hit = document.elementFromPoint(x, y);
+  if (hit === null) return null;
+  return hit.closest("a,button,input,select,textarea,summary,[role],[contenteditable='true']");
+}
+
+// A visible password field means the page is asking the user to sign in.
+export function hasVisiblePasswordField(): boolean {
+  for (const el of Array.from(document.querySelectorAll("input[type=password]"))) {
+    const r = el.getBoundingClientRect();
+    if (r.width > 0 && r.height > 0) return true;
+  }
+  return false;
+}
+
+// A bot check standing in for the page: Cloudflare's "Just a moment..." interstitial defines _cf_chl_opt, which
+// a page it lets through does not. Only Cloudflare's is known; a page could fake it, which only makes replay wait
+// and then stop, never run a step it should not.
+export function isBotCheck(): boolean {
+  return typeof Reflect.get(window, "_cf_chl_opt") === "object";
+}
+
+// Visible status and alert messages (toasts, live regions), which carry no ref, so a recipe can expect one.
+// A live region without one of the message roles is reported as status (polite) or alert (assertive).
+export function liveMessages(): Array<{ role: string; name: string }> {
+  const roles = ["status", "alert", "alertdialog"];
+  const out: Array<{ role: string; name: string }> = [];
+  const found = document.querySelectorAll("[role=status],[role=alert],[role=alertdialog],[aria-live=polite],[aria-live=assertive]");
+  for (const el of Array.from(found)) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || r.height === 0) continue;
+    const name = el.textContent.replace(/\s+/g, " ").trim().slice(0, 200);
+    if (name === "") continue;
+    const explicit = el.getAttribute("role") ?? "";
+    const role = roles.includes(explicit) ? explicit : el.getAttribute("aria-live") === "assertive" ? "alert" : "status";
+    out.push({ role, name });
+  }
+  return out;
+}
+
+// A hash of everything a script could change on the page: its markup, the live values of its form fields (which
+// the markup does not show), its storage and its URL. Two equal hashes around a script mean it only read the page.
+export function pageFingerprint(): string {
+  const parts: string[] = [location.href, document.documentElement.outerHTML];
+  for (const el of Array.from(document.querySelectorAll("input,textarea,select"))) {
+    if (el instanceof HTMLInputElement) parts.push(`${el.value}\u0001${String(el.checked)}`);
+    else if (el instanceof HTMLTextAreaElement) parts.push(el.value);
+    else if (el instanceof HTMLSelectElement) parts.push(String(el.selectedIndex));
+  }
+  for (const store of [() => localStorage, () => sessionStorage]) {
+    try {
+      const s = store();
+      for (let i = 0; i < s.length; i++) {
+        const key = s.key(i) ?? "";
+        parts.push(`${key}\u0001${s.getItem(key) ?? ""}`);
+      }
+    } catch {
+      parts.push("storage unavailable");
+    }
+  }
+  let hash = 0x811c9dc5;
+  const text = parts.join("\u0000");
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return `${hash.toString(16)}:${text.length}`;
+}

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

@@ -4,6 +4,7 @@ export type SerpAnchor = {
   readonly href: string;
   readonly heading: string;
   readonly snippet: string;
+  readonly cite?: string;
 };
 
 export type SerpExtraction = {
@@ -31,7 +32,9 @@ export function extractSerp(pageTextLimit: number): string {
     const containerText = container ? container.innerText : "";
     const heading = h3.innerText || h3.textContent;
     const snippet = containerText.replace(heading, "").replace(/\s+/g, " ").trim().slice(0, 500);
-    anchors.push({ href, heading, snippet });
+    const citeEl = container ? container.querySelector<HTMLElement>("cite") : null;
+    const cite = citeEl ? (citeEl.innerText || citeEl.textContent || "").trim() : "";
+    anchors.push({ href, heading, snippet, cite });
   }
   const pageText = document.body.innerText.slice(0, pageTextLimit);
   const extraction: SerpExtraction = { anchors, pageText };

package/src/domains/ref-resolve.ts

@@ -57,7 +57,7 @@ export const refreshRefs = async (client: BrowserClient): Promise<Result<RefRefr
 
   const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
   if (!axRes.success) return axRes;
-  const slim = buildTree(axRes.data.nodes, { interestingOnly: true, maxNodes: 1000 });
+  const slim = buildTree(axRes.data.nodes, { interestingOnly: true, maxNodes: Number.POSITIVE_INFINITY });
   const targets = collectInteractiveTargets(slim);
 
   const priorRefs = session.refMappings();