@e2e-dev/web 0.11.0-canary-20260928184528

package/dist/provider.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The seam a hosted browser service plugs into: a `BrowserProvider` leases a
+ * browser and hands back the CDP endpoint to attach to. In `worker` scope the
+ * engine leases one browser per worker slot in `prepare`, attaches each from
+ * its worker, and releases them all in `finish`; in `attempt` scope it leases
+ * a fresh browser in every `startAttempt` and releases it in `endAttempt`.
+ * Nothing here knows any vendor: a cloud browser service, a browser farm, or
+ * a Chrome on a machine down the hall are each one small provider in user code.
+ */
+import { type EngineAttemptContext, type EngineCleanupContext, type EngineFinishInfo, type EngineInitInfo, type EnginePrepareInfo, type EnginePrepareResult } from 'e2e/engine';
+/**
+ * How long a lease lives. `worker` (the default) is one browser per worker
+ * slot, acquired in `prepare` and released in `finish`; `attempt` is a fresh
+ * browser per attempt, acquired in `startAttempt` and released in
+ * `endAttempt`, reconnected through the lease's `reconnectEndpoint` after a
+ * transport drop.
+ */
+export type BrowserProviderScope = 'worker' | 'attempt';
+/** What the engine asks a provider for: one browser for one worker slot, or for one attempt, of a run. */
+export interface BrowserRequest {
+    /** The run id, for naming the session at the provider. */
+    readonly runId: string;
+    /** The target the browser serves. */
+    readonly targetName: string;
+    /** Worker slot the browser serves, `0` to `slots - 1`; in `worker` scope `slots` leases are acquired at once. */
+    readonly slot: number;
+    /** Worker slots the run uses for this target, in all. */
+    readonly slots: number;
+    /** Present only for a per-attempt lease. */
+    readonly attemptId?: string | undefined;
+    /** The run's environment: where a provider reads its token from, never `process.env`. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Aborts on interrupt, and when the attempt that needs the browser is cancelled or exceeds its budget. */
+    readonly signal: AbortSignal;
+    /** Reports one line of progress to the run's reporter (a session URL to watch); discarded in a worker process. */
+    readonly log: (line: string) => void;
+}
+/**
+ * One leased browser, as `acquire` returns it and `release` gets it back.
+ * JSON data only: a lease travels from the runner process to the worker that
+ * attaches to it through the environment.
+ */
+export interface BrowserLease {
+    /**
+     * The provider's handle on the lease (a session id); named in progress
+     * lines and handed back to `release`. A provider may keep further fields on
+     * the object it returns: `release` gets that same object, while only the
+     * fields declared here travel to the worker.
+     */
+    readonly id: string;
+    /** `ws://`, `wss://`, or `http://` DevTools endpoint to attach to over CDP. */
+    readonly cdpEndpoint: string;
+    /**
+     * Endpoint to reattach to the same browser after a transport drop, when it
+     * differs from `cdpEndpoint`; only meaningful for a per-attempt lease.
+     */
+    readonly reconnectEndpoint?: string | undefined;
+}
+/** Handed to `release`, once per lease. */
+export interface BrowserReleaseContext {
+    readonly runId: string;
+    readonly targetName: string;
+    /** The run's environment, the same `acquire` saw. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Aborts when the cleanup budget is spent. */
+    readonly signal: AbortSignal;
+    readonly log: (line: string) => void;
+}
+/**
+ * A source of hosted browsers. In `worker` scope `acquire` is called once per
+ * worker slot, for every slot at once, in the runner process; a worker whose
+ * browser drops calls it again, from its own process, for a replacement. In
+ * `attempt` scope every `startAttempt` calls it from the worker. `release`
+ * is called exactly once per lease, by the process that acquired it, also
+ * after an `acquire` of another slot failed. A provider must not rely on
+ * runner-process state to serve a request from a worker.
+ */
+export interface BrowserProvider {
+    /** Label in progress lines and error messages. */
+    readonly name: string;
+    /** How long a lease lives; `worker` when absent. */
+    readonly scope?: BrowserProviderScope | undefined;
+    acquire(request: BrowserRequest): Promise<BrowserLease>;
+    release(lease: BrowserLease, context: BrowserReleaseContext): Promise<void>;
+}
+/** Narrows an intended provider, or names what it is missing. */
+export declare function asBrowserProvider(browser: object): BrowserProvider;
+/**
+ * Browsers a provider leases for one target, on both sides of the worker
+ * boundary. In the runner, `prepare` leases one per slot, all at once (hosted
+ * browsers start in parallel and are billed from the moment they do), and
+ * holds every lease granted for `finish` before the outcome is known, so a
+ * slot that fails to lease fails the run and the others are still released.
+ * In a worker, `init` reads the slot's lease from the environment; a browser
+ * that drops is replaced by a lease the worker acquires itself, and
+ * per-attempt leases come and go with the attempt. Each lease is released
+ * exactly once, by the side that acquired it.
+ */
+export declare class LeasedBrowsers {
+    private readonly provider;
+    readonly scope: BrowserProviderScope;
+    /** Leases granted so far, per target, filled as each `acquire` settles. */
+    private readonly held;
+    private run;
+    /** The lease the worker's shared browser attaches to, and whether `endpoint` has handed it out yet. */
+    private current;
+    private attached;
+    private attempt;
+    /** The attempt whose lease is being acquired or held; a lease that arrives for any other attempt is released, not committed. */
+    private opened;
+    /** This worker's tenure, replaced by `init` and `dispose`; a replacement lease that arrives for an earlier one is released, not committed. */
+    private tenure;
+    constructor(provider: BrowserProvider);
+    /**
+     * Leases one browser per worker slot the run will use, in `worker` scope,
+     * and hands the leases to the workers through the environment; `attempt`
+     * scope leases per attempt instead and hands over the slot count alone. A
+     * target nothing runs on leases nothing.
+     */
+    prepare(info: EnginePrepareInfo): Promise<EnginePrepareResult>;
+    /** Releases what `prepare` leased for the target, every lease before the first failure is reported. */
+    finish(info: EngineFinishInfo): Promise<void>;
+    /**
+     * Records the run this worker serves and, in `worker` scope, the lease its
+     * slot was handed. A missing hand-off is a broken invariant: the runner
+     * prepares every target before it starts a worker, and caps the slots at
+     * the workers `prepare` reported.
+     */
+    init(info: EngineInitInfo): void;
+    /**
+     * The endpoint the worker's shared browser attaches to, in `worker` scope:
+     * the slot's lease the first time, and a replacement the worker leases
+     * itself every time after, since the connection only asks again once the
+     * browser it had dropped. A dead lease is released by the side that
+     * acquired it: the worker here, best effort, or the runner in `finish`. A
+     * replacement that arrives once the attempt was cancelled or the worker
+     * disposed is given straight back and never committed.
+     */
+    endpoint(signal: AbortSignal): Promise<string>;
+    /**
+     * Leases a fresh browser for the attempt, in `attempt` scope; `endAttempt`
+     * releases it on every path. A lease that arrives once the attempt was
+     * cancelled or already ended (a provider that ignored the abort) is given
+     * straight back and never committed, so a retry never finds it.
+     */
+    startAttempt(context: EngineAttemptContext): Promise<BrowserLease>;
+    /** Releases the attempt's lease, when one was granted; idempotent, and safe after a failed `startAttempt`. */
+    endAttempt(context: EngineCleanupContext): Promise<void>;
+    /** Releases the replacement lease the worker acquired for itself; what `prepare` leased is the runner's to release. */
+    dispose(context: EngineCleanupContext): Promise<void>;
+    private requireRun;
+    /** One `acquire`, its result checked field by field; a failure is named after the provider. */
+    private acquire;
+    /** One `release` from the worker, bounded by the cleanup budget; a failure is a cleanup error named after the provider. */
+    private release;
+    private releaseContext;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

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

package/dist/provider.js

@@ -0,0 +1,311 @@
+/**
+ * The seam a hosted browser service plugs into: a `BrowserProvider` leases a
+ * browser and hands back the CDP endpoint to attach to. In `worker` scope the
+ * engine leases one browser per worker slot in `prepare`, attaches each from
+ * its worker, and releases them all in `finish`; in `attempt` scope it leases
+ * a fresh browser in every `startAttempt` and releases it in `endAttempt`.
+ * Nothing here knows any vendor: a cloud browser service, a browser farm, or
+ * a Chrome on a machine down the hall are each one small provider in user code.
+ */
+import { createHash } from 'node:crypto';
+import { ConfigurationError, EngineError, obj, raceAbort, } from 'e2e/engine';
+import { message } from './support.js';
+const SCOPES = new Set(['worker', 'attempt']);
+/** Narrows an intended provider, or names what it is missing. */
+export function asBrowserProvider(browser) {
+    const candidate = browser;
+    if (typeof candidate.name !== 'string' || candidate.name.trim() === '') {
+        throw new ConfigurationError('INVALID_CONFIG', 'web: a `browser` provider needs a non-empty `name`');
+    }
+    for (const member of ['acquire', 'release']) {
+        if (typeof candidate[member] !== 'function') {
+            throw new ConfigurationError('INVALID_CONFIG', `web: browser provider "${candidate.name}" must implement ${member}()`);
+        }
+    }
+    if (candidate.scope !== undefined && (typeof candidate.scope !== 'string' || !SCOPES.has(candidate.scope))) {
+        throw new ConfigurationError('INVALID_CONFIG', `web: browser provider "${candidate.name}" has scope ${JSON.stringify(candidate.scope)}; use "worker" or "attempt"`);
+    }
+    return browser;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/** A lease as a provider returned it or as JSON parsed it back, checked field by field: the engine trusts nothing it did not write. */
+function isBrowserLease(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { id, cdpEndpoint, reconnectEndpoint } = value;
+    return isNonEmptyString(id) && isNonEmptyString(cdpEndpoint) && (reconnectEndpoint === undefined || isNonEmptyString(reconnectEndpoint));
+}
+/**
+ * The most the serialized hand-off of one target may occupy in a worker's
+ * environment: a lease comes from third-party code, and an oversized
+ * environment fails the worker spawn with an opaque error.
+ */
+const MAX_HANDOFF_ENV_BYTES = 16 * 1024;
+/**
+ * The environment variable a target's hand-off travels to the workers in:
+ * the name made environment-safe for reading, plus a digest of the exact
+ * name so `web-a` and `web.a` never share a key.
+ */
+function handoffVariable(targetName) {
+    const readable = targetName.replace(/[^A-Za-z0-9]/g, '_').toUpperCase();
+    const digest = createHash('sha256').update(targetName).digest('hex').slice(0, 8).toUpperCase();
+    return `E2E_WEB_BROWSERS_${readable}_${digest}`;
+}
+/** Serializes the hand-off for the environment: declared lease fields only, bounded. */
+function encodeHandoff(handoff) {
+    const encoded = JSON.stringify({
+        slots: handoff.slots,
+        leases: handoff.leases.map((lease) => obj({ id: lease.id, cdpEndpoint: lease.cdpEndpoint, reconnectEndpoint: lease.reconnectEndpoint })),
+    });
+    const bytes = Buffer.byteLength(encoded);
+    if (bytes > MAX_HANDOFF_ENV_BYTES) {
+        throw new EngineError('ENGINE_FAILURE', `the browser leases take ${bytes} bytes; the worker environment carries at most ${MAX_HANDOFF_ENV_BYTES}`, { retryable: false });
+    }
+    return encoded;
+}
+/** The hand-off a `prepare` left in the environment, or `undefined` when there is none it can read. */
+function decodeHandoff(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const { slots, leases } = parsed;
+        if (Number.isInteger(slots) && slots >= 0 && Array.isArray(leases) && leases.every(isBrowserLease)) {
+            return { slots: slots, leases };
+        }
+    }
+    catch {
+        // Not ours to read.
+    }
+    return undefined;
+}
+/** Runs every task, then reports the first failure: nothing is skipped because a sibling failed. */
+async function allOrFirstFailure(tasks, describe) {
+    // `async` so a task that throws before its first await is a rejection like any other, not an escape.
+    const settled = await Promise.allSettled(tasks.map(async (task) => task()));
+    const failed = settled.find((result) => result.status === 'rejected');
+    if (failed !== undefined) {
+        if (failed.reason instanceof EngineError)
+            throw failed.reason;
+        throw new EngineError('ENGINE_FAILURE', `${describe}: ${message(failed.reason)}`, { retryable: false, cause: failed.reason });
+    }
+    return settled.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
+}
+const discard = () => undefined;
+/**
+ * Browsers a provider leases for one target, on both sides of the worker
+ * boundary. In the runner, `prepare` leases one per slot, all at once (hosted
+ * browsers start in parallel and are billed from the moment they do), and
+ * holds every lease granted for `finish` before the outcome is known, so a
+ * slot that fails to lease fails the run and the others are still released.
+ * In a worker, `init` reads the slot's lease from the environment; a browser
+ * that drops is replaced by a lease the worker acquires itself, and
+ * per-attempt leases come and go with the attempt. Each lease is released
+ * exactly once, by the side that acquired it.
+ */
+export class LeasedBrowsers {
+    provider;
+    scope;
+    /** Leases granted so far, per target, filled as each `acquire` settles. */
+    held = new Map();
+    run;
+    /** The lease the worker's shared browser attaches to, and whether `endpoint` has handed it out yet. */
+    current;
+    attached = false;
+    attempt;
+    /** The attempt whose lease is being acquired or held; a lease that arrives for any other attempt is released, not committed. */
+    opened;
+    /** This worker's tenure, replaced by `init` and `dispose`; a replacement lease that arrives for an earlier one is released, not committed. */
+    tenure = {};
+    constructor(provider) {
+        this.provider = provider;
+        this.scope = provider.scope ?? 'worker';
+    }
+    // --- runner side ---
+    /**
+     * Leases one browser per worker slot the run will use, in `worker` scope,
+     * and hands the leases to the workers through the environment; `attempt`
+     * scope leases per attempt instead and hands over the slot count alone. A
+     * target nothing runs on leases nothing.
+     */
+    async prepare(info) {
+        if (info.slots === 0)
+            return {};
+        const variable = handoffVariable(info.targetName);
+        if (this.scope === 'attempt')
+            return { env: { [variable]: encodeHandoff({ slots: info.slots, leases: [] }) } };
+        const { provider } = this;
+        const held = [];
+        this.held.set(info.targetName, held);
+        info.log(`leasing ${info.slots} browser(s) from ${provider.name}`);
+        const leases = await allOrFirstFailure(Array.from({ length: info.slots }, (_, slot) => async () => {
+            const lease = await this.acquire({
+                runId: info.runId,
+                targetName: info.targetName,
+                slot,
+                slots: info.slots,
+                env: info.env,
+                signal: info.signal,
+                log: (line) => info.log(`${provider.name} (${slot + 1} of ${info.slots}): ${line}`),
+            });
+            held.push(lease);
+            info.log(`${provider.name}: leased ${lease.id}`);
+            return lease;
+        }), `browser provider "${provider.name}" could not lease a browser`);
+        return { workers: leases.length, env: { [variable]: encodeHandoff({ slots: leases.length, leases }) } };
+    }
+    /** Releases what `prepare` leased for the target, every lease before the first failure is reported. */
+    async finish(info) {
+        const { provider } = this;
+        const leases = this.held.get(info.targetName);
+        this.held.delete(info.targetName);
+        if (leases === undefined || leases.length === 0)
+            return;
+        const context = { runId: info.runId, targetName: info.targetName, env: info.env, signal: info.signal, log: (line) => info.log(`${provider.name}: ${line}`) };
+        await allOrFirstFailure(leases.map((lease) => () => provider.release(lease, context)), `browser provider "${provider.name}" could not release a browser`);
+        info.log(`${provider.name}: released ${leases.length} browser(s)`);
+    }
+    // --- worker side ---
+    /**
+     * Records the run this worker serves and, in `worker` scope, the lease its
+     * slot was handed. A missing hand-off is a broken invariant: the runner
+     * prepares every target before it starts a worker, and caps the slots at
+     * the workers `prepare` reported.
+     */
+    init(info) {
+        const { provider } = this;
+        this.current = undefined;
+        this.attached = false;
+        this.tenure = {};
+        const handoff = decodeHandoff(info.env[handoffVariable(info.targetName)]);
+        if (handoff === undefined) {
+            throw new EngineError('ENGINE_FAILURE', `browser provider "${provider.name}" prepared nothing for target "${info.targetName}"; the runner must prepare the target before a worker starts`, { retryable: false });
+        }
+        this.run = { runId: info.runId, targetName: info.targetName, env: info.env, slot: info.workerSlot, slots: handoff.slots };
+        if (this.scope === 'attempt')
+            return;
+        const lease = handoff.leases[info.workerSlot];
+        if (lease === undefined) {
+            throw new EngineError('ENGINE_FAILURE', `worker slot ${info.workerSlot} is outside the ${handoff.leases.length} browser(s) "${provider.name}" leased; the runner must cap the target at the engine's reported workers`, { retryable: false });
+        }
+        this.current = { lease, owned: false };
+    }
+    /**
+     * The endpoint the worker's shared browser attaches to, in `worker` scope:
+     * the slot's lease the first time, and a replacement the worker leases
+     * itself every time after, since the connection only asks again once the
+     * browser it had dropped. A dead lease is released by the side that
+     * acquired it: the worker here, best effort, or the runner in `finish`. A
+     * replacement that arrives once the attempt was cancelled or the worker
+     * disposed is given straight back and never committed.
+     */
+    async endpoint(signal) {
+        const run = this.requireRun();
+        const previous = this.current;
+        if (previous !== undefined && !this.attached) {
+            this.attached = true;
+            return previous.lease.cdpEndpoint;
+        }
+        const { tenure } = this;
+        const lease = await this.acquire({ runId: run.runId, targetName: run.targetName, slot: run.slot, slots: run.slots, env: run.env, signal, log: discard });
+        if (signal.aborted || this.tenure !== tenure) {
+            await this.provider.release(lease, this.releaseContext(run, signal)).catch(discard);
+            throw new EngineError('CANCELLED', `browser lease from "${this.provider.name}" arrived after the worker gave up; released`, { retryable: false });
+        }
+        this.current = { lease, owned: true };
+        this.attached = true;
+        if (previous?.owned === true)
+            await this.provider.release(previous.lease, this.releaseContext(run, signal)).catch(discard);
+        return lease.cdpEndpoint;
+    }
+    /**
+     * Leases a fresh browser for the attempt, in `attempt` scope; `endAttempt`
+     * releases it on every path. A lease that arrives once the attempt was
+     * cancelled or already ended (a provider that ignored the abort) is given
+     * straight back and never committed, so a retry never finds it.
+     */
+    async startAttempt(context) {
+        const run = this.requireRun();
+        const opened = {};
+        this.opened = opened;
+        const lease = await this.acquire({
+            runId: run.runId,
+            targetName: run.targetName,
+            slot: run.slot,
+            slots: run.slots,
+            attemptId: context.attemptId,
+            env: run.env,
+            signal: context.signal,
+            log: discard,
+        });
+        if (context.signal.aborted || this.opened !== opened) {
+            await this.provider.release(lease, this.releaseContext(run, context.signal)).catch(discard);
+            throw new EngineError('CANCELLED', `browser lease from "${this.provider.name}" arrived after the attempt ended; released`, { retryable: false });
+        }
+        this.attempt = lease;
+        return lease;
+    }
+    /** Releases the attempt's lease, when one was granted; idempotent, and safe after a failed `startAttempt`. */
+    async endAttempt(context) {
+        const lease = this.attempt;
+        this.attempt = undefined;
+        this.opened = undefined;
+        if (lease === undefined)
+            return;
+        await this.release(lease, context);
+    }
+    /** Releases the replacement lease the worker acquired for itself; what `prepare` leased is the runner's to release. */
+    async dispose(context) {
+        const current = this.current;
+        this.current = undefined;
+        this.attached = false;
+        this.tenure = {};
+        if (current === undefined || !current.owned)
+            return;
+        await this.release(current.lease, context);
+    }
+    requireRun() {
+        if (this.run === undefined) {
+            throw new EngineError('ENGINE_FAILURE', `browser provider "${this.provider.name}" was asked for a browser before init`, { retryable: false });
+        }
+        return this.run;
+    }
+    /** One `acquire`, its result checked field by field; a failure is named after the provider. */
+    async acquire(request) {
+        const { provider } = this;
+        let lease;
+        try {
+            lease = await provider.acquire(request);
+        }
+        catch (cause) {
+            if (request.signal.aborted) {
+                throw new EngineError('CANCELLED', `browser lease from "${provider.name}" cancelled`, { retryable: false, cause });
+            }
+            throw new EngineError('ENGINE_FAILURE', `browser provider "${provider.name}" could not lease a browser: ${message(cause)}`, { retryable: false, cause });
+        }
+        if (!isBrowserLease(lease)) {
+            throw new EngineError('ENGINE_FAILURE', `browser provider "${provider.name}" returned a lease without an id and a cdpEndpoint`, { retryable: false });
+        }
+        return lease;
+    }
+    /** One `release` from the worker, bounded by the cleanup budget; a failure is a cleanup error named after the provider. */
+    async release(lease, budget) {
+        const run = this.requireRun();
+        try {
+            await raceAbort(this.provider.release(lease, this.releaseContext(run, budget.signal)), budget.signal, `releasing browser ${lease.id}`);
+        }
+        catch (cause) {
+            if (cause instanceof EngineError)
+                throw cause;
+            throw new EngineError('ENGINE_FAILURE', `browser provider "${this.provider.name}" could not release browser ${lease.id}: ${message(cause)}`, { retryable: false, cause });
+        }
+    }
+    releaseContext(run, signal) {
+        return { runId: run.runId, targetName: run.targetName, env: run.env, signal, log: discard };
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/read-node.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The wire types of the in-page semantic reader and the page functions
+ * assembled from its source for locator.evaluate, locator.evaluateAll, and
+ * page.evaluate. The reader itself lives in `in-page/read-semantics.ts`; it is
+ * serialized into the page, so every page function here is built from its
+ * source with `new Function` and stays free of module-scope captures.
+ */
+/**
+ * The one definition of a secure field.
+ *
+ * It is a selector rather than a predicate because it has to be applied from
+ * two sides that cannot share code: the in-page reader matches elements
+ * against it to mark nodes `secure`, and the engine hands the same string to
+ * the screenshot masker. One string means the tree's redaction and the image's
+ * redaction cannot describe different sets of elements, which is what the
+ * runner's pixel-clearance check relies on.
+ */
+export declare const SECURE_FIELD_SELECTOR = "input[type=\"password\" i]";
+export interface RawNodeData {
+    role: string | null;
+    name: string | null;
+    /**
+     * Every label a person or a tool may call this control by: its `aria-label`,
+     * each `aria-labelledby` target, and each associated `<label>`, read as an
+     * accessible name (aria-hidden dropped). Null for a node with none. An exact
+     * label query matches any one of them, as Playwright's `getByLabel` does,
+     * rather than the combined or overridden `name`.
+     */
+    labels: string[] | null;
+    text: string | null;
+    value: string | null;
+    /** Text selected inside the focused field or editing host; null when unfocused, collapsed, or secure. */
+    selection: string | null;
+    inputPurpose: 'username' | 'password' | 'one-time-code' | 'generic-secret' | 'none';
+    states: {
+        checked: boolean | null;
+        disabled: boolean;
+        selected: boolean | null;
+        expanded: boolean | null;
+        pressed: boolean | null;
+        focused: boolean;
+        hidden: boolean;
+        secure: boolean;
+    };
+    /** Heading level of a heading: `aria-level`, else the digit of `h1` through `h6`; null for anything else. */
+    level: number | null;
+    attributes: Record<string, string>;
+    /** Value of the project's test-id attribute, when the element carries one. */
+    testId: string | null;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** One observed node plus its position in the flattened depth-first tree. */
+export interface RawObservedNode extends RawNodeData {
+    /** Index of the nearest included ancestor, or -1 for the root. */
+    parent: number;
+    /** Unique CSS selector of this `<iframe>` element; set only for iframes. */
+    frameSelector?: string;
+}
+/** One walked document. */
+interface RawObservation {
+    nodes: RawObservedNode[];
+    /** True when the node budget stopped the walk before the document was read whole. */
+    truncated: boolean;
+    /** Live element handles positionally aligned with `nodes`. */
+    elements: Element[];
+    /**
+     * Node ids positionally aligned with `nodes`. An id is stamped on the element
+     * the first time an observation includes it and read back on every later
+     * one, so the same element keeps the same id for as long as it lives in the
+     * document: two looks at an unchanged screen name its nodes identically, and
+     * an update can list exactly what changed. A re-created element (a framework
+     * re-mount, a new document) is a new node and gets a fresh id.
+     */
+    ids: string[];
+}
+export type SemanticMode = {
+    kind: 'node';
+} | {
+    kind: 'tree';
+    maxNodes: number;
+    /**
+     * First numeric id available to nodes seen for the first time. The caller
+     * reserves maxNodes ids before execution, so an abandoned reader cannot
+     * collide with later captures or locator resolution.
+     */
+    idSeed: number;
+    /** Cuts each node's name at this length; the caller owns the contract value. */
+    nameLimit: number;
+    /** Cuts each node's text at this length; the caller owns the contract value. */
+    textLimit: number;
+};
+/**
+ * What a node read reports for an element no longer in its document. A
+ * detached element has no boxes, so everything else it would report (hidden,
+ * no labels) describes nothing on screen; its current value is still its own.
+ */
+export interface DetachedNodeData {
+    readonly detached: true;
+    readonly value: string | null;
+}
+/** Result of one read, selected by the mode discriminant. */
+export type SemanticResult<Mode extends SemanticMode> = Mode extends {
+    kind: 'node';
+} ? RawNodeData | DetachedNodeData : RawObservation;
+/** Options for a single-node read, shared by `evaluate` and `evaluateAll` callers. */
+interface NodeReadOptions {
+    readonly testIdAttribute: string;
+    readonly secureFieldSelector: string;
+    readonly mode: {
+        readonly kind: 'node';
+    };
+}
+/** Options for one document's tree walk. */
+interface TreeReadOptions {
+    readonly testIdAttribute: string;
+    readonly secureFieldSelector: string;
+    readonly mode: Extract<SemanticMode, {
+        kind: 'tree';
+    }>;
+}
+/**
+ * Walks a whole document from its root element in one in-page call. Built
+ * from the reader's source like the batch reader below, so the caller
+ * evaluates it directly on a page or frame instead of first resolving a
+ * `:root` locator - one fewer protocol round trip per document per capture.
+ */
+export declare const readDocumentSemanticsFunction: (options: TreeReadOptions) => RawObservation;
+/**
+ * Reads every matched element in one in-page round trip. A page function
+ * cannot close over module scope, so the batch function is assembled from the
+ * reader's own source (the same source `evaluate` sends) and is a
+ * self-contained function Playwright serializes and calls with the elements.
+ */
+export declare const readManySemanticsFunction: (elements: Element[], options: NodeReadOptions) => (RawNodeData | DetachedNodeData)[];
+/**
+ * Reads every handle the caller already holds in one round trip, so what is
+ * read and what is later acted on are the same elements by construction rather
+ * than by a second lookup. Evaluated on the first handle so the read runs in
+ * the frame the handles belong to; `page.evaluate` would reject handles taken
+ * inside an iframe.
+ */
+export declare const readHandlesSemanticsFunction: (first: Element, arg: {
+    elements: Element[];
+    options: NodeReadOptions;
+}) => (RawNodeData | DetachedNodeData)[];
+export {};
+//# sourceMappingURL=read-node.d.ts.map

package/dist/read-node.d.ts.map

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