@e2e-dev/web 0.11.2 → 0.12.0

package/dist/init-scripts.js

@@ -0,0 +1,105 @@
+/**
+ * Init scripts: test code every document of an attempt runs after it is
+ * created and before any of its own scripts, in every tab and frame, as
+ * Playwright's `addInitScript` runs it. The configured ones apply to every
+ * attempt; `browser.addInitScript` adds more for one attempt.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ConfigurationError, TestError, validateJsonValue } from 'e2e/engine';
+import { KEEP_NAMES_HELPER } from './evaluation.js';
+import { message } from './support.js';
+/** Refuses, at config load, a `web({ initScripts })` value that is not a list of scripts. */
+export function validateInitScripts(scripts) {
+    if (!Array.isArray(scripts)) {
+        throw new ConfigurationError('INVALID_CONFIG', 'web({ initScripts }) must be an array of scripts');
+    }
+    // Indexed, not `forEach`, so a hole in a sparse array is refused like `undefined`.
+    for (let index = 0; index < scripts.length; index += 1) {
+        assertInitScript(scripts[index], (problem) => new ConfigurationError('INVALID_CONFIG', `web({ initScripts })[${index}] ${problem}`));
+    }
+}
+/** The configured `initScripts`, read into page source once per process and handed to each attempt as the start of its own list. */
+export class ConfiguredInitScripts {
+    scripts;
+    sources = [];
+    constructor(scripts) {
+        this.scripts = scripts;
+    }
+    /** Reads every script, a `path` against the project root; a file that cannot be read is `INVALID_CONFIG`. */
+    async load(projectRoot) {
+        if (this.scripts.length === 0)
+            return;
+        this.sources = await Promise.all(this.scripts.map(async (script, index) => {
+            try {
+                return await initScriptSource(script, undefined, (file) => path.resolve(projectRoot, file));
+            }
+            catch (cause) {
+                throw new ConfigurationError('INVALID_CONFIG', `web({ initScripts })[${index}] ${message(cause)}`, { cause });
+            }
+        }));
+    }
+    /** A new attempt's init scripts: the configured ones, to which `browser.addInitScript` appends. */
+    forAttempt() {
+        return [...this.sources];
+    }
+}
+/**
+ * Validates one script `browser.addInitScript` was given and reads it into
+ * page source, a `path` through `resolvePath`. Only a function takes an
+ * argument, as in Playwright.
+ */
+export async function testInitScriptSource(script, argument, resolvePath) {
+    assertInitScript(script, (problem) => new TestError('INVALID_ARGUMENT', `browser.addInitScript script ${problem}`));
+    if (argument !== undefined && typeof script !== 'function') {
+        throw new TestError('INVALID_ARGUMENT', 'browser.addInitScript takes an argument only with a function script');
+    }
+    validateJsonValue(argument?.arg, 'addInitScript argument');
+    try {
+        return await initScriptSource(script, argument?.arg, resolvePath);
+    }
+    catch (cause) {
+        throw new TestError('INVALID_ARGUMENT', `browser.addInitScript ${message(cause)}`, { cause });
+    }
+}
+/** The step label of a script: the file a `path` names, else its kind, never its source. */
+export function initScriptLabel(script) {
+    if (typeof script === 'object' && script !== null && 'path' in script)
+        return String(script.path);
+    return typeof script === 'function' ? 'function' : 'source';
+}
+/** Throws what `fail` makes of the problem unless `script` is one init script. */
+function assertInitScript(script, fail) {
+    if (typeof script === 'string' || typeof script === 'function')
+        return;
+    if (typeof script !== 'object' || script === null || Array.isArray(script)) {
+        const got = script === null ? 'null' : Array.isArray(script) ? 'an array' : typeof script;
+        throw fail(`must be a string of source, a { path }, or a function, got ${got}`);
+    }
+    const unknown = Object.keys(script).filter((key) => key !== 'path');
+    if (unknown.length > 0)
+        throw fail(`takes only path, got ${unknown.join(', ')}`);
+    if (!('path' in script) || typeof script.path !== 'string' || script.path === '')
+        throw fail('path must be a non-empty string');
+}
+/**
+ * The page source of one script. A function is called with its JSON argument
+ * as Playwright calls it, beside the `__name` helper tsx's output needs; the
+ * argument is parsed in the page, since an object literal would turn an own
+ * `__proto__` key into the prototype. A
+ * file gets a `sourceURL`, so a stack trace in the page names it.
+ */
+async function initScriptSource(script, arg, resolvePath) {
+    if (typeof script === 'string')
+        return script;
+    if (typeof script === 'function') {
+        return `(() => {\n${KEEP_NAMES_HELPER}\n(${script.toString()}\n)(${arg === undefined ? '' : `JSON.parse(${JSON.stringify(JSON.stringify(arg))})`});\n})();`;
+    }
+    const file = resolvePath(script.path);
+    try {
+        return `${await readFile(file, 'utf8')}\n//# sourceURL=${file.replace(/[\r\n]/g, '')}`;
+    }
+    catch (cause) {
+        throw new Error(`path cannot be read: ${file} (${cause.code ?? message(cause)})`, { cause });
+    }
+}

package/dist/install.d.ts

@@ -1,5 +1,12 @@
 /** First-run browser provisioning for the Playwright engine. */
 import { type BrowserName } from './browser-connection.ts';
+/**
+ * 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 declare function runPlaywrightCli(args: readonly string[]): Promise<number>;
 /** What an installer receives besides the browser names. */
 export interface InstallContext {
     /** Receives every line the installer prints: the download URL, progress, warnings. */
@@ -30,7 +37,7 @@ export interface EnsureBrowsersOptions {
 }
 /**
  * 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

package/dist/install.js

@@ -2,6 +2,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync } 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';
@@ -23,14 +24,40 @@ function isBrowserInstalled(name, env) {
         return false;
     }
 }
-/** Resolves the `playwright` CLI entry point relative to this package. */
-function playwrightCliPath() {
+/** 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' });
+        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]));
+        });
+    });
 }
 /**
  * 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
@@ -81,14 +108,14 @@ function forwardLines(stream, log) {
     });
     stream.on('end', () => flush(pending));
 }
-/** Spawns `node <playwright>/cli.js install <names>`, narrating its output through `log`. */
+/** Spawns `node <playwright-core>/cli.js install <names>`, narrating its output through `log`. */
 function runPlaywrightInstall(names, { log, signal, env }) {
     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', ...names]), {
             stdio: ['ignore', 'pipe', 'pipe'],
             env,
         });
@@ -101,7 +128,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 +137,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/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;