@e2edev/web 0.11.0-canary-20260921180210

package/dist/install.d.ts

@@ -0,0 +1,40 @@
+/** First-run browser provisioning for the Playwright engine. */
+import { type BrowserName } from './browser-connection.ts';
+/** What an installer receives besides the browser names. */
+export interface InstallContext {
+    /** Receives every line the installer prints: the download URL, progress, warnings. */
+    readonly log: (line: string) => void;
+    /** Aborts a download in progress. */
+    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;
+}
+export interface EnsureBrowsersOptions {
+    /**
+     * Receives progress lines; defaults to stderr. The engine's `prepare` hands
+     * the harness's `info.log` here, so a first-run download narrates through
+     * the reporter rather than underneath it.
+     */
+    readonly log?: (line: string) => void;
+    /**
+     * Injected detection for tests; defaults to an executable existence check.
+     * Undefined means "cannot tell here": the installer runs and decides.
+     */
+    readonly isInstalled?: (name: BrowserName) => boolean | undefined;
+    /** Injected installer for tests; defaults to spawning the Playwright CLI. */
+    readonly install?: (names: readonly BrowserName[], context: InstallContext) => Promise<void>;
+    /** Aborts a download in progress; the run's interrupt owns it. */
+    readonly signal?: AbortSignal;
+    /** The run's environment; defaults to this process's. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Ensures the given Playwright browsers are installed, downloading any
+ * missing ones via `playwright 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
+ * them with a registry lock.
+ */
+export declare function ensureBrowsersInstalled(names: readonly BrowserName[], options?: EnsureBrowsersOptions): Promise<void>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAOhE,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAyBxE,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,0GAA0G;IAC1G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,CAAC;IAClE,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/install.js

@@ -0,0 +1,117 @@
+/** First-run browser provisioning for the Playwright engine. */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { EngineError, InfrastructureError } from 'e2e/engine';
+import { browserType } from './browser-connection.js';
+/**
+ * Whether the browser's executable exists on disk, or undefined when this
+ * process cannot tell. Playwright resolves its browser cache from
+ * `PLAYWRIGHT_BROWSERS_PATH` at module load, so the in-process check is only
+ * authoritative when the run's environment agrees with this process's. A run
+ * pointed at another cache is left to the CLI, which resolves against the
+ * environment it is spawned with and is a no-op when nothing is missing.
+ */
+function isBrowserInstalled(name, env) {
+    if (env['PLAYWRIGHT_BROWSERS_PATH'] !== process.env['PLAYWRIGHT_BROWSERS_PATH'])
+        return undefined;
+    try {
+        return existsSync(browserType(name).executablePath());
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolves the `playwright` CLI entry point relative to this package. */
+function playwrightCliPath() {
+    const require = createRequire(import.meta.url);
+    return path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
+}
+/**
+ * Ensures the given Playwright browsers are installed, downloading any
+ * missing ones via `playwright 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
+ * them with a registry lock.
+ */
+export async function ensureBrowsersInstalled(names, options = {}) {
+    const env = options.env ?? process.env;
+    const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env));
+    const verdicts = new Map([...new Set(names)].map((name) => [name, isInstalled(name)]));
+    const missing = [...verdicts.keys()].filter((name) => verdicts.get(name) !== true);
+    if (missing.length === 0)
+        return;
+    // The headline is only honest when every listed browser is known to be
+    // absent; when the verdict is the CLI's, its own output tells the story
+    // and says nothing when there is nothing to fetch.
+    const knownMissing = missing.every((name) => verdicts.get(name) === false);
+    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    if (knownMissing)
+        log(`Downloading missing Playwright browsers (first run): ${missing.join(', ')}...`);
+    const install = options.install ?? runPlaywrightInstall;
+    await install(missing, { log, signal: options.signal, env });
+    if (knownMissing)
+        log('Browser download complete.');
+}
+/**
+ * Forwards a child's stdout or stderr to `log` one complete line at a time.
+ * The Playwright CLI redraws its progress bar with carriage returns when it
+ * has a terminal; with a pipe it prints whole lines, but the splitter accepts
+ * both so no partial redraw ever reaches the reporter.
+ */
+function forwardLines(stream, log) {
+    let pending = '';
+    const flush = (text) => {
+        for (const line of text.split(/\r\n|\n|\r/)) {
+            const trimmed = line.trimEnd();
+            if (trimmed !== '')
+                log(trimmed);
+        }
+    };
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        pending += chunk;
+        const cut = Math.max(pending.lastIndexOf('\n'), pending.lastIndexOf('\r'));
+        if (cut === -1)
+            return;
+        flush(pending.slice(0, cut + 1));
+        pending = pending.slice(cut + 1);
+    });
+    stream.on('end', () => flush(pending));
+}
+/** Spawns `node <playwright>/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], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env,
+        });
+        forwardLines(child.stdout, log);
+        forwardLines(child.stderr, log);
+        const onAbort = () => {
+            child.kill();
+            reject(new EngineError('CANCELLED', 'browser install cancelled', { retryable: false }));
+        };
+        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}`, {
+                cause,
+            }));
+        });
+        child.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new InfrastructureError('BROWSER_INSTALL_FAILED', `playwright install ${names.join(' ')} exited with code ${String(code)}; run "npx playwright install ${names.join(' ')}" manually`));
+        });
+    });
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/locators.d.ts

@@ -0,0 +1,74 @@
+/** LocatorExpression -> Playwright locator projection. */
+import type { Locator as PwLocator, Page } from 'playwright';
+import { type LocatorExpression, type TextPattern } from 'e2e/engine';
+/** One positional step applied after display-value filtering. */
+export type PositionalStep = 'first' | 'last' | number;
+type PwFilterOptions = NonNullable<Parameters<PwLocator['filter']>[0]>;
+/**
+ * One step a display-value projection applies after its candidates are
+ * value-filtered, in expression order: a position among the matches, or a
+ * per-element filter that came after a position and so could not compose onto
+ * the candidate locator.
+ */
+export type PostStep = {
+    readonly kind: 'index';
+    readonly index: PositionalStep;
+} | {
+    readonly kind: 'filter';
+    readonly options: PwFilterOptions;
+};
+export interface ProjectedLocator {
+    /**
+     * The Playwright locator to resolve. For a display-value query this is the
+     * candidate set (every form control in scope), not the matches: Playwright
+     * has no selector for a control's current value, so the value predicate can
+     * only run after the candidates are read.
+     */
+    readonly locator: PwLocator;
+    /** Non-null when the terminal query filters by display value. */
+    readonly displayValue: TextPattern | null;
+    /**
+     * Non-null when the terminal query is an exact label query: `locator` holds
+     * every labelable control in scope and the surface keeps those with an
+     * associated label (an `aria-label`, an `aria-labelledby` target, or a
+     * `<label>`) whose accessible-name text equals the pattern. Playwright's own
+     * `getByLabel` reads a label's full text, aria-hidden included, so a
+     * required-field marker made `getByLabel('Display name')` miss
+     * `Display name*`; the engine's reader drops such text.
+     */
+    readonly name: TextPattern | null;
+    /**
+     * The Playwright locator to compose with as a scope or `has` filter, for a
+     * projection whose own predicate lives outside Playwright's chain. An exact
+     * label query composes through Playwright's substring label match, which
+     * accepts every control the predicate would and some it would not; that is
+     * the one place the predicate is approximated. Null for a display-value
+     * projection, which has no such equivalent and is rejected instead.
+     */
+    readonly composable: PwLocator | null;
+    /**
+     * Steps to apply to the value-filtered matches, innermost first. Always
+     * empty when `displayValue` is null, because the projection then composes
+     * positions and filters natively onto the locator.
+     */
+    readonly steps: readonly PostStep[];
+    /**
+     * True when the terminal query keeps only nodes whose `hidden` state is
+     * false. The surface applies it to the batch read before the display-value
+     * predicate and any post step, so a position is taken among shown matches.
+     */
+    readonly visible: boolean;
+}
+/** Projects an expression onto the page; `testIdAttribute` is what a `testId` query reads. */
+export declare function projectExpression(page: Page, expression: LocatorExpression, testIdAttribute: string): ProjectedLocator;
+/**
+ * Applies post steps, innermost first, to an ordered list of matches. `nth`
+ * past the end selects nothing, matching Playwright's `nth` on a locator with
+ * too few matches. A filter step keeps the matches `passesFilter` accepts;
+ * it runs only on the matches that survived the steps before it.
+ */
+export declare function applyPostSteps<T>(matches: readonly T[], steps: readonly PostStep[], passesFilter: (match: T, options: PwFilterOptions) => Promise<boolean>): Promise<readonly T[]>;
+/** 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.d.ts","sourceRoot":"","sources":["../src/locators.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAE1D,OAAO,KAAK,EAAgB,OAAO,IAAI,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAe,KAAK,iBAAiB,EAAsB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAiFvG,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,KAAK,eAAe,GAAG,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAyBnE,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAsGD,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,iBAAiB,EAC7B,eAAe,EAAE,MAAM,GACtB,gBAAgB,CAElB;AAkBD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,GACrE,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAiBvB;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAYtE"}

package/dist/locators.js

@@ -0,0 +1,260 @@
+/** LocatorExpression -> Playwright locator projection. */
+import { EngineError } from 'e2e/engine';
+function patternToPw(pattern) {
+    if (pattern.kind === 'regexp')
+        return new RegExp(pattern.source, pattern.flags);
+    return pattern.value;
+}
+function patternExact(pattern) {
+    return pattern.kind === 'string' ? pattern.exact : false;
+}
+/**
+ * The selector `getByTestId` compiles to, with the project's attribute in
+ * place of Playwright's process-global one (`selectors.setTestIdAttribute`
+ * would leak one engine's attribute into every other engine of the process).
+ * The value is encoded as Playwright's `escapeForAttributeSelector` encodes it:
+ * a string is an exact, case-sensitive match; a RegExp is passed as written.
+ */
+function testIdSelector(attribute, pattern) {
+    const name = attribute.includes(',') ? JSON.stringify(attribute) : attribute;
+    const value = pattern.kind === 'regexp'
+        ? escapeRegexForSelector(new RegExp(pattern.source, pattern.flags))
+        : `"${pattern.value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"s`;
+    return `internal:testid=[${name}=${value}]`;
+}
+/** A RegExp written into a Playwright selector: quotes and `>>` escaped unless the flags forbid it. */
+function escapeRegexForSelector(re) {
+    if (/[uv]/.test(re.flags))
+        return String(re);
+    return String(re)
+        .replace(/(^|[^\\])(\\\\)*(["'`])/g, '$1$2\\$3')
+        .replace(/>>/g, '\\>\\>');
+}
+/**
+ * The contract's role vocabulary spelled as the ARIA role the role selector
+ * knows, where the two differ: the tree reports an `img` as `image`, so an
+ * `image` query has to go back to `img` to match it.
+ */
+const ARIA_ROLE_BY_CONTRACT_ROLE = { image: 'img' };
+function queryToPw(scope, query, testIdAttribute) {
+    switch (query.kind) {
+        case 'role': {
+            if (query.value.kind !== 'string') {
+                throw new EngineError('ENGINE_FAILURE', 'role query value must be a string', {
+                    retryable: false,
+                });
+            }
+            const options = {};
+            if (query.name !== undefined) {
+                options.name = patternToPw(query.name);
+                if (query.name.kind === 'string')
+                    options.exact = query.name.exact;
+            }
+            const states = query.states ?? {};
+            if (states.checked !== undefined)
+                options.checked = states.checked;
+            if (states.disabled !== undefined)
+                options.disabled = states.disabled;
+            if (states.selected !== undefined)
+                options.selected = states.selected;
+            if (states.expanded !== undefined)
+                options.expanded = states.expanded;
+            if (states.pressed !== undefined)
+                options.pressed = states.pressed;
+            if (query.level !== undefined)
+                options.level = query.level;
+            const role = ARIA_ROLE_BY_CONTRACT_ROLE[query.value.value] ?? query.value.value;
+            return scope.getByRole(role, options);
+        }
+        case 'label':
+            return scope.getByLabel(patternToPw(query.value), { exact: patternExact(query.value) });
+        case 'placeholder':
+            return scope.getByPlaceholder(patternToPw(query.value), { exact: patternExact(query.value) });
+        case 'text':
+            return scope.getByText(patternToPw(query.value), { exact: patternExact(query.value) });
+        case 'displayValue':
+            // Candidate set; the surface filters by current value at locate time.
+            return scope.locator('input, textarea, select');
+        case 'testId':
+            return scope.locator(testIdSelector(testIdAttribute, query.value));
+    }
+}
+/**
+ * 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, so a direct query agrees with `toBeVisible()` even at the margin
+ * where the two predicates differ (a zero-size element with a layout rect is
+ * hidden to Playwright and shown to the semantic read).
+ */
+function visibleQueryToPw(scope, query, testIdAttribute) {
+    const located = queryToPw(scope, query, testIdAttribute);
+    if (query.visible !== true)
+        return located;
+    return located.filter({ visible: true }).locator(NOT_ARIA_HIDDEN);
+}
+/**
+ * Every control `getByLabel` can name: labelable form controls plus anything
+ * carrying its own label attributes. The candidates of an exact label query;
+ * the surface keeps those whose labels match.
+ */
+const LABELABLE_SELECTOR = 'button, input:not([type="hidden"]), textarea, select, meter, output, progress, [aria-label], [aria-labelledby]';
+function positioned(locator, index) {
+    return index === 'first' ? locator.first() : index === 'last' ? locator.last() : locator.nth(index);
+}
+const DISPLAY_VALUE_COMPOSITION_MESSAGE = 'displayValue queries cannot scope child queries or serve as a has-filter in this engine';
+/**
+ * Projects a complete immutable expression onto a Playwright locator within
+ * one scope. Frame cardinality is validated separately by the surface.
+ *
+ * A display-value query resolves to a candidate locator plus a value predicate
+ * the surface applies once the candidates are read. Per-element filters
+ * (`filter({ hasText, has })`) commute with that predicate, so they compose
+ * onto the candidate locator as for any other query. Positional selection does
+ * not commute (positions are relative to the value-filtered matches), so it is
+ * recorded as a step and applied after filtering; a filter that follows a
+ * position is recorded the same way and checked on the selected element. Two
+ * compositions need the predicate inside Playwright's own chain and stay
+ * unsupported: a display-value query as the scope of a child query, and as a
+ * `has` filter.
+ */
+function project(scope, expression, testIdAttribute) {
+    switch (expression.kind) {
+        case 'query': {
+            const inner = expression.scope === undefined
+                ? scope
+                : requireComposable(project(scope, expression.scope, testIdAttribute));
+            const { query } = expression;
+            const exactLabel = query.kind === 'label' && patternExact(query.value);
+            const locator = exactLabel
+                ? inner.locator(LABELABLE_SELECTOR)
+                : visibleQueryToPw(inner, query, testIdAttribute);
+            return {
+                locator,
+                displayValue: query.kind === 'displayValue' ? query.value : null,
+                name: exactLabel ? query.value : null,
+                composable: exactLabel ? inner.getByLabel(patternToPw(query.value), { exact: false }) : null,
+                steps: [],
+                visible: query.visible === true,
+            };
+        }
+        case 'filter': {
+            const source = project(scope, expression.source, testIdAttribute);
+            const options = {};
+            if (expression.hasText !== undefined)
+                options.hasText = patternToPw(expression.hasText);
+            if (expression.has !== undefined) {
+                options.has = requireComposable(project(scope, expression.has, testIdAttribute));
+            }
+            if (source.steps.length > 0) {
+                return { ...source, steps: [...source.steps, { kind: 'filter', options }] };
+            }
+            return {
+                ...source,
+                locator: source.locator.filter(options),
+                composable: source.composable === null ? null : source.composable.filter(options),
+                steps: [],
+            };
+        }
+        case 'index': {
+            const source = project(scope, expression.source, testIdAttribute);
+            if (source.displayValue !== null || source.name !== null) {
+                return {
+                    ...source,
+                    composable: source.composable === null ? null : positioned(source.composable, expression.index),
+                    steps: [...source.steps, { kind: 'index', index: expression.index }],
+                };
+            }
+            return {
+                locator: positioned(source.locator, expression.index),
+                displayValue: null,
+                name: null,
+                composable: null,
+                steps: [],
+                visible: false,
+            };
+        }
+        case 'selector':
+            return {
+                locator: scope.locator(expression.selector),
+                displayValue: null,
+                name: null,
+                composable: null,
+                steps: [],
+                visible: false,
+            };
+        case 'frame':
+            return project(scope.frameLocator(expression.selector), expression.source, testIdAttribute);
+    }
+}
+/** Projects an expression onto the page; `testIdAttribute` is what a `testId` query reads. */
+export function projectExpression(page, expression, testIdAttribute) {
+    return project(page, expression, testIdAttribute);
+}
+/**
+ * Returns the locator of a projection that must participate in Playwright's
+ * own locator chain: a scope for child queries or a `has` target. A
+ * display-value projection cannot, because its value predicate lives outside
+ * that chain.
+ */
+function requireComposable(projected) {
+    if (projected.composable !== null)
+        return projected.composable;
+    if (projected.displayValue !== null) {
+        throw new EngineError('UNSUPPORTED_CAPABILITY', DISPLAY_VALUE_COMPOSITION_MESSAGE, {
+            retryable: false,
+        });
+    }
+    return projected.locator;
+}
+/**
+ * Applies post steps, innermost first, to an ordered list of matches. `nth`
+ * past the end selects nothing, matching Playwright's `nth` on a locator with
+ * too few matches. A filter step keeps the matches `passesFilter` accepts;
+ * it runs only on the matches that survived the steps before it.
+ */
+export async function applyPostSteps(matches, steps, passesFilter) {
+    let selected = matches;
+    for (const step of steps) {
+        if (step.kind === 'index') {
+            const { index } = step;
+            if (index === 'first')
+                selected = selected.slice(0, 1);
+            else if (index === 'last')
+                selected = selected.slice(-1);
+            else
+                selected = index < selected.length ? [selected[index]] : [];
+            continue;
+        }
+        const kept = [];
+        for (const match of selected) {
+            if (await passesFilter(match, step.options))
+                kept.push(match);
+        }
+        selected = kept;
+    }
+    return selected;
+}
+/** Returns every frame selector along an expression, outermost first. */
+export function frameSelectors(expression) {
+    switch (expression.kind) {
+        case 'query':
+            return expression.scope === undefined ? [] : frameSelectors(expression.scope);
+        case 'filter':
+        case 'index':
+            return frameSelectors(expression.source);
+        case 'selector':
+            return [];
+        case 'frame':
+            return [expression.selector, ...frameSelectors(expression.source)];
+    }
+}
+//# sourceMappingURL=locators.js.map

package/dist/locators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.js","sourceRoot":"","sources":["../src/locators.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAG1D,OAAO,EAAE,WAAW,EAAgE,MAAM,YAAY,CAAC;AAIvG,SAAS,WAAW,CAAC,OAAoB;IACvC,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAChF,OAAO,OAAO,CAAC,KAAK,CAAC;AACvB,CAAC;AAED,SAAS,YAAY,CAAC,OAAoB;IACxC,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,SAAiB,EAAE,OAAoB;IAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,MAAM,KAAK,GACT,OAAO,CAAC,IAAI,KAAK,QAAQ;QACvB,CAAC,CAAC,sBAAsB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;IACxE,OAAO,oBAAoB,IAAI,IAAI,KAAK,GAAG,CAAC;AAC9C,CAAC;AAED,uGAAuG;AACvG,SAAS,sBAAsB,CAAC,EAAU;IACxC,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC,EAAE,CAAC;SACd,OAAO,CAAC,0BAA0B,EAAE,UAAU,CAAC;SAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,0BAA0B,GAAqC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAEtF,SAAS,SAAS,CAAC,KAAc,EAAE,KAAoB,EAAE,eAAuB;IAC9E,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM,EAAE,CAAC;YACZ,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,mCAAmC,EAAE;oBAC3E,SAAS,EAAE,KAAK;iBACjB,CAAC,CAAC;YACL,CAAC;YACD,MAAM,OAAO,GAAqC,EAAE,CAAC;YACrD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACvC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YACrE,CAAC;YACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YACnE,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACtE,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACtE,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACtE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YACnE,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;gBAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YAC3D,MAAM,IAAI,GAAG,0BAA0B,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YAChF,OAAO,KAAK,CAAC,SAAS,CAAC,IAAwC,EAAE,OAAO,CAAC,CAAC;QAC5E,CAAC;QACD,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1F,KAAK,aAAa;YAChB,OAAO,KAAK,CAAC,gBAAgB,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChG,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzF,KAAK,cAAc;YACjB,sEAAsE;YACtE,OAAO,KAAK,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAClD,KAAK,QAAQ;YACX,OAAO,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAiBD;;;GAGG;AACH,MAAM,eAAe,GAAG,kCAAkC,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CAAC,KAAc,EAAE,KAAoB,EAAE,eAAuB;IACrF,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AACpE,CAAC;AA6CD;;;;GAIG;AACH,MAAM,kBAAkB,GACtB,gHAAgH,CAAC;AAEnH,SAAS,UAAU,CAAC,OAAkB,EAAE,KAAgC;IACtE,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACtG,CAAC;AAED,MAAM,iCAAiC,GACrC,yFAAyF,CAAC;AAE5F;;;;;;;;;;;;;;GAcG;AACH,SAAS,OAAO,CAAC,KAAc,EAAE,UAA6B,EAAE,eAAuB;IACrF,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,OAAO,EAAE,CAAC;YACb,MAAM,KAAK,GACT,UAAU,CAAC,KAAK,KAAK,SAAS;gBAC5B,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;YAC3E,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;YAC7B,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,UAAU;gBACxB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,kBAAkB,CAAC;gBACnC,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;YACpD,OAAO;gBACL,OAAO;gBACP,YAAY,EAAE,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;gBAChE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;gBACrC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;gBAC5F,KAAK,EAAE,EAAE;gBACT,OAAO,EAAE,KAAK,CAAC,OAAO,KAAK,IAAI;aAChC,CAAC;QACJ,CAAC;QACD,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;YAClE,MAAM,OAAO,GAAoB,EAAE,CAAC;YACpC,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACxF,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO,CAAC,GAAG,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC;YACnF,CAAC;YACD,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YAC9E,CAAC;YACD,OAAO;gBACL,GAAG,MAAM;gBACT,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;gBACvC,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC;gBACjF,KAAK,EAAE,EAAE;aACV,CAAC;QACJ,CAAC;QACD,KAAK,OAAO,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;YAClE,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBACzD,OAAO;oBACL,GAAG,MAAM;oBACT,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC;oBAC/F,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;iBACrE,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC;gBACrD,YAAY,EAAE,IAAI;gBAClB,IAAI,EAAE,IAAI;gBACV,UAAU,EAAE,IAAI;gBAChB,KAAK,EAAE,EAAE;gBACT,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QACD,KAAK,UAAU;YACb,OAAO;gBACL,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAC3C,YAAY,EAAE,IAAI;gBAClB,IAAI,EAAE,IAAI;gBACV,UAAU,EAAE,IAAI;gBAChB,KAAK,EAAE,EAAE;gBACT,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,KAAK,OAAO;YACV,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChG,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAC/B,IAAU,EACV,UAA6B,EAC7B,eAAuB;IAEvB,OAAO,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,SAA2B;IACpD,IAAI,SAAS,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC,UAAU,CAAC;IAC/D,IAAI,SAAS,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,IAAI,WAAW,CAAC,wBAAwB,EAAE,iCAAiC,EAAE;YACjF,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC,OAAO,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAqB,EACrB,KAA0B,EAC1B,YAAsE;IAEtE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;YACvB,IAAI,KAAK,KAAK,OAAO;gBAAE,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;iBAClD,IAAI,KAAK,KAAK,MAAM;gBAAE,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;;gBACpD,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAQ,EAAE,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChE,CAAC;QACD,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,UAA6B;IAC1D,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,OAAO;YACV,OAAO,UAAU,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAChF,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3C,KAAK,UAAU;YACb,OAAO,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}

package/dist/observation-capture.d.ts

@@ -0,0 +1,12 @@
+/** One observation transaction: settling, semantic capture, masked pixels, and staged refs. */
+import type { Page } from 'playwright';
+import { type EngineObserveOptions, type OperationContext } from 'e2e/engine';
+import { RefRegistry, type CapturedObservation } from './refs.ts';
+interface CaptureSettings {
+    readonly testIdAttribute: string;
+    readonly site: string | undefined;
+}
+/** 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-capture.d.ts","sourceRoot":"","sources":["../src/observation-capture.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAe,KAAK,oBAAoB,EAAuB,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIhH,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAUlE,UAAU,eAAe;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,0FAA0F;AAC1F,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,OAAO,CAAC,mBAAmB,CAAC,CAqE9B"}

package/dist/observation-capture.js

@@ -0,0 +1,93 @@
+/** One observation transaction: settling, semantic capture, masked pixels, and staged refs. */
+import { EngineError } from 'e2e/engine';
+import { CaptureScope } from './capture-scope.js';
+import { captureDocument, ROOT_NODE_ID } from './observation.js';
+import { capturePixels } from './observe.js';
+import { RefRegistry } from './refs.js';
+import { cancelled, DEFAULT_VIEWPORT } from './support.js';
+/** Shared node budget across the main document and its frames. */
+const MAX_OBSERVED_NODES = 3_000;
+/** Settling is best-effort and spends from the observation's total budget. */
+const SETTLE_TIMEOUT_MS = 5_000;
+/** Leave time for a fresh masked screenshot after semantic capture expires. */
+const PIXEL_FALLBACK_RESERVE_MS = 2_000;
+/** Captures under one deadline, retaining no refs from a failed or abandoned document. */
+export async function captureObservation(page, refs, settings, operation, options) {
+    const deadline = Date.now() + operation.timeoutMs;
+    let accepting = true;
+    const generation = new Map();
+    try {
+        const settleDeadline = Math.min(deadline, Date.now() + SETTLE_TIMEOUT_MS);
+        await new CaptureScope(settleDeadline, operation.signal).run(() => page.waitForLoadState('domcontentloaded', {
+            timeout: Math.max(1, settleDeadline - Date.now()),
+        })).catch(() => undefined);
+        if (operation.signal.aborted)
+            throw cancelled('observe cancelled');
+        const viewport = page.viewportSize() ?? DEFAULT_VIEWPORT;
+        const semanticDeadline = options?.pixelFallback === true
+            ? deadline - Math.min(PIXEL_FALLBACK_RESERVE_MS, (deadline - Date.now()) / 4)
+            : deadline;
+        // The initial image is independent of the reader. A fallback always takes a fresh one.
+        const pixelCapture = options?.pixels === true
+            ? capturePixels(page, { ...operation, timeoutMs: semanticDeadline - Date.now() }, viewport).catch(() => undefined)
+            : Promise.resolve(undefined);
+        let snapshot;
+        try {
+            const [captured, pixels] = await Promise.all([
+                captureDocument({
+                    ...settings,
+                    reserveIds: (count) => refs.reserveIds(count),
+                    commit: (id, element) => {
+                        if (accepting && !operation.signal.aborted)
+                            generation.set(id, { kind: 'element', element });
+                        else
+                            void element.dispose().catch(() => undefined);
+                    },
+                }, page, {
+                    framePath: [], budget: MAX_OBSERVED_NODES,
+                    deadline: semanticDeadline, signal: operation.signal,
+                }),
+                pixelCapture,
+            ]);
+            snapshot = {
+                location: page.url(),
+                root: captured.tree,
+                viewport: { width: viewport.width, height: viewport.height },
+                ...(captured.truncated ? { truncated: true } : {}),
+                ...(pixels === undefined ? {} : { pixels: pixels.pixels, maskedRegionCount: pixels.maskedRegionCount }),
+            };
+        }
+        catch (cause) {
+            RefRegistry.dispose(generation);
+            generation.clear();
+            if (options?.pixelFallback !== true || !(cause instanceof EngineError) || cause.code !== 'OPERATION_TIMEOUT')
+                throw cause;
+            await pixelCapture;
+            const fallbackViewport = page.viewportSize() ?? DEFAULT_VIEWPORT;
+            const pixels = await capturePixels(page, {
+                ...operation, timeoutMs: deadline - Date.now(),
+            }, fallbackViewport);
+            if (!pixels.maskingProven)
+                throw cause;
+            snapshot = {
+                location: page.url(),
+                root: { ref: { id: ROOT_NODE_ID, revision: '' } },
+                viewport: { width: fallbackViewport.width, height: fallbackViewport.height },
+                truncated: true,
+                treeUnavailable: true,
+                pixels: pixels.pixels,
+                maskedRegionCount: pixels.maskedRegionCount,
+            };
+        }
+        return { snapshot, generation };
+    }
+    catch (cause) {
+        RefRegistry.dispose(generation);
+        generation.clear();
+        throw cause;
+    }
+    finally {
+        accepting = false;
+    }
+}
+//# sourceMappingURL=observation-capture.js.map

package/dist/observation-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-capture.js","sourceRoot":"","sources":["../src/observation-capture.ts"],"names":[],"mappings":"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"}