@ultimat3/cli 20.2.1 → 21.0.0

package/src/dev-route-table.ts

@@ -0,0 +1,119 @@
+// The route table `x dev` serves, in mount order: the dashboard, the API, the assets a document
+// names, the island and sync-worker scripts, and the app's pages last. Split from `cmd-dev.ts` at its
+// 500-line ceiling; `serve.ts` composes the production table from the same builders.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import type { Storage } from '@ultimat3/storage';
+import { apiRoutes } from './api-routes';
+import { mountAppMcp } from './app-mcp';
+import { assetRoutes } from './dev-assets';
+import type { DevDashboardInput } from './dev-dashboard';
+import { devDashboardRoutes } from './dev-dashboard';
+import { appRoutes } from './dev-render';
+import { storageRoutes } from './dev-storage';
+import { errorPageStyleSources } from './error-page-csp';
+import type { IslandBundle } from './island-bundle';
+import { islandHarnessRoutes } from './island-harness-route';
+import { islandRoutes } from './island-routes';
+import { loadIslandStates } from './island-states-load';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import type { ThemeBoot } from './theme-boot';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+export interface DevRouteTableInput {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly buildId: string;
+  readonly storage: Storage;
+  readonly dashboard: DevDashboardInput;
+  /** A getter: the watcher tick rebuilds the islands, and a captured bundle would serve the first. */
+  readonly islands: () => IslandBundle;
+}
+
+export interface DevRouteTable {
+  readonly routes: readonly Route[];
+  /** The theme boot, whose `cspSource` the web role admits. */
+  readonly theme: ThemeBoot;
+  /** The app's own error pages' inline styles, admitted the same way. */
+  readonly errorStyles: readonly string[];
+  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  readonly mcpPath: string | null;
+}
+
+export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
+  // Resolved once, before the first route. `undefined` for an app that is not installable: nothing
+  // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
+  const pwa = await loadPwaArtifacts(input.root);
+  const theme = themeBoot(await loadThemeMode(input.root));
+  // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
+  const sync = await pageSync(input.root, input.env, input.buildId);
+  const errorStyles = await errorPageStyleSources(input.root);
+  // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
+  // changes under a page it controls is the update path, and one per keystroke exercises it per save.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId: input.buildId,
+          routes: describeRoutes(),
+          islands: input.islands(),
+          styles: styleBundle(),
+          scripts: sync.scripts,
+        });
+
+  // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
+  // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
+  // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
+  const mcpMount = await mountAppMcp(input.root);
+  const routes: readonly Route[] = [
+    ...devDashboardRoutes(input.dashboard),
+    // The same API table the container serves: a read that answers here and 404s in production
+    // is exactly the drift one composition exists to prevent.
+    ...apiRoutes(),
+    ...mcpMount.routes,
+    // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
+    // variants every `srcset` promises. Mounted before the app's own routes so a page route can
+    // never shadow `/icons` or `/media`.
+    ...assetRoutes({
+      root: input.root,
+      storage: input.storage,
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: input.storage }),
+    // The chunks the documents below name. Mounted before the app's routes for the reason
+    // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
+    ...islandRoutes(() => input.islands()),
+    // And the stylesheet every one of those documents links. Read through the getter for the
+    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
+    // captured at boot would answer 404 for the href the document now carries.
+    ...styleRoutes(() => styleBundle()),
+    // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
+    // lives here rather than in a second server because everything it needs is in THIS process:
+    // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
+    // may have. The states are read per REQUEST — an author editing a state and re-running the
+    // command must not need a restart to see it.
+    ...islandHarnessRoutes({
+      islands: () => input.islands(),
+      states: () => loadIslandStates(input.root),
+    }),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...sync.routes,
+    ...appRoutes({
+      buildId: input.buildId,
+      resolveIsland: (file) => input.islands().resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
+      themeHead: theme.head,
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+    }),
+  ];
+
+  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+}

package/src/dev-services.ts

@@ -40,7 +40,10 @@ const nonEmpty = (value: string | undefined): string | undefined =>
  * is a directory delete rather than a container dance.
  */
 export function resolveServices(root: string, env: Env): DevServices {
-  const stateDir = join(root, '.x');
+  // `ULTIMATE_STATE_DIR` relocates the whole of `.x/` — the embedded database, the local disk and
+  // the dev lock — for one process tree. It is how an e2e run boots the app on a THROWAWAY database
+  // (`e2e-app.ts`) instead of resetting the developer's own, beside a running `x dev`.
+  const stateDir = nonEmpty(env['ULTIMATE_STATE_DIR']) ?? join(root, '.x');
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
   const natsUrl = nonEmpty(env['NATS_URL']);
   const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);

package/src/dev-sync.ts

@@ -131,6 +131,8 @@ export interface RunningSync {
   readonly url: string;
   /** The node's registry, so the boot can hand it a change feed the database cannot produce. */
   readonly registry: LiveQueryRegistry;
+  /** The node's channel hub — fed the same changes, so a declared channel's `records` flow in dev. */
+  readonly hub: ChannelHub;
   stop(): Promise<void>;
 }
 
@@ -212,7 +214,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
     stop: () => node.stop(),
-    listen: async (appUrl) => await listen(options, node, registry, appUrl),
+    listen: async (appUrl) => await listen(options, node, { registry, hub }, appUrl),
   };
 }
 
@@ -241,7 +243,7 @@ function syncPortFrom(requested: number, appUrl: string | null): number {
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
-  registry: LiveQueryRegistry,
+  feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
 ): Promise<RunningSync> {
   const port = syncPortFrom(options.port, appUrl);
@@ -266,7 +268,7 @@ async function listen(
     });
     return {
       url: listener.url,
-      registry,
+      ...feeds,
       stop: async () => {
         listener.stop();
         await node.stop();

package/src/e2e-app.ts

@@ -0,0 +1,103 @@
+// The app an e2e suite drives, spawned on a THROWAWAY state directory: its own embedded database,
+// its own disk, its own dev lock, created per call and removed on `stop()`. Never the developer's
+// `.x/pgdata` — resetting that from a test run destroys the data an `x dev` beside it is using.
+// This file is the DATABASE half; spawning, readiness and the restart are `e2e-spawn.ts`'s.
+
+// why: Bun ships no temp-directory primitive or recursive remove; `tmpdir()` is node:os's alone.
+import { mkdtemp, rm } from 'node:fs/promises';
+// why: Bun exposes no tmpdir() — only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path API — the state dir is joined, not concatenated.
+import { join } from 'node:path';
+import { finiteCount } from '@ultimat3/core';
+import type { E2eAppMode } from './e2e-spawn';
+import { inherited, refuse, spawnE2eApp, X_BIN } from './e2e-spawn';
+
+export type { E2eAppMode } from './e2e-spawn';
+
+export interface StartE2eAppOptions {
+  /** The app root — the directory holding `app.config.ts`. */
+  readonly root: string;
+  readonly mode?: E2eAppMode | undefined;
+  /**
+   * The arguments after `x db seed`, or `false` for no seeding. Default `['--tier', 'dev']`: every
+   * dev-tier seed, which is what a developer's own `x dev` starts from.
+   */
+  readonly seed?: readonly string[] | false | undefined;
+  /** Extra environment for every process — the reset, the seed and the app. */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /** How long the app may take to answer `/readyz`. */
+  readonly readyTimeoutMs?: number | undefined;
+}
+
+export interface E2eApp {
+  /** `http://localhost:<port>`, no trailing slash. */
+  readonly base: string;
+  /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
+  readonly stateDir: string;
+  /** Kill the app and delete its state directory. Idempotent. */
+  stop(): Promise<void>;
+  /**
+   * Stop the app and start it again on the SAME port and state directory, with `env` added — a
+   * deploy. `{ BUILD_ID: 'b2' }` is a new build the open tabs have not seen (`deploy.newBuild()`).
+   */
+  restart(env?: Readonly<Record<string, string>>): Promise<void>;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 90_000;
+
+function x(args: readonly string[], root: string, env: Record<string, string>): void {
+  const run = Bun.spawnSync(['bun', X_BIN, ...args], {
+    cwd: root,
+    env: { ...inherited(), ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  if (run.exitCode !== 0) {
+    throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);
+  }
+}
+
+/**
+ * Reset and seed a fresh state directory, then spawn the app on a free port and wait for `/readyz`.
+ * The reset runs against the throwaway directory, so it is a first migration, never a data loss.
+ */
+export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp> {
+  // Screened FIRST, before a directory or a process exists: `waited < NaN` is false, so a NaN budget would never poll and report a dead app.
+  const deadline = finiteCount(
+    'startE2eApp',
+    'readyTimeoutMs',
+    options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+  );
+  const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
+  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
+  const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
+  try {
+    x(['db', 'reset'], options.root, env);
+    const seed = options.seed ?? ['--tier', 'dev'];
+    if (seed !== false) x(['db', 'seed', ...seed], options.root, env);
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+  try {
+    const spawned = await spawnE2eApp({
+      root: options.root,
+      mode: options.mode ?? 'dev',
+      env,
+      readyTimeoutMs: deadline,
+    });
+    return {
+      base: spawned.base,
+      stateDir,
+      restart: (next) => spawned.restart(next),
+      async stop(): Promise<void> {
+        await spawned.stop();
+        await cleanup();
+      },
+    };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}

package/src/e2e-browser-handle.ts

@@ -0,0 +1,55 @@
+// The browser and the app the e2e step opened, reachable from a test file: `e2eBrowser()` and
+// `e2eApp()`. On `globalThis` under one `Symbol.for` key, because the preload and a test may each
+// hold their own copy of this module — the page-client handle's reason, one runtime over.
+
+import type { E2eBrowser } from './cdp-browser';
+import { CdpBrowserMissingError } from './cdp-errors';
+import { CHROME_CANDIDATES } from './cdp-launch';
+import type { E2eApp } from './e2e-app';
+
+/** Set by the e2e step to the app root; the preload spawns that app and opens a browser. */
+export const E2E_ROOT_ENV = 'ULTIMATE_E2E_ROOT';
+
+interface E2eRun {
+  browser: E2eBrowser;
+  readonly app: E2eApp;
+}
+
+const KEY = Symbol.for('ultimate.e2e.run');
+
+export function publishE2eRun(run: E2eRun): void {
+  Object.defineProperty(globalThis, KEY, { value: run, configurable: true });
+}
+
+const current = (): E2eRun | undefined => Reflect.get(globalThis, KEY) as E2eRun | undefined;
+
+/** Swap in a relaunched browser — the app stays; only the dead browser is replaced. */
+export function republishE2eBrowser(browser: E2eBrowser): void {
+  const run = current();
+  if (run !== undefined) run.browser = browser;
+}
+
+const missing = (): CdpBrowserMissingError =>
+  new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+
+/**
+ * The run's browser: `page`, and `session` for a second tab, an init script, the socket and request
+ * log and the offline switch for every worker. Refuses by name outside an e2e run that found one.
+ */
+export function e2eBrowser(): E2eBrowser {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.browser;
+}
+
+/** The app the run spawned: `base`, `stateDir`, and `restart({ BUILD_ID })` — a deploy. */
+export function e2eApp(): E2eApp {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.app;
+}
+
+/** The spawned app's origin, or `undefined` outside an e2e run. */
+export function e2eBaseUrl(): string | undefined {
+  return current()?.app.base;
+}

package/src/e2e-driver.ts

@@ -14,7 +14,14 @@ import {
 import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 
-export type E2eDriverOptions = E2ePageOptions;
+export interface E2eDriverOptions extends E2ePageOptions {
+  /**
+   * Switch the running app to a new build — the SERVER half no page port can speak for. Given, it
+   * becomes the `deploy` fixture's `newBuild()` and `e2eTest`'s `update()`; absent, both refuse by
+   * name. The gate's e2e preload passes the spawned app's `restart({ BUILD_ID })`.
+   */
+  readonly newBuild?: (() => Promise<void>) | undefined;
+}
 
 /**
  * A member this driver cannot build is a REFUSAL, never a no-op. A fixture that silently did
@@ -52,15 +59,21 @@ const networkFixtures = (browser: E2eBrowserPage): Pick<E2eFixtures, 'offline' |
 };
 
 /** What `e2eTest` hands its body: a real page, the network condition, and one honest refusal. */
-export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixtures => ({
+export const e2eFixtures = (
+  page: PageLike,
+  browser: E2eBrowserPage,
+  newBuild?: () => Promise<void>,
+): E2eFixtures => ({
   page,
   ...networkFixtures(browser),
-  // The one that is still genuinely out of reach, and it is not a port gap: a new build id is a
-  // fact about the SERVER, which no page port has ever been able to speak for.
-  update: refuse(
-    'update',
-    'a second build served under a new immutable build id, which is a server fact',
-  ),
+  // A new build id is a fact about the SERVER, which no page port can speak for — so it is
+  // forwarded when whoever spawned the app can restart it, and refused by name otherwise.
+  update:
+    newBuild ??
+    refuse(
+      'update',
+      'a second build served under a new immutable build id, which is a server fact',
+    ),
 });
 
 /**
@@ -73,7 +86,7 @@ export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixture
  * `test.skip` — which the gate now reports as a SKIPPED step rather than the green check it
  * printed until #434, and which a repo whose `x.verify.json` names `e2e` gets red for.
  *
- * `budget`, `signIn` and `deploy` are deliberately NOT registered here. Each needs something a
+ * `budget` and `signIn` are deliberately NOT registered here, and `deploy` only with `newBuild`. Each needs something a
  * page cannot supply — byte counts off a built `dist/`, an app's own sign-in route, a second build
  * — so each keeps refusing with `X_TEST_FIXTURE_UNAVAILABLE` naming what it waits for.
  *
@@ -82,16 +95,23 @@ export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixture
  */
 export function installE2eDriver(options: E2eDriverOptions): () => void {
   const page = e2ePage(options);
-  defineFixtures({ page: () => page });
+  const newBuild = options.newBuild;
+  defineFixtures({
+    page: () => page,
+    ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
+  });
   useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page)));
+    bunTest(name, () => body(e2eFixtures(page, options.page, newBuild)));
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than
     // deleting the key — is what keeps a later file's `{ page }` failing as
     // `X_TEST_FIXTURE_UNAVAILABLE` (a driver is missing) instead of `X_TEST_FIXTURE_UNKNOWN`
     // (register it), which is the wrong instruction for a name the framework declares.
-    defineFixtures({ page: unavailableFixture('page') });
+    defineFixtures({
+      page: unavailableFixture('page'),
+      ...(newBuild === undefined ? {} : { deploy: unavailableFixture('deploy') }),
+    });
     resetE2eDriver();
   };
 }

package/src/e2e-errors.ts

@@ -101,3 +101,17 @@ export class E2eServiceWorkerAbsentError extends UltimateError {
     });
   }
 }
+
+/**
+ * The app an e2e run spawns (`e2e-app.ts`) did not come up: its reset, its seed, or its boot. The
+ * cause carries that process's own output, rendered, because it is the only place the reason is.
+ */
+export class E2eAppFailedError extends UltimateError {
+  constructor(input: { readonly step: string; readonly output: string }) {
+    super({
+      code: 'X_E2E_APP_FAILED',
+      cause: `${renderCauseValue(input.step)} failed for the e2e app: ${renderCauseValue(input.output)}`,
+      fix: 'x dev --json   # boot the same app by hand and read why it would not start; the e2e run used a throwaway ULTIMATE_STATE_DIR, so your own .x is untouched',
+    });
+  }
+}

package/src/e2e-page.ts

@@ -67,11 +67,14 @@ const TITLE = '(() => JSON.stringify({ title: document.title }))()';
  * The cost, stated rather than hidden: this is a SECOND request to the same route, so what it
  * measures is that route's streaming behaviour and not the byte-for-byte first chunk the open
  * document received. It runs in the page, so it carries the page's cookies and its origin — a
- * `fetch` from the test process would carry neither.
+ * `fetch` from the test process would carry neither. The reader is CANCELLED after that chunk: a
+ * streamed response nobody pulls stays open until its last hole fills, holding one of the page's
+ * six connections to its origin for the rest of the test.
  */
 const firstFlushExpression = (url: string): string =>
   `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
-    .then((response) => response.body.getReader().read())
+    .then((response) => { const reader = response.body.getReader(); return reader.read()
+      .then((chunk) => { reader.cancel().catch(() => {}); return chunk; }); })
     .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
 
 /**

package/src/e2e-preload.ts

@@ -0,0 +1,64 @@
+// The e2e step's own preload: when the gate names an app root (`ULTIMATE_E2E_ROOT`, set by
+// `verify-e2e.ts`), spawn that app on a throwaway database, open ONE browser, install it as the
+// `page` fixture and the `e2eTest` driver, register `deploy.newBuild()` as a restart of the app on
+// its own port, and hand both to any test that asks `e2eBrowser()` / `e2eApp()`.
+
+import { afterAll, beforeEach } from 'bun:test';
+import type { E2eBrowser } from './cdp-browser';
+import { openE2eBrowser } from './cdp-browser';
+import { startE2eApp } from './e2e-app';
+import { E2E_ROOT_ENV, e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-handle';
+import { installE2eDriver } from './e2e-driver';
+import type { E2eBrowserPage } from './e2e-page';
+import { answersWithin } from './e2e-probe';
+
+/** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
+const PROBE_MS = 5_000;
+
+const root = Bun.env[E2E_ROOT_ENV];
+if (root !== undefined && root !== '') {
+  const app = await startE2eApp({ root });
+  let builds = 0;
+  // A deploy leaves the browser holding the OLD build's state: a SharedWorker whose socket went
+  // down with the restart and is now deep in its reconnect backoff, and tabs rendered by the old
+  // build. The test that deployed asserts on exactly that; the NEXT test must not inherit it.
+  let deployed = false;
+  const newBuild = async (): Promise<void> => {
+    deployed = true;
+    builds += 1;
+    await app.restart({ BUILD_ID: `e2e-build-${String(builds)}-${String(Date.now())}` });
+  };
+  // `openE2eBrowser`, never the `IfAvailable` door: the step only names a root after finding one.
+  let browser: E2eBrowser = await openE2eBrowser();
+  publishE2eRun({ browser, app });
+  // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
+  // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
+  // every test defined before it driving a closed browser.
+  const current: E2eBrowserPage = {
+    url: () => browser.page.url(),
+    goto: (url, options) => browser.page.goto(url, options),
+    evaluate: (expression) => browser.page.evaluate(expression),
+    click: (selector) => browser.page.click(selector),
+    offline: (enabled) => browser.page.offline(enabled),
+  };
+  const uninstall = installE2eDriver({ page: current, baseUrl: app.base, newBuild });
+
+  // A browser that stopped answering takes every later suite down with it, one call deadline per
+  // call (run 8). So each test starts with a short probe, and a browser that fails it — or one a
+  // deploy ran under — is closed and relaunched: the app is untouched, and the test gets a fresh
+  // profile, a fresh SharedWorker and a fresh tab on the same origin.
+  beforeEach(async () => {
+    const alive = !deployed && (await answersWithin(e2eBrowser().page, PROBE_MS));
+    if (alive) return;
+    deployed = false;
+    browser.close();
+    browser = await openE2eBrowser();
+    republishE2eBrowser(browser);
+  });
+
+  afterAll(async () => {
+    uninstall();
+    browser.close();
+    await app.stop();
+  });
+}

package/src/e2e-probe.ts

@@ -0,0 +1,23 @@
+// Is the browser still answering? One cheap `evaluate('1')` raced against a short budget — the
+// question the e2e preload asks before every test, because a hung browser otherwise costs every
+// later suite one full CDP deadline per call (run 8) instead of one relaunch.
+
+/** `true` when the page evaluated `1` within `ms`; a rejection or a stall is `false`, never a throw. */
+export async function answersWithin(
+  page: { evaluate(expression: string): Promise<unknown> },
+  ms: number,
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stalled = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  const answered = page.evaluate('1').then(
+    () => true,
+    () => false,
+  );
+  try {
+    return await Promise.race([answered, stalled]);
+  } finally {
+    clearTimeout(timer);
+  }
+}