@orkestrel/browser 0.0.6 → 0.0.8

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

@@ -2,15 +2,6 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 
-/**
- * Return the nearest-first ancestor chain for a captured browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Descendant node
- * @returns Nearest-first ancestor list
- */
-export declare function ancestorsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
-
 /**
  * Read one captured node attribute.
  *
@@ -58,7 +49,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 /** Tool identity embedded in HAR 1.2 documents. */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.5";
+    version: "0.0.8";
 }>;
 
 /** CDP Input modifier bit values keyed by canonical key name. */
@@ -741,6 +732,7 @@ export declare class BrowserFrame implements BrowserFrameInterface {
     get touch(): BrowserTouchInterface;
     title(): Promise<string>;
     content(): Promise<BrowserContentResult>;
+    article(): Promise<string>;
     click(selector: string, options?: BrowserActionOptions): Promise<void>;
     fill(selector: string, value: string, options?: BrowserActionOptions): Promise<void>;
     select(selector: string, values: readonly string[], options?: BrowserActionOptions): Promise<void>;
@@ -783,6 +775,7 @@ export declare interface BrowserFrameInfo {
  * - `url` — current frame URL
  * - `title` — resolve the document title
  * - `content` — extract page URL, title, HTML, and visible text
+ * - `article` — the page's reader-facing prose, boilerplate and hidden regions pruned (not `content()`'s whole-body text)
  * - `click` — click an element matching the selector
  * - `fill` — type text into an input element
  * - `select` — choose option(s) in a `<select>` element
@@ -801,6 +794,7 @@ export declare interface BrowserFrameInterface {
     readonly touch: BrowserTouchInterface;
     title(): Promise<string>;
     content(): Promise<BrowserContentResult>;
+    article(): Promise<string>;
     click(selector: string, options?: BrowserActionOptions): Promise<void>;
     fill(selector: string, value: string, options?: BrowserActionOptions): Promise<void>;
     select(selector: string, values: readonly string[], options?: BrowserActionOptions): Promise<void>;
@@ -1305,7 +1299,7 @@ export declare interface BrowserNode {
     readonly layout: BrowserLayout | undefined;
 }
 
-/** Predicate used by browser snapshot traversal helpers. */
+/** Predicate form accepted by {@link BrowserSnapshotInterface} find, filter, and closest methods. */
 export declare type BrowserNodePredicate = (node: BrowserNode) => boolean;
 
 /**
@@ -1350,7 +1344,7 @@ export declare class BrowserPage extends BrowserFrame implements BrowserPageInte
     save(path: string, bytes: Uint8Array): Promise<void>;
     frame(name: string): Promise<BrowserFrameInterface | undefined>;
     frames(): Promise<readonly BrowserFrameInterface[]>;
-    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshot>;
+    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshotInterface>;
     codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -1420,7 +1414,7 @@ export declare interface BrowserPageInterface extends BrowserFrameInterface {
     pdf(options?: BrowserPDFOptions): Promise<BrowserPDFResult>;
     frame(name: string): Promise<BrowserFrameInterface | undefined>;
     frames(): Promise<readonly BrowserFrameInterface[]>;
-    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshot>;
+    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshotInterface>;
     codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
@@ -1812,14 +1806,56 @@ export declare interface BrowserSelectorManagerInterface {
 /** Resolve the current CDP session for a frame id. */
 export declare type BrowserSessionFunction = (frame: string) => Promise<string>;
 
-/** A flattened, serializable snapshot of every document attached to a page. */
-export declare interface BrowserSnapshot {
+/** Structural sibling relationship relative to a browser node. */
+export declare type BrowserSiblingRelation = 'preceding' | 'following';
+
+/** A navigable, serializable browser DOM snapshot. */
+export declare class BrowserSnapshot implements BrowserSnapshotInterface {
+    #private;
+    readonly documents: readonly BrowserDocument[];
+    readonly styles: readonly string[];
+    constructor(input: BrowserSnapshotInput);
+    walk(options?: BrowserWalkOptions): Generator<BrowserNode, void, unknown>;
+    descendants(node: BrowserNode): Generator<BrowserNode, void, unknown>;
+    document(node: BrowserNode): BrowserDocument | undefined;
+    children(node: BrowserNode): readonly BrowserNode[];
+    parent(node: BrowserNode): BrowserNode | undefined;
+    siblings(node: BrowserNode, relation?: BrowserSiblingRelation): readonly BrowserNode[];
+    ancestors(node: BrowserNode): readonly BrowserNode[];
+    common(first: BrowserNode, second: BrowserNode): BrowserNode | undefined;
+    distance(first: BrowserNode, second: BrowserNode): number | undefined;
+    find(query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    filter(query: BrowserNodeQuery | BrowserNodePredicate, limit?: number): readonly BrowserNode[];
+    closest(node: BrowserNode, query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    path(node: BrowserNode): string;
+}
+
+/** Serializable input for a navigable browser snapshot. */
+export declare interface BrowserSnapshotInput {
     readonly documents: readonly BrowserDocument[];
     readonly styles: readonly string[];
 }
 
+/** A navigable, serializable snapshot of every document attached to a page. */
+export declare interface BrowserSnapshotInterface extends BrowserSnapshotInput {
+    walk(options?: BrowserWalkOptions): Generator<BrowserNode, void, unknown>;
+    descendants(node: BrowserNode): Generator<BrowserNode, void, unknown>;
+    document(node: BrowserNode): BrowserDocument | undefined;
+    children(node: BrowserNode): readonly BrowserNode[];
+    parent(node: BrowserNode): BrowserNode | undefined;
+    siblings(node: BrowserNode, relation?: BrowserSiblingRelation): readonly BrowserNode[];
+    ancestors(node: BrowserNode): readonly BrowserNode[];
+    common(first: BrowserNode, second: BrowserNode): BrowserNode | undefined;
+    distance(first: BrowserNode, second: BrowserNode): number | undefined;
+    find(query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    filter(query: BrowserNodeQuery | BrowserNodePredicate, limit?: number): readonly BrowserNode[];
+    closest(node: BrowserNode, query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    path(node: BrowserNode): string;
+}
+
 /**
- * Options for capturing a browser DOM snapshot.
+ * Options configuring capture through {@link BrowserPageInterface} `snapshot()`.
+ * The snapshot entity's creation input is {@link BrowserSnapshotInput}.
  *
  * @remarks
  * - `styles` — computed CSS property names to capture
@@ -2011,6 +2047,21 @@ export declare type BrowserWaitState = 'attached' | 'detached' | 'visible' | 'hi
 /** Page load condition for navigation — the CDP load event awaited by `navigate()`. */
 export declare type BrowserWaitUntil = 'commit' | 'load' | 'domcontentloaded';
 
+/**
+ * Options for walking a browser snapshot.
+ *
+ * @remarks
+ * - `root` — optional subtree root, included in the walk
+ * - `order` — structural traversal order, defaulting to depth-first
+ */
+export declare interface BrowserWalkOptions {
+    readonly root?: BrowserNode;
+    readonly order?: BrowserWalkOrder;
+}
+
+/** Structural ordering for a browser snapshot walk. */
+export declare type BrowserWalkOrder = 'depth' | 'breadth';
+
 /**
  * Observable WebSocket connection reconstructed from Network-domain events.
  */
@@ -2239,39 +2290,6 @@ export declare interface CDPTransportInterface {
     close(): Promise<void>;
 }
 
-/**
- * Return direct children of a captured browser node.
- *
- * @remarks
- * Includes the root nodes of an iframe's linked content document. Shadow DOM
- * and template content already carry flattened parent indexes from CDP.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Parent node
- * @returns Direct children in snapshot order
- */
-export declare function childrenOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
-
-/**
- * Find the nearest matching node from the candidate through its ancestors.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Starting node, included in the search
- * @param predicate - Node predicate
- * @returns Closest matching node, or undefined
- */
-export declare function closestBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode, predicate: BrowserNodePredicate): BrowserNode | undefined;
-
-/**
- * Resolve the nearest common ancestor of two captured browser nodes.
- *
- * @param snapshot - Captured browser snapshot
- * @param first - First node
- * @param second - Second node
- * @returns Common ancestor, or undefined
- */
-export declare function commonAncestorOfBrowserNodes(snapshot: BrowserSnapshot, first: BrowserNode, second: BrowserNode): BrowserNode | undefined;
-
 /**
  * Compile the element-side actionability pass used before trusted input.
  *
@@ -2491,16 +2509,6 @@ export declare function computeBrowserButtons(buttons: readonly BrowserMouseButt
  */
 export declare function computeBrowserModifiers(modifiers: readonly string[]): number;
 
-/**
- * Compute the edge count between two captured browser nodes.
- *
- * @param snapshot - Captured browser snapshot
- * @param first - First node
- * @param second - Second node
- * @returns Tree distance, or undefined when no common ancestor exists
- */
-export declare function computeBrowserNodeDistance(snapshot: BrowserSnapshot, first: BrowserNode, second: BrowserNode): number | undefined;
-
 /**
  * Concatenate byte chunks without Node-specific buffers.
  *
@@ -2528,6 +2536,22 @@ export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<R
  */
 export declare function createBrowserHAREntry(pending: BrowserHARPending, duration: number, body?: Uint8Array, error?: string): BrowserHAREntry;
 
+/**
+ * Create a navigable browser snapshot from decoded serializable data.
+ *
+ * @param input - Captured documents and computed-style names
+ * @returns A {@link BrowserSnapshotInterface}
+ *
+ * @example
+ * ```ts
+ * import { createBrowserSnapshot, decodeBrowserSnapshot } from '@src/core'
+ *
+ * const snapshot = createBrowserSnapshot(decodeBrowserSnapshot(captured, ['display']))
+ * snapshot.find({ name: 'main' })
+ * ```
+ */
+export declare function createBrowserSnapshot(input: BrowserSnapshotInput): BrowserSnapshotInterface;
+
 /**
  * Create a CDP client bound to the given transport.
  *
@@ -2579,7 +2603,7 @@ export declare function decodeBrowserAttributes(value: unknown, strings: readonl
  * @param limit - Maximum accepted node count
  * @returns A typed serializable browser snapshot
  */
-export declare function decodeBrowserSnapshot(value: unknown, styles?: readonly string[], limit?: number): BrowserSnapshot;
+export declare function decodeBrowserSnapshot(value: unknown, styles?: readonly string[], limit?: number): BrowserSnapshotInput;
 
 /**
  * Decode CDP snapshot sparse boolean data.
@@ -2606,24 +2630,6 @@ export declare function decodeRareIntegerData(value: unknown): ReadonlyMap<numbe
  */
 export declare function decodeRareStringData(value: unknown, strings: readonly string[]): ReadonlyMap<number, string>;
 
-/**
- * Lazily walk descendants of one captured node, excluding the node itself.
- *
- * @param snapshot - Captured browser snapshot
- * @param root - Root whose descendants are required
- * @returns A lazy descendant generator
- */
-export declare function descendantsOfBrowserNode(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
-
-/**
- * Resolve the document containing a browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Node whose document is required
- * @returns The containing document, or undefined
- */
-export declare function documentOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): BrowserDocument | undefined;
-
 /**
  * Encode raw bytes as base64 without relying on Node or DOM globals.
  *
@@ -2632,44 +2638,6 @@ export declare function documentOfBrowserNode(snapshot: BrowserSnapshot, node: B
  */
 export declare function encodeBase64(bytes: Uint8Array): string;
 
-/**
- * Find the first matching descendant beneath one captured node.
- *
- * @param snapshot - Captured browser snapshot
- * @param root - Root whose descendants are searched
- * @param predicate - Node predicate
- * @returns First matching descendant, or undefined
- */
-export declare function findBrowserDescendant(snapshot: BrowserSnapshot, root: BrowserNode, predicate: BrowserNodePredicate): BrowserNode | undefined;
-
-/**
- * Find the first captured node satisfying a predicate.
- *
- * @param snapshot - Captured browser snapshot
- * @param predicate - Node predicate
- * @returns First matching node, or undefined
- */
-export declare function findBrowserNode(snapshot: BrowserSnapshot, predicate: BrowserNodePredicate): BrowserNode | undefined;
-
-/**
- * Find captured nodes satisfying a predicate.
- *
- * @param snapshot - Captured browser snapshot
- * @param predicate - Node predicate
- * @param limit - Optional maximum result count
- * @returns Matching nodes in snapshot order
- */
-export declare function findBrowserNodes(snapshot: BrowserSnapshot, predicate: BrowserNodePredicate, limit?: number): readonly BrowserNode[];
-
-/**
- * Return structural siblings after the supplied browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Reference node
- * @returns Later siblings in structural order
- */
-export declare function followingSiblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
-
 /**
  * Wrap a `Runtime.evaluate` expression so the IN-PAGE code stringifies its
  * own result and throws a recognizable error before an oversized result
@@ -2703,14 +2671,20 @@ export declare function guardEvaluateExpression(expression: string, limit: numbe
 export declare function isBrowserError(value: unknown): value is BrowserError;
 
 /**
- * Test whether one captured node is below another across frame boundaries.
+ * Test whether a browser-node matcher is a declarative query.
+ *
+ * @param value - Browser-node query or predicate
+ * @returns Whether the matcher is a declarative query
  *
- * @param snapshot - Captured browser snapshot
- * @param node - Candidate descendant
- * @param ancestor - Candidate ancestor
- * @returns Whether the relationship exists
+ * @example
+ * ```ts
+ * import { isBrowserNodeQuery } from '@src/core'
+ *
+ * isBrowserNodeQuery({ name: 'main' }) // true
+ * isBrowserNodeQuery(() => true) // false
+ * ```
  */
-export declare function isBrowserNodeDescendant(snapshot: BrowserSnapshot, node: BrowserNode, ancestor: BrowserNode): boolean;
+export declare function isBrowserNodeQuery(value: BrowserNodeQuery | BrowserNodePredicate): value is BrowserNodeQuery;
 
 /**
  * Test whether a captured node has a non-empty rendered layout box.
@@ -2812,15 +2786,6 @@ export declare function matchesBrowserURL(url: string, pattern: string): boolean
  */
 export declare function mediaToFeatures(media: BrowserMedia): readonly Readonly<Record<string, string>>[];
 
-/**
- * Build a deterministic, serializable path for a captured browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Captured browser node
- * @returns Frame-qualified structural path
- */
-export declare function nodeToPath(snapshot: BrowserSnapshot, node: BrowserNode): string;
-
 /**
  * Normalize a raw list of recorded codegen actions.
  *
@@ -2835,18 +2800,6 @@ export declare function nodeToPath(snapshot: BrowserSnapshot, node: BrowserNode)
  */
 export declare function normalizeCodegenActions(actions: readonly BrowserCodegenAction[]): readonly BrowserCodegenAction[];
 
-/**
- * Resolve the structural parent of a captured browser node.
- *
- * @remarks
- * An iframe content-document root resolves to its owning iframe node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Child node
- * @returns Parent node, or undefined for a top-level document root
- */
-export declare function parentOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): BrowserNode | undefined;
-
 /**
  * Parse a keyboard chord such as `Control+Shift+P`.
  *
@@ -2868,15 +2821,6 @@ export declare function parseBrowserChord(value: string): BrowserChord;
  */
 export declare function parseCodegenActionPayload(payload: unknown): BrowserCodegenAction | undefined;
 
-/**
- * Return structural siblings before the supplied browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Reference node
- * @returns Earlier siblings in structural order
- */
-export declare function precedingSiblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
-
 /**
  * Decode Accessibility-domain nodes into a flat serializable tree.
  *
@@ -3228,15 +3172,6 @@ export declare interface ScreenshotWriterInterface {
     write(path: string, data: Uint8Array): Promise<void>;
 }
 
-/**
- * Return every structural sibling except the supplied browser node.
- *
- * @param snapshot - Captured browser snapshot
- * @param node - Node whose siblings are required
- * @returns Siblings in structural order
- */
-export declare function siblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
-
 /** Encode UTF-8 text as bytes. */
 export declare function textToBytes(value: string): Uint8Array;
 
@@ -3307,42 +3242,4 @@ export declare function validateBrowserTimeout(timeout: number): void;
  */
 export declare function validateBrowserViewport(viewport: BrowserViewport): void;
 
-/**
- * Lazily walk one captured browser-node subtree in depth-first order.
- *
- * @param snapshot - Captured browser snapshot
- * @param root - Root node, included as the first result
- * @returns A lazy subtree generator
- */
-export declare function walkBrowserNode(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
-
-/**
- * Lazily walk one captured browser-node subtree in breadth-first order.
- *
- * @param snapshot - Captured browser snapshot
- * @param root - Root node, included as the first result
- * @returns A lazy breadth-first subtree generator
- */
-export declare function walkBrowserNodeBreadthFirst(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
-
-/**
- * Lazily walk every captured browser node in structural depth-first order.
- *
- * @remarks
- * Iframe content documents are entered at their owner element. Orphaned or
- * cyclic protocol nodes are still yielded once through an identity guard.
- *
- * @param snapshot - Captured browser snapshot
- * @returns A lazy node generator
- */
-export declare function walkBrowserSnapshot(snapshot: BrowserSnapshot): Generator<BrowserNode, void, unknown>;
-
-/**
- * Lazily walk every captured node in structural breadth-first order.
- *
- * @param snapshot - Captured browser snapshot
- * @returns A lazy breadth-first generator
- */
-export declare function walkBrowserSnapshotBreadthFirst(snapshot: BrowserSnapshot): Generator<BrowserNode, void, unknown>;
-
 export { }