@e2e-dev/web 0.11.1 → 0.12.0

package/dist/read-selector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The selector engine that reads a locate's matches in the task that finds
+ * them. Appended to a projected locator (`<locator> >> e2e-read=<json>`), it
+ * maps each match to itself and records the reader's semantics for it on the
+ * element, so a page that replaces the match a frame later can never detach
+ * it between the query and the read: both happen before the page runs again.
+ * A later protocol call takes those reads back from the very elements the
+ * query returned, as values or as handles to pin.
+ */
+import type { RawNodeData } from './read-node.ts';
+/** Playwright selector engine name; `e2e-read=<json>` reads every match under one locate's token. */
+export declare const READ_SELECTOR_ENGINE = "e2e-read";
+/** What the selector body carries into the page: the locate's token and the reader's options. */
+interface ReadSelectorBody {
+    readonly token: string;
+    readonly testIdAttribute: string;
+    readonly secureFieldSelector: string;
+}
+/**
+ * The selector one locate appends to its projected locator, under a fresh
+ * token so concurrent locates of one element each take back their own read.
+ * The body is JSON, kept whole by Playwright's selector parser like the
+ * `e2e-label` body.
+ */
+export declare function readSelector(options: Omit<ReadSelectorBody, 'token'>): {
+    readonly selector: string;
+    readonly token: string;
+};
+/**
+ * The engine behind `e2e-read=<json>`: each query root is a match of the
+ * locator before it, returned as is after the reader's node read of it is
+ * recorded under the body's token. The reader is embedded as source because
+ * a selector engine is one self-contained page function. It runs in the main
+ * world (not as a content script) so the take function, which Playwright
+ * evaluates there, finds what it recorded.
+ */
+export declare const READ_SELECTOR_ENGINE_SOURCE: string;
+/**
+ * Takes back, in order, the reads the engine recorded under `token` and
+ * deletes them; `null` where none was recorded, which is a match the engine
+ * never saw: a `*` capture earlier in the selector returns an element the
+ * chain only passed through. `locator.evaluateAll` calls it with the matched
+ * elements. A caller pinning handles evaluates it on the first handle with
+ * every handle in `elements`, so it runs in the frame the handles belong to;
+ * `page.evaluate` would reject handles taken inside an iframe.
+ */
+export declare const takeReadsFunction: (subject: Element | Element[], arg: {
+    readonly token: string;
+    readonly elements?: Element[];
+}) => (RawNodeData | null)[];
+export {};

package/dist/read-selector.js

@@ -0,0 +1,69 @@
+/**
+ * The selector engine that reads a locate's matches in the task that finds
+ * them. Appended to a projected locator (`<locator> >> e2e-read=<json>`), it
+ * maps each match to itself and records the reader's semantics for it on the
+ * element, so a page that replaces the match a frame later can never detach
+ * it between the query and the read: both happen before the page runs again.
+ * A later protocol call takes those reads back from the very elements the
+ * query returned, as values or as handles to pin.
+ */
+import { randomUUID } from 'node:crypto';
+import { readSemanticsFunction } from './in-page/read-semantics.js';
+/** Playwright selector engine name; `e2e-read=<json>` reads every match under one locate's token. */
+export const READ_SELECTOR_ENGINE = 'e2e-read';
+/**
+ * Where the engine records reads on an element: a `Map` from locate token to
+ * read under a registry symbol, like the observation's ref stamp: no
+ * attribute, nothing a key listing shows, not removable by application code,
+ * and gone with the element. The take function below repeats the literal, since a page function
+ * cannot import it.
+ */
+const READS_KEY = 'e2e.locate.reads';
+/**
+ * The selector one locate appends to its projected locator, under a fresh
+ * token so concurrent locates of one element each take back their own read.
+ * The body is JSON, kept whole by Playwright's selector parser like the
+ * `e2e-label` body.
+ */
+export function readSelector(options) {
+    const token = randomUUID();
+    return { selector: `${READ_SELECTOR_ENGINE}=${JSON.stringify({ ...options, token })}`, token };
+}
+/**
+ * The engine behind `e2e-read=<json>`: each query root is a match of the
+ * locator before it, returned as is after the reader's node read of it is
+ * recorded under the body's token. The reader is embedded as source because
+ * a selector engine is one self-contained page function. It runs in the main
+ * world (not as a content script) so the take function, which Playwright
+ * evaluates there, finds what it recorded.
+ */
+export const READ_SELECTOR_ENGINE_SOURCE = `() => {
+  const read = (${readSemanticsFunction.toString()});
+  const key = Symbol.for(${JSON.stringify(READS_KEY)});
+  const queryAll = (root, selector) => {
+    if (root.nodeType !== 1) return [];
+    const body = JSON.parse(selector);
+    const options = { testIdAttribute: body.testIdAttribute, secureFieldSelector: body.secureFieldSelector, mode: { kind: 'node' } };
+    if (!Object.prototype.hasOwnProperty.call(root, key)) {
+      Object.defineProperty(root, key, { value: new Map(), enumerable: false, configurable: false, writable: false });
+    }
+    root[key].set(body.token, read(root, options));
+    return [root];
+  };
+  return { queryAll, query: (root, selector) => queryAll(root, selector)[0] ?? null };
+}`;
+/**
+ * Takes back, in order, the reads the engine recorded under `token` and
+ * deletes them; `null` where none was recorded, which is a match the engine
+ * never saw: a `*` capture earlier in the selector returns an element the
+ * chain only passed through. `locator.evaluateAll` calls it with the matched
+ * elements. A caller pinning handles evaluates it on the first handle with
+ * every handle in `elements`, so it runs in the frame the handles belong to;
+ * `page.evaluate` would reject handles taken inside an iframe.
+ */
+export const takeReadsFunction = (subject, arg) => (Array.isArray(subject) ? subject : (arg.elements ?? [])).map((element) => {
+    const reads = element[Symbol.for('e2e.locate.reads')];
+    const read = reads?.get(arg.token) ?? null;
+    reads?.delete(arg.token);
+    return read;
+});

package/dist/refs.d.ts

@@ -40,4 +40,3 @@ export declare class RefRegistry {
     /** Disposes every element handle in one observation generation. */
     static dispose(generation: ReadonlyMap<string, ActionTarget>): void;
 }
-//# sourceMappingURL=refs.d.ts.map

package/dist/refs.js

@@ -82,4 +82,3 @@ export class RefRegistry {
         }
     }
 }
-//# sourceMappingURL=refs.js.map

package/dist/route-options.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { type JsonValue } from 'e2e/engine';
+/** What `route.fulfill` hands Playwright once the response is validated. */
+export interface FulfillDecision {
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly contentType?: string;
+    readonly json?: JsonValue;
+    readonly body?: string;
+    /** Absolute; Playwright reads it and derives `Content-Type` from its extension when none is given. */
+    readonly path?: string;
+}
+/** What `route.continue` hands Playwright once the overrides are validated; `headers` before the site's are merged in. */
+export interface ContinueDecision {
+    readonly url?: string;
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly postData?: string;
+}
+/**
+ * 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 declare function parseFulfill(response: unknown, resolvePath: (file: string) => string): FulfillDecision;
+/**
+ * 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 declare function parseContinue(overrides: unknown, requestUrl: string, resolveUrl: (url: string) => string): ContinueDecision;
+/** Rejects any argument to a decision that takes none (`abort`, `fallback`). */
+export declare function requireNoArguments(api: string, args: readonly unknown[]): void;

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

@@ -10,4 +10,3 @@ export declare function compileRoutePattern(pattern: string): RegExp;
 export declare function routePatternMatches(pattern: TextPattern, url: string): boolean;
 /** Structural equality for route patterns, used by unroute. */
 export declare function routePatternsEqual(a: TextPattern, b: TextPattern): boolean;
-//# sourceMappingURL=route-pattern.d.ts.map

package/dist/route-pattern.js

@@ -52,4 +52,3 @@ export function routePatternsEqual(a, b) {
         return a.source === b.source && a.flags === b.flags;
     return false;
 }
-//# sourceMappingURL=route-pattern.js.map

package/dist/selector-engines.d.ts

@@ -3,4 +3,3 @@ export declare const SELECTOR_ENGINES: readonly {
     readonly name: string;
     readonly source: string;
 }[];
-//# sourceMappingURL=selector-engines.d.ts.map

package/dist/selector-engines.js

@@ -1,8 +1,11 @@
 /** Every selector engine the web engine registers, in a launched browser and in a CDP context alike. */
 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 },
 ];
-//# sourceMappingURL=selector-engines.js.map

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;
 /**
@@ -119,6 +119,8 @@ export declare function isTestErrorCode(cause: unknown, code: string): cause is
 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
@@ -144,4 +146,3 @@ export declare function nearestPixel(point: ViewportPoint): ViewportPoint;
 export declare function performPointDrag(mouse: Mouse, start: ViewportPoint, end: ViewportPoint): Promise<void>;
 export declare function performElementSwipe(target: ActionTarget, direction: ScrollDirection, momentum: Momentum, timeout: number): Promise<void>;
 export {};
-//# sourceMappingURL=support.d.ts.map

package/dist/support.js

@@ -274,7 +274,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));
 }
 /**
@@ -363,4 +363,3 @@ function wheelDelta(direction, distance) {
             return [-distance, 0];
     }
 }
-//# sourceMappingURL=support.js.map

package/dist/surface.d.ts

@@ -6,11 +6,12 @@
  * `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 WebInitScript } from './init-scripts.ts';
 import { ErrorLatch } from './support.ts';
 type RoutePredicate = (url: URL) => boolean;
 type RouteHandler = (route: Route) => Promise<void>;
@@ -41,7 +42,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 +132,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 +177,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 +200,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 +266,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;
@@ -354,4 +391,3 @@ export declare class PlaywrightSurface {
     private captureObservation;
 }
 export {};
-//# sourceMappingURL=surface.d.ts.map