@akanjs/devkit 3.2.0-rc.3 → 3.2.0-rc.6

package/frontendBuild/nativeCore.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, realpath, symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
+
+const makeTempRoot = tempDirs("akan-native-core-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+const repoRoot = path.resolve(akanjsRoot, "../..");
+const frameworkBarrels = ["akanjs/webkit", "akanjs/common", "akanjs/ui", "akanjs/server"];
+const reactExternals = [
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "scheduler",
+  "react-server-dom-webpack/client.browser",
+];
+const pageRuntime = [
+  path.join(akanjsRoot, "server/rscClient.tsx"),
+  path.join(akanjsRoot, "server/rscSegmentOutlet.tsx"),
+  path.join(akanjsRoot, "ui/System/Client.tsx"),
+];
+
+interface PageBuild {
+  workspaceRoot: string;
+  paths: Record<string, string[]>;
+  barrelImports: string[];
+  entries: string[];
+}
+
+const eagerInputsOf = async ({ workspaceRoot, paths, barrelImports, entries }: PageBuild) => {
+  const app = {
+    name: "demo",
+    cwdPath: path.join(workspaceRoot, "apps/demo"),
+    workspace: { workspaceRoot },
+    getConfig: async () => ({ barrelImports }),
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+  };
+  const result = await Bun.build({
+    entrypoints: entries,
+    target: "browser",
+    format: "esm",
+    splitting: true,
+    metafile: true,
+    throw: true,
+    conditions: ["production"],
+    external: reactExternals,
+    plugins: [await createBarrelImportsPlugin(app as never)],
+  });
+  const outputs = result.metafile?.outputs ?? {};
+  const eager = new Set<string>();
+  const load = (outputPath: string) => {
+    if (eager.has(outputPath) || !outputs[outputPath]) return;
+    eager.add(outputPath);
+    for (const imp of outputs[outputPath].imports) if (imp.kind === "import-statement") load(imp.path);
+  };
+  //? A dynamically imported module gets an entry chunk of its own too: only the page's entries start the walk.
+  for (const [outputPath, output] of Object.entries(outputs))
+    if (output.entryPoint && entries.includes(path.resolve(output.entryPoint))) load(outputPath);
+  return {
+    eager: [...eager].flatMap((outputPath) => Object.keys(outputs[outputPath]?.inputs ?? {})),
+    all: Object.keys(result.metafile?.inputs ?? {}),
+  };
+};
+
+const eagerInputsOfAPage = async (store: string) => {
+  //? Real path: Bun names entry points through /private on macOS, where the temp dir is a symlink.
+  const root = await realpath(await makeTempRoot());
+  await mkdir(path.join(root, "node_modules"), { recursive: true });
+  await symlink(akanjsRoot, path.join(root, "node_modules/akanjs"));
+  const paths = { "@apps/*": ["./apps/*"] };
+  await write(path.join(root, "tsconfig.json"), JSON.stringify({ compilerOptions: { paths } }));
+  await write(path.join(root, "apps/demo/lib/st.ts"), store);
+  return await eagerInputsOf({
+    workspaceRoot: root,
+    paths,
+    barrelImports: frameworkBarrels,
+    entries: [...pageRuntime, path.join(akanjsRoot, "ui/Link/Anchor.tsx"), path.join(root, "apps/demo/lib/st.ts")],
+  });
+};
+
+const isCore = (input: string) => /native\/packages\/core\//.test(input);
+
+//? `akan sync` generates these, which a fresh checkout lacks; CI's sync job sets REQUIRE_SYNCED_LIBS after syncing.
+const syncedLibFiles = [
+  ...["shared", "util"].flatMap((lib) =>
+    [
+      "client.ts",
+      "server.ts",
+      "index.ts",
+      "ui/index.ts",
+      "webkit/index.ts",
+      "common/index.ts",
+      "lib/cnst.ts",
+      "lib/st.ts",
+      "lib/useClient.ts",
+    ].map((file) => `libs/${lib}/${file}`),
+  ),
+  ...["user", "admin"].map((module) => `libs/shared/lib/${module}/index.ts`),
+];
+const libsSynced = syncedLibFiles.every((file) => existsSync(path.join(repoRoot, file)));
+
+describe("@akanjs/native/core on a web page", () => {
+  test("the runtime, the system shell, Link and a store reading the host stay off it", async () => {
+    const { eager, all } = await eagerInputsOfAPage(
+      'import { isNativeShell, router } from "akanjs/client";\nimport { store } from "akanjs/store";\nexport const st = { isNativeShell, router, store };\n',
+    );
+
+    expect(eager.filter(isCore)).toEqual([]);
+    expect(all.some(isCore)).toBe(true);
+  });
+
+  test("a store importing akanjs/client/native statically puts it on the page", async () => {
+    const { eager } = await eagerInputsOfAPage(
+      'import { isNativeShell } from "akanjs/client/native";\nexport const st = { isNativeShell };\n',
+    );
+
+    expect(eager.some(isCore)).toBe(true);
+  });
+
+  test.skipIf(!libsSynced && !process.env.REQUIRE_SYNCED_LIBS)(
+    "a page drawing a shared Field and User template, on a store merging shared, stays off it",
+    async () => {
+      const { eager, all } = await eagerInputsOf({
+        workspaceRoot: repoRoot,
+        paths: (await Bun.file(path.join(repoRoot, "tsconfig.json")).json()).compilerOptions.paths,
+        barrelImports: [
+          ...frameworkBarrels,
+          ...["shared", "util"].flatMap((lib) =>
+            ["ui", "webkit", "common", "client", "server"].map((facet) => `@libs/${lib}/${facet}`),
+          ),
+        ],
+        entries: [
+          ...pageRuntime,
+          ...["lib/useClient.ts", "lib/st.ts", "ui/Field.tsx", "lib/user/User.Template.tsx"].map((file) =>
+            path.join(repoRoot, "libs/shared", file),
+          ),
+        ],
+      });
+
+      expect(eager.filter(isCore)).toEqual([]);
+      expect(all.some(isCore)).toBe(true);
+    },
+  );
+});

package/frontendBuild/ssrBaseArtifactBuilder.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { SsrBaseArtifactBuilder } from "./ssrBaseArtifactBuilder";
+
+describe("SsrBaseArtifactBuilder.outletModuleMap", () => {
+  const outlet = "pkgs/akanjs/server/rscSegmentOutlet.tsx";
+  const ssrOutput = "/dist/client-ssr/rscSegmentOutlet.js";
+  const manifest = {
+    [`${outlet}#AkanSegmentOutlet`]: { id: "/_akan/client/outlet.js", chunks: [], name: "AkanSegmentOutlet" },
+    [`${outlet}#AkanRouteHead`]: { id: "/_akan/client/outlet.js", chunks: [], name: "AkanRouteHead" },
+    "pkgs/akanjs/ui/Other.tsx#Other": { id: "/_akan/client/other.js", chunks: [], name: "Other" },
+  };
+
+  test("keeps every export of the outlet module under its one client id, each served by the SSR build", () => {
+    expect(SsrBaseArtifactBuilder.outletModuleMap(manifest, outlet, ssrOutput)).toEqual({
+      "/_akan/client/outlet.js": {
+        AkanSegmentOutlet: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: "AkanSegmentOutlet", async: true },
+        AkanRouteHead: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: "AkanRouteHead", async: true },
+      },
+    });
+  });
+
+  test("is empty without the outlet's SSR build or client reference", () => {
+    expect(SsrBaseArtifactBuilder.outletModuleMap(manifest, outlet, undefined)).toEqual({});
+    expect(SsrBaseArtifactBuilder.outletModuleMap(manifest, undefined, ssrOutput)).toEqual({});
+  });
+});

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -153,25 +153,10 @@ export class SsrBaseArtifactBuilder {
     const rscClientUrl = clientBundle.entryUrlsByAbsPath.get(rscClientEntry) ?? "";
     const rscRuntimeSsrManifest = {
       moduleLoading: null,
-      moduleMap: Object.fromEntries(
-        Object.entries(clientBundle.manifest)
-          .map(([key, row]) => {
-            const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(rscSegmentOutletEntry);
-            if (
-              !ssrOutput ||
-              key !== `${clientBundle.clientReferenceIdByAbsPath.get(rscSegmentOutletEntry)}#${row.name}`
-            ) {
-              return null;
-            }
-            return [
-              row.id,
-              { [row.name]: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true } },
-            ];
-          })
-          .filter(
-            (entry): entry is [string, Record<string, { id: string; chunks: string[]; name: string; async: true }>] =>
-              Boolean(entry),
-          ),
+      moduleMap: SsrBaseArtifactBuilder.outletModuleMap(
+        clientBundle.manifest,
+        clientBundle.clientReferenceIdByAbsPath.get(rscSegmentOutletEntry),
+        ssrBundle.entryOutputAbsByAbsPath.get(rscSegmentOutletEntry),
       ),
     };
     const vendorMap = Object.fromEntries(
@@ -190,6 +175,25 @@ export class SsrBaseArtifactBuilder {
       },
     };
   }
+
+  /** Every export of the outlet module shares one client id, so each joins that id's row instead of replacing it. */
+  static outletModuleMap(
+    manifest: NonNullable<BaseBuildArtifact["rscRuntimeClientManifest"]>,
+    outletReferenceId: string | undefined,
+    ssrOutput: string | undefined,
+  ) {
+    const moduleMap: Record<string, Record<string, { id: string; chunks: string[]; name: string; async: true }>> = {};
+    if (!ssrOutput || !outletReferenceId) return moduleMap;
+    for (const [key, row] of Object.entries(manifest)) {
+      if (key !== `${outletReferenceId}#${row.name}`) continue;
+      moduleMap[row.id] = {
+        ...moduleMap[row.id],
+        [row.name]: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true },
+      };
+    }
+    return moduleMap;
+  }
+
   async #resolveAkanServerPath() {
     const candidates: string[] = [];
     try {

package/frontendBuild/vendorImportScanner.test.ts

@@ -50,22 +50,43 @@ describe("VendorImportScanner", () => {
     expect(used["akanjs/store"]).toEqual([]);
   });
 
+  test("reads the import at the end of a minified body too long for the call stack to walk", () => {
+    const body = Array.from({ length: 40_000 }, (_, i) => `a${i % 26}(${i})`).join(",");
+
+    const used = scan(`import{st}from"akanjs/store";function f(){${body},import("akanjs/fetch")}`);
+
+    expect(used).toEqual({ "akanjs/store": ["st"], "akanjs/common": [], "tailwind-merge": [] });
+  });
+
   test("collects across every .js file of a directory", async () => {
     const dir = await makeTempRoot();
     await write(path.join(dir, "entry-a.js"), 'import{st}from"akanjs/store";');
     await write(path.join(dir, "chunks/lazy.js"), 'import{RootStore}from"akanjs/store";');
     await write(path.join(dir, "chunks/lazy.js.map"), 'import{ignored}from"akanjs/store";');
 
-    const used = await VendorImportScanner.exportsUsedIn(dir, ["akanjs/store"]);
+    const used = await VendorImportScanner.exportsUsedIn(dir, ["akanjs/store"], ["/_akan/client/entry-a.js"]);
 
     expect(used).toEqual({ "akanjs/store": ["RootStore", "st"] });
   });
 
-  test("reads a client output directory a build never wrote as importing nothing", async () => {
+  test("reads a client output directory a build never wrote as importing nothing when the routes have no client entry", async () => {
     const dir = await makeTempRoot();
 
-    expect(await VendorImportScanner.exportsUsedIn(path.join(dir, "client"), ["akanjs/store"])).toEqual({
+    expect(await VendorImportScanner.exportsUsedIn(path.join(dir, "client"), ["akanjs/store"], [])).toEqual({
       "akanjs/store": [],
     });
   });
+
+  test("fails, naming the entry, when a route client entry is not in the directory it scans", async () => {
+    const dir = await makeTempRoot();
+    await write(path.join(dir, "chunks/shared.js"), 'import{st}from"akanjs/store";');
+    const entries = ["/_akan/client/page-a1.js", "/_akan/client/page-a1.js", "/_akan/client/chunks/shared.js"];
+
+    await expect(VendorImportScanner.exportsUsedIn(dir, ["akanjs/store"], entries)).rejects.toThrow(
+      `no file under ${dir} for the route client entries /_akan/client/page-a1.js`,
+    );
+    await expect(
+      VendorImportScanner.exportsUsedIn(path.join(dir, "missing"), ["akanjs/store"], ["/_akan/client/page-a1.js"]),
+    ).rejects.toThrow("/_akan/client/page-a1.js");
+  });
 });

package/frontendBuild/vendorImportScanner.ts

@@ -12,25 +12,40 @@ export class VendorImportScanner {
     for (const specifier of specifiers) this.#names.set(specifier, new Set());
   }
 
-  /** The names each specifier's importers read across a directory's `.js` files; a specifier read whole is left out. */
-  static async exportsUsedIn(dir: string, specifiers: readonly string[]): Promise<Record<string, string[]>> {
+  static async exportsUsedIn(
+    dir: string,
+    specifiers: readonly string[],
+    entryUrls: readonly string[],
+  ): Promise<Record<string, string[]>> {
     const scanner = new VendorImportScanner(specifiers);
-    if (!fs.existsSync(dir)) return scanner.usedExports();
-    for await (const relative of new Bun.Glob("**/*.js").scan({ cwd: dir }))
-      scanner.scan(await Bun.file(path.join(dir, relative)).text(), relative);
+    const scanned: string[] = [];
+    if (fs.existsSync(dir))
+      for await (const relative of new Bun.Glob("**/*.js").scan({ cwd: dir })) {
+        scanner.scan(await Bun.file(path.join(dir, relative)).text(), relative);
+        scanned.push(`/${relative.split(path.sep).join("/")}`);
+      }
+    const unread = [...new Set(entryUrls)].filter((url) => !scanned.some((relative) => url.endsWith(relative)));
+    if (unread.length > 0) {
+      const named = `${unread.slice(0, 3).join(", ")}${unread.length > 3 ? `, and ${unread.length - 3} more` : ""}`;
+      throw new Error(
+        `[VendorImportScanner] no file under ${dir} for the route client entries ${named}; narrowing the vendor entries without them would drop names those pages import`,
+      );
+    }
     return scanner.usedExports();
   }
 
   scan(source: string, fileName = "chunk.js"): this {
     if (![...this.#specifiers].some((specifier) => source.includes(specifier))) return this;
-    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS);
-    const visit = (node: ts.Node): void => {
+    //? A stack, not recursion: minified code folds a long body into one comma chain, deeper than the call stack.
+    const stack: ts.Node[] = [ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS)];
+    for (let node = stack.pop(); node; node = stack.pop()) {
       if (ts.isImportDeclaration(node)) this.#readImport(node);
       else if (ts.isExportDeclaration(node)) this.#readExport(node);
       else if (ts.isCallExpression(node)) this.#readCall(node);
-      ts.forEachChild(node, visit);
-    };
-    visit(file);
+      ts.forEachChild(node, (child) => {
+        stack.push(child);
+      });
+    }
     return this;
   }
 

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -123,18 +123,21 @@ describe("IncrementalBuilderHost", () => {
         id: 1,
         ok: false,
         error: "builder exited to release bundler memory before answering; reload to retry",
+        kind: "unavailable",
       },
       {
         type: "build-csr-res",
         id: 2,
         ok: false,
         error: "builder exited to release bundler memory before answering; reload to retry",
+        kind: "unavailable",
       },
       {
         type: "build-graph-res",
         id: 4,
         ok: false,
         error: "builder exited to release bundler memory before answering; reload to retry",
+        kind: "unavailable",
       },
     ]);
 
@@ -159,6 +162,7 @@ describe("IncrementalBuilderHost", () => {
         id: 1,
         ok: false,
         error: "builder exited unexpectedly before answering; reload once it is back",
+        kind: "unavailable",
       },
     ]);
 
@@ -168,7 +172,7 @@ describe("IncrementalBuilderHost", () => {
     expect(host.send({ type: "build-route", id: 2, routeId: "b", seeds: [], knownEntries: [] })).toBe(true);
     host.stop();
     expect(messages).toEqual([
-      { type: "build-route-res", id: 2, ok: false, error: "builder was stopped before answering" },
+      { type: "build-route-res", id: 2, ok: false, error: "builder was stopped before answering", kind: "unavailable" },
     ]);
   });
 

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -287,7 +287,8 @@ export class IncrementalBuilderHost {
     const lost = [...this.#inFlight];
     this.#inFlight.clear();
     this.logger.warn(`failing ${lost.length} unanswered builder request(s): ${reason}`);
-    for (const [id, type] of lost) this.#onMessage({ type: `${type}-res`, id, ok: false, error: reason });
+    for (const [id, type] of lost)
+      this.#onMessage({ type: `${type}-res`, id, ok: false, error: reason, kind: "unavailable" });
   }
   stop() {
     this.#manualStop = true;

package/lint/no-web-only-api-outside-webkit.grit

@@ -13,7 +13,7 @@ or {
     $access <: or { `navigator.share`, `navigator.canShare` },
     register_diagnostic(
       span = $access,
-      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`; the runtime's `share` plugin is the app side.",
+      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client`; the runtime's `share` plugin is the app side.",
       severity = "warn"
     )
   },
@@ -21,7 +21,7 @@ or {
     $access <: or { `navigator.serviceWorker`, `Notification.requestPermission`, `Notification.permission` },
     register_diagnostic(
       span = $access,
-      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native`, and `usePushNotification` in libs/util wraps both.",
+      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native/push`, and `usePushNotification` in libs/util wraps both.",
       severity = "warn"
     )
   },
@@ -37,7 +37,7 @@ or {
     $access <: `navigator.vibrate`,
     register_diagnostic(
       span = $access,
-      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native` in a `webkit/` hook.",
+      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native/haptics` in a `webkit/` hook.",
       severity = "warn"
     )
   }

package/{constantFieldNames.test.ts → moduleFieldNames.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { constantFieldNames } from "./constantFieldNames";
+import { constantFieldNames, unlabeledFieldNames } from "./moduleFieldNames";
 
-describe("constantFieldNames", () => {
+describe("moduleFieldNames", () => {
   test("names each field the code declares, chained or not", () => {
     const content = `export class TaskInput extends via((field) => ({
   title: field(String),
@@ -31,4 +31,26 @@ export const example = \`previousStatus: field(TaskStatus)\`;
 
     expect(constantFieldNames(content)).toEqual(["title", "note"]);
   });
+
+  test("unlabeledFieldNames finds a real label and reports one that is only commented out or inside a string", () => {
+    const constant = `export class TaskInput extends via((field) => ({
+  title: field(String),
+  content: field(String),
+  status: field(TaskStatus),
+  due: field(Date).optional(),
+})) {}
+`;
+    const dictionary = `export const dictionary = modelDictionary(["en", "ko"])
+  .model<Task>((t) => ({
+    title: t(["Title", "제목"]).desc(["Task title", "할 일 제목"]),
+    // content: t(["Content", "내용"]),
+    /* status: t(["Status", "상태"]), */
+  }))
+  .translate({
+    taskDueHint: ["due: pick a date", "마감: 날짜를 고르세요"],
+  });
+`;
+
+    expect(unlabeledFieldNames(constant, dictionary)).toEqual(["content", "status", "due"]);
+  });
 });

package/moduleFieldNames.ts

@@ -0,0 +1,25 @@
+import ts from "typescript";
+
+const isFieldCall = (node: ts.Expression): boolean =>
+  ts.isCallExpression(node) &&
+  (ts.isIdentifier(node.expression)
+    ? node.expression.text === "field"
+    : ts.isPropertyAccessExpression(node.expression) && isFieldCall(node.expression.expression));
+
+const propertyNames = (content: string, declares: (initializer: ts.Expression) => boolean) => {
+  const names: string[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && declares(node.initializer))
+      names.push(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(ts.createSourceFile("module.ts", content, ts.ScriptTarget.Latest));
+  return names;
+};
+
+export const constantFieldNames = (content: string) => propertyNames(content, isFieldCall);
+
+export const unlabeledFieldNames = (constantContent: string, dictionaryContent: string) => {
+  const labels = new Set(propertyNames(dictionaryContent, () => true));
+  return constantFieldNames(constantContent).filter((name) => !labels.has(name));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.3",
+  "version": "3.2.0-rc.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.3",
+    "@akanjs/language": "3.2.0-rc.6",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.3",
+    "akanjs": "3.2.0-rc.6",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewView.ts

@@ -77,20 +77,12 @@ export class PreviewView {
     }: PreviewProbeOptions = {},
   ): Promise<PreviewProbeResult> {
     const logs: string[] = [];
-    const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
+    const view = await PreviewView.#start(
+      () => PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) }),
+      engine,
+      { startTimeoutMs, timeoutMs },
+    );
     try {
-      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
-      //? One that died or was closed instead is spawned afresh by the next view, which gets the full bound.
-      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
-      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
-      await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled).then(
-        () => PreviewView.#stalled.delete(engine),
-        (error: unknown) => {
-          if (error === stalled) PreviewView.#stalled.add(engine);
-          else PreviewView.#stalled.delete(engine);
-          throw error;
-        },
-      );
       const deadline = Date.now() + timeoutMs;
       const within = <T>(work: Promise<T>, what: string) =>
         PreviewView.#within(
@@ -122,6 +114,33 @@ export class PreviewView {
     }
   }
 
+  static async #start(
+    open: () => WebViewLike,
+    engine: PreviewEngine,
+    { startTimeoutMs, timeoutMs }: { startTimeoutMs: number; timeoutMs: number },
+  ) {
+    for (let attempt = 1; ; attempt++) {
+      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
+      //? One that died or was closed instead is spawned afresh by the next view, which gets the full bound.
+      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
+      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
+      let view: WebViewLike | undefined;
+      try {
+        view = open();
+        await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled);
+        PreviewView.#stalled.delete(engine);
+        return view;
+      } catch (error) {
+        await view?.close();
+        if (error === stalled) PreviewView.#stalled.add(engine);
+        else PreviewView.#stalled.delete(engine);
+        if (error === stalled || attempt > 1) throw error;
+        //? Bun reaps a browser that died only on a later timer turn; until then `new Bun.WebView()` throws "Failed to spawn Chrome".
+        await Bun.sleep(100);
+      }
+    }
+  }
+
   static async #load(
     view: WebViewLike,
     url: string,

package/preview/previewView.test.ts

@@ -178,9 +178,7 @@ Bun.WebView.closeAll();`,
 console.log(await open());
 const killed = open();
 Bun.WebView.closeAll();
-console.error(await killed);
-await Bun.sleep(500);
-console.log(await open());
+console.log(await killed);
 Bun.WebView.closeAll();`,
         6,
       );
@@ -194,4 +192,36 @@ Bun.WebView.closeAll();`,
     },
     browserTestMs,
   );
+
+  test.skipIf(!slowChromeRuns)(
+    "starts a new browser for the page right after one that the browser died on",
+    async () => {
+      const { code, out, log } = await withSlowChrome(
+        `const { promise: loading, resolve } = Promise.withResolvers();
+const server = Bun.serve({
+  port: 0,
+  fetch: (req) =>
+    new URL(req.url).pathname === "/hang"
+      ? (resolve(), new Promise(() => undefined))
+      : new Response("<!doctype html><body>up</body>", { headers: { "content-type": "text/html" } }),
+});
+const open = (path) =>
+  PreviewView.probe(\`http://localhost:\${server.port}\${path}\`, { engine: "chrome" }).then(
+    (probe) => probe.text,
+    (error) => error.message,
+  );
+const killed = open("/hang");
+await loading;
+Bun.WebView.closeAll();
+console.error(await killed);
+console.log(await open("/"));
+server.stop(true);
+Bun.WebView.closeAll();`,
+        0,
+      );
+      expect(out, log).toBe("up");
+      expect(code, log).toBe(0);
+    },
+    browserTestMs,
+  );
 });