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

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/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/precompressArtifacts.ts

@@ -22,7 +22,7 @@ export interface PrecompressArtifactsResult {
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  //* WebRouter serves client/, styles/ and dict/ through the same sidecar-aware #fileResponse.
+  //* WebRouter serves client/, styles/ and dict/ through the same sidecar-aware WebRouteContext.fileResponse.
   const artifactDir = path.join(app.dist.cwdPath, ".akan/artifact");
   const roots = [
     { root: path.join(artifactDir, "client") },

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/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/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

@@ -68,6 +68,31 @@ describe("IncrementalBuilderHost", () => {
     host.stop();
   });
 
+  test("a stop while a restart is pending leaves the builder down once the delay passes", async () => {
+    const { spawns, host } = startRecordingHost();
+    spawns[0]?.options.onExit?.();
+    expect(host.status).toBe("restarting");
+
+    host.stop();
+    await wait(1_050);
+    expect(spawns).toHaveLength(1);
+    expect(host.status).toBe("stopped");
+  });
+
+  test("a builder that crashes again after coming back ready waits the first delay again", async () => {
+    const { spawns, host } = startRecordingHost();
+    spawns[0]?.options.onExit?.();
+    await wait(1_050);
+    expect(spawns).toHaveLength(2);
+
+    spawns[1]?.options.ipc?.({ type: "builder-ready" });
+    spawns[1]?.options.onExit?.();
+    await wait(1_050);
+    expect(spawns).toHaveLength(3);
+
+    host.stop();
+  });
+
   test("recycles a ready builder gracefully and replaces it immediately", async () => {
     const spawns = mockSpawns();
     const onRestartReady = mock();
@@ -123,18 +148,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 +187,7 @@ describe("IncrementalBuilderHost", () => {
         id: 1,
         ok: false,
         error: "builder exited unexpectedly before answering; reload once it is back",
+        kind: "unavailable",
       },
     ]);
 
@@ -168,7 +197,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

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { Logger } from "akanjs/common";
+import { Logger, RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuilderRequest } from "akanjs/server";
 import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
@@ -49,8 +49,6 @@ interface IncrementalBuilderStartOptions {
 }
 
 export class IncrementalBuilderHost {
-  static readonly #restartBaseDelayMs = 1_000;
-  static readonly #restartMaxDelayMs = 30_000;
   static readonly #recycleDrainTimeoutMs = 30_000;
   // apps/akan's builder peaks near 950MB holding the SSR registry's patcher through a route build, and arming CSR adds
   // a second patcher: this recycles only a builder grown well past both.
@@ -65,8 +63,7 @@ export class IncrementalBuilderHost {
   readonly #onOutput: ((kind: "stdout" | "stderr", text: string) => void) | null;
   #proc: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #status: IncrementalBuilderStatus = "stopped";
-  #restartAttempts = 0;
-  #restartTimer: ReturnType<typeof setTimeout> | null = null;
+  readonly #restart = new RestartSchedule({ min: 1_000, max: 30_000 });
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
@@ -136,7 +133,7 @@ export class IncrementalBuilderHost {
         if (msg.type === "builder-ready" && !this.ready) {
           this.ready = true;
           this.#status = "ready";
-          this.#restartAttempts = 0;
+          this.#restart.reset();
           if (isRestart) this.#startOptions.onRestartReady?.();
           else this.#startOptions.onReady?.();
         }
@@ -210,20 +207,13 @@ export class IncrementalBuilderHost {
     }
   }
   #scheduleRestart() {
-    if (this.#manualStop || this.#restartTimer) return;
+    if (this.#manualStop || this.#restart.pending) return;
     this.#status = "restarting";
-    const attempt = this.#restartAttempts;
-    const delay = Math.min(
-      IncrementalBuilderHost.#restartBaseDelayMs * 2 ** attempt,
-      IncrementalBuilderHost.#restartMaxDelayMs,
-    );
-    this.#restartAttempts = attempt + 1;
-    this.logger.warn(`builder exited after ready; restarting in ${delay}ms (attempt ${this.#restartAttempts})`);
-    this.#restartTimer = setTimeout(() => {
-      this.#restartTimer = null;
+    const delay = this.#restart.schedule(() => {
       if (this.#manualStop) return;
       this.#spawn(true);
-    }, delay);
+    });
+    this.logger.warn(`builder exited after ready; restarting in ${delay}ms (attempt ${this.#restart.attempts})`);
   }
   /** Drain-and-exit rather than `kill()`, so no rebuild is truncated; false when the request was not sent. */
   recycle(reason: string): boolean {
@@ -287,16 +277,14 @@ 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;
     this.#clearRecycle();
     this.#failInFlight("builder was stopped before answering");
-    if (this.#restartTimer) {
-      clearTimeout(this.#restartTimer);
-      this.#restartTimer = null;
-    }
+    this.#restart.cancel();
     if (this.#proc) this.#proc.kill();
     this.#proc = null;
     this.ready = false;

package/lint/__fixtures__/no-import-common-err/bad.tsx

@@ -0,0 +1,13 @@
+import { Err } from "akanjs/common"; // @flag
+import { Err as Aliased } from "akanjs/common"; // @flag
+import { Err as Mixed, Logger } from "akanjs/common"; // @flag
+import { type ErrPayload, Err as MixedWithType } from "akanjs/common"; // @flag
+import { Err as SingleQuoted } from 'akanjs/common'; // @flag
+import { Err as DeepWithExtension } from "akanjs/common/err.ts"; // @flag
+import { Err as ThroughIndex } from "akanjs/common/index.ts"; // @flag
+import {
+  hasErrKey,
+  Err as MultiLine, // @flag
+} from "akanjs/common";
+export { Err as Reexported } from "akanjs/common"; // @flag
+export { Err as DeepReexported } from "akanjs/common/err.ts"; // @flag

package/lint/__fixtures__/no-import-common-err/good.tsx

@@ -0,0 +1,12 @@
+import { Err } from "../dict"; // @ok
+import { Err as ClientErr } from "@libs/shared/client"; // @ok
+import { Err as AppErr } from "@apps/demo/client"; // @ok
+import type { Err as TypeOnly } from "akanjs/common"; // @ok
+import { type Err as InlineType, Logger } from "akanjs/common"; // @ok
+import type { Err as DeepType } from "akanjs/common/err.ts"; // @ok
+import { hasErrKey } from "akanjs/common"; // @ok
+import type { ErrConstructor, ErrPayload } from "akanjs/common"; // @ok
+import { Err as NearName } from "akanjs/common/hasErrKey.ts"; // @ok
+export type { Err as ReexportedType } from "akanjs/common"; // @ok
+export { Logger as Log } from "akanjs/common"; // @ok
+export const quotesTheRule = 'import { Err } from "akanjs/common"'; // @ok