slopkit 0.3.0 → 0.4.0-rc.0

package/dist/test/page.js

@@ -0,0 +1,763 @@
+/**
+ * An app's real page, headless, for its tests: the app's own page entry (components, runtime, replica) in a DOM shim
+ * (`happy-dom`), over the app's real server running in this process on loopback, signed in through the kit's
+ * approve-all OpenID stand-in. Tests drive it as a person does, by accessible name, and read what it says; every action
+ * ends when the page and the server are quiet, and the view is then checked by the kit's rules (`viewProblems`). No
+ * browser and no real login. For vitest; one page at a time per process.
+ *
+ * - **One clock.** The page and the server see the driver's clock as `Date`, and their `setTimeout`/`setInterval` are
+ *   virtual; Node's own I/O (fetch, sockets, IndexedDB) keeps real time. Only `settle` and `advance` move the clock.
+ * - **Settle is a person who stops and waits:** every pending timeout within `idle` of the clock runs, the clock moving
+ *   to each in turn, intervals crossed on the way running once, the server's due jobs after each move; in-flight fetches
+ *   and socket messages finish. Bounded: past 200 rounds it throws, naming what stayed busy.
+ * - **The page's own commands:** the driver only types, presses and selects in the DOM; what reaches the server is what
+ *   the page sends.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { IDBFactory } from "fake-indexeddb";
+import { Window } from "happy-dom";
+// A fresh module graph for each page load, as a browser gives; this resets modules, it mocks nothing.
+// oxlint-disable-next-line no-restricted-imports
+import { vi } from "vitest";
+import { WebSocket as NodeSocket } from "ws";
+import { parseWebConfig } from "../server/config.js";
+import { Log, scoped } from "../server/log.js";
+import { isLine, MEANINGS } from "../states.js";
+import { identityProvider } from "./oidc.js";
+import { viewProblems } from "./states.js";
+/** Whether code runs for the server or the page: timers and their owner follow async context. */
+const owner = new AsyncLocalStorage();
+/** The longest real time a settle waits for I/O to finish before it says what stayed busy. */
+const QUIET_LIMIT_MS = 10_000;
+/** The most timeouts one move of the clock runs before it says which keeps re-arming. */
+const FIRES = 200;
+const ROUNDS = 200;
+const QUIET_CHECKS = 3;
+const QUIET_MS = 2;
+const realSetTimeout = globalThis.setTimeout;
+const realSetInterval = globalThis.setInterval;
+const realClearTimeout = globalThis.clearTimeout;
+const RealDate = Date;
+const VIRTUAL = Symbol("virtual timer");
+/**
+ * Whether a timer is Node's own (fetch's parser and its tick, from `node:internal`): those keep real time, since they
+ * are the I/O the page waits on, not the page's or the server's time.
+ */
+function internal() {
+    // The frame that called setTimeout: this function, the wrapper, then the caller.
+    const caller = new Error("stack").stack?.split("\n")[3] ?? "";
+    return caller.includes("node:internal") || caller.includes("(node:");
+}
+let open = false;
+function matches(name, value) {
+    return typeof name === "string" ? value === name : name.test(value);
+}
+export async function openPage(options) {
+    if (open) {
+        throw new Error("openPage: another page is open in this process; close it first");
+    }
+    const clock = { now: typeof options.at === "number" ? options.at : RealDate.parse(options.at) };
+    if (!Number.isFinite(clock.now)) {
+        throw new TypeError(`openPage: at ${String(options.at)} isn't an instant`);
+    }
+    open = true;
+    const idle = options.idle ?? 5000;
+    const order = options.order ?? MEANINGS;
+    const timers = new Map();
+    let nextTimer = 0;
+    let activity = 0;
+    let inflight = 0;
+    const errors = [];
+    const restore = [];
+    const set = (key, value) => {
+        const before = Object.getOwnPropertyDescriptor(globalThis, key);
+        Object.defineProperty(globalThis, key, { value, configurable: true, writable: true });
+        restore.push(() => {
+            if (before === undefined) {
+                Reflect.deleteProperty(globalThis, key);
+            }
+            else {
+                Object.defineProperty(globalThis, key, before);
+            }
+        });
+    };
+    // The clock as Date, for page and server alike: `new Date()` and `Date.now()` read it, `Date()` says it, and every
+    // other use is the real Date's, so a Date from structuredClone or IndexedDB is still `instanceof Date`.
+    const Clocked = new Proxy(RealDate, {
+        construct: (target, args, newTarget) => 
+        // oxlint-disable-next-line typescript/no-unsafe-return -- the real Date's own construction, passed through
+        Reflect.construct(target, args.length === 0 ? [clock.now] : args, newTarget),
+        apply: () => new RealDate(clock.now).toString(),
+        get: (target, key, receiver) => 
+        // oxlint-disable-next-line typescript/no-unsafe-return -- the real Date's own members, passed through
+        key === "now" ? () => clock.now : Reflect.get(target, key, receiver),
+    });
+    set("Date", Clocked);
+    const handle = (timer) => ({
+        [VIRTUAL]: true,
+        id: timer.id,
+        ref() {
+            return this;
+        },
+        unref() {
+            return this;
+        },
+        hasRef: () => true,
+        refresh() {
+            timer.at = clock.now + timer.delay;
+            timers.set(timer.id, timer);
+            return this;
+        },
+        [Symbol.toPrimitive]: () => timer.id,
+    });
+    const schedule = (run, ms, every, rest) => {
+        const delay = Math.max(0, Number(ms) || 0);
+        const id = ++nextTimer;
+        const timer = {
+            id,
+            at: clock.now + delay,
+            delay,
+            every: every ? Math.max(1, delay) : 0,
+            owner: owner.getStore() ?? "server",
+            run: () => {
+                owner.run(timer.owner, () => run(...rest));
+            },
+            label: `${every ? "interval" : "timeout"} ${delay} ms${run.name ? ` (${run.name})` : ""}`,
+        };
+        timers.set(id, timer);
+        return handle(timer);
+    };
+    const clear = (value) => {
+        if (typeof value === "object" && value !== null && !(VIRTUAL in value)) {
+            // A real timer of Node's own.
+            // SAFETY: only Node's real timers are objects without the virtual mark.
+            // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion
+            realClearTimeout(value);
+            return;
+        }
+        const id = typeof value === "object" && value !== null && "id" in value
+            ? Number(value.id)
+            : Number(value);
+        timers.delete(id);
+    };
+    set("setTimeout", (run, ms, ...rest) => internal() ? realSetTimeout(run, ms, ...rest) : schedule(run, ms, false, rest));
+    set("setInterval", (run, ms, ...rest) => internal() ? realSetInterval(run, ms, ...rest) : schedule(run, ms, true, rest));
+    set("clearTimeout", clear);
+    set("clearInterval", clear);
+    const fire = (timer) => {
+        if (timer.every > 0) {
+            timer.at = Math.max(timer.at + timer.every, clock.now + timer.every);
+        }
+        else {
+            timers.delete(timer.id);
+        }
+        activity++;
+        try {
+            timer.run();
+        }
+        catch (error) {
+            errors.push(`${timer.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    /** The pending timeout that comes first, at or before `to`. */
+    const first = (to) => [...timers.values()]
+        .filter((each) => each.every === 0 && each.at <= to)
+        .toSorted((a, b) => a.at - b.at || a.id - b.id)[0];
+    /** Drops the page's timers; the server's go on. */
+    const pages = () => {
+        for (const timer of [...timers.values()].filter((each) => each.owner === "page")) {
+            timers.delete(timer.id);
+        }
+    };
+    /** Runs intervals due by now once each. */
+    const intervals = () => {
+        for (const each of [...timers.values()].filter((timer) => timer.every > 0 && timer.at <= clock.now)) {
+            fire(each);
+        }
+    };
+    const onRejection = (reason) => {
+        errors.push(`unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
+    };
+    process.on("unhandledRejection", onRejection);
+    restore.push(() => {
+        process.off("unhandledRejection", onRejection);
+    });
+    set("reportError", (error) => {
+        errors.push(`reported: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const quiet = async () => {
+        let still = 0;
+        let seen = activity;
+        const until = RealDate.now() + QUIET_LIMIT_MS;
+        while (still < QUIET_CHECKS) {
+            if (RealDate.now() > until) {
+                throw new Error(`the page never settles: ${inflight} requests or sockets still in flight after ${QUIET_LIMIT_MS} ms`);
+            }
+            // oxlint-disable-next-line no-await-in-loop -- each check waits out real I/O before the next
+            await new Promise((resolve) => {
+                realSetTimeout(resolve, QUIET_MS);
+            });
+            if (inflight === 0 && activity === seen) {
+                still++;
+            }
+            else {
+                still = 0;
+                seen = activity;
+            }
+        }
+    };
+    // What to undo on close, or when opening fails part way: newest first.
+    const undo = [
+        () => {
+            for (const each of restore.toReversed()) {
+                each();
+            }
+            open = false;
+        },
+    ];
+    // Every step runs even when one fails, so a failed close never leaves the clock, the timers or the slot behind.
+    const teardown = async () => {
+        const failed = [];
+        for (const each of undo.splice(0).toReversed()) {
+            try {
+                // oxlint-disable-next-line no-await-in-loop -- in order, newest first
+                await each();
+            }
+            catch (error) {
+                failed.push(error);
+            }
+        }
+        if (failed.length > 0) {
+            throw new AggregateError(failed, "openPage: closing failed");
+        }
+    };
+    const opened = async () => {
+        const home = await mkdtemp(join(tmpdir(), "slopkit-page-"));
+        undo.push(() => rm(home, { recursive: true, force: true }));
+        const provider = await identityProvider();
+        undo.push(() => provider.close());
+        const web = parseWebConfig({
+            port: 0,
+            bind: "127.0.0.1",
+            oidc: { issuer: provider.issuer, clientId: "page" },
+            allow: ["sub:owner"],
+        }, []);
+        const log = new Log(home, "page", { echo: false });
+        undo.push(() => log.flushed());
+        // The server runs in its own async context: its timers outlive a page load.
+        const server = await owner.run("server", () => options.server({ home, web, now: () => clock.now, log: scoped(log, "server") }));
+        undo.push(() => owner.run("server", () => server.close()));
+        /** Real I/O, the server's jobs due by now, then their I/O. */
+        const step = async () => {
+            await quiet();
+            await owner.run("server", () => server.due?.());
+            await quiet();
+        };
+        /** Moves the clock to `to`: each timeout due by then at its own instant, with I/O and due jobs after each, then
+         * the intervals crossed, once each. */
+        const move = async (to) => {
+            for (let fired = 0;; fired++) {
+                const next = first(to);
+                if (next === undefined) {
+                    break;
+                }
+                if (fired > FIRES) {
+                    throw new Error(`the page never settles: ${next.label} keeps re-arming`);
+                }
+                clock.now = Math.max(clock.now, next.at);
+                fire(next);
+                // oxlint-disable-next-line no-await-in-loop -- each timeout's effects land before the next runs
+                await step();
+            }
+            clock.now = Math.max(clock.now, to);
+            intervals();
+            await step();
+        };
+        const base = new URL(server.url);
+        const origin = base.origin;
+        let cookie = "";
+        // The server's own login, through the stand-in: its redirects followed by hand, the last session cookie kept.
+        const signIn = async () => {
+            let at = new URL("/auth/login", base);
+            let found = "";
+            for (let hop = 0; hop < 5; hop++) {
+                // oxlint-disable-next-line no-await-in-loop -- each redirect follows the one before
+                const response = await fetch(at, {
+                    redirect: "manual",
+                    headers: found === "" ? {} : { cookie: found },
+                });
+                const pair = (response.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
+                if (/^[^=]+=[^=]/.test(pair)) {
+                    found = pair;
+                }
+                const location = response.headers.get("location");
+                if (location === null) {
+                    break;
+                }
+                at = new URL(location, at);
+            }
+            if (found === "") {
+                throw new Error("openPage: the stand-in sign-in gave no session");
+            }
+            cookie = found;
+        };
+        await signIn();
+        const nodeFetch = globalThis.fetch.bind(globalThis);
+        let device = new IDBFactory();
+        /** The device's Web Storage, kept across page loads as a browser keeps it. */
+        let stored = { local: new Map(), session: new Map() };
+        let address = new URL(options.path ?? "/", base).href;
+        /**
+         * The tab's history, as a browser keeps it across a reload: each entry's address and state, and where the tab is.
+         * Recorded, never driven: the page's own history (happy-dom's) moves; a reload restores the entries up to here.
+         */
+        let trail = [];
+        let at = 0;
+        let window;
+        let entry;
+        let pageGlobals = [];
+        const pageFetch = async (input, init = {}) => {
+            const url = new URL(input instanceof Request ? input.url : String(input), base);
+            const headers = new Headers(input instanceof Request ? input.headers : undefined);
+            for (const [key, value] of new Headers(init.headers)) {
+                headers.set(key, value);
+            }
+            if (url.origin === origin) {
+                if (cookie !== "") {
+                    headers.set("cookie", cookie);
+                }
+                headers.set("origin", origin);
+            }
+            inflight++;
+            activity++;
+            try {
+                const method = init.method ?? (input instanceof Request ? input.method : "GET");
+                const response = await nodeFetch(url, { ...init, method, headers });
+                // The body is read here, so the request counts as in flight until it has all arrived.
+                const body = response.status === 204 || response.status === 304 ? null : await response.arrayBuffer();
+                const copy = new Response(body, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                });
+                Object.defineProperty(copy, "url", { value: response.url });
+                return copy;
+            }
+            finally {
+                inflight--;
+                activity++;
+            }
+        };
+        const sockets = new Set();
+        class PageSocket extends NodeSocket {
+            constructor(url) {
+                super(String(url), { headers: cookie === "" ? { origin } : { cookie, origin } });
+                sockets.add(this);
+                this.once("close", () => {
+                    sockets.delete(this);
+                });
+                inflight++;
+                // The handshake is in flight until it opens, fails or closes, whichever comes first; a refused upgrade fails
+                // and closes, as in a browser, so the page's retry runs.
+                let pending = true;
+                const done = () => {
+                    if (pending) {
+                        pending = false;
+                        inflight--;
+                    }
+                    activity++;
+                };
+                this.once("open", done);
+                this.once("error", done);
+                this.once("close", done);
+                this.on("message", () => {
+                    activity++;
+                });
+            }
+        }
+        const unload = async () => {
+            // The page goes as a closed tab does: it hears it is hidden and going (visibilitychange, pagehide) and may save,
+            // then its timers stop, its sockets close, and what it had in flight lands before its globals go, so nothing of
+            // it runs afterwards. The server's timers go on.
+            const going = window;
+            if (going !== undefined) {
+                Object.defineProperty(going.document, "visibilityState", {
+                    value: "hidden",
+                    configurable: true,
+                });
+                Object.defineProperty(going.document, "hidden", { value: true, configurable: true });
+                owner.run("page", () => {
+                    going.document.dispatchEvent(new going.Event("visibilitychange"));
+                    going.dispatchEvent(new going.PageTransitionEvent("pagehide"));
+                });
+                await quiet();
+            }
+            pages();
+            for (const socket of sockets) {
+                socket.close();
+            }
+            await quiet();
+            for (const each of pageGlobals.toReversed()) {
+                each();
+            }
+            pageGlobals = [];
+            if (window !== undefined) {
+                address = window.location.href;
+                trail = trail.slice(0, at + 1);
+                for (const [into, from] of [
+                    [stored.local, window.localStorage],
+                    [stored.session, window.sessionStorage],
+                ]) {
+                    into.clear();
+                    for (let index = 0; index < from.length; index++) {
+                        const key = from.key(index);
+                        if (key !== null) {
+                            into.set(key, from.getItem(key) ?? "");
+                        }
+                    }
+                }
+                await window.happyDOM.abort();
+                await window.happyDOM.close();
+                window = undefined;
+            }
+            pages();
+        };
+        const load = async () => {
+            window = new Window({
+                url: trail[0]?.url ?? address,
+                width: options.viewport?.width ?? 412,
+                height: options.viewport?.height ?? 915,
+            });
+            // The entries a reload keeps, back to the one the tab is on: same document, so going back fires popstate.
+            const history = window.history;
+            const push = history.pushState.bind(history);
+            const replace = history.replaceState.bind(history);
+            for (const kept of trail.slice(1)) {
+                push(kept.state, "", kept.url);
+            }
+            if (trail.length === 0) {
+                trail = [{ url: address, state: null }];
+            }
+            at = trail.length - 1;
+            history.pushState = (state, unused, url) => {
+                push(state, unused, url);
+                trail = [...trail.slice(0, at + 1), { url: window?.location.href ?? address, state }];
+                at = trail.length - 1;
+            };
+            history.replaceState = (state, unused, url) => {
+                replace(state, unused, url);
+                trail[at] = { url: window?.location.href ?? address, state };
+            };
+            window.addEventListener("popstate", () => {
+                const href = window?.location.href;
+                const near = [at - 1, at + 1].find((index) => trail[index]?.url === href);
+                at =
+                    near ??
+                        Math.max(0, trail.findIndex((each) => each.url === href));
+            });
+            // A hash the page set is a new entry; one that back or forward reached is already where popstate put the tab.
+            window.addEventListener("hashchange", () => {
+                if (trail[at]?.url === window?.location.href) {
+                    return;
+                }
+                trail = [...trail.slice(0, at + 1), { url: window?.location.href ?? address, state: null }];
+                at = trail.length - 1;
+            });
+            for (const [from, into] of [
+                [stored.local, window.localStorage],
+                [stored.session, window.sessionStorage],
+            ]) {
+                for (const [key, value] of from) {
+                    into.setItem(key, value);
+                }
+            }
+            // The window's own timers and Date are the driver's, as the bare globals are.
+            for (const key of ["setTimeout", "setInterval", "clearTimeout", "clearInterval", "Date"]) {
+                Object.defineProperty(window, key, {
+                    value: Reflect.get(globalThis, key),
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            // An error a listener throws: the DOM reports it on the window rather than to the caller.
+            window.addEventListener("error", (event) => {
+                const error = "error" in event ? event.error : undefined;
+                errors.push(`page error: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            const own = [];
+            const put = (key, value) => {
+                const before = Object.getOwnPropertyDescriptor(globalThis, key);
+                Object.defineProperty(globalThis, key, { value, configurable: true, writable: true });
+                own.push(() => {
+                    if (before === undefined) {
+                        Reflect.deleteProperty(globalThis, key);
+                    }
+                    else {
+                        Object.defineProperty(globalThis, key, before);
+                    }
+                });
+            };
+            const shim = Object.fromEntries(Object.getOwnPropertyNames(window).flatMap((key) => {
+                try {
+                    return [[key, Reflect.get(window ?? {}, key)]];
+                }
+                catch {
+                    return [];
+                }
+            }));
+            for (const [key, value] of Object.entries(shim)) {
+                // The DOM's classes and objects, where Node has none of its own; Node keeps its timers, fetch and streams.
+                if (!(key in globalThis) || ["Event", "CustomEvent"].includes(key)) {
+                    put(key, value);
+                }
+            }
+            for (const [key, value] of Object.entries({
+                window,
+                self: window,
+                document: window.document,
+                location: window.location,
+                navigator: window.navigator,
+                localStorage: window.localStorage,
+                sessionStorage: window.sessionStorage,
+                indexedDB: device,
+                fetch: pageFetch,
+                WebSocket: PageSocket,
+            })) {
+                put(key, value);
+            }
+            pageGlobals = own;
+            window.document.body.innerHTML = '<div id="app"></div>';
+            vi.resetModules();
+            entry = await owner.run("page", () => options.page());
+        };
+        const doc = () => {
+            if (window === undefined) {
+                throw new Error("the page isn't loaded");
+            }
+            return window.document;
+        };
+        /** An element's accessible name: aria-label, aria-labelledby, its <label>, or its text. */
+        const nameOf = (element) => {
+            const label = element.getAttribute("aria-label");
+            if (label !== null) {
+                return label.trim();
+            }
+            const by = element.getAttribute("aria-labelledby");
+            if (by !== null) {
+                return by
+                    .split(/\s+/)
+                    .map((id) => doc().querySelector(`#${CSS.escape(id)}`)?.textContent ?? "")
+                    .join(" ")
+                    .trim();
+            }
+            const id = element.getAttribute("id");
+            const labelled = id === null ? null : doc().querySelector(`label[for="${id}"]`);
+            const wrapping = element.closest("label");
+            const from = labelled ?? (wrapping === element ? null : wrapping);
+            if (from !== null && element.tagName !== "BUTTON") {
+                const copy = from.cloneNode(true);
+                for (const control of copy.querySelectorAll("input, select, textarea, button")) {
+                    control.remove();
+                }
+                return (copy.textContent ?? "").replaceAll(/\s+/g, " ").trim();
+            }
+            if (element.tagName === "INPUT" &&
+                /^(submit|button|reset)$/i.test(element.getAttribute("type") ?? "")) {
+                return (element.getAttribute("value") ?? "").trim();
+            }
+            return (element.textContent ?? "").replaceAll(/\s+/g, " ").trim();
+        };
+        const find = (selector, name, what) => {
+            const found = [...doc().querySelectorAll(selector)].filter((each) => matches(name, nameOf(each)));
+            if (found.length !== 1) {
+                const names = [...doc().querySelectorAll(selector)].map((each) => `"${nameOf(each)}"`);
+                throw new Error(`${found.length === 0 ? "no" : `${found.length}`} ${what} named ${String(name)}; there are: ${names.join(", ") || "none"}`);
+            }
+            // SAFETY: happy-dom's HTML elements are the DOM's, under its own type names.
+            // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion, anti-slop/no-chained-type-assertions
+            return found[0];
+        };
+        const event = (target, type) => {
+            if (window === undefined) {
+                return;
+            }
+            // SAFETY: happy-dom's Event is the DOM's Event, under its own type name.
+            // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion, anti-slop/no-chained-type-assertions
+            const made = new window.Event(type, { bubbles: true });
+            // The page's handlers run as the page: what they start is the page's, and dies with a reload.
+            owner.run("page", () => target.dispatchEvent(made));
+        };
+        const read = () => entry === undefined || options.read === undefined
+            ? { shown: undefined }
+            : options.read(entry);
+        const lines = () => {
+            const found = [];
+            const seen = new Set();
+            const visit = (value) => {
+                if (typeof value !== "object" || value === null || seen.has(value)) {
+                    return;
+                }
+                seen.add(value);
+                if (isLine(value)) {
+                    found.push({
+                        subject: value.subject,
+                        kind: value.kind,
+                        meaning: value.meaning,
+                        text: value.text,
+                        owed: value.owed,
+                    });
+                    return;
+                }
+                for (const each of value instanceof Map
+                    ? [...value.keys(), ...value.values()]
+                    : value instanceof Set || Array.isArray(value)
+                        ? value
+                        : Object.values(value)) {
+                    visit(each);
+                }
+            };
+            visit(read().shown);
+            return found;
+        };
+        const settleWithin = async (within, settling = {}) => {
+            const horizon = clock.now + within;
+            let rounds = 0;
+            for (;;) {
+                if (++rounds > ROUNDS) {
+                    const busy = [...timers.values()].filter((each) => each.every === 0 && each.at <= horizon);
+                    throw new Error(`the page never settles: after ${ROUNDS} rounds still ${[
+                        ...busy.map((each) => each.label),
+                        ...(inflight > 0 ? [`${inflight} requests in flight`] : []),
+                    ].join(", ")}`);
+                }
+                // Each round waits for the last one's work: real I/O, then the jobs it made due, then their I/O.
+                // oxlint-disable-next-line no-await-in-loop -- in order, by design
+                await step();
+                const next = first(horizon);
+                if (next === undefined) {
+                    break;
+                }
+                // oxlint-disable-next-line no-await-in-loop -- in order, by design
+                await move(next.at);
+            }
+            const problems = errors.splice(0);
+            const now = read();
+            problems.push(...viewProblems(now.shown, {
+                order,
+                world: {
+                    now: clock.now,
+                    ...(server.jobs === undefined ? {} : { jobs: server.jobs() ?? [] }),
+                    ...(now.model === undefined ? {} : { model: now.model }),
+                },
+            }));
+            if (problems.length > 0 && settling.lenient !== true) {
+                throw new Error(`the page settled with problems:\n- ${problems.join("\n- ")}`);
+            }
+            return { lines: lines(), problems };
+        };
+        const settle = (settling) => settleWithin(idle, settling);
+        undo.push(unload);
+        await load();
+        // The first screen is the one at `at`: what loads and syncs now, with no time passing.
+        await settleWithin(0);
+        return {
+            async type(name, text) {
+                const field = find("input, textarea, [contenteditable], [role=textbox], [role=searchbox]", name, "text field");
+                if ("value" in field) {
+                    // SAFETY: an input or textarea takes a value.
+                    // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion
+                    field.value = text;
+                }
+                else {
+                    field.textContent = text;
+                }
+                event(field, "input");
+                event(field, "change");
+                await settle();
+            },
+            async press(name) {
+                const button = find("button, input[type=submit], input[type=button], input[type=reset], a[href], [role=button], [role=link], [role=tab], [role=menuitem]", name, "button");
+                owner.run("page", () => {
+                    button.click();
+                });
+                await settle();
+            },
+            async select(name, option) {
+                // SAFETY: matched by the select selector, so a select element.
+                // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion, anti-slop/no-chained-type-assertions
+                const field = find("select", name, "select");
+                const chosen = [...field.options].find((each) => each.value === option || each.text.trim() === option);
+                if (chosen === undefined) {
+                    throw new Error(`select ${String(name)} has no option ${option}`);
+                }
+                field.value = chosen.value;
+                event(field, "input");
+                event(field, "change");
+                await settle();
+            },
+            async advance(ms) {
+                await move(clock.now + Math.max(0, ms));
+                await settle();
+            },
+            settle,
+            text(name) {
+                return (name === undefined
+                    ? (doc().querySelector("#app")?.textContent ?? "")
+                    : (find("[aria-label], [aria-labelledby]", name, "named element").textContent ?? ""))
+                    .replaceAll(/\s+/g, " ")
+                    .trim();
+            },
+            lines,
+            location() {
+                return window?.location.href ?? address;
+            },
+            async back() {
+                const from = window?.location.href;
+                let heard = false;
+                window?.addEventListener("popstate", () => {
+                    heard = true;
+                }, { once: true });
+                owner.run("page", () => doc().defaultView?.history.back());
+                await settle();
+                if (!heard && window?.location.href === from) {
+                    throw new Error("openPage: back() with nowhere to go back to");
+                }
+            },
+            async reload(reloading = {}) {
+                await unload();
+                if (reloading.device === "new") {
+                    device = new IDBFactory();
+                    stored = { local: new Map(), session: new Map() };
+                }
+                await load();
+                await settle();
+            },
+            async signOut() {
+                cookie = "";
+                const { problems } = await settle({ lenient: true });
+                // Page errors in signing out fail the next settle; its view is checked again there.
+                errors.push(...problems.filter((each) => !each.includes(" (working) but owes ")));
+            },
+            async signIn() {
+                await signIn();
+                await settle();
+            },
+            get now() {
+                return clock.now;
+            },
+            async close() {
+                await teardown();
+            },
+        };
+    };
+    try {
+        return await opened();
+    }
+    catch (error) {
+        await teardown().catch(() => undefined);
+        throw error;
+    }
+}