@e2e-dev/web 0.11.0-canary-20260928184528

package/dist/cdp-recovery.js

@@ -0,0 +1,84 @@
+import { EngineError } from 'e2e/engine';
+import { connectCdp } from './browser-connection.js';
+import { registerCdpSelectors, requireCdpShadowTracking } from './cdp-selectors.js';
+import { connectionAbort } from './operation-budget.js';
+/** A failed reconnect must never quietly provision another session. */
+export function recoveryFailed(detail) {
+    return new EngineError('ENGINE_FAILURE', `CDP recovery failed: ${detail}`, { retryable: false });
+}
+/** Reads protocol identity, independent of URL, document contents, and tab order. */
+export async function targetIdentity(page) {
+    const session = await page.context().newCDPSession(page);
+    try {
+        return (await session.send('Target.getTargetInfo')).targetInfo;
+    }
+    finally {
+        await session.detach().catch(() => undefined);
+    }
+}
+/** Owns an uncommitted connection until its identity is proven; aborted and late connections detach. */
+export async function attachPersistent(resolve, budget, previous) {
+    const { signal } = budget;
+    const deadline = Date.now() + budget.timeoutMs;
+    const check = () => { if (signal.aborted)
+        throw connectionAbort(signal, 'CDP connection'); };
+    check();
+    const endpoint = await resolve(signal);
+    check();
+    if (typeof endpoint !== 'string' || endpoint.trim() === '')
+        throw recoveryFailed('the endpoint is empty');
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new EngineError('OPERATION_TIMEOUT', 'CDP connection timed out', { retryable: false });
+    const browser = await connectCdp(endpoint, remaining);
+    const detach = () => { void browser.close().catch(() => undefined); };
+    signal.addEventListener('abort', detach, { once: true });
+    try {
+        check();
+        const session = await browser.newBrowserCDPSession();
+        let contextId;
+        try {
+            const contexts = await session.send('Target.getBrowserContexts');
+            if (contexts.browserContextIds.length > 0) {
+                throw recoveryFailed('the remote browser must contain only its dedicated default context');
+            }
+            contextId = contexts.defaultBrowserContextId;
+        }
+        finally {
+            await session.detach().catch(() => undefined);
+        }
+        check();
+        const context = browser.contexts()[0];
+        if (context === undefined)
+            throw recoveryFailed('the default context is missing');
+        if (contextId === undefined || contextId === '')
+            throw recoveryFailed('the default context identity is unavailable');
+        if (previous !== undefined && contextId !== previous.contextId) {
+            throw recoveryFailed('reconnectEndpoint returned a different browser');
+        }
+        await registerCdpSelectors(context, { signal, timeoutMs: deadline - Date.now() });
+        check();
+        if (previous?.target === undefined)
+            return { browser, context, page: null, identity: { contextId } };
+        for (const page of context.pages()) {
+            const target = await targetIdentity(page);
+            check();
+            if (target.targetId !== previous.target.targetId)
+                continue;
+            if (target.browserContextId !== previous.target.browserContextId) {
+                throw recoveryFailed('the original page belongs to a different context');
+            }
+            await requireCdpShadowTracking(page, { signal, timeoutMs: deadline - Date.now() });
+            return { browser, context, page, identity: { contextId, target } };
+        }
+        throw recoveryFailed('the original page no longer exists');
+    }
+    catch (cause) {
+        await browser.close().catch(() => undefined);
+        throw cause;
+    }
+    finally {
+        signal.removeEventListener('abort', detach);
+    }
+}
+//# sourceMappingURL=cdp-recovery.js.map

package/dist/cdp-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-recovery.js","sourceRoot":"","sources":["../src/cdp-recovery.ts"],"names":[],"mappings":"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"}

package/dist/cdp-selectors.d.ts

@@ -0,0 +1,15 @@
+/** Registers the engine's selector engines in a CDP default context; every locator and secure-field mask needs them. */
+import type { BrowserContext, Page } from 'playwright';
+import { type ConnectionBudget } from './operation-budget.ts';
+/**
+ * Playwright 1.63 seeds custom selectors only in newly created contexts, not
+ * the persistent context returned by connectOverCDP. Its public register API
+ * rejects an already registered name before reaching that context. Use the
+ * same context channel as selectors.register, without allocating global names
+ * on every reconnect. Missing channel support must fail the connection: every
+ * locator resolves through these engines and every masked capture relies on them.
+ */
+export declare function registerCdpSelectors(context: BrowserContext, budget: ConnectionBudget): Promise<void>;
+/** Existing closed roots cannot be recovered if their document loaded without the tracking hook. */
+export declare function requireCdpShadowTracking(page: Page, budget: ConnectionBudget): Promise<void>;
+//# sourceMappingURL=cdp-selectors.d.ts.map

package/dist/cdp-selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-selectors.d.ts","sourceRoot":"","sources":["../src/cdp-selectors.ts"],"names":[],"mappings":"AAAA,wHAAwH;AAExH,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAW/E;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB3G;AAED,oGAAoG;AACpG,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASlG"}

package/dist/cdp-selectors.js

@@ -0,0 +1,52 @@
+/** Registers the engine's selector engines in a CDP default context; every locator and secure-field mask needs them. */
+import { EngineError } from 'e2e/engine';
+import { connectionAbort } from './operation-budget.js';
+import { CLOSED_SHADOW_ROOTS_KEY } from './closed-shadow.js';
+import { SELECTOR_ENGINES } from './selector-engines.js';
+/**
+ * Playwright 1.63 seeds custom selectors only in newly created contexts, not
+ * the persistent context returned by connectOverCDP. Its public register API
+ * rejects an already registered name before reaching that context. Use the
+ * same context channel as selectors.register, without allocating global names
+ * on every reconnect. Missing channel support must fail the connection: every
+ * locator resolves through these engines and every masked capture relies on them.
+ */
+export async function registerCdpSelectors(context, budget) {
+    if (budget.signal.aborted)
+        throw connectionAbort(budget.signal, 'CDP selector registration');
+    if (budget.timeoutMs <= 0) {
+        throw new EngineError('OPERATION_TIMEOUT', 'CDP selector registration timed out', { retryable: false });
+    }
+    const channel = Reflect.get(context, '_channel');
+    const register = channel !== null && typeof channel === 'object' ? Reflect.get(channel, 'registerSelectorEngine') : undefined;
+    if (typeof register !== 'function') {
+        throw new EngineError('UNSUPPORTED_CAPABILITY', 'this Playwright version cannot register selector engines in the CDP context; locators and secure-field masks need them', { retryable: false });
+    }
+    for (const { name, source } of SELECTOR_ENGINES) {
+        try {
+            await channel.registerSelectorEngine({ selectorEngine: {
+                    name,
+                    source: `(${source})(undefined)`,
+                    contentScript: false,
+                } }, { timeout: budget.timeoutMs, signal: budget.signal });
+        }
+        catch (cause) {
+            // A version that seeds CDP contexts already has our process-wide registration.
+            const duplicate = `"${name}" selector engine has been already registered`;
+            if (!(cause instanceof Error) || !cause.message.endsWith(duplicate))
+                throw cause;
+        }
+    }
+}
+/** Existing closed roots cannot be recovered if their document loaded without the tracking hook. */
+export async function requireCdpShadowTracking(page, budget) {
+    if (budget.signal.aborted)
+        throw connectionAbort(budget.signal, 'CDP tracking verification');
+    const tracked = await Promise.all(page.frames().map((frame) => frame.evaluate((key) => Reflect.get(globalThis, Symbol.for(key)) instanceof WeakMap, CLOSED_SHADOW_ROOTS_KEY)));
+    if (budget.signal.aborted)
+        throw connectionAbort(budget.signal, 'CDP tracking verification');
+    if (tracked.some((present) => !present)) {
+        throw new EngineError('ENGINE_FAILURE', 'CDP recovery failed: closed shadow root tracking is unavailable after a document changed while disconnected; locators and secure-field masks need it', { retryable: false });
+    }
+}
+//# sourceMappingURL=cdp-selectors.js.map

package/dist/cdp-selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-selectors.js","sourceRoot":"","sources":["../src/cdp-selectors.ts"],"names":[],"mappings":"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"}

package/dist/closed-shadow.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Closed shadow roots, kept reachable for the reader, the locators, and the
+ * screenshot masks: the context init script that records them, and the two
+ * Playwright selector engines that search them. Both engines are page code as
+ * source strings; the engine list is what the browser connection and the CDP
+ * context register.
+ */
+/**
+ * Where the init script below records closed shadow roots, keyed by host, and
+ * where the in-page reader looks for them. The reader is serialized into the
+ * page and cannot import this constant, so the literal is repeated inside it;
+ * the two must agree, like `SECURE_FIELD_SELECTOR` on both sides of masking.
+ *
+ * The record is a `WeakMap` from host to root with one own property beside
+ * the map: `count`, the number of closed roots the document has attached. It
+ * lets a selector engine answer for a document without closed roots without
+ * walking it.
+ */
+export declare const CLOSED_SHADOW_ROOTS_KEY = "e2e.closedShadowRoots";
+/**
+ * Context init script that keeps every closed shadow root reachable for the
+ * reader. A closed root hides its tree from `element.shadowRoot`, so a checkout
+ * button a third-party widget renders that way is on screen for a person yet
+ * absent from the walk. `attachShadow` is the one way a script creates such a
+ * root; wrapping it before any page script runs records host and root in a
+ * WeakMap under a well-known symbol, which the reader consults where it reads
+ * `shadowRoot`, and counts the roots attached so far. The map is keyed by the
+ * host element and never enumerated, so it holds nothing alive and changes
+ * nothing the page can observe about the root itself. Declarative
+ * `<template shadowrootmode="closed">` roots are parsed rather than attached
+ * and stay out of reach.
+ */
+export declare const CLOSED_SHADOW_ROOTS_INIT_SCRIPT: string;
+/** Playwright selector engine name; `e2e-closed=<css>` matches inside recorded closed shadow roots. */
+export declare const CLOSED_SHADOW_SELECTOR_ENGINE = "e2e-closed";
+/**
+ * Playwright selector engine name for the roots a semantic query searches.
+ * `e2e-roots=` (an empty body) resolves to the query root followed by every
+ * closed shadow root recorded under it, so the Playwright query part that
+ * follows (`internal:role`, `internal:text`, `internal:label`, ...) runs its
+ * own matching in each of them; `e2e-roots=<css>` resolves to the elements the
+ * CSS selector matches in the query root and in every closed root under it.
+ */
+export declare const SEARCH_ROOTS_SELECTOR_ENGINE = "e2e-roots";
+/**
+ * In-page helpers the selector engines below and the label engine
+ * (`label-selector.ts`) are built on, as source: the
+ * closed roots the init script recorded under a query root (the root's own,
+ * when it is a closed host, and every one below through open and closed
+ * roots alike), and the elements a CSS selector matches in one tree and the
+ * open roots below it. A closed root is searched only as an entry of the
+ * first list, never by recursion from the tree above it, so each element is
+ * reached from exactly one root. A document that has attached no closed root
+ * (the record's `count` is zero) has none to find, and the walk over every
+ * element is skipped; every locator resolution runs this, so a page without
+ * closed roots must pay nothing for the reach.
+ */
+export declare const CLOSED_SHADOW_HELPERS_SOURCE: string;
+/** The two closed-root selector engines; `selector-engines.ts` lists them with the label engine for registration. */
+export declare const CLOSED_SHADOW_SELECTOR_ENGINES: readonly {
+    readonly name: string;
+    readonly source: string;
+}[];
+//# sourceMappingURL=closed-shadow.d.ts.map

package/dist/closed-shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closed-shadow.d.ts","sourceRoot":"","sources":["../src/closed-shadow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,+BAA+B,QAetC,CAAC;AAEP,uGAAuG;AACvG,eAAO,MAAM,6BAA6B,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,cAAc,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,QAsBpC,CAAC;AA6CN,qHAAqH;AACrH,eAAO,MAAM,8BAA8B,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAGvG,CAAC"}

package/dist/closed-shadow.js

@@ -0,0 +1,142 @@
+/**
+ * Closed shadow roots, kept reachable for the reader, the locators, and the
+ * screenshot masks: the context init script that records them, and the two
+ * Playwright selector engines that search them. Both engines are page code as
+ * source strings; the engine list is what the browser connection and the CDP
+ * context register.
+ */
+/**
+ * Where the init script below records closed shadow roots, keyed by host, and
+ * where the in-page reader looks for them. The reader is serialized into the
+ * page and cannot import this constant, so the literal is repeated inside it;
+ * the two must agree, like `SECURE_FIELD_SELECTOR` on both sides of masking.
+ *
+ * The record is a `WeakMap` from host to root with one own property beside
+ * the map: `count`, the number of closed roots the document has attached. It
+ * lets a selector engine answer for a document without closed roots without
+ * walking it.
+ */
+export const CLOSED_SHADOW_ROOTS_KEY = 'e2e.closedShadowRoots';
+/**
+ * Context init script that keeps every closed shadow root reachable for the
+ * reader. A closed root hides its tree from `element.shadowRoot`, so a checkout
+ * button a third-party widget renders that way is on screen for a person yet
+ * absent from the walk. `attachShadow` is the one way a script creates such a
+ * root; wrapping it before any page script runs records host and root in a
+ * WeakMap under a well-known symbol, which the reader consults where it reads
+ * `shadowRoot`, and counts the roots attached so far. The map is keyed by the
+ * host element and never enumerated, so it holds nothing alive and changes
+ * nothing the page can observe about the root itself. Declarative
+ * `<template shadowrootmode="closed">` roots are parsed rather than attached
+ * and stay out of reach.
+ */
+export const CLOSED_SHADOW_ROOTS_INIT_SCRIPT = `(() => {
+  const key = Symbol.for(${JSON.stringify(CLOSED_SHADOW_ROOTS_KEY)});
+  if (Object.prototype.hasOwnProperty.call(globalThis, key)) return;
+  const roots = new WeakMap();
+  Object.defineProperty(roots, 'count', { value: 0, enumerable: false, configurable: false, writable: true });
+  Object.defineProperty(globalThis, key, { value: roots, enumerable: false, configurable: false, writable: false });
+  const attachShadow = Element.prototype.attachShadow;
+  Element.prototype.attachShadow = function (init) {
+    const root = attachShadow.call(this, init);
+    if (root.mode === 'closed') {
+      roots.set(this, root);
+      roots.count += 1;
+    }
+    return root;
+  };
+})();`;
+/** Playwright selector engine name; `e2e-closed=<css>` matches inside recorded closed shadow roots. */
+export const CLOSED_SHADOW_SELECTOR_ENGINE = 'e2e-closed';
+/**
+ * Playwright selector engine name for the roots a semantic query searches.
+ * `e2e-roots=` (an empty body) resolves to the query root followed by every
+ * closed shadow root recorded under it, so the Playwright query part that
+ * follows (`internal:role`, `internal:text`, `internal:label`, ...) runs its
+ * own matching in each of them; `e2e-roots=<css>` resolves to the elements the
+ * CSS selector matches in the query root and in every closed root under it.
+ */
+export const SEARCH_ROOTS_SELECTOR_ENGINE = 'e2e-roots';
+/**
+ * In-page helpers the selector engines below and the label engine
+ * (`label-selector.ts`) are built on, as source: the
+ * closed roots the init script recorded under a query root (the root's own,
+ * when it is a closed host, and every one below through open and closed
+ * roots alike), and the elements a CSS selector matches in one tree and the
+ * open roots below it. A closed root is searched only as an entry of the
+ * first list, never by recursion from the tree above it, so each element is
+ * reached from exactly one root. A document that has attached no closed root
+ * (the record's `count` is zero) has none to find, and the walk over every
+ * element is skipped; every locator resolution runs this, so a page without
+ * closed roots must pay nothing for the reach.
+ */
+export const CLOSED_SHADOW_HELPERS_SOURCE = `
+  const roots = globalThis[Symbol.for(${JSON.stringify(CLOSED_SHADOW_ROOTS_KEY)})];
+  const tracked = roots instanceof WeakMap;
+  const closedRootsUnder = (root, out) => {
+    if (!tracked || roots.count === 0) return out;
+    const scan = (el) => {
+      const closed = roots.get(el);
+      if (closed !== undefined) out.push(closed);
+      const nested = el.shadowRoot ?? closed;
+      if (nested !== undefined && nested !== null) closedRootsUnder(nested, out);
+    };
+    if (root.nodeType === 1) scan(root);
+    for (const el of root.querySelectorAll('*')) scan(el);
+    return out;
+  };
+  const matchesIn = (root, selector, out) => {
+    for (const el of root.querySelectorAll(selector)) out.push(el);
+    if (root.nodeType === 1 && root.shadowRoot !== null) matchesIn(root.shadowRoot, selector, out);
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot !== null) matchesIn(el.shadowRoot, selector, out);
+    }
+    return out;
+  };`;
+/**
+ * The engine behind `e2e-closed=<css>`: every element matching the CSS
+ * selector inside a closed shadow root the init script recorded, reached from
+ * the query root through light DOM and open roots, and through roots of either
+ * kind nested below a closed one. Playwright's own selectors stop at a closed
+ * root, so this is what lets a screenshot mask cover a secure field the reader
+ * now reports there. It runs in the page's main world (not as a content
+ * script) because that is where the record lives. A document without the
+ * record is refused: a mask that cannot prove its coverage must fail closed.
+ */
+const CLOSED_SHADOW_SELECTOR_ENGINE_SOURCE = `() => {${CLOSED_SHADOW_HELPERS_SOURCE}
+  const queryAll = (root, selector) => {
+    if (!tracked) throw new Error('closed-shadow root tracking is unavailable for this document');
+    const out = [];
+    for (const closed of closedRootsUnder(root, [])) matchesIn(closed, selector, out);
+    return out;
+  };
+  return { queryAll, query: (root, selector) => queryAll(root, selector)[0] ?? null };
+}`;
+/**
+ * The engine behind `e2e-roots=`: the roots a semantic query searches, or the
+ * elements a CSS selector matches across them. Playwright's own query engines
+ * accept a shadow root as their root and never cross a closed boundary
+ * downward, so listing every closed root as a root of its own lets them match
+ * inside with the same role, name, text, label, and attribute rules they apply
+ * outside, and finds each element exactly once. A CSS selector list is matched
+ * here rather than by Playwright's CSS engine, which sorts a list's matches in
+ * DOM order through `shadowRoot` and so drops the direct children of a closed
+ * root; the matches of one root keep their document order and roots follow in
+ * the order they were found. A document without the record answers as
+ * Playwright alone would, so a locator never fails where it used to work.
+ */
+const SEARCH_ROOTS_SELECTOR_ENGINE_SOURCE = `() => {${CLOSED_SHADOW_HELPERS_SOURCE}
+  const queryAll = (root, selector) => {
+    if (selector === '') return [root, ...closedRootsUnder(root, [])];
+    const out = matchesIn(root, selector, []);
+    for (const closed of closedRootsUnder(root, [])) matchesIn(closed, selector, out);
+    return out;
+  };
+  return { queryAll, query: (root, selector) => queryAll(root, selector)[0] ?? null };
+}`;
+/** The two closed-root selector engines; `selector-engines.ts` lists them with the label engine for registration. */
+export const CLOSED_SHADOW_SELECTOR_ENGINES = [
+    { name: CLOSED_SHADOW_SELECTOR_ENGINE, source: CLOSED_SHADOW_SELECTOR_ENGINE_SOURCE },
+    { name: SEARCH_ROOTS_SELECTOR_ENGINE, source: SEARCH_ROOTS_SELECTOR_ENGINE_SOURCE },
+];
+//# sourceMappingURL=closed-shadow.js.map

package/dist/closed-shadow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closed-shadow.js","sourceRoot":"","sources":["../src/closed-shadow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;2BACpB,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC;;;;;;;;;;;;;;MAc5D,CAAC;AAEP,uGAAuG;AACvG,MAAM,CAAC,MAAM,6BAA6B,GAAG,YAAY,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,WAAW,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;wCACJ,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC;;;;;;;;;;;;;;;;;;;;;KAqB1E,CAAC;AAEN;;;;;;;;;GASG;AACH,MAAM,oCAAoC,GAAG,UAAU,4BAA4B;;;;;;;;EAQjF,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,mCAAmC,GAAG,UAAU,4BAA4B;;;;;;;;EAQhF,CAAC;AAEH,qHAAqH;AACrH,MAAM,CAAC,MAAM,8BAA8B,GAAkE;IAC3G,EAAE,IAAI,EAAE,6BAA6B,EAAE,MAAM,EAAE,oCAAoC,EAAE;IACrF,EAAE,IAAI,EAAE,4BAA4B,EAAE,MAAM,EAAE,mCAAmC,EAAE;CACpF,CAAC"}

package/dist/dialogs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Native dialog routing for one attempt. Handlers are registered by the `web`
+ * fixture; the surface owns the router so a dialog that fires before a test
+ * ever touches `web` is still accounted for instead of silently dismissed.
+ */
+import type { Dialog as PwDialog } from 'playwright';
+import { ErrorLatch } from './support.ts';
+/** A native dialog as a test's handler sees it. */
+export interface Dialog {
+    /** The dialog's text. */
+    readonly message: string;
+    /** Accepts the dialog once. */
+    accept(text?: string): Promise<void>;
+    /** Dismisses the dialog once. */
+    dismiss(): Promise<void>;
+}
+export type DialogHandler = 'accept' | 'dismiss' | ((dialog: Dialog) => void | Promise<void>);
+export declare class DialogRouter {
+    private readonly latch;
+    private registrations;
+    /**
+     * `latch` is shared with the surface: a dialog failure and a route-handler
+     * failure surface through one check at the next step.
+     */
+    constructor(latch?: ErrorLatch);
+    /**
+     * Registers a handler (the newest wins) and returns its idempotent
+     * unsubscribe. Registrations are tracked by identity, so registering the
+     * same handler twice and unsubscribing once leaves one in place.
+     */
+    add(handler: DialogHandler): () => void;
+    /** Rethrows an error latched by an unhandled or failing dialog handler. */
+    throwPending(): void;
+    /** Routes one native dialog to the newest registered handler; the attempt end waits for it. */
+    dispatch(dialog: PwDialog): Promise<void>;
+    private route;
+}
+//# sourceMappingURL=dialogs.d.ts.map

package/dist/dialogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogs.d.ts","sourceRoot":"","sources":["../src/dialogs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,UAAU,EAAyB,MAAM,cAAc,CAAC;AAEjE,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,iCAAiC;IACjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAM9F,qBAAa,YAAY;IAOX,OAAO,CAAC,QAAQ,CAAC,KAAK;IANlC,OAAO,CAAC,aAAa,CAAsB;IAE3C;;;OAGG;IACH,YAA6B,KAAK,GAAE,UAA6B,EAAI;IAErE;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI,CAMtC;IAED,2EAA2E;IAC3E,YAAY,IAAI,IAAI,CAEnB;IAED,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxC;YAEa,KAAK;CAyDpB"}

package/dist/dialogs.js

@@ -0,0 +1,87 @@
+/**
+ * Native dialog routing for one attempt. Handlers are registered by the `web`
+ * fixture; the surface owns the router so a dialog that fires before a test
+ * ever touches `web` is still accounted for instead of silently dismissed.
+ */
+import { EngineError } from 'e2e/engine';
+import { ErrorLatch, isClassified, message } from './support.js';
+export class DialogRouter {
+    latch;
+    registrations = [];
+    /**
+     * `latch` is shared with the surface: a dialog failure and a route-handler
+     * failure surface through one check at the next step.
+     */
+    constructor(latch = new ErrorLatch()) {
+        this.latch = latch;
+    }
+    /**
+     * Registers a handler (the newest wins) and returns its idempotent
+     * unsubscribe. Registrations are tracked by identity, so registering the
+     * same handler twice and unsubscribing once leaves one in place.
+     */
+    add(handler) {
+        const registration = { handler };
+        this.registrations.push(registration);
+        return () => {
+            this.registrations = this.registrations.filter((entry) => entry !== registration);
+        };
+    }
+    /** Rethrows an error latched by an unhandled or failing dialog handler. */
+    throwPending() {
+        this.latch.throwPending();
+    }
+    /** Routes one native dialog to the newest registered handler; the attempt end waits for it. */
+    dispatch(dialog) {
+        const work = this.route(dialog);
+        this.latch.track('dialog', work);
+        return work;
+    }
+    async route(dialog) {
+        const handler = this.registrations.at(-1)?.handler;
+        if (handler === undefined) {
+            this.latch.latch(new EngineError('INVALID_STATE', `unhandled ${dialog.type()} dialog: ${dialog.message()}`, { retryable: false }));
+            await dialog.dismiss().catch(() => undefined);
+            return;
+        }
+        let decided = false;
+        const publicDialog = {
+            message: dialog.message(),
+            accept: async (text) => {
+                decided = true;
+                await dialog.accept(text);
+            },
+            dismiss: async () => {
+                decided = true;
+                await dialog.dismiss();
+            },
+        };
+        try {
+            if (handler === 'accept')
+                await dialog.accept();
+            else if (handler === 'dismiss')
+                await dialog.dismiss();
+            else {
+                await handler(publicDialog);
+                // A dialog left open blocks the page, and the failure would surface
+                // later as an unrelated action timeout. The handler contract is the
+                // same as a route handler's: decide, or the step fails naming you.
+                if (!decided) {
+                    await dialog.dismiss().catch(() => undefined);
+                    this.latch.latch(new EngineError('INVALID_STATE', `dialog handler returned without calling accept or dismiss for ${dialog.type()} dialog: ${dialog.message()}`, { retryable: false }));
+                }
+            }
+        }
+        catch (cause) {
+            // A failed assertion or a policy refusal keeps its code; only an
+            // unclassified throw is the engine's to name.
+            this.latch.latch(isClassified(cause)
+                ? cause
+                : new EngineError('ENGINE_FAILURE', `dialog handler failed: ${message(cause)}`, {
+                    retryable: false,
+                    cause,
+                }));
+        }
+    }
+}
+//# sourceMappingURL=dialogs.js.map

package/dist/dialogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogs.js","sourceRoot":"","sources":["../src/dialogs.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The Playwright engine for e2e: a browser body built with the
+ * public `defineEngine`, validated by the same rules and graded by the same
+ * capabilities as any other engine. Core imports nothing from here; this
+ * package imports the contract from `e2e/engine` and contributes the `web`
+ * fixture the way a device engine contributes `device`.
+ */
+import type { BrowserContext, Page } from 'playwright';
+import { type EngineHandle } from 'e2e/engine';
+import { type WebOptions } from './surface.ts';
+/**
+ * The live browser objects behind a `web()` handle, for agent-side code
+ * that replaces the toolset wholesale (spec chapter 16) and drives the page with
+ * its own Playwright tooling. Both accessors read the current attempt: the
+ * context exists from `startAttempt`, the page from the first `app.open()` or
+ * `web.goto()`, and either throws `INVALID_STATE` before that. The harness
+ * remains the notary for what it witnesses; a caller here acts out of band.
+ */
+export interface PlaywrightLiveSurface {
+    readonly page: () => Page;
+    readonly context: () => BrowserContext;
+}
+/** The live surface of a handle this module created, or undefined for any other engine. */
+export declare function surfaceOf(engine: EngineHandle): PlaywrightLiveSurface | undefined;
+export declare function web(options?: WebOptions): EngineHandle;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAOL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAMlE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,cAAc,CAAC;CACxC;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,qBAAqB,GAAG,SAAS,CAIjF;AAED,wBAAgB,GAAG,CAAC,OAAO,GAAE,UAAe,GAAG,YAAY,CAyF1D"}