@orkestrel/browser 0.0.20 → 0.0.22

package/dist/src/core/index.d.cts

@@ -25,8 +25,8 @@ export declare const BASE64_LOOKUP: Readonly<Record<string, number>>;
  * units, one fewer when the last would split a surrogate pair (so a limit of 1 before a pair keeps
  * nothing), followed by `\n[characters 0–END of TOTAL; FOOTER]`. The footer has no default, so
  * every caller states what the cut result's reader does next: the toolset passes
- * `BROWSER_TOOL_VIEW_FOOTER` for a result that carries a view and `BROWSER_TOOL_CUT_FOOTER` for
- * any other.
+ * `BROWSER_TOOL_VIEW_FOOTER` for an action or `dialog` receipt that carries a view and
+ * `BROWSER_TOOL_CUT_FOOTER` for any other result, including `look` and `read` results.
  *
  * @param text - The page-authored or composed string
  * @param limit - The most characters kept before the footer, a positive integer
@@ -68,6 +68,9 @@ export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
  */
 export declare const BROWSER_CODEGEN_SOURCE = "(() => {\n\tconst binding = '__orkestrelBrowserCodegen'\n\twindow[binding + '__state']?.controller.abort()\n\tconst state = { controller: new AbortController(), nodes: [], indices: new WeakMap() }\n\twindow[binding + '__state'] = state\n\tfor (const event of ['click', 'input', 'change', 'keydown', 'focusout', 'submit', 'contextmenu', 'drop']) {\n\t\tdocument.addEventListener(event, (event) => {\n\t\t\tif (!event.isTrusted || typeof window[binding] !== 'function') return\n\t\t\tif (event.type === 'keydown' && event.key !== 'Enter') return\n\t\t\tconst element = event.composedPath()[0]\n\t\t\tif (!(element instanceof Element)) return\n\t\t\tlet index = state.indices.get(element)\n\t\t\tif (index === undefined) {\n\t\t\t\tindex = state.nodes.push(element) - 1\n\t\t\t\tstate.indices.set(element, index)\n\t\t\t}\n\t\t\tconst control = element.tagName === 'SELECT' ? (element.multiple ? 'multiple' : 'select')\n\t\t\t\t: element.tagName === 'OPTION' ? 'option'\n\t\t\t\t: element.tagName === 'INPUT' && element.type === 'password' ? 'password'\n\t\t\t\t: element.tagName === 'TEXTAREA' || element.isContentEditable ||\n\t\t\t\t\t(element.tagName === 'INPUT' && ['text', 'search', 'url', 'tel', 'email', 'number'].includes(element.type)) ? 'text' : 'other'\n\t\t\tconst payload = { event: event.type, index, top: window === window.top && element.ownerDocument === document, control, form: !!element.form }\n\t\t\tif (event.type === 'click') payload.detail = event.detail\n\t\t\tif (event.type === 'keydown') payload.key = 'Enter'\n\t\t\tif (event.type === 'input' && control === 'password') payload.secret = true\n\t\t\tif (event.type === 'input' && control === 'text') payload.value = element.isContentEditable ? element.textContent || '' : element.value\n\t\t\tif (event.type === 'change' && control === 'select') {\n\t\t\t\tpayload.value = element.value\n\t\t\t\tpayload.roundtrip = Array.from(element.options).find(option => option.value === element.value) === element.selectedOptions[0]\n\t\t\t}\n\t\t\tif (element.getRootNode() !== document) {\n\t\t\t\tpayload.event = 'unsupported'\n\t\t\t\tpayload.gap = 'the element is in a shadow root'\n\t\t\t} else if (event.type === 'contextmenu' || event.type === 'drop' || (event.type === 'click' && (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) && !['select', 'multiple', 'option'].includes(control))) {\n\t\t\t\tpayload.event = 'unsupported'\n\t\t\t\tpayload.gap = 'an unsupported gesture'\n\t\t\t}\n\t\t\twindow[binding](JSON.stringify(payload.event === 'unsupported' ? { event: payload.event, index, top: payload.top, control, form: payload.form, gap: payload.gap } : payload))\n\t\t}, { capture: true, signal: state.controller.signal })\n\t}\n})()";
 
+/** Matches protocol errors caused by replacement or closure of an execution context. */
+export declare const BROWSER_CONTEXT_LOSS_PATTERN: RegExp;
+
 /**
  * Sets the default timeout for browser connection, requests, and navigation, `30_000`
  * milliseconds.
@@ -104,7 +107,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
  */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.20";
+    version: "0.0.22";
 }>;
 
 /** Names accessibility roles that receive actionable outline references. */
@@ -249,6 +252,16 @@ export declare const BROWSER_SCHEMES: readonly string[];
 /** Names the attribute that tags temporary screenshot styles and masks. */
 export declare const BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
 
+/**
+ * Matches one word of an outline search and of a row's role and name: a run of at least 3 letters
+ * or digits.
+ *
+ * @remarks
+ * The 3-character floor drops words such as `a`, `to`, and `of`, which would otherwise score a row
+ * whose name shares them with the search.
+ */
+export declare const BROWSER_SEARCH_PATTERN: RegExp;
+
 /**
  * Sets the default maximum node count accepted from a decoded CDP DOM snapshot, `100_000`.
  */
@@ -297,20 +310,21 @@ export declare const BROWSER_TOOL_CHANGED_NOTE = "(The page changed before the v
  *
  * @remarks
  * Every tool description is at most 25 words and says what the tool shows or does, and for
- * `look` and `read` when to call it; every parameter description is at most 100 characters.
+ * `look`, `read`, and `plain` when to call it; every parameter description is at most 100 characters.
  * Every tool declares at least one required parameter, because the streamed tool-call parser of
- * Ollama 0.34.4 rejects a call to a tool that declares no parameter. `look` takes `what` alone
- * and `read` takes `what` and `offset`; neither is scoped to an element, and an element's own
- * reading is `BrowserElementInterface.read`. `look`, `read`, and `journeys` annotate `pure` and
+ * Ollama 0.34.4 rejects a call to a tool that declares no parameter. `look`, `read`, and `plain` take
+ * `search` and `offset`; an element's own reading is `BrowserElementInterface.read`.
+ * `look`, `read`, `plain`, and `journeys` annotate `pure` and
  * `untrusted`, `wait` and `tabs` annotate `pure`, and the rest carry no annotation. `type` takes
  * `secret` beside `ref`, `text`, and `submit`. The journey tools `record`, `save`, `journeys`,
  * `edit`, and `replay` are advertised only by a toolset constructed with `journeys`.
+ * `wait` takes `absent` beside `text` and `timeout`.
  */
 export declare const BROWSER_TOOL_COPY: Readonly<Record<BrowserToolName, ToolDefinition>>;
 
 /**
- * Holds the clause that ends the footer of a cut result that carries no view: a read note, a tab
- * list, a wait, a page tool's output, or an error message.
+ * Holds the clause that ends the footer of a cut result other than an action or `dialog` receipt
+ * that carries a view, including `look` and `read` results.
  */
 export declare const BROWSER_TOOL_CUT_FOOTER = "the rest was cut";
 
@@ -351,7 +365,7 @@ export declare const BROWSER_TOOL_LIMIT = 4000;
 export declare const BROWSER_TOOL_NAME_PATTERN: RegExp;
 
 /**
- * Names every tool the browser toolset reserves: `look`, `read`, `click`, `type`, `press`,
+ * Names every tool the browser toolset reserves: `look`, `read`, `plain`, `click`, `type`, `press`,
  * `navigate`, `wait`, `dialog`, `tabs`, and `switch`.
  */
 export declare const BROWSER_TOOL_NAMES: readonly BrowserToolName[];
@@ -374,10 +388,10 @@ export declare const BROWSER_TOOL_TIMEOUT_LIMIT_MS = 30000;
 export declare const BROWSER_TOOL_TIMEOUT_MS = 5000;
 
 /**
- * Holds the clause that ends the footer of a cut result that carries a view, the result of
- * `look` and of every action, and names `read` as the call that returns the page's text.
+ * Holds the clause that ends the footer of a cut action or `dialog` receipt that carries a view,
+ * and names `look` as the call that finds an element the cut view leaves out.
  */
-export declare const BROWSER_TOOL_VIEW_FOOTER = "the rest was cut; call read for the page's text";
+export declare const BROWSER_TOOL_VIEW_FOOTER = "the rest was cut; call look with words to find";
 
 /**
  * Names the accessibility roles the `type` tool writes to: `textbox`, `searchbox`, and
@@ -392,6 +406,15 @@ export declare const BROWSER_TOOL_VIEW_FOOTER = "the rest was cut; call read for
  */
 export declare const BROWSER_TYPED_ROLES: ReadonlySet<string>;
 
+/**
+ * Names the finished transitions and animations that wake a parked wait.
+ *
+ * @remarks
+ * Chromium 154.0.4258.53 delivers these events in main and isolated worlds after a
+ * visibility or discrete display exit. Opacity alone leaves text in `innerText`.
+ */
+export declare const BROWSER_WAIT_EVENTS: readonly string[];
+
 /**
  * Captures Chromium Accessibility-domain snapshots for one page.
  *
@@ -1109,8 +1132,9 @@ export declare interface BrowserElementInterface {
     /** Moves focus to the element. */
     focus(options?: BrowserCallOptions): Promise<void>;
     /**
-     * Captures the element's markup with its document's URL and title as a reading whose `stale` flag
-     * tracks later navigations of that document.
+     * Captures the element's rendered markup with its document's URL and title as a reading whose
+     * `stale` flag tracks later navigations of that document; {@link BrowserReadingInput} defines
+     * the rendered markup.
      */
     read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
     /**
@@ -1141,7 +1165,7 @@ export declare class BrowserElementManager implements BrowserElementManagerInter
     outline(options?: BrowserOutlineOptions): Promise<BrowserOutline>;
     /** A CSS query searches the page's main-frame document; use the accessibility outline for in-process child documents. */
     find(query: BrowserElementQuery, options?: BrowserCallOptions): Promise<readonly BrowserPageElementInterface[]>;
-    wait(query: BrowserElementQuery, options?: BrowserElementWaitOptions): Promise<readonly BrowserPageElementInterface[]>;
+    wait(query: BrowserElementQuery, options?: BrowserWaitOptions): Promise<readonly BrowserPageElementInterface[]>;
     element(reference: string): BrowserPageElementInterface | undefined;
     elements(): readonly BrowserPageElementInterface[];
     clear(): void;
@@ -1163,13 +1187,16 @@ export declare interface BrowserElementManagerInput {
     readonly world: BrowserElementWorldFunction;
     readonly reference: BrowserReferenceFunction;
     readonly ready: BrowserReadinessFunction;
+    /** Discards readiness after context loss and waits for the destination document. */
+    readonly recover: BrowserReadinessFunction;
 }
 
 /** Captures, queries, and retains references to a view's elements. */
 export declare interface BrowserElementManagerInterface<TElement extends BrowserElementInterface = BrowserElementInterface> {
     /**
      * Captures the view's document as a document-order outline, binding a reference to each
-     * interactive element and bounding the referenced rows by `limit`.
+     * interactive element and bounding the referenced rows by `limit`. The outline also lists the
+     * rows that best match `search` and names the focused referenced row, both past `limit`.
      */
     outline(options?: BrowserOutlineOptions): Promise<BrowserOutline>;
     /**
@@ -1178,10 +1205,10 @@ export declare interface BrowserElementManagerInterface<TElement extends Browser
      */
     find(query: BrowserElementQuery, options?: BrowserCallOptions): Promise<readonly TElement[]>;
     /**
-     * Resolves with the elements matching `query` after a mutation produces a match, or after none
+     * Resolves with the elements matching `query` after a mutation or a finished transition or animation produces a match, or after none
      * matches when `absent` is set; rejects at the deadline or on abort.
      */
-    wait(query: BrowserElementQuery, options?: BrowserElementWaitOptions): Promise<readonly TElement[]>;
+    wait(query: BrowserElementQuery, options?: BrowserWaitOptions): Promise<readonly TElement[]>;
     /**
      * Returns the element a reference names, or `undefined` when the reference is unknown or was
      * dropped.
@@ -1235,11 +1262,6 @@ export declare interface BrowserElementSubject {
     readonly subject: string;
 }
 
-/** Configures an element wait, including whether absence satisfies it. */
-export declare interface BrowserElementWaitOptions extends BrowserCallOptions {
-    readonly absent?: boolean;
-}
-
 /** Resolves the page-owned isolated world for a particular frame and session. */
 export declare type BrowserElementWorldFunction = (frame: string, session: string, options?: BrowserCallOptions) => Promise<number>;
 
@@ -1412,11 +1434,11 @@ export declare interface BrowserFrameInterface {
     /** Resolves the frame document title. */
     title(options?: BrowserCallOptions): Promise<string>;
     /**
-     * Captures the document URL, title, and HTML in one size-guarded evaluation in the frame's
+     * Captures the document URL, title, and rendered HTML in one size-guarded evaluation in the frame's
      * isolated world and returns them as a reading whose `stale` flag tracks later navigations.
      * A frame constructed without an epoch source (a standalone `BrowserFrame` with no `epoch`
      * argument) returns readings whose `stale` stays `false`, because no navigation counter is
-     * available to it.
+     * available to it. {@link BrowserReadingInput} defines the rendered markup.
      */
     read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
     /** Evaluates an expression in the frame execution world under the result-size guard. */
@@ -2389,13 +2411,24 @@ export declare interface BrowserNodeQuery {
  */
 export declare type BrowserOperationOptions = BrowserClickOptions & BrowserDragOptions;
 
-/** Carries a document-order outline and its included and available element counts. */
+/**
+ * Carries a document-order outline and its included and available element counts.
+ *
+ * @remarks
+ * - `matches` — the rendered rows that best match the options' `search`, in document order and
+ *   past `limit` included; empty without a `search` or without a match
+ * - `focus` — the rendered row of the referenced element that has focus, past `limit` included;
+ *   the last such row in document order when several do, and `undefined` when focus is on no
+ *   referenced element
+ */
 export declare interface BrowserOutline {
     readonly url: string;
     readonly title: string;
     readonly text: string;
     readonly count: number;
     readonly total: number;
+    readonly matches: readonly string[];
+    readonly focus: string | undefined;
 }
 
 /** Associates an outline row with its frame, session, and optional actionable reference. */
@@ -2405,10 +2438,20 @@ export declare interface BrowserOutlineNode extends BrowserAXNode {
     readonly tool?: string;
 }
 
-/** Configures an outline's element limit and optional subtree. */
+/**
+ * Configures an outline's element limit, optional subtree, and search.
+ *
+ * @remarks
+ * - `search` — the words that select the outline's `matches`: the text is lowercased and split
+ *   into whole words of at least 3 letters or digits (`BROWSER_SEARCH_PATTERN`), each referenced
+ *   row's role and accessible name are split the same way, and a row scores the number of distinct
+ *   search words equal to one of its words; every referenced row with the highest score above 0
+ *   matches
+ */
 export declare interface BrowserOutlineOptions extends BrowserCallOptions {
     readonly limit?: number;
     readonly within?: string;
+    readonly search?: string;
 }
 
 /**
@@ -2452,7 +2495,7 @@ export declare class BrowserPage extends BrowserFrame implements BrowserPageInte
     get mouse(): BrowserMouseInterface;
     get touch(): BrowserTouchInterface;
     read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
-    wait(text: string, options?: BrowserCallOptions): Promise<void>;
+    wait(text: string, options?: BrowserWaitOptions): Promise<void>;
     get network(): BrowserNetworkManagerInterface;
     get registry(): BrowserRegistryInterface;
     get navigation(): BrowserNavigationManagerInterface;
@@ -2586,8 +2629,8 @@ export declare interface BrowserPageInterface extends BrowserFrameInterface, Bro
     readonly keyboard: BrowserKeyboardInterface;
     readonly mouse: BrowserMouseInterface;
     readonly touch: BrowserTouchInterface;
-    /** Waits for visible text in the main document, rejecting at the deadline or on abort. */
-    wait(text: string, options?: BrowserCallOptions): Promise<void>;
+    /** Waits for text in the main document body’s `innerText`, or its absence with `absent`, rejecting at the deadline or on abort. */
+    wait(text: string, options?: BrowserWaitOptions): Promise<void>;
     readonly emitter: EmitterInterface<BrowserPageEventMap>;
     readonly registry: BrowserRegistryInterface;
     readonly network: BrowserNetworkManagerInterface;
@@ -2892,7 +2935,7 @@ export declare interface BrowserReadinessWait {
  * 	title: 'Example',
  * 	html: '<nav>Menu</nav><main><p>Body</p></main>',
  * })
- * reading.markdown() // { text: 'Body', offset: 0, total: 4 }
+ * reading.markdown({ distill: true }) // { text: 'Body', offset: 0, total: 4 }
  * ```
  */
 export declare class BrowserReading implements BrowserReadingInterface {
@@ -2910,13 +2953,45 @@ export declare class BrowserReading implements BrowserReadingInterface {
  * Describes the captured document a reading is built from.
  *
  * @remarks
- * - `url` — the document URL, which distillation resolves relative links against
+ * - `url` — the document URL, which each projection resolves relative links against
  * - `title` — the document title
  * - `html` — the serialized document HTML
  * - `epoch` — the navigation epoch recorded when the capture was issued. Default: the value
  *   `navigation` returns at construction
  * - `navigation` — reads the source's navigation epoch at the moment of the call; a reading
  *   built without it never reports stale
+ *
+ * A view, frame, or element captures rendered markup by importing its root into an HTML
+ * document without a window, so that nothing in the copy loads or runs, and pruning the copy
+ * against the live document's computed styles. The live document is never written.
+ * - A root or flat-tree ancestor in its own document with `display: none` yields empty HTML.
+ * - Descendants with `display: none` are removed.
+ * - Text under `visibility: hidden` or `collapse`, and invisible elements without children,
+ *   are removed; visible descendants of invisible elements remain.
+ * - A child node of an element with an open shadow root is removed when no slot takes it or
+ *   when its slot sits under an element whose computed `display` is `none`.
+ * - Closed `details` keeps only its first `summary` child. Elements with `content-visibility:
+ *   hidden`, and `canvas`, `video`, and `audio` elements, lose their child nodes.
+ * - SVG `switch` keeps the child element with client rects, or its first child element when
+ *   none has rects, including definitions referenced by `use`. Other branches are removed.
+ * Forms, rendered dialogs, and buttons become neutral carriers. Text fields and textareas
+ * carry live values; empty text fields and textareas carry visible placeholders. Selects carry the selected
+ * label, or displayed option and group labels in a listbox's client area. Named graphics carry
+ * one explicit alternative; printed button text takes precedence over its accessible name.
+ * Links carry resolved live addresses. Region elements remain available to distillation.
+ * Carriers and block `div`, `summary`, and `details` elements receive `br` separators around their
+ * contents. The `html` handle is this normalized capture, not the original DOM serialization.
+ * Direct element reads apply the same ancestor visibility and child-pruning rules.
+ * Password and hidden inputs are removed entirely, including in the data-only fallback for
+ * detached roots and documents without a window. Active floor elements are dropped.
+ * Checkbox, radio, range, and color values aren't printed text. Native control captions,
+ * localized dates, invalid or intermediate number edits, and MathML are omitted rather than
+ * guessed. A file input carries its sole filename; native multiple-file summaries are omitted.
+ * Valid committed numbers carry their live value.
+ * Opacity, clipping outside listboxes, size, position, and `content-visibility: auto` remove
+ * nothing. Shadow-root text, generated content, text transformations, localized number
+ * formatting, textarea clipping, and significant spaces are outside the capture's fidelity.
+ * Caller-supplied HTML is parsed as given; projection options and their safety floors apply.
  */
 export declare interface BrowserReadingInput {
     readonly url: string;
@@ -2933,12 +3008,13 @@ export declare interface BrowserReadingInput {
  * @remarks
  * - `url` — the document URL at capture
  * - `title` — the document title at capture
- * - `html` — the parsed document handle every projection reads
+ * - `html` — the parsed captured and normalized document handle every projection reads;
+ *   caller-supplied HTML remains as supplied
  * - `stale` — true when the source frame has navigated or detached since the capture; false
  *   otherwise
  *
- * Each projection runs over `html.distill({ base: url })` by default and over the whole document
- * with `distill: false`. A reading computes each projection one time and cuts every slice from
+ * Each projection runs over the whole document by default and over
+ * `html.distill({ base: url })` with `distill: true`. A reading computes each projection one time and cuts every slice from
  * it, so successive slices of one reading and mode share one `total`.
  */
 export declare interface BrowserReadingInterface {
@@ -2959,12 +3035,23 @@ export declare interface BrowserReadingInterface {
     text(options?: BrowserReadOptions): BrowserReadResult;
 }
 
+/**
+ * Describes a matching line and its character offset in a reading's projection.
+ *
+ * @remarks
+ * Offsets count UTF-16 code units in the original text, including preceding line breaks.
+ */
+export declare interface BrowserReadMatch {
+    readonly offset: number;
+    readonly text: string;
+}
+
 /**
  * Describes the options for one slice of a reading's Markdown or plain-text projection.
  *
  * @remarks
  * - `distill` — if `true`, projects the distilled document; if `false`, projects the whole
- *   document. Default: `true`
+ *   document. Default: `false`
  * - `offset` — the character index the slice starts at, a non-negative integer. Default: `0`
  * - `limit` — the most characters the slice holds, a positive integer. Default: unbounded
  *
@@ -3129,7 +3216,7 @@ export declare interface BrowserRegistryInterface {
     tool(name: string, frame?: string): BrowserTool | undefined;
     /** Returns every registered tool, including shadowed frame registrations. */
     tools(): readonly BrowserTool[];
-    /** Projects tools as untrusted executable tools, omitting optional-what schemas. */
+    /** Projects tools as untrusted executable tools, omitting optional-purpose schemas. */
     adopt(): Promise<readonly ToolInterface[]>;
     /** Invokes a tool and awaits its terminal event; rejects on abort, invalidation, or timeout. */
     execute(tool: BrowserTool, input: Readonly<Record<string, unknown>>, options?: BrowserCallOptions): Promise<BrowserInvocationResult>;
@@ -3876,11 +3963,11 @@ export declare interface BrowserRunStoreInterface {
     }
 
     /**
-     * Names a tool the browser toolset reserves: the seven generic tools, the staged `dialog`, the
+     * Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the
      * opt-in `tabs` and `switch`, and the journey tools `record`, `save`, `journeys`, `edit`,
      * `replay`, and `forget`, which a toolset constructed with `journeys` reserves.
      */
-    export declare type BrowserToolName = 'look' | 'read' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget';
+    export declare type BrowserToolName = 'look' | 'read' | 'plain' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget';
 
     /** Identifies a removed WebMCP tool by document and name. */
     export declare interface BrowserToolRemoval {
@@ -3893,7 +3980,7 @@ export declare interface BrowserRunStoreInterface {
      * view's own tools beside them.
      *
      * @remarks
-     * Every toolset advertises `look`, `read`, `click`, `type`, and `wait`, which need only the
+     * Every toolset advertises `look`, `read`, `plain`, `click`, `type`, and `wait`, which need only the
      * `BrowserViewInterface` it is constructed over. With `options.page` it also advertises `press`
      * and `navigate`, stages the `dialog` tool while a dialog is open on the current page, follows a
      * popup the current page opens and returns to the opener when the popup closes, and adopts
@@ -3907,11 +3994,18 @@ export declare interface BrowserRunStoreInterface {
      * refuses every tool but `dialog` while a dialog is open, forwards `ToolContext.signal` into every
      * protocol call, refuses a call to a toolset tool that carries a parameter the tool does not
      * advertise, and cuts every returned string and every thrown message at `limit` characters plus
-     * a footer; the footer of a cut result that carries a view names `read` as the next call. `look`
-     * and `read` read the page, never one element. A page tool's error message and JSON output reach
-     * the toolset already cut at `BROWSER_REGISTRY_OUTPUT_LIMIT` (4 096) by the registry, so a
-     * `limit` over that shows at most 4 096 characters of either; a page tool's text output reaches
-     * the boundary whole.
+     * a footer; the footer of a cut action or `dialog` receipt that carries a view names `look` as the next
+     * call. `look`, `read`, and `plain` read the page and return pages of at most `limit`
+     * characters and name the offset the next page starts at. A page ends after the last line break
+     * in its window that lies past the page's start, or at the window's end when no such break fits,
+     * without splitting a surrogate pair. The last page ends at the end of the outline or reading. A `look` whose
+     * `search` matches referenced rows lists those rows first, and its pages reach every referenced row.
+     * A `press` receipt names the referenced element that has focus after the key. A page tool's
+     * error message and JSON output reach the toolset already cut at `BROWSER_REGISTRY_OUTPUT_LIMIT`
+     * (4 096) by the registry, so a `limit` over that shows at most 4 096 characters of either; a page
+     * tool's text output reaches the boundary whole.
+     * `wait` with `absent` set to `true` settles when the text is not on the page, and a miss
+     * returns the `timeout` outcome as an appearance miss does.
      *
      * `click`, `type`, `press`, `navigate`, and `switch` are actions: one runs at a time, in call
      * order, and holds the queue until its receipt. A queued action whose signal aborts leaves
@@ -3942,7 +4036,7 @@ export declare interface BrowserRunStoreInterface {
      * page placement's `type` with `submit` ends its action with `and submitted the form` when a read
      * recorded a submission, or when the navigation the receipt settled names `formSubmissionGet` or
      * `formSubmissionPost` as its reason, whatever the read answered, and with `and pressed Enter`
-     * otherwise. A `read`
+     * otherwise. A `read` or `plain`
      * at an offset at or past its retained reading's end restarts that reading at 0. A receipt that
      * waits for a requested navigation shares one `BROWSER_TOOL_TIMEOUT_MS` deadline between that
      * wait and its view capture, of which `BROWSER_TOOL_CAPTURE_MS` is reserved for the capture. The
@@ -3958,9 +4052,9 @@ export declare interface BrowserRunStoreInterface {
      * A page tool is skipped, with `skip` emitted, when its name is reserved (`unresolved` included), when the manager holds
      * its name under a tool the toolset did not add (checked again immediately before each addition),
      * when its name falls outside `BROWSER_TOOL_NAME_PATTERN`, when its parameters or, for a source
-     * that supplies `tools()`, its selected registration declare `what` optional, or when that
+     * that supplies `tools()`, its selected registration declare `purpose` optional, or when that
      * registration is marked `debugging`. The selected registration is the main frame's, then the
-     * earlier one. A page tool whose parameters require nothing advertises a required `what`, which
+     * earlier one. A page tool whose parameters require nothing advertises a required `purpose`, which
      * is stripped before the tool runs. Every adopted tool is advertised `untrusted`. `destroy()`
      * removes only the tools the manager still holds under the instances the toolset added, never
      * closes a page, and ends only what `options.release` hands over, calling it one time last.
@@ -3971,7 +4065,7 @@ export declare interface BrowserRunStoreInterface {
      *
      * const toolset = new BrowserToolset(page, { page })
      * await toolset.start()
-     * const result = await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'cart' } })
+     * const result = await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'cart' } })
      * await toolset.destroy()
      * ```
      */
@@ -4029,8 +4123,8 @@ export declare interface BrowserRunStoreInterface {
      * - `emitter` — emits `adopt`, `skip`, `select`, `action`, `hold`, and `release`
      * - `tools` — the manager the toolset fills, with execution through the `perform` boundary
      * - `native` — the generic tools alone, which a consumer publishes to a built-in agent: the
-     *   seven for a page-backed toolset, and `look`, `read`, `click`, `type`, and `wait` for a
-     *   view-backed one
+     *   `look`, `read`, `plain`, `click`, `type`, `press`, `navigate`, and `wait` for a page-backed
+     *   toolset, and `look`, `read`, `plain`, `click`, `type`, and `wait` for a view-backed one
      * - `view` — the view the tools act on
      */
     export declare interface BrowserToolsetInterface {
@@ -4142,7 +4236,7 @@ export declare interface BrowserRunStoreInterface {
      * - `reserved` — the name is one of the toolset's own tool names
      * - `held` — the manager holds the name under a tool the toolset did not add
      * - `pattern` — the name falls outside `BROWSER_TOOL_NAME_PATTERN`
-     * - `schema` — the page's input schema declares `what` as optional
+     * - `schema` — the page's input schema declares `purpose` as optional
      * - `debugging` — the page marks the tool for developers
      */
     export declare type BrowserToolsetReason = 'reserved' | 'held' | 'pattern' | 'schema' | 'debugging';
@@ -4359,15 +4453,15 @@ export declare interface BrowserRunStoreInterface {
         /** Resolves the document title. */
         title(options?: BrowserCallOptions): Promise<string>;
         /**
-         * Captures the document URL, title, and markup as a reading whose `stale` flag tracks later
-         * navigations.
+         * Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks
+         * later navigations; {@link BrowserReadingInput} defines the rendered markup.
          */
         read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
         /**
-         * Resolves when `text` is visible in the document; rejects with a `BrowserError` coded
+         * Resolves when the main document body’s `innerText` contains `text`, or lacks it with `absent`; rejects with a `BrowserError` coded
          * `BROWSER_WAIT_TIMEOUT` at the deadline, and with `signal.reason` on abort.
          */
-        wait(text: string, options?: BrowserCallOptions): Promise<void>;
+        wait(text: string, options?: BrowserWaitOptions): Promise<void>;
     }
 
     /** Describes the viewport dimensions for a browser page. */
@@ -4380,6 +4474,18 @@ export declare interface BrowserRunStoreInterface {
         readonly landscape?: boolean;
     }
 
+    /**
+     * Configures a text or element wait, including whether absence satisfies it.
+     *
+     * @remarks
+     * - `absent` — if `true`, the wait resolves when the body's `innerText` lacks the text or no
+     *   element matches; if `false` or omitted, when the text is present or an element matches.
+     *   A condition that already holds resolves at the first check
+     */
+    export declare interface BrowserWaitOptions extends BrowserCallOptions {
+        readonly absent?: boolean;
+    }
+
     /** Names the page load condition for navigation — the CDP load event awaited by `navigate()`. */
     export declare type BrowserWaitUntil = 'commit' | 'load' | 'domcontentloaded' | 'idle';
 
@@ -4762,6 +4868,20 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function collectBrowserJourneyTextBindings(steps: readonly BrowserJourneyStepInput[]): readonly string[];
 
+    /**
+     * Collects distinct lowercase words of at least 3 letters or digits.
+     *
+     * @param text - Text to scan
+     * @returns The searchable whole words
+     *
+     * @example
+     * ```ts
+     * import { collectBrowserWords } from '@orkestrel/browser'
+     * [...collectBrowserWords('The cart, the bag')] // ['the', 'cart', 'bag']
+     * ```
+     */
+    export declare function collectBrowserWords(text: string): ReadonlySet<string>;
+
     /**
      * Compiles the element-side actionability pass used before trusted input.
      *
@@ -4894,22 +5014,26 @@ export declare interface BrowserRunStoreInterface {
     export declare function compileHitFunction(): string;
 
     /**
-     * Compiles a mutation-driven wait with one deadline and explicit disconnect ownership.
+     * Compiles a wait woken by mutations and finished transitions and animations, with one deadline and explicit disconnect ownership.
+     * @remarks
+     * `transitionend` and `animationend` inside a shadow root are not composed in Chromium
+     * 154.0.4258.53, so this document listener does not see them. Mutations inside that root are
+     * not observed either.
      * @param deadline - Maximum time in milliseconds
      * @param key - Isolated-world property owning this observer
-     * @param predicate - Optional expression checked immediately and after each mutation batch
+     * @param predicate - Optional expression checked immediately and on the task after a mutation batch or a `BROWSER_WAIT_EVENTS` event
      * @returns Promise expression resolving true on a match or change, false at the deadline
      */
     export declare function compileQueryWaitExpression(deadline: number, key: string, predicate?: string): string;
 
     /**
-     * Compiles the in-page function that reads the document's URL, title, and serialized HTML.
+     * Compiles the in-page function that reads the document's URL, title, and rendered HTML.
      *
      * @remarks
-     * The declaration takes no arguments and returns `{ url, title, html }` from `location.href`,
-     * `document.title`, and `document.documentElement.outerHTML`, with `html` empty for a document
-     * that has no root element. Call it inside {@link compileGuardedEvaluateExpression} to bound the
-     * result under {@link BROWSER_RESULT_LIMIT}.
+     * The optional root defaults to `document.documentElement`. {@link BrowserReadingInput}
+     * defines its inert capture, lowering, redaction, and limits. A missing root yields empty HTML.
+     * Call it inside {@link compileGuardedEvaluateExpression} to bound the final serialized result
+     * under {@link BROWSER_RESULT_LIMIT}.
      *
      * @returns A function declaration source
      */
@@ -5008,13 +5132,14 @@ export declare interface BrowserRunStoreInterface {
     export declare function compileSubmitReadExpression(token: number): string;
 
     /**
-     * Compiles a visible-text wait coalesced by animation frames.
+     * Compiles a wait for the presence or absence of visible text, coalesced by tasks.
      * @param text - Text to find in the main document body
      * @param deadline - Maximum time in milliseconds
      * @param key - Isolated-world property owning this observer
+     * @param absent - If `true`, resolves when the body's `innerText` lacks `text`; if `false`, when it contains it. Default: `false`
      * @returns Mutation-driven promise expression with one deadline
      */
-    export declare function compileTextWaitExpression(text: string, deadline: number, key: string): string;
+    export declare function compileTextWaitExpression(text: string, deadline: number, key: string, absent?: boolean): string;
 
     /**
      * Composes a frame-local point with its ancestor frame offsets.
@@ -5150,7 +5275,7 @@ export declare interface BrowserRunStoreInterface {
      *
      * const toolset = createBrowserToolset(page, { context })
      * await toolset.start()
-     * const result = await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'cart' } })
+     * const result = await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'cart' } })
      * ```
      *
      * @example Drive a page with a small model
@@ -5164,8 +5289,8 @@ export declare interface BrowserRunStoreInterface {
      * const system =
      * 	'You control a web browser with tools and must call a tool before you answer. ' +
      * 	'The first message shows the page as look returns it; references such as e4 name its elements. ' +
-     * 	'To learn a fact, call read with what set to your question; when its result ends by naming an offset, call read again with that offset. ' +
-     * 	'To search, call type with the search box reference, the words, and submit true. ' +
+     * 	'To learn a fact, call read with search set to words from your question; when its result ends by naming an offset, call read again with that offset. ' +
+     * 	"To use the site's search box, call type with its reference, the words, and submit true. " +
      * 	'To press a button or follow a link, call click with its reference from the latest result. Never invent a reference. ' +
      * 	'If text you expect has not appeared, call wait once. ' +
      * 	'When the task is done, answer in one short sentence.'
@@ -5175,11 +5300,11 @@ export declare interface BrowserRunStoreInterface {
      * const page = await browser.create({ url: 'https://shop.example.test/' })
      * const toolset = createBrowserToolset(page, { tools: createToolManager() })
      * await toolset.start()
-     * toolset.tools.tools().map((tool) => tool.name) // ['look', 'read', 'click', 'type', 'press', 'navigate', 'wait']
+     * toolset.tools.tools().map((tool) => tool.name) // ['look', 'read', 'plain', 'click', 'type', 'press', 'navigate', 'wait']
      * const seeded = await toolset.tools.execute({
      * 	id: 'seed',
      * 	name: 'look',
-     * 	arguments: { what: 'the page' },
+     * 	arguments: { search: '' },
      * })
      * const view = seeded.success ? String(seeded.value) : seeded.error
      * const agent = createAgent(createOllama({ model: 'qwen3.5:2b-q4_K_M' }), {
@@ -5266,10 +5391,10 @@ export declare interface BrowserRunStoreInterface {
     export declare function deriveBrowserJourneyTrigger(step: BrowserJourneyStepInput, inputs?: Readonly<Record<string, string>>): string;
 
     /**
-     * Derives the advertised input schema from an authored one, adding a required `what` parameter when the schema requires nothing.
+     * Derives the advertised input schema from an authored one, adding a required `purpose` parameter when the schema requires nothing.
      * @param schema - Authored input schema, or undefined for a parameterless tool
-     * @returns An advertised schema, or undefined when the authored `what` parameter is optional
-     * @remarks The caller strips only a synthetic `what` parameter before invoking the page tool.
+     * @returns An advertised schema, or undefined when the authored `purpose` parameter is optional
+     * @remarks The caller strips only a synthetic `purpose` parameter before invoking the page tool.
      */
     export declare function deriveBrowserToolSchema(schema: Readonly<Record<string, unknown>> | undefined): Readonly<Record<string, unknown>> | undefined;
 
@@ -6100,15 +6225,111 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function renderBrowserJourneyFault(fault: BrowserStoreFault): string;
 
+    /**
+     * Renders matching rows in at most half the available reply room.
+     *
+     * @remarks
+     * An oversized first row is cut with an ellipsis without splitting a surrogate pair, reserving
+     * room for the first later row that can fit beside it only when the cut keeps the leading token
+     * through its first space. Otherwise it cuts without reserving. Later rows that do not fit are
+     * skipped. An empty collection or a cut with no character before the ellipsis produces no block.
+     *
+     * @param heading - The match count and search, ending with a colon
+     * @param rows - Matching rows in document order
+     * @param room - Characters available in the reply
+     * @returns The bounded block with a trailing blank line, or an empty string
+     *
+     * @example
+     * ```ts
+     * import { renderBrowserMatches } from '@orkestrel/browser'
+     * renderBrowserMatches('Matches:', ['[5] Cart'], 100) // 'Matches:\n[5] Cart\n\n'
+     * ```
+     */
+    export declare function renderBrowserMatches(heading: string, rows: readonly string[], room: number): string;
+
     /**
      * Renders document-order text and referenced elements with a bounded element count.
+     *
+     * @remarks
+     * Each referenced row renders through `renderBrowserOutlineRow`, and the closing
+     * `(COUNT of TOTAL elements)` line counts the rows included and available. `matches` holds the
+     * rows `scanBrowserOutline` returns for `search`, and `focus` the last referenced row whose node
+     * carries a `focused` property of `true`; both reach past `limit`.
+     *
      * @param url - Document address
      * @param title - Document title
      * @param nodes - Ordered accessibility rows
      * @param limit - Maximum referenced rows to include
-     * @returns Outline text and element counts
+     * @param search - The words whose best-matching rows `matches` lists. Default: none, which lists
+     * none
+     * @returns Outline text, element counts, matching rows, and the focused row
+     *
+     * @example
+     * ```ts
+     * import { renderBrowserOutline } from '@orkestrel/browser'
+     *
+     * const node = {
+     * 	parent: undefined,
+     * 	children: [],
+     * 	backend: undefined,
+     * 	frame: undefined,
+     * 	ignored: false,
+     * 	description: undefined,
+     * 	value: undefined,
+     * 	session: 'main',
+     * }
+     * const outline = renderBrowserOutline(
+     * 	'https://shop.example/cart',
+     * 	'Cart',
+     * 	[
+     * 		{ ...node, id: '1', role: 'button', name: 'Close', properties: {}, reference: 'e1' },
+     * 		{ ...node, id: '2', role: 'button', name: 'Archive', properties: { focused: true }, reference: 'e2' },
+     * 	],
+     * 	1,
+     * 	'archive button',
+     * )
+     * outline.text // 'page "Cart" https://shop.example/cart\ne1 button "Close"\n(1 of 2 elements)'
+     * outline.matches // ['e2 button "Archive"']
+     * outline.focus // 'e2 button "Archive"'
+     * ```
+     */
+    export declare function renderBrowserOutline(url: string, title: string, nodes: readonly BrowserOutlineNode[], limit: number, search?: string): BrowserOutline;
+
+    /**
+     * Renders one outline row: the node's reference, its role, its quoted accessible name, and the
+     * states it carries.
+     *
+     * @remarks
+     * After the name the row appends `value="V"` when the node carries a non-empty value,
+     * `pressed=true|false|mixed`, `expanded=true|false`, and `selected=true|false` when present,
+     * `[checked]` when checked, `[disabled]` when disabled, and `[tool=NAME]` for a page tool's form,
+     * in that order. A node without a reference renders without one.
+     *
+     * @param node - The outline node
+     * @returns The rendered row
+     *
+     * @example
+     * ```ts
+     * import { renderBrowserOutlineRow } from '@orkestrel/browser'
+     *
+     * renderBrowserOutlineRow({
+     * 	id: '4',
+     * 	parent: undefined,
+     * 	children: [],
+     * 	backend: undefined,
+     * 	frame: undefined,
+     * 	ignored: false,
+     * 	role: 'checkbox',
+     * 	name: ' Gift  wrap ',
+     * 	description: undefined,
+     * 	value: undefined,
+     * 	properties: { checked: 'true' },
+     * 	session: 'main',
+     * 	reference: 'e4',
+     * }) // 'e4 checkbox "Gift wrap" [checked]'
+     * ```
      */
-    export declare function renderBrowserOutline(url: string, title: string, nodes: readonly BrowserOutlineNode[], limit: number): BrowserOutline;
+    export declare function renderBrowserOutlineRow(node: BrowserOutlineNode): string;
 
     /**
      * Renders a tool receipt: the action and its status on one line, the interrupting dialog, then
@@ -6194,6 +6415,61 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function resolveBrowserJourneyBinding(value: unknown, inputs: Readonly<Record<string, string>>): string;
 
+    /**
+     * Returns the referenced outline nodes whose role and accessible name share the most words with a
+     * search, in document order.
+     *
+     * @remarks
+     * The search and each node's role and name are lowercased and split into whole words by
+     * `BROWSER_SEARCH_PATTERN`, so a word shorter than 3 letters or digits never counts, and words
+     * compare whole, with no substring or prefix match. A node scores the number of distinct search
+     * words equal to one of its words, and every node with the highest score above 0 matches. Only a
+     * node an outline renders as a referenced row takes part: one that is not ignored, carries a
+     * reference, and whose role is not omitted, a heading, or text.
+     *
+     * @param nodes - Ordered accessibility rows
+     * @param search - The words to match
+     * @returns The best-matching nodes in document order; empty when no node shares a word
+     *
+     * @example
+     * ```ts
+     * import { scanBrowserOutline } from '@orkestrel/browser'
+     *
+     * const node = {
+     * 	parent: undefined,
+     * 	children: [],
+     * 	backend: undefined,
+     * 	frame: undefined,
+     * 	ignored: false,
+     * 	description: undefined,
+     * 	value: undefined,
+     * 	properties: {},
+     * 	session: 'main',
+     * }
+     * const nodes = [
+     * 	{ ...node, id: '1', role: 'button', name: 'Close', reference: 'e1' },
+     * 	{ ...node, id: '2', role: 'button', name: 'Archive', reference: 'e2' },
+     * ]
+     * scanBrowserOutline(nodes, 'archive dialog button').map((match) => match.reference) // ['e2']
+     * ```
+     */
+    export declare function scanBrowserOutline(nodes: readonly BrowserOutlineNode[], search: string): readonly BrowserOutlineNode[];
+
+    /**
+     * Matches the lines sharing the most distinct search words, in document order.
+     *
+     * @param text - The complete projection
+     * @param search - Words to match, using the outline's word rule
+     * @returns The best-scoring lines and their original UTF-16 offsets; empty without a shared word
+     *
+     * @example
+     * ```ts
+     * import { scanBrowserText } from '@orkestrel/browser'
+     * scanBrowserText('Cart\nBlue kettle', 'kettle') // [{ offset: 5, text: 'Blue kettle' }]
+     * ```
+     */
+    export declare function scanBrowserText(text: string, search: string): readonly BrowserReadMatch[];
+
     /**
      * Awaits every teardown step in order and returns the first failure.
      *
@@ -6357,8 +6633,8 @@ export declare interface BrowserRunStoreInterface {
      * ```ts
      * import { BROWSER_TOOL_COPY, validateBrowserToolArguments } from '@orkestrel/browser'
      *
-     * validateBrowserToolArguments(BROWSER_TOOL_COPY.look, { what: 'cart', ref: 'e1' })
-     * // throws 'The look tool takes no ref parameter; call look with what.'
+     * validateBrowserToolArguments(BROWSER_TOOL_COPY.look, { search: 'cart', ref: 'e1' })
+     * // throws 'The look tool takes no ref parameter; call look with search and offset.'
      * ```
      */
     export declare function validateBrowserToolArguments(definition: ToolDefinition, args: Readonly<Record<string, unknown>>): void;