@akanjs/devkit 3.0.0-beta.23 → 3.0.0-beta.25

package/frontendBuild/ssrDevBundler.ts

@@ -0,0 +1,91 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { computeRouteSeedIndex } from "../artifact/routeSeedIndex";
+import type { App } from "../commandDecorators";
+import { bundleDefine } from "./bundleDefine";
+import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { DevRegistryBundler } from "./devRegistryBundler";
+import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
+
+//* Dev-only client code of SSR pages as a module registry, under `.akan/artifact/ssr-dev`. Its roots are a bootstrap
+//* (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 = 1;
+  static readonly bootstrapKey = "";
+  readonly reloadsOnEntryChange = false;
+  #discovery: ClientEntryDiscovery | null = null;
+  readonly #sharedDiscovery: (() => ClientEntryDiscovery) | null;
+
+  /** `discovery` is the resident builder's, which it keeps current with every save; a worker discovers afresh. */
+  constructor(app: App, { discovery }: { discovery?: () => ClientEntryDiscovery } = {}) {
+    super(app, { dirName: SSR_DEV_DIRNAME, routePrefix: SSR_DEV_ROUTE_PREFIX, library: true });
+    this.#sharedDiscovery = discovery ?? null;
+  }
+
+  async context(): Promise<CsrDevContext> {
+    const akanConfig = await this.app.getConfig();
+    const define = bundleDefine(this.app, "start", "ssr");
+    const optimizeImports = [...akanConfig.optimizeImports];
+    const configKey = Bun.hash(
+      JSON.stringify(["ssr", SsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, VENDOR_SPECIFIERS]),
+    ).toString(36);
+    return {
+      pageEntries: [],
+      basePaths: [...akanConfig.basePaths],
+      htmlBasePaths: [],
+      define,
+      optimizeImports,
+      configKey,
+      refreshFile: null,
+      externals: VENDOR_SPECIFIERS,
+    };
+  }
+
+  //? The client runtime of an SSR page inlines no dictionary (`useClient.ts` reads one only when rendering csr), so
+  //? a dictionary save is none of this registry's business.
+  override isMetadataFile(file: string): boolean {
+    return super.isMetadataFile(file) && !file.endsWith(".dictionary.ts") && path.basename(file) !== "dict.ts";
+  }
+
+  // Run first in the tab, before any client module the payload names: the store registry must exist by then.
+  async writeEntries(): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.entryDir, { recursive: true });
+    const file = path.join(this.entryDir, "bootstrap.ts");
+    const hasStore = await Bun.file(path.join(this.app.cwdPath, "lib", "st.ts")).exists();
+    const source = hasStore ? `import ${JSON.stringify(`@apps/${this.app.name}/client`)};\n` : "export {};\n";
+    const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
+    if (!unchanged) await Bun.write(file, source);
+    const entryFile = CsrDevPaths.realpath(file);
+    return { files: { [SsrDevBundler.bootstrapKey]: entryFile }, changed: unchanged ? [] : [entryFile] };
+  }
+
+  /** Every `"use client"` entry the app's routes reach, the ones a route build names in its manifest. */
+  async clientEntries(): Promise<string[]> {
+    const pageEntries = await resolveSsrPageEntriesForApp(this.app, await this.app.getPageKeys());
+    const seedIndex = computeRouteSeedIndex(pageEntries);
+    const seeds = [...new Set([...seedIndex.globalLayoutFiles, ...seedIndex.entries.flatMap((entry) => entry.seeds)])];
+    const discovery = this.#sharedDiscovery?.() ?? (await this.#ownDiscovery());
+    return (await discovery.discover(seeds)).map((file) => CsrDevPaths.realpath(file));
+  }
+
+  async #ownDiscovery(): Promise<ClientEntryDiscovery> {
+    this.#discovery ??= await GraphClientEntryDiscovery.create(this.app);
+    return this.#discovery;
+  }
+
+  override async wantedRoots(files: string[], graph: CsrDevGraph): Promise<Set<string>> {
+    const entries = new Set(await this.clientEntries());
+    const reached = await super.wantedRoots(files, graph);
+    return new Set(files.filter((file) => reached.has(file) || entries.has(CsrDevPaths.realpath(file))));
+  }
+
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return [...entryFiles, ...(await this.clientEntries())];
+  }
+}

package/incrementalBuilder/buildBatch.proc.ts

@@ -7,13 +7,17 @@ import type { App } from "@akanjs/devkit/commandDecorators";
 import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import {
   CsrArtifactBuilder,
+  CsrDevBundler,
   CssCompiler,
   FontOptimizer,
   PagesBundleBuilder,
+  ServerGraphFile,
   SsrBaseArtifactBuilder,
+  SsrDevBundler,
 } from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage, BuildPhase } from "akanjs/server";
+import type { BuilderMessage, BuildPhase, HmrTrace } from "akanjs/server";
+import { resolveDevCsrMode } from "akanjs/server/hmr/csrDevManifest";
 import type { BuildBatchRequest, BuildBatchResult, OptimizedFonts, PagesBatchCssAssets } from "./buildBatchProtocol";
 
 // `Bun.build` keeps native bundler arenas that `Bun.gc(true)` cannot reclaim; only exiting returns them.
@@ -30,10 +34,11 @@ class BuildBatch {
 
   async run(): Promise<BuildBatchResult> {
     if (this.#request.needs.includes("base")) await this.#buildBase();
-    // Order kept from the in-process build: csr before pages, 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("ssr")) await this.#buildSsrRegistry();
+    // Css before pages: it scans the sources and reads nothing pages produces, so a class edit need not wait for pages.
     if (this.#request.needs.includes("css")) await this.#buildCss();
+    if (this.#request.needs.includes("pages")) await this.#buildPages();
     return this.#result;
   }
 
@@ -43,6 +48,12 @@ class BuildBatch {
     process.send?.(message);
   }
 
+  #sentTrace(): HmrTrace | undefined {
+    if (!this.#request.trace) return undefined;
+    const now = Date.now();
+    return { ...this.#request.trace, patchAt: now, sentAt: now };
+  }
+
   #emitStatus(phase: BuildPhase, message?: string): void {
     this.#emit({
       type: "build-status",
@@ -80,22 +91,108 @@ class BuildBatch {
   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)`);
+      if (resolveDevCsrMode() === "registry") await this.#updateCsrRegistry(started);
+      else await this.#rebuildCsrArtifact(started);
       this.#emitStatus("csr");
     } catch (err) {
       this.#fail("csr", "csr-rebundle", err);
     }
   }
 
+  async #rebuildCsrArtifact(started: number): Promise<void> {
+    await new CsrArtifactBuilder(this.#app).build();
+    this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
+    // A CSR tab takes none of the SSR refresh messages, so a rebuilt artifact reaches it only as this reload.
+    if (this.#request.changedFiles.length === 0) return;
+    this.#emit({
+      type: "csr-updated",
+      data: { generation: Date.now(), mode: "artifact", reload: true, reason: "the CSR artifact was rebuilt" },
+    });
+  }
+
+  async #updateCsrRegistry(started: number): Promise<void> {
+    const update = await new CsrDevBundler(this.#app).update(this.#request.changedFiles, {
+      announce: (announced) =>
+        this.#emit({
+          type: "csr-updated",
+          data: {
+            generation: announced.generation,
+            mode: "registry",
+            reload: announced.reload,
+            reason: announced.reason,
+            patchUrl: announced.patchUrl,
+            changedIds: announced.changedIds,
+            trace: this.#sentTrace(),
+          },
+        }),
+    });
+    if (!update) {
+      this.#logger.verbose(`csr-dev unchanged (${Date.now() - started}ms)`);
+      return;
+    }
+    this.#logger.verbose(
+      `csr-dev generation=${update.generation} ${update.reload ? `reload (${update.reason})` : `patch modules=${update.changedIds.length}`} graph=${update.moduleCount} (${Date.now() - started}ms)`,
+    );
+  }
+
+  // Takes every entry the routes reach as a root, so a route build naming any of them finds it in the registry.
+  async #buildSsrRegistry(): Promise<void> {
+    const started = Date.now();
+    try {
+      const bundler = new SsrDevBundler(this.#app);
+      //? Runs before pages, so the graph is the last build's, as in the resident builder: a save it holds still waits.
+      const hold = await ServerGraphFile.touches(
+        await ServerGraphFile.read(this.#request.artifactDir),
+        this.#request.changedFiles,
+        (file) => ServerGraphFile.clientExportsOf(file),
+      );
+      const update = await bundler.update(this.#request.changedFiles, {
+        roots: await bundler.clientEntries(),
+        announce: (announced) =>
+          this.#emit({
+            type: "ssr-updated",
+            data: {
+              generation: announced.generation,
+              reload: announced.reload,
+              reason: announced.reason,
+              patchUrl: announced.patchUrl,
+              changedIds: announced.changedIds,
+              trace: this.#sentTrace(),
+              ...(announced.epoch !== undefined ? { epoch: announced.epoch } : {}),
+              ...(announced.first ? { first: true } : {}),
+              ...(hold && this.#request.changedFiles.length > 0
+                ? { hold, batchGeneration: this.#request.generation }
+                : {}),
+            },
+          }),
+      });
+      this.#emitStatus("ssr");
+      this.#logger.verbose(
+        update
+          ? `ssr-dev generation=${update.generation} ${update.reload ? `reload (${update.reason})` : `patch modules=${update.changedIds.length}`} graph=${update.moduleCount} (${Date.now() - started}ms)`
+          : `ssr-dev unchanged (${Date.now() - started}ms)`,
+      );
+    } catch (err) {
+      this.#fail("ssr", "ssr-dev", err);
+    }
+  }
+
   // Rewritten with the bundle: the backend rereads it on `pages-updated` to pick up added, moved or deleted routes.
   async #buildPages(): Promise<void> {
     const started = Date.now();
     try {
       const pageEntries = await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys());
       const seedIndex = computeRouteSeedIndex(pageEntries);
+      const previousGraph = await ServerGraphFile.read(this.#request.artifactDir);
       const next = await new PagesBundleBuilder(this.#app, "start", pageEntries).build();
       await saveRouteSeedIndex(this.#request.artifactDir, seedIndex);
+      const nextGraph = await ServerGraphFile.read(this.#request.artifactDir);
+      const serverTouched = await ServerGraphFile.touches(
+        previousGraph,
+        [...this.#request.changedFiles, ...(previousGraph?.carried ?? [])],
+        (file) => nextGraph?.clientExports[file] ?? null,
+        nextGraph,
+      );
       this.#emit({
         type: "pages-updated",
         data: {
@@ -103,12 +200,17 @@ class BuildBatch {
           buildId: next.buildId,
           generation: this.#request.generation,
           changedFiles: this.#request.changedFiles,
+          trace: this.#sentTrace(),
+          serverTouched,
         },
       });
       this.#emitStatus("pages");
       this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
     } catch (err) {
       this.#fail("pages", "pages-rebundle", err);
+      await ServerGraphFile.carry(this.#request.artifactDir, this.#request.changedFiles).catch((carryError: unknown) =>
+        this.#logger.warn(`server graph carry failed; the next save may skip its RSC refresh: ${String(carryError)}`),
+      );
     }
   }
 
@@ -178,7 +280,13 @@ class BuildBatch {
   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 parsed = JSON.parse(raw) as BuildBatchRequest;
+    const request = parsed.trace
+      ? {
+          ...parsed,
+          trace: { ...parsed.trace, workerStartAt: Math.round(performance.timeOrigin), workerAt: Date.now() },
+        }
+      : parsed;
     const workspace = WorkspaceExecutor.fromRoot({
       workspaceRoot: request.workspaceRoot,
       repoName: request.repoName,
@@ -186,8 +294,13 @@ class BuildBatch {
     const app = AppExecutor.from(workspace, request.appName);
     // Seeded, not rediscovered: route discovery would be the largest cost of spawning this process.
     if (request.pageKeys) app.setPageKeys(request.pageKeys);
+    //? Exits with the builder that spawned it (a kill, a crash, a restart for a metadata save): left running, it would
+    //? write a registry its replacement is rebuilding. Removed before returning, since the listener keeps Bun's IPC open.
+    const orphaned = () => process.exit(1);
+    process.on("disconnect", orphaned);
     const result = await new BuildBatch(request, app).run();
     process.send?.({ type: "build-batch-result", data: result });
+    process.off("disconnect", orphaned);
   }
 }
 

package/incrementalBuilder/buildBatchProtocol.ts

@@ -1,10 +1,10 @@
 import type { FontOptimizer } from "@akanjs/devkit/frontendBuild";
-import type { BaseBuildArtifact, CssPayload, PagesBundlePayload } from "akanjs/server";
+import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from "akanjs/server";
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
 // `base` is the boot build: it always runs alone, before the builder can serve anything.
-export type BuildBatchNeed = "base" | "pages" | "css" | "csr";
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {
@@ -18,6 +18,7 @@ export interface BuildBatchRequest {
   optimizedFonts: OptimizedFonts | null; // reused unless this batch touched one of its files
   cssAssets: PagesBatchCssAssets | null; // an unchanged compile skips the broadcast instead of busting hashes
   artifactDir: string;
+  trace?: HmrTrace;
 }
 
 export type PagesBatchCssAssets = CssPayload["cssAssets"];
@@ -29,7 +30,9 @@ export interface BuildBatchResult {
   optimizedFonts?: OptimizedFonts;
   artifact?: BaseBuildArtifact; // `base` batches only
   errors: Partial<Record<BuildBatchNeed, string>>;
-  crashed?: boolean; // died before reporting, so it streamed no build-status for these needs
+  crashed?: boolean; // died before reporting its result
+  /** Of a crashed batch, the needs it died before reporting: the others streamed their build-status first. */
+  crashedNeeds?: BuildBatchNeed[];
 }
 
 export type BuildBatchMessage = { type: "build-batch-result"; data: BuildBatchResult };

package/incrementalBuilder/buildBatchRunner.test.ts

@@ -31,4 +31,35 @@ describe("BuildBatchRunner", () => {
 
     expect(result.errors.base).toContain('"./not-there" (apps/demo/page/_index.tsx:1:22)');
   }, 30_000);
+
+  test("a worker that dies mid-batch keeps what each need reported, and fails only the needs it never reached", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+const status = (phase, message) =>
+  process.send({ type: "build-status", data: { generation, phase, ok: !message, files: [], message } });
+status("ssr");
+status("css", "css broke");
+setTimeout(() => process.exit(1), 50);
+`,
+    );
+    const result = await new BuildBatchRunner({ workspaceRoot: root, cwd: appDir }).run({
+      appName: "demo",
+      workspaceRoot: root,
+      repoName: "repo",
+      generation: 7,
+      needs: ["ssr", "css", "pages"],
+      changedFiles: [],
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.join(appDir, ".akan/artifact"),
+    });
+    expect(result).toMatchObject({ crashed: true, crashedNeeds: ["pages"] });
+    expect(result.errors.ssr).toBeUndefined();
+    expect(result.errors.css).toBe("css broke");
+    expect(result.errors.pages).toContain("exited with code 1");
+  }, 30_000);
 });

package/incrementalBuilder/buildBatchRunner.ts

@@ -3,7 +3,8 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
 import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
 
-// No pool on purpose: one worker at a time, exiting after its batch, returns the arenas `Bun.build` never frees.
+// No pool on purpose: a worker exiting after its batch returns the arenas `Bun.build` never frees. The callers order
+// their own work (the slow lane, the css queue, the SSR registry's boot build beside them), so a few can overlap.
 // A worker that dies without reporting must not take the watcher down; its needs come back as errors.
 export class BuildBatchRunner {
   #logger = new Logger("BuildBatchRunner");
@@ -38,8 +39,10 @@ export class BuildBatchRunner {
     const started = Date.now();
     const entry = await this.#resolveEntry();
     let result: BuildBatchResult | null = null;
+    const reported = new Map<string, string | undefined>();
+    const payload = request.trace ? { ...request, trace: { ...request.trace, spawnAt: Date.now() } } : request;
     // argv rather than IPC, so the worker starts on its first tick instead of waiting for a handshake.
-    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(payload)], {
       cwd: this.#cwd,
       env: process.env,
       stdio: ["ignore", "inherit", "inherit"],
@@ -47,7 +50,10 @@ export class BuildBatchRunner {
       ipc: (message: BuildBatchMessage | BuilderMessage) => {
         if (!message || typeof message !== "object") return;
         if (message.type === "build-batch-result") result = message.data;
-        else onMessage(message);
+        else {
+          if (message.type === "build-status") reported.set(message.data.phase, message.data.message);
+          onMessage(message);
+        }
       },
     });
     const exitCode = await proc.exited;
@@ -64,10 +70,13 @@ export class BuildBatchRunner {
         }`
       : `build worker exited with code ${exitCode} before reporting a result`;
     this.#logger.error(`[build-batch] generation=${request.generation} ${message}`);
-    return {
-      generation: request.generation,
-      errors: Object.fromEntries(request.needs.map((need) => [need, message])),
-      crashed: true,
-    };
+    //? A need that reported before the crash keeps what it reported: a worker killed during pages built ssr and css.
+    const crashedNeeds = request.needs.filter((need) => !reported.has(need));
+    const failed = request.needs.flatMap((need) => {
+      if (!reported.has(need)) return [[need, message] as const];
+      const error = reported.get(need);
+      return error ? [[need, error] as const] : [];
+    });
+    return { generation: request.generation, errors: Object.fromEntries(failed), crashed: true, crashedNeeds };
   }
 }

package/incrementalBuilder/builderWorkQueue.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { type BatchJob, BuilderWorkQueue } from "./builderWorkQueue";
+
+const gate = () => {
+  const { promise: opened, resolve: open } = Promise.withResolvers<void>();
+  return { open, opened };
+};
+
+describe("BuilderWorkQueue", () => {
+  test("runs jobs one at a time, in the order they were queued", async () => {
+    const order: string[] = [];
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const first = gate();
+    const a = queue.enqueue("a", async () => {
+      await first.opened;
+      order.push("a");
+    });
+    const b = queue.enqueue("b", async () => {
+      order.push("b");
+      return 2;
+    });
+    expect(queue.size).toBe(2);
+    first.open();
+    await a;
+    expect(await b).toBe(2);
+    expect(order).toEqual(["a", "b"]);
+    expect(queue.size).toBe(0);
+  });
+
+  test("folds a batch queued behind another batch into it, for the newest generation", async () => {
+    const ran: BatchJob[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        ran.push(batch);
+        if (ran.length === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages", "css"], changedFiles: ["a.tsx"] });
+    const second = queue.enqueueBatch({
+      generation: 2,
+      needs: ["pages", "css"],
+      changedFiles: ["b.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+    const third = queue.enqueueBatch({ generation: 3, needs: ["csr", "pages"], changedFiles: ["a.tsx", "c.tsx"] });
+    expect(second).toBe(third);
+    running.open();
+    await Promise.all([first, second, third]);
+    expect(ran).toHaveLength(2);
+    expect(ran[1]).toEqual({
+      generation: 3,
+      needs: ["pages", "css", "csr"],
+      changedFiles: ["b.tsx", "a.tsx", "c.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+  });
+
+  test("keeps a batch queued after a task behind that task", async () => {
+    const order: string[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        order.push(`batch:${batch.generation}`);
+        if (batch.generation === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages"], changedFiles: [] });
+    const route = queue.enqueue("route", async () => {
+      order.push("route");
+    });
+    const second = queue.enqueueBatch({ generation: 2, needs: ["pages"], changedFiles: [] });
+    running.open();
+    await Promise.all([first, route, second]);
+    expect(order).toEqual(["batch:1", "route", "batch:2"]);
+  });
+
+  test("drains jobs queued while it waits, and survives a job that throws", async () => {
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const failing = queue.enqueue("fails", async () => {
+      throw new Error("boom");
+    });
+    let late = false;
+    void queue.enqueue("queues-more", async () => {
+      void queue.enqueue("late", async () => {
+        late = true;
+      });
+    });
+    await expect(failing).rejects.toThrow("boom");
+    await queue.drain();
+    expect(late).toBe(true);
+    expect(queue.size).toBe(0);
+  });
+});

package/incrementalBuilder/builderWorkQueue.ts

@@ -0,0 +1,126 @@
+import type { HmrTrace } from "akanjs/server";
+import type { BuildBatchNeed } from "./buildBatchProtocol";
+
+export interface DiscoveryJob {
+  files: string[];
+  refresh: boolean;
+  /** The newest batch these files came from: a route build that starts after has taken it in. */
+  generation: number;
+}
+
+export interface BatchJob {
+  generation: number;
+  needs: BuildBatchNeed[];
+  changedFiles: string[];
+  trace?: HmrTrace;
+  /** Code files whose client-entry discovery goes stale before this batch builds; `refresh` rebuilds it whole. */
+  discovery?: DiscoveryJob;
+}
+
+interface QueuedJob {
+  label: string;
+  batch: BatchJob | null;
+  run: () => Promise<void>;
+  settle: PromiseWithResolvers<void>;
+}
+
+export interface BuilderWorkQueueOptions {
+  runBatch: (batch: BatchJob) => Promise<void>;
+  onSettled?: (label: string, ms: number) => void;
+}
+
+//* The builder's slow lane: build-worker batches, route builds and full CSR builds run here one at a time, so a save's
+//* CSR patch never waits behind them. A batch queued behind another batch folds into it: a burst of saves builds pages
+//* and css once for the newest generation instead of once per save.
+export class BuilderWorkQueue {
+  readonly #runBatch: BuilderWorkQueueOptions["runBatch"];
+  readonly #onSettled: BuilderWorkQueueOptions["onSettled"];
+  readonly #pending: QueuedJob[] = [];
+  #running: QueuedJob | null = null;
+  #idle: Promise<void> = Promise.resolve();
+  #wakeIdle: (() => void) | null = null;
+
+  constructor({ runBatch, onSettled }: BuilderWorkQueueOptions) {
+    this.#runBatch = runBatch;
+    this.#onSettled = onSettled;
+  }
+
+  /** Jobs waiting or running. */
+  get size(): number {
+    return this.#pending.length + (this.#running ? 1 : 0);
+  }
+
+  enqueueBatch(batch: BatchJob): Promise<void> {
+    const tail = this.#pending.at(-1);
+    if (tail?.batch) {
+      tail.batch = BuilderWorkQueue.merge(tail.batch, batch);
+      return tail.settle.promise;
+    }
+    const job = this.#job("batch", batch, async () => undefined);
+    job.run = async () => await this.#runBatch(job.batch ?? batch);
+    return this.#push(job);
+  }
+
+  enqueue<T>(label: string, run: () => Promise<T>): Promise<T> {
+    let result: T | undefined;
+    const job = this.#job(label, null, async () => {
+      result = await run();
+    });
+    return this.#push(job).then(() => result as T);
+  }
+
+  /** Resolves once nothing is waiting or running, including jobs queued while it waits. */
+  async drain(): Promise<void> {
+    while (this.size > 0) await this.#idle;
+  }
+
+  static merge(into: BatchJob, next: BatchJob): BatchJob {
+    const discovery =
+      into.discovery || next.discovery
+        ? {
+            files: [...new Set([...(into.discovery?.files ?? []), ...(next.discovery?.files ?? [])])],
+            refresh: !!into.discovery?.refresh || !!next.discovery?.refresh,
+            generation: Math.max(into.discovery?.generation ?? 0, next.discovery?.generation ?? 0),
+          }
+        : undefined;
+    return {
+      generation: Math.max(into.generation, next.generation),
+      needs: [...new Set([...into.needs, ...next.needs])],
+      changedFiles: [...new Set([...into.changedFiles, ...next.changedFiles])],
+      trace: next.trace ?? into.trace,
+      ...(discovery ? { discovery } : {}),
+    };
+  }
+
+  #job(label: string, batch: BatchJob | null, run: () => Promise<void>): QueuedJob {
+    return { label, batch, run, settle: Promise.withResolvers<void>() };
+  }
+
+  #push(job: QueuedJob): Promise<void> {
+    if (this.size === 0)
+      this.#idle = new Promise<void>((resolve) => {
+        this.#wakeIdle = resolve;
+      });
+    this.#pending.push(job);
+    if (!this.#running) void this.#pump();
+    return job.settle.promise;
+  }
+
+  async #pump(): Promise<void> {
+    for (let job = this.#pending.shift(); job; job = this.#pending.shift()) {
+      this.#running = job;
+      const started = Date.now();
+      try {
+        await job.run();
+        job.settle.resolve();
+      } catch (error) {
+        job.settle.reject(error);
+      } finally {
+        this.#running = null;
+        this.#onSettled?.(job.label, Date.now() - started);
+      }
+    }
+    this.#wakeIdle?.();
+    this.#wakeIdle = null;
+  }
+}

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -196,7 +196,7 @@ describe("IncrementalBuilderHost.maxRssBytes", () => {
     withEnv(
       { AKAN_BUILDER_MAX_RSS_MB: undefined, AKAN_BUILDER_MAX_RSS: undefined, AKAN_MEMORY_LIMIT: undefined },
       () => {
-        expect(IncrementalBuilderHost.maxRssBytes()).toBe(1_200 * 1024 * 1024);
+        expect(IncrementalBuilderHost.maxRssBytes()).toBe(2_048 * 1024 * 1024);
       },
     );
   });