@e2e-dev/web 0.11.2 → 0.13.0

package/dist/install.js

@@ -1,36 +1,92 @@
 /** First-run browser provisioning for the Playwright engine. */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import os from 'node:os';
 import path from 'node:path';
 import { EngineError, InfrastructureError } from 'e2e/engine';
 import { browserType } from './browser-connection.js';
+/** Whether `chromium_headless_shell-<revision>` under `browsersPath` finished installing and holds its executable. */
+function headlessShellInstalled(browsersPath, revision) {
+    const shellRoot = path.join(browsersPath, `chromium_headless_shell-${revision}`);
+    if (!existsSync(path.join(shellRoot, 'INSTALLATION_COMPLETE')))
+        return false;
+    const executable = process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+    return readdirSync(shellRoot, { withFileTypes: true }).some((entry) => entry.isDirectory() && existsSync(path.join(shellRoot, entry.name, executable)));
+}
 /**
- * Whether the browser's executable exists on disk, or undefined when this
- * process cannot tell. Playwright resolves its browser cache from
- * `PLAYWRIGHT_BROWSERS_PATH` at module load, so the in-process check is only
- * authoritative when the run's environment agrees with this process's. A run
- * pointed at another cache is left to the CLI, which resolves against the
- * environment it is spawned with and is a no-op when nothing is missing.
+ * Whether the build the run launches (headless shell for headless chromium, else the full build)
+ * is on disk, or undefined when `env` points at another cache than this process loaded.
  */
-function isBrowserInstalled(name, env) {
+function isBrowserInstalled(name, env, headed) {
     if (env['PLAYWRIGHT_BROWSERS_PATH'] !== process.env['PLAYWRIGHT_BROWSERS_PATH'])
         return undefined;
     try {
-        return existsSync(browserType(name).executablePath());
+        const executable = browserType(name).executablePath();
+        if (headed || name !== 'chromium')
+            return existsSync(executable);
+        return headlessShellAt(executable);
     }
     catch {
         return false;
     }
 }
-/** Resolves the `playwright` CLI entry point relative to this package. */
-function playwrightCliPath() {
+/** Whether the shell beside `executable`'s full build is installed. */
+function headlessShellAt(executable) {
+    const marker = `${path.sep}chromium-`;
+    const at = executable.lastIndexOf(marker);
+    if (at === -1)
+        return false;
+    const revision = executable.slice(at + marker.length).split(path.sep)[0] ?? '';
+    return revision !== '' && headlessShellInstalled(executable.slice(0, at), revision);
+}
+/** The `node` arguments that run the pinned `playwright-core` CLI with `args`. */
+function playwrightCliArgs(args) {
     const require = createRequire(import.meta.url);
-    return path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
+    return [path.join(path.dirname(require.resolve('playwright-core/package.json')), 'cli.js'), ...args];
+}
+/**
+ * Runs the pinned Playwright CLI with `args`, sharing this process's terminal,
+ * and resolves to its exit code, 128 plus the signal number when a signal
+ * ended it. SIGINT and SIGTERM sent to this process reach the child, so a
+ * cancelled CI job does not leave a download running. Backs the `e2e-web` command.
+ */
+export function runPlaywrightCli(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, playwrightCliArgs(args), {
+            stdio: 'inherit',
+            env: installEnvironment(),
+        });
+        const forward = (signal) => child.kill(signal);
+        process.on('SIGINT', forward);
+        process.on('SIGTERM', forward);
+        const settle = () => {
+            process.off('SIGINT', forward);
+            process.off('SIGTERM', forward);
+        };
+        child.on('error', (error) => {
+            settle();
+            reject(error);
+        });
+        child.on('exit', (code, signal) => {
+            settle();
+            resolve(code ?? (signal === null ? 1 : 128 + os.constants.signals[signal]));
+        });
+    });
+}
+/** The `playwright install` arguments for `names`: `--only-shell` on a headless chromium run. */
+export function installArgs(names, headed) {
+    if (headed || !names.includes('chromium'))
+        return [...names];
+    return ['--only-shell', ...names];
+}
+/** `env` with `PLAYWRIGHT_SKIP_BROWSER_GC=1` unless already set, so an install keeps other tools' browsers. */
+function installEnvironment(env = process.env) {
+    return { ...env, PLAYWRIGHT_SKIP_BROWSER_GC: env['PLAYWRIGHT_SKIP_BROWSER_GC'] ?? '1' };
 }
 /**
  * Ensures the given Playwright browsers are installed, downloading any
- * missing ones via `playwright install`. Called from the engine's `prepare`,
+ * missing ones via `playwright-core install`. Called from the engine's `prepare`,
  * once per run before any worker starts, so a download is never charged
  * against a launch timeout and never runs once per worker. Concurrent
  * installs (two runs at once) are still safe: the Playwright CLI serializes
@@ -38,7 +94,8 @@ function playwrightCliPath() {
  */
 export async function ensureBrowsersInstalled(names, options = {}) {
     const env = options.env ?? process.env;
-    const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env));
+    const headed = options.headed ?? false;
+    const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env, headed));
     const verdicts = new Map([...new Set(names)].map((name) => [name, isInstalled(name)]));
     const missing = [...verdicts.keys()].filter((name) => verdicts.get(name) !== true);
     if (missing.length === 0)
@@ -51,7 +108,7 @@ export async function ensureBrowsersInstalled(names, options = {}) {
     if (knownMissing)
         log(`Downloading missing Playwright browsers (first run): ${missing.join(', ')}...`);
     const install = options.install ?? runPlaywrightInstall;
-    await install(missing, { log, signal: options.signal, env });
+    await install(missing, { log, signal: options.signal, env: installEnvironment(env), headed });
     if (knownMissing)
         log('Browser download complete.');
 }
@@ -81,14 +138,14 @@ function forwardLines(stream, log) {
     });
     stream.on('end', () => flush(pending));
 }
-/** Spawns `node <playwright>/cli.js install <names>`, narrating its output through `log`. */
-function runPlaywrightInstall(names, { log, signal, env }) {
+/** Spawns `node <playwright-core>/cli.js install <names>`, narrating its output through `log`. */
+function runPlaywrightInstall(names, { log, signal, env, headed }) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted === true) {
             reject(new EngineError('CANCELLED', 'browser install cancelled', { retryable: false }));
             return;
         }
-        const child = spawn(process.execPath, [playwrightCliPath(), 'install', ...names], {
+        const child = spawn(process.execPath, playwrightCliArgs(['install', ...installArgs(names, headed)]), {
             stdio: ['ignore', 'pipe', 'pipe'],
             env,
         });
@@ -101,7 +158,7 @@ function runPlaywrightInstall(names, { log, signal, env }) {
         signal?.addEventListener('abort', onAbort, { once: true });
         child.on('exit', () => signal?.removeEventListener('abort', onAbort));
         child.on('error', (cause) => {
-            reject(new InfrastructureError('BROWSER_INSTALL_FAILED', `failed to run playwright install: ${cause.message}`, {
+            reject(new InfrastructureError('BROWSER_INSTALL_FAILED', `failed to run playwright-core install: ${cause.message}`, {
                 cause,
             }));
         });
@@ -110,7 +167,7 @@ function runPlaywrightInstall(names, { log, signal, env }) {
                 resolve();
                 return;
             }
-            reject(new InfrastructureError('BROWSER_INSTALL_FAILED', `playwright install ${names.join(' ')} exited with code ${String(code)}; run "npx playwright install ${names.join(' ')}" manually`));
+            reject(new InfrastructureError('BROWSER_INSTALL_FAILED', `playwright-core install ${names.join(' ')} exited with code ${String(code)}; run "npx @e2e-dev/web install ${names.join(' ')}" (pnpm: "pnpm exec e2e-web install ${names.join(' ')}") manually`));
         });
     });
 }

package/dist/locators.d.ts

@@ -1,5 +1,5 @@
 /** LocatorExpression -> Playwright locator projection. */
-import type { Locator as PwLocator, Page } from 'playwright';
+import type { Locator as PwLocator, Page } from 'playwright-core';
 import { type LocatorExpression, type TextPattern } from 'e2e/engine';
 /** One positional step applied after display-value filtering. */
 export type PositionalStep = 'first' | 'last' | number;

package/dist/locators.js

@@ -3,11 +3,27 @@ import { EngineError } from 'e2e/engine';
 import { SEARCH_ROOTS_SELECTOR_ENGINE } from './closed-shadow.js';
 import { exactLabelSelector } from './label-selector.js';
 import { SECURE_FIELD_SELECTOR } from './read-node.js';
+import { SHOWN_SELECTOR } from './shown-selector.js';
 function patternToPw(pattern) {
     if (pattern.kind === 'regexp')
-        return new RegExp(pattern.source, pattern.flags);
+        return selectorSafeRegExp(new RegExp(pattern.source, pattern.flags));
     return pattern.value;
 }
+/**
+ * A RegExp Playwright can write into a selector as is. Playwright escapes the
+ * quotes and `>>` of a RegExp it writes into a selector, except under the `u`
+ * or `v` flag, where `\'` is a syntax error: a bare quote there opens a
+ * string that swallows every part chained after it. A quote or the second `>`
+ * of `>>` becomes the hex escape the flag accepts, matching the same text.
+ */
+function selectorSafeRegExp(re) {
+    if (!/[uv]/.test(re.flags))
+        return re;
+    const source = re.source
+        .replace(/["'`]/g, (quote) => `\\x${quote.charCodeAt(0).toString(16)}`)
+        .replace(/>>/g, '>\\x3e');
+    return source === re.source ? re : new RegExp(source, re.flags);
+}
 function patternExact(pattern) {
     return pattern.kind === 'string' ? pattern.exact : false;
 }
@@ -21,7 +37,7 @@ function patternExact(pattern) {
 function testIdSelector(attribute, pattern) {
     const name = attribute.includes(',') ? JSON.stringify(attribute) : attribute;
     const value = pattern.kind === 'regexp'
-        ? escapeRegexForSelector(new RegExp(pattern.source, pattern.flags))
+        ? escapeRegexForSelector(selectorSafeRegExp(new RegExp(pattern.source, pattern.flags)))
         : `"${pattern.value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"s`;
     return `internal:testid=[${name}=${value}]`;
 }
@@ -39,8 +55,12 @@ function escapeRegexForSelector(re) {
  * `image` query has to go back to `img` to match it.
  */
 const ARIA_ROLE_BY_CONTRACT_ROLE = { image: 'img' };
-/** Every control that carries a current value: the candidates of a display-value query. */
-const VALUED_SELECTOR = 'input, textarea, select';
+/**
+ * Every control that displays a current value: the candidates of a
+ * display-value query. A checkbox or radio carries a value it never shows
+ * (`on` by default), so it is no candidate.
+ */
+const VALUED_SELECTOR = 'input:not([type="checkbox" i]):not([type="radio" i]), textarea, select';
 /** Whitespace or an icon-font glyph (a private-use code point), the characters the tree's names drop or collapse. */
 const GLYPH_OR_SPACE = '[\\s\\p{Co}]';
 /**
@@ -58,7 +78,7 @@ function glyphTolerantName(name, exact) {
         .split(/\s+/)
         .map((word) => word.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'))
         .join(`${GLYPH_OR_SPACE}+`);
-    return exact ? new RegExp(`^${GLYPH_OR_SPACE}*${body}${GLYPH_OR_SPACE}*$`, 'u') : new RegExp(body, 'iu');
+    return selectorSafeRegExp(exact ? new RegExp(`^${GLYPH_OR_SPACE}*${body}${GLYPH_OR_SPACE}*$`, 'u') : new RegExp(body, 'iu'));
 }
 /**
  * The one table of query kinds: each declares its Playwright getter or its
@@ -125,20 +145,12 @@ function queryToPw(scope, query, testIdAttribute) {
             return candidates.locate(scope.locator(`${SEARCH_ROOTS_SELECTOR_ENGINE}=`));
     }
 }
-/**
- * Self-selector for the part of the semantic `hidden` state Playwright's own
- * visibility filter does not read: `aria-hidden` on the element itself.
- */
-const NOT_ARIA_HIDDEN = ':scope:not([aria-hidden="true"])';
 /**
  * A `visible` query narrows its candidates inside the selector, before any
- * enclosing scope, filter, or index runs: Playwright's visibility predicate
- * (layout box, `display`, `visibility`) plus the `aria-hidden` check the
- * semantic `hidden` state also makes. An indexed, filtered, or scoping visible
- * query therefore never selects or retains a node that state calls hidden.
- * The surface additionally holds a terminal query to the batch-read `hidden`
- * state, which reads the same box, style, and `details` facts Playwright's
- * predicate does, so a direct query agrees with `toBeVisible()`.
+ * enclosing scope, filter, or index runs, by the reader's own `hidden` state
+ * (`e2e-shown`). An indexed, filtered, or scoping visible query therefore
+ * never selects or retains a node that state calls hidden, and the surface's
+ * hold of a terminal query to the batch-read state agrees with it.
  */
 function visibleQueryToPw(scope, query, testIdAttribute) {
     return narrowedToVisible(queryToPw(scope, query, testIdAttribute), query);
@@ -147,7 +159,7 @@ function visibleQueryToPw(scope, query, testIdAttribute) {
 function narrowedToVisible(located, query) {
     if (query.visible !== true)
         return located;
-    return located.filter({ visible: true }).locator(NOT_ARIA_HIDDEN);
+    return located.locator(SHOWN_SELECTOR);
 }
 function positioned(locator, index) {
     return index === 'first' ? locator.first() : index === 'last' ? locator.last() : locator.nth(index);

package/dist/observation-capture.d.ts

@@ -1,5 +1,5 @@
 /** One observation transaction: settling, semantic capture, masked pixels, and staged refs. */
-import type { Page } from 'playwright';
+import type { Page } from 'playwright-core';
 import { type EngineObserveOptions, type OperationContext } from 'e2e/engine';
 import { RefRegistry, type CapturedObservation } from './refs.ts';
 interface CaptureSettings {

package/dist/observation.d.ts

@@ -2,7 +2,7 @@
  * Semantic tree capture for one observation: the in-page walk, nested-document
  * stitching, and element-handle bookkeeping the surface keeps per generation.
  */
-import type { ElementHandle, Frame } from 'playwright';
+import type { ElementHandle, Frame } from 'playwright-core';
 import { type NodeRef, type SemanticNode } from 'e2e/engine';
 import { type RawNodeData } from './read-node.ts';
 /**

package/dist/observation.js

@@ -154,7 +154,7 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
  *
  * A `data:` document is *not* admitted, even though its bytes are written by the
  * page that embeds it. It has an opaque origin rather than an inherited one, and
- * navigation denies the scheme by name alongside `file:` and `javascript:`.
+ * navigation admits only http(s) and `about:blank`.
  */
 function isOnSiteFrame(url, site) {
     if (url === '' || url === 'about:blank' || url === 'about:srcdoc')
@@ -213,7 +213,7 @@ function assembleTree(nodes, ids, framePath, frameChildren) {
         // bordered iframe is off by its border width, which is within a tap
         // target. A frame under a CSS transform is not unwound: its boxes are
         // where the untransformed frame would put them.
-        if (embedded !== undefined)
+        if (embedded !== undefined && raw.rect !== null)
             childLists[index].unshift(placeInFrame(embedded, raw.rect));
         const node = toSemanticNode({ id: ids[index], revision: '' }, raw, childLists[index], framePath);
         built[index] = node;
@@ -272,7 +272,7 @@ export function toSemanticNode(ref, raw, children = [], framePath = []) {
         states,
         ...(raw.level !== null ? { level: raw.level } : {}),
         attributes: raw.attributes,
-        rect: raw.rect,
+        ...(raw.rect !== null ? { rect: raw.rect } : {}),
         ...(framePath.length > 0 ? { framePath } : {}),
         ...(children.length > 0 ? { children } : {}),
     };

package/dist/observe.d.ts

@@ -1,5 +1,5 @@
 /** Masked pixel capture for an observation. */
-import type { Locator, Page } from 'playwright';
+import type { Locator, Page } from 'playwright-core';
 import type { ObservationPixels, OperationContext, ViewportSize } from 'e2e/engine';
 /**
  * Two mask locators per frame Playwright can reach, covering every secure

package/dist/operation-budget.d.ts

@@ -6,5 +6,19 @@ export interface ConnectionBudget {
 }
 /** Preserves the reason for an engine-owned deadline without relabeling caller cancellation. */
 export declare function connectionAbort(signal: AbortSignal, label: string): EngineError;
+/**
+ * Whether the operation's deadline may end it. `test-code` is for an
+ * operation that runs the test's own code (a download trigger): that code
+ * keeps its own steps and their budgets, so the operation is not cut under
+ * it, and only cancellation ends the wait.
+ */
+export type OperationBound = 'deadline' | 'test-code';
+/**
+ * Bounds one operation by its budget: a call still pending at the deadline
+ * is abandoned as `OPERATION_TIMEOUT` instead of holding the test until its
+ * own timeout. `remaining` hands `work` the time left before Playwright's
+ * own timeout, the one to pass Playwright.
+ */
+export declare function withOperationDeadline<T>(budget: ConnectionBudget, label: string, work: (remaining: () => ConnectionBudget) => Promise<T>, bound?: OperationBound): Promise<T>;
 /** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
 export declare function withConnectionBudget<T>(budget: ConnectionBudget, label: string, work: (remaining: () => ConnectionBudget) => Promise<T>): Promise<T>;

package/dist/operation-budget.js

@@ -6,6 +6,37 @@ export function connectionAbort(signal, label) {
         ? signal.reason
         : new EngineError('CANCELLED', `${label} cancelled`, { retryable: false });
 }
+/**
+ * How much sooner than an operation's deadline Playwright's own timeout
+ * fires: its error names what blocked an action, or that the input was
+ * already dispatched, and this lead lets that answer arrive before the
+ * deadline does. The deadline is for the calls Playwright never answers: an
+ * evaluate, which takes no timeout, and every call while a trace snapshots a
+ * page whose renderer is stuck in a script. A budget shorter than twice the
+ * lead splits in half.
+ */
+const PLAYWRIGHT_TIMEOUT_LEAD_MS = 250;
+/**
+ * Bounds one operation by its budget: a call still pending at the deadline
+ * is abandoned as `OPERATION_TIMEOUT` instead of holding the test until its
+ * own timeout. `remaining` hands `work` the time left before Playwright's
+ * own timeout, the one to pass Playwright.
+ */
+export function withOperationDeadline(budget, label, work, bound = 'deadline') {
+    if (bound === 'test-code') {
+        const endsAt = Date.now() + budget.timeoutMs;
+        return raceAbort(() => work(() => {
+            if (budget.signal.aborted)
+                throw connectionAbort(budget.signal, label);
+            return { signal: budget.signal, timeoutMs: Math.max(1, endsAt - Date.now()) };
+        }), budget.signal, label);
+    }
+    return withConnectionBudget(budget, label, (remaining) => work(() => {
+        const current = remaining();
+        const lead = Math.min(PLAYWRIGHT_TIMEOUT_LEAD_MS, current.timeoutMs / 2);
+        return { signal: current.signal, timeoutMs: Math.ceil(current.timeoutMs - lead) };
+    }));
+}
 /** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
 export async function withConnectionBudget(budget, label, work) {
     const controller = new AbortController();

package/dist/protected-app.d.ts

@@ -4,7 +4,7 @@
  * a challenge wherever one is issued. The surface calls these on every
  * context it creates; nothing here holds state.
  */
-import type { BrowserContext } from 'playwright';
+import type { BrowserContext } from 'playwright-core';
 import { type ResolveSecretOptions, type Secret } from 'e2e/engine';
 import type { WebBasicAuth } from './surface.ts';
 /** The credentials Playwright answers an HTTP authentication challenge with. */
@@ -12,15 +12,31 @@ export interface PlaywrightHttpCredential {
     readonly username: string;
     readonly password: string;
 }
+/** A control character no HTTP field value may carry; a horizontal tab is the one the grammar allows. */
+export declare const FIELD_VALUE_CONTROL: RegExp;
+/**
+ * Why the browser could not send this header, or `undefined` when it can: a
+ * name outside the token grammar, a value that is not a string, or one
+ * carrying a control character (a line break is a header-injection vector).
+ * Config and route overrides both check headers here.
+ */
+export declare function headerProblem(name: string, value: unknown): string | undefined;
 /** Header names lowercased, as Playwright reports a request's own headers. */
 export declare function lowercaseNames(headers: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * The configured headers a request to `url` carries: all of them for the
+ * app's site, none for any other site or when there is no site policy.
+ */
+export declare function siteHeadersFor(url: string | URL, site: string | undefined, headers: Readonly<Record<string, string>> | undefined): Readonly<Record<string, string>> | undefined;
 /**
  * Adds the configured headers to every request bound for the app's site,
  * via a context route that falls back to the network. A request for any
  * other site is not routed at all; without a site there is no policy and
- * nothing is routed. Nothing awaits a route handler, so a fallback that
- * fails (the page closed under the request) is dropped rather than left to
- * surface as an unhandled rejection.
+ * nothing is routed. Registered before any test route, so it runs last: a
+ * test route's `fallback` reaches it, and a `continue`, which skips it,
+ * merges the same headers itself (`siteHeadersFor`). Nothing awaits a route
+ * handler, so a fallback that fails (the page closed under the request) is
+ * dropped rather than left to surface as an unhandled rejection.
  */
 export declare function installSiteHeaders(context: BrowserContext, site: string | undefined, headers: Readonly<Record<string, string>> | undefined): Promise<void>;
 /**

package/dist/protected-app.js

@@ -5,22 +5,53 @@
  * context it creates; nothing here holds state.
  */
 import { sameSite } from 'e2e/engine';
+/** An HTTP header field name: one or more `token` characters (RFC 9110). */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** A control character no HTTP field value may carry; a horizontal tab is the one the grammar allows. */
+// oxlint-disable-next-line no-control-regex -- the control characters are the point
+export const FIELD_VALUE_CONTROL = /[\u0000-\u0008\u000A-\u001F\u007F]/;
+/**
+ * Why the browser could not send this header, or `undefined` when it can: a
+ * name outside the token grammar, a value that is not a string, or one
+ * carrying a control character (a line break is a header-injection vector).
+ * Config and route overrides both check headers here.
+ */
+export function headerProblem(name, value) {
+    if (!HEADER_NAME.test(name))
+        return `has an invalid header name: "${name}"`;
+    if (typeof value !== 'string')
+        return `header "${name}" must be a string, got ${typeof value}`;
+    if (FIELD_VALUE_CONTROL.test(value))
+        return `header "${name}" must not contain a control character`;
+    return undefined;
+}
 /** Header names lowercased, as Playwright reports a request's own headers. */
 export function lowercaseNames(headers) {
     return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
 }
+/**
+ * The configured headers a request to `url` carries: all of them for the
+ * app's site, none for any other site or when there is no site policy.
+ */
+export function siteHeadersFor(url, site, headers) {
+    if (headers === undefined || site === undefined)
+        return undefined;
+    return sameSite(url, site) ? headers : undefined;
+}
 /**
  * Adds the configured headers to every request bound for the app's site,
  * via a context route that falls back to the network. A request for any
  * other site is not routed at all; without a site there is no policy and
- * nothing is routed. Nothing awaits a route handler, so a fallback that
- * fails (the page closed under the request) is dropped rather than left to
- * surface as an unhandled rejection.
+ * nothing is routed. Registered before any test route, so it runs last: a
+ * test route's `fallback` reaches it, and a `continue`, which skips it,
+ * merges the same headers itself (`siteHeadersFor`). Nothing awaits a route
+ * handler, so a fallback that fails (the page closed under the request) is
+ * dropped rather than left to surface as an unhandled rejection.
  */
 export async function installSiteHeaders(context, site, headers) {
     if (headers === undefined || site === undefined)
         return;
-    await context.route((url) => sameSite(url, site), async (route) => {
+    await context.route((url) => siteHeadersFor(url, site, headers) !== undefined, async (route) => {
         await route.fallback({ headers: { ...route.request().headers(), ...headers } }).catch(() => undefined);
     });
 }

package/dist/provider-video.d.ts

@@ -4,7 +4,7 @@
  * ended by `stopProviderRecording` into the attempt's one segment, a file in
  * its `video` directory or a link.
  */
-import type { Page } from 'playwright';
+import type { Page } from 'playwright-core';
 import { type VideoSegment } from 'e2e/engine';
 import type { LeaseRecording } from './provider.ts';
 import type { AttemptVideo } from './video.ts';

package/dist/read-node.d.ts

@@ -48,12 +48,13 @@ export interface RawNodeData {
     attributes: Record<string, string>;
     /** Value of the project's test-id attribute, when the element carries one. */
     testId: string | null;
+    /** The element's box in its document's viewport; null when it lays out no box (`display: none`). */
     rect: {
         x: number;
         y: number;
         width: number;
         height: number;
-    };
+    } | null;
 }
 /** One observed node plus its position in the flattened depth-first tree. */
 export interface RawObservedNode extends RawNodeData {
@@ -81,6 +82,10 @@ interface RawObservation {
 }
 export type SemanticMode = {
     kind: 'node';
+}
+/** The element's `states.hidden` alone, for the `visible` narrowing a selector engine applies. */
+ | {
+    kind: 'hidden';
 } | {
     kind: 'tree';
     maxNodes: number;
@@ -98,7 +103,9 @@ export type SemanticMode = {
 /** Result of one read, selected by the mode discriminant. */
 export type SemanticResult<Mode extends SemanticMode> = Mode extends {
     kind: 'node';
-} ? RawNodeData : RawObservation;
+} ? RawNodeData : Mode extends {
+    kind: 'hidden';
+} ? boolean : RawObservation;
 /** Options for one document's tree walk. */
 interface TreeReadOptions {
     readonly testIdAttribute: string;

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;