@e2e-dev/web 0.11.2 → 0.13.0

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
@@ -214,7 +219,21 @@ export const readSemanticsFunction = (element, options) => {
             }
             case 'th': {
                 const scope = (el.getAttribute('scope') ?? '').toLowerCase();
-                return scope === 'row' || scope === 'rowgroup' ? 'rowheader' : 'columnheader';
+                if (scope === 'row' || scope === 'rowgroup')
+                    return 'rowheader';
+                if (scope === 'col' || scope === 'colgroup')
+                    return 'columnheader';
+                const previous = el.previousElementSibling;
+                const next = el.nextElementSibling;
+                if (previous === null && next === null) {
+                    const row = el.parentElement;
+                    const table = row?.tagName.toLowerCase() === 'tr' ? row.closest('table') : null;
+                    return table !== null && table.rows.length <= 1 ? null : 'columnheader';
+                }
+                if (previous?.tagName.toLowerCase() === 'th' && next?.tagName.toLowerCase() === 'th')
+                    return 'columnheader';
+                const hasDataNeighbor = [previous, next].some((cell) => cell?.tagName.toLowerCase() === 'td' && ((cell.textContent ?? '').trim() !== '' || cell.children.length > 0));
+                return hasDataNeighbor ? 'rowheader' : 'columnheader';
             }
             case 'dialog':
                 return 'dialog';
@@ -262,11 +281,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 +434,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 +529,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 +556,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 +569,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 +603,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 +667,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 +693,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 +847,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 +895,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 +1148,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 +1252,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 +1289,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 +1403,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;

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. */
@@ -8,6 +15,8 @@ export interface InstallContext {
     readonly signal?: AbortSignal | undefined;
     /** Environment the installer runs with: the run's, so it fills the cache the workers will launch from. */
     readonly env: NodeJS.ProcessEnv;
+    /** Whether the run launches a window, which decides the chromium build it needs. */
+    readonly headed: boolean;
 }
 export interface EnsureBrowsersOptions {
     /**
@@ -27,10 +36,14 @@ export interface EnsureBrowsersOptions {
     readonly signal?: AbortSignal;
     /** The run's environment; defaults to this process's. */
     readonly env?: NodeJS.ProcessEnv;
+    /** Whether the run launches a window, which decides the chromium build it needs. Defaults to false. */
+    readonly headed?: boolean;
 }
+/** The `playwright install` arguments for `names`: `--only-shell` on a headless chromium run. */
+export declare function installArgs(names: readonly BrowserName[], headed: boolean): string[];
 /**
  * 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