@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.10

package/maintainabilityContract.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
+import { BareErrorScanner } from "./bareErrorScanner";
 import { ComponentSizeScanner } from "./componentSizeScanner";
 import { ComponentWriteChainScanner } from "./componentWriteChainScanner";
 import { EndpointReach } from "./endpointReach";
@@ -97,6 +98,16 @@ export interface StoreAccessViolation {
   recorded?: number;
 }
 
+export interface BareErrorViolation {
+  kind: "bareError";
+  rule: "akan.error.bare-error";
+  key: string;
+  file: string;
+  line: number;
+  lines: number[];
+  recorded?: number;
+}
+
 export interface BaselineGrowth {
   kind: "baselineGrowth";
   rule: "akan.baseline.growth";
@@ -110,14 +121,25 @@ export interface BaselineGrowth {
   measured?: boolean;
 }
 
+export interface StaleTotal {
+  kind: "staleTotal";
+  rule: DebtRuleId;
+  key: string;
+  file: string;
+  line: number;
+  count: number;
+  recorded: number;
+}
+
 export type MaintainabilityViolation =
   | SizeViolation
   | ClassSizeViolation
   | MultiWriteViolation
   | StoreAccessViolation
   | WritePlacementViolation
-  | LoopCallViolation;
-export type MaintainabilityFailure = MaintainabilityViolation | BaselineGrowth;
+  | LoopCallViolation
+  | BareErrorViolation;
+export type MaintainabilityFailure = MaintainabilityViolation | BaselineGrowth | StaleTotal;
 
 export type BaselineSeed = "written" | "kept" | "removed" | "clean";
 
@@ -133,6 +155,7 @@ export class MaintainabilityContract {
     "akan.component.store-access",
     "akan.write.placement",
     "akan.service.call-in-loop",
+    "akan.error.bare-error",
     "akan.baseline.growth",
   ] as const;
   static readonly #measuredFiles = "{lib,ui,webkit,srvkit,common,plugin}/**/*.{ts,tsx,md}";
@@ -180,23 +203,33 @@ export class MaintainabilityContract {
       existing === null ? new MaintainabilityBaseline() : MaintainabilityBaseline.parse(existing, this.baselinePath);
     const tightened = baseline.tightenedBy(violations);
     if (fix && existing !== null) await this.#tighten(baseline, tightened);
-    const failures: MaintainabilityFailure[] = violations
-      .filter((violation) => !baseline.allows(violation))
-      .map((violation) => {
-        const recorded = baseline.recordedOf(violation);
-        return recorded === undefined ? violation : { ...violation, recorded };
-      });
     //? Without fix the file on disk is what merges, so an entry it holds above the measured count is checked as written.
     const working = fix ? tightened : baseline;
-    const source = `${reference.label}:${this.sysPath}/${MaintainabilityBaseline.fileName}`;
-    const committed =
-      reference.text !== null
-        ? MaintainabilityBaseline.parse(reference.text, source, { lenient: true })
-        : working.isEmpty
-          ? null
-          : await this.#measuredAt(reference.ref);
-    if (committed === null) return failures;
     const lines = ((await this.#readBaseline()) ?? "").split(/\r?\n/);
+    const failures: MaintainabilityFailure[] = [
+      ...working.staleTotals(violations).map(
+        ({ rule, count, recorded }): StaleTotal => ({
+          kind: "staleTotal",
+          rule,
+          key: MaintainabilityBaseline.totalKey,
+          file: MaintainabilityBaseline.fileName,
+          line: MaintainabilityContract.#lineOf(lines, rule, MaintainabilityBaseline.totalKey),
+          count,
+          recorded,
+        }),
+      ),
+      ...baseline.unallowed(violations).map((violation) => {
+        const recorded = baseline.recordedOf(violation);
+        return recorded === undefined ? violation : { ...violation, recorded };
+      }),
+    ];
+    const source = `${reference.label}:${this.sysPath}/${MaintainabilityBaseline.fileName}`;
+    const recorded =
+      reference.text !== null ? MaintainabilityBaseline.parse(reference.text, source, { lenient: true }) : null;
+    const unrecorded = new Set(working.rulesOutside(recorded));
+    const measured = unrecorded.size ? await this.#measuredAt(reference.ref) : null;
+    if (recorded === null && measured === null) return failures;
+    const committed = (recorded ?? new MaintainabilityBaseline()).withSectionsOf(measured, unrecorded);
     const growths = working
       .grownFrom(committed)
       .map(
@@ -207,7 +240,7 @@ export class MaintainabilityContract {
           line: MaintainabilityContract.#lineOf(lines, rule, growth.key),
           debtRule: rule,
           reference: reference.label,
-          ...(reference.text === null ? { measured: true } : {}),
+          ...(unrecorded.has(rule) ? { measured: true } : {}),
           ...growth,
         }),
       )
@@ -234,17 +267,37 @@ export class MaintainabilityContract {
 
   async #measurePackage() {
     const files = (await this.#packageFiles()).filter(MaintainabilityLimits.isPackageSource);
+    const packageName = await this.#packageName();
     const violations = await Promise.all(
       files.map(async (file) => {
         const workspaceFile = `${this.sysPath}/${file}`;
         const content = await this.#read(workspaceFile);
-        return MaintainabilityContract.#measurePackageFile(file, this.#sourceOf(workspaceFile, content).sourceFile);
+        return MaintainabilityContract.#measurePackageFile(
+          file,
+          this.#sourceOf(workspaceFile, content).sourceFile,
+          MaintainabilityLimits.holdsBareErrors(packageName, file),
+        );
       }),
     );
     return violations.flat();
   }
 
-  static #measurePackageFile(file: string, sourceFile: ts.SourceFile) {
+  async #packageName() {
+    const manifest = `${this.sysPath}/package.json`;
+    const text = this.#tree
+      ? this.#tree.get(manifest)
+      : existsSync(path.join(this.#workspaceRoot, manifest))
+        ? await this.#read(manifest)
+        : undefined;
+    try {
+      const { name } = JSON.parse(text ?? "{}") as { name?: unknown };
+      return typeof name === "string" ? name : null;
+    } catch {
+      return null;
+    }
+  }
+
+  static #measurePackageFile(file: string, sourceFile: ts.SourceFile, holdsBareErrors: boolean) {
     const violations: MaintainabilityViolation[] = [];
     const maxLines = MaintainabilityLimits.packageFileMaxLines;
     const lineCount = MaintainabilityLimits.lineCountOf(sourceFile.text);
@@ -275,6 +328,16 @@ export class MaintainabilityContract {
         memberCount,
         maxMembers: MaintainabilityLimits.classMaxMembers,
       });
+    const bareErrors = holdsBareErrors ? new BareErrorScanner().lines(sourceFile) : [];
+    if (bareErrors.length)
+      violations.push({
+        kind: "bareError",
+        rule: "akan.error.bare-error",
+        key: file,
+        file,
+        line: bareErrors[0] ?? 1,
+        lines: bareErrors,
+      });
     return violations;
   }
 
@@ -426,15 +489,16 @@ export class MaintainabilityContract {
     return { ref, label: ref === "HEAD" ? ref : ref.slice(0, 12), text };
   }
 
-  //* With no baseline file at the reference, the debt its code already holds is the floor: none for a scope new to the
-  //* branch or one whose paid-off file was removed, and the breaches it had for a scope that adopts the gate here.
+  //* With no baseline file at the reference, or no section there for a rule, the debt its code already holds is the
+  //* floor: none for a scope new to the branch or one whose paid-off file was removed, and the breaches it had for a
+  //* scope that adopts the gate here or a rule this version adds.
   async #measuredAt(ref: string) {
     if ((await this.#git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])) === null) return null;
     const roots = [this.sysPath, ...this.#libNames.map((libName) => `libs/${libName}`)];
     const contract = new MaintainabilityContract(this.#workspaceRoot, this.#scope, this.#libNames);
     contract.#tree = await new GitRevision(this.#workspaceRoot).filesAt(
       ref,
-      (file) => /\.(tsx?|md)$/.test(file),
+      (file) => /\.(tsx?|md)$/.test(file) || file === `${this.sysPath}/package.json`,
       roots,
     );
     return MaintainabilityBaseline.of(await contract.measure());
@@ -492,6 +556,7 @@ export class MaintainabilityContract {
       lines.findIndex((line) => line.includes(`${JSON.stringify(rule)}:`)),
       0,
     );
+    if (key === MaintainabilityBaseline.totalKey) return from + 1;
     const idx = lines.findIndex((line, lineIdx) => lineIdx >= from && line.includes(`${JSON.stringify(key)}:`));
     return Math.max(idx + 1, 1);
   }

package/maintainabilityExceptionScanner.test.ts

@@ -98,4 +98,18 @@ describe("MaintainabilityExceptionScanner", () => {
     expect(byRule("apps/demo/akan.baseline.json", "akan.size.component")?.fix).toContain("threshold is wrong");
     expect(byRule("apps/demo/akan.baseline.json", "akan.store.multi-write")?.fix).toContain("add-mutation");
   });
+
+  test("tells a bare Error entry to construct a coded error, since the rule takes no exception", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/akan.baseline.json": baselineOf({ "akan.error.bare-error": { "server/host.ts": 2 } }),
+    });
+
+    expect(await new MaintainabilityExceptionScanner().scan(root)).toMatchObject([
+      {
+        message:
+          "pkgs/akanjs carries 0 reasoned exceptions and 1 adopted-debt entry for akan.error.bare-error: server/host.ts.",
+        fix: expect.stringContaining("construct an `AkanError` subclass"),
+      },
+    ]);
+  });
 });

package/maintainabilityExceptionScanner.ts

@@ -11,6 +11,8 @@ export class MaintainabilityExceptionScanner {
     "Many reasoned exceptions under one rule mean its threshold is wrong: fix the limit in MaintainabilityLimits rather than record another. Otherwise shrink the code, and `akan lint` lowers each entry and drops it once it passes.";
   static readonly #correctnessFix =
     "A write rule takes no exception: send the writes through one store action and one endpoint (`akan workflow plan add-mutation`), and `akan lint` drops the entry.";
+  static readonly #bareErrorFix =
+    "A bare Error takes no exception: construct an `AkanError` subclass with a code, and `akan lint` lowers the entries as they go.";
 
   async scan(workspaceRoot: string): Promise<QualityWarning[]> {
     const sysPaths = await Promise.all(
@@ -81,7 +83,9 @@ export class MaintainabilityExceptionScanner {
       locations,
       fix: MaintainabilityBaseline.reasonedRules.has(rule)
         ? MaintainabilityExceptionScanner.#shapeFix
-        : MaintainabilityExceptionScanner.#correctnessFix,
+        : rule === "akan.error.bare-error"
+          ? MaintainabilityExceptionScanner.#bareErrorFix
+          : MaintainabilityExceptionScanner.#correctnessFix,
     };
   }
 

package/maintainabilityLimits.ts

@@ -25,6 +25,18 @@ export class MaintainabilityLimits {
   static readonly packageFileMaxLines = 800;
   static readonly functionMaxLines = 150;
   static readonly classMaxMembers = 60;
+  //? The request-path facets: a failure there reaches a caller, who branches on its code rather than its message.
+  static readonly bareErrorRoots: ReadonlyMap<string, readonly string[]> = new Map([
+    ["akanjs", ["server/", "service/", "signal/"]],
+  ]);
+
+  //? Rules this repository holds its own framework to: no workspace has a package they measure, so none is told of them.
+  static readonly repoOnlyRules: ReadonlySet<string> = new Set(["akan.error.bare-error"]);
+
+  static holdsBareErrors(pkgName: string | null, pkgRelativePath: string) {
+    const roots = pkgName === null ? undefined : MaintainabilityLimits.bareErrorRoots.get(pkgName);
+    return (roots ?? []).some((root) => pkgRelativePath.startsWith(root));
+  }
 
   static fileKindOf(sysRelativePath: string): FileKind | null {
     const kinds = Object.keys(MaintainabilityLimits.#maxLinesByKind) as FileKind[];

package/maintainabilityReport.ts

@@ -1,4 +1,5 @@
 import { AbstractDoc } from "./abstractDoc";
+import { MaintainabilityBaseline } from "./maintainabilityBaseline";
 import type {
   DebtRuleId,
   MaintainabilityCommands,
@@ -7,7 +8,7 @@ import type {
 } from "./maintainabilityContract";
 import { type FileKind, MaintainabilityLimits } from "./maintainabilityLimits";
 
-type FixKey = FileKind | "package" | Exclude<MaintainabilityRuleId, "akan.size.file">;
+type FixKey = FileKind | "package" | "staleTotal" | Exclude<MaintainabilityRuleId, "akan.size.file">;
 
 export class MaintainabilityReport {
   static readonly #clientSplitFix =
@@ -48,8 +49,12 @@ export class MaintainabilityReport {
       "A server write leaves the browser through one store action, started by one module component. Move a `fetch.<mutation>` into a store action, and hand `ui/` and `webkit/` code the write as an `onX` prop or hook argument from the module's `Zone` or `Util`: they stay free of any one model, and an agent or another screen reaches the write through the store.",
     "akan.service.call-in-loop":
       "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (`create<Model>Many(rows)`, one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
+    "akan.error.bare-error":
+      "Construct an `AkanError` subclass from `akanjs/base` with a code the caller can branch on, and a `statusCode` when it answers a request: an existing class whose code fits, or a new one beside the code that fails; a class extending a built-in Error extends `AkanError` instead. A failure another process reported travels as itself. The package's total is what is held, so moving a bare Error between files passes and `akan lint` rewrites the entries.",
     "akan.baseline.growth":
       "Restore the entry from the default branch, then split the file or move the writes instead: `akan lint` lowers an entry as the code shrinks and never raises one.",
+    staleTotal:
+      "Run `akan verify <package>`, which lowers the section, and commit `akan.baseline.json` in this change: a recorded total above the code is room for a new failure anywhere. A bare `akan verify` covers only uncommitted files.",
   };
 
   static readonly #labels: { [key in FixKey]?: string } = {
@@ -65,7 +70,9 @@ export class MaintainabilityReport {
     "akan.component.store-access": "component or hook reaching the store often",
     "akan.write.placement": "write sent outside a store action or module component",
     "akan.service.call-in-loop": "service call per item",
+    "akan.error.bare-error": "bare Error",
     "akan.baseline.growth": "baseline entry",
+    staleTotal: "baseline total",
   };
 
   static readonly #units: { [rule in DebtRuleId]: string } = {
@@ -79,6 +86,7 @@ export class MaintainabilityReport {
     "akan.component.write-chain": "writes",
     "akan.write.placement": "writes",
     "akan.service.call-in-loop": "calls per item",
+    "akan.error.bare-error": "bare Errors",
   };
 
   static describe(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
@@ -118,13 +126,17 @@ export class MaintainabilityReport {
   }
 
   static #problemOf(failure: MaintainabilityFailure) {
+    if (failure.kind === "staleTotal")
+      return `records ${failure.recorded} ${MaintainabilityReport.#units[failure.rule]} in all, above the ${failure.count} the code holds`;
     if (failure.kind === "baselineGrowth") {
       const entry = `entry "${failure.key}" under ${failure.debtRule}`;
       const units = MaintainabilityReport.#units[failure.debtRule];
+      if (failure.key === MaintainabilityBaseline.totalKey)
+        return `${failure.debtRule} allows ${failure.count} ${units} in all, above the ${failure.committed ?? 0} ${failure.measured ? `the code at ${failure.reference} holds with no entry for its rule recorded there` : `at ${failure.reference}`}; the baseline may only shrink`;
       if (failure.measured)
         return failure.committed === undefined
-          ? `${entry} is debt the code at ${failure.reference} does not hold, and with no baseline there the baseline may only shrink from that code`
-          : `${entry} allows ${failure.count} ${units}, above the ${failure.committed} the code at ${failure.reference} holds with no baseline there; the baseline may only shrink`;
+          ? `${entry} is debt the code at ${failure.reference} does not hold, and with no entry for its rule recorded there the baseline may only shrink from that code`
+          : `${entry} allows ${failure.count} ${units}, above the ${failure.committed} the code at ${failure.reference} holds with no entry for its rule recorded there; the baseline may only shrink`;
       return failure.committed === undefined
         ? `${entry} is not in the baseline at ${failure.reference}, which may only shrink`
         : `${entry} allows ${failure.count} ${units}, above the ${failure.committed} at ${failure.reference}; the baseline may only shrink`;
@@ -143,6 +155,10 @@ export class MaintainabilityReport {
     }
     if (failure.kind === "writePlacement")
       return `sends ${failure.writes.length} server write(s) from outside a store action or a module component: ${failure.writes.join(", ")}${grown}`;
+    if (failure.kind === "bareError") {
+      const plural = failure.lines.length === 1 ? "" : "s";
+      return `constructs or extends ${failure.lines.length} bare Error${plural}, on line${plural} ${failure.lines.join(", ")}${grown}, and the package's total grew`;
+    }
     if (failure.kind === "loopCall")
       return `service method ${failure.owner} calls once per item: ${failure.calls.join(", ")}${grown}`;
     if (failure.kind === "classSize")
@@ -163,6 +179,7 @@ export class MaintainabilityReport {
   }
 
   static #fixKeyOf(sysPath: string, failure: MaintainabilityFailure): FixKey {
+    if (failure.kind === "staleTotal") return "staleTotal";
     if (failure.rule !== "akan.size.file") return failure.rule;
     if (sysPath.startsWith("pkgs/")) return "package";
     return MaintainabilityLimits.fileKindOf(failure.file) ?? "akan.size.component";

package/moduleFieldNames.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { constantFieldNames, unlabeledFieldNames } from "./moduleFieldNames";
+
+describe("moduleFieldNames", () => {
+  test("names each field the code declares, chained or not", () => {
+    const content = `export class TaskInput extends via((field) => ({
+  title: field(String),
+  tags: field(String).list().optional(),
+  workHistory: field([WorkHistory]),
+})) {}
+export class TaskObject extends via(TaskInput, (field) => ({
+  due: field(Date).optional(),
+  total: resolve<number>(),
+})) {}
+`;
+
+    expect(constantFieldNames(content)).toEqual(["title", "tags", "workHistory", "due"]);
+  });
+
+  test("leaves out a field that appears only in a comment or a string", () => {
+    const content = `export class TaskInput extends via((field) => ({
+  title: field(String),
+  // priority: field(TaskPriority, { default: "medium" })
+  /* assignee: field(ID).optional() */
+  note: field(String, { default: "completedAt: field(Date)" }),
+})) {}
+// ---- Expandable additional fields: ----
+//  - actor: field(String).optional() — who performed the action
+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.0",
+  "version": "3.2.0-rc.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.0",
+    "@akanjs/language": "3.2.0-rc.10",
     "@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.0",
+    "akanjs": "3.2.0-rc.10",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewChrome.ts

@@ -12,12 +12,12 @@ export class PreviewChrome {
   /** Set this to drive Chrome on macOS too, e.g. to reproduce what a pod sees. */
   static readonly backendEnvKey = "AKAN_CODE_WEBVIEW_BACKEND";
 
-  /** The executables Bun looks for on PATH before giving up. */
+  /** The executables Bun looks for on PATH before giving up, in its order: the first found is the one it starts. */
   static readonly executables = [
-    "chromium",
-    "chromium-browser",
     "google-chrome-stable",
     "google-chrome",
+    "chromium-browser",
+    "chromium",
     "brave-browser",
     "microsoft-edge",
     "chrome",

package/preview/PreviewView.ts

@@ -5,7 +5,8 @@ export interface PreviewProbeOptions {
   width?: number;
   height?: number;
   engine?: PreviewEngine;
-  /** Bounds the whole probe: a dev server that is recovering takes the connection and never answers. */
+  startTimeoutMs?: number;
+  /** Bounds the probe once the browser is up: a dev server that is recovering takes the connection and never answers. */
   timeoutMs?: number;
   /** Waited after the load, so the errors effects throw land before the page is read. */
   settleMs?: number;
@@ -45,6 +46,10 @@ interface PageRead {
 // Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
 // It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
 export class PreviewView {
+  /** A view's first navigation includes the browser's start, which took ~35 s on a cold CI runner. */
+  static readonly startTimeoutMs = 120_000;
+  static readonly #stalled = new Set<PreviewEngine>();
+
   static get available() {
     return PreviewView.isAvailable();
   }
@@ -66,15 +71,25 @@ export class PreviewView {
       width = 1280,
       height = 800,
       engine = PreviewChrome.backend,
+      startTimeoutMs = PreviewView.startTimeoutMs,
       timeoutMs = 30_000,
       settleMs = 0,
     }: PreviewProbeOptions = {},
   ): Promise<PreviewProbeResult> {
     const logs: string[] = [];
-    const deadline = Date.now() + timeoutMs;
-    const within = <T>(work: Promise<T>, what: string) => PreviewView.#within(work, deadline, `${what} ${url}`);
-    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 {
+      const deadline = Date.now() + timeoutMs;
+      const within = <T>(work: Promise<T>, what: string) =>
+        PreviewView.#within(
+          work,
+          deadline,
+          new Error(`Timed out ${what} ${url}; the dev server may be rebuilding or stuck.`),
+        );
       let page = await PreviewView.#load(view, url, settleMs, within);
       //? Right after a save the first load can render nothing (`[rscClient] module not loaded`); the next one has it.
       if (page.empty) {
@@ -99,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,
@@ -126,13 +168,10 @@ export class PreviewView {
     return response?.status ?? null;
   }
 
-  static async #within<T>(work: Promise<T>, deadline: number, what: string): Promise<T> {
+  static async #within<T>(work: Promise<T>, deadline: number, expiry: Error): Promise<T> {
     let timer: ReturnType<typeof setTimeout> | undefined;
     const expired = new Promise<never>((_, reject) => {
-      timer = setTimeout(
-        () => reject(new Error(`Timed out ${what}; the dev server may be rebuilding or stuck.`)),
-        Math.max(0, deadline - Date.now()),
-      );
+      timer = setTimeout(() => reject(expiry), Math.max(0, deadline - Date.now()));
     });
     try {
       return await Promise.race([work, expired]);