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

package/dist/observation.js

@@ -5,6 +5,8 @@
 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
  * id the engine mints, stable across observations and navigations, so the
@@ -36,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;
     });
@@ -98,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();
@@ -109,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
@@ -118,6 +129,9 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
         // boundary nodes by design, so leaving them out is not truncation.
         if (!isOnSiteFrame(frame.url(), deps.site))
             continue;
+        // A frame whose navigation has not committed shows nothing yet.
+        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
         // capture) leaves the tree incomplete, and the snapshot must say so.
@@ -130,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;
@@ -170,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
@@ -252,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 };
@@ -309,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/observe.d.ts

@@ -8,9 +8,10 @@ import type { ObservationPixels, OperationContext, ViewportSize } from 'e2e/engi
  * frames an observation walked makes the masked set a superset of the observed
  * secure set - the direction that is safe. Shared by the observation pixels
  * and the artifact screenshot so both are redacted at the source by the same
- * rule.
+ * rule. A frame with no readable document shows nothing to mask, and probing
+ * it would wait for its navigation to commit.
  */
-export declare function secureFieldMasks(page: Page): Locator[];
+export declare function secureFieldMasks(page: Page): Promise<Locator[]>;
 /** Screenshot options that apply the secure-field masks; empty when there is no frame to mask. */
 export declare function maskOptions(masks: readonly Locator[]): Partial<{
     mask: Locator[];

package/dist/observe.js

@@ -1,6 +1,7 @@
 /** Masked pixel capture for an observation. */
 import { CaptureScope } from './capture-scope.js';
 import { CLOSED_SHADOW_SELECTOR_ENGINE } from './closed-shadow.js';
+import { readableFrames } from './frame-document.js';
 import { SECURE_FIELD_SELECTOR } from './read-node.js';
 import { withHiddenCaret } from './screenshot-caret.js';
 /**
@@ -19,11 +20,11 @@ const MASK_COLOR = '#000000';
  * frames an observation walked makes the masked set a superset of the observed
  * secure set - the direction that is safe. Shared by the observation pixels
  * and the artifact screenshot so both are redacted at the source by the same
- * rule.
+ * rule. A frame with no readable document shows nothing to mask, and probing
+ * it would wait for its navigation to commit.
  */
-export function secureFieldMasks(page) {
-    return page
-        .frames()
+export async function secureFieldMasks(page) {
+    return (await readableFrames(page.frames()))
         .flatMap((frame) => [
         frame.locator(SECURE_FIELD_SELECTOR),
         frame.locator(`${CLOSED_SHADOW_SELECTOR_ENGINE}=${SECURE_FIELD_SELECTOR}`),
@@ -49,7 +50,7 @@ export async function capturePixels(page, operation, viewport) {
     const deadline = Date.now() + operation.timeoutMs;
     const scope = new CaptureScope(deadline, operation.signal);
     return scope.run(async () => {
-        const masks = secureFieldMasks(page);
+        const masks = await scope.read(() => secureFieldMasks(page));
         // A frame that detaches mid-sweep contributes nothing to the count, which can
         // only push the observation toward withholding the image.
         const counts = await scope.read(() => Promise.allSettled(masks.map((mask) => mask.count())));

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/route-options.d.ts

@@ -13,11 +13,16 @@ export interface FulfillDecision {
     readonly headers: Record<string, string>;
     readonly contentType?: string;
     readonly json?: JsonValue;
-    readonly body?: string;
+    /** A `Buffer` for bytes, which Playwright sends unchanged. */
+    readonly body?: string | Buffer;
     /** Absolute; Playwright reads it and derives `Content-Type` from its extension when none is given. */
     readonly path?: string;
 }
-/** What `route.continue` hands Playwright once the overrides are validated; `headers` before the site's are merged in. */
+/**
+ * What `route.continue` hands Playwright once the overrides are validated;
+ * `headers` before the site's are merged in, a header set to `undefined`
+ * left out so the request goes without it.
+ */
 export interface ContinueDecision {
     readonly url?: string;
     readonly method?: string;

package/dist/route-options.js

@@ -7,6 +7,7 @@
  * the same `resolveUrl` `goto` uses.
  */
 import { statSync } from 'node:fs';
+import { types } from 'node:util';
 import { rejectUnknownOptions, TestError, validateJsonValue } from 'e2e/engine';
 import { headerProblem } from './protected-app.js';
 const FULFILL_KEYS = ['status', 'headers', 'contentType', 'json', 'body', 'path'];
@@ -35,7 +36,7 @@ export function parseFulfill(response, resolvePath) {
     const file = path === undefined ? undefined : resolvePath(requireString('route.fulfill', 'path', path, true));
     if (file !== undefined)
         requireFile(file);
-    const replied = requireHeaders('route.fulfill', headers) ?? {};
+    const replied = requireHeaders('route.fulfill', headers, 'response') ?? {};
     const type = contentType === undefined
         ? Object.entries(replied).find(([name]) => name.toLowerCase() === 'content-type')?.[1]
         : requireString('route.fulfill', 'contentType', contentType, true);
@@ -44,7 +45,7 @@ export function parseFulfill(response, resolvePath) {
         headers: replied,
         ...(type === undefined ? {} : { contentType: type }),
         ...(json === undefined ? {} : { json: json }),
-        ...(body === undefined ? {} : { body: requireString('route.fulfill', 'body', body, false) }),
+        ...(body === undefined ? {} : { body: requireBody(body) }),
         ...(file === undefined ? {} : { path: file }),
     };
 }
@@ -65,7 +66,7 @@ export function parseContinue(overrides, requestUrl, resolveUrl) {
             throw new TestError('INVALID_ARGUMENT', `route.continue url must keep the request's ${from} scheme; got ${to}`);
         }
     }
-    const replaced = requireHeaders('route.continue', headers);
+    const replaced = requireHeaders('route.continue', headers, 'request');
     return {
         ...(target === undefined ? {} : { url: target }),
         ...(method === undefined ? {} : { method: requireString('route.continue', 'method', method, true) }),
@@ -96,19 +97,42 @@ function requireString(api, key, value, nonempty) {
     }
     return value;
 }
-/** A header map the browser can send, or `undefined` when none was given. */
-function requireHeaders(api, value) {
+/**
+ * A header map the browser can send, or `undefined` when none was given. A
+ * request header set to `undefined` is dropped, so the request goes without
+ * it. A response `set-cookie` may join several cookies with `\n`, the way
+ * Playwright reports them, and each line is checked as its own value; any
+ * other line break is refused as header injection.
+ */
+function requireHeaders(api, value, kind) {
     if (value === undefined)
         return undefined;
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new TestError('INVALID_ARGUMENT', `${api} headers must map names to string values`);
     }
+    const headers = [];
     for (const [name, entry] of Object.entries(value)) {
-        const problem = headerProblem(name, entry);
-        if (problem !== undefined)
-            throw new TestError('INVALID_ARGUMENT', `${api} ${problem}`);
+        if (entry === undefined && kind === 'request')
+            continue;
+        if (typeof entry !== 'string')
+            throw new TestError('INVALID_ARGUMENT', `${api} ${headerProblem(name, entry)}`);
+        const lines = kind === 'response' && name.toLowerCase() === 'set-cookie' ? entry.split('\n') : [entry];
+        for (const line of lines) {
+            const problem = headerProblem(name, line);
+            if (problem !== undefined)
+                throw new TestError('INVALID_ARGUMENT', `${api} ${problem}`);
+        }
+        headers.push([name, entry]);
     }
-    return value;
+    return Object.fromEntries(headers);
+}
+/** A fulfill body: a string as is, or bytes as a `Buffer` over the same memory so Playwright sends them unchanged. */
+function requireBody(value) {
+    if (typeof value === 'string')
+        return value;
+    if (types.isUint8Array(value))
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    throw new TestError('INVALID_ARGUMENT', 'route.fulfill body must be a string, Buffer, or Uint8Array');
 }
 /** Rejects a path that does not name a regular file; synchronous so the check lands before the decision. */
 function requireFile(file) {

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
@@ -398,10 +414,13 @@ export declare class PlaywrightSurface {
      * the same chain; a frame-scoped `count` is 0 until that frame's document
      * has loaded, which is what makes `FRAME_NOT_FOUND` worth retrying. Returns
      * the innermost frame's content box in the top-level viewport, where its
-     * document's viewport starts: undefined for an expression in the main
-     * document, null for a frame with no box.
+     * document's viewport starts (undefined for an expression in the main
+     * document, null for a frame with no box), and
+     * whether a frame along the chain is hidden: a frame element's own `hidden`
+     * state, read in the document around it, so a cross-origin frame reads too.
+     * Every node in a hidden frame is hidden, and so are the frames under it.
      */
-    private frameBox;
+    private frameOf;
     /**
      * Reserves one artifact path under the attempt directory: a per-attempt
      * counter keeps names unique, the label keeps them readable.
@@ -421,15 +440,18 @@ 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
      * page as closely in time as two engine calls can.
      */
     observe(operation: OperationContext, options?: EngineObserveOptions): Promise<EngineSnapshot>;
-    /** Captures privately, then publishes only into the page and ref generation that requested it. */
+    /** Captures privately in the session's turn, then publishes only into the page and ref generation that requested it. */
     private captureObservation;
+    /** One observation that holds the session's turn. */
+    private captureInTurn;
 }
 export {};