@e2e-dev/web 0.11.1 → 0.12.0

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,8 +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`));
         });
     });
 }
-//# sourceMappingURL=install.js.map

package/dist/label-selector.d.ts

@@ -34,4 +34,3 @@ export declare function exactLabelSelector(body: ExactLabelSelectorBody): string
  * page function.
  */
 export declare const EXACT_LABEL_SELECTOR_ENGINE_SOURCE: string;
-//# sourceMappingURL=label-selector.d.ts.map

package/dist/label-selector.js

@@ -50,4 +50,3 @@ export const EXACT_LABEL_SELECTOR_ENGINE_SOURCE = `() => {${CLOSED_SHADOW_HELPER
   };
   return { queryAll, query: (root, selector) => queryAll(root, selector)[0] ?? null };
 }`;
-//# sourceMappingURL=label-selector.js.map

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;
@@ -73,4 +73,3 @@ export declare function applyPostSteps<T>(matches: readonly T[], steps: readonly
 /** Returns every frame selector along an expression, outermost first. */
 export declare function frameSelectors(expression: LocatorExpression): string[];
 export {};
-//# sourceMappingURL=locators.d.ts.map

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);
@@ -305,4 +317,3 @@ export function frameSelectors(expression) {
             return [expression.selector, ...frameSelectors(expression.source)];
     }
 }
-//# sourceMappingURL=locators.js.map

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 {
@@ -9,4 +9,3 @@ interface CaptureSettings {
 /** Captures under one deadline, retaining no refs from a failed or abandoned document. */
 export declare function captureObservation(page: Page, refs: RefRegistry, settings: CaptureSettings, operation: OperationContext, options: EngineObserveOptions | undefined): Promise<CapturedObservation>;
 export {};
-//# sourceMappingURL=observation-capture.d.ts.map

package/dist/observation-capture.js

@@ -90,4 +90,3 @@ export async function captureObservation(page, refs, settings, operation, option
         accepting = false;
     }
 }
-//# sourceMappingURL=observation-capture.js.map

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';
 /**
@@ -60,4 +60,3 @@ export interface CapturedDocument {
  */
 export declare function captureDocument(deps: CaptureDeps, host: DocumentHost, options: CaptureOptions): Promise<CapturedDocument>;
 export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
-//# sourceMappingURL=observation.d.ts.map

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,9 +272,8 @@ 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 } : {}),
     };
 }
-//# sourceMappingURL=observation.js.map

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
@@ -48,4 +48,3 @@ export declare function readPngSize(data: Uint8Array): {
     width: number;
     height: number;
 } | null;
-//# sourceMappingURL=observe.d.ts.map

package/dist/observe.js

@@ -102,4 +102,3 @@ export function readPngSize(data) {
         return null;
     return { width, height };
 }
-//# sourceMappingURL=observe.js.map

package/dist/operation-budget.d.ts

@@ -8,4 +8,3 @@ export interface ConnectionBudget {
 export declare function connectionAbort(signal: AbortSignal, label: string): EngineError;
 /** 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>;
-//# sourceMappingURL=operation-budget.d.ts.map

package/dist/operation-budget.js

@@ -37,4 +37,3 @@ export async function withConnectionBudget(budget, label, work) {
         clearTimeout(timer);
     }
 }
-//# sourceMappingURL=operation-budget.js.map

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>;
 /**
@@ -33,4 +49,3 @@ export declare function installSiteHeaders(context: BrowserContext, site: string
  * echoes its request headers shows that, not the password.
  */
 export declare function httpCredentials(basicAuth: WebBasicAuth, resolveSecret: (secret: Secret, options?: ResolveSecretOptions) => Promise<string>): Promise<PlaywrightHttpCredential>;
-//# sourceMappingURL=protected-app.d.ts.map

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);
     });
 }
@@ -46,7 +77,6 @@ export async function httpCredentials(basicAuth, resolveSecret) {
  */
 function basicCredentials(username, password) {
     const encoded = Buffer.from(`${username}:${password}`, 'utf8').toString('base64');
-    const unpadded = encoded.replace(/=+$/, '');
+    const unpadded = encoded.replace(/={1,2}$/, '');
     return unpadded === encoded ? [encoded] : [encoded, unpadded];
 }
-//# sourceMappingURL=protected-app.js.map

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';
@@ -45,4 +45,3 @@ export declare class ProviderVideo implements AttemptVideo {
     /** Ends one of the provider's recordings as a segment of the attempt. */
     private stopLease;
 }
-//# sourceMappingURL=provider-video.d.ts.map

package/dist/provider-video.js

@@ -77,4 +77,3 @@ export class ProviderVideo {
         });
     }
 }
-//# sourceMappingURL=provider-video.js.map

package/dist/provider.d.ts

@@ -250,4 +250,3 @@ export declare class LeasedBrowsers {
     private release;
     private releaseContext;
 }
-//# sourceMappingURL=provider.d.ts.map

package/dist/provider.js

@@ -442,4 +442,3 @@ export class LeasedBrowsers {
         return { runId: run.runId, targetName: run.targetName, env: run.env, signal, log: run.log };
     }
 }
-//# sourceMappingURL=provider.js.map

package/dist/read-node.d.ts

@@ -1,9 +1,10 @@
 /**
- * The wire types of the in-page semantic reader and the page functions
- * assembled from its source for locator.evaluate, locator.evaluateAll, and
- * page.evaluate. The reader itself lives in `in-page/read-semantics.ts`; it is
- * serialized into the page, so every page function here is built from its
- * source with `new Function` and stays free of module-scope captures.
+ * The wire types of the in-page semantic reader and the document walk
+ * assembled from its source for page.evaluate. The reader itself lives in
+ * `in-page/read-semantics.ts`; it is serialized into the page, so the page
+ * function here is built from its source with `new Function` and stays free
+ * of module-scope captures. Locator reads run it inside the selector engines
+ * (`read-selector.ts`, `label-selector.ts`).
  */
 /**
  * The one definition of a secure field.
@@ -47,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 {
@@ -80,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;
@@ -94,27 +100,12 @@ export type SemanticMode = {
     /** Cuts each node's text at this length; the caller owns the contract value. */
     textLimit: number;
 };
-/**
- * What a node read reports for an element no longer in its document. A
- * detached element has no boxes, so everything else it would report (hidden,
- * no labels) describes nothing on screen; its current value is still its own.
- */
-export interface DetachedNodeData {
-    readonly detached: true;
-    readonly value: string | null;
-}
 /** Result of one read, selected by the mode discriminant. */
 export type SemanticResult<Mode extends SemanticMode> = Mode extends {
     kind: 'node';
-} ? RawNodeData | DetachedNodeData : RawObservation;
-/** Options for a single-node read, shared by `evaluate` and `evaluateAll` callers. */
-interface NodeReadOptions {
-    readonly testIdAttribute: string;
-    readonly secureFieldSelector: string;
-    readonly mode: {
-        readonly kind: 'node';
-    };
-}
+} ? RawNodeData : Mode extends {
+    kind: 'hidden';
+} ? boolean : RawObservation;
 /** Options for one document's tree walk. */
 interface TreeReadOptions {
     readonly testIdAttribute: string;
@@ -125,28 +116,9 @@ interface TreeReadOptions {
 }
 /**
  * Walks a whole document from its root element in one in-page call. Built
- * from the reader's source like the batch reader below, so the caller
+ * from the reader's source, so the caller
  * evaluates it directly on a page or frame instead of first resolving a
  * `:root` locator - one fewer protocol round trip per document per capture.
  */
 export declare const readDocumentSemanticsFunction: (options: TreeReadOptions) => RawObservation;
-/**
- * Reads every matched element in one in-page round trip. A page function
- * cannot close over module scope, so the batch function is assembled from the
- * reader's own source (the same source `evaluate` sends) and is a
- * self-contained function Playwright serializes and calls with the elements.
- */
-export declare const readManySemanticsFunction: (elements: Element[], options: NodeReadOptions) => (RawNodeData | DetachedNodeData)[];
-/**
- * Reads every handle the caller already holds in one round trip, so what is
- * read and what is later acted on are the same elements by construction rather
- * than by a second lookup. Evaluated on the first handle so the read runs in
- * the frame the handles belong to; `page.evaluate` would reject handles taken
- * inside an iframe.
- */
-export declare const readHandlesSemanticsFunction: (first: Element, arg: {
-    elements: Element[];
-    options: NodeReadOptions;
-}) => (RawNodeData | DetachedNodeData)[];
 export {};
-//# sourceMappingURL=read-node.d.ts.map

package/dist/read-node.js

@@ -1,9 +1,10 @@
 /**
- * The wire types of the in-page semantic reader and the page functions
- * assembled from its source for locator.evaluate, locator.evaluateAll, and
- * page.evaluate. The reader itself lives in `in-page/read-semantics.ts`; it is
- * serialized into the page, so every page function here is built from its
- * source with `new Function` and stays free of module-scope captures.
+ * The wire types of the in-page semantic reader and the document walk
+ * assembled from its source for page.evaluate. The reader itself lives in
+ * `in-page/read-semantics.ts`; it is serialized into the page, so the page
+ * function here is built from its source with `new Function` and stays free
+ * of module-scope captures. Locator reads run it inside the selector engines
+ * (`read-selector.ts`, `label-selector.ts`).
  */
 import { readSemanticsFunction } from './in-page/read-semantics.js';
 /**
@@ -19,24 +20,8 @@ import { readSemanticsFunction } from './in-page/read-semantics.js';
 export const SECURE_FIELD_SELECTOR = 'input[type="password" i]';
 /**
  * Walks a whole document from its root element in one in-page call. Built
- * from the reader's source like the batch reader below, so the caller
+ * from the reader's source, so the caller
  * evaluates it directly on a page or frame instead of first resolving a
  * `:root` locator - one fewer protocol round trip per document per capture.
  */
 export const readDocumentSemanticsFunction = new Function('options', `return (${readSemanticsFunction.toString()})(document.documentElement, options);`);
-/**
- * Reads every matched element in one in-page round trip. A page function
- * cannot close over module scope, so the batch function is assembled from the
- * reader's own source (the same source `evaluate` sends) and is a
- * self-contained function Playwright serializes and calls with the elements.
- */
-export const readManySemanticsFunction = new Function('elements', 'options', `return elements.map((element) => (${readSemanticsFunction.toString()})(element, options));`);
-/**
- * Reads every handle the caller already holds in one round trip, so what is
- * read and what is later acted on are the same elements by construction rather
- * than by a second lookup. Evaluated on the first handle so the read runs in
- * the frame the handles belong to; `page.evaluate` would reject handles taken
- * inside an iframe.
- */
-export const readHandlesSemanticsFunction = new Function('_first', 'arg', `return arg.elements.map((element) => (${readSemanticsFunction.toString()})(element, arg.options));`);
-//# sourceMappingURL=read-node.js.map