@akanjs/devkit 2.4.1-rc.1 → 2.4.1-rc.3

package/akanApp/akanApp.host.test.ts

@@ -4,14 +4,17 @@ import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
+  decideBuilderRssRecycle,
   hasBuildFailureForGeneration,
   isLegacyBackendFallbackFile,
   mergeBackendRestartReasons,
   mergeInvalidateMessages,
   normalizeBackendReportedGeneration,
   shouldAbandonBackendRecovery,
+  shouldAbandonBuilderRssCeiling,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
+  shouldRelayRecycledFrontendState,
   shouldReplaceLastGoodMessage,
   shouldRestartBackendByDevPlan,
   shouldRestartBuilderByDevPlan,
@@ -141,6 +144,87 @@ describe("last-good frontend helpers", () => {
   });
 });
 
+describe("builder rss recycle", () => {
+  const ceiling = 1_200 * 1024 * 1024;
+  const decide = (over: Partial<Parameters<typeof decideBuilderRssRecycle>[0]>) =>
+    decideBuilderRssRecycle({
+      rssBytes: ceiling + 1,
+      ceilingBytes: ceiling,
+      buildFailed: false,
+      msSinceLastRecycle: null,
+      ...over,
+    });
+
+  test("recycles an idle builder that crossed the ceiling", () => {
+    expect(decide({})).toBe("recycle");
+  });
+
+  test("leaves a builder under the ceiling alone", () => {
+    expect(decide({ rssBytes: ceiling - 1 })).toBe("below-ceiling");
+  });
+
+  test("does nothing when no ceiling is configured", () => {
+    expect(decide({ ceilingBytes: null })).toBe("unbounded");
+  });
+
+  // Rebooting on a generation whose build failed strands the dev server: the replacement hits the
+  // same compile error and exits before builder-ready.
+  test("defers while the current generation has a failing build", () => {
+    expect(decide({ buildFailed: true })).toBe("build-failed");
+  });
+
+  test("refuses a second recycle inside the minimum interval", () => {
+    expect(decide({ msSinceLastRecycle: 5_000 })).toBe("too-soon");
+    expect(decide({ msSinceLastRecycle: 31_000 })).toBe("recycle");
+    expect(decide({ msSinceLastRecycle: 5_000, minIntervalMs: 1_000 })).toBe("recycle");
+  });
+
+  // An app whose fresh boot is already over the ceiling would otherwise be recycled forever.
+  test("abandons the ceiling once recycling stops buying relief", () => {
+    expect(shouldAbandonBuilderRssCeiling(1)).toBe(false);
+    expect(shouldAbandonBuilderRssCeiling(2)).toBe(true);
+    expect(shouldAbandonBuilderRssCeiling(1, 1)).toBe(true);
+  });
+});
+
+describe("recycled builder state announcements", () => {
+  const pages = (bundlePath: string): Extract<BuilderMessage, { type: "pages-updated" }> => ({
+    type: "pages-updated",
+    data: { bundlePath, buildId: 7, generation: 3, changedFiles: [], reason: "builder-recycle" },
+  });
+  const css = (cssUrl: string): Extract<BuilderMessage, { type: "css-updated" }> => ({
+    type: "css-updated",
+    data: {
+      cssAssets: { "": { cssUrl, cssRelPath: cssUrl.slice(1) } },
+      cssBase64ByUrl: { [cssUrl]: "" },
+      generation: 3,
+      changedFiles: [],
+      reason: "builder-recycle",
+    },
+  });
+
+  // Both identities are content hashes, so a recycle with no concurrent edit reproduces them exactly
+  // and must not reload the backend — that would refresh every browser on a memory recycle.
+  test("suppresses an unchanged pages announcement and relays a moved one", () => {
+    expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-abc.js"))).toBe(false);
+    expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-def.js"))).toBe(true);
+  });
+
+  test("suppresses an unchanged css announcement and relays a moved one", () => {
+    expect(shouldRelayRecycledFrontendState(css("/_akan/styles/root-abc.css"), css("/_akan/styles/root-abc.css"))).toBe(
+      false,
+    );
+    expect(shouldRelayRecycledFrontendState(css("/_akan/styles/root-abc.css"), css("/_akan/styles/root-def.css"))).toBe(
+      true,
+    );
+  });
+
+  test("relays when the backend has no state of that kind yet", () => {
+    expect(shouldRelayRecycledFrontendState(undefined, pages("/a/pages-abc.js"))).toBe(true);
+    expect(shouldRelayRecycledFrontendState(css("/_akan/styles/root-abc.css"), pages("/a/pages-abc.js"))).toBe(true);
+  });
+});
+
 describe("build status helpers", () => {
   const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
     generation,

package/akanApp/akanApp.host.ts

@@ -1,6 +1,13 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangePlan, DevChangeRole } from "akanjs/server";
+import type {
+  BuilderMessage,
+  BuilderMetrics,
+  BuildPhase,
+  DevBuildStatus,
+  DevChangePlan,
+  DevChangeRole,
+} from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
@@ -17,6 +24,11 @@ const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
+// Save-on-keystroke arrives as a burst of batches. Recycling mid-burst would drop the watcher events
+// still on their way to the builder, so an over-ceiling builder is replaced only once it goes quiet.
+const BUILDER_RSS_RECYCLE_QUIET_MS = 750;
+const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
+const BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT = 2;
 // The builder is the file watcher: while it is down no edit can trigger a retry, so unlike the
 // backend the recovery loop never gives up — it only backs off.
 const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
@@ -177,6 +189,68 @@ export const hasBuildFailureForGeneration = (
   return false;
 };
 
+export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
+
+/**
+ * Whether an over-ceiling builder should be replaced now.
+ *
+ * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
+ * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
+ * cases where a recycle cannot help are excluded: a generation whose build already failed (the
+ * replacement would hit the same compile error), and a recycle so soon after the last one that the
+ * ceiling is evidently unreachable for this app.
+ */
+export const decideBuilderRssRecycle = ({
+  rssBytes,
+  ceilingBytes,
+  buildFailed,
+  msSinceLastRecycle,
+  minIntervalMs = BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+}: {
+  rssBytes: number;
+  ceilingBytes: number | null;
+  buildFailed: boolean;
+  msSinceLastRecycle: number | null;
+  minIntervalMs?: number;
+}): BuilderRssRecycleDecision => {
+  if (!ceilingBytes) return "unbounded";
+  if (rssBytes < ceilingBytes) return "below-ceiling";
+  if (buildFailed) return "build-failed";
+  if (msSinceLastRecycle !== null && msSinceLastRecycle < minIntervalMs) return "too-soon";
+  return "recycle";
+};
+
+/**
+ * A builder whose fresh boot already exceeds the ceiling reports `too-soon` after every recycle and
+ * would be replaced forever without ever getting under it. After this many recycles bought no relief
+ * the host stops enforcing the ceiling and says so, rather than looping.
+ */
+export const shouldAbandonBuilderRssCeiling = (
+  ineffectiveRecycles: number,
+  limit = BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT,
+): boolean => ineffectiveRecycles >= limit;
+
+/**
+ * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
+ * already has. Both payload identities are content hashes — `pages-[hash].js` and
+ * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
+ * save that raced the recycle moves them, and that is the case worth pushing.
+ */
+export const shouldRelayRecycledFrontendState = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => {
+  if (!current || current.type !== next.type) return true;
+  if (current.type === "pages-updated" && next.type === "pages-updated")
+    return current.data.bundlePath !== next.data.bundlePath;
+  if (current.type === "css-updated" && next.type === "css-updated")
+    return JSON.stringify(current.data.cssAssets) !== JSON.stringify(next.data.cssAssets);
+  return true;
+};
+
 const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChangePlan | undefined => {
   if (!current) return next;
   if (!next) return current;
@@ -344,6 +418,11 @@ export class AkanAppHost {
   #backendBuildStatusGeneration = 0;
   #backendStderrTail: string[] = [];
   #lastGoodFrontend: LastGoodFrontendState = {};
+  #rssRecycleTimer: ReturnType<typeof setTimeout> | null = null;
+  #rssRecycleReason: string | null = null;
+  #lastRssRecycleAtMono: number | null = null;
+  #rssCeilingIneffective = 0;
+  #rssCeilingAbandoned = false;
   #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
   #pendingBuildStatusReplay: DevBuildStatus[] = [];
   #builderMessageQueue: Promise<void> = Promise.resolve();
@@ -642,16 +721,105 @@ export class AkanAppHost {
       this.#reviveBackendAfterGreenBuild(message.data);
       return;
     }
-    if (message.type === "pages-updated") this.#recordLastGood(message);
-    if (message.type === "css-updated") this.#recordLastGood(message);
+    if (message.type === "builder-metrics") {
+      this.#handleBuilderMetrics(message.data);
+      return;
+    }
+    if (message.type === "pages-updated" || message.type === "css-updated") {
+      const recycled = message.data.reason === "builder-recycle";
+      if (recycled && !this.#shouldRelayRecycledState(message)) return;
+      this.#recordLastGood(message, { supersede: recycled });
+    }
     if (message.type === "invalidate") {
       await this.#handleInvalidate(message);
       return;
     }
     this.#sendToBackend(message);
   }
+  /**
+   * A recycled builder re-announces the artifact it booted with, because the backend read
+   * `base-artifact.json` once and never re-reads it. Dropping the announcement when the hashes match
+   * is what keeps the common case — a recycle with no concurrent edit — invisible to browsers.
+   */
+  #shouldRelayRecycledState(
+    message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+  ): boolean {
+    const current = message.type === "pages-updated" ? this.#lastGoodFrontend.pages : this.#lastGoodFrontend.css;
+    if (shouldRelayRecycledFrontendState(current, message)) {
+      this.logger.verbose(`[builder-recycle] ${message.type} moved during the recycle; pushing it to the backend`);
+      return true;
+    }
+    this.logger.verbose(`[builder-recycle] ${message.type} unchanged after the recycle; backend left as is`);
+    return false;
+  }
+  #handleBuilderMetrics(metrics: BuilderMetrics): void {
+    if (this.#rssCeilingAbandoned) return;
+    const ceilingBytes = IncrementalBuilderHost.maxRssBytes();
+    const asMib = (bytes: number) => Math.round(bytes / 1024 / 1024);
+    const decision = decideBuilderRssRecycle({
+      rssBytes: metrics.rssBytes,
+      ceilingBytes,
+      buildFailed: hasBuildFailureForGeneration(this.#buildStatusByPhase, metrics.generation),
+      msSinceLastRecycle: this.#lastRssRecycleAtMono === null ? null : performance.now() - this.#lastRssRecycleAtMono,
+    });
+    if (decision === "below-ceiling") {
+      this.#rssCeilingIneffective = 0;
+      return;
+    }
+    if (decision === "unbounded") return;
+    if (decision === "build-failed") {
+      this.logger.verbose(
+        `[builder-recycle] deferred: generation=${metrics.generation} has a failing build, so a replacement would hit the same error`,
+      );
+      return;
+    }
+    if (decision === "too-soon") {
+      this.#rssCeilingIneffective += 1;
+      if (!shouldAbandonBuilderRssCeiling(this.#rssCeilingIneffective)) return;
+      this.#rssCeilingAbandoned = true;
+      this.logger.error(
+        `[builder-recycle] the builder is still at ${asMib(metrics.rssBytes)}MiB right after being recycled, so the ${asMib(ceilingBytes ?? 0)}MiB ceiling cannot be met for this app; no longer enforcing it this session. Raise AKAN_BUILDER_MAX_RSS_MB, or set it to 0 to leave the builder unbounded.`,
+      );
+      return;
+    }
+    this.#armRssRecycle(
+      `rss=${asMib(metrics.rssBytes)}MiB>=${asMib(ceilingBytes ?? 0)}MiB after ${metrics.workCount} build(s)`,
+    );
+  }
+  /** Waits for the builder to go quiet, so a recycle never lands in the middle of a burst of saves. */
+  #armRssRecycle(reason: string): void {
+    if (this.#rssRecycleReason !== reason)
+      this.logger.verbose(`[builder-recycle] armed (${reason}); replacing the builder once it stays quiet`);
+    this.#rssRecycleReason = reason;
+    if (this.#rssRecycleTimer) clearTimeout(this.#rssRecycleTimer);
+    this.#rssRecycleTimer = setTimeout(() => {
+      this.#rssRecycleTimer = null;
+      const pendingReason = this.#rssRecycleReason;
+      this.#rssRecycleReason = null;
+      if (pendingReason) this.#recycleBuilderForRss(pendingReason);
+    }, BUILDER_RSS_RECYCLE_QUIET_MS);
+  }
+  #cancelRssRecycle(): void {
+    this.#rssRecycleReason = null;
+    if (!this.#rssRecycleTimer) return;
+    clearTimeout(this.#rssRecycleTimer);
+    this.#rssRecycleTimer = null;
+  }
+  #recycleBuilderForRss(reason: string): void {
+    // A config or runtime-metadata change already replaces the builder along with the backend, and a
+    // pending backend restart is disruption enough on its own; either way, dropping the recycle here
+    // costs nothing — the next build re-reports an over-ceiling rss and arms it again.
+    if (this.#pendingRecycle || this.#restartTimer) {
+      this.logger.verbose(`[builder-recycle] skipped (${reason}); a dev restart is already pending`);
+      return;
+    }
+    if (!this.#builder?.recycle(reason)) return;
+    this.#lastRssRecycleAtMono = performance.now();
+  }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
     this.#logDevPlan(message);
+    // More batches are on the way, so push the recycle out until the dev server settles.
+    if (this.#rssRecycleReason) this.#armRssRecycle(this.#rssRecycleReason);
     // Config changes subsume builder restarts: the dev-host restart recycles builder and backend
     // AND re-runs the prepare step, so check it first when a batch carries both actions.
     const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
@@ -811,18 +979,25 @@ export class AkanAppHost {
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
   }
+  /**
+   * `supersede` bypasses the generation check for a builder that just replaced another one. Its
+   * generation counter restarts at 0, so its announcement looks stale to `shouldReplaceLastGoodMessage`
+   * — and leaving the old payload cached would make the next backend restart replay an artifact the
+   * builder that produced it no longer serves.
+   */
   #recordLastGood(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+    { supersede = false }: { supersede?: boolean } = {},
   ): void {
     if (message.type === "pages-updated") {
-      if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
+      if (!supersede && !shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
       this.#lastGoodFrontend.pages = message;
       this.logger.verbose(
         `[last-good] pages generation=${message.data.generation ?? "(unknown)"} buildId=${message.data.buildId}`,
       );
       return;
     }
-    if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
+    if (!supersede && !shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
     this.#lastGoodFrontend.css = message;
     this.logger.verbose(
       `[last-good] css generation=${message.data.generation ?? "(unknown)"} assets=${Object.keys(message.data.cssAssets).length}`,
@@ -985,6 +1160,7 @@ export class AkanAppHost {
     this.logger.warn("akanAppHost builder is not running");
   }
   #stopBuilder(): void {
+    this.#cancelRssRecycle();
     if (!this.#builder) return;
     this.#builder.stop();
     this.#builder = null;

package/incrementalBuilder/buildBatch.proc.ts

@@ -0,0 +1,194 @@
+import path from "node:path";
+import type { App } from "@akanjs/devkit/commandDecorators";
+// Subpath imports only, and as few as possible: this process is spawned once per generation, so every
+// eager import is paid on every save. Measured on a 177-route app: `executors` 24ms, `frontendBuild`
+// ~110ms, app config 5ms.
+import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
+import { CsrArtifactBuilder, CssCompiler, FontOptimizer, PagesBundleBuilder } from "@akanjs/devkit/frontendBuild";
+import { Logger } from "akanjs/common";
+import type { BuilderMessage, BuildPhase } from "akanjs/server";
+import type { BuildBatchRequest, BuildBatchResult, OptimizedFonts, PagesBatchCssAssets } from "./buildBatchProtocol";
+
+/**
+ * One generation of frontend build work, in a process that exits when it is done.
+ *
+ * This exists for one reason: `Bun.build` retains native bundler arenas that the process never returns
+ * to the OS — `Bun.gc(true)` reclaims nothing and the JS heap stays flat while RSS climbs ~250MB per
+ * save. Exit is the only mechanism that gives that memory back, so the work that scales per save lives
+ * here rather than in the long-lived watcher.
+ *
+ * Nothing is cached here, by design. That costs less than it appears to: `CssCompiler` rebuilds its
+ * tailwind compilers on every `compileCss` call, and the watcher always asked for `refresh: true`, so
+ * there was no warm state to lose. What genuinely had to be preserved travels in the request — the
+ * validated page keys and the previous font optimization.
+ */
+class BuildBatch {
+  #logger = new Logger("BuildBatch");
+  #request: BuildBatchRequest;
+  #app: App;
+  #result: BuildBatchResult;
+  constructor(request: BuildBatchRequest, app: App) {
+    this.#request = request;
+    this.#app = app;
+    this.#result = { generation: request.generation, errors: {} };
+  }
+
+  async run(): Promise<BuildBatchResult> {
+    // Ordered the way the watcher used to run them: csr before pages so a csr failure cannot delay the
+    // pages bundle the browser is waiting on, and css last because it depends on the rebuilt client.
+    if (this.#request.needs.includes("csr")) await this.#buildCsr();
+    if (this.#request.needs.includes("pages")) await this.#buildPages();
+    if (this.#request.needs.includes("css")) await this.#buildCss();
+    return this.#result;
+  }
+
+  /**
+   * Broadcast as soon as a need finishes rather than when the batch does. The browser is waiting on the
+   * pages bundle; making it wait for the css compile behind it would add latency the in-process version
+   * never had, and it would move every artifact write into the window right before the watcher reports
+   * the generation complete — which is where a save issued immediately afterwards gets dropped by Bun's
+   * recursive `fs.watch` (`local/optimize-resource/06-watcher-dropped-event.md`).
+   */
+  #emit(message: BuilderMessage): void {
+    process.send?.(message);
+  }
+
+  #emitStatus(phase: BuildPhase, message?: string): void {
+    this.#emit({
+      type: "build-status",
+      data: {
+        generation: this.#request.generation,
+        phase,
+        ok: !message,
+        files: this.#request.changedFiles,
+        message,
+      },
+    });
+  }
+
+  async #buildCsr(): Promise<void> {
+    const started = Date.now();
+    try {
+      await new CsrArtifactBuilder(this.#app).build();
+      this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
+      this.#emitStatus("csr");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.#logger.error(`csr-rebundle failed: ${message}`);
+      this.#result.errors.csr = message;
+      this.#emitStatus("csr", message);
+    }
+  }
+
+  async #buildPages(): Promise<void> {
+    const started = Date.now();
+    try {
+      const next = await new PagesBundleBuilder(this.#app).build();
+      this.#emit({
+        type: "pages-updated",
+        data: {
+          bundlePath: next.bundlePath,
+          buildId: next.buildId,
+          generation: this.#request.generation,
+          changedFiles: this.#request.changedFiles,
+        },
+      });
+      this.#emitStatus("pages");
+      this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.#logger.error(`pages-rebundle failed: ${message}`);
+      this.#result.errors.pages = message;
+      this.#emitStatus("pages", message);
+    }
+  }
+
+  async #buildCss(): Promise<void> {
+    const started = Date.now();
+    try {
+      const cssByBasePath = await new CssCompiler(this.#app).getCssByBasePath({ refresh: true });
+      const optimizedFonts = await this.#optimizeFonts();
+      const cssAssetEntries: Array<[string, { cssUrl: string; cssRelPath: string }]> = [];
+      const cssBase64ByUrl: Record<string, string> = {};
+      await Promise.all(
+        Object.entries(cssByBasePath).map(async ([basePath, baseCssText]) => {
+          const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
+          if (!cssText) return;
+          const cssAssetName = basePath || "root";
+          const cssHash = Bun.hash(`${basePath}\n${cssText}`).toString(36);
+          const cssRelPath = `styles/${cssAssetName}-${cssHash}.css`;
+          const cssUrl = `/_akan/styles/${cssAssetName}-${cssHash}.css`;
+          await Bun.write(path.join(this.#request.artifactDir, cssRelPath), cssText);
+          cssAssetEntries.push([basePath, { cssUrl, cssRelPath }]);
+          cssBase64ByUrl[cssUrl] = Buffer.from(new TextEncoder().encode(cssText)).toString("base64");
+        }),
+      );
+      const cssAssets = Object.fromEntries(cssAssetEntries) as PagesBatchCssAssets;
+      this.#result.cssAssets = cssAssets;
+      this.#emitStatus("css");
+      if (JSON.stringify(this.#request.cssAssets ?? {}) === JSON.stringify(cssAssets)) {
+        this.#logger.verbose("css-rebuild unchanged assets; broadcast skipped");
+        return;
+      }
+      this.#emit({
+        type: "css-updated",
+        data: {
+          cssAssets,
+          cssBase64ByUrl,
+          generation: this.#request.generation,
+          changedFiles: this.#request.changedFiles,
+        },
+      });
+      this.#logger.verbose(`css-compile ok assets=${Object.keys(cssAssets).length} (${Date.now() - started}ms)`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.#logger.error(`css-rebuild failed: ${message}`);
+      this.#result.errors.css = message;
+      this.#emitStatus("css", message);
+    }
+  }
+
+  /** Fonts are expensive and rarely change, so the previous result is reused unless this batch touched it. */
+  async #optimizeFonts(): Promise<OptimizedFonts> {
+    const previous = this.#request.optimizedFonts;
+    if (previous && !BuildBatch.#shouldReoptimizeFonts(previous, this.#request.changedFiles)) {
+      this.#logger.verbose(`font-optimize cached files=${previous.files.length}`);
+      return previous;
+    }
+    const started = Date.now();
+    const optimizedFonts = await new FontOptimizer(this.#app, "start").optimize();
+    this.#result.optimizedFonts = optimizedFonts;
+    this.#logger.verbose(`font-optimize ok files=${optimizedFonts.files.length} (${Date.now() - started}ms)`);
+    return optimizedFonts;
+  }
+
+  static #shouldReoptimizeFonts(previous: OptimizedFonts, changedFiles: string[]): boolean {
+    if (changedFiles.length === 0) return false;
+    return changedFiles.some((file) => {
+      const normalized = path.resolve(file);
+      if (/\.(woff2?|ttf|otf)$/i.test(normalized)) return true;
+      return previous.files.some((fontFile) => path.resolve(fontFile) === normalized);
+    });
+  }
+
+  static async main(): Promise<void> {
+    const raw = process.argv[2];
+    if (!raw) throw new Error("[build-batch] missing request argument");
+    const request = JSON.parse(raw) as BuildBatchRequest;
+    const workspace = WorkspaceExecutor.fromRoot({
+      workspaceRoot: request.workspaceRoot,
+      repoName: request.repoName,
+    });
+    const app = AppExecutor.from(workspace, request.appName);
+    // Seeded rather than rediscovered: the watcher already globbed and validated every route source,
+    // and repeating that here would be the single largest cost of spawning this process.
+    if (request.pageKeys) app.setPageKeys(request.pageKeys);
+    const result = await new BuildBatch(request, app).run();
+    process.send?.({ type: "build-batch-result", data: result });
+  }
+}
+
+void BuildBatch.main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/incrementalBuilder/buildBatchProtocol.ts

@@ -0,0 +1,53 @@
+import type { FontOptimizer } from "@akanjs/devkit/frontendBuild";
+import type { CssPayload, PagesBundlePayload } from "akanjs/server";
+
+export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
+
+export type BuildBatchNeed = "pages" | "css" | "csr";
+
+/**
+ * One generation of build work, handed to a process that exits when it is done.
+ *
+ * Everything here is JSON: the worker is spawned per batch, so state that the long-lived watcher
+ * caches for the session has to travel by value. Two fields exist purely to keep behaviour identical
+ * to the in-process version — `pageKeys` because rediscovering them costs ~220ms on a 177-route app
+ * (route-export validation), and `optimizedFonts` because fonts are only re-optimized when a font file
+ * actually changed.
+ */
+export interface BuildBatchRequest {
+  appName: string;
+  workspaceRoot: string;
+  repoName: string;
+  generation: number;
+  needs: BuildBatchNeed[];
+  changedFiles: string[];
+  /** Page keys the watcher already validated, or null to make the worker discover them itself. */
+  pageKeys: string[] | null;
+  /** Previous font optimization, reused unless this batch touched one of its files. */
+  optimizedFonts: OptimizedFonts | null;
+  /** Previous css assets, so an unchanged compile skips the broadcast instead of busting hashes. */
+  cssAssets: PagesBatchCssAssets | null;
+  /** Absolute artifact directory; the worker writes css assets under it. */
+  artifactDir: string;
+}
+
+export type PagesBatchCssAssets = CssPayload["cssAssets"];
+
+/**
+ * What the watcher folds back into its own state once the worker is done.
+ *
+ * Deliberately small: the payloads browsers are waiting on are *streamed* as each need finishes
+ * (`pages-updated`, `css-updated`, `build-status`, relayed straight through), so a page reload is not
+ * held back by a css compile that has not started yet. Only state the next batch needs travels here.
+ */
+export interface BuildBatchResult {
+  generation: number;
+  cssAssets?: PagesBatchCssAssets;
+  optimizedFonts?: OptimizedFonts;
+  errors: Partial<Record<BuildBatchNeed, string>>;
+  /** The worker died before reporting, so it streamed no `build-status` of its own for these needs. */
+  crashed?: boolean;
+}
+
+export type BuildBatchMessage = { type: "build-batch-result"; data: BuildBatchResult };
+export type { PagesBundlePayload };