@e2e-dev/web 0.11.2 → 0.12.0

package/dist/engine.js

@@ -10,6 +10,8 @@ import { createRequire } from 'node:module';
 import { asBrowserProvider } from './provider.js';
 import { PlaywrightSurface } from './surface.js';
 import { createBrowserFixture } from './browser.js';
+import { validateInitScripts } from './init-scripts.js';
+import { FIELD_VALUE_CONTROL, headerProblem } from './protected-app.js';
 /** App fields only a device target reads. */
 const NATIVE_APP_KEYS = ['bundleId', 'appPath', 'launchArguments', 'permissions'];
 /** Creates one Playwright engine: one browser per worker, one context per attempt. */
@@ -46,6 +48,12 @@ export function web(options = {}) {
         validateTestIdAttribute(options.testIdAttribute);
     if (options.userAgent !== undefined)
         validateUserAgent(options.userAgent, options.headers);
+    if (options.locale !== undefined)
+        validateLocale(options.locale, options.headers);
+    if (options.timezoneId !== undefined)
+        validateTimezoneId(options.timezoneId);
+    if (options.initScripts !== undefined)
+        validateInitScripts(options.initScripts);
     if (options.screencast !== undefined)
         validateScreencast(options.screencast);
     const reconnecting = options.connect?.reconnectEndpoint !== undefined;
@@ -55,8 +63,9 @@ export function web(options = {}) {
     // A per-attempt lease rides the same persistent context as `reconnectEndpoint`, with the same limits.
     const recoverable = reconnecting || provider?.scope === 'attempt';
     const mode = provider === undefined ? 'connect.reconnectEndpoint' : `browser provider "${provider.name}" with scope "attempt"`;
-    if (recoverable && (options.headers !== undefined || options.basicAuth !== undefined || options.userAgent !== undefined)) {
-        throw new ConfigurationError('INVALID_CONFIG', `${mode} uses a persistent context; headers, basicAuth, and userAgent require a newly created context`);
+    const creationOptions = CREATION_OPTION_KEYS.filter((key) => options[key] !== undefined);
+    if (recoverable && creationOptions.length > 0) {
+        throw new ConfigurationError('INVALID_CONFIG', `${mode} uses a persistent context; ${creationOptions.join(', ')} ${creationOptions.length === 1 ? 'requires' : 'require'} a newly created context`);
     }
     const surface = new PlaywrightSurface(options);
     const handle = defineEngine({
@@ -125,7 +134,12 @@ const WEB_OPTION_KEYS = Object.keys({
     basicAuth: true,
     testIdAttribute: true,
     userAgent: true,
+    locale: true,
+    timezoneId: true,
+    initScripts: true,
 });
+/** The options applied when the engine creates a browser context, which a persistent context never is. */
+const CREATION_OPTION_KEYS = ['headers', 'basicAuth', 'userAgent', 'locale', 'timezoneId'];
 /**
  * What a persistent context rules out, named with its cause: `what` replaces
  * the browser context, which `mode` never does. A per-attempt lease starts
@@ -135,11 +149,6 @@ function persistentContextLimit(what, mode, leased) {
     const remedy = leased ? '; every attempt already starts on a fresh browser, and scope "worker" can clear one mid-test' : '';
     return new ConfigurationError('UNSUPPORTED_CAPABILITY', `${what} is unavailable with ${mode}: it replaces the browser context, and the attempt rides one persistent context${remedy}`);
 }
-/** 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
-const FIELD_VALUE_CONTROL = /[\u0000-\u0008\u000A-\u001F\u007F]/;
 /** True for a plain object; the shape both options take. Config runs as JavaScript, so the types alone are no guard. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -155,15 +164,9 @@ function validateHeaders(headers) {
         throw new ConfigurationError('INVALID_CONFIG', 'web({ headers }) must be an object of header name to value');
     }
     for (const [name, value] of Object.entries(headers)) {
-        if (!HEADER_NAME.test(name)) {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) has an invalid header name: "${name}"`);
-        }
-        if (typeof value !== 'string') {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) header "${name}" must be a string, got ${typeof value}`);
-        }
-        if (FIELD_VALUE_CONTROL.test(value)) {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) header "${name}" must not contain a control character`);
-        }
+        const problem = headerProblem(name, value);
+        if (problem !== undefined)
+            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) ${problem}`);
     }
 }
 /** Refuses credentials the browser could not present: a missing field, or a `:` in the user name (RFC 7617). */
@@ -199,6 +202,61 @@ function validateUserAgent(userAgent, headers) {
         throw new ConfigurationError('INVALID_CONFIG', 'web({ userAgent }) and a user-agent header in web({ headers }) conflict; set userAgent only');
     }
 }
+/**
+ * Refuses a locale that is not a BCP 47 tag, and one an `accept-language`
+ * header would override on the app's site while `navigator.language` kept
+ * reporting it.
+ */
+function validateLocale(locale, headers) {
+    if (typeof locale !== 'string' || locale === '' || !isLanguageTag(locale)) {
+        throw new ConfigurationError('INVALID_CONFIG', `web({ locale }) must be a BCP 47 language tag such as "de-DE", got ${JSON.stringify(locale)}`);
+    }
+    if (headers !== undefined && Object.keys(headers).some((name) => name.toLowerCase() === 'accept-language')) {
+        throw new ConfigurationError('INVALID_CONFIG', 'web({ locale }) and an accept-language header in web({ headers }) conflict; set locale only');
+    }
+}
+/**
+ * True when `tag` names a language the browser can run in: a Unicode locale
+ * `Intl.Locale` parses, other than the undetermined `und`, which Chromium
+ * refuses at context creation as it does a private-use-only tag.
+ */
+function isLanguageTag(tag) {
+    try {
+        const { language } = new Intl.Locale(tag);
+        return language !== undefined && language !== 'und';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refuses, at config load, a time zone the browser would otherwise refuse at
+ * the first context. Best effort: Node cannot tell a miscased alias
+ * (`us/eastern`) from the real one, so the browser's own `Invalid timezone ID`
+ * stays the final word.
+ */
+function validateTimezoneId(timezoneId) {
+    if (typeof timezoneId !== 'string' || timezoneId === '' || !isTimeZone(timezoneId)) {
+        throw new ConfigurationError('INVALID_CONFIG', `web({ timezoneId }) must be an IANA time zone such as "Europe/Berlin", got ${JSON.stringify(timezoneId)}`);
+    }
+}
+/**
+ * True when `timeZone` is an IANA name `Intl` resolves, spelled with its own
+ * case. Node also takes an offset (`+01:00`) and any casing (`europe/berlin`),
+ * both of which Chromium refuses; an alias resolving to another name
+ * (`US/Eastern`) is fine.
+ */
+function isTimeZone(timeZone) {
+    if (/^[+-]/.test(timeZone))
+        return false;
+    try {
+        const resolved = new Intl.DateTimeFormat('en-US', { timeZone }).resolvedOptions().timeZone;
+        return resolved === timeZone || resolved.toLowerCase() !== timeZone.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * An attribute name the document grammar accepts (XML `Name`, ASCII): a value
  * outside it could never be on an element, so `getByTestId` would match nothing

package/dist/evaluation.d.ts

@@ -5,6 +5,8 @@ type EvaluationResult = {
     ok: false;
     message: string;
 };
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
+export declare const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
  *

package/dist/evaluation.js

@@ -1,6 +1,8 @@
 /** Separates exceptions thrown by trusted page code from failures of the evaluation transport. */
 import { TestError } from 'e2e/engine';
 import { message } from './support.js';
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
+export const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
  *
@@ -13,7 +15,7 @@ export function compileEvaluation(source, hasArgument) {
     try {
         return new Function('arg', `
       return (async () => {
-        const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });
+        ${KEEP_NAMES_HELPER}
         try {
           return { ok: true, value: await (${source}\n)(${hasArgument ? 'arg' : ''}) };
         } catch (cause) {

package/dist/in-page/read-semantics.d.ts

@@ -13,6 +13,7 @@ import type { SemanticMode, SemanticResult } from '../read-node.ts';
  * `mode.kind === 'node'` reads exactly one element for locator reads, in
  * the selector engine's task that found it (`read-selector.ts`,
  * `label-selector.ts`), so the element is always in its document.
+ * `mode.kind === 'hidden'` answers that one element's `states.hidden` alone.
  * `mode.kind === 'tree'` walks the subtree for one agent observation and
  * returns live element handles aligned with the flattened node list. The two
  * modes also project nodes differently; those differences are data (see

package/dist/in-page/read-semantics.js

@@ -12,6 +12,7 @@
  * `mode.kind === 'node'` reads exactly one element for locator reads, in
  * the selector engine's task that found it (`read-selector.ts`,
  * `label-selector.ts`), so the element is always in its document.
+ * `mode.kind === 'hidden'` answers that one element's `states.hidden` alone.
  * `mode.kind === 'tree'` walks the subtree for one agent observation and
  * returns live element handles aligned with the flattened node list. The two
  * modes also project nodes differently; those differences are data (see
@@ -54,8 +55,10 @@ export const readSemanticsFunction = (element, options) => {
     /**
      * How the active mode projects one node, expressed as data so `describe`
      * stays branch-free. Tree mode is the model-bound projection: bounded text,
-     * a bounded attribute projection, hrefs reduced to origin+path, and the root
-     * document named by its title. Node mode is the full locator-read surface.
+     * a bounded attribute projection, hrefs reduced to origin+path, the root
+     * document named by its title, and no value on a checkbox or radio, whose
+     * value attribute is an app token its checked state already says more
+     * than. Node mode is the full locator-read surface.
      */
     const projection = options.mode.kind === 'tree'
         ? {
@@ -65,6 +68,7 @@ export const readSemanticsFunction = (element, options) => {
             redactHref: true,
             directTextOnly: true,
             documentRoot: true,
+            checkableValue: false,
         }
         : {
             attributes: null,
@@ -73,6 +77,7 @@ export const readSemanticsFunction = (element, options) => {
             redactHref: false,
             directTextOnly: false,
             documentRoot: false,
+            checkableValue: true,
         };
     /**
      * Per-element memo for the facts several passes need. A tree walk asks for
@@ -262,11 +267,11 @@ export const readSemanticsFunction = (element, options) => {
     /** Computed style of any element, SVG included, or undefined in a document with no view. */
     const styleOf = (el) => el.ownerDocument.defaultView?.getComputedStyle(el);
     /** A walk from the top, with the elements that may not contribute again already visited. */
-    const nameWalk = (visited, generated) => ({
+    const nameWalk = (visited, accessible) => ({
         inReference: false,
         hiddenAllowed: false,
         visited: new Set(visited),
-        generated,
+        accessible,
     });
     /**
      * Private-use code points: icon-font glyphs (Font Awesome's `\f090`) that
@@ -415,21 +420,86 @@ export const readSemanticsFunction = (element, options) => {
                 inReference: true,
                 hiddenAllowed: isReferenceHidden(target),
                 visited: walk.visited,
-                generated: walk.generated,
+                accessible: walk.accessible,
             }));
         }
         if (contributions.join(' ') === '')
             return null;
         return contributions.map((text) => text.replace(/\s+/g, ' ').trim()).filter((name) => name !== '');
     };
+    /**
+     * What an embedded control contributes to a name computed through another
+     * element (accname 2C), by the rules Playwright's role selector applies, so
+     * `<button>Flash the screen <input value="3"> times</button>` is the button
+     * "Flash the screen 3 times": a textbox or searchbox its current value (an
+     * editable element its text), a combobox or listbox its selected options'
+     * names (a native select with none selected its first option, a text field
+     * with none its value), and a range widget its `aria-valuetext`, else its
+     * `aria-valuenow`, else its `value` attribute. A menu contributes nothing,
+     * and neither does a secure field, whose value no name may carry. Null for
+     * any other element, and for one its own `aria-labelledby` names, which is
+     * named, not embedded.
+     */
+    const embeddedControlNameOf = (el, walk) => {
+        const role = implicitRole(el);
+        if (role === null)
+            return null;
+        if (el.id !== '' && (el.getAttribute('aria-labelledby') ?? '').trim().split(/\s+/).indexOf(el.id) !== -1)
+            return null;
+        if (el.matches(options.secureFieldSelector))
+            return '';
+        if (role === 'textbox' || role === 'searchbox') {
+            return el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement ? el.value : el.textContent ?? '';
+        }
+        if (role === 'combobox' || role === 'listbox') {
+            let selected;
+            if (el instanceof HTMLSelectElement) {
+                selected = Array.from(el.selectedOptions);
+                if (selected.length === 0 && el.options.length > 0)
+                    selected.push(el.options[0]);
+            }
+            else {
+                const listbox = role === 'combobox' ? ariaOwnedOf(el).find((owned) => implicitRole(owned) === 'listbox') : el;
+                selected = listbox === undefined
+                    ? []
+                    : ariaOwnedOf(listbox).filter((owned) => owned.getAttribute('aria-selected') === 'true' && implicitRole(owned) === 'option');
+            }
+            if (selected.length === 0 && el instanceof HTMLInputElement)
+                return el.value;
+            return selected.map((option) => contentNameOf(option, styleOf(option), walk)).join(' ');
+        }
+        if (role === 'progressbar' || role === 'scrollbar' || role === 'slider' || role === 'spinbutton' || role === 'meter') {
+            if (el.hasAttribute('aria-valuetext'))
+                return el.getAttribute('aria-valuetext') ?? '';
+            if (el.hasAttribute('aria-valuenow'))
+                return el.getAttribute('aria-valuenow') ?? '';
+            return el.getAttribute('value') ?? '';
+        }
+        return role === 'menu' ? '' : null;
+    };
+    /**
+     * Every element under `el` and every element its `aria-owns` names, with
+     * theirs: what a composite widget owns, as Playwright's role selector
+     * collects a combobox's listbox and a listbox's options.
+     */
+    const ariaOwnedOf = (el) => {
+        const owned = Array.from(el.querySelectorAll('*'));
+        for (const id of (el.getAttribute('aria-owns') ?? '').trim().split(/\s+/)) {
+            const target = id === '' ? null : referencedElementOf(el, id);
+            if (target !== null)
+                owned.push(target, ...Array.from(target.querySelectorAll('*')));
+        }
+        return owned;
+    };
     /**
      * What one element contributes to a name computed through another: as an
      * aria-labelledby target (accname 2B) or as a descendant read for name from
-     * content (2F). Its own references, else its `aria-label`, its `alt`, its
-     * children, then its `title`. So `<button><img alt="Search"></button>` is
-     * the button "Search", an icon whose only child is
+     * content (2F). Its own references, else its value as an embedded control,
+     * its `aria-label`, its `alt`, its children, then its `title`. So
+     * `<button><img alt="Search"></button>` is the button "Search", an icon
+     * whose only child is
      * `<svg aria-labelledby="t"><title id="t">Close</title></svg>` is "Close",
-     * and a hidden `<span>` a button references still names it. A form
+     * and a hidden `<span>` a button references still names it. Any other form
      * control's content is its value, not label text, so it contributes nothing.
      * The title is the fallback only for empty content, untrimmed as Playwright
      * reads it: the spaces a block-level child adds count, so a flex container's
@@ -445,6 +515,9 @@ export const readSemanticsFunction = (element, options) => {
         const referenced = referencedNamesOf(el, walk);
         if (referenced !== null)
             return referenced.join(' ');
+        const embedded = walk.accessible ? embeddedControlNameOf(el, walk) : null;
+        if (embedded !== null)
+            return embedded;
         const ariaLabel = el.getAttribute('aria-label');
         if (ariaLabel !== null && ariaLabel.trim() !== '')
             return ariaLabel.trim();
@@ -469,7 +542,7 @@ export const readSemanticsFunction = (element, options) => {
      * `.next::after { content: " \2192" }` is the button "Go →".
      */
     const childrenNameOf = (el, walk) => {
-        let out = walk.generated ? beforeContentOf(el) : '';
+        let out = walk.accessible ? beforeContentOf(el) : '';
         for (const child of contentChildrenOf(el)) {
             if (child.nodeType === 3) {
                 out += child.nodeValue ?? '';
@@ -482,7 +555,7 @@ export const readSemanticsFunction = (element, options) => {
             const block = child.tagName === 'BR' || (style?.display ?? 'inline') !== 'inline';
             out += block ? ` ${token} ` : token;
         }
-        return walk.generated ? out + afterContentOf(el) : out;
+        return walk.accessible ? out + afterContentOf(el) : out;
     };
     /**
      * The nodes a name from content reads under an element, in the order the
@@ -516,15 +589,17 @@ export const readSemanticsFunction = (element, options) => {
      * its descendants' contributions, hidden and aria-hidden subtrees dropped (a
      * required-field marker, a decorative glyph), whitespace collapsed. The
      * element's own attributes are `accessibleName`'s business; this reads what
-     * is inside it. `generated` reads CSS generated content too, as an
-     * accessible name does and label text does not.
+     * is inside it. `accessible` reads CSS generated content and embedded
+     * controls' values too, as an accessible name does and label text does not.
+     * `named` is the element the text names when that is not `el` (a control
+     * read through its `<label>`), which never contributes to its own name.
      */
-    const nameTextOf = (el, generated) => {
+    const nameTextOf = (el, accessible, named = el) => {
         if (isNameHidden(el, styleOf(el)))
             return '';
         if (NAME_OPAQUE_TAGS.has(el.tagName))
             return '';
-        return childrenNameOf(el, nameWalk([el], generated)).replace(/\s+/g, ' ').trim();
+        return childrenNameOf(el, nameWalk([el, named], accessible)).replace(/\s+/g, ' ').trim();
     };
     const NAME_OPAQUE_TAGS = new Set(['TEXTAREA', 'SELECT', 'INPUT', 'SCRIPT', 'STYLE']);
     /**
@@ -578,8 +653,14 @@ export const readSemanticsFunction = (element, options) => {
         const shown = labels.map(withoutGlyphs).filter((label) => label !== '');
         return shown.length === 0 ? null : shown;
     };
-    /** Text owned directly by an element, excluding descendant elements. */
+    /**
+     * Text owned directly by an element, excluding descendant elements. An
+     * element with `content-visibility: hidden` renders none of it, as its
+     * `innerText` reads empty, so it owns none.
+     */
     const directTextOf = memoized((el) => {
+        if (styleOf(el)?.getPropertyValue('content-visibility') === 'hidden')
+            return '';
         let out = '';
         for (const child of Array.from(el.childNodes)) {
             if (child.nodeType === 3)
@@ -598,7 +679,7 @@ export const readSemanticsFunction = (element, options) => {
         const labels = associatedLabels(el);
         if (labels.length > 0) {
             const joined = labels
-                .map((label) => nameTextOf(label, true))
+                .map((label) => nameTextOf(label, true, el))
                 .join(' ')
                 .trim();
             if (joined !== '')
@@ -752,25 +833,42 @@ export const readSemanticsFunction = (element, options) => {
         return false;
     };
     /**
-     * The visibility Playwright's `toBeHidden` reads, so a semantic `hidden`
-     * state and the platform's own filter agree: `aria-hidden` on the element,
+     * True when an ancestor in the flat tree has `content-visibility: hidden`:
+     * it keeps its own box and skips rendering everything under it, slotted
+     * and shadow content included, as `checkVisibility()` reads it. Memoized,
+     * so siblings under one ancestor share the walk up.
+     */
+    const isSkippedContent = memoized((el) => {
+        const parent = el.assignedSlot ?? parentOrHostOf(el);
+        if (parent === null)
+            return false;
+        return styleOf(parent)?.getPropertyValue('content-visibility') === 'hidden' || isSkippedContent(parent);
+    });
+    /**
+     * Render visibility, the one Playwright's `toBeVisible` and `toBeHidden`
+     * read, so a semantic `hidden` state and the platform's own filter agree:
      * `display: none` or a `visibility` other than `visible` on any element (an
-     * SVG included), content a closed `<details>` folds away, and a box with no
-     * width or no height. `display: contents` generates no box of its own while
-     * every child still paints (Shopify's one-page checkout form is one), so
-     * such an element is shown when some child element or text is, and hidden
-     * when nothing under it is.
+     * SVG included), content a `content-visibility: hidden` ancestor skips or a
+     * closed `<details>` folds away, and a box with no width or no height.
+     * `aria-hidden` is not in it: it removes a node from the accessibility tree
+     * (`hidesSubtree`, a role query) while the node still paints, as a spinner
+     * marked decorative does. `display: contents` generates no box of its own
+     * while every child still paints (Shopify's one-page checkout form is one),
+     * so such an element is shown when some child element or text is, and
+     * hidden when nothing under it is. Its text paints in its own `visibility`,
+     * which a range's box does not reflect, so text under a hidden one is
+     * hidden, where Playwright calls it visible.
      */
     const isHidden = (el, style = styleOf(el)) => {
-        if (el.getAttribute('aria-hidden') === 'true')
-            return true;
         if (style === undefined)
             return true;
+        if (isSkippedContent(el))
+            return true;
         if (style.display === 'contents') {
             for (let child = el.firstChild; child !== null; child = child.nextSibling) {
                 if (child instanceof Element && !isHidden(child))
                     return false;
-                if (child.nodeType === Node.TEXT_NODE && isVisibleText(child))
+                if (child.nodeType === Node.TEXT_NODE && style.visibility === 'visible' && isVisibleText(child))
                     return false;
             }
             return true;
@@ -783,18 +881,20 @@ export const readSemanticsFunction = (element, options) => {
         return !(rect.width > 0 && rect.height > 0);
     };
     /**
-     * The part of `isHidden` that holds for everything under the element too,
-     * which is what lets the tree walk stop there. A box with no size is not in
-     * it: a zero-height `<html>` or wrapper still shows the fixed, absolute, and
-     * overflowing descendants laid out past its edges, so the walk goes on
-     * through it and only the element itself stays unlisted. An inert element
-     * is in it too (`isInert`).
+     * What takes the element and everything under it out of the tree walk: an
+     * `aria-hidden` or inert subtree, which the accessibility tree drops though
+     * it may paint (`isInert`), and `display: none` or a closed `<details>`
+     * body, which no descendant can undo. A `visibility` other than `visible`
+     * is not in it, since a descendant may set `visibility: visible` and paint
+     * again; nor is a box with no size: a zero-height `<html>` or wrapper still
+     * shows the fixed, absolute, and overflowing descendants laid out past its
+     * edges. The walk goes on through both and only the element itself stays
+     * unlisted.
      */
     const hidesSubtree = (el, style) => el.getAttribute('aria-hidden') === 'true' ||
         isInert(el, style) ||
         style === undefined ||
         style.display === 'none' ||
-        (style.display !== 'contents' && style.visibility !== 'visible') ||
         isInClosedDetails(el);
     /**
      * Inert content takes no input and is hidden from assistive technology, as
@@ -1034,9 +1134,13 @@ export const readSemanticsFunction = (element, options) => {
         let checked = null;
         let selectedState = null;
         if (el instanceof HTMLInputElement) {
-            if (el.type === 'checkbox' || el.type === 'radio')
+            // A checkbox or radio submits its value attribute (`on` by default)
+            // whatever its checked state, so a locator read reports both; the tree
+            // drops that token as it drops an option's.
+            const checkable = el.type === 'checkbox' || el.type === 'radio';
+            if (checkable)
                 checked = el.checked;
-            else
+            if (!checkable || projection.checkableValue)
                 value = el.value;
         }
         else if (el instanceof HTMLTextAreaElement) {
@@ -1134,7 +1238,10 @@ export const readSemanticsFunction = (element, options) => {
         const isDocumentRoot = projection.documentRoot && tag === 'html';
         if (isDocumentRoot)
             name = el.ownerDocument.title;
-        const rect = el.getBoundingClientRect();
+        // No layout box at all (`display: none`, an empty `display: contents`) is
+        // no rect, as Playwright's `boundingBox()` answers null; a box with no
+        // size, or one `visibility: hidden` keeps, is still a rect.
+        const rect = el.getClientRects().length === 0 ? null : el.getBoundingClientRect();
         const role = isDocumentRoot ? 'document' : roleOf(el, tag);
         let level = null;
         if (role === 'heading') {
@@ -1168,11 +1275,13 @@ export const readSemanticsFunction = (element, options) => {
             level,
             attributes,
             testId: el.getAttribute(options.testIdAttribute),
-            rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            rect: rect === null ? null : { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
         };
     };
     // The conditional return type resolves per call site; inside the body the
-    // discriminant narrows the value but not the generic, hence the two casts.
+    // discriminant narrows the value but not the generic, hence the casts.
+    if (options.mode.kind === 'hidden')
+        return isHidden(element);
     if (options.mode.kind === 'node') {
         return describe(element);
     }
@@ -1280,6 +1389,9 @@ export const readSemanticsFunction = (element, options) => {
         }
         if (OPAQUE_TAGS.indexOf(tag) !== -1)
             return;
+        // The element keeps its box, and nothing under it renders (`isSkippedContent`).
+        if (style?.getPropertyValue('content-visibility') === 'hidden')
+            return;
         for (const child of Array.from(el.children))
             walk(child, nextParent);
         // A shadow root is part of what the user sees, so it is part of what the

package/dist/index.d.ts

@@ -8,10 +8,11 @@ import type { Browser } from './browser.ts';
 export { web, surfaceOf } from './engine.ts';
 export type { PlaywrightLiveSurface } from './engine.ts';
 export type { WebBasicAuth, WebConnectOptions, WebOptions, WebScreencastOptions } from './surface.ts';
+export type { WebInitScript } from './init-scripts.ts';
 export type { BrowserDownloadContext, BrowserLease, BrowserProvider, BrowserProviderDownloads, BrowserProviderScope, BrowserReleaseContext, BrowserRequest, } from './provider.ts';
 export type { BrowserName } from './browser-connection.ts';
 export type { Dialog, DialogHandler } from './dialogs.ts';
-export type { Browser, BrowserExpectation, Cookie, CookieFields, FrameScreen, RouteFulfillResponse, WebResponse, WebRoute, } from './browser.ts';
+export type { Browser, BrowserExpectation, Cookie, CookieFields, FrameScreen, RouteContinueOverrides, RouteFulfillResponse, WebResponse, WebRoute, } from './browser.ts';
 /**
  * `test` typed with this engine's contributed `browser` fixture. The same
  * runtime `test` as `e2e`'s; only the fixture types differ.

package/dist/init-scripts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One init script: a string of JavaScript source, a `{ path }` to a file of
+ * it relative to the project root, or a function serialized into the page,
+ * which can close over nothing from the test process.
+ */
+export type WebInitScript = string | {
+    readonly path: string;
+} | (() => unknown);
+/** Refuses, at config load, a `web({ initScripts })` value that is not a list of scripts. */
+export declare function validateInitScripts(scripts: unknown): void;
+/** The configured `initScripts`, read into page source once per process and handed to each attempt as the start of its own list. */
+export declare class ConfiguredInitScripts {
+    private readonly scripts;
+    private sources;
+    constructor(scripts: readonly WebInitScript[]);
+    /** Reads every script, a `path` against the project root; a file that cannot be read is `INVALID_CONFIG`. */
+    load(projectRoot: string): Promise<void>;
+    /** A new attempt's init scripts: the configured ones, to which `browser.addInitScript` appends. */
+    forAttempt(): string[];
+}
+/**
+ * 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 declare function testInitScriptSource(script: unknown, argument: {
+    readonly arg: unknown;
+} | undefined, resolvePath: (file: string) => string): Promise<string>;
+/** The step label of a script: the file a `path` names, else its kind, never its source. */
+export declare function initScriptLabel(script: unknown): string;