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

package/README.md

@@ -146,4 +146,4 @@ ones the engine launches. Under pnpm, run the bin by name:
 
 ## Documentation
 
-Full documentation lives at [e2e.tester.army/docs](https://e2e.tester.army/docs).
+Full documentation lives at [e2e.com/docs](https://e2e.com/docs).

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.15.5-nightly-20261104030231"}
+{"version":"0.15.5"}

package/dist/actions.d.ts

@@ -8,7 +8,7 @@ import type { ConnectionBudget } from './operation-budget.ts';
  * platform's own actionability checks. `lookup` resolves the second ref of a
  * drag; everything else needs only the target.
  */
-export declare function dispatchLocatorAction(target: ActionTarget, action: LocatorAction, operation: ConnectionBudget, lookup: (ref: NodeRef) => ActionTarget): Promise<void>;
+export declare function dispatchLocatorAction(target: ActionTarget, action: LocatorAction, operation: ConnectionBudget, lookup: (ref: NodeRef) => Promise<ActionTarget>): Promise<void>;
 /**
  * Dispatches one pointer action at a viewport point with nothing resolved
  * behind it: no actionability wait, because there is no element to wait on,

package/dist/actions.js

@@ -34,13 +34,15 @@ async function setChecked(target, checked, operation) {
     try {
         if ((await element.isChecked()) === checked)
             return;
-        if (!checked && (await isRadio(element))) {
+        const radio = checked ? undefined : await radioKind(element);
+        if (radio === 'native') {
             throw new EngineError('NOT_ACTIONABLE', 'uncheck cannot clear a radio button; select another radio in its group', {
                 retryable: false,
             });
         }
         await element.click({ timeout: remaining() });
-        const unchanged = (detail = '') => new EngineError('NOT_ACTIONABLE', `${verb} clicked the control but its checked state did not change${detail}`, {
+        const hint = radio === 'aria' ? '; a radio usually clears only when another radio in its group is selected' : '';
+        const unchanged = (detail = '') => new EngineError('NOT_ACTIONABLE', `${verb} clicked the control but its checked state did not change${detail}${hint}`, {
             retryable: false,
         });
         let firstRead = true;
@@ -70,9 +72,17 @@ async function setChecked(target, checked, operation) {
             void element.dispose().catch(() => undefined);
     }
 }
-/** Whether a checkable element is a radio, which a click can select but never clear. */
-function isRadio(element) {
-    return element.evaluate((node) => (node instanceof HTMLInputElement && node.type === 'radio') || node.getAttribute('role') === 'radio');
+/**
+ * Which kind of radio a checkable element is, if any. A native radio can be
+ * selected but never cleared by a click. An ARIA radio is clicked like any
+ * control, as Playwright does: its script decides what a click does.
+ */
+function radioKind(element) {
+    return element.evaluate((node) => {
+        if (node instanceof HTMLInputElement && node.type === 'radio')
+            return 'native';
+        return node.getAttribute('role') === 'radio' ? 'aria' : undefined;
+    });
 }
 /**
  * Attaches files to a file input, or to a control that opens a native file
@@ -190,7 +200,8 @@ export async function dispatchLocatorAction(target, action, operation, lookup) {
             await uploadFiles(target, action.paths, operation);
             return;
         case 'dragTo': {
-            const other = lookup(action.target);
+            const other = await lookup(action.target);
+            operation.signal.throwIfAborted();
             // Playwright's own drag when both sides are locators: it waits for
             // actionability on each and reports better failures than a pointer
             // sequence can. Anything else - an observed reference on either side -

package/dist/attempt-session.d.ts

@@ -41,6 +41,8 @@ export declare class AttemptSession {
     private state;
     private generation;
     private observed;
+    /** Settles when the latest observation in line has finished; never rejects. */
+    private observing;
     /** Until the attempt's first page opens: a persistent browser's own first tab can serve as that page. */
     private firstPage;
     private requestedViewport;
@@ -56,6 +58,12 @@ export declare class AttemptSession {
     check(token: object): void;
     /** An observation commits its references and freshness together against the same generation. */
     observedGeneration(token: object): void;
+    /**
+     * Runs one observation after every earlier one has finished, so each
+     * publishes its references in turn instead of the later one superseding a
+     * capture still in flight. Time spent waiting comes out of the operation's.
+     */
+    observeInTurn<T>(operation: OperationContext, capture: (operation: OperationContext) => Promise<T>): Promise<T>;
     /** Observation-backed pointer and keyboard input needs evidence captured after recovery. */
     requireObservation(): void;
     /** Reads the only published binding. Pending work never replaces it halfway through setup. */

package/dist/attempt-session.js

@@ -13,6 +13,8 @@ export class AttemptSession {
     state = { kind: 'empty' };
     generation = {};
     observed = true;
+    /** Settles when the latest observation in line has finished; never rejects. */
+    observing = Promise.resolve();
     /** Until the attempt's first page opens: a persistent browser's own first tab can serve as that page. */
     firstPage = true;
     requestedViewport;
@@ -41,6 +43,25 @@ export class AttemptSession {
         this.check(token);
         this.observed = true;
     }
+    /**
+     * Runs one observation after every earlier one has finished, so each
+     * publishes its references in turn instead of the later one superseding a
+     * capture still in flight. Time spent waiting comes out of the operation's.
+     */
+    async observeInTurn(operation, capture) {
+        const queued = Date.now();
+        const before = this.observing;
+        let finished;
+        const mine = new Promise((resolve) => { finished = resolve; });
+        this.observing = before.then(() => mine);
+        try {
+            await raceAbort(before, operation.signal, 'observe');
+            return await capture({ ...operation, timeoutMs: Math.max(1, operation.timeoutMs - (Date.now() - queued)) });
+        }
+        finally {
+            finished();
+        }
+    }
     /** Observation-backed pointer and keyboard input needs evidence captured after recovery. */
     requireObservation() {
         if (!this.observed)

package/dist/browser-connection.d.ts

@@ -1,6 +1,5 @@
 /** Shares one browser process connection across a worker's attempts. */
-import type { Browser } from 'playwright-core';
-import { chromium } from 'playwright-core';
+import type { Browser, BrowserType } from 'playwright-core';
 /** Every browser the engine launches, in the order the CLI lists them. */
 export declare const BROWSER_NAMES: readonly ['chromium', 'firefox', 'webkit'];
 export type BrowserName = (typeof BROWSER_NAMES)[number];
@@ -27,7 +26,7 @@ export declare class BrowserConnection {
     dispose(): Promise<void>;
 }
 /** Maps a browser name to its Playwright BrowserType. */
-export declare function browserType(name: BrowserName): typeof chromium;
+export declare function browserType(name: BrowserName): Promise<BrowserType>;
 /**
  * Attaches to a remote browser over the Chrome DevTools Protocol. CDP attach
  * is chromium-only; a hosted-browser engine (a per-run cloud session) resolves

package/dist/browser-connection.js

@@ -1,6 +1,11 @@
 /** Shares one browser process connection across a worker's attempts. */
-import { chromium, firefox, selectors, webkit } from 'playwright-core';
 import { SELECTOR_ENGINES } from './selector-engines.js';
+/**
+ * Playwright, imported the first time a browser is looked up, launched, or
+ * attached to. A process that only reads the config (`e2e list`, a run whose
+ * browsers come from a provider) never loads it.
+ */
+const loadPlaywright = () => import('playwright-core');
 /** Every browser the engine launches, in the order the CLI lists them. */
 export const BROWSER_NAMES = ['chromium', 'firefox', 'webkit'];
 /** Whether `name` is a browser the engine launches. */
@@ -44,8 +49,12 @@ export class BrowserConnection {
                 return this.acquire(name, headed, timeoutMs, connect);
             this.pending = undefined;
         }
-        await registerSelectorEngines();
-        const launching = connect !== undefined ? connect() : browserType(name).launch({ headless: !headed, timeout: timeoutMs, ...RUNNER_OWNS_SIGNALS });
+        // Set before anything awaits: the first call loads Playwright, and a `dispose`
+        // that arrives meanwhile must close the browser this launch produces, while a
+        // second caller waits for it instead of launching another.
+        const launching = registerSelectorEngines().then(() => connect !== undefined
+            ? connect()
+            : browserType(name).then((type) => type.launch({ headless: !headed, timeout: timeoutMs, ...RUNNER_OWNS_SIGNALS })));
         this.pending = launching;
         try {
             return await launching;
@@ -69,7 +78,8 @@ export class BrowserConnection {
     }
 }
 /** Maps a browser name to its Playwright BrowserType. */
-export function browserType(name) {
+export async function browserType(name) {
+    const { chromium, firefox, webkit } = await loadPlaywright();
     if (name === 'firefox')
         return firefox;
     if (name === 'webkit')
@@ -84,6 +94,7 @@ export function browserType(name) {
  */
 export async function connectCdp(endpoint, timeoutMs) {
     await registerSelectorEngines();
+    const { chromium } = await loadPlaywright();
     return chromium.connectOverCDP(endpoint, { timeout: timeoutMs });
 }
 /** Registration is process-wide and rejected twice; one shared promise serves every connection. */
@@ -97,6 +108,8 @@ function registerSelectorEngines() {
     // Playwright serializes a function argument with `toString()` and invokes it
     // in the page, so each factory is materialized from its source here to keep
     // the in-page code self-contained, the same way the reader is assembled.
-    selectorEngines ??= Promise.all(SELECTOR_ENGINES.map(({ name, source }) => selectors.register(name, new Function(`return ${source};`)()))).then(() => undefined);
+    selectorEngines ??= loadPlaywright()
+        .then(({ selectors }) => Promise.all(SELECTOR_ENGINES.map(({ name, source }) => selectors.register(name, new Function(`return ${source};`)()))))
+        .then(() => undefined);
     return selectorEngines;
 }

package/dist/browser.d.ts

@@ -23,6 +23,7 @@ import type { PlaywrightSurface } from './surface.ts';
  */
 export type RouteFulfillResponse = {
     status?: number;
+    /** Response headers; `set-cookie` may join several cookies with `\n`, as `route.fetch()` reports them. */
     headers?: Record<string, string>;
     /** Sets the `Content-Type` response header. */
     contentType?: string;
@@ -31,7 +32,7 @@ export type RouteFulfillResponse = {
     body?: never;
     path?: never;
 } | {
-    body: string;
+    body: string | Uint8Array;
     json?: never;
     path?: never;
 } | {
@@ -49,8 +50,8 @@ export interface RouteContinueOverrides {
     url?: string;
     /** Request method. */
     method?: string;
-    /** Replaces every request header; the configured `headers` for the app's site are added on top. */
-    headers?: Record<string, string>;
+    /** Replaces every request header; `undefined` drops one, and the configured `headers` for the app's site are added on top. */
+    headers?: Record<string, string | undefined>;
     /** Request body. */
     postData?: string;
 }
@@ -78,8 +79,10 @@ export interface WebResponse {
     readonly url: string;
     /** HTTP status. */
     readonly status: number;
-    /** Response headers, lower-cased names. */
+    /** Response headers, lower-cased names; `route.fetch()` joins several `set-cookie` values with `\n`, `waitForResponse` leaves cookie headers out. */
     readonly headers: Readonly<Record<string, string>>;
+    /** Waits for the body and returns its bytes; rejects with `ACTION_FAILED` when the body could not be read. */
+    body(): Promise<Buffer>;
     /** Waits for the body and parses it as JSON; rejects with `ACTION_FAILED` when the body could not be read. */
     json<T = unknown>(): Promise<T>;
     /** Waits for the body and reads it as text; rejects with `ACTION_FAILED` when the body could not be read. */

package/dist/browser.js

@@ -11,11 +11,11 @@
  * never re-implemented here: `context.app.resolveUrl` is the one place that
  * says which URLs a test may open.
  */
-import { ConfigurationError, Deadline, describePattern, EngineError, matchesText, obj, pollCondition, raceAbort, rejectUnknownOptions, TestError, toTextPattern, urlMatches, validateJsonValue, withTimeout, } from 'e2e/engine';
+import { ConfigurationError, Deadline, describePattern, EngineError, matchesText, obj, pollCondition, raceAbort, stepTimeout, rejectUnknownOptions, TestError, toTextPattern, urlMatches, validateJsonValue, withTimeout, } from 'e2e/engine';
 import { classifyInputError } from './actions.js';
 import { saveDownloadsTo, saveFromBrowser, saveLocally } from './downloads.js';
-import { isTestErrorCode, message as causeMessage, translatePwError } from './support.js';
-import { compileEvaluation, pageFunctionSource } from './evaluation.js';
+import { isTestErrorCode, message as causeMessage, pageScriptFailure, translatePwError } from './support.js';
+import { compileEvaluation, decodeEvaluation, pageFunctionSource } from './evaluation.js';
 import { initScriptLabel, testInitScriptSource } from './init-scripts.js';
 import { MEDIA_KEYS, mediaLabel, mediaProblem } from './media.js';
 import { lowercaseNames } from './protected-app.js';
@@ -23,7 +23,7 @@ import { parseContinue, parseFulfill, requireNoArguments } from './route-options
 import { routePatternMatches, routePatternsEqual } from './route-pattern.js';
 /**
  * Reads the body once the response is known and keeps the outcome: a body
- * that arrived decodes to text on every call, a body the browser could not
+ * that arrived returns a copy of its bytes on every call, a body the browser could not
  * read rejects every call with `ACTION_FAILED` naming the cause. Swallowing
  * that failure would hand the test an empty string the server never sent,
  * indistinguishable from a real empty body. `failure` names the reason the
@@ -34,14 +34,27 @@ import { routePatternMatches, routePatternsEqual } from './route-pattern.js';
  */
 async function readResponseBody(api, body, failure = () => undefined) {
     try {
-        const text = new TextDecoder().decode(await body());
-        return () => Promise.resolve(text);
+        const bytes = await body();
+        return () => Promise.resolve(Buffer.from(bytes));
     }
     catch (cause) {
         const error = new TestError('ACTION_FAILED', `${api}: response body could not be read: ${failure() ?? causeMessage(cause)}`);
         return () => Promise.reject(error);
     }
 }
+/** The `WebResponse` over a Playwright response's metadata and a reader for its body bytes. */
+function webResponse(response, body) {
+    const text = async () => new TextDecoder().decode(await body());
+    return {
+        url: response.url(),
+        status: response.status(),
+        headers: response.headers(),
+        body,
+        // oxlint-disable-next-line e2e/no-unchecked-json -- public API: the caller names T, unknown by default
+        json: async () => JSON.parse(await text()),
+        text,
+    };
+}
 /**
  * Runs `trigger` once and saves the first `count` downloads it starts, in
  * start order, each attached as a `download` artifact. One budget bounds the
@@ -49,10 +62,7 @@ async function readResponseBody(api, body, failure = () => undefined) {
  * downloads are canceled and nothing is attached after it.
  */
 async function collectDownloads(surface, context, trigger, count, timeout, api) {
-    if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0)) {
-        throw new TestError('INVALID_ARGUMENT', `${api} timeout must be positive and finite`);
-    }
-    const operation = context.operation(timeout);
+    const operation = context.operation(stepTimeout(timeout, api));
     const waitMs = operation.timeoutMs;
     const deadline = new Deadline(waitMs);
     const scope = new AbortController();
@@ -157,12 +167,12 @@ export function createBrowserFixture(surface, context) {
      * harness gives `app.open` - a document load is not an action and must not
      * be cut at the action timeout.
      */
-    const navigation = (options, run) => {
-        const operation = context.operation(options?.timeout ?? context.timeouts.test);
+    const navigation = (api, options, run) => {
+        const operation = context.operation(stepTimeout(options?.timeout, api) ?? context.timeouts.test);
         return surface.guard(operation, 'navigation', run);
     };
     /** An assertion-style budget: the given timeout or the assertion timeout, clamped to the test. */
-    const deadlineFor = (timeout) => new Deadline(context.operation(timeout ?? context.timeouts.assertion).timeoutMs);
+    const deadlineFor = (timeout, api) => new Deadline(context.operation(stepTimeout(timeout, api) ?? context.timeouts.assertion).timeoutMs);
     /** The page URL, read within the action timeout or, for a matcher poll, within the poll's deadline. */
     const currentUrl = (deadline) => surface.guard(context.operation(deadline?.remaining()), 'url', async () => surface.requirePage().url());
     /** The page title, read within the action timeout or, for a matcher poll, within the poll's deadline. */
@@ -171,7 +181,7 @@ export function createBrowserFixture(surface, context) {
     const browser = {
         goto(url, options) {
             const resolved = context.app.resolveUrl(url);
-            return navigation(options, (operation) => surface.navigating(async () => {
+            return navigation('browser.goto', options, (operation) => surface.navigating(async () => {
                 const page = await surface.ensurePage();
                 await page.goto(resolved, {
                     waitUntil: options?.waitUntil ?? 'load',
@@ -179,13 +189,13 @@ export function createBrowserFixture(surface, context) {
                 });
             }));
         },
-        reload: (options) => navigation(options, (operation) => surface.navigating(async () => {
+        reload: (options) => navigation('browser.reload', options, (operation) => surface.navigating(async () => {
             await surface.requirePage().reload({ waitUntil: 'load', timeout: operation.timeoutMs });
         })),
-        back: (options) => navigation(options, (operation) => surface.navigating(async () => {
+        back: (options) => navigation('browser.back', options, (operation) => surface.navigating(async () => {
             await surface.requirePage().goBack({ waitUntil: 'load', timeout: operation.timeoutMs });
         })),
-        forward: (options) => navigation(options, (operation) => surface.navigating(async () => {
+        forward: (options) => navigation('browser.forward', options, (operation) => surface.navigating(async () => {
             await surface.requirePage().goForward({ waitUntil: 'load', timeout: operation.timeoutMs });
         })),
         url: () => currentUrl(),
@@ -203,11 +213,19 @@ export function createBrowserFixture(surface, context) {
             const evaluate = compileEvaluation(source, arg !== undefined);
             // JSON safety is checked above; Playwright's recursive argument type cannot expand JsonValue.
             const input = arg;
-            const result = await surface.guard(context.operation(), 'evaluate', () => surface.requirePage().evaluate(evaluate, input));
-            if (!result.ok)
-                throw new TestError('EVALUATE_FAILED', result.message);
-            validateJsonValue(result.value, 'evaluate result');
-            return result.value;
+            // A handle, not a value: the boundary resolves to a string, which Playwright
+            // keeps out of its in-page serializer when it is taken back from a handle.
+            const report = await surface.guard(context.operation(), 'evaluate', async (operation) => {
+                const page = surface.requirePage();
+                try {
+                    const handle = await page.evaluateHandle(evaluate, input);
+                    return await handle.jsonValue();
+                }
+                catch (cause) {
+                    throw (await pageScriptFailure(page, cause, 'evaluate', operation.timeoutMs)) ?? cause;
+                }
+            });
+            return decodeEvaluation(report);
         },
         async addInitScript(script, ...rest) {
             const source = await testInitScriptSource(script, rest.length === 0 ? undefined : { arg: rest[0] }, (file) => surface.projectPath(file));
@@ -221,6 +239,12 @@ export function createBrowserFixture(surface, context) {
             // is latched on the surface and fails the next step with its real cause.
             const handleRoute = async (route) => {
                 let decided = false;
+                const request = route.request();
+                // Noted before the abort, so a navigation it fails reads as aborted by the test.
+                const abort = async () => {
+                    surface.noteRouteAbort(request);
+                    await route.abort();
+                };
                 const decide = (name) => {
                     if (decided) {
                         throw new TestError('ACTION_FAILED', `route handler already decided; ${name} called twice`);
@@ -236,11 +260,10 @@ export function createBrowserFixture(surface, context) {
                         await act();
                     }
                     catch (cause) {
-                        await route.abort().catch(() => undefined);
+                        await abort().catch(() => undefined);
                         throw cause;
                     }
                 };
-                const request = route.request();
                 const postData = request.postData();
                 const publicRoute = {
                     request: {
@@ -259,15 +282,7 @@ export function createBrowserFixture(surface, context) {
                                 maxRedirects: 0,
                             });
                             try {
-                                const text = await readResponseBody('route.fetch', () => response.body());
-                                return {
-                                    url: response.url(),
-                                    status: response.status(),
-                                    headers: response.headers(),
-                                    // oxlint-disable-next-line e2e/no-unchecked-json -- public API: the caller names T, unknown by default
-                                    json: async () => JSON.parse(await text()),
-                                    text,
-                                };
+                                return webResponse(response, await readResponseBody('route.fetch', () => response.body()));
                             }
                             finally {
                                 await response.dispose();
@@ -301,7 +316,7 @@ export function createBrowserFixture(surface, context) {
                     },
                     abort: async (...args) => {
                         requireNoArguments('route.abort', args);
-                        await decideWith('abort', () => route.abort());
+                        await decideWith('abort', abort);
                     },
                 };
                 try {
@@ -315,7 +330,7 @@ export function createBrowserFixture(surface, context) {
                         ? cause
                         : new TestError('ACTION_FAILED', `route handler failed: ${causeMessage(cause)}`));
                     if (!decided)
-                        await route.abort().catch(() => undefined);
+                        await abort().catch(() => undefined);
                 }
             };
             // Tracked so the attempt end waits for a handler still running and
@@ -339,28 +354,21 @@ export function createBrowserFixture(surface, context) {
         },
         waitForResponse(pattern, options) {
             const wirePattern = toTextPattern(pattern);
-            const operation = context.operation(options?.timeout);
+            const operation = context.operation(stepTimeout(options?.timeout, 'browser.waitForResponse'));
             return surface.guard(operation, 'waitForResponse', async (currentOperation) => {
                 const page = await surface.ensurePage();
                 const response = await page.waitForResponse((candidate) => routePatternMatches(wirePattern, candidate.url()), { timeout: currentOperation.timeoutMs });
                 // Started now, while the browser still holds the body, and awaited
-                // only by `text` and `json` on a budget of their own: the timeout
+                // only by the body readers on a budget of their own: the timeout
                 // bounds the match, never a body still streaming in behind headers
                 // that already arrived.
                 const body = readResponseBody('waitForResponse', () => response.body(), () => response.request().failure()?.errorText);
-                const text = async () => {
+                const read = async () => {
                     const { signal, timeoutMs } = context.operation();
-                    const read = await raceAbort(withTimeout(body, timeoutMs, () => new TestError('ACTION_FAILED', `waitForResponse: response body did not finish within ${timeoutMs}ms`)), signal, 'waitForResponse body');
-                    return read();
-                };
-                return {
-                    url: response.url(),
-                    status: response.status(),
-                    headers: response.headers(),
-                    // oxlint-disable-next-line e2e/no-unchecked-json -- public API: the caller names T, unknown by default
-                    json: async () => JSON.parse(await text()),
-                    text,
+                    const bytes = await raceAbort(withTimeout(body, timeoutMs, () => new TestError('ACTION_FAILED', `waitForResponse: response body did not finish within ${timeoutMs}ms`)), signal, 'waitForResponse body');
+                    return bytes();
                 };
+                return webResponse(response, read);
             });
         },
         cookies: () => surface.guard(context.operation(), 'cookies', async () => {
@@ -477,13 +485,13 @@ export function createBrowserFixture(surface, context) {
         forward: navigationCall,
         url: action,
         title: action,
-        waitForURL: { ...navigationCall, verifies: true, label: (url) => String(url) },
+        waitForURL: { ...navigationCall, verifies: true, label: patternLabel },
         evaluate: action,
         addInitScript: { ...action, label: (script) => initScriptLabel(script) },
-        route: { ...action, label: (pattern) => String(pattern) },
-        unroute: { ...action, label: (pattern) => String(pattern) },
+        route: { ...action, label: patternLabel },
+        unroute: { ...action, label: patternLabel },
         unrouteAll: action,
-        waitForResponse: { ...action, timeout: (_pattern, options) => options?.timeout, label: (pattern) => String(pattern) },
+        waitForResponse: { ...action, timeout: (_pattern, options) => options?.timeout, label: patternLabel },
         cookies: action,
         setCookies: action,
         clearCookies: action,
@@ -504,7 +512,7 @@ export function createBrowserFixture(surface, context) {
  */
 function createBrowserExpectation(deps, negated = false) {
     const poll = async (api, label, read, timeout) => {
-        const deadline = deps.deadlineFor(timeout);
+        const deadline = deps.deadlineFor(timeout, api);
         // pollCondition calls onTimeout only after a read completed, so a sample is always there.
         let last;
         await pollCondition({
@@ -586,6 +594,10 @@ function requireSelector(method, selector) {
     }
     return selector;
 }
+/** A URL pattern as steps and errors name it: a string quoted, a RegExp as its literal. */
+function patternLabel(pattern) {
+    return typeof pattern === 'string' ? JSON.stringify(pattern) : String(pattern);
+}
 /**
  * The scope for the innermost of `frames` (outermost first). Every query and
  * both escape hatches compile through the same `frame` chain, so a `locator`

package/dist/element-list.d.ts

@@ -0,0 +1,28 @@
+/** The elements one document's observation walk read, kept behind a single in-page array. */
+import type { ElementHandle, JSHandle } from 'playwright-core';
+/**
+ * One handle to the in-page array the reader filled, and the element handles
+ * made from it on demand.
+ *
+ * An observation can list thousands of nodes and an action touches a few, so a
+ * handle per node would cost a round trip to create and another to release for
+ * every node, every observation. The array keeps each element alive, which is
+ * what a handle did: a ref names the element the walk read, never whatever sits
+ * at that position now. Disposing the list releases the array and every handle
+ * made from it.
+ */
+export declare class ElementList {
+    readonly handle: JSHandle;
+    private readonly resolved;
+    private disposed;
+    constructor(handle: JSHandle);
+    /**
+     * A new handle to one element of the walk. The caller owns it and disposes
+     * it; a missing element, or a document replaced since the walk, is a stale node.
+     */
+    fetch(index: number): Promise<ElementHandle<Element>>;
+    /** The element of one node, made once and kept until the list is disposed. */
+    at(index: number): Promise<ElementHandle<Element>>;
+    /** Releases the array and every element made from it; safe to call again. */
+    dispose(): void;
+}

package/dist/element-list.js

@@ -0,0 +1,73 @@
+/** The elements one document's observation walk read, kept behind a single in-page array. */
+import { EngineError } from 'e2e/engine';
+import { navigationStaleOr } from './support.js';
+/**
+ * One handle to the in-page array the reader filled, and the element handles
+ * made from it on demand.
+ *
+ * An observation can list thousands of nodes and an action touches a few, so a
+ * handle per node would cost a round trip to create and another to release for
+ * every node, every observation. The array keeps each element alive, which is
+ * what a handle did: a ref names the element the walk read, never whatever sits
+ * at that position now. Disposing the list releases the array and every handle
+ * made from it.
+ */
+export class ElementList {
+    handle;
+    resolved = new Map();
+    disposed = false;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /**
+     * A new handle to one element of the walk. The caller owns it and disposes
+     * it; a missing element, or a document replaced since the walk, is a stale node.
+     */
+    async fetch(index) {
+        const handle = await this.handle
+            .evaluateHandle((elements, at) => elements[at], index)
+            .catch((cause) => {
+            throw navigationStaleOr(cause, 'resolve observed node');
+        });
+        const element = handle.asElement();
+        if (element === null) {
+            void handle.dispose().catch(() => undefined);
+            throw new EngineError('NODE_STALE', `observation node ${String(index)} lost its element`, { retryable: true });
+        }
+        return element;
+    }
+    /** The element of one node, made once and kept until the list is disposed. */
+    at(index) {
+        if (this.disposed)
+            return Promise.reject(staleList());
+        let element = this.resolved.get(index);
+        if (element === undefined) {
+            element = this.fetch(index).then((made) => {
+                if (!this.disposed)
+                    return made;
+                void made.dispose().catch(() => undefined);
+                throw staleList();
+            }, (cause) => {
+                this.resolved.delete(index);
+                throw this.disposed ? staleList() : cause;
+            });
+            this.resolved.set(index, element);
+        }
+        return element;
+    }
+    /** Releases the array and every element made from it; safe to call again. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const element of this.resolved.values()) {
+            void element.then((made) => made.dispose()).catch(() => undefined);
+        }
+        this.resolved.clear();
+        void this.handle.dispose().catch(() => undefined);
+    }
+}
+/** The observation the list belonged to was replaced or cleared, so its refs no longer bind. */
+function staleList() {
+    return new EngineError('NODE_STALE', 'observation node references were released', { retryable: true });
+}