@orkestrel/browser 0.0.28 → 0.0.30

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

@@ -1,3 +1,4 @@
+import type { Emitter } from '@orkestrel/emitter';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
@@ -26,6 +27,9 @@ export declare function abbreviateBrowserText(text: string, limit: number): stri
  */
 export declare function belongsBrowserOutline(node: BrowserOutlineNode, ancestor: BrowserOutlineNode, indexed: ReadonlyMap<string, BrowserOutlineNode>): boolean;
 
+/** Fits a character-range footer by narrowing a UTF-16 slice boundary. */
+export declare function boundBrowserTail(text: string, limit: number, footer: string, end: number): string;
+
 /**
  * Bounds a tool string at a character limit, appending a footer that names the cut and the
  * caller's closing clause.
@@ -74,7 +78,7 @@ export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
  * Holds the self-contained document listener installed before a frame resumes.
  * Password input carries a marker; only Enter carries a key. Node indices are local to a document.
  */
-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})()";
+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\tconst known = state.indices.get(element)\n\t\t\tconst index = known === undefined ? state.nodes.push(element) - 1 : known\n\t\t\tif (known === undefined) {\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;
@@ -102,6 +106,12 @@ export declare const BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
  */
 export declare const BROWSER_ELEMENT_REFUSALS: ReadonlyMap<string, BrowserElementRefusal>;
 
+/** Identifies browser errors across installed copies and module formats. */
+export declare const BROWSER_ERROR_BRAND: unique symbol;
+
+/** Holds the declared codes accepted by the browser error guard. */
+export declare const BROWSER_ERROR_CODES: readonly BrowserErrorCode[];
+
 /** Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. */
 export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 
@@ -115,7 +125,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
  */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.28";
+    version: "0.0.30";
 }>;
 
 /** Names accessibility roles that receive actionable outline references. */
@@ -137,7 +147,7 @@ export declare const BROWSER_JOURNEY_EDIT_CHOICE_REFUSAL = "Edit requires journe
 export declare const BROWSER_JOURNEY_EDIT_EMPTY_REFUSAL = "No journey is saved, so there is nothing to edit; call record to start one.";
 
 /** Holds the result the `journeys` tool returns when no journey is saved. */
-export declare const BROWSER_JOURNEY_EMPTY_LISTING = "No journeys are saved; call record to start one.";
+export declare const BROWSER_JOURNEY_EMPTY_LIST = "No journeys are saved; call record to start one.";
 
 /** Holds the refusal `save` returns while the recording has no steps. */
 export declare const BROWSER_JOURNEY_EMPTY_REFUSAL = "Nothing is recorded for {name} yet, and it is still recording. Click and type the flow's steps now, then call save.";
@@ -311,6 +321,9 @@ export declare const BROWSER_SNAPSHOT_NODE_LIMIT = 100000;
 /** Sets the number of animation frames whose element bounds must agree before trusted input. */
 export declare const BROWSER_STABLE_FRAME_COUNT = 2;
 
+/** Identifies journey step errors across installed copies and module formats. */
+export declare const BROWSER_STEP_ERROR_BRAND: unique symbol;
+
 /**
  * Bounds the best-effort `Page.stopLoading` call issued after a failed `navigate()` at `1_000`
  * milliseconds.
@@ -643,6 +656,119 @@ export declare interface BrowserConsoleMessage {
     readonly stack: readonly BrowserStackFrame[];
 }
 
+/**
+ * Represents one captured document, parsed one time and projected to Markdown or plain text in
+ * bounded slices.
+ *
+ * @example
+ * ```ts
+ * import { BrowserContent } from '@orkestrel/browser'
+ *
+ * const reading = new BrowserContent({
+ * 	url: 'https://example.com/',
+ * 	title: 'Example',
+ * 	html: '<nav>Menu</nav><main><p>Body</p></main>',
+ * })
+ * reading.markdown({ distill: true }) // { text: 'Body', offset: 0, total: 4 }
+ * ```
+ */
+export declare class BrowserContent implements BrowserContentInterface {
+    #private;
+    constructor(input: BrowserContentInput);
+    get url(): string;
+    get title(): string;
+    get html(): HTMLInterface;
+    get stale(): boolean;
+    markdown(options?: BrowserReadOptions): BrowserReadResult;
+    text(options?: BrowserReadOptions): BrowserReadResult;
+}
+
+/**
+ * Describes the captured document a reading is built from.
+ *
+ * @remarks
+ * - `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 BrowserContentInput {
+    readonly url: string;
+    readonly title: string;
+    readonly html: string;
+    readonly epoch?: number;
+    readonly navigation?: BrowserEpochFunction;
+}
+
+/**
+ * Represents one captured document, parsed one time and projected to Markdown or plain text in
+ * bounded slices.
+ *
+ * @remarks
+ * - `url` — the document URL at capture
+ * - `title` — the document title at capture
+ * - `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 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 BrowserContentInterface {
+    readonly url: string;
+    readonly title: string;
+    readonly html: HTMLInterface;
+    readonly stale: boolean;
+    /**
+     * Returns a slice of the document rendered as Markdown. A bounded slice ends after the
+     * last line break in its window when one lies past `offset`, and at `limit` characters
+     * otherwise.
+     */
+    markdown(options?: BrowserReadOptions): BrowserReadResult;
+    /**
+     * Returns a slice of the document rendered as structural plain text, cut by the rule
+     * `markdown` applies.
+     */
+    text(options?: BrowserReadOptions): BrowserReadResult;
+}
+
 /**
  * Owns pages and shared state inside one Chromium browser context.
  *
@@ -883,7 +1009,7 @@ export declare type BrowserDestinationRelationship = 'self' | 'parent' | 'top';
 
 /** Groups the diagnostics by capability. */
 export declare interface BrowserDiagnosticsInterface {
-    readonly tracing: BrowserTracingInterface;
+    readonly trace: BrowserTraceInterface;
     readonly coverage: BrowserCoverageInterface;
     readonly performance: BrowserPerformanceInterface;
     readonly profiler: BrowserProfilerInterface;
@@ -1017,10 +1143,10 @@ export declare interface BrowserElementInterface {
     focus(options?: BrowserCallOptions): Promise<void>;
     /**
      * 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
+     * `stale` flag tracks later navigations of that document; {@link BrowserContentInput} defines
      * the rendered markup.
      */
-    read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
+    read(options?: BrowserCallOptions): Promise<BrowserContentInterface>;
     /**
      * Submits the form the element belongs to. The CDP placement focuses the element and presses
      * Enter through a trusted key pair, sending the release even after an abort; the DOM
@@ -1241,10 +1367,10 @@ export declare interface BrowserFrameInterface {
     /**
      * 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.
-     * The owning page supplies the navigation counter. {@link BrowserReadingInput} defines
+     * The owning page supplies the navigation counter. {@link BrowserContentInput} defines
      * the rendered markup.
      */
-    read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
+    read(options?: BrowserCallOptions): Promise<BrowserContentInterface>;
     /** Evaluates an expression in the frame execution world under the result-size guard. */
     evaluate(expression: string, options?: BrowserCallOptions): Promise<unknown>;
     /**
@@ -1552,6 +1678,18 @@ export declare type BrowserJourneyEdit = {
     readonly parameter: BrowserJourneyParameter;
 };
 
+/** Applies one journey edit batch and retains the edit responsible for a refusal. */
+export declare class BrowserJourneyEditor implements BrowserJourneyEditorInterface {
+    #private;
+    readonly journey: BrowserJourney;
+    constructor(journey: BrowserJourney, edits: readonly BrowserJourneyEdit[]);
+}
+
+/** Exposes the result of one atomic journey edit batch. */
+export declare interface BrowserJourneyEditorInterface {
+    readonly journey: BrowserJourney;
+}
+
 /**
  * Describes an edit as the `edit` tool receives it over the wire: an added or updated step can name
  * `ref` instead of a target, converted from the current view before the pure editor runs.
@@ -1593,6 +1731,17 @@ export declare interface BrowserJourneyOptions {
     readonly readonly?: boolean;
 }
 
+/** Iterates a store listing while retaining its offset between page requests. */
+export declare class BrowserJourneyPages implements BrowserJourneyPagesInterface {
+    #private;
+    constructor(store: BrowserJourneyStoreInterface, signal: AbortSignal, empty: boolean);
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<BrowserStorePage<BrowserJourneyRevision>, undefined>>;
+}
+
+/** Iterates pages of journey revisions from a store. */
+export declare type BrowserJourneyPagesInterface = AsyncIterableIterator<BrowserStorePage<BrowserJourneyRevision>>;
+
 /**
  * Declares one parameter a journey takes: its default, or none when it is a secret.
  *
@@ -1773,6 +1922,13 @@ export declare interface BrowserLineSpan {
     readonly text: string;
 }
 
+/** Wraps one semantic line while retaining its continuation and reference boundaries. */
+export declare class BrowserLineWrap extends Iterator<BrowserLine, undefined> {
+    #private;
+    constructor(line: BrowserLine);
+    next(): IteratorResult<BrowserLine, undefined>;
+}
+
 /** Describes the paper margin lengths accepted by Chromium print-to-PDF. */
 export declare interface BrowserMargin {
     readonly top?: number;
@@ -1933,9 +2089,45 @@ export declare interface BrowserNavigationResult {
     readonly same: boolean;
 }
 
+/** Yields the settlement selected after each navigation step. */
+export declare class BrowserNavigationScan extends Iterator<BrowserNavigationSelection, undefined> {
+    #private;
+    constructor(steps: Iterable<BrowserNavigationStep>, frames: ReadonlySet<string>, any: boolean);
+    next(): IteratorResult<BrowserNavigationSelection, undefined>;
+}
+
+/** Carries the settlement selected after a navigation event. */
+export declare interface BrowserNavigationSelection {
+    readonly done: boolean;
+    readonly result: BrowserSettlementResult | undefined;
+}
+
 /** Names how far a settled navigation got: requested, committed, or loaded. */
 export declare type BrowserNavigationStage = 'requested' | 'committed' | 'loaded';
 
+/** Carries one recorded navigation event and its frame identity. */
+export declare type BrowserNavigationStep = {
+    readonly event: 'request';
+    readonly frame: string;
+    readonly url: string;
+    readonly loader: string | undefined;
+    readonly reason: BrowserNavigationReason | undefined;
+} | {
+    readonly event: 'commit';
+    readonly frame: string;
+    readonly url: string;
+    readonly loader: string | undefined;
+    readonly same: boolean;
+} | {
+    readonly event: 'load';
+    readonly frame: string;
+    readonly loader: string | undefined;
+} | {
+    readonly event: 'detach';
+    readonly frame: string;
+    readonly swapped: boolean;
+};
+
 /** Maps the network events a page's network manager emits. */
 export declare type BrowserNetworkEventMap = {
     readonly request: readonly [request: BrowserRequest];
@@ -2033,6 +2225,12 @@ export declare interface BrowserNodeQuery {
  */
 export declare type BrowserOperationOptions = BrowserClickOptions & BrowserDragOptions;
 
+/** Yields positive ordinals for fallback secret parameter names. */
+export declare class BrowserOrdinals extends Iterator<number, undefined> {
+    #private;
+    next(): IteratorYieldResult<number>;
+}
+
 /** Carries document-order lines, element counts, and the focused element's row. */
 export declare interface BrowserOutline {
     readonly url: string;
@@ -2045,6 +2243,13 @@ export declare interface BrowserOutline {
     readonly focus: string | undefined;
 }
 
+/** Traverses outline parents lazily through the supplied index. */
+export declare class BrowserOutlineAncestors extends Iterator<BrowserOutlineNode, undefined> {
+    #private;
+    constructor(node: BrowserOutlineNode | undefined, indexed: ReadonlyMap<string, BrowserOutlineNode>);
+    next(): IteratorResult<BrowserOutlineNode, undefined>;
+}
+
 /** Associates an outline row with its frame, session, and optional actionable reference. */
 export declare interface BrowserOutlineNode extends BrowserAXNode {
     readonly session: string;
@@ -2059,6 +2264,24 @@ export declare interface BrowserOutlineOptions extends BrowserCallOptions {
     readonly secrets?: readonly string[];
 }
 
+/** Projects outline nodes into wrapped lines while retaining listing totals and focus. */
+export declare class BrowserOutlineRows extends Iterator<BrowserLine, undefined> {
+    #private;
+    constructor(input: BrowserOutlineRowsInput);
+    get listed(): number;
+    get found(): number;
+    get focus(): string | undefined;
+    next(): IteratorResult<BrowserLine, undefined>;
+}
+
+/** Supplies the nodes, location, limits, and secrets for an outline projection. */
+export declare interface BrowserOutlineRowsInput {
+    readonly nodes: readonly BrowserOutlineNode[];
+    readonly url: string;
+    readonly limit: number;
+    readonly secrets: readonly string[];
+}
+
 /** Provides trusted page input and capture for a referenced element. */
 export declare interface BrowserPageElementInterface extends BrowserElementInterface {
     /** The id of the frame whose document holds the element. */
@@ -2379,119 +2602,6 @@ export declare interface BrowserQuad {
  */
 export declare type BrowserReadinessFunction = (options?: BrowserCallOptions) => Promise<void>;
 
-/**
- * Represents one captured document, parsed one time and projected to Markdown or plain text in
- * bounded slices.
- *
- * @example
- * ```ts
- * import { BrowserReading } from '@orkestrel/browser'
- *
- * const reading = new BrowserReading({
- * 	url: 'https://example.com/',
- * 	title: 'Example',
- * 	html: '<nav>Menu</nav><main><p>Body</p></main>',
- * })
- * reading.markdown({ distill: true }) // { text: 'Body', offset: 0, total: 4 }
- * ```
- */
-export declare class BrowserReading implements BrowserReadingInterface {
-    #private;
-    constructor(input: BrowserReadingInput);
-    get url(): string;
-    get title(): string;
-    get html(): HTMLInterface;
-    get stale(): boolean;
-    markdown(options?: BrowserReadOptions): BrowserReadResult;
-    text(options?: BrowserReadOptions): BrowserReadResult;
-}
-
-/**
- * Describes the captured document a reading is built from.
- *
- * @remarks
- * - `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;
-    readonly title: string;
-    readonly html: string;
-    readonly epoch?: number;
-    readonly navigation?: BrowserEpochFunction;
-}
-
-/**
- * Represents one captured document, parsed one time and projected to Markdown or plain text in
- * bounded slices.
- *
- * @remarks
- * - `url` — the document URL at capture
- * - `title` — the document title at capture
- * - `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 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 {
-    readonly url: string;
-    readonly title: string;
-    readonly html: HTMLInterface;
-    readonly stale: boolean;
-    /**
-     * Returns a slice of the document rendered as Markdown. A bounded slice ends after the
-     * last line break in its window when one lies past `offset`, and at `limit` characters
-     * otherwise.
-     */
-    markdown(options?: BrowserReadOptions): BrowserReadResult;
-    /**
-     * Returns a slice of the document rendered as structural plain text, cut by the rule
-     * `markdown` applies.
-     */
-    text(options?: BrowserReadOptions): BrowserReadResult;
-}
-
 /**
  * Describes the options for one slice of a reading's Markdown or plain-text projection.
  *
@@ -2698,6 +2808,18 @@ export declare type BrowserReplayEventMap = {
     readonly step: readonly [step: BrowserRunStep];
 };
 
+/** Owns the hold, captures, and completion of one prepared replay call. */
+export declare class BrowserReplayExecution implements BrowserReplayExecutionInterface {
+    #private;
+    constructor(toolset: BrowserToolsetInterface, revision: BrowserJourneyRevision, inputs: Readonly<Record<string, string>>, emitter: Emitter<BrowserReplayEventMap>, options?: BrowserReplayOptions, call?: BrowserCallOptions);
+    get result(): Promise<BrowserRun>;
+}
+
+/** Exposes the result of one prepared replay execution. */
+export declare interface BrowserReplayExecutionInterface {
+    readonly result: Promise<BrowserRun>;
+}
+
 /**
  * Replays one journey over a toolset.
  *
@@ -3203,6 +3325,12 @@ export declare interface BrowserRunStoreInterface {
         readonly limit?: number;
     }
 
+    /** Names the undecoded tables supplied by a CDP snapshot response. */
+    export declare interface BrowserSnapshotTables {
+        readonly strings: readonly unknown[];
+        readonly documents: readonly unknown[];
+    }
+
     /** Represents one browser-side stack frame. */
     export declare interface BrowserStackFrame {
         readonly url: string;
@@ -3336,9 +3464,24 @@ export declare interface BrowserRunStoreInterface {
         readonly current: boolean;
     }
 
+    /** Runs teardown steps in order while retaining the first failure, including undefined. */
+    export declare class BrowserTeardown implements BrowserTeardownInterface {
+        #private;
+        readonly result: Promise<unknown>;
+        constructor(steps: readonly BrowserTeardownFunction[]);
+    }
+
     /** Runs one teardown step to settlement while the first failure is retained. */
     export declare type BrowserTeardownFunction = () => Promise<unknown>;
 
+    /** Exposes completion after every teardown step has run. */
+    export declare interface BrowserTeardownInterface {
+        readonly result: Promise<unknown>;
+    }
+
+    /** Names the UTF-16 boundaries of a reference span. */
+    export declare type BrowserTextRange = readonly [start: number, end: number];
+
     /** Holds network timing values in milliseconds relative to request time. */
     export declare interface BrowserTiming {
         readonly request: number;
@@ -3375,6 +3518,9 @@ export declare interface BrowserRunStoreInterface {
         readonly autosubmit?: boolean;
     }
 
+    /** Executes a tool action and returns its body and footer. */
+    export declare type BrowserToolHandler = (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<readonly [body: string, footer: string]>;
+
     /**
      * Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the
      * opt-in `switch`, and the journey tools `record`, `save`, `journeys`, `edit`,
@@ -3382,6 +3528,12 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare type BrowserToolName = 'read' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget' | 'capture';
 
+    /** Identifies one form-submission observation and the frames it watches. */
+    export declare interface BrowserToolObservation {
+        readonly token: number;
+        readonly frames: Set<BrowserFrameInterface>;
+    }
+
     /** Identifies a removed WebMCP tool by document and name. */
     export declare interface BrowserToolRemoval {
         readonly frame: string;
@@ -3707,6 +3859,12 @@ export declare interface BrowserRunStoreInterface {
         readonly fault?: unknown;
     }
 
+    /** Carries the initial command outcome and the receipt deadline. */
+    export declare interface BrowserToolSettlement {
+        readonly first: boolean;
+        readonly deadline: number;
+    }
+
     /** Maps the signal a tool source emits when its page's tools change. */
     export declare type BrowserToolSourceEventMap = {
         readonly change: readonly [];
@@ -3743,18 +3901,18 @@ export declare interface BrowserRunStoreInterface {
     }
 
     /** Drives the trace capture lifecycle. */
-    export declare interface BrowserTracingInterface {
+    export declare interface BrowserTraceInterface {
         readonly active: boolean;
         /**
          * Begins tracing with the given categories. Throws a `BrowserError` when a trace is
          * already active.
          */
-        start(options?: BrowserTracingOptions): Promise<void>;
+        start(options?: BrowserTraceOptions): Promise<void>;
         /**
          * Ends tracing, drains the IO stream, and writes it through the page writer when a path
          * was set.
          */
-        stop(): Promise<BrowserTracingResult>;
+        stop(): Promise<BrowserTraceResult>;
         /**
          * Stops an active trace, discarding any failure, and does nothing when no trace is
          * running.
@@ -3763,15 +3921,15 @@ export declare interface BrowserRunStoreInterface {
     }
 
     /** Describes the options for a Chromium trace capture. */
-    export declare interface BrowserTracingOptions {
+    export declare interface BrowserTraceOptions {
         readonly path?: string;
         readonly categories?: readonly string[];
         readonly screenshots?: boolean;
-        readonly sampling?: boolean;
+        readonly samples?: boolean;
     }
 
     /** Describes the result of a trace capture. */
-    export declare interface BrowserTracingResult {
+    export declare interface BrowserTraceResult {
         readonly bytes: Uint8Array;
         readonly path: string | undefined;
     }
@@ -3866,9 +4024,9 @@ export declare interface BrowserRunStoreInterface {
         title(options?: BrowserCallOptions): Promise<string>;
         /**
          * Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks
-         * later navigations; {@link BrowserReadingInput} defines the rendered markup.
+         * later navigations; {@link BrowserContentInput} defines the rendered markup.
          */
-        read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
+        read(options?: BrowserCallOptions): Promise<BrowserContentInterface>;
         /**
          * Resolves when the main document body’s `innerText` contains `text`, or lacks it with `absent`; rejects with a `BrowserError` coded
          * `TIMEOUT` at the deadline, and with `signal.reason` on abort.
@@ -3927,6 +4085,14 @@ export declare interface BrowserRunStoreInterface {
         readonly url: string;
     }
 
+    /** Retains an accepted projection row and its footer eligibility. */
+    export declare interface BrowserWindowRow {
+        readonly index: number;
+        readonly row: string;
+        readonly heading: readonly string[];
+        readonly eligible: boolean;
+    }
+
     /** Names a worker target category. */
     export declare type BrowserWorkerCategory = 'worker' | 'service_worker' | 'shared_worker';
 
@@ -4364,7 +4530,7 @@ export declare interface BrowserRunStoreInterface {
      * Compiles the in-page function that reads the document's URL, title, and rendered HTML.
      *
      * @remarks
-     * The optional root defaults to `document.documentElement`. {@link BrowserReadingInput}
+     * The optional root defaults to `document.documentElement`. {@link BrowserContentInput}
      * 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}.
@@ -4529,39 +4695,20 @@ export declare interface BrowserRunStoreInterface {
     export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<Record<string, unknown>>;
 
     /**
-     * Creates a wrapper over an existing browser context on a CDP client.
-     *
-     * @remarks
-     * `id` selects an existing remote context; omission selects the default context.
-     * The caller owns the client. Use `browser.isolate` to create a remote context with
-     * `proxy` or `origins`; this factory refuses those options.
-     *
-     * @param client - The client whose connection carries the context's pages
-     * @param options - Context identity, page defaults, writer, and event hooks
-     * @returns The context wrapper
-     * @throws Thrown with `ARGUMENT` when `proxy` or `origins` is supplied.
-     * @example
-     * const context = createBrowserContext(client, { viewport: { width: 1280, height: 720 } })
-     * const page = await context.create({ url: 'https://example.com/' })
-     * await context.destroy()
-     */
-    export declare function createBrowserContext(client: CDPClientInterface, options?: BrowserContextOptions): BrowserContextInterface;
-
-    /**
-     * Creates a `BrowserReadingInterface` over a captured document, parsing its HTML one time.
+     * Creates a `BrowserContentInterface` over a captured document, parsing its HTML one time.
      *
      * @remarks
      * A reading built with a `navigation` source reports `stale` when that source's epoch differs
      * from the `epoch` recorded at capture; a reading built without one never does.
      *
      * @param input - The document URL, title, and HTML, and the optional navigation epoch
-     * @returns A {@link BrowserReadingInterface}
+     * @returns A {@link BrowserContentInterface}
      *
      * @example
      * ```ts
-     * import { createBrowserReading } from '@orkestrel/browser'
+     * import { createBrowserContent } from '@orkestrel/browser'
      *
-     * const reading = createBrowserReading({
+     * const reading = createBrowserContent({
      * 	url: 'https://example.com/',
      * 	title: 'Example',
      * 	html: '<nav>Menu</nav><main><p>Body</p></main>',
@@ -4569,7 +4716,26 @@ export declare interface BrowserRunStoreInterface {
      * reading.text({ distill: false }) // { text: 'Menu\nBody', offset: 0, total: 9 }
      * ```
      */
-    export declare function createBrowserReading(input: BrowserReadingInput): BrowserReadingInterface;
+    export declare function createBrowserContent(input: BrowserContentInput): BrowserContentInterface;
+
+    /**
+     * Creates a wrapper over an existing browser context on a CDP client.
+     *
+     * @remarks
+     * `id` selects an existing remote context; omission selects the default context.
+     * The caller owns the client. Use `browser.isolate` to create a remote context with
+     * `proxy` or `origins`; this factory refuses those options.
+     *
+     * @param client - The client whose connection carries the context's pages
+     * @param options - Context identity, page defaults, writer, and event hooks
+     * @returns The context wrapper
+     * @throws Thrown with `ARGUMENT` when `proxy` or `origins` is supplied.
+     * @example
+     * const context = createBrowserContext(client, { viewport: { width: 1280, height: 720 } })
+     * const page = await context.create({ url: 'https://example.com/' })
+     * await context.destroy()
+     */
+    export declare function createBrowserContext(client: CDPClientInterface, options?: BrowserContextOptions): BrowserContextInterface;
 
     /**
      * Creates a recorder over toolset actions.
@@ -4809,19 +4975,29 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function findBrowserText(lines: readonly BrowserLine[], text: string): number;
 
+    /** Finds a soft wrap before a reference token without splitting its preceding name. */
+    export declare function findBrowserWrapSpace(text: string, offset: number, whitespace: number, references: readonly BrowserTextRange[]): number;
+
     /**
      * Generates a run id from an ISO timestamp and a cryptographic hexadecimal suffix.
      * @returns An ISO timestamp with hyphens replacing colons, followed by four hexadecimal digits
      */
     export declare function generateBrowserRunId(): string;
 
+    /** Checks whether a step error carries the declared action members. */
+    export declare function isBrowserAction(value: unknown): value is BrowserAction;
+
     /**
-     * Checks whether a value is a browser error.
+     * Checks whether an error carries the browser brand and declared members across package copies.
+     * @remarks Subclasses are accepted without requiring their name; transparent proxies are refused.
      * @param value - Value to check
      * @returns True if the value is a browser error; false otherwise
      */
     export declare function isBrowserError(value: unknown): value is BrowserError;
 
+    /** Checks error metadata, including non-finite numbers that describe refused input values. */
+    export declare function isBrowserErrorContext(value: unknown): value is JSONRecord;
+
     /**
      * Checks whether a native string argument is a literal or a parameter binding.
      * @param value - Candidate argument
@@ -4906,8 +5082,12 @@ export declare interface BrowserRunStoreInterface {
         };
     };
 
+    /** Checks the outer tables of a CDP snapshot without decoding their entries. */
+    export declare function isBrowserSnapshotTables(value: unknown): value is BrowserSnapshotTables;
+
     /**
-     * Checks whether a value is a journey step error.
+     * Checks whether a branded browser error carries the step brand and declared action members.
+     * @remarks Subclasses are accepted without requiring their name; transparent proxies are refused.
      * @param value - Value to check
      * @returns True if the value is a step error; false otherwise
      */
@@ -5691,6 +5871,9 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function renderBrowserSearch(lines: readonly BrowserLine[], from: number, to?: number, search?: string): BrowserSearch;
 
+    /** Chooses a bounded reference-bearing quote for a search outside the requested range. */
+    export declare function renderBrowserSearchQuote(passage: BrowserPassage, found: BrowserSearch, header: readonly string[], limit: number, total: number): string | undefined;
+
     /** Renders an element as searchable text separated from references and syntax.
      * @param node - Captured element
      * @param url - Owning document address
@@ -5792,6 +5975,9 @@ export declare interface BrowserRunStoreInterface {
      */
     export declare function settleBrowserTeardown(...steps: readonly BrowserTeardownFunction[]): Promise<unknown>;
 
+    /** Finds the next non-whitespace offset after a soft line break. */
+    export declare function skipBrowserWhitespace(text: string, offset: number): number;
+
     /**
      * Validates Accessibility-domain snapshot bounds.
      *