@e2edev/e2e 0.2.0

package/dist/internal/trace.js

@@ -0,0 +1,46 @@
+/**
+ * Live agent tracing for iterating on agentic tests: `E2E_DEBUG=agent` streams
+ * every invocation phase, model selection, and locate-candidate outcome to
+ * stderr as it happens, from whichever process runs the attempt. This is a
+ * debugging aid, not telemetry: the report stays the canonical record.
+ */
+import { sanitizeText, truncateUtf8 } from './errors.js';
+/**
+ * Parsed on first use, not at import, so tests and embedders can set
+ * `E2E_DEBUG` after this module loads but before the first trace call.
+ */
+let cachedFlags;
+function flags() {
+    cachedFlags ??= new Set((process.env['E2E_DEBUG'] ?? '')
+        .split(',')
+        .map((flag) => flag.trim())
+        .filter((flag) => flag !== ''));
+    return cachedFlags;
+}
+function agentTraceEnabled() {
+    return flags().has('agent') || flags().has('all');
+}
+/** `E2E_DEBUG=observations` additionally dumps every observation the model sees. */
+function observationTraceEnabled() {
+    return flags().has('observations') || flags().has('all');
+}
+/**
+ * Writes one bounded, sanitized trace line when agent tracing is on. Takes a
+ * thunk so call sites in polling loops pay nothing while tracing is off.
+ */
+export function agentTrace(message) {
+    if (!agentTraceEnabled())
+        return;
+    process.stderr.write(`[e2e agent] ${truncateUtf8(sanitizeText(message()), 2_000)}\n`);
+}
+/**
+ * Dumps one full observation as the model will receive it. The text is
+ * already redacted and size-bounded by the observation pipeline, so the dump
+ * needs no further truncation to stay safe.
+ */
+export function observationTrace(header, text) {
+    if (!observationTraceEnabled())
+        return;
+    process.stderr.write(`[e2e observation] ${header()}\n${text}\n[e2e observation] end\n`);
+}
+//# sourceMappingURL=trace.js.map

package/dist/internal/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/internal/trace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzD;;;GAGG;AACH,IAAI,WAA4C,CAAC;AAEjD,SAAS,KAAK;IACZ,WAAW,KAAK,IAAI,GAAG,CACrB,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;SAC7B,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,CACjC,CAAC;IACF,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO,KAAK,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACpD,CAAC;AAED,oFAAoF;AACpF,SAAS,uBAAuB;IAC9B,OAAO,KAAK,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,KAAK,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,OAAqB;IAC9C,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,YAAY,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACxF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB,EAAE,IAAY;IACjE,IAAI,CAAC,uBAAuB,EAAE;QAAE,OAAO;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,MAAM,EAAE,KAAK,IAAI,2BAA2B,CAAC,CAAC;AAC1F,CAAC"}

package/dist/internal/urls.d.ts

@@ -0,0 +1,31 @@
+/** URL normalization and origin policy helpers (spec 05-config.md). */
+export interface NormalizedBaseUrl {
+    /** Serialized base URL without trailing artifacts beyond the normalized path. */
+    readonly href: string;
+    readonly origin: string;
+    readonly basePath: string;
+}
+/**
+ * Parses and normalizes the app base URL. Rejects userinfo, query, and
+ * fragment. WHATWG parsing handles IDNA ASCII hosts, dot segments, and
+ * default-port removal.
+ */
+export declare function normalizeBaseUrl(raw: string): NormalizedBaseUrl;
+/** True for loopback hosts where plain HTTP is allowed. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** True when environment may default to `test` (loopback, .localhost, .test hosts). */
+export declare function isImplicitTestHost(hostname: string): boolean;
+/**
+ * Resolves a navigation URL against the base and enforces the allowed-origin
+ * policy. Returns the absolute URL string.
+ */
+export declare function resolveNavigationUrl(input: string, base: NormalizedBaseUrl, allowedOrigins: readonly string[]): {
+    url: string;
+};
+/**
+ * Compares a current URL to an expected string/regexp per 03-assertions.md.
+ * Relative expected strings resolve against the base URL; string comparison is
+ * exact after WHATWG serialization; regexps test the complete serialized URL.
+ */
+export declare function urlMatches(current: string, expected: string | RegExp, baseHref: string): boolean;
+//# sourceMappingURL=urls.d.ts.map

package/dist/internal/urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/internal/urls.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAKvE,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CA0B/D;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKxD;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,EACvB,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAiBjB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWhG"}

package/dist/internal/urls.js

@@ -0,0 +1,95 @@
+/** URL normalization and origin policy helpers (spec 05-config.md). */
+import { ConfigurationError } from './errors.js';
+import { testPattern } from './regexp.js';
+/**
+ * Parses and normalizes the app base URL. Rejects userinfo, query, and
+ * fragment. WHATWG parsing handles IDNA ASCII hosts, dot segments, and
+ * default-port removal.
+ */
+export function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ConfigurationError('INVALID_APP_URL', `invalid app URL: ${raw}`);
+    }
+    if (url.username !== '' || url.password !== '') {
+        throw new ConfigurationError('INVALID_APP_URL', 'app URL must not contain userinfo');
+    }
+    if (url.search !== '') {
+        throw new ConfigurationError('INVALID_APP_URL', 'app URL must not contain a query');
+    }
+    if (url.hash !== '') {
+        throw new ConfigurationError('INVALID_APP_URL', 'app URL must not contain a fragment');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new ConfigurationError('INVALID_APP_URL', `app URL must be http(s): ${raw}`);
+    }
+    if (url.protocol === 'http:' && !isLoopbackHost(url.hostname)) {
+        throw new ConfigurationError('INVALID_APP_URL', `plain HTTP is allowed only for loopback hosts: ${raw}`);
+    }
+    return { href: url.href, origin: url.origin, basePath: url.pathname };
+}
+/** True for loopback hosts where plain HTTP is allowed. */
+export function isLoopbackHost(hostname) {
+    if (hostname === 'localhost' || hostname.endsWith('.localhost'))
+        return true;
+    if (hostname === '::1' || hostname === '[::1]')
+        return true;
+    if (/^127(\.\d{1,3}){3}$/.test(hostname))
+        return true;
+    return false;
+}
+/** True when environment may default to `test` (loopback, .localhost, .test hosts). */
+export function isImplicitTestHost(hostname) {
+    return isLoopbackHost(hostname) || hostname.endsWith('.test');
+}
+const FORBIDDEN_PROTOCOLS = new Set(['file:', 'data:', 'javascript:']);
+/**
+ * Resolves a navigation URL against the base and enforces the allowed-origin
+ * policy. Returns the absolute URL string.
+ */
+export function resolveNavigationUrl(input, base, allowedOrigins) {
+    let url;
+    try {
+        url = new URL(input, base.href);
+    }
+    catch {
+        throw new ConfigurationError('POLICY_DENIED', `malformed URL: ${input}`);
+    }
+    if (FORBIDDEN_PROTOCOLS.has(url.protocol)) {
+        throw new ConfigurationError('POLICY_DENIED', `forbidden URL scheme: ${url.protocol}`);
+    }
+    if (!allowedOrigins.includes(url.origin)) {
+        throw new ConfigurationError('POLICY_DENIED', `origin ${url.origin} is not in allowedOrigins`);
+    }
+    return { url: url.href };
+}
+/**
+ * Compares a current URL to an expected string/regexp per 03-assertions.md.
+ * Relative expected strings resolve against the base URL; string comparison is
+ * exact after WHATWG serialization; regexps test the complete serialized URL.
+ */
+export function urlMatches(current, expected, baseHref) {
+    if (typeof expected === 'string') {
+        let expectedUrl;
+        try {
+            expectedUrl = new URL(expected, baseHref);
+        }
+        catch {
+            return false;
+        }
+        return serializeForComparison(current) === expectedUrl.href;
+    }
+    return testPattern(expected.source, expected.flags, serializeForComparison(current));
+}
+function serializeForComparison(url) {
+    try {
+        return new URL(url).href;
+    }
+    catch {
+        return url;
+    }
+}
+//# sourceMappingURL=urls.js.map

package/dist/internal/urls.js.map

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

package/dist/locator/engine.d.ts

@@ -0,0 +1,65 @@
+/** Runner-owned query polling, strictness, and action retry (spec 08-platforms.md). */
+import { type TargetSession, type LocatorAction, type LocatorExpression, type NodeRef, type OperationContext, type SemanticNode } from '../backend/surface.ts';
+import { E2EError } from '../internal/errors.ts';
+import { Deadline } from '../internal/time.ts';
+/** Canonical visibility predicate over a semantic node snapshot. */
+export declare function isNodeVisible(node: SemanticNode | null): boolean;
+interface EngineOptions {
+    readonly session: TargetSession;
+    readonly signal: AbortSignal;
+    readonly runId: string;
+    readonly attemptId: string;
+    readonly actionTimeout: number;
+    readonly assertionTimeout: number;
+    readonly testDeadline: Deadline;
+}
+/** Per-attempt locator execution engine. */
+export declare class LocatorEngine {
+    private readonly options;
+    constructor(options: EngineOptions);
+    get session(): TargetSession;
+    get signal(): AbortSignal;
+    get assertionTimeout(): number;
+    /** Builds an operation context capped by the remaining test timeout. */
+    operation(timeoutMs?: number): OperationContext;
+    /** Deadline for one action-family operation, capped by the test deadline. */
+    deadline(timeoutMs?: number): Deadline;
+    private operationWithin;
+    /** One immediate backend resolve, retrying retryable frame misses within the deadline. */
+    private resolveOnce;
+    /**
+     * Resolves exactly one match. Zero matches poll until the deadline;
+     * multiple matches fail immediately with LOCATOR_AMBIGUOUS.
+     */
+    resolveExactlyOne(expression: LocatorExpression, deadline: Deadline): Promise<NodeRef>;
+    /** Immediate single resolve for direct reads: zero or multiple matches fail immediately. */
+    resolveForRead(expression: LocatorExpression): Promise<NodeRef>;
+    /**
+     * Resolves all current matches once without waiting. The caller's deadline,
+     * when given, bounds internal retries of retryable backend errors; it
+     * defaults to the action timeout.
+     */
+    resolveAll(expression: LocatorExpression, deadline?: Deadline): Promise<readonly NodeRef[]>;
+    /**
+     * Reads one node snapshot. A concurrent locator can supersede the ref
+     * between resolve and read; that is a repeatable race, so it re-resolves
+     * while the deadline remains instead of failing the test.
+     */
+    read(expression: LocatorExpression): Promise<SemanticNode>;
+    /** Reads one node for polling surfaces; returns null while zero matches. */
+    tryRead(expression: LocatorExpression, deadline: Deadline): Promise<{
+        node: SemanticNode | null;
+        count: number;
+    }>;
+    /**
+     * Performs exactly one action against exactly one match. Stale nodes are
+     * re-resolved while the deadline remains; a possibly committed action is
+     * never repeated. An action that itself names other nodes (dragTo) is built
+     * per attempt, so its refs are re-resolved together with the source.
+     */
+    perform(expression: LocatorExpression, action: LocatorAction | ((deadline: Deadline) => Promise<LocatorAction>), timeoutMs?: number): Promise<void>;
+}
+/** Translates a backend error into the runner-owned public taxonomy. */
+export declare function translateLocatorError(cause: unknown, expression?: LocatorExpression): E2EError;
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/locator/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/locator/engine.ts"],"names":[],"mappings":"AAAA,uFAAuF;AAEvF,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,QAAQ,EAGT,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAA2B,MAAM,qBAAqB,CAAC;AAExE,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAEhE;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;CACjC;AAED,4CAA4C;AAC5C,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,aAAa,EAAI;IAEvD,IAAI,OAAO,IAAI,aAAa,CAE3B;IAED,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,wEAAwE;IACxE,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAE9C;IAED,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKrC;IAED,OAAO,CAAC,eAAe;IASvB,0FAA0F;YAC5E,WAAW;IAiBzB;;;OAGG;IACG,iBAAiB,CAAC,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAY3F;IAED,4FAA4F;IACtF,cAAc,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;IAED;;;;OAIG;IACG,UAAU,CACd,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,GAAE,QAAoD,GAC7D,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAE7B;IAED;;;;OAIG;IACG,IAAI,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAc/D;IAED,4EAA4E;IACtE,OAAO,CACX,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;QAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAYvD;IAED;;;;;OAKG;IACG,OAAO,CACX,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,aAAa,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,EACxE,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAoBf;CACF;AAaD,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,QAAQ,CAG9F"}

package/dist/locator/engine.js

@@ -0,0 +1,164 @@
+/** Runner-owned query polling, strictness, and action retry (spec 08-platforms.md). */
+import {} from '../backend/surface.js';
+import { asBackendError, E2EError, TestError, translateBackendError, } from '../internal/errors.js';
+import { describeExpression } from './expression.js';
+import { Deadline, POLL_INTERVAL_MS, sleep } from '../internal/time.js';
+/** Canonical visibility predicate over a semantic node snapshot. */
+export function isNodeVisible(node) {
+    return node !== null && node.states?.hidden !== true;
+}
+/** Per-attempt locator execution engine. */
+export class LocatorEngine {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get session() {
+        return this.options.session;
+    }
+    get signal() {
+        return this.options.signal;
+    }
+    get assertionTimeout() {
+        return this.options.assertionTimeout;
+    }
+    /** Builds an operation context capped by the remaining test timeout. */
+    operation(timeoutMs) {
+        return this.operationWithin(this.deadline(timeoutMs));
+    }
+    /** Deadline for one action-family operation, capped by the test deadline. */
+    deadline(timeoutMs) {
+        return Deadline.min(new Deadline(timeoutMs ?? this.options.actionTimeout), this.options.testDeadline);
+    }
+    operationWithin(deadline) {
+        return {
+            signal: this.options.signal,
+            timeoutMs: Math.max(1, deadline.remaining()),
+            runId: this.options.runId,
+            attemptId: this.options.attemptId,
+        };
+    }
+    /** One immediate backend resolve, retrying retryable frame misses within the deadline. */
+    async resolveOnce(expression, deadline) {
+        for (;;) {
+            try {
+                return await this.session.locate(expression, this.operationWithin(deadline));
+            }
+            catch (cause) {
+                if (asBackendError(cause)?.retryable === true && !deadline.expired()) {
+                    await sleep(POLL_INTERVAL_MS, this.options.signal);
+                    continue;
+                }
+                throw translateLocatorError(cause, expression);
+            }
+        }
+    }
+    /**
+     * Resolves exactly one match. Zero matches poll until the deadline;
+     * multiple matches fail immediately with LOCATOR_AMBIGUOUS.
+     */
+    async resolveExactlyOne(expression, deadline) {
+        for (;;) {
+            const ref = assertSingle(await this.resolveOnce(expression, deadline), expression);
+            if (ref !== null)
+                return ref;
+            if (deadline.expired()) {
+                throw new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes within ${describeExpression(expression)}`);
+            }
+            await sleep(POLL_INTERVAL_MS, this.options.signal);
+        }
+    }
+    /** Immediate single resolve for direct reads: zero or multiple matches fail immediately. */
+    async resolveForRead(expression) {
+        const deadline = this.deadline(this.options.actionTimeout);
+        const ref = assertSingle(await this.resolveOnce(expression, deadline), expression);
+        if (ref === null) {
+            throw new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes: ${describeExpression(expression)}`);
+        }
+        return ref;
+    }
+    /**
+     * Resolves all current matches once without waiting. The caller's deadline,
+     * when given, bounds internal retries of retryable backend errors; it
+     * defaults to the action timeout.
+     */
+    async resolveAll(expression, deadline = this.deadline(this.options.actionTimeout)) {
+        return this.resolveOnce(expression, deadline);
+    }
+    /**
+     * Reads one node snapshot. A concurrent locator can supersede the ref
+     * between resolve and read; that is a repeatable race, so it re-resolves
+     * while the deadline remains instead of failing the test.
+     */
+    async read(expression) {
+        const deadline = this.deadline(this.options.actionTimeout);
+        for (;;) {
+            const ref = await this.resolveForRead(expression);
+            try {
+                return await this.session.read(ref, this.operationWithin(deadline));
+            }
+            catch (cause) {
+                const backendError = asBackendError(cause);
+                if (backendError?.code === 'NODE_STALE' && backendError.retryable && !deadline.expired()) {
+                    continue;
+                }
+                throw translateLocatorError(cause, expression);
+            }
+        }
+    }
+    /** Reads one node for polling surfaces; returns null while zero matches. */
+    async tryRead(expression, deadline) {
+        const ref = assertSingle(await this.resolveOnce(expression, deadline), expression);
+        if (ref === null)
+            return { node: null, count: 0 };
+        try {
+            const node = await this.session.read(ref, this.operationWithin(deadline));
+            return { node, count: 1 };
+        }
+        catch (cause) {
+            if (asBackendError(cause)?.code === 'NODE_STALE') {
+                return { node: null, count: 0 };
+            }
+            throw translateLocatorError(cause, expression);
+        }
+    }
+    /**
+     * Performs exactly one action against exactly one match. Stale nodes are
+     * re-resolved while the deadline remains; a possibly committed action is
+     * never repeated. An action that itself names other nodes (dragTo) is built
+     * per attempt, so its refs are re-resolved together with the source.
+     */
+    async perform(expression, action, timeoutMs) {
+        const deadline = this.deadline(timeoutMs);
+        for (;;) {
+            const ref = await this.resolveExactlyOne(expression, deadline);
+            const resolved = typeof action === 'function' ? await action(deadline) : action;
+            try {
+                await this.session.perform(ref, resolved, this.operationWithin(deadline));
+                return;
+            }
+            catch (cause) {
+                const backendError = asBackendError(cause);
+                if (backendError?.code === 'NODE_STALE' &&
+                    backendError.retryable &&
+                    !deadline.expired()) {
+                    continue;
+                }
+                throw translateLocatorError(cause, expression);
+            }
+        }
+    }
+}
+/** Zero matches -> null; one -> the ref; many -> LOCATOR_AMBIGUOUS. */
+function assertSingle(refs, expression) {
+    if (refs.length > 1) {
+        throw new TestError('LOCATOR_AMBIGUOUS', `locator matched ${refs.length} nodes, expected exactly one: ${describeExpression(expression)}`);
+    }
+    return refs[0] ?? null;
+}
+/** Translates a backend error into the runner-owned public taxonomy. */
+export function translateLocatorError(cause, expression) {
+    const suffix = expression === undefined ? '' : `: ${describeExpression(expression)}`;
+    return translateBackendError(cause, suffix);
+}
+//# sourceMappingURL=engine.js.map

package/dist/locator/engine.js.map

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

package/dist/locator/expression.d.ts

@@ -0,0 +1,19 @@
+/** Immutable locator expression construction (spec 08-platforms.md). */
+import type { LocatorExpression } from '../backend/surface.ts';
+import type { Role, RoleOptions, TextMatch, TextMatchOptions } from '../types.ts';
+/** Builds a role query expression. */
+export declare function roleQuery(role: Role, options: RoleOptions | undefined, scope: LocatorExpression | undefined): LocatorExpression;
+/** Builds a text-family query expression (label, placeholder, text, displayValue). */
+export declare function textQuery(kind: 'label' | 'placeholder' | 'text' | 'displayValue', text: TextMatch, options: TextMatchOptions | undefined, scope: LocatorExpression | undefined): LocatorExpression;
+/** Builds a test-id query expression. */
+export declare function testIdQuery(id: string, scope: LocatorExpression | undefined): LocatorExpression;
+/** Builds a filter expression; an empty filter object is an immediate error. */
+export declare function filterExpression(source: LocatorExpression, options: {
+    hasText?: TextMatch;
+    has?: LocatorExpression;
+}): LocatorExpression;
+/** Builds an index expression; negative indices are errors. */
+export declare function indexExpression(source: LocatorExpression, index: number | 'first' | 'last'): LocatorExpression;
+/** Renders an expression for diagnostics. */
+export declare function describeExpression(expression: LocatorExpression): string;
+//# sourceMappingURL=expression.d.ts.map

package/dist/locator/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../src/locator/expression.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,uBAAuB,CAAC;AAG9E,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAElF,sCAAsC;AACtC,wBAAgB,SAAS,CACvB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GACnC,iBAAiB,CAenB;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,cAAc,EACvD,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GACnC,iBAAiB,CAKnB;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,SAAS,GAAG,iBAAiB,CAK/F;AAUD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACxD,iBAAiB,CAUnB;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAC/B,iBAAiB,CAKnB;AAED,6CAA6C;AAC7C,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAgCxE"}

package/dist/locator/expression.js

@@ -0,0 +1,85 @@
+/** Immutable locator expression construction (spec 08-platforms.md). */
+import { toTextPattern } from '../internal/text.js';
+import { TestError } from '../internal/errors.js';
+/** Builds a role query expression. */
+export function roleQuery(role, options, scope) {
+    const states = {};
+    for (const key of ['checked', 'disabled', 'selected', 'expanded', 'hidden']) {
+        const value = options?.[key];
+        if (value !== undefined)
+            states[key] = value;
+    }
+    const query = {
+        kind: 'role',
+        value: { kind: 'string', value: role, exact: true },
+        ...(options?.name !== undefined
+            ? { name: toTextPattern(options.name, { exact: options.exact ?? true }) }
+            : {}),
+        ...(Object.keys(states).length > 0 ? { states } : {}),
+    };
+    return scoped({ kind: 'query', query }, scope);
+}
+/** Builds a text-family query expression (label, placeholder, text, displayValue). */
+export function textQuery(kind, text, options, scope) {
+    return scoped({ kind: 'query', query: { kind, value: toTextPattern(text, { exact: options?.exact ?? true }) } }, scope);
+}
+/** Builds a test-id query expression. */
+export function testIdQuery(id, scope) {
+    return scoped({ kind: 'query', query: { kind: 'testId', value: { kind: 'string', value: id, exact: true } } }, scope);
+}
+function scoped(expression, scope) {
+    if (scope === undefined)
+        return expression;
+    return { ...expression, scope };
+}
+/** Builds a filter expression; an empty filter object is an immediate error. */
+export function filterExpression(source, options) {
+    if (options.hasText === undefined && options.has === undefined) {
+        throw new TestError('INVALID_LOCATOR', 'filter() requires hasText and/or has');
+    }
+    return {
+        kind: 'filter',
+        source,
+        ...(options.hasText !== undefined ? { hasText: toTextPattern(options.hasText, { exact: false }) } : {}),
+        ...(options.has !== undefined ? { has: options.has } : {}),
+    };
+}
+/** Builds an index expression; negative indices are errors. */
+export function indexExpression(source, index) {
+    if (typeof index === 'number' && (!Number.isInteger(index) || index < 0)) {
+        throw new TestError('INVALID_LOCATOR', `nth() index must be a nonnegative integer, got ${index}`);
+    }
+    return { kind: 'index', source, index };
+}
+/** Renders an expression for diagnostics. */
+export function describeExpression(expression) {
+    switch (expression.kind) {
+        case 'query': {
+            const query = expression.query;
+            const value = query.value.kind === 'string' ? JSON.stringify(query.value.value) : `/${query.value.source}/${query.value.flags}`;
+            const name = query.name === undefined
+                ? ''
+                : `, name: ${query.name.kind === 'string' ? JSON.stringify(query.name.value) : `/${query.name.source}/${query.name.flags}`}`;
+            const scope = expression.scope === undefined ? '' : `${describeExpression(expression.scope)} >> `;
+            return `${scope}getBy${query.kind[0].toUpperCase()}${query.kind.slice(1)}(${value}${name})`;
+        }
+        case 'filter': {
+            const parts = [];
+            if (expression.hasText !== undefined) {
+                parts.push(`hasText: ${expression.hasText.kind === 'string' ? JSON.stringify(expression.hasText.value) : `/${expression.hasText.source}/${expression.hasText.flags}`}`);
+            }
+            if (expression.has !== undefined)
+                parts.push(`has: ${describeExpression(expression.has)}`);
+            return `${describeExpression(expression.source)}.filter({ ${parts.join(', ')} })`;
+        }
+        case 'index':
+            return typeof expression.index === 'number'
+                ? `${describeExpression(expression.source)}.nth(${expression.index})`
+                : `${describeExpression(expression.source)}.${expression.index}()`;
+        case 'selector':
+            return `locator(${JSON.stringify(expression.selector)})`;
+        case 'frame':
+            return `frameLocator(${JSON.stringify(expression.selector)}) >> ${describeExpression(expression.source)}`;
+    }
+}
+//# sourceMappingURL=expression.js.map

package/dist/locator/expression.js.map

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

package/dist/locator/screen.d.ts

@@ -0,0 +1,36 @@
+/** Public Screen and Locator surfaces bound to one attempt. */
+import type { LocatorExpression } from '../backend/surface.ts';
+import type { Locator, Screen, Secret } from '../types.ts';
+import type { StepRecorder } from '../run/steps.ts';
+import { type LocatorEngine } from './engine.ts';
+export interface SecretResolver {
+    /**
+     * Resolves an opaque Secret to its plaintext for a closed input sink, at
+     * fill time — a provider-backed credential may compute it fresh per fill.
+     */
+    resolve(secret: Secret): Promise<string>;
+}
+export interface ScreenContext {
+    readonly engine: LocatorEngine;
+    readonly steps: StepRecorder;
+    readonly secrets: SecretResolver;
+    /** Base directory for resolving relative file paths, e.g. uploads. */
+    readonly projectRoot?: string;
+}
+export declare function isSecret(value: unknown): value is Secret;
+/** Internal accessor used by expect() to reach a locator's expression/engine. */
+export interface LocatorInternals {
+    readonly expression: LocatorExpression;
+    readonly context: ScreenContext;
+}
+export declare function locatorInternals(locator: unknown): LocatorInternals | undefined;
+/** Creates the screen fixture for one attempt. */
+export declare function createScreen(context: ScreenContext): Screen;
+/**
+ * Creates a screen scope whose every query is wrapped by `wrap` - a
+ * contributed fixture scoping queries into a nested document, for example.
+ */
+export declare function createScopedScreen(context: ScreenContext, wrap: (expression: LocatorExpression) => LocatorExpression): Screen;
+/** Creates a public locator from a raw expression (a contributed fixture's platform selector). */
+export declare function createLocator(context: ScreenContext, expression: LocatorExpression): Locator;
+//# sourceMappingURL=screen.d.ts.map

package/dist/locator/screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../../src/locator/screen.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAG/D,OAAO,KAAK,EAAE,iBAAiB,EAAgB,MAAM,uBAAuB,CAAC;AAK7E,OAAO,KAAK,EAEV,OAAO,EAGP,MAAM,EACN,MAAM,EAKP,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAWhE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAMxD;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAQD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAI/E;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,CAAC,UAAU,EAAE,iBAAiB,KAAK,iBAAiB,GACzD,MAAM,CAER;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAE5F"}