@lingxia/test 0.18.0 → 0.20.0

package/dist/fixture.js

@@ -1,21 +1,41 @@
-import { AssertionError, applyMatcher, expect as immediateExpect, popAssertionSilence, pushAssertionSilence, setAssertionSink, } from "./expect.js";
-import { formatValue, truncate } from "./format.js";
+import { AssertionError, applyMatcher, check, popAssertionSilence, pushAssertionSilence, setExpectScope, } from "./expect.js";
+import { firstDifference, formatValue, truncate } from "./format.js";
 import { encodeAttachPayload, remapStack } from "./host.js";
 import { rememberInline } from "./report.js";
+import { NetworkScope, wrapNetwork } from "./network.js";
+import { ScenarioScope, installScenario } from "./mock.js";
+import { ClockScope, wrapClock } from "./clock.js";
+import { watchDialogs, wrapDialogs } from "./dialogs.js";
+import { activeOpenApi } from "./openapi.js";
+import { ActionDeadline, TimeoutError, asFixtureTimeout } from "./deadline.js";
+import { isTransientTransportError, matchesErrorCode } from "./deadline.js";
+import { checkJsonArgs, explainRemoteError, isRetryableRemoteError, functionDetail, logicScript, pageScript } from "./remote.js";
 import { callerLocation, displayLocation, isFrameworkFrame, parseFrames, resolveOrigin } from "./ids.js";
-import { PageLocator, sleep, testIdSelector, } from "./locator.js";
+import { PageLocator, normalizeText, sleep, testIdSelector, } from "./locator.js";
 import { DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SPEC_TIMEOUT_MS, MAX_ACTIONS, MAX_EVAL_BUDGET_MS, WEDGED_DEFER_BUDGET_MS, } from "./version.js";
-export class TimeoutError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "TimeoutError";
+export { TimeoutError };
+/**
+ * Thrown by `t.skip()`. It unwinds the spec like any throw, but the runtime
+ * grades it `skipped`, never `failed` — and not `xfail` under `spec.fail`.
+ * Internal: a spec never needs to name it.
+ */
+export class SkipSignal extends Error {
+    constructor(reason) {
+        super(`skipped: ${reason}`);
+        this.reason = reason;
+        this.name = "SkipSignal";
+        this.code = "E_SKIPPED";
     }
 }
 export class LiveFixture {
-    constructor(specId, rawApp, host, args, automation, specBudgetMs = DEFAULT_SPEC_TIMEOUT_MS) {
+    traceMeta() {
+        return { sequence: ++this.eventSequence, at_ms: Math.max(0, Date.now() - this.startedAt) };
+    }
+    constructor(specId, rawApp, host, args, automation, specBudgetMs = DEFAULT_SPEC_TIMEOUT_MS, redactor, appId, traceOriginMs) {
         this.specId = specId;
         this.host = host;
         this.specBudgetMs = specBudgetMs;
+        this.redactor = redactor;
         this.steps = [];
         /**
          * `lx.*` members this spec's evals actually reached. Collected so the report
@@ -30,57 +50,236 @@ export class LiveFixture {
         this.abortError = null;
         this.actionSilence = 0;
         this.actionCount = 0;
+        this.traceTruncated = false;
+        this.eventSequence = 0;
         /** Actions still in flight, so an abort can mark them instead of leaving
          *  them at their optimistic default. */
         this.openActions = new Set();
+        /** Fixture calls that have started and not settled; see `track`. */
+        this.inFlight = new Set();
         this.cleanupUntil = 0;
         this.cleanupActive = false;
+        /**
+         * The spec reached an app page (a locator, view, nav or page-bound Logic
+         * call). A failure names the current page only then: a unit spec that
+         * never touched one is not "on" whatever page the app happens to show.
+         */
+        this.usedPage = false;
         this.failurePhase = null;
+        /** Locator assertions that timed out, by error: the page instance they were bound to. */
+        this.locatorFailures = new WeakMap();
+        /** Instance ids `t.app.page()` bound, so a trace detail's `#id` is not read from a CSS selector. */
+        this.boundPages = new Set();
         this.stepStack = [];
-        this.rawApp = rawApp;
-        this.args = args;
-        setAssertionSink((entry) => this.noteAssertion(entry));
-        const root = guardObject(automation, this, "", ["lxapp"]);
+        this.stepStarted = new WeakMap();
+        /** Every app a fixture app reaches; a profile switch re-selects them. */
+        this.appRefs = [];
+        this.dialogWatches = new Map();
+        this.dialogInitializers = new Map();
+        this.networkScope = new NetworkScope();
+        /** The scenario this spec installed; removed when it ends. */
+        this.scenarioScope = new ScenarioScope();
+        /** Test clocks this spec installed; uninstalled when it ends. */
+        this.clockScope = new ClockScope();
+        this.pinned = { appid: appId, driver: rawApp };
+        this.appRefs.push(this.pinned);
+        this.hostAutomation = automation;
+        this.startedAt = traceOriginMs ?? Date.now();
+        this.argValues = args;
+        this.specDeadline = Date.now() + specBudgetMs;
+        let resolveDialogFailure;
+        this.dialogFailure = new Promise((resolve) => { resolveDialogFailure = resolve; });
+        this.resolveDialogFailure = resolveDialogFailure;
+        setExpectScope({
+            note: (entry) => this.noteAssertion(entry),
+            locator: (locator, message) => this.locatorMatchers(locator, false, message),
+            poll: (read, options) => this.pollMatchers(read, options, false, "expect.poll"),
+        });
+        const root = guardObject(automation, this, "", ["lxapp", ...HOST_TIERS]);
         this.automation = new Proxy(root, {
             get: (target, prop) => prop === "lxapp"
                 ? (appId) => {
                     this.assertRunnable();
-                    return this.wrapApp(appId === undefined ? automation.lxapp() : automation.lxapp(appId));
+                    return this.appOf(appId === undefined ? this.pinned : this.refFor(appId));
                 }
-                : Reflect.get(target, prop),
+                // Reading a host tier never throws, even on a host without it; each
+                // call resolves it and rejects there instead.
+                : HOST_TIERS.includes(prop)
+                    ? lazyDriver(() => ({ owner: automation, value: Reflect.get(automation, prop) }), this, `${String(prop)}.`)
+                    : Reflect.get(target, prop),
         });
-        this.apps = { lxapp: (appId) => this.automation.lxapp(appId) };
     }
     get app() {
-        return this.wrapApp(this.rawApp);
+        return this.appOf(this.pinned);
+    }
+    get scenario() {
+        return { use: async (definition, options) => {
+                const app = options?.app;
+                if (app === undefined) {
+                    return installScenario(() => this.pinned.driver, this, this.scenarioScope, definition, options?.variant);
+                }
+                if (typeof app !== "string" || app.trim() === "") {
+                    throw new TypeError("t.scenario.use { app } must be a non-empty app id");
+                }
+                // Function rules go to the run's companion, which no app scopes.
+                const appScoped = "t.scenario.use { app } takes a scenario of http rules only; function rules are not app-scoped";
+                if (hasFunctionRules(definition, options?.variant))
+                    throw new TypeError(appScoped);
+                const ref = this.refFor(app);
+                const scenario = await installScenario(() => ref.driver, this, this.scenarioScope, definition, options?.variant);
+                if (scenario.rules.some((rule) => rule.kind === "function")) {
+                    await scenario.remove();
+                    throw new TypeError(appScoped);
+                }
+                return scenario;
+            } };
     }
     get raw() {
-        return this.rawApp;
+        return this.pinned.driver;
+    }
+    async watchPrimaryDialogs() {
+        await this.ensureDialogWatch(this.pinned);
+    }
+    ensureDialogWatch(ref) {
+        const pending = this.dialogInitializers.get(ref);
+        if (pending)
+            return pending;
+        const task = this.startDialogWatch(ref).finally(() => { this.dialogInitializers.delete(ref); });
+        this.dialogInitializers.set(ref, task);
+        return task;
+    }
+    async startDialogWatch(ref) {
+        const appid = ref.appid ?? (await new ActionDeadline(DEFAULT_ACTION_TIMEOUT_MS, this.budgetRoom())
+            .call("dialog watch app info", () => ref.driver.info(), () => "starting dialog watch")).appId;
+        ref.appid = appid;
+        if (this.dialogWatches.has(appid))
+            return;
+        const watch = watchDialogs(ref.driver);
+        // Only another app's dialog needs its app named.
+        const label = (message) => ref === this.pinned ? message : `${appid}: ${message}`;
+        this.dialogWatches.set(appid, { ref, watch, label });
+        if (watch)
+            void watch.unanswered.then((message) => this.resolveDialogFailure(label(message)));
+    }
+    async endDialogWatches() {
+        const unused = [];
+        const failures = [];
+        for (const [appid, entry] of this.dialogWatches) {
+            try {
+                const message = await entry.watch?.end(entry.ref.driver);
+                if (message)
+                    unused.push(entry.label(message));
+            }
+            catch (error) {
+                failures.push(entry.label(String(error)));
+            }
+            this.dialogWatches.delete(appid);
+        }
+        return { unused, failures };
+    }
+    /** One fixture app per reached app, so a saved handle stays the same object. */
+    appOf(ref) {
+        return ref.app ?? (ref.app = this.wrapApp(ref));
+    }
+    refFor(appid) {
+        return this.appRefs.find((ref) => ref.appid === appid) ??
+            this.trackRef({ appid, driver: this.hostAutomation.lxapp(appid) });
+    }
+    trackRef(ref) {
+        this.appRefs.push(ref);
+        return ref;
+    }
+    get openapi() {
+        const index = activeOpenApi();
+        if (!index)
+            return undefined;
+        return {
+            documents: index.documents.map((doc) => ({
+                name: doc.name,
+                version: doc.version,
+                ...(doc.title ? { title: doc.title } : {}),
+            })),
+        };
+    }
+    /** `t.app.profile`: it re-selects the app after a switch. */
+    profileFixture(ref) {
+        return {
+            checkpoint: () => this.act("profile.checkpoint", "", () => this.reopening(ref, async (driver) => ({ id: await driver.profile.checkpoint() }))),
+            restore: (checkpoint, options) => {
+                const id = checkpointId(checkpoint, "t.app.profile.restore");
+                return this.act("profile.restore", options?.keep?.length ? `${id} keep ${options.keep.join(",")}` : id, () => this.reopening(ref, (driver) => options?.keep?.length ? driver.profile.restore(id, { keep: [...options.keep] }) : driver.profile.restore(id)));
+            },
+            drop: (checkpoint) => {
+                const id = checkpointId(checkpoint, "t.app.profile.drop");
+                return this.act("profile.drop", id, async () => { await ref.driver.profile.drop(id); });
+            },
+        };
+    }
+    /**
+     * A profile switch closes the app and reopens it as a new instance, which
+     * the old driver no longer reaches: select the same lxapp again after it,
+     * for every fixture app that reaches it. Fixture apps read `ref.driver` on
+     * each call, so one saved before the switch follows the reopened app.
+     */
+    async reopening(ref, op) {
+        const appid = ref.appid ?? (await ref.driver.info()).appId;
+        ref.appid = appid;
+        // The no-arg alias is `pinned`; an explicit same-app alias can still be
+        // reached before its id was known. A closed unrelated app must not block
+        // this profile switch just because its handle was read earlier.
+        if (this.pinned.appid === undefined && ref !== this.pinned) {
+            try {
+                this.pinned.appid = (await this.pinned.driver.info()).appId;
+            }
+            catch { /* unavailable alias */ }
+        }
+        try {
+            return await op(ref.driver);
+        }
+        finally {
+            for (const reached of this.appRefs) {
+                if (reached.appid === appid)
+                    reached.driver = this.hostAutomation.lxapp(appid);
+            }
+        }
     }
     step(name, body) {
-        return this.guard(async () => {
+        return this.runStep(name, body);
+    }
+    runStep(name, body, parent) {
+        return this.track("t.step", name, () => this.guard(async () => {
+            const active = this.stepStack[this.stepStack.length - 1];
+            if (active !== parent) {
+                const conflict = new Error("Overlapping t.step calls cannot share an implicit step owner. Await top-level steps sequentially; nest with the callback scope: t.step('outer', async (step) => step.step('inner', ...)).");
+                this.stepConflict ?? (this.stepConflict = conflict);
+                throw conflict;
+            }
             const record = {
                 name,
-                path: [...this.stepStack.map((step) => step.name), name].join(" > "),
+                ...this.traceMeta(),
+                path: parent ? `${parent.path} > ${name}` : name,
                 status: "passed",
                 duration_ms: 0,
                 steps: [],
                 attachments: [],
                 assertions: [],
             };
-            const parent = this.stepStack[this.stepStack.length - 1];
             (parent ? parent.steps : this.steps).push(record);
             this.stepStack.push(record);
-            await this.host.emit({
+            const started = Date.now();
+            this.stepStarted.set(record, started);
+            await this.emitTrace({
                 type: "step_started",
                 name,
                 path: record.path,
             });
-            const started = Date.now();
             try {
-                const result = await body();
+                const scope = {
+                    step: (childName, childBody) => this.runStep(childName, childBody, record),
+                };
+                const result = await body(scope);
                 record.duration_ms = Date.now() - started;
-                await this.host.emit({
+                await this.emitTrace({
                     type: "step_finished",
                     name,
                     path: record.path,
@@ -91,10 +290,21 @@ export class LiveFixture {
             }
             catch (error) {
                 record.duration_ms = Date.now() - started;
+                if (error instanceof SkipSignal) {
+                    record.status = "skipped";
+                    await this.emitTrace({
+                        type: "step_finished",
+                        name,
+                        path: record.path,
+                        status: record.status,
+                        duration_ms: record.duration_ms,
+                    });
+                    throw error;
+                }
                 record.status = error instanceof TimeoutError ? "timeout" : "failed";
                 record.error = toReportError(error, record.path);
                 this.lastStepPath = record.path;
-                await this.host.emit({
+                await this.emitTrace({
                     type: "step_finished",
                     name,
                     path: record.path,
@@ -105,14 +315,12 @@ export class LiveFixture {
                 throw error;
             }
             finally {
-                this.stepStack.pop();
+                this.stepStarted.delete(record);
+                const index = this.stepStack.lastIndexOf(record);
+                if (index >= 0)
+                    this.stepStack.splice(index, 1);
             }
-        });
-    }
-    get expect() {
-        const fn = ((locator) => this.locatorMatchers(locator, false));
-        fn.poll = (read, options) => this.pollMatchers(read, options, false);
-        return fn;
+        }));
     }
     async reject(operation, expected = {}) {
         return this.guard(async () => {
@@ -142,7 +350,7 @@ export class LiveFixture {
                 ].filter(Boolean).join("\n"));
             }
             const record = received;
-            if (expected.code !== undefined && record.code !== expected.code) {
+            if (expected.code !== undefined && !matchesErrorCode(received, expected.code)) {
                 this.noteAssertion({
                     matcher: "reject",
                     expected: formatValue(expected.code),
@@ -158,10 +366,10 @@ export class LiveFixture {
                 ].filter(Boolean).join("\n"));
             }
             if (typeof expected.message === "string") {
-                immediateExpect(String(record.message)).toContain(expected.message);
+                check(String(record.message)).toContain(expected.message);
             }
             if (expected.message instanceof RegExp) {
-                immediateExpect(String(record.message)).toMatch(expected.message);
+                check(String(record.message)).toMatch(expected.message);
             }
             this.noteAssertion({
                 matcher: "reject",
@@ -175,12 +383,114 @@ export class LiveFixture {
     defer(cleanup) {
         this.defers.push(cleanup);
     }
+    arg(name, options = {}) {
+        const value = this.argValues[name];
+        if (value !== undefined)
+            return value;
+        if (options.default !== undefined)
+            return options.default;
+        if (options.required === false)
+            return undefined;
+        // Keys are case-sensitive: `LXDEV_SECRET_PASSWORD` is `PASSWORD`.
+        const other = Object.keys(this.argValues).find((key) => key !== name && key.toLowerCase() === name.toLowerCase());
+        const hint = other === undefined
+            ? ""
+            : `; "${other}" was given, and arg keys are case-sensitive ` +
+                `(LXDEV_ARG_<KEY> / LXDEV_SECRET_<KEY> keep the case of <KEY>)`;
+        throw new Error(`Missing test arg "${name}": pass --arg ${name}=<value> ` +
+            `(or --secret-arg ${name}=<value>) to lxdev test${hint}`);
+    }
+    waitFor(read, options = {}) {
+        const location = callerLocation();
+        if (typeof options === "function") {
+            throw new TypeError("t.waitFor(read, { until }) takes its acceptance test as `until`, not as a second argument");
+        }
+        const accept = options.until ?? Boolean;
+        const requested = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+        const interval = options.interval ?? DEFAULT_POLL_INTERVAL_MS;
+        if (!Number.isFinite(requested) || requested <= 0 || !Number.isFinite(interval) || interval <= 0) {
+            throw new TypeError("t.waitFor timeout and interval must be positive finite numbers");
+        }
+        const retryIf = options.retryIf ?? isRetryableReadError;
+        const detail = truncate(read.name || functionDetail(read), 80);
+        return this.act("waitFor", detail, async () => {
+            const deadline = new ActionDeadline(requested, this.budgetRoom());
+            let attempts = 0;
+            let hasValue = false;
+            let lastValue;
+            let lastError;
+            this.silenceActions();
+            try {
+                for (;;) {
+                    if (deadline.expired())
+                        break;
+                    attempts += 1;
+                    const before = new Set(this.inFlight);
+                    try {
+                        const value = await deadline.call("t.waitFor read", read, () => `${detail} at ${displayLocation(location.file, location.line, location.column)}`);
+                        if (deadline.expired())
+                            break;
+                        lastValue = value;
+                        hasValue = true;
+                        lastError = undefined;
+                        if (accept(value))
+                            return value;
+                    }
+                    catch (error) {
+                        if (error instanceof SkipSignal || this.aborted)
+                            throw error;
+                        if (error instanceof TimeoutError && deadline.expired()) {
+                            for (const call of this.inFlight)
+                                if (!before.has(call))
+                                    call.detached = true;
+                            break;
+                        }
+                        if (!retryIf(error))
+                            throw error;
+                        lastError = error;
+                    }
+                    const pause = Math.min(interval, deadline.remaining());
+                    if (pause <= 0)
+                        break;
+                    await sleep(pause);
+                    if (this.aborted && this.abortError)
+                        throw this.abortError;
+                }
+            }
+            finally {
+                this.resumeActions();
+            }
+            const last = lastError !== undefined
+                ? `Last error: ${errorLine(lastError)}`
+                : hasValue
+                    ? `Last value: ${formatValue(lastValue)}${accept === Boolean ? " (waiting for a truthy value)" : " (rejected by until)"}`
+                    : "No read completed.";
+            throw new TimeoutError([
+                `t.waitFor timed out after ${deadline.elapsed()}ms (${attempts} ${attempts === 1 ? "read" : "reads"}).`,
+                last,
+                deadline.clampNote(),
+                `at ${displayLocation(location.file, location.line, location.column)}`,
+                this.stepPathLine(),
+            ].filter(Boolean).join("\n"));
+        });
+    }
+    skip(reason) {
+        // Cleanup runs after the verdict; a skip there cannot mean anything.
+        if (this.cleanupActive)
+            throw new Error("t.skip cannot be called during cleanup (t.defer or afterEach)");
+        const text = typeof reason === "string" && reason.trim().length > 0 ? reason : "skipped at runtime";
+        this.skipReason ?? (this.skipReason = text);
+        throw new SkipSignal(text);
+    }
     async attach(name, data) {
         await this.guard(async () => {
             await this.attachRaw(name, data);
         });
     }
-    async attachRaw(name, data) {
+    async attachRaw(name, input, purpose) {
+        // Declared secrets are masked in the data itself, before it is encoded
+        // or previewed, so neither the file nor the report carries them.
+        const data = this.redactor ? this.redactor.attachment(input) : input;
         const payload = encodeAttachPayload(data);
         if (typeof data === "object" && data && "base64" in data && !("mimeType" in data)) {
             if (name.endsWith(".png"))
@@ -196,18 +506,26 @@ export class LiveFixture {
         else if (isPreviewable(payload.mimeType)) {
             rememberInline(this.specId, name, { text: previewText(data, payload) });
         }
-        const ref = { name, path, mimeType: payload.mimeType };
         const current = this.stepStack[this.stepStack.length - 1];
+        const ref = { name, path, mimeType: payload.mimeType, ...this.traceMeta(),
+            ...(current ? { step: current.path } : {}), ...(purpose ? { purpose } : {}) };
         (current ? current.attachments : this.attachments).push(ref);
         return ref;
     }
-    abort(reason) {
+    /**
+     * Stop the body: its fixture calls reject with `reason` from now on. A
+     * timeout marks the actions still open as timed out; a failure (an
+     * unanswered dialog) as failed.
+     */
+    abort(reason, as = "timeout") {
         this.aborted = true;
         this.abortError = reason;
-        this.failurePhase = "timeout";
+        this.failurePhase = as === "timeout" ? "timeout" : "body";
+        this.finishOpenSteps(reason, as);
         for (const record of this.openActions) {
-            record.status = "timeout";
+            record.status = as;
             record.error = toReportError(reason, record.path);
+            this.noteFailedAction(record.name, record.detail, reason);
         }
         this.openActions.clear();
     }
@@ -223,17 +541,108 @@ export class LiveFixture {
      * trace of what it did. Retry loops silence themselves: a five-second poll
      * would otherwise bury the report in a hundred identical rows.
      */
-    async act(name, detail, op) {
+    act(name, detail, op) {
+        if (PAGE_ACTION.test(name))
+            this.usedPage = true;
+        return this.track(name, detail, () => this.recordAct(name, detail, async () => {
+            try {
+                return await op();
+            }
+            catch (error) {
+                const code = error && typeof error === "object" ? error.code : undefined;
+                if (code === "E_EVAL_TIMEOUT" && (name === "logic.eval" || name === "page.data" || name === "view.eval")) {
+                    this.remoteTimeoutKind ?? (this.remoteTimeoutKind = name === "view.eval" ? "View eval" : "Logic eval");
+                }
+                else if (code === "E_AUTOMATION_TIMEOUT" && name === "page.action") {
+                    this.remoteTimeoutKind ?? (this.remoteTimeoutKind = "page action");
+                }
+                throw asFixtureTimeout(error);
+            }
+        }));
+    }
+    /**
+     * Run one fixture call while it counts as in flight, so a body that
+     * returns without awaiting it can be named (with where it was started),
+     * and a timed-out body can say what it still awaits.
+     */
+    track(name, detail, op, label) {
+        const call = { name, detail, label, started: Date.now(), origin: new Error() };
+        this.inFlight.add(call);
+        const promise = (async () => {
+            try {
+                return await op();
+            }
+            finally {
+                this.inFlight.delete(call);
+            }
+        })();
+        call.promise = promise;
+        return promise;
+    }
+    /** A read `t.waitFor` gave up on is still running in the app. */
+    detachedInFlight() {
+        return [...this.inFlight].some((entry) => entry.detached);
+    }
+    /**
+     * The fixture calls still running, as a body that returned without
+     * awaiting them left them: what each is and where the spec started it.
+     */
+    unsettledCalls() {
+        const now = Date.now();
+        return [...this.inFlight].filter((entry) => !entry.detached).map((entry) => {
+            const frame = resolveOrigin(parseFrames(entry.origin.stack));
+            return {
+                call: entry.label ?? (entry.detail ? `${entry.name} ${entry.detail}` : entry.name),
+                at: displayLocation(frame.file, frame.line, frame.column),
+                ageMs: now - entry.started,
+            };
+        });
+    }
+    /**
+     * Stop the calls a returned body left running: each fails at its next
+     * fixture guard or retry, and its rejection is marked handled (nobody
+     * awaits it). Resolves `true` once they settled, `false` if one is still
+     * waiting on the app after `ms`. The fixture is usable again afterwards,
+     * for cleanup.
+     */
+    async stopUnsettled(reason, ms) {
+        for (const entry of this.inFlight)
+            entry.promise?.catch(() => { });
+        this.aborted = true;
+        this.abortError = reason;
+        const deadline = Date.now() + ms;
+        while (this.inFlight.size > 0 && Date.now() < deadline)
+            await sleep(10);
+        this.aborted = false;
+        this.abortError = null;
+        return this.inFlight.size === 0;
+    }
+    /**
+     * Fixture calls that have not returned, e.g. a hung `t.app.logic.eval` a
+     * timed-out body still awaits. Unlike the trace rows, this includes calls
+     * made from silenced retry loops.
+     */
+    pendingCalls() {
+        return [...this.inFlight].map((call) => ({
+            kind: /^(?:logic|view)\.eval$|^page\.data$/.test(call.name) ? "eval" : "action",
+            detail: call.detail ? `${call.name} ${call.detail}` : call.name,
+            owner: this.specId,
+            at_ms: call.started - this.startedAt,
+        }));
+    }
+    async recordAct(name, detail, op) {
         if (this.actionSilence > 0)
             return this.guard(op);
         // Past the cap, keep recording failures: the action that finally breaks is
         // the one row worth having, and dropping it leaves nothing pointing at it.
         if (this.actionCount >= MAX_ACTIONS) {
+            this.traceTruncated = true;
             try {
                 return await this.guard(op);
             }
             catch (error) {
                 this.recordFailedAction(name, detail, error, 0);
+                this.noteFailedAction(name, detail, error);
                 throw error;
             }
         }
@@ -245,7 +654,8 @@ export class LiveFixture {
         if (previous?.kind === "action" &&
             previous.status === "passed" &&
             previous.name === name &&
-            previous.detail === detail) {
+            previous.detail === detail &&
+            previous.sequence === this.eventSequence) {
             const started = Date.now();
             try {
                 const result = await this.guard(op);
@@ -257,6 +667,7 @@ export class LiveFixture {
                 // A failure is its own row: it is the one attempt worth reading.
                 const failed = {
                     name,
+                    ...this.traceMeta(),
                     detail,
                     kind: "action",
                     path: previous.path,
@@ -268,12 +679,14 @@ export class LiveFixture {
                     error: toReportError(error, previous.path),
                 };
                 siblings.push(failed);
+                this.noteFailedAction(name, detail, error);
                 throw error;
             }
         }
         this.actionCount += 1;
         const record = {
             name,
+            ...this.traceMeta(),
             detail,
             kind: "action",
             path: [...this.stepStack.map((step) => step.name), name].join(" > "),
@@ -289,7 +702,7 @@ export class LiveFixture {
         // body, so a record left at its optimistic default would serialise as an
         // instant success — the hung call rendered as the fastest one in the trace.
         this.openActions.add(record);
-        await this.host.emit({ type: "step_started", name, path: record.path });
+        await this.emitTrace({ type: "step_started", name, path: record.path });
         try {
             const result = await this.guard(op);
             record.duration_ms = Date.now() - started;
@@ -301,18 +714,64 @@ export class LiveFixture {
             record.status = error instanceof TimeoutError ? "timeout" : "failed";
             record.error = toReportError(error, record.path);
             this.openActions.delete(record);
+            this.noteFailedAction(name, detail, error);
             throw error;
         }
         finally {
-            await this.host.emit({ type: "step_finished", name, path: record.path,
+            await this.emitTrace({ type: "step_finished", name, path: record.path,
                 status: record.status, duration_ms: record.duration_ms, error: record.error });
         }
     }
+    /**
+     * A trace event is progress for lxdev, not part of the spec: one the
+     * transport drops is sent once more and then given up, and never fails the
+     * action it describes. The report is built from the fixture's own records.
+     */
+    async emitTrace(event) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                await this.host.emit(event);
+                return;
+            }
+            catch {
+                // Next attempt, then give up.
+            }
+        }
+    }
+    /**
+     * A note beside the trace. A warning unless `level` is `"info"`: expected
+     * housekeeping, such as the timers the spec's own clock dropped, which
+     * lxdev shows only with `--verbose`.
+     */
+    async diagnostic(phase, message, level) {
+        await this.emitTrace({ type: "diagnostic", phase, message, ...(level ? { level } : {}) });
+    }
+    /**
+     * An idempotent driver read, retried when the transport between the test
+     * runtime and the app dropped it. Never used for input or other calls with
+     * side effects: those may already have landed.
+     */
+    async readRetrying(read) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await read();
+            }
+            catch (error) {
+                if (attempt >= TRANSPORT_RETRIES || !isTransientTransportError(error) || this.aborted)
+                    throw error;
+                await sleep(TRANSPORT_RETRY_DELAY_MS * (attempt + 1));
+            }
+        }
+    }
+    noteFailedAction(name, detail, error) {
+        this.failedAction = { action: detail ? `${name} ${detail}` : name, error };
+    }
     recordFailedAction(name, detail, error, duration) {
         const parent = this.stepStack[this.stepStack.length - 1];
         const path = [...this.stepStack.map((step) => step.name), name].join(" > ");
         (parent ? parent.steps : this.steps).push({
             name,
+            ...this.traceMeta(),
             detail,
             kind: "action",
             path,
@@ -336,6 +795,18 @@ export class LiveFixture {
         this.assertRunnable();
         return result;
     }
+    /**
+     * Milliseconds an action or assertion may still take. Short of the spec's
+     * own deadline by a margin, so the action fails first and names its step
+     * instead of losing the race to the anonymous spec timeout. During cleanup
+     * the cleanup budget bounds it instead.
+     */
+    budgetRoom() {
+        if (this.cleanupActive)
+            return this.cleanupUntil > 0 ? this.cleanupUntil - Date.now() : Number.POSITIVE_INFINITY;
+        const margin = Math.min(250, Math.floor(this.specBudgetMs / 20));
+        return this.specDeadline - margin - Date.now();
+    }
     currentStepPath() {
         const current = this.stepStack[this.stepStack.length - 1];
         return current?.path ?? this.lastStepPath;
@@ -343,12 +814,48 @@ export class LiveFixture {
     noteAssertion(entry) {
         const record = {
             ...entry,
+            ...this.traceMeta(),
             step: this.currentStepPath(),
         };
         const current = this.stepStack[this.stepStack.length - 1];
         (current ? current.assertions : this.assertions).push(record);
     }
-    close() { this.closed = true; }
+    close() {
+        this.closed = true;
+        this.finishOpenSteps(new Error("step was still running when the spec ended"), "failed");
+    }
+    finishOpenSteps(reason, status) {
+        for (const record of this.stepStack) {
+            if (record.status !== "passed")
+                continue;
+            record.status = status;
+            record.duration_ms = Date.now() - (this.stepStarted.get(record) ?? Date.now());
+            record.error = toReportError(reason, record.path);
+        }
+    }
+    /**
+     * Remove what the framework installed for this spec — its routes, mock
+     * scenario and test clocks — apart from the spec's own cleanup, and
+     * whether or not its body settled. Resolves one message per failure; a
+     * resource already gone is removed.
+     */
+    async reclaim() {
+        const failures = [];
+        const tasks = [
+            () => this.networkScope.reclaim(),
+            () => this.scenarioScope.reclaim(),
+            () => this.clockScope.reclaim((phase, message, level) => this.diagnostic(phase, message, level)),
+        ];
+        for (const task of tasks) {
+            try {
+                await task();
+            }
+            catch (error) {
+                failures.push(String(error?.message ?? error));
+            }
+        }
+        return failures;
+    }
     assertRunnable() {
         if (this.closed)
             throw new Error("Test fixture is closed");
@@ -365,152 +872,407 @@ export class LiveFixture {
         const path = this.currentStepPath();
         return path ? `in step ${JSON.stringify(path)}` : "";
     }
-    wrapApp(driver) {
-        const page = this.wrapPage(driver.page);
+    wrapApp(ref) {
+        const fixture = this;
+        const driver = () => ref.driver;
+        const input = lazyDriver(() => ({ owner: driver().page, value: driver().page }), fixture, "window.");
         return {
-            page,
-            nav: guardObject(driver.nav, this, "nav."),
-            info: () => this.act("app.info", "", () => driver.info()),
-            pages: () => this.act("app.pages", "", () => driver.pages()),
-            surfaceLayout: () => this.act("app.surfaceLayout", "", () => driver.surfaceLayout()),
-            eval: (options) => this.act("app.eval", summarise(options), async () => {
-                // Ask the runtime which `lx.*` the script reached, and hand the
-                // caller only the value — the observation is the report's business,
-                // not the spec author's, and specs must not have to opt in for their
-                // coverage to be measured.
-                const result = (await driver.eval({
-                    ...this.withEvalBudget(options),
-                    captureCalls: true,
-                }));
-                // The marker, not the shape, identifies the envelope: a script that
-                // returns undefined loses its `value` key on the wire, and sniffing
-                // for that key handed the envelope itself back as the result.
-                if (result && typeof result === "object" && result.__lxEval === 1) {
-                    const { calls, value } = result;
-                    if (Array.isArray(calls)) {
-                        for (const call of calls) {
-                            if (typeof call === "string")
-                                this.observed.add(call);
-                        }
+            page: (selector, options) => this.bindPage(driver, selector, options),
+            view: this.wrapView(() => driver().page, undefined),
+            window: {
+                get pointer() { return input.pointer; },
+                get key() { return input.key; },
+            },
+            logic: this.wrapLogic(driver),
+            nav: this.wrapNav(() => driver().nav),
+            // Lazy: the driver is read inside each traced call.
+            get network() {
+                return wrapNetwork(() => driver().network, fixture, fixture.networkScope);
+            },
+            get profile() {
+                return fixture.profileFixture(ref);
+            },
+            // Lazy and non-throwing like `network`; spec-scoped: uninstalled when
+            // the spec ends.
+            get clock() {
+                return wrapClock(() => ({ driver: driver().clock, appid: async () => (await driver().info()).appId }), fixture, fixture.clockScope, () => fixture.hostAutomation);
+            },
+            // Lazy and non-throwing like `clock`; the runner watches the app under
+            // test for each spec.
+            get dialogs() {
+                return wrapDialogs(() => driver().dialogs, fixture, () => fixture.ensureDialogWatch(ref));
+            },
+            info: () => this.act("app.info", "", () => this.readRetrying(() => driver().info())),
+            pages: () => this.act("app.pages", "", () => this.readRetrying(() => driver().pages())),
+            surfaceLayout: () => this.act("app.surfaceLayout", "", () => this.readRetrying(() => driver().surfaceLayout())),
+        };
+    }
+    /**
+     * Fixture navigation takes the fixture's option names and waits for the
+     * landed page's `onReady` unless the caller picks `waitUntil: 'commit'`;
+     * reads retry a dropped transport.
+     */
+    wrapNav(nav) {
+        const land = (verb) => (options) => this.act(`nav.${verb}`, summarise(options), () => nav()[verb](this.navOptions(options, `t.app.nav.${verb}`)));
+        const read = (verb, op, detail) => this.act(`nav.${verb}`, summarise(detail), () => this.readRetrying(op));
+        return {
+            to: land("to"),
+            redirect: land("redirect"),
+            switchTab: land("switchTab"),
+            relaunch: land("relaunch"),
+            back: (options) => this.act("nav.back", summarise(options), () => nav().back(this.navOptions(options ?? {}, "t.app.nav.back"))),
+            current: () => read("current", () => nav().current()),
+            info: (options) => read("info", () => nav().info(options), options),
+            stack: () => read("stack", () => nav().stack()),
+        };
+    }
+    bindPage(driver, selector, options) {
+        if (selector !== undefined) {
+            const keys = [selector?.name, selector?.instanceId].filter(value => value !== undefined);
+            if (keys.length !== 1 || typeof keys[0] !== "string" || keys[0].trim() === "") {
+                return Promise.reject(new TypeError("t.app.page(selector): select exactly one non-empty name or instanceId"));
+            }
+        }
+        const timeout = options?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            return Promise.reject(new TypeError("t.app.page(selector, { timeout }) takes a positive number of ms"));
+        }
+        const wanted = selector === undefined ? "the current page" : selector.name !== undefined
+            ? `page ${JSON.stringify(selector.name)}` : `page instance #${selector.instanceId}`;
+        return this.act("page.bind", summarise(selector), async () => {
+            // Capture this app driver: reopening the app must not retarget the handle.
+            const app = driver();
+            const deadline = new ActionDeadline(timeout, this.budgetRoom());
+            let info;
+            let last = "not open";
+            for (;;) {
+                try {
+                    const found = await deadline.call("t.app.page binding read", () => selector
+                        ? app.nav.info({ page: selector.instanceId ?? selector.name })
+                        : app.nav.current(), () => `waiting for ${wanted}`);
+                    if (deadline.expired())
+                        break;
+                    if (found?.instanceId) {
+                        info = found;
+                        break;
                     }
-                    return value;
+                    last = "no live instance";
                 }
-                // An older runtime ignores `captureCalls` and returns the bare value.
-                return result;
-            }),
+                catch (error) {
+                    if (error instanceof TimeoutError && deadline.expired())
+                        break;
+                    // Not open yet is "not yet"; an unknown page name is an answer.
+                    if (!matchesErrorCode(error, "E_PAGE_NOT_ACTIVE") && !isTransientTransportError(error))
+                        throw error;
+                    last = error instanceof Error ? error.message : String(error);
+                }
+                if (deadline.expired()) {
+                    throw new TimeoutError(`Timed out after ${deadline.elapsed()}ms waiting for ${wanted} to open: ${last}.` +
+                        (deadline.clampNote() ? `\n${deadline.clampNote()}` : ""));
+                }
+                await sleep(Math.min(DEFAULT_POLL_INTERVAL_MS, Math.max(1, deadline.remaining())));
+            }
+            if (!info) {
+                throw new TimeoutError(`Timed out after ${deadline.elapsed()}ms waiting for ${wanted} to open: ${last}.` +
+                    (deadline.clampNote() ? `\n${deadline.clampNote()}` : ""));
+            }
+            const instanceId = info.instanceId;
+            if (selector?.name !== undefined) {
+                const stack = await deadline.call("t.app.page stack read", () => app.nav.stack(), () => `checking whether ${wanted} is ambiguous`);
+                if (deadline.expired()) {
+                    throw new TimeoutError(`Timed out after ${deadline.elapsed()}ms checking ${wanted}.`);
+                }
+                const matches = stack.filter(page => page.path === info.path && page.instanceId);
+                if (matches.length > 1) {
+                    throw new Error(`t.app.page: ${wanted} has ${matches.length} live instances ` +
+                        `(${matches.map(page => `#${page.instanceId}`).join(", ")}); select one by instanceId`);
+                }
+            }
+            this.boundPages.add(instanceId);
+            const view = this.wrapView(() => app.page, instanceId);
+            const invoke = (name, args, timeout) => {
+                if (typeof name !== "string" || name.trim() === "") {
+                    return Promise.reject(new TypeError("page.invoke needs a non-empty action name"));
+                }
+                if (args.length > 1) {
+                    return Promise.reject(new TypeError(`page.actions.${name} takes at most one JSON payload`));
+                }
+                if (timeout !== undefined && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) {
+                    return Promise.reject(new TypeError("page.invoke({ timeout }) takes a positive number of ms"));
+                }
+                checkJsonArgs(args, `page.actions.${name}`);
+                // A timeout stops waiting, but cannot undo a side effect already
+                // performed by the action. Never retry dispatch automatically.
+                return this.act("page.action", `${name} #${instanceId}`, () => {
+                    const budget = Math.floor(Math.min(timeout ?? Number.POSITIVE_INFINITY, this.budgetRoom()));
+                    if (budget < 1) {
+                        throw new TimeoutError(`page.action ${name} #${instanceId} was not dispatched: its action budget expired`);
+                    }
+                    return app.page.action({
+                        page: instanceId, name, ...(args.length > 0 ? { payload: args[0] } : {}),
+                        timeoutMs: budget,
+                    });
+                });
+            };
+            const actions = new Proxy(Object.create(null), {
+                get: (_, name) => {
+                    if (typeof name !== "string" || name === "then")
+                        return undefined;
+                    return (...args) => invoke(name, args);
+                },
+            });
+            return {
+                instanceId,
+                name: info.name ?? info.path,
+                view,
+                actions,
+                invoke: (name, options) => {
+                    if (!options || typeof options !== "object" || Array.isArray(options)) {
+                        return Promise.reject(new TypeError("page.invoke(name, { payload?, timeout? }) needs an options object"));
+                    }
+                    return invoke(name, Object.prototype.hasOwnProperty.call(options, "payload") ? [options.payload] : [], options.timeout);
+                },
+                data: () => this.act("page.data", `#${instanceId}`, () => remote("page.data", "logic", () => this.evalLogic(app, {
+                    script: logicScript(readPageData, [instanceId], "page.data", "snapshot"),
+                }))),
+            };
+        });
+    }
+    /** The driver's options for a fixture nav action. */
+    navOptions(options, api) {
+        if (!options || typeof options !== "object")
+            throw new TypeError(`${api} takes an options object`);
+        if ("timeoutMs" in options)
+            throw new TypeError(`${api} takes { timeout } in ms`);
+        const { timeout, waitUntil = "ready", ...rest } = options;
+        if (timeout !== undefined && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) {
+            throw new TypeError(`${api}({ timeout }) takes a positive number of ms`);
+        }
+        if (waitUntil !== "ready")
+            return { ...rest, waitUntil };
+        const room = Math.max(1, Math.floor(this.budgetRoom()));
+        return { ...rest, waitUntil, timeoutMs: Math.min(timeout ?? NAV_READY_TIMEOUT_MS, room) };
+    }
+    wrapLogic(driver) {
+        return {
+            eval: (...input) => {
+                const { options, fn, args } = evalInput(input);
+                if (typeof fn !== "function") {
+                    throw new TypeError("t.app.logic.eval(fn, ...args) takes a function; a script string is for the raw driver (rawAutomation().lxapp().eval({ script }) from @lingxia/test/runner)");
+                }
+                const script = logicScript(fn, args, "t.app.logic.eval");
+                const timeoutMs = this.evalTimeout(options, "t.app.logic.eval");
+                const detail = `${summarise(functionDetail(fn))}${args.length ? ` args=${summarise(args)}` : ""}`;
+                return this.act("logic.eval", detail, () => remote("t.app.logic.eval", "logic", () => this.evalLogic(driver(), { script, timeoutMs })));
+            },
         };
     }
+    /**
+     * Logic eval that asks the runtime which `lx.*` the script reached and
+     * hands the caller only the value — the observation is the report's
+     * business, not the spec author's, and specs must not have to opt in for
+     * their coverage to be measured.
+     */
+    async evalLogic(driver, options) {
+        const result = (await driver.eval({
+            ...this.withEvalBudget(options, "Logic eval"),
+            captureCalls: true,
+        }));
+        // The marker, not the shape, identifies the envelope: a script that
+        // returns undefined loses its `value` key on the wire, and sniffing
+        // for that key handed the envelope itself back as the result.
+        if (result && typeof result === "object" && result.__lxEval === 1) {
+            const { calls, value } = result;
+            if (Array.isArray(calls)) {
+                for (const call of calls) {
+                    if (typeof call === "string")
+                        this.observed.add(call);
+                }
+            }
+            return value;
+        }
+        throw new Error("t.app.logic.eval: the host answered without the call-capture envelope; " +
+            "it is older than this @lingxia/test — run `lingxia upgrade` and restart the session (`lingxia dev`)");
+    }
     /**
      * The driver's own eval default is a flat few seconds, so a call that runs
      * long under load fails a spec that still had most of its budget left. An
-     * eval gets a share of the spec's budget instead — a third, capped — never
-     * all of it: a call allowed to run the full budget leaves the spec no room
-     * to retry, so one stalled call takes the whole spec down with it.
+     * eval gets `MAX_EVAL_BUDGET_MS` instead, clamped to what the spec has left.
      */
-    withEvalBudget(options) {
-        if (options && typeof options === "object" && options.timeoutMs === undefined) {
-            const share = Math.floor(this.specBudgetMs / 3);
-            return { ...options, timeoutMs: Math.max(1, Math.min(share, MAX_EVAL_BUDGET_MS)) };
+    withEvalBudget(options, name) {
+        const budget = Math.floor(Math.min(options.timeoutMs ?? MAX_EVAL_BUDGET_MS, this.budgetRoom()));
+        if (budget < 1)
+            throw new TimeoutError(`${name} was not dispatched: its action budget expired`);
+        return { ...options, timeoutMs: budget };
+    }
+    /**
+     * An eval's own `timeout`, clamped to the spec's remaining budget; without
+     * one, `withEvalBudget` picks the default.
+     */
+    evalTimeout(options, api) {
+        const timeout = options?.timeout;
+        if (timeout === undefined)
+            return undefined;
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            throw new TypeError(`${api}({ timeout }, fn, ...args) takes a positive number of ms`);
+        }
+        return Math.min(timeout, this.budgetRoom());
+    }
+    viewEval(page, input, api, bound) {
+        const { options, fn, args } = evalInput(input);
+        if (typeof fn !== "function") {
+            throw new TypeError(`${api}(fn, ...args) takes a function; a script string is for the raw driver (rawAutomation().lxapp().page.eval({ script }) from @lingxia/test/runner)`);
+        }
+        if (options && "page" in options) {
+            throw new TypeError(`${api}: page is not an eval option; bind the page with t.app.page({ name }) and use its view`);
         }
-        return options;
+        const script = pageScript(fn, args, api);
+        const timeoutMs = this.evalTimeout(options, api);
+        const detail = `${summarise(functionDetail(fn))}${args.length ? ` args=${summarise(args)}` : ""}`;
+        return this.act("view.eval", bound ? `#${bound} ${detail}` : detail, () => remote(api, "page", () => page().eval(this.withEvalBudget({
+            script,
+            ...(bound ? { page: bound } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        }, "View eval"))));
     }
-    wrapPage(page) {
+    /** `bound` is the immutable instance id captured by app.page(). */
+    wrapView(page, bound) {
         const location = () => {
             const frame = callerLocation();
             return { source: frame.file, line: frame.line, column: frame.column };
         };
-        // Every override lives in the proxy's `get` trap. Assigning onto the proxy
-        // would write straight through to the real driver — `page.eval` would then
-        // call itself forever.
-        const overrides = {
-            testId: (id, options) => this.locator(page, testIdSelector(id), location(), options),
-            css: (selector, options) => this.locator(page, selector, location(), options),
-            eval: (options) => this.act("page.eval", summarise(options), () => page.eval(this.withEvalBudget(options))),
+        // Resolved on each call, like the rest of a fixture app.
+        const lazyPage = {
+            query: (options) => page().query(options),
+            click: (options) => page().click(options),
+            fill: (options) => page().fill(options),
+            press: (options) => page().press(options),
+            type: (options) => page().type(options),
+            eval: (options) => page().eval(options),
         };
-        const guarded = guardObject(page, this, "page.", Object.keys(overrides));
-        return new Proxy(guarded, {
-            get(target, prop, receiver) {
-                if (typeof prop === "string" && prop in overrides)
-                    return overrides[prop];
-                return Reflect.get(target, prop, receiver);
+        const input = lazyDriver(() => ({ owner: page(), value: page() }), this, "page.");
+        const target = bound === undefined ? {} : { page: bound };
+        const noOptions = (api, options) => {
+            if (options !== undefined) {
+                throw new TypeError(`${api}() takes no options: bind another page with t.app.page({ name }) and use its view`);
+            }
+        };
+        return {
+            testId: (id, options) => {
+                noOptions("view.testId", options);
+                return this.locator(lazyPage, testIdSelector(id), location(), target);
             },
-        });
+            css: (selector, options) => {
+                noOptions("view.css", options);
+                return this.locator(lazyPage, selector, location(), target);
+            },
+            eval: ((...args) => this.viewEval(page, args, bound ? "page.view.eval" : "t.app.view.eval", bound)),
+            screenshot: (options) => {
+                noOptions("view.screenshot", options);
+                return this.act("page.screenshot", bound ? `#${bound}` : "", () => this.readRetrying(() => page().screenshot(bound ? target : undefined)));
+            },
+            scroll: (options) => {
+                if (options && "page" in options) {
+                    throw new TypeError("view.scroll() takes no page option: bind another page with t.app.page({ name }) and use its view");
+                }
+                return input.scroll({ ...options, ...target });
+            },
+        };
     }
     locator(page, selector, location, options) {
-        return new PageLocator(page, (fn) => this.guard(fn), (verb, detail, op) => this.act(verb, detail, op), selector, location, options);
+        this.usedPage = true;
+        return new PageLocator(page, (fn) => this.guard(fn), (verb, detail, op) => this.act(verb, detail, op), selector, location, options, () => this.budgetRoom());
     }
-    locatorMatchers(locator, inverted) {
+    locatorMatchers(locator, inverted, message) {
+        const withMessage = (options) => message === undefined || options?.message !== undefined ? options : { ...options, message };
         const self = {
-            toBeVisible: (options) => this.retryLocator(locator, "toBeVisible", inverted, options, inverted ? "not visible" : "visible"),
-            toBeHidden: (options) => this.retryLocator(locator, "toBeHidden", inverted, options, true),
-            toBeAttached: (options) => this.retryLocator(locator, "toBeAttached", inverted, options, true),
-            toBeEnabled: (options) => this.retryLocator(locator, "toBeEnabled", inverted, options, true),
-            toBeDisabled: (options) => this.retryLocator(locator, "toBeDisabled", inverted, options, true),
-            toBeEditable: (options) => this.retryLocator(locator, "toBeEditable", inverted, options, true),
-            toHaveText: (expected, options) => this.retryLocator(locator, "toHaveText", inverted, options, expected),
-            toHaveCount: (expected, options) => this.retryLocator(locator, "toHaveCount", inverted, options, expected),
-            toHaveValue: (expected, options) => this.retryLocator(locator, "toHaveValue", inverted, options, expected),
+            toBeVisible: (options) => this.retryLocator(locator, "toBeVisible", inverted, withMessage(options), inverted ? "not visible" : "visible"),
+            toBeInViewport: (options) => this.retryLocator(locator, "toBeInViewport", inverted, withMessage(options), inverted ? "not in viewport" : "in viewport"),
+            toBeHidden: (options) => this.retryLocator(locator, "toBeHidden", inverted, withMessage(options), true),
+            toBeAttached: (options) => this.retryLocator(locator, "toBeAttached", inverted, withMessage(options), true),
+            toBeEnabled: (options) => this.retryLocator(locator, "toBeEnabled", inverted, withMessage(options), true),
+            toBeDisabled: (options) => this.retryLocator(locator, "toBeDisabled", inverted, withMessage(options), true),
+            toBeEditable: (options) => this.retryLocator(locator, "toBeEditable", inverted, withMessage(options), true),
+            toHaveText: (expected, options) => this.retryLocator(locator, "toHaveText", inverted, withMessage(options), expected),
+            toContainText: (expected, options) => this.retryLocator(locator, "toContainText", inverted, withMessage(options), expected),
+            toHaveAttribute: (name, value, options) => {
+                if (typeof name !== "string" || !name)
+                    throw new TypeError("toHaveAttribute needs an attribute name");
+                return this.retryLocator(locator, "toHaveAttribute", inverted, withMessage(options), new AttributeExpectation(name, value));
+            },
+            toHaveCount: (expected, options) => this.retryLocator(locator, "toHaveCount", inverted, withMessage(options), expected),
+            toHaveValue: (expected, options) => this.retryLocator(locator, "toHaveValue", inverted, withMessage(options), expected),
         };
         Object.defineProperty(self, "not", {
-            get: () => this.locatorMatchers(locator, !inverted),
+            get: () => this.locatorMatchers(locator, !inverted, message),
+            configurable: true,
         });
         return self;
     }
-    pollMatchers(read, options, inverted) {
-        const run = (matcher, expected) => this.retryPoll(read, matcher, inverted, options, expected);
+    pollMatchers(read, options, inverted, api) {
+        const run = (matcher, expected) => this.retryPoll(read, matcher, inverted, options, expected, api);
         const fixture = this;
         const self = {
             toBe: (expected) => run("toBe", expected),
             toEqual: (expected) => run("toEqual", expected),
             toContain: (expected) => run("toContain", expected),
+            toContainEqual: (expected) => run("toContainEqual", expected),
             toMatch: (expected) => run("toMatch", expected),
             toBeTruthy: () => run("toBeTruthy"),
             toBeFalsy: () => run("toBeFalsy"),
             toBeDefined: () => run("toBeDefined"),
             toBeUndefined: () => run("toBeUndefined"),
             toBeInstanceOf: (expected) => run("toBeInstanceOf", expected),
+            toHaveLength: (expected) => run("toHaveLength", expected),
             toBeGreaterThan: (expected) => run("toBeGreaterThan", expected),
             toBeGreaterThanOrEqual: (expected) => run("toBeGreaterThanOrEqual", expected),
             toBeLessThan: (expected) => run("toBeLessThan", expected),
             toBeLessThanOrEqual: (expected) => run("toBeLessThanOrEqual", expected),
         };
         Object.defineProperty(self, "not", {
-            get: () => fixture.pollMatchers(read, options, !inverted),
+            get: () => fixture.pollMatchers(read, options, !inverted, api),
+            configurable: true,
         });
         return self;
     }
-    async retryLocator(locator, matcher, inverted, options, expected) {
-        await this.guard(async () => {
+    retryLocator(locator, matcher, inverted, options, expected) {
+        const target = locator instanceof PageLocator ? locator.describe() : locator.selector;
+        const assertion = `${inverted ? "not." : ""}${matcher}`;
+        return this.track("expect", `${target} ${assertion}`, () => this.guard(async () => {
             const frame = callerLocation();
             const location = { source: frame.file, line: frame.line, column: frame.column };
-            const timeout = options?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+            const deadline = new ActionDeadline(options?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS, this.budgetRoom());
             const interval = options?.interval ?? DEFAULT_POLL_INTERVAL_MS;
-            const started = Date.now();
+            const context = () => this.deadlineContext(inverted ? `not.${matcher}` : matcher, location);
             let lastResolved;
             let lastError;
             pushAssertionSilence();
             this.silenceActions();
             try {
-                while (Date.now() - started < timeout) {
+                while (!deadline.expired()) {
                     try {
-                        lastResolved = await resolveLocator(locator);
+                        lastResolved = await resolveLocator(locator, deadline, context, expected instanceof AttributeExpectation ? [expected.name] : []);
                         matchLocator(locator, lastResolved, matcher, expected, inverted);
                         this.noteAssertion({
                             matcher: inverted ? `not.${matcher}` : matcher,
                             expected: formatValue(expected),
-                            actual: formatValue(locatorActual(matcher, lastResolved)),
+                            actual: formatValue(locatorActual(matcher, lastResolved, expected)),
                             passed: true,
+                            target,
+                            message: options?.message,
+                            location: displayLocation(location.source, location.line, location.column),
+                            duration_ms: deadline.elapsed(),
                         });
                         return;
                     }
                     catch (error) {
-                        if (error instanceof TimeoutError || this.aborted)
+                        if (error instanceof TimeoutError || this.aborted || !isRetryableReadError(error))
                             throw error;
                         lastError = error;
                     }
-                    if (Date.now() - started >= timeout)
+                    if (deadline.expired())
                         break;
-                    await sleep(interval);
+                    await sleep(Math.min(interval, Math.max(1, deadline.remaining())));
                     if (this.aborted && this.abortError)
                         throw this.abortError;
                 }
@@ -519,50 +1281,61 @@ export class LiveFixture {
                 popAssertionSilence();
                 this.resumeActions();
             }
-            const duration = Date.now() - started;
+            const duration = deadline.elapsed();
+            const miss = lastResolved && locator instanceof PageLocator ? locator.missText(lastResolved) : undefined;
             throw this.retryFailure({
+                clampNote: deadline.clampNote(),
                 matcher: inverted ? `not.${matcher}` : matcher,
                 expected,
-                actual: locatorActual(matcher, lastResolved),
+                actual: locatorActual(matcher, lastResolved, expected),
                 duration,
                 location,
                 lastError,
-                extra: lastResolved && locator instanceof PageLocator ? locator.missText(lastResolved) : undefined,
+                extra: miss,
+                locator: locator instanceof PageLocator ? locator.boundPage : null,
+                target,
+                message: options?.message,
             });
-        });
+        }), `expect(${target}).${assertion}`);
     }
-    async retryPoll(read, matcher, inverted, options, expected) {
-        await this.guard(async () => {
+    retryPoll(read, matcher, inverted, options, expected, api) {
+        const source = truncate(read.name || functionDetail(read), 60);
+        const assertion = `${inverted ? "not." : ""}${matcher}`;
+        return this.track(api, `${source} ${assertion}`, () => this.guard(async () => {
             const frame = callerLocation();
             const location = { source: frame.file, line: frame.line, column: frame.column };
-            const timeout = options?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+            const deadline = new ActionDeadline(options?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS, this.budgetRoom());
             const interval = options?.interval ?? DEFAULT_POLL_INTERVAL_MS;
-            const started = Date.now();
+            const context = () => this.deadlineContext(`${api} ${inverted ? "not." : ""}${matcher}`, location);
             let lastActual;
             let lastError;
             pushAssertionSilence();
             this.silenceActions();
             try {
-                while (Date.now() - started < timeout) {
+                while (!deadline.expired()) {
                     try {
-                        lastActual = await read();
+                        lastActual = await deadline.call(`${api} read`, read, context);
                         applyMatcher(matcher, lastActual, expected, inverted);
                         this.noteAssertion({
                             matcher: inverted ? `not.${matcher}` : matcher,
                             expected: formatValue(expected),
                             actual: formatValue(lastActual),
                             passed: true,
+                            target: source,
+                            message: options?.message,
+                            location: displayLocation(location.source, location.line, location.column),
+                            duration_ms: deadline.elapsed(),
                         });
                         return;
                     }
                     catch (error) {
-                        if (error instanceof TimeoutError || this.aborted)
+                        if (error instanceof TimeoutError || this.aborted || !isRetryableReadError(error))
                             throw error;
                         lastError = error;
                     }
-                    if (Date.now() - started >= timeout)
+                    if (deadline.expired())
                         break;
-                    await sleep(interval);
+                    await sleep(Math.min(interval, Math.max(1, deadline.remaining())));
                     if (this.aborted && this.abortError)
                         throw this.abortError;
                 }
@@ -572,14 +1345,24 @@ export class LiveFixture {
                 this.resumeActions();
             }
             throw this.retryFailure({
+                clampNote: deadline.clampNote(),
                 matcher: inverted ? `not.${matcher}` : matcher,
                 expected,
                 actual: lastActual,
-                duration: Date.now() - started,
+                duration: deadline.elapsed(),
                 location,
                 lastError,
+                target: source,
+                message: options?.message,
             });
-        });
+        }), `${api}(${source}).${assertion}`);
+    }
+    deadlineContext(matcher, location) {
+        return [
+            `while retrying ${matcher}`,
+            `at ${displayLocation(location.source, location.line, location.column)}`,
+            this.stepPathLine(),
+        ].filter(Boolean).join("\n");
     }
     retryFailure(input) {
         const where = displayLocation(input.location.source, input.location.line, input.location.column);
@@ -589,11 +1372,13 @@ export class LiveFixture {
                 ? input.lastError.message
                 : undefined;
         const lines = [
+            input.message,
             `Timed out after ${input.duration}ms retrying ${input.matcher}.`,
             input.extra,
             `Expected: ${formatValue(input.expected)}`,
             `Received: ${formatValue(input.actual)}`,
             `Retried for ${input.duration}ms`,
+            input.clampNote,
             `at ${where}`,
             this.stepPathLine(),
             last && last !== `Expected: ${formatValue(input.expected)}` ? last : undefined,
@@ -603,18 +1388,119 @@ export class LiveFixture {
             expected: formatValue(input.expected),
             actual: formatValue(input.actual),
             passed: false,
+            difference: ["toBe", "toEqual"].includes(input.matcher)
+                ? firstDifference(input.expected, input.actual) : undefined,
+            target: input.target,
+            message: input.message,
+            location: where,
+            duration_ms: input.duration,
         });
-        return new AssertionError(input.matcher, input.actual, input.expected, lines.join("\n"));
+        const error = new AssertionError(input.matcher, input.actual, input.expected, lines.join("\n"), "E_TIMEOUT");
+        if (input.locator !== undefined)
+            this.locatorFailures.set(error, input.locator);
+        return error;
+    }
+}
+/** An inline scenario (or its selected variant) with `function` rules. */
+function hasFunctionRules(definition, variant) {
+    if (!definition || typeof definition !== "object")
+        return false;
+    const record = definition;
+    const rules = [
+        ...(Array.isArray(record.rules) ? record.rules : []),
+        ...(variant !== undefined && Array.isArray(record.variants?.[variant]?.rules) ? record.variants[variant].rules : []),
+    ];
+    return rules.some((rule) => !!rule && typeof rule === "object" && "function" in rule);
+}
+/** Extra attempts of an idempotent read the transport dropped, and the backoff step. */
+const TRANSPORT_RETRIES = 2;
+const TRANSPORT_RETRY_DELAY_MS = 100;
+/**
+ * Host tiers a host may lack. The fixture resolves them per call, so reading
+ * `t.automation.desktop` never throws.
+ */
+const HOST_TIERS = ["browser", "desktop", "terminal"];
+/** Driver reads with no side effect, retried when the transport drops them. */
+const IDEMPOTENT_READS = new Set(["nav.current", "nav.info", "nav.stack", "page.query", "page.screenshot", "lxapps.list", "lxapps.current"]);
+function checkpointId(checkpoint, api) {
+    const id = typeof checkpoint === "string" ? checkpoint : checkpoint?.id;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new TypeError(`${api} needs the checkpoint t.app.profile.checkpoint() resolved (or its id)`);
     }
+    return id;
 }
-function resolveLocator(locator) {
-    if (locator instanceof PageLocator)
-        return locator.resolve();
-    throw new Error("t.expect() requires a locator from page.testId() or page.css()");
+/**
+ * `t.waitFor` retries a read that says "not yet" by throwing, but not one
+ * that is invalid locally or violates the eval JSON boundary. Remote DOM
+ * TypeErrors can resolve as rendering catches up.
+ */
+function isRetryableReadError(error) {
+    if (error instanceof AssertionError || isRetryableRemoteError(error))
+        return true;
+    const name = error instanceof Error ? error.name : undefined;
+    return name !== "TypeError" && name !== "ReferenceError" && name !== "SyntaxError";
 }
-function locatorActual(matcher, resolved) {
+function errorLine(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : formatValue(error);
+}
+/**
+ * `eval(fn, ...args)` or `eval(options, fn, ...args)`. An object with a
+ * `script` key is a script string's options, not eval options: it stays the
+ * "function" so the caller refuses it as such.
+ */
+function evalInput(input) {
+    const [first, ...rest] = input;
+    if (first !== null && typeof first === "object" && !("script" in first)) {
+        const [fn, ...args] = rest;
+        return { options: first, fn, args };
+    }
+    return { options: undefined, fn: first, args: rest };
+}
+async function remote(api, target, op) {
+    try {
+        return await op();
+    }
+    catch (error) {
+        throw explainRemoteError(error, api, target);
+    }
+}
+// Sent to app Logic as source text: it must stay self-contained.
+function readPageData(scope, instanceId) {
+    const page = scope.getPage(instanceId);
+    if (!page)
+        throw new Error(`page.data: page instance #${instanceId} is gone`);
+    return page.data;
+}
+function resolveLocator(locator, deadline, context, attributes = []) {
+    if (locator instanceof PageLocator) {
+        return deadline.call("locator read", () => locator.resolve(undefined, "resolve", attributes), context);
+    }
+    throw new Error("expect(locator) takes a locator from view.testId() or view.css()");
+}
+/** `toHaveAttribute`'s expectation; formats as the report shows it. */
+class AttributeExpectation {
+    constructor(name, value) {
+        this.name = name;
+        this.value = value;
+    }
+    toString() {
+        return this.value === undefined ? `attribute ${this.name}` : `${this.name}=${formatValue(this.value)}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+function locatorActual(matcher, resolved, expected) {
     if (!resolved)
         return undefined;
+    if (matcher === "toBeInViewport") {
+        return resolved.kind === "unique" ? (resolved.inViewport ? "in viewport" : "outside viewport") : resolved.kind;
+    }
+    if (matcher === "toContainText")
+        return resolved.text;
+    if (matcher === "toHaveAttribute") {
+        return expected instanceof AttributeExpectation ? resolved.attributes?.[expected.name] ?? null : undefined;
+    }
     if (matcher === "toBeHidden")
         return !resolved.visible;
     if (matcher === "toBeAttached")
@@ -651,6 +1537,35 @@ function matchLocator(locator, resolved, matcher, expected, inverted) {
         }
         return;
     }
+    if (matcher === "toBeInViewport") {
+        const pass = resolved.kind === "unique" && resolved.inViewport;
+        if (pass === inverted) {
+            const detail = locator instanceof PageLocator ? locator.missText(resolved) : `resolved to ${resolved.kind}`;
+            const actual = String(locatorActual(matcher, resolved));
+            throw new AssertionError(inverted ? "not.toBeInViewport" : "toBeInViewport", actual, inverted ? "not in viewport" : "in viewport", `${detail}\nExpected: ${inverted ? "not " : ""}in viewport\nReceived: ${formatValue(actual)}`);
+        }
+        return;
+    }
+    if (matcher === "toContainText") {
+        if (expected instanceof RegExp)
+            applyMatcher("toMatch", resolved.text, expected, inverted);
+        else
+            applyMatcher("toContain", resolved.text, typeof expected === "string" ? normalizeText(expected) : expected, inverted);
+        return;
+    }
+    if (matcher === "toHaveAttribute" && expected instanceof AttributeExpectation) {
+        if (resolved.count !== 1)
+            throw new Error(`Expected one attached element, received ${resolved.count}`);
+        const actual = resolved.attributes?.[expected.name] ?? null;
+        const pass = actual !== null && (expected.value === undefined ? true
+            : expected.value instanceof RegExp ? (expected.value.lastIndex = 0, expected.value.test(actual))
+                : actual === expected.value);
+        if (pass === inverted) {
+            const name = inverted ? "not.toHaveAttribute" : "toHaveAttribute";
+            throw new AssertionError(name, formatValue(actual), `${inverted ? "not " : ""}${expected}`, `Expected: ${inverted ? "not " : ""}${expected}\nReceived: ${actual === null ? `no ${expected.name} attribute` : `${expected.name}=${formatValue(actual)}`}`);
+        }
+        return;
+    }
     if (matcher === "toHaveCount") {
         applyMatcher("toBe", resolved.count, expected, inverted);
         return;
@@ -659,7 +1574,7 @@ function matchLocator(locator, resolved, matcher, expected, inverted) {
         if (expected instanceof RegExp)
             applyMatcher("toMatch", resolved.text, expected, inverted);
         else
-            applyMatcher("toBe", resolved.text, expected, inverted);
+            applyMatcher("toBe", resolved.text, typeof expected === "string" ? normalizeText(expected) : expected, inverted);
         return;
     }
     if (matcher === "toHaveValue") {
@@ -669,6 +1584,10 @@ function matchLocator(locator, resolved, matcher, expected, inverted) {
             applyMatcher("toBe", resolved.value, expected, inverted);
     }
 }
+/** The driver's own bound for `waitUntil: 'ready'`, the fixture's default too. */
+const NAV_READY_TIMEOUT_MS = 15000;
+/** Actions that reach a page of the app. */
+const PAGE_ACTION = /^(?:page|view|nav)\./;
 function guardObject(target, fixture, path, skip = []) {
     const cache = new Map();
     return new Proxy(target, {
@@ -692,7 +1611,9 @@ function guardObject(target, fixture, path, skip = []) {
             }
             if (typeof value === "function" && !accessor) {
                 const name = `${path}${String(prop)}`;
-                const bound = (...args) => fixture.act(name, summarise(args[0]), () => value.apply(obj, args));
+                const bound = IDEMPOTENT_READS.has(name)
+                    ? (...args) => fixture.act(name, summarise(args[0]), () => fixture.readRetrying(() => value.apply(obj, args)))
+                    : (...args) => fixture.act(name, summarise(args[0]), () => value.apply(obj, args));
                 cache.set(prop, bound);
                 return bound;
             }
@@ -705,6 +1626,43 @@ function guardObject(target, fixture, path, skip = []) {
         },
     });
 }
+/**
+ * A driver namespace resolved on each call instead of on read. `resolve`
+ * yields the namespace's owner and value; a member read returns another lazy
+ * namespace, and a call resolves the chain, then records the call as an
+ * action. A host that lacks the tier rejects the call, never the read.
+ */
+function lazyDriver(resolve, fixture, path) {
+    const cache = new Map();
+    const target = function lazy() { };
+    return new Proxy(target, {
+        get(_, prop) {
+            // Not a thenable: `await t.automation.desktop` must not call `then`.
+            if (prop === "then" || typeof prop === "symbol")
+                return undefined;
+            if (cache.has(prop))
+                return cache.get(prop);
+            const member = lazyDriver(() => {
+                const { value } = resolve();
+                if (!value || (typeof value !== "object" && typeof value !== "function")) {
+                    throw new Error(`${path.slice(0, -1)} is not available on this host`);
+                }
+                return { owner: value, value: Reflect.get(value, prop, value) };
+            }, fixture, `${path}${String(prop)}.`);
+            cache.set(prop, member);
+            return member;
+        },
+        apply(_, __, args) {
+            const name = path.slice(0, -1);
+            return fixture.act(name, summarise(args[0]), () => {
+                const { owner, value } = resolve();
+                if (typeof value !== "function")
+                    throw new TypeError(`${name} is not a function on this host`);
+                return value.apply(owner, args);
+            });
+        },
+    });
+}
 /** The one detail worth showing beside an action: what it acted on. */
 function summarise(input) {
     if (input === undefined || input === null)
@@ -748,40 +1706,52 @@ function safeJson(data) {
 export function toReportError(error, step) {
     if (error instanceof AssertionError) {
         const stack = remapStack(error.stack);
+        const cause = error;
         return {
+            code: typeof cause.code === "string" ? cause.code : undefined,
+            data: jsonData(cause.data),
             name: error.name,
             message: error.message,
             stack,
             matcher: error.matcher,
             expected: formatValue(error.expected),
             actual: formatValue(error.actual),
-            location: firstLocation(stack),
+            difference: ["toBe", "toEqual"].includes(error.matcher)
+                ? firstDifference(error.expected, error.actual) : undefined,
+            location: firstLocation(stack, error),
             step,
         };
     }
     if (error instanceof Error) {
         const stack = remapStack(error.stack);
         const details = error;
-        let data;
-        try {
-            if (details.data !== undefined)
-                data = JSON.parse(JSON.stringify(details.data));
-        }
-        catch { /* Non-JSON diagnostic data must not break reporting. */ }
         return {
             code: typeof details.code === "string" ? details.code : undefined,
-            data,
+            data: jsonData(details.data),
             name: error.name,
             message: error.message,
             stack,
-            location: firstLocation(stack),
+            location: firstLocation(stack, error),
             step,
         };
     }
     return { name: "Error", message: String(error), step };
 }
-function firstLocation(stack) {
-    const frames = parseFrames(stack);
+function jsonData(data) {
+    try {
+        return data === undefined ? undefined : JSON.parse(JSON.stringify(data));
+    }
+    catch {
+        // Non-JSON diagnostic data must not break reporting.
+        return undefined;
+    }
+}
+function firstLocation(stack, error) {
+    // V8 starts the stack with the message; a message line (a schema issue,
+    // a received value) must not be read as a frame.
+    const header = `${error.name}: ${error.message}`;
+    const frameText = stack?.startsWith(header) ? stack.slice(header.length) : stack;
+    const frames = parseFrames(frameText);
     const frame = frames.length ? resolveOrigin(frames) : undefined;
     return frame && !isFrameworkFrame(frame.file) ? `${frame.file}:${frame.line}:${frame.column}` : undefined;
 }