@e2e-dev/web 0.15.5-nightly-20261105030216 → 0.15.5

package/dist/install.js

@@ -18,11 +18,11 @@ function headlessShellInstalled(browsersPath, revision) {
  * Whether the build the run launches (headless shell for headless chromium, else the full build)
  * is on disk, or undefined when `env` points at another cache than this process loaded.
  */
-function isBrowserInstalled(name, env, headed) {
+async function isBrowserInstalled(name, env, headed) {
     if (env['PLAYWRIGHT_BROWSERS_PATH'] !== process.env['PLAYWRIGHT_BROWSERS_PATH'])
         return undefined;
     try {
-        const executable = browserType(name).executablePath();
+        const executable = (await browserType(name)).executablePath();
         if (headed || name !== 'chromium')
             return existsSync(executable);
         return headlessShellAt(executable);
@@ -79,8 +79,8 @@ export function runPlaywrightCli(args) {
  * disk, a `warn` when the first run will download it, or none when `env`
  * points at another browser cache than this process loaded.
  */
-export function browserCheck(name, env, headed, isInstalled = (browser) => isBrowserInstalled(browser, env, headed)) {
-    const installed = isInstalled(name);
+export async function browserCheck(name, env, headed, isInstalled = (browser) => isBrowserInstalled(browser, env, headed)) {
+    const installed = await isInstalled(name);
     if (installed === undefined)
         return [];
     if (installed)
@@ -115,7 +115,7 @@ export async function ensureBrowsersInstalled(names, options = {}) {
     const env = options.env ?? process.env;
     const headed = options.headed ?? false;
     const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env, headed));
-    const verdicts = new Map([...new Set(names)].map((name) => [name, isInstalled(name)]));
+    const verdicts = new Map(await Promise.all([...new Set(names)].map(async (name) => [name, await isInstalled(name)])));
     const missing = [...verdicts.keys()].filter((name) => verdicts.get(name) !== true);
     if (missing.length === 0)
         return;

package/dist/observation-capture.js

@@ -37,11 +37,11 @@ export async function captureObservation(page, refs, settings, operation, option
                 captureDocument({
                     ...settings,
                     reserveIds: (count) => refs.reserveIds(count),
-                    commit: (id, element) => {
+                    commit: (id, target) => {
                         if (accepting && !operation.signal.aborted)
-                            generation.set(id, { kind: 'element', element });
+                            generation.set(id, target);
                         else
-                            void element.dispose().catch(() => undefined);
+                            target.list.dispose();
                     },
                 }, page, {
                     framePath: [], budget: MAX_OBSERVED_NODES,

package/dist/observation.d.ts

@@ -2,9 +2,10 @@
  * Semantic tree capture for one observation: the in-page walk, nested-document
  * stitching, and element-handle bookkeeping the surface keeps per generation.
  */
-import type { ElementHandle, Frame } from 'playwright-core';
-import { type NodeRef, type SemanticNode } from 'e2e/engine';
+import type { Frame } from 'playwright-core';
+import { type NodeRef, type SemanticNode, type ViewportPoint } from 'e2e/engine';
 import { type RawNodeData } from './read-node.ts';
+import type { ListedTarget } from './refs.ts';
 /**
  * The id of every observation's root: the main document's element under one
  * id the engine mints, stable across observations and navigations, so the
@@ -21,8 +22,8 @@ export interface CaptureDeps {
     readonly site: string | undefined;
     /** Reserves a disjoint range before the reader can stamp any element, including on timeout. */
     reserveIds(count: number): number;
-    /** Publishes one element handle under its id in the generation being built. */
-    commit(id: string, element: ElementHandle<Element>): void;
+    /** Publishes one observed node under its id in the generation being built. */
+    commit(id: string, target: ListedTarget): void;
 }
 export interface CaptureOptions {
     /** Enclosing frame selectors, outermost first; empty for the main document. */
@@ -69,10 +70,13 @@ export declare function frameContentInset(element: Element): Rect;
 /** A frame element's content box, from its border box and `frameContentInset`. */
 export declare function contentBox(border: Rect, inset: Rect): Rect;
 /**
- * A box a child document measured against its own viewport, in the top-level
- * viewport's space: shifted by the frame's box and clipped to it; undefined
- * when nothing of it is inside the frame.
+ * A node box a child document measured against its own viewport, in the
+ * top-level viewport's space: `rect` shifted by the frame's box and clipped
+ * to it, empty when nothing of it is inside the frame. `origin` is shifted
+ * but never clipped, and a clip that moves the box's corner keeps the
+ * unclipped corner as `origin`, so an offset into the node lands where it
+ * would at the top level.
  */
-export declare function placeRectInFrame(rect: Rect, frame: Rect): Rect | undefined;
+export declare function placeBoxInFrame(rect: Rect, origin: ViewportPoint | undefined, frame: Rect): Pick<SemanticNode, 'rect' | 'origin'>;
 export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
 export {};

package/dist/observation.js

@@ -5,6 +5,7 @@
 import { EngineError, sameSite, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, } from 'e2e/engine';
 import { readDocumentSemanticsFunction, SECURE_FIELD_SELECTOR, } from './read-node.js';
 import { CaptureScope } from './capture-scope.js';
+import { ElementList } from './element-list.js';
 import { hasReadableDocument } from './frame-document.js';
 /**
  * The id of every observation's root: the main document's element under one
@@ -37,16 +38,22 @@ export async function captureDocument(deps, host, options) {
     // A child document's handles are published only once it captured whole; a
     // frame that fails midway leaves no reachable ids behind.
     const staged = [];
-    const stage = (id, element) => {
-        if (scope.own(element))
-            staged.push([id, element]);
+    const accepted = new Map();
+    const stage = (id, target) => {
+        let owned = accepted.get(target.list);
+        if (owned === undefined) {
+            owned = scope.own(target.list.handle);
+            accepted.set(target.list, owned);
+        }
+        if (owned)
+            staged.push([id, target]);
     };
     return scope.run(async () => {
         const captured = await captureInto(deps, scope, stage, host, framePath, budget, signal);
         scope.check();
-        for (const [id, element] of staged) {
-            deps.commit(id, element);
-            scope.release(element);
+        for (const [id, target] of staged) {
+            deps.commit(id, target);
+            scope.release(target.list.handle);
         }
         return captured;
     });
@@ -99,8 +106,8 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
     if (framePath.length === 0 && ids.length > 0)
         ids[0] = ROOT_NODE_ID;
     const elementsHandle = await scope.read(() => captured.getProperty('elements'), (handle) => scope.own(handle));
-    const elements = await collectElementHandles(scope, elementsHandle, nodes.length);
-    elements.forEach((element, index) => stage(ids[index], element));
+    const list = new ElementList(elementsHandle);
+    ids.forEach((id, index) => stage(id, { kind: 'listed', list, index }));
     let nodeCount = nodes.length;
     let truncated = walkTruncated === true;
     const frameChildren = new Map();
@@ -110,7 +117,10 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             continue;
         // A frame with no document (detached, never loaded) shows nothing, so
         // nothing is missing from the tree.
-        const frame = await scope.read(() => elements[index].contentFrame().catch(() => null));
+        // Owned by the scope and released with it: the frame's element is read
+        // here, and an action reaches it later through the list like any node.
+        const element = await scope.read(() => list.fetch(index), (handle) => scope.own(handle));
+        const frame = await scope.read(() => element.contentFrame().catch(() => null));
         if (frame === null)
             continue;
         // Only frames on the app's site enter observations. Third-party
@@ -120,7 +130,7 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
         if (!isOnSiteFrame(frame.url(), deps.site))
             continue;
         // A frame whose navigation has not committed shows nothing yet.
-        if (!(await scope.read(() => hasReadableDocument(frame, elements[index]))))
+        if (!(await scope.read(() => hasReadableDocument(frame, element))))
             continue;
         // From here the frame's document is content the model should see: any
         // reason it is not read (depth, budget, deadline, a failed or timed-out
@@ -134,7 +144,7 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             truncated = true;
             continue;
         }
-        const inset = await scope.read(() => elements[index].evaluate(frameContentInset).catch(() => undefined));
+        const inset = await scope.read(() => element.evaluate(frameContentInset).catch(() => undefined));
         if (inset === undefined) {
             truncated = true;
             continue;
@@ -174,31 +184,6 @@ function isOnSiteFrame(url, site) {
     const protocol = URL.canParse(url) ? new URL(url).protocol : undefined;
     return protocol !== 'data:' && sameSite(url, site);
 }
-/**
- * Reads one element handle per observed node from the in-page element array.
- * `asElement` types handles as `ElementHandle<Node>`, but the observation walk
- * records `Element` nodes only, so the narrowing is safe by construction.
- */
-async function collectElementHandles(scope, elementsHandle, count) {
-    const properties = await scope.read(() => elementsHandle.getProperties(), (handles) => {
-        for (const handle of handles.values())
-            scope.own(handle);
-    });
-    const elements = [];
-    for (let index = 0; index < count; index += 1) {
-        const property = properties.get(String(index));
-        const element = (property?.asElement() ?? null);
-        if (element === null) {
-            // The in-page array outlived its document (a navigation committed while
-            // the handles were being read back). The capture is repeatable.
-            throw new EngineError('NODE_STALE', `observation node ${index} lost its element`, {
-                retryable: true,
-            });
-        }
-        elements.push(element);
-    }
-    return elements;
-}
 /**
  * Rebuilds the observation tree from the depth-first node list. Descendants
  * always follow their parent, so children are complete before a parent is
@@ -256,21 +241,28 @@ export function contentBox(border, inset) {
 }
 /** The tree with every box translated into the frame's space and clipped to its box; a box left empty by the clip is dropped. */
 function placeInFrame(node, frame) {
-    const { rect, ...rest } = node;
-    const placed = rect === undefined ? undefined : placeRectInFrame(rect, frame);
+    const { rect, origin, ...rest } = node;
     return {
         ...rest,
-        ...(placed === undefined ? {} : { rect: placed }),
+        ...(rect === undefined ? {} : placeBoxInFrame(rect, origin, frame)),
         ...(node.children === undefined ? {} : { children: node.children.map((child) => placeInFrame(child, frame)) }),
     };
 }
 /**
- * A box a child document measured against its own viewport, in the top-level
- * viewport's space: shifted by the frame's box and clipped to it; undefined
- * when nothing of it is inside the frame.
+ * A node box a child document measured against its own viewport, in the
+ * top-level viewport's space: `rect` shifted by the frame's box and clipped
+ * to it, empty when nothing of it is inside the frame. `origin` is shifted
+ * but never clipped, and a clip that moves the box's corner keeps the
+ * unclipped corner as `origin`, so an offset into the node lands where it
+ * would at the top level.
  */
-export function placeRectInFrame(rect, frame) {
-    return clipRect(offsetRect(rect, frame), frame);
+export function placeBoxInFrame(rect, origin, frame) {
+    const placed = clipRect(offsetRect(rect, frame), frame);
+    if (placed === undefined)
+        return {};
+    const corner = origin ?? rect;
+    const shifted = { x: corner.x + frame.x, y: corner.y + frame.y };
+    return shifted.x === placed.x && shifted.y === placed.y ? { rect: placed } : { rect: placed, origin: shifted };
 }
 function offsetRect(rect, by) {
     return { x: rect.x + by.x, y: rect.y + by.y, width: rect.width, height: rect.height };
@@ -313,6 +305,7 @@ export function toSemanticNode(ref, raw, children = [], framePath = []) {
         ...(raw.level !== null ? { level: raw.level } : {}),
         attributes: raw.attributes,
         ...(raw.rect !== null ? { rect: raw.rect } : {}),
+        ...(raw.origin !== null ? { origin: raw.origin } : {}),
         ...(framePath.length > 0 ? { framePath } : {}),
         ...(children.length > 0 ? { children } : {}),
     };

package/dist/read-node.d.ts

@@ -55,6 +55,11 @@ export interface RawNodeData {
         width: number;
         height: number;
     } | null;
+    /** The element's padding-box corner in the same viewport, when a border puts it past `rect`'s; null otherwise. */
+    origin: {
+        x: number;
+        y: number;
+    } | null;
 }
 /** One observed node plus its position in the flattened depth-first tree. */
 export interface RawObservedNode extends RawNodeData {

package/dist/refs.d.ts

@@ -4,17 +4,24 @@
  *
  * Two populations with different lifetimes live here. Locator-backed refs
  * from `locate` hold no live handles and are pruned oldest-first past a
- * bound. Handle-backed refs from `observe` form one generation per
- * observation: the whole generation is swapped atomically and the superseded
- * one disposed in a sweep, so locator-ref eviction can never destroy a handle
+ * bound. List-backed refs from `observe` form one generation per
+ * observation: the whole generation is swapped atomically and its element
+ * lists disposed in a sweep, so locator-ref eviction can never destroy a list
  * an in-flight observation still references.
  */
 import { type EngineSnapshot, type NodeRef } from 'e2e/engine';
+import type { ElementList } from './element-list.ts';
 import type { ActionTarget } from './support.ts';
+/** An observed node: one position in the element list of the document it was read from. */
+export interface ListedTarget {
+    readonly kind: 'listed';
+    readonly list: ElementList;
+    readonly index: number;
+}
 /** A complete observation and the private handles that back its semantic refs. */
 export interface CapturedObservation {
     readonly snapshot: EngineSnapshot;
-    readonly generation: Map<string, ActionTarget>;
+    readonly generation: Map<string, ListedTarget>;
 }
 export declare class RefRegistry {
     private counter;
@@ -28,15 +35,17 @@ export declare class RefRegistry {
     storeLocated(target: ActionTarget): string;
     /**
      * Ids are the engine's; revisions are the harness's. The adapter already
-     * rejected a ref from a superseded resolution, so lookup is by id alone.
+     * rejected a ref from a superseded resolution, so lookup is by id alone. An
+     * observed node's element handle is made here, the first time an action
+     * reaches for it.
      */
-    lookup(ref: NodeRef): ActionTarget;
+    lookup(ref: NodeRef): Promise<ActionTarget>;
     /** Starts a capture, preventing older in-flight observations from publishing afterward. */
     beginCapture(): number;
     /** Publishes only the current capture; pixel-only recovery also retires located refs. */
     publish(capture: number, { snapshot, generation }: CapturedObservation): void;
     /** Releases every ref of the attempt: located and observed alike. */
     clear(): void;
-    /** Disposes every element handle in one observation generation. */
-    static dispose(generation: ReadonlyMap<string, ActionTarget>): void;
+    /** Disposes every element handle in one generation, each list once however many nodes it backs. */
+    static dispose(generation: ReadonlyMap<string, ActionTarget | ListedTarget>): void;
 }

package/dist/refs.js

@@ -4,9 +4,9 @@
  *
  * Two populations with different lifetimes live here. Locator-backed refs
  * from `locate` hold no live handles and are pruned oldest-first past a
- * bound. Handle-backed refs from `observe` form one generation per
- * observation: the whole generation is swapped atomically and the superseded
- * one disposed in a sweep, so locator-ref eviction can never destroy a handle
+ * bound. List-backed refs from `observe` form one generation per
+ * observation: the whole generation is swapped atomically and its element
+ * lists disposed in a sweep, so locator-ref eviction can never destroy a list
  * an in-flight observation still references.
  */
 import { EngineError } from 'e2e/engine';
@@ -42,14 +42,19 @@ export class RefRegistry {
     }
     /**
      * Ids are the engine's; revisions are the harness's. The adapter already
-     * rejected a ref from a superseded resolution, so lookup is by id alone.
+     * rejected a ref from a superseded resolution, so lookup is by id alone. An
+     * observed node's element handle is made here, the first time an action
+     * reaches for it.
      */
-    lookup(ref) {
-        const target = this.located.get(ref.id) ?? this.observation.get(ref.id);
-        if (target === undefined) {
+    async lookup(ref) {
+        const located = this.located.get(ref.id);
+        if (located !== undefined)
+            return located;
+        const observed = this.observation.get(ref.id);
+        if (observed === undefined) {
             throw new EngineError('NODE_STALE', `node reference ${ref.id} is stale`, { retryable: true });
         }
-        return target;
+        return { kind: 'element', element: await observed.list.at(observed.index) };
     }
     /** Starts a capture, preventing older in-flight observations from publishing afterward. */
     beginCapture() {
@@ -74,11 +79,16 @@ export class RefRegistry {
         RefRegistry.dispose(this.located);
         this.located.clear();
     }
-    /** Disposes every element handle in one observation generation. */
+    /** Disposes every element handle in one generation, each list once however many nodes it backs. */
     static dispose(generation) {
+        const lists = new Set();
         for (const target of generation.values()) {
-            if (target.kind === 'element')
+            if (target.kind === 'listed')
+                lists.add(target.list);
+            else if (target.kind === 'element')
                 void target.element.dispose().catch(() => undefined);
         }
+        for (const list of lists)
+            list.dispose();
     }
 }

package/dist/support.d.ts

@@ -1,6 +1,7 @@
 /** Shared error translation, filename, and swipe helpers for the Playwright engine. */
-import type { ElementHandle, Locator as PwLocator, Mouse, Page } from 'playwright-core';
+import type { ElementHandle, FrameLocator, Locator as PwLocator, Mouse, Page } from 'playwright-core';
 import { EngineError, type EngineCleanupContext, type Momentum, type ScrollDirection, type ViewportPoint, type ViewportSize } from 'e2e/engine';
+import { TestError } from 'e2e/engine';
 export declare const DEFAULT_VIEWPORT: {
     readonly width: 1280;
     readonly height: 720;
@@ -13,8 +14,9 @@ export declare const DEFAULT_VIEWPORT: {
 export declare function currentViewport(page: Page): Promise<ViewportSize>;
 /**
  * A resolved node is addressed either by a deterministic locator expression or
- * by a live element handle captured during one agent observation. Handles are
- * always elements: the in-page observation walk records `Element` nodes only.
+ * by an element handle made from one agent observation's element list.
+ * Handles are always elements: the in-page observation walk records `Element`
+ * nodes only.
  */
 export type ActionTarget = {
     readonly kind: 'locator';
@@ -127,6 +129,17 @@ export declare const POST_DISPATCH_PATTERN: RegExp;
 export declare function translatePwError(cause: unknown, operation: string): Error;
 /** Whether a Playwright failure describes a read that lost its document to a navigation. */
 export declare function isNavigationRace(cause: unknown): boolean;
+/**
+ * The failure of an operation whose in-page code the page's own scripts broke,
+ * as `EVALUATE_FAILED`, or undefined when something else failed. A page that
+ * deletes or replaces a JavaScript built-in (`Map`, `Object`) breaks every
+ * script Playwright runs in its main world, e2e's locate reads included. Told
+ * apart by asking the frame in both worlds: Playwright's utility world still
+ * reads the document before and after a main-world query that runs no e2e
+ * code fails, so the frame lives throughout and e2e's own code is not the
+ * cause.
+ */
+export declare function pageScriptFailure(scope: Page | FrameLocator, cause: unknown, operation: string, timeoutMs: number): Promise<TestError | undefined>;
 /**
  * Like translatePwError, but a read that lost its document to a navigation
  * becomes retryable NODE_STALE so the runner re-reads the new document instead

package/dist/support.js

@@ -283,6 +283,37 @@ const NAVIGATION_RACE_PATTERN = /execution context was destroyed|because of a na
 export function isNavigationRace(cause) {
     return NAVIGATION_RACE_PATTERN.test(message(cause));
 }
+/**
+ * The failure of an operation whose in-page code the page's own scripts broke,
+ * as `EVALUATE_FAILED`, or undefined when something else failed. A page that
+ * deletes or replaces a JavaScript built-in (`Map`, `Object`) breaks every
+ * script Playwright runs in its main world, e2e's locate reads included. Told
+ * apart by asking the frame in both worlds: Playwright's utility world still
+ * reads the document before and after a main-world query that runs no e2e
+ * code fails, so the frame lives throughout and e2e's own code is not the
+ * cause.
+ */
+export async function pageScriptFailure(scope, cause, operation, timeoutMs) {
+    if (isClassified(cause) || isPwTimeout(cause) || isNavigationRace(cause))
+        return undefined;
+    const root = scope.locator(':root');
+    /** Whether Playwright's utility world still reads the frame's document. */
+    const alive = () => root.count().then(() => true, () => false);
+    if (!(await alive()))
+        return undefined;
+    try {
+        await root.evaluate(() => 0, undefined, { timeout: Math.max(timeoutMs, 1) });
+        return undefined;
+    }
+    catch (probe) {
+        if (isPwTimeout(probe) || isNavigationRace(probe))
+            return undefined;
+    }
+    // A crash or a closed target between the two probes fails this read too.
+    if (!(await alive()))
+        return undefined;
+    return new TestError('EVALUATE_FAILED', `${operation} failed: the page deleted or replaced a JavaScript built-in that in-page automation code needs: ${message(cause)}`, { cause });
+}
 /**
  * Like translatePwError, but a read that lost its document to a navigation
  * becomes retryable NODE_STALE so the runner re-reads the new document instead

package/dist/surface.d.ts

@@ -6,7 +6,7 @@
  * `actions.ts` and tree capture in `observation.ts`. `AttemptSession` owns
  * the attempt's live binding, recovery, references, and recordings.
  */
-import type { BrowserContext, Page, Route } from 'playwright-core';
+import type { BrowserContext, Page, Request, Route } from 'playwright-core';
 import { type EngineAttemptContext, type EngineCleanupContext, type EngineDoctorCheck, type EngineDoctorInfo, type EngineInitInfo, type EngineObserveOptions, type EnginePrepareInfo, type EnginePrepareResult, type EngineFinishInfo, type EngineSnapshot, type EngineState, type LocatorAction, type LocatorExpression, type NodeRef, type OperationContext, type PointerAction, type Secret, type SemanticNode, type VideoSegment, type ViewportPoint, type ViewportSize } from 'e2e/engine';
 import { type BrowserName } from './browser-connection.ts';
 import { type BrowserProvider, type LeaseDownloads } from './provider.ts';
@@ -206,6 +206,8 @@ export declare class PlaywrightSurface {
     private artifactsDir;
     /** Navigations the engine has in flight, which the app log leaves to the step that started them. */
     private ownNavigations;
+    /** One entry per navigation in flight, set to the URL of a document request a test route aborted during it. */
+    private readonly navigationAborts;
     /** What the attempt tells its trace beside the app log; absent between attempts. */
     private trace;
     private artifactCounter;
@@ -344,8 +346,18 @@ export declare class PlaywrightSurface {
     back(operation: OperationContext): Promise<void>;
     /** Sets the viewport for the agent's `resize` verb, as `browser.setViewport` does, and shows the screen after it. */
     resize(size: ViewportSize, operation: OperationContext): Promise<void>;
-    /** Runs one navigation the engine itself makes, so the app log leaves it to the step that asked for it. */
+    /**
+     * Runs one navigation the engine itself makes, so the app log leaves it to
+     * the step that asked for it. A navigation that fails after a test route
+     * aborted its document request failed because the test aborted it: an
+     * action failure, not an engine fault.
+     */
     navigating<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Records a request a test route is about to abort, when it loads the
+     * document of the attempt's page. Never throws: the abort must follow.
+     */
+    noteRouteAbort(request: Request): void;
     /** Resolves with what an action resolved with once the trace has the screen it left (`TraceFeed.screenAfterAction`); an action that failed leaves none. */
     private acted;
     /** Restarts the document while retaining this attempt's context and storage. */
@@ -362,6 +374,10 @@ export declare class PlaywrightSurface {
      * reported before either of those, so a position is among shown matches.
      */
     locate(expression: LocatorExpression, operation: OperationContext): Promise<readonly SemanticNode[]>;
+    /** The body of `locate`, inside its guard. */
+    private locateNow;
+    /** The page or frame an expression's frame selectors lead to, unresolved. */
+    private frameScope;
     /**
      * One action on a located or observed node. A `swipe` on the observation
      * root is the viewport swipe: a wheel gesture sized by the viewport, with no
@@ -424,8 +440,9 @@ export declare class PlaywrightSurface {
     restoreState(state: EngineState, operation: OperationContext): Promise<void>;
     /**
      * Captures one atomic semantic observation. Secure fields are masked in the
-     * page before the tree leaves the engine, and every node keeps a live
-     * element handle valid until the next observation replaces the generation.
+     * page before the tree leaves the engine, and every node stays reachable
+     * through its document's element list until the next observation replaces
+     * the generation; an action makes the node's handle on first use.
      *
      * With `options.pixels`, masked viewport pixels are captured alongside the
      * tree rather than after it, so the image and the node geometry describe the