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

package/frontendBuild/csrDevTypes.ts

@@ -1,11 +1,24 @@
 import type { PageEntry } from "../artifact/implicitRootLayout";
 
+export interface CsrDevNarrowedImport {
+  names: string[];
+  hash: string;
+}
+
+export interface CsrDevBarrelStamp {
+  /** The mtime of each file and directory the barrel's analysis read, by id. */
+  read: Record<string, number>;
+  /** Each export name with the file it resolves to, hashed: what every importer's narrowing reads. */
+  digest: string;
+}
+
 export interface CsrDevGraphModule {
   vendor: boolean;
   mtimeMs: number;
   hash: string;
   deps: string[];
   helpers?: string;
+  narrowed?: Record<string, CsrDevNarrowedImport>;
 }
 
 export interface CsrDevGraph {
@@ -22,6 +35,7 @@ export interface CsrDevGraph {
   failed?: { roots: string[]; files: Record<string, string> };
   /** The stamp of the signal and dictionary sources the last whole build inlined; see `RegistryMetadataFingerprint`. */
   metadata?: string;
+  barrels?: Record<string, CsrDevBarrelStamp>;
 }
 
 export interface CsrDevContext {
@@ -35,6 +49,7 @@ export interface CsrDevContext {
   refreshFile: string | null;
   /** Bare specifiers the page already loads (an SSR page's import map): required as `vendor:<specifier>`, not compiled. */
   externals?: readonly string[];
+  barrelImports?: readonly string[];
 }
 
 export interface CsrDevSharedHelpers {
@@ -52,6 +67,7 @@ export interface CsrDevCompiledModule {
   deps: string[];
   mtimeMs: number;
   hash: string;
+  narrowed?: Record<string, CsrDevNarrowedImport>;
 }
 
 /** Module factories by id and helper definitions by hash, kept in memory so app.js is written without a pass over the disk. */

package/frontendBuild/cssCompiler.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { declaredCustomProperties } from "./cssCompiler";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { CssCompiler, declaredCustomProperties } from "./cssCompiler";
+
+const makeTempRoot = tempDirs("akan-css-compiler-");
 
 describe("declaredCustomProperties", () => {
   test("names what the regex-based version named", () => {
@@ -51,3 +55,61 @@ describe("declaredCustomProperties", () => {
     }
   });
 });
+
+describe("CssCompiler.discoverCssAndSources", () => {
+  test("scans the files a page reaches through a client barrel's narrowed imports, never the barrel's other modules", async () => {
+    const root = await makeTempRoot();
+    const paths = { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] };
+    const writeSys = async (dir: string, modules: string[]) => {
+      await write(
+        path.join(dir, "client.ts"),
+        [
+          'export * as cnst from "./lib/cnst";',
+          'export { msg, usePage } from "./lib/useClient";',
+          'export { st, RootStore } from "./lib/st";',
+          ...modules.map((name) => `export { ${name} } from "./lib/${name.toLowerCase()}";`),
+          "",
+        ].join("\n"),
+      );
+      await write(path.join(dir, "lib/cnst.ts"), "export const Sample = 1;\n");
+      await write(path.join(dir, "lib/useClient.ts"), "export const msg = 1;\nexport const usePage = () => msg;\n");
+      for (const name of modules) {
+        await write(
+          path.join(dir, `lib/${name.toLowerCase()}/index.ts`),
+          `import * as Zone from "./${name}.Zone";\nexport const ${name} = { Zone };\n`,
+        );
+        await write(path.join(dir, `lib/${name.toLowerCase()}/${name}.Zone.tsx`), 'export const Card = () => "p-4";\n');
+      }
+    };
+    const appDir = path.join(root, "apps/demo");
+    await writeSys(appDir, ["Memo", "Other"]);
+    await writeSys(path.join(root, "libs/kit"), ["Widget"]);
+    await write(path.join(root, "libs/kit/lib/st.ts"), "export class RootStore {}\nexport const st = {};\n");
+    await write(
+      path.join(appDir, "lib/st.ts"),
+      'import { RootStore as kit } from "@libs/kit/client";\nexport class RootStore {}\nexport const st = { kit };\n',
+    );
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import { Memo, st } from "@apps/demo/client";\nexport default function Page() { return [Memo, st]; }\n',
+    );
+    const app = {
+      cwdPath: appDir,
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: { paths } }),
+      getConfig: async () => ({ barrelImports: ["@apps/demo/client", "@libs/kit/client"] }),
+    };
+
+    const { sourcePaths } = await new CssCompiler(app as never).discoverCssAndSources({ pageKeys: ["_index.tsx"] });
+
+    expect(sourcePaths.map((file) => path.relative(root, file)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "apps/demo/lib/memo/Memo.Zone.tsx",
+      "apps/demo/lib/memo/index.ts",
+      "apps/demo/lib/st.ts",
+      "apps/demo/lib/useClient.ts",
+      "apps/demo/page/_index.tsx",
+      "libs/kit/lib/st.ts",
+      "libs/kit/lib/useClient.ts",
+    ]);
+  });
+});

package/frontendBuild/devBarrelImports.ts

@@ -0,0 +1,132 @@
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { BarrelAnalyzer, type PackageEntry } from "../transforms/barrelAnalyzer";
+import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevBarrelStamp, CsrDevNarrowedImport } from "./csrDevTypes";
+
+export interface DevBarrelRewrite {
+  contents: string | null;
+  narrowed: Record<string, CsrDevNarrowedImport>;
+}
+
+//* Targets are written as relative paths, which resolve against the disk with no resolution build: a save that adds a
+//* barrel import stays a patch.
+export class DevBarrelImports {
+  readonly #barrels: string[];
+  readonly #resolvePackage: (pkgName: string) => Promise<PackageEntry | null>;
+  readonly #analyzer: BarrelAnalyzer;
+  readonly #packages = new Map<string, Promise<PackageEntry | null>>();
+
+  constructor(barrels: readonly string[], resolvePackage: (pkgName: string) => Promise<PackageEntry | null>) {
+    this.#barrels = [...barrels];
+    this.#resolvePackage = resolvePackage;
+    this.#analyzer = new BarrelAnalyzer({ resolvePackage });
+  }
+
+  static async create(app: App, barrels: readonly string[]): Promise<DevBarrelImports | null> {
+    if (barrels.length === 0) return null;
+    return new DevBarrelImports(barrels, await createTsconfigPackageResolver(app));
+  }
+
+  async rewrite(source: string, importer: string): Promise<DevBarrelRewrite | null> {
+    const named = this.#barrels.filter((barrel) => source.includes(barrel));
+    if (named.length === 0) return null;
+    const packages = await this.#packagesOf(named);
+    const from = path.dirname(CsrDevPaths.realpath(importer));
+    const names = new Map<string, Set<string>>();
+    const contents = await rewriteBarrelImports(source, named, this.#analyzer, {
+      keepLines: true,
+      specifierOf: (subpath) => DevBarrelImports.#relative(subpath, from, packages),
+      onImport: (barrel, imported) => names.set(barrel, new Set([...(names.get(barrel) ?? []), ...imported])),
+    });
+    const narrowed = await Promise.all(
+      [...names].map(async ([barrel, set]) => {
+        const sorted = [...set].sort();
+        return [barrel, { names: sorted, hash: await this.fingerprint(barrel, sorted) }] as const;
+      }),
+    );
+    return { contents, narrowed: Object.fromEntries(narrowed) };
+  }
+
+  //? Hashes what an import of these names alone narrows to, with each target as the file it resolves to: the same
+  //? names in another importer narrow to the same files, and only a moved export or a moved file changes it.
+  async fingerprint(barrel: string, names: string[]): Promise<string> {
+    const packages = await this.#packagesOf([barrel]);
+    const aliased = names.map((name, index) => `${name} as _${index}`).join(", ");
+    const narrowed = await rewriteBarrelImports(
+      `import { ${aliased} } from ${JSON.stringify(barrel)};`,
+      [barrel],
+      this.#analyzer,
+      { specifierOf: (subpath) => DevBarrelImports.#fileOf(subpath, packages) ?? subpath },
+    );
+    return Bun.hash(narrowed ?? "").toString(36);
+  }
+
+  async stamps(barrels: Iterable<string>, idOf: (file: string) => string): Promise<Record<string, CsrDevBarrelStamp>> {
+    const stamped = await Promise.all(
+      [...barrels].map(async (barrel) => {
+        const files = await this.#analyzer.filesOf(barrel);
+        const read = [...new Set([...files, ...files.map((file) => path.dirname(file))])];
+        const stamp: CsrDevBarrelStamp = {
+          read: Object.fromEntries(read.map((file) => [idOf(file), CsrDevPaths.mtimeOf(file)])),
+          digest: await this.#digest(barrel),
+        };
+        return [barrel, stamp] as const;
+      }),
+    );
+    return Object.fromEntries(stamped);
+  }
+
+  //? Every input of an importer's fingerprint: an importer is hashed again only once this moves, so a save that
+  //? changes a component's body costs one analysis of its barrel, whatever the number of importers.
+  async #digest(barrel: string): Promise<string> {
+    const map = await this.#analyzer.analyze(barrel);
+    const packages = await this.#packagesOf([barrel]);
+    const files = new Map<string, string>();
+    const fileOf = (subpath: string) => {
+      let file = files.get(subpath);
+      if (file === undefined) {
+        file = DevBarrelImports.#fileOf(subpath, packages) ?? subpath;
+        files.set(subpath, file);
+      }
+      return file;
+    };
+    const exports = [...(map ?? [])]
+      .map(([name, target]) => [name, target.originalName, !!target.namespace, fileOf(target.subpath)] as const)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Bun.hash(JSON.stringify([fileOf(barrel), map === null, exports])).toString(36);
+  }
+
+  async #packagesOf(barrels: string[]): Promise<PackageEntry[]> {
+    return (await Promise.all(barrels.map((barrel) => this.#packageOf(barrel))))
+      .filter((pkg): pkg is PackageEntry => pkg !== null)
+      .sort((a, b) => b.pkgName.length - a.pkgName.length);
+  }
+
+  #packageOf(barrel: string): Promise<PackageEntry | null> {
+    let pkg = this.#packages.get(barrel);
+    if (!pkg) {
+      pkg = this.#resolvePackage(barrel);
+      this.#packages.set(barrel, pkg);
+    }
+    return pkg;
+  }
+
+  static #fileOf(subpath: string, packages: PackageEntry[]): string | null {
+    const pkg = packages.find(({ pkgName }) => subpath === pkgName || subpath.startsWith(`${pkgName}/`));
+    if (!pkg) return null;
+    const file = CsrDevPaths.resolveOnDisk(path.join(pkg.pkgDir, subpath.slice(pkg.pkgName.length)));
+    return file ? CsrDevPaths.realpath(file) : null;
+  }
+
+  static #relative(subpath: string, from: string, packages: PackageEntry[]): string {
+    const file = DevBarrelImports.#fileOf(subpath, packages);
+    if (!file) return subpath;
+    const relative = path.relative(from, file);
+    //? A target on another Windows drive has no relative path: `path.relative` returns it absolute.
+    if (path.isAbsolute(relative)) return file.split(path.sep).join("/");
+    const posix = relative.split(path.sep).join("/");
+    return posix.startsWith("../") ? posix : `./${posix}`;
+  }
+}

package/frontendBuild/devRegistryBundler.ts

@@ -7,7 +7,8 @@ import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
 import { CsrDevPatcher } from "./csrDevPatcher";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevBarrelStamp, CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { DevBarrelImports } from "./devBarrelImports";
 import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
 import { WatchRootResolver } from "./watchRootResolver";
 
@@ -131,7 +132,7 @@ export abstract class DevRegistryBundler {
     const resolver = new CsrDevResolver({ paths: this.paths, context, entryFiles: roots });
     await resolver.prepass();
     const compiler = this.compiler(context, resolver);
-    const { modules: compiled } = await compiler.compile(
+    const { modules: compiled, barrels } = await compiler.compile(
       [...roots, ...(context.refreshFile ? [context.refreshFile] : [])],
       new Set(),
     );
@@ -147,7 +148,7 @@ export abstract class DevRegistryBundler {
       pending: [],
       metadata,
     };
-    this.merge(graph, resolver, compiled);
+    this.merge(graph, resolver, compiled, barrels);
     await this.writer.markBuilding();
     await this.writer.writeModules(compiled);
     const vendorFile = await this.writer.writeVendor(graph);
@@ -170,7 +171,16 @@ export abstract class DevRegistryBundler {
     });
   }
 
-  merge(graph: CsrDevGraph, resolver: CsrDevResolver, compiled: CsrDevCompiledModule[]): void {
+  async barrelImports(context: CsrDevContext): Promise<DevBarrelImports | null> {
+    return await DevBarrelImports.create(this.app, context.barrelImports ?? []);
+  }
+
+  merge(
+    graph: CsrDevGraph,
+    resolver: CsrDevResolver,
+    compiled: CsrDevCompiledModule[],
+    barrels: Record<string, CsrDevBarrelStamp> = {},
+  ): void {
     for (const module of compiled)
       graph.modules[module.id] = {
         vendor: module.vendor,
@@ -178,7 +188,12 @@ export abstract class DevRegistryBundler {
         hash: module.hash,
         deps: module.deps.map((dep) => (CsrDevPaths.isStub(dep) ? dep : this.paths.idOf(dep))),
         ...(module.helpers ? { helpers: module.helpers.hash } : {}),
+        ...(module.narrowed ? { narrowed: module.narrowed } : {}),
       };
+    const narrowing = new Set(Object.values(graph.modules).flatMap((module) => Object.keys(module.narrowed ?? {})));
+    graph.barrels = Object.fromEntries(
+      Object.entries({ ...graph.barrels, ...barrels }).filter(([barrel]) => narrowing.has(barrel)),
+    );
     //? Only what this round compiled leaves pending: a root another route's check failed on stays for its retry.
     const compiledIds = new Set(compiled.map((module) => module.id));
     graph.pending = graph.pending.filter((id) => !compiledIds.has(id));

package/frontendBuild/mcpAppViewBuilder.test.ts

@@ -177,6 +177,7 @@ describe("McpAppViewBuilder.build", () => {
       dist: { cwdPath: file("dist/apps/demo") },
       workspace: { workspaceRoot: root },
       getTsConfig: async () => ({ compilerOptions: {} }),
+      getConfig: async () => ({ barrelImports: [] }),
       getPublicEnv: () => ({}),
       logger: { warn: () => undefined },
     };
@@ -195,6 +196,72 @@ describe("McpAppViewBuilder.build", () => {
   });
 });
 
+describe("McpAppViewBuilder.build with an app barrel", () => {
+  test("narrows the app's client barrel to the module the trimmed page names, never another module's UI", async () => {
+    const root = await makeTempRoot();
+    const file = (rel: string) => path.join(root, rel);
+    const paths = { "@apps/*": ["./apps/*"] };
+    await write(file("tsconfig.json"), JSON.stringify({ compilerOptions: { baseUrl: ".", paths } }));
+    await write(
+      file("node_modules/akanjs/package.json"),
+      JSON.stringify({ name: "akanjs", exports: { "./webkit": "./webkit.ts" } }),
+    );
+    await write(
+      file("node_modules/akanjs/webkit.ts"),
+      "export const McpAppBoot = { run: (view: unknown) => console.info(view) };\n",
+    );
+    await write(
+      file("apps/demo/client.ts"),
+      [
+        'export { usePage } from "./lib/useClient";',
+        'export { st } from "./lib/st";',
+        'export { Memo } from "./lib/memo";',
+        'export { Report } from "./lib/report";',
+        "",
+      ].join("\n"),
+    );
+    await write(
+      file("apps/demo/lib/useClient.ts"),
+      'console.info("the client runtime loaded");\nexport const usePage = () => null;\n',
+    );
+    await write(file("apps/demo/lib/st.ts"), 'console.info("the store loaded");\nexport const st = null;\n');
+    await write(file("apps/demo/lib/memo/index.ts"), 'export const Memo = "a memo card";\n');
+    await write(
+      file("apps/demo/lib/report/index.ts"),
+      'console.info("the report module loaded");\nexport const Report = "a report card";\n',
+    );
+    await write(
+      file("apps/demo/page/home.tsx"),
+      [
+        'import { Memo, Report } from "@apps/demo/client";',
+        "const page = () => ({ app: (name: string, description: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, description, draw, render] }) });",
+        'export default page().app("showHome", "Show home.", () => Memo).render(() => Report);',
+      ].join("\n"),
+    );
+    const app = {
+      cwdPath: file("apps/demo"),
+      dist: { cwdPath: file("dist/apps/demo") },
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: { paths } }),
+      getConfig: async () => ({ barrelImports: ["@apps/demo/client"] }),
+      getPublicEnv: () => ({}),
+      logger: { warn: () => undefined },
+    };
+
+    await new McpAppViewBuilder(app as never, "build").build(
+      [{ key: "./home.tsx", moduleAbsPath: file("apps/demo/page/home.tsx") }],
+      { basePaths: [], cssAssets: {}, options: CsrArtifactBuilder.bundleOptions(app as never, "build") },
+    );
+
+    const view = await Bun.file(file("dist/apps/demo/mcp-apps/showHome.html")).text();
+    expect(view).toContain("a memo card");
+    expect(view).toContain("the client runtime loaded");
+    expect(view).toContain("the store loaded");
+    expect(view).not.toContain("a report card");
+    expect(view).not.toContain("the report module loaded");
+  });
+});
+
 describe("McpAppViewBuilder.entryOf", () => {
   test("boots the one app with its page, the root layout and overrides it sits under, by relative path", () => {
     const view = {

package/frontendBuild/ssrDevBundler.ts

@@ -5,6 +5,7 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex } from "../artifact/routeSeedIndex";
 import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
+import { workspaceBarrels } from "../transforms/barrelImportsPlugin";
 import { bundleDefine } from "./bundleDefine";
 import type { ClientEntryDiscovery } from "./clientBuildTypes";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
@@ -17,7 +18,7 @@ import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
 //* (the app's client runtime) and every `"use client"` entry; React and the akanjs vendor facets stay the import map's,
 //* so the page keeps one React and one store registry.
 export class SsrDevBundler extends DevRegistryBundler {
-  static readonly #formatVersion = 2;
+  static readonly #formatVersion = 4;
   static readonly bootstrapKey = "";
   readonly reloadsOnEntryChange = false;
   #discovery: ClientEntryDiscovery | null = null;
@@ -33,8 +34,17 @@ export class SsrDevBundler extends DevRegistryBundler {
     const akanConfig = await this.app.getConfig();
     const define = bundleDefine(this.app, "start", "ssr");
     const optimizeImports = [...akanConfig.optimizeImports];
+    const barrelImports = workspaceBarrels(akanConfig.barrelImports);
     const configKey = Bun.hash(
-      JSON.stringify(["ssr", SsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, VENDOR_SPECIFIERS]),
+      JSON.stringify([
+        "ssr",
+        SsrDevBundler.#formatVersion,
+        Bun.version,
+        define,
+        optimizeImports,
+        VENDOR_SPECIFIERS,
+        barrelImports,
+      ]),
     ).toString(36);
     return {
       pageEntries: [],
@@ -45,6 +55,7 @@ export class SsrDevBundler extends DevRegistryBundler {
       configKey,
       refreshFile: null,
       externals: VENDOR_SPECIFIERS,
+      barrelImports,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.0",
+  "version": "3.2.0-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.0",
+    "@akanjs/language": "3.2.0-rc.2",
     "@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.2",
     "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,31 @@ 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) });
     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(
+          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) {
@@ -126,13 +147,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]);

package/preview/previewView.test.ts

@@ -1,9 +1,42 @@
 import { describe, expect, test } from "bun:test";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { PreviewChrome } from "./PreviewChrome";
 import { PreviewView } from "./PreviewView";
 
 const serve = (html: string, status = 200) =>
   Bun.serve({ port: 0, fetch: () => new Response(html, { status, headers: { "content-type": "text/html" } }) });
 
+const browserTestMs = PreviewView.startTimeoutMs + 30_000;
+const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !== "win32";
+
+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`);
+  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.
+  const child = Bun.spawn([process.execPath, "-e", script], {
+    env: { ...process.env, [PreviewChrome.pathEnvKey]: chrome },
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: PreviewView.startTimeoutMs + 15_000,
+  });
+  try {
+    const [out, err, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, out: out.trim(), err };
+  } finally {
+    child.kill();
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
 describe("PreviewView", () => {
   test("reports whether this Bun build can drive a headless page at all", () => {
     expect(typeof PreviewView.available).toBe("boolean");
@@ -29,7 +62,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -56,7 +89,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -71,6 +104,57 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "starts the page's bound once the browser is up, however long Chrome takes to spawn",
+    async () => {
+      const server = serve("<!doctype html><title>Up</title><body>up</body>");
+      try {
+        const { code, out, err } = 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);
+      } finally {
+        server.stop(true);
+      }
+    },
+    browserTestMs,
+  );
+
+  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 open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+console.log(await open());
+let late = await open();
+for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+console.log(late);
+Bun.WebView.closeAll();
+await Bun.sleep(500);
+console.log(await open());
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out || err).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1 s.",
+          "opened",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code).toBe(0);
+    },
+    browserTestMs,
   );
 });