@akanjs/devkit 3.2.0-rc.1 → 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.1",
+  "version": "3.2.0-rc.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.1",
+    "@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.1",
+    "akanjs": "3.2.0-rc.10",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewView.ts

@@ -77,18 +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.
-      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);
-          throw error;
-        },
-      );
       const deadline = Date.now() + timeoutMs;
       const within = <T>(work: Promise<T>, what: string) =>
         PreviewView.#within(
@@ -120,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

@@ -14,7 +14,12 @@ const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !==
 const withSlowChrome = async (body: string, startSeconds = 3) => {
   const dir = await mkdtemp(path.join(tmpdir(), "akan-slow-chrome-"));
   const chrome = path.join(dir, "chrome");
-  await writeFile(chrome, `#!/bin/sh\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`);
+  const chromeLog = path.join(dir, "chrome.log");
+  //? Bun.WebView sends the browser's stderr to /dev/null, which would hide why it died.
+  await writeFile(
+    chrome,
+    `#!/bin/sh\nexec 2>>"${chromeLog}"\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`,
+  );
   await chmod(chrome, 0o755);
   const script = `const { PreviewView } = await import(${JSON.stringify(path.join(import.meta.dir, "PreviewView.ts"))});\n${body}`;
   //? Chrome is spawned once per process, so only a fresh process takes the slow executable.
@@ -30,7 +35,10 @@ const withSlowChrome = async (body: string, startSeconds = 3) => {
       new Response(child.stderr).text(),
       child.exited,
     ]);
-    return { code, out: out.trim(), err };
+    const chromeErr = await Bun.file(chromeLog)
+      .text()
+      .catch(() => "");
+    return { code, out: out.trim(), log: `${err}\nChrome's stderr:\n${chromeErr}` };
   } finally {
     child.kill();
     await rm(dir, { recursive: true, force: true });
@@ -112,12 +120,12 @@ describe("PreviewView", () => {
     async () => {
       const server = serve("<!doctype html><title>Up</title><body>up</body>");
       try {
-        const { code, out, err } = await withSlowChrome(
+        const { code, out, log } = await withSlowChrome(
           `const probe = await PreviewView.probe("http://localhost:${server.port}/", { engine: "chrome", timeoutMs: 1_500 });
 console.log(probe.text);`,
         );
-        expect(out || err).toBe("up");
-        expect(code).toBe(0);
+        expect(out, log).toBe("up");
+        expect(code, log).toBe(0);
       } finally {
         server.stop(true);
       }
@@ -128,7 +136,7 @@ console.log(probe.text);`,
   test.skipIf(!slowChromeRuns)(
     "gives a later page only its own bound for a browser that missed its start, and recovers once it is up",
     async () => {
-      const { code, out, err } = await withSlowChrome(
+      const { code, out, log } = await withSlowChrome(
         `const open = () =>
   PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
     () => "opened",
@@ -137,7 +145,7 @@ console.log(probe.text);`,
 console.log(await open());
 console.log(await open());
 let late = await open();
-for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+for (let tries = 0; late.startsWith("Timed out starting") && tries < 100; tries++) late = await open();
 console.log(late);
 Bun.WebView.closeAll();
 await Bun.sleep(500);
@@ -145,7 +153,7 @@ console.log(await open());
 Bun.WebView.closeAll();`,
         6,
       );
-      expect(out || err).toBe(
+      expect(out, log).toBe(
         [
           "Timed out starting the chrome browser after 1.5 s.",
           "Timed out starting the chrome browser after 1 s.",
@@ -153,7 +161,66 @@ Bun.WebView.closeAll();`,
           "Timed out starting the chrome browser after 1.5 s.",
         ].join("\n"),
       );
-      expect(code).toBe(0);
+      expect(code, log).toBe(0);
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "gives a browser killed after it missed its start the full bound for its next start",
+    async () => {
+      const { code, out, log } = await withSlowChrome(
+        `const open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+const killed = open();
+Bun.WebView.closeAll();
+console.log(await killed);
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out, log).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code, log).toBe(0);
+    },
+    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,
   );