browserscale-ts 1.5.0 → 1.7.0

package/dist/dom-mirror.d.ts

@@ -0,0 +1,271 @@
+import type { DomEvent } from "./gen/wrc_pb.ts";
+/**
+ * A node in the mirrored page, in CDP's `DOM.Node` shape — the same shape
+ * {@link CloudBrowser.getDOM} returns, with two additions that the mirror
+ * needs and a caller usually wants anyway: {@link DomNode.frameId} and
+ * {@link DomNode.contentFrameId}.
+ *
+ * An `<iframe>` is an ordinary element here. The document it hosts is its one
+ * entry in {@link DomNode.children}, present once the element has been
+ * expanded, and nothing about walking the tree has to know a process boundary
+ * runs through it.
+ */
+export interface DomNode {
+    nodeId: number;
+    backendNodeId: number;
+    nodeType: number;
+    nodeName: string;
+    localName?: string;
+    nodeValue?: string;
+    /** Flat `[name, value, name, value, ...]`, as CDP sends it. */
+    attributes?: string[];
+    /**
+     * Total children in the page, whether or not they are in `children`. An
+     * `<iframe>` reports 1: the document it hosts.
+     */
+    childNodeCount?: number;
+    /** Present once the node has been expanded. */
+    children?: DomNode[];
+    /** Author shadow roots, when the mirror was started with `pierce`. */
+    shadowRoots?: DomNode[];
+    /**
+     * The frame this node lives in. Always set.
+     *
+     * Together with `backendNodeId` this is the node's address: node ids are
+     * handed out per renderer and restart per frame, so two frames can and do
+     * use the same one, and the id on its own is ambiguous across a page.
+     */
+    frameId: string;
+    /**
+     * For an element that hosts a frame (`<iframe>`, `<frame>`, `<object>`):
+     * the frame it hosts, which is a different frame from `frameId` and is the
+     * one its child document's ids belong to.
+     */
+    contentFrameId?: string;
+}
+/**
+ * The opening snapshot: the main frame's document. Child frames are not in it
+ * — their documents are fetched by expanding the `<iframe>` elements that host
+ * them, which is also what starts mirroring them.
+ */
+export interface DomSnapshot {
+    root: string;
+    frameId: string;
+    /** The page sequence this snapshot is the baseline for. */
+    seq: number;
+}
+/** Why a mirror had to be rebuilt. */
+export type DomResyncReason = "documentReplaced" | "overflow" | "rendererGone" | "slowReader" | string;
+export interface DomMirrorOptions {
+    /**
+     * Levels to fetch up front. Default 2, which is `#document` → `<html>` →
+     * `<head>`/`<body>` — enough to draw a collapsed tree. Fetching everything
+     * (-1) works but gives up what the mirror is for.
+     */
+    depth?: number;
+    /** Descend into author shadow roots. Fixed for the life of the mirror. */
+    pierce?: boolean;
+}
+/**
+ * Called after the tree changed. `root` is a fresh object whenever anything
+ * below it changed, so it can be compared by identity and rendered with
+ * memoized components.
+ */
+export type DomChangeHandler = (mirror: DomMirror) => void;
+/** Called when the mirror had to be rebuilt, after the new tree is in place. */
+export type DomResyncHandler = (reason: DomResyncReason) => void;
+/** @internal The transport calls the mirror needs. Supplied by CloudBrowser. */
+export interface DomMirrorTransport {
+    start(opts: DomMirrorOptions): Promise<DomSnapshot>;
+    stop(): Promise<void>;
+    children(backendNodeId: number, frameId: string, depth?: number): Promise<{
+        children: string;
+        seq: number;
+    }>;
+    release(backendNodeId: number, frameId: string): Promise<void>;
+    reveal(backendNodeId: number, frameId: string): Promise<{
+        path: string;
+        seq: number;
+    }>;
+}
+/**
+ * A live copy of a page's DOM, across every frame in it.
+ *
+ * Returned by {@link CloudBrowser.mirrorDom}. The browser sends the top of the
+ * tree once and from then on only what changed in the part you expanded, so a
+ * page that churns inside a collapsed subtree costs one number per batch
+ * instead of a re-serialized document.
+ *
+ * It is one tree. An `<iframe>` is an element whose one child is the document
+ * it hosts; expanding it fetches that document and starts mirroring the frame,
+ * collapsing it stops again, and a frame navigating arrives as its owner's
+ * child being replaced. Underneath there is still one mirror per document,
+ * because a mutation observer is bound to a single Document and an
+ * out-of-process iframe is a different Document in a different process — but
+ * that is engine bookkeeping, not something a caller models.
+ *
+ * Node ids restart per frame, so a node's address is the pair
+ * ({@link DomNode.frameId}, `backendNodeId`) and never the id alone.
+ *
+ * The tree is treated as immutable: applying a change replaces the nodes from
+ * the root down to the one that moved and leaves every other object identical.
+ * A UI can therefore re-render from `root` and let `React.memo` (or any
+ * identity check) skip the parts that did not move.
+ *
+ * ```ts
+ * const mirror = await browser.mirrorDom({ pierce: true }, () => render(mirror.root));
+ * await mirror.expand(bodyNode);   // start reporting changes inside <body>
+ * await mirror.collapse(bodyNode); // stop again
+ * await mirror.stop();
+ * ```
+ */
+export declare class DomMirror {
+    private readonly transport;
+    private readonly options;
+    private readonly onChange;
+    private readonly onResync?;
+    private readonly abort;
+    private readonly finished;
+    private nodes;
+    private slots;
+    private expandedKeys;
+    /**
+     * Per node: the page sequence its current state was defined at, by a read
+     * payload or by an edit.
+     *
+     * Reads and events reach a client over two different channels — a unary call
+     * and a stream — so an event can turn up that the read reply already folded
+     * in. Applying it twice would duplicate an insertion, which is the one entry
+     * type that is not idempotent. Comparing against the node's own watermark
+     * rather than a single page-wide one keeps that from silently discarding a
+     * change to an unrelated part of the tree.
+     */
+    private asOf;
+    private seqValue;
+    private rootNode;
+    private mainFrame;
+    /**
+     * Events are held until a snapshot exists to apply them to, and dropped if
+     * they predate it. Without this a batch that lands between subscribing and
+     * the snapshot arriving would either be applied to nothing or applied twice.
+     */
+    private ready;
+    private pendingEvents;
+    private stopped;
+    private failure;
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init: {
+        stream: AsyncIterable<DomEvent>;
+        transport: DomMirrorTransport;
+        options: DomMirrorOptions;
+        onChange: DomChangeHandler;
+        onResync?: DomResyncHandler;
+        abort: AbortController;
+    });
+    /** The main frame's document, or null before the first snapshot arrived. */
+    get root(): DomNode | null;
+    /** The page's main frame. */
+    get mainFrameId(): string;
+    /**
+     * Every frame with a document in the tree, main frame first. A frame whose
+     * `<iframe>` has not been expanded is not mirrored and not listed.
+     */
+    get frameIds(): string[];
+    /**
+     * The page sequence of the last change applied. One clock for the whole
+     * page: a change in an out-of-process iframe and one in the main document
+     * are ordered against each other.
+     */
+    get seq(): number;
+    /** Looks up a node by its address. */
+    getNode(frameId: string, backendNodeId: number): DomNode | undefined;
+    /**
+     * Whether this node's children are known. Changes inside a node that is not
+     * expanded arrive only as an updated `childNodeCount`.
+     */
+    isExpanded(node: DomNode): boolean;
+    /** Why the mirror ended: null while running and after a clean stop. */
+    get error(): Error | null;
+    /**
+     * Fetches a node's children and starts reporting changes inside them. This
+     * is what a tree view calls when the user opens a node.
+     *
+     * On an `<iframe>` the one child is the document it hosts, and this call is
+     * what starts mirroring that frame. Nothing about the result says a process
+     * boundary was crossed; it is a child list like any other.
+     *
+     * @param depth levels below the node, default 1
+     */
+    expand(node: DomNode, depth?: number): Promise<void>;
+    /**
+     * Stops reporting changes inside a node, called when the user closes it. The
+     * node itself stays in the tree and keeps reporting its child count. A child
+     * frame below it stops being mirrored too.
+     *
+     * Skipping this is not an error, it is a slow leak: the browser's revealed
+     * set only grows, and eventually it is no longer filtering anything.
+     */
+    collapse(node: DomNode): Promise<void>;
+    /**
+     * Brings a node into the tree together with its ancestors and their
+     * siblings, and starts reporting changes along that path.
+     *
+     * Use it to focus a node you do not hold — an `inspectAtPosition` hit, say.
+     * You cannot walk up to it yourself: it is not in your tree, so there is
+     * nothing to walk from.
+     *
+     * The node may be in a frame nobody opened, and that works: the chain comes
+     * back crossing the frame boundaries it has to, and those frames start being
+     * mirrored, exactly as if you had expanded your way there by hand.
+     *
+     * @returns the ancestor chain, the main document first, or an empty array if
+     *   the node is not on the page
+     */
+    reveal(backendNodeId: number, frameId?: string): Promise<DomNode[]>;
+    /**
+     * Throws away the local copy of the whole page and fetches a fresh one.
+     * Happens automatically whenever the browser says the copy is void, so you
+     * rarely need to call it.
+     */
+    resync(reason?: DomResyncReason): Promise<void>;
+    /** Resolves once the mirror ends — stop(), a dead session, a transport failure. */
+    wait(): Promise<void>;
+    /** Stops mirroring and detaches the reader. Idempotent, safe in a `finally`. */
+    stop(): Promise<void>;
+    /** @internal Called by CloudBrowser with the opening snapshot. */
+    install(snapshot: DomSnapshot): void;
+    private reset;
+    private pump;
+    private handle;
+    private apply;
+    /** Records that a node's state is current as of `seq`. Never moves back. */
+    private mark;
+    /**
+     * Replaces `key` and every ancestor with copies, so the path from the root
+     * to the changed node has new identities and nothing else does. Returns the
+     * fresh copy of `key`, which the caller then edits in place.
+     *
+     * The walk crosses frame boundaries without noticing them: a document is a
+     * child of the `<iframe>` hosting it like any other, so a change deep inside
+     * an out-of-process frame still produces a new `root`.
+     */
+    private touch;
+    /**
+     * Registers a payload subtree and returns the copy that lives in the tree.
+     *
+     * `frame` is the id space the payload's ids belong to, and it changes here
+     * and nowhere else: a document node names its own frame, and everything
+     * below it counts in that frame. That is the whole of what crossing into an
+     * iframe means to a client.
+     */
+    private adopt;
+    /** Replaces a node's child list from a fresh payload for the same node. */
+    private mergeChildren;
+    private dropChildren;
+    /**
+     * Removes a subtree from the index. It descends through hosted documents
+     * like through anything else — they are children, and a frame stops being
+     * mirrored exactly when the element hosting it stops being expanded.
+     */
+    private forget;
+}