@e2e-dev/web 0.11.2 → 0.13.0

package/dist/route-options.js

@@ -0,0 +1,125 @@
+/**
+ * Argument validation for a route handler's decision. Every key is checked
+ * before the decision is taken: an option this engine does not implement
+ * (Playwright's `abort(errorCode)`, `fulfill({ response })`, a misspelled
+ * key) is `INVALID_ARGUMENT` rather than a request answered as if the option
+ * were absent. A continue URL goes through the harness's navigation rule,
+ * the same `resolveUrl` `goto` uses.
+ */
+import { statSync } from 'node:fs';
+import { rejectUnknownOptions, TestError, validateJsonValue } from 'e2e/engine';
+import { headerProblem } from './protected-app.js';
+const FULFILL_KEYS = ['status', 'headers', 'contentType', 'json', 'body', 'path'];
+const CONTINUE_KEYS = ['url', 'method', 'headers', 'postData'];
+/**
+ * Validates `route.fulfill(response)`, synchronously so the decision is
+ * taken the moment `fulfill` is called. `path` resolves with `resolvePath`
+ * (the project root, never `process.cwd()`) and must name a file now, so a
+ * missing fixture fails the step with its own message, and `json` follows
+ * the JSON-value rules `evaluate` does. A `content-type` header becomes
+ * `contentType` when none is given, since Playwright overwrites the header
+ * with the type it derives for `json` and `path`.
+ */
+export function parseFulfill(response, resolvePath) {
+    const fields = requireOptions('route.fulfill', response, FULFILL_KEYS, false);
+    const sources = ['json', 'body', 'path'].filter((key) => fields[key] !== undefined);
+    if (sources.length > 1) {
+        throw new TestError('INVALID_ARGUMENT', `route.fulfill takes one of json, body, or path; got ${sources.join(' and ')}`);
+    }
+    const { status, headers, contentType, json, body, path } = fields;
+    if (status !== undefined && !(Number.isInteger(status) && status >= 100 && status <= 599)) {
+        throw new TestError('INVALID_ARGUMENT', 'route.fulfill status must be an integer from 100 to 599');
+    }
+    if (json !== undefined)
+        validateJsonValue(json, 'route.fulfill json');
+    const file = path === undefined ? undefined : resolvePath(requireString('route.fulfill', 'path', path, true));
+    if (file !== undefined)
+        requireFile(file);
+    const replied = requireHeaders('route.fulfill', headers) ?? {};
+    const type = contentType === undefined
+        ? Object.entries(replied).find(([name]) => name.toLowerCase() === 'content-type')?.[1]
+        : requireString('route.fulfill', 'contentType', contentType, true);
+    return {
+        status: status ?? 200,
+        headers: replied,
+        ...(type === undefined ? {} : { contentType: type }),
+        ...(json === undefined ? {} : { json: json }),
+        ...(body === undefined ? {} : { body: requireString('route.fulfill', 'body', body, false) }),
+        ...(file === undefined ? {} : { path: file }),
+    };
+}
+/**
+ * Validates `route.continue(overrides)`. A `url` resolves against the base
+ * URL through `resolveUrl`, which denies what navigation denies, and keeps
+ * the request's scheme, as the browser requires of a rewritten request.
+ */
+export function parseContinue(overrides, requestUrl, resolveUrl) {
+    const fields = requireOptions('route.continue', overrides, CONTINUE_KEYS, true);
+    const { url, method, headers, postData } = fields;
+    let target;
+    if (url !== undefined) {
+        target = resolveUrl(requireString('route.continue', 'url', url, true));
+        const from = new URL(requestUrl).protocol;
+        const to = new URL(target).protocol;
+        if (from !== to) {
+            throw new TestError('INVALID_ARGUMENT', `route.continue url must keep the request's ${from} scheme; got ${to}`);
+        }
+    }
+    const replaced = requireHeaders('route.continue', headers);
+    return {
+        ...(target === undefined ? {} : { url: target }),
+        ...(method === undefined ? {} : { method: requireString('route.continue', 'method', method, true) }),
+        ...(replaced === undefined ? {} : { headers: replaced }),
+        ...(postData === undefined ? {} : { postData: requireString('route.continue', 'postData', postData, false) }),
+    };
+}
+/** Rejects any argument to a decision that takes none (`abort`, `fallback`). */
+export function requireNoArguments(api, args) {
+    if (args.some((arg) => arg !== undefined)) {
+        throw new TestError('INVALID_ARGUMENT', `${api}() takes no arguments`);
+    }
+}
+/** The options object with every key checked against `allowed`; `undefined` is `{}` when `optional`. */
+function requireOptions(api, value, allowed, optional) {
+    if (value === undefined) {
+        if (optional)
+            return {};
+        throw new TestError('INVALID_ARGUMENT', `${api} takes an options object`);
+    }
+    rejectUnknownOptions(api, value, allowed);
+    return value;
+}
+/** `value` as a string, else `INVALID_ARGUMENT` naming the option. */
+function requireString(api, key, value, nonempty) {
+    if (typeof value !== 'string' || (nonempty && value.length === 0)) {
+        throw new TestError('INVALID_ARGUMENT', `${api} ${key} must be a ${nonempty ? 'nonempty ' : ''}string`);
+    }
+    return value;
+}
+/** A header map the browser can send, or `undefined` when none was given. */
+function requireHeaders(api, value) {
+    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`);
+    }
+    for (const [name, entry] of Object.entries(value)) {
+        const problem = headerProblem(name, entry);
+        if (problem !== undefined)
+            throw new TestError('INVALID_ARGUMENT', `${api} ${problem}`);
+    }
+    return value;
+}
+/** Rejects a path that does not name a regular file; synchronous so the check lands before the decision. */
+function requireFile(file) {
+    let isFile = false;
+    try {
+        isFile = statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+    }
+    catch {
+        // A directory on the path the runner may not search (`EACCES`): not a file the route can serve.
+    }
+    if (!isFile) {
+        throw new TestError('INVALID_ARGUMENT', `route.fulfill path is not a readable file: ${file}`);
+    }
+}

package/dist/selector-engines.js

@@ -2,8 +2,10 @@
 import { CLOSED_SHADOW_SELECTOR_ENGINES } from './closed-shadow.js';
 import { EXACT_LABEL_SELECTOR_ENGINE, EXACT_LABEL_SELECTOR_ENGINE_SOURCE } from './label-selector.js';
 import { READ_SELECTOR_ENGINE, READ_SELECTOR_ENGINE_SOURCE } from './read-selector.js';
+import { SHOWN_SELECTOR_ENGINE, SHOWN_SELECTOR_ENGINE_SOURCE } from './shown-selector.js';
 export const SELECTOR_ENGINES = [
     ...CLOSED_SHADOW_SELECTOR_ENGINES,
     { name: EXACT_LABEL_SELECTOR_ENGINE, source: EXACT_LABEL_SELECTOR_ENGINE_SOURCE },
     { name: READ_SELECTOR_ENGINE, source: READ_SELECTOR_ENGINE_SOURCE },
+    { name: SHOWN_SELECTOR_ENGINE, source: SHOWN_SELECTOR_ENGINE_SOURCE },
 ];

package/dist/shown-selector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The selector engine a `visible` query narrows through inside Playwright's
+ * own chain, before an index, a filter, or an enclosing scope runs. It keeps
+ * the query root when the reader's `hidden` state is false, so a node the
+ * chain retains is one `toBeVisible()` accepts by construction. Playwright's
+ * `filter({ visible: true })` could not stand in for it: it reads text under
+ * a `display: contents` element with `visibility: hidden` as visible, which
+ * paints nothing.
+ */
+/** Playwright selector engine name; `e2e-shown=` resolves to the query root when it reads as shown. */
+export declare const SHOWN_SELECTOR_ENGINE = "e2e-shown";
+/** The selector step that keeps a match only when it reads as shown. */
+export declare const SHOWN_SELECTOR = "e2e-shown=";
+/**
+ * The engine behind `e2e-shown=`: the query root itself when the reader's
+ * `hidden` mode answers false, else nothing. The reader is embedded as source
+ * because a selector engine, like the reader, is one self-contained page
+ * function.
+ */
+export declare const SHOWN_SELECTOR_ENGINE_SOURCE: string;

package/dist/shown-selector.js

@@ -0,0 +1,27 @@
+/**
+ * The selector engine a `visible` query narrows through inside Playwright's
+ * own chain, before an index, a filter, or an enclosing scope runs. It keeps
+ * the query root when the reader's `hidden` state is false, so a node the
+ * chain retains is one `toBeVisible()` accepts by construction. Playwright's
+ * `filter({ visible: true })` could not stand in for it: it reads text under
+ * a `display: contents` element with `visibility: hidden` as visible, which
+ * paints nothing.
+ */
+import { readSemanticsFunction } from './in-page/read-semantics.js';
+import { SECURE_FIELD_SELECTOR } from './read-node.js';
+/** Playwright selector engine name; `e2e-shown=` resolves to the query root when it reads as shown. */
+export const SHOWN_SELECTOR_ENGINE = 'e2e-shown';
+/** The selector step that keeps a match only when it reads as shown. */
+export const SHOWN_SELECTOR = `${SHOWN_SELECTOR_ENGINE}=`;
+/**
+ * The engine behind `e2e-shown=`: the query root itself when the reader's
+ * `hidden` mode answers false, else nothing. The reader is embedded as source
+ * because a selector engine, like the reader, is one self-contained page
+ * function.
+ */
+export const SHOWN_SELECTOR_ENGINE_SOURCE = `() => {
+  const read = (${readSemanticsFunction.toString()});
+  const options = { testIdAttribute: '', secureFieldSelector: ${JSON.stringify(SECURE_FIELD_SELECTOR)}, mode: { kind: 'hidden' } };
+  const queryAll = (root) => (read(root, options) ? [] : [root]);
+  return { queryAll, query: (root) => queryAll(root)[0] ?? null };
+}`;

package/dist/support.d.ts

@@ -1,5 +1,5 @@
 /** Shared error translation, filename, and swipe helpers for the Playwright engine. */
-import type { ElementHandle, Locator as PwLocator, Mouse, Page } from 'playwright';
+import type { ElementHandle, Locator as PwLocator, Mouse, Page } from 'playwright-core';
 import { EngineError, type EngineCleanupContext, type Momentum, type ScrollDirection, type ViewportPoint, type ViewportSize } from 'e2e/engine';
 export declare const DEFAULT_VIEWPORT: {
     readonly width: 1280;
@@ -29,7 +29,7 @@ export type ActionTarget = {
  * evaluate, page ownership, drag) have explicit helpers below so every fork is
  * visible at its call site instead of hidden behind a uniform interface.
  */
-type Actionable = Pick<PwLocator, 'click' | 'dblclick' | 'fill' | 'press' | 'check' | 'uncheck' | 'hover' | 'scrollIntoViewIfNeeded' | 'selectOption' | 'setInputFiles'>;
+type Actionable = Pick<PwLocator, 'click' | 'dblclick' | 'fill' | 'press' | 'hover' | 'scrollIntoViewIfNeeded' | 'selectOption' | 'setInputFiles'>;
 /** Narrows one action target to the shared Playwright action surface. */
 export declare function asActionable(target: ActionTarget): Actionable;
 /**
@@ -102,23 +102,29 @@ export declare function isTestErrorCode(cause: unknown, code: string): cause is
  * | `TimeoutError` on a read, navigation, or artifact call          | OPERATION_TIMEOUT         |
  * | `TimeoutError` on an action, log ends before the input dispatch | NOT_ACTIONABLE            |
  * | `TimeoutError` on an action, log shows the dispatch started     | ACTION_MAY_HAVE_COMMITTED |
+ * | operation deadline cut off an action, pointer, or keyboard call | ACTION_MAY_HAVE_COMMITTED |
  * | element detached / not attached / no element / resolved hidden  | NODE_STALE (retryable)    |
  * | execution context destroyed / frame detached by a navigation    | NODE_STALE (retryable)    |
+ * | strict mode violation, log ends before the input dispatch       | NODE_STALE (retryable)    |
+ * | strict mode violation, log shows the dispatch started           | ACTION_MAY_HAVE_COMMITTED |
  * | not an input / not editable / not checkable                     | NOT_ACTIONABLE            |
- * | strict mode violation, anything else                            | ENGINE_FAILURE           |
+ * | anything else                                                   | ENGINE_FAILURE            |
  *
  * The action split is read from the call log Playwright appends to a timeout
- * message: `performing <x> action`, `<x> action done`, and `waiting for
- * scheduled navigations to finish` are only logged once the input is being (or
- * has been) dispatched, so a timeout whose log reaches them is uncertain and
- * the harness must not blindly repeat it. Every earlier line (`waiting for
- * element to be visible, enabled and stable`, `scrolling into view if
- * needed`, `retrying <x> action`) precedes dispatch and is a plain
- * actionability miss.
+ * or strict mode message: `performing <x> action`, `<x> action done`, and
+ * `waiting for scheduled navigations to finish` are only logged once the input
+ * is being (or has been) dispatched, so a failure whose log reaches them is
+ * uncertain and the harness must not blindly repeat it. Every earlier line
+ * (`waiting for element to be visible, enabled and stable`, `scrolling into
+ * view if needed`, `retrying <x> action`) precedes dispatch and is a plain
+ * actionability miss. Only whole `- ` log lines count, so a locator or element
+ * text quoting those words never does.
  */
 export declare const POST_DISPATCH_PATTERN: RegExp;
 /** Translates an unexpected Playwright error at the contract boundary. */
 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;
 /**
  * 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
@@ -140,7 +146,7 @@ export declare function performViewportSwipe(page: Page, direction: ScrollDirect
  * CSS pixel instead.
  */
 export declare function nearestPixel(point: ViewportPoint): ViewportPoint;
-/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion. */
-export declare function performPointDrag(mouse: Mouse, start: ViewportPoint, end: ViewportPoint): Promise<void>;
+/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion; paced over `durationMs` when given. */
+export declare function performPointDrag(mouse: Mouse, start: ViewportPoint, end: ViewportPoint, durationMs?: number, signal?: AbortSignal): Promise<void>;
 export declare function performElementSwipe(target: ActionTarget, direction: ScrollDirection, momentum: Momentum, timeout: number): Promise<void>;
 export {};

package/dist/support.js

@@ -1,4 +1,5 @@
 /** Shared error translation, filename, and swipe helpers for the Playwright engine. */
+import { setTimeout } from 'node:timers/promises';
 import { EngineError, withinCleanupBudget } from 'e2e/engine';
 import { ConfigurationError, InfrastructureError, TestError } from 'e2e/engine';
 export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
@@ -193,11 +194,12 @@ export class ErrorLatch {
     }
 }
 /**
- * The runner error classes as their `name` reads. A project loads this engine
- * from its config file in one module realm (tsx) while the runner's core runs
- * in another, so a runner error reaching the engine is often a `TestError`
- * from a copy of `e2e` this module never imported: `instanceof` says no while
- * `name` and `code` still tell the truth.
+ * The runner error classes as their `name` reads. A project can load this
+ * engine against a copy of `e2e` other than the one the runner's core runs
+ * from (and e2e before 0.17 always loaded config in a module realm of its
+ * own), so a runner error reaching the engine can be a `TestError` this
+ * module never imported: `instanceof` says no while `name` and `code` still
+ * tell the truth.
  */
 const CLASSIFIED_NAMES = new Set([
     'EngineError',
@@ -236,21 +238,25 @@ export function isTestErrorCode(cause, code) {
  * | `TimeoutError` on a read, navigation, or artifact call          | OPERATION_TIMEOUT         |
  * | `TimeoutError` on an action, log ends before the input dispatch | NOT_ACTIONABLE            |
  * | `TimeoutError` on an action, log shows the dispatch started     | ACTION_MAY_HAVE_COMMITTED |
+ * | operation deadline cut off an action, pointer, or keyboard call | ACTION_MAY_HAVE_COMMITTED |
  * | element detached / not attached / no element / resolved hidden  | NODE_STALE (retryable)    |
  * | execution context destroyed / frame detached by a navigation    | NODE_STALE (retryable)    |
+ * | strict mode violation, log ends before the input dispatch       | NODE_STALE (retryable)    |
+ * | strict mode violation, log shows the dispatch started           | ACTION_MAY_HAVE_COMMITTED |
  * | not an input / not editable / not checkable                     | NOT_ACTIONABLE            |
- * | strict mode violation, anything else                            | ENGINE_FAILURE           |
+ * | anything else                                                   | ENGINE_FAILURE            |
  *
  * The action split is read from the call log Playwright appends to a timeout
- * message: `performing <x> action`, `<x> action done`, and `waiting for
- * scheduled navigations to finish` are only logged once the input is being (or
- * has been) dispatched, so a timeout whose log reaches them is uncertain and
- * the harness must not blindly repeat it. Every earlier line (`waiting for
- * element to be visible, enabled and stable`, `scrolling into view if
- * needed`, `retrying <x> action`) precedes dispatch and is a plain
- * actionability miss.
+ * or strict mode message: `performing <x> action`, `<x> action done`, and
+ * `waiting for scheduled navigations to finish` are only logged once the input
+ * is being (or has been) dispatched, so a failure whose log reaches them is
+ * uncertain and the harness must not blindly repeat it. Every earlier line
+ * (`waiting for element to be visible, enabled and stable`, `scrolling into
+ * view if needed`, `retrying <x> action`) precedes dispatch and is a plain
+ * actionability miss. Only whole `- ` log lines count, so a locator or element
+ * text quoting those words never does.
  */
-export const POST_DISPATCH_PATTERN = /performing \w+ action|\w+ action done|waiting for scheduled navigations to finish/i;
+export const POST_DISPATCH_PATTERN = /^\s*- (performing \w+ action|[\w ]+ action done|waiting for scheduled navigations to finish)\s*$/im;
 /** Translates an unexpected Playwright error at the contract boundary. */
 export function translatePwError(cause, operation) {
     if (isClassified(cause))
@@ -274,7 +280,7 @@ const STALE_PATTERN = /detached|not attached|resolved to hidden|no element|not f
  */
 const NAVIGATION_RACE_PATTERN = /execution context was destroyed|because of a navigation|navigating and changing the content|frame was detached|frame got detached|node is detached from document/i;
 /** Whether a Playwright failure describes a read that lost its document to a navigation. */
-function isNavigationRace(cause) {
+export function isNavigationRace(cause) {
     return NAVIGATION_RACE_PATTERN.test(message(cause));
 }
 /**
@@ -321,16 +327,31 @@ export async function performViewportSwipe(page, direction, momentum) {
 export function nearestPixel(point) {
     return { x: Math.round(point.x), y: Math.round(point.y) };
 }
-/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion. */
-export async function performPointDrag(mouse, start, end) {
+/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion; paced over `durationMs` when given. */
+export async function performPointDrag(mouse, start, end, durationMs, signal) {
     const from = nearestPixel(start);
     const to = nearestPixel(end);
     const middle = nearestPixel({ x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 });
     await mouse.move(from.x, from.y);
     await mouse.down();
-    await mouse.move(middle.x, middle.y);
-    await mouse.move(to.x, to.y);
-    await mouse.up();
+    try {
+        if (durationMs !== undefined) {
+            const steps = Math.max(2, Math.round(durationMs / 16));
+            const startedAt = performance.now();
+            for (let step = 1; step <= steps; step += 1) {
+                const due = startedAt + (durationMs * step) / steps;
+                await setTimeout(Math.max(0, due - performance.now()), undefined, { signal });
+                await mouse.move(from.x + ((to.x - from.x) * step) / steps, from.y + ((to.y - from.y) * step) / steps);
+            }
+        }
+        else {
+            await mouse.move(middle.x, middle.y);
+            await mouse.move(to.x, to.y);
+        }
+    }
+    finally {
+        await mouse.up();
+    }
 }
 export async function performElementSwipe(target, direction, momentum, timeout) {
     // Hover first: it auto-waits for visibility on both target kinds, so the

package/dist/surface.d.ts

@@ -6,11 +6,13 @@
  * `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';
+import type { BrowserContext, Page, Route } from 'playwright-core';
 import { type EngineAttemptContext, type EngineCleanupContext, 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';
 import { DialogRouter } from './dialogs.ts';
+import { type OperationBound } from './operation-budget.ts';
+import { type WebInitScript } from './init-scripts.ts';
 import { ErrorLatch } from './support.ts';
 type RoutePredicate = (url: URL) => boolean;
 type RouteHandler = (route: Route) => Promise<void>;
@@ -41,7 +43,7 @@ export interface WebConnectOptions {
      * same browser after a transport drop. Called once before the next
      * operation, within its budget. The original browser and page must survive.
      * Dispatched operations are never retried. The host owns browser cleanup.
-     * Context replacement, headers, basicAuth, and userAgent are unavailable in this mode.
+     * Context replacement, headers, basicAuth, userAgent, locale, and timezoneId are unavailable in this mode.
      */
     readonly reconnectEndpoint?: (signal: AbortSignal) => string | Promise<string>;
 }
@@ -131,6 +133,29 @@ export interface WebOptions {
      * (`connect.reconnectEndpoint`, or a provider with `scope: 'attempt'`).
      */
     readonly userAgent?: string;
+    /**
+     * The locale every attempt's context runs in, a BCP 47 tag such as
+     * `de-DE`, as Playwright's own `locale` context option sets it: what
+     * `navigator.language`, `Intl` formatting, and the `Accept-Language` header
+     * report. Defaults to the browser's own. An `accept-language` entry in
+     * `headers` beside it is `INVALID_CONFIG`, and so is a persistent context
+     * (`connect.reconnectEndpoint`, or a provider with `scope: 'attempt'`).
+     */
+    readonly locale?: string;
+    /**
+     * The IANA time zone every attempt's context runs in, such as
+     * `Europe/Berlin`, as Playwright's own `timezoneId` context option sets it:
+     * what `Date` and `Intl` resolve local time against. Defaults to the
+     * machine's. A persistent context (`connect.reconnectEndpoint`, or a
+     * provider with `scope: 'attempt'`) is `INVALID_CONFIG`.
+     */
+    readonly timezoneId?: string;
+    /**
+     * Scripts every document runs before the page's own, in every tab and
+     * frame: JavaScript source, a `{ path }` relative to the project root, or a
+     * function, which cannot close over test variables.
+     */
+    readonly initScripts?: readonly WebInitScript[];
 }
 export declare class PlaywrightSurface {
     /**
@@ -153,7 +178,13 @@ export declare class PlaywrightSurface {
     private readonly basicAuth;
     private readonly testIdAttribute;
     private readonly userAgent;
+    private readonly locale;
+    private readonly timezoneId;
+    private readonly configuredInitScripts;
+    /** The attempt's init scripts, configured then added, applied to each context the attempt opens. */
+    private initScripts;
     private app;
+    private projectRoot;
     private headed;
     private artifactsDir;
     private artifactCounter;
@@ -170,7 +201,8 @@ export declare class PlaywrightSurface {
      * leases the run's browsers from a provider. A CDP attach uses the
      * remote's browser, so only a local launch needs the browser here. The
      * download narrates through `info.log` and is bounded by the run's
-     * interrupt alone, never by a launch budget.
+     * interrupt alone, never by a launch budget. Init scripts are read first
+     * so a missing file fails the run before any worker starts.
      */
     prepare(info: EnginePrepareInfo): Promise<EnginePrepareResult | void>;
     /** Releases the browsers `prepare` leased; a local launch or a `connect` has nothing to release. */
@@ -235,8 +267,14 @@ export declare class PlaywrightSurface {
     dispose(context: EngineCleanupContext): Promise<void>;
     /** Returns the active attempt, including its connection generation and references. */
     private requireSession;
+    /** Adds one attempt-scoped init script to the current context, for every document it creates from now on. */
+    addInitScript(source: string): Promise<void>;
     /** Registers one attempt-scoped route on the current context. */
     route(predicate: RoutePredicate, handler: RouteHandler): Promise<void>;
+    /** The configured headers a request to `url` carries, lowercased; `undefined` off the app's site. */
+    siteHeaders(url: string): Readonly<Record<string, string>> | undefined;
+    /** Resolves a file a test names against the project root, as config paths do, never `process.cwd()`. */
+    projectPath(file: string): string;
     /** Removes one registered route from the attempt and the current context. */
     unroute(predicate: RoutePredicate, handler: RouteHandler): Promise<void>;
     requirePage(): Page;
@@ -260,11 +298,13 @@ export declare class PlaywrightSurface {
      * The single entry of every operation: rethrows an error latched on an
      * unawaited path, refuses a cancelled operation, races `fn` against the
      * operation signal so an abort mid-call surfaces as `CANCELLED` instead of
-     * waiting out Playwright, and translates raw errors at the contract
+     * waiting out Playwright, bounds it by the operation's budget so a call a
+     * hung page never answers is `OPERATION_TIMEOUT`, and translates raw errors at the contract
      * boundary. `translate` overrides the default translation for operations
-     * with a documented retryable failure mode.
+     * with a documented retryable failure mode; `bound` is `test-code` for an
+     * operation that runs the test's own code, which the deadline never cuts.
      */
-    guard<T>(operation: OperationContext, label: string, fn: (operation: OperationContext) => Promise<T>, translate?: (cause: unknown, label: string) => Error): Promise<T>;
+    guard<T>(operation: OperationContext, label: string, fn: (operation: OperationContext) => Promise<T>, translate?: (cause: unknown, label: string) => Error, bound?: OperationBound): Promise<T>;
     /** Opens one URL the harness resolved; the attempt's page is created on first use. */
     open(url: string, operation: OperationContext): Promise<void>;
     back(operation: OperationContext): Promise<void>;