@akanjs/devkit 2.4.1-rc.2 → 2.4.1-rc.4

package/frontendBuild/sourceMtimeIndex.ts

@@ -0,0 +1,326 @@
+import type { Dirent, Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { HmrChangeClassifier } from "./hmrChangeClassifier";
+
+interface TrackedFile {
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * A directory the index could not read, held with this mtime so every subsequent scan sees a mismatch
+ * and retries it. `NaN !== NaN`, which is exactly the "always stale" semantics wanted here.
+ */
+const UNREADABLE = Number.NaN;
+
+export interface SourceMtimeIndexOptions {
+  roots: string[];
+  classifier?: HmrChangeClassifier;
+}
+
+/**
+ * A snapshot of every interesting source file's mtime under the watch roots, so the watcher can answer
+ * "what actually changed" without trusting `fs.watch` event payloads.
+ *
+ * Bun 1.3.14's recursive `fs.watch` on macOS reports roughly **one path per ~200ms coalescing window**
+ * and discards every other path changed in that window. Measured on this repo: saving 5 files together
+ * reports 1; saving 20 reports 2; a single unrelated write landing first in the window hides a
+ * concurrent save entirely. Node 22 reports all 20 on the same tree, so this is a Bun defect rather
+ * than an FSEvents limitation (`local/optimize-resource/06-watcher-dropped-event.md`).
+ *
+ * Re-stating the tracked set costs ~15ms against ~1300 source files here, where a fresh walk costs
+ * ~70ms — the walk has to visit ~40k entries (`ios/`, `android/`, `public/`) to find those 1300. So
+ * changes are found by re-stating known files plus re-reading only the directories whose own mtime
+ * moved, which is what adding or removing an entry bumps.
+ */
+export class SourceMtimeIndex {
+  readonly #roots: string[];
+  readonly #classifier: HmrChangeClassifier;
+  readonly #files = new Map<string, TrackedFile>();
+  readonly #dirs = new Map<string, number>();
+  readonly #unreadable = new Map<string, string>();
+  #primed = false;
+  #queue: Promise<unknown> = Promise.resolve();
+
+  constructor({ roots, classifier }: SourceMtimeIndexOptions) {
+    this.#roots = SourceMtimeIndex.#pruneNestedRoots(roots);
+    this.#classifier = classifier ?? new HmrChangeClassifier();
+  }
+
+  get primed(): boolean {
+    return this.#primed;
+  }
+
+  get trackedFileCount(): number {
+    return this.#files.size;
+  }
+
+  /**
+   * Paths the index currently cannot read, as `{ path, code }`. Non-empty means change detection has a
+   * blind spot right now: anything edited underneath one of these is not reported until it recovers.
+   *
+   * Worth surfacing rather than swallowing, because the failure is silent by nature — a walk cannot tell
+   * how much it did not see. Each entry is retried on every scan and clears itself on success.
+   */
+  get coverageGaps(): { path: string; code: string }[] {
+    return [...this.#unreadable].map(([file, code]) => ({ path: file, code }));
+  }
+
+  /** Record the current state as the baseline. Reports nothing; call before the first `collectChanges`. */
+  async prime(): Promise<void> {
+    await this.#serialize(async () => {
+      this.#files.clear();
+      this.#dirs.clear();
+      this.#unreadable.clear();
+      await Promise.all(this.#roots.map((root) => this.#walk(root, null)));
+      this.#primed = true;
+    });
+  }
+
+  /**
+   * Absolute paths whose content changed (or which disappeared) since the last call, with the baseline
+   * advanced to match. Returns an empty list until primed, so a failed prime degrades to watcher events
+   * rather than reporting the entire tree as changed.
+   */
+  async collectChanges(): Promise<string[]> {
+    return this.#serialize(async () => {
+      if (!this.#primed) return [];
+      const changed = new Set<string>();
+      await this.#collectFileChanges(changed);
+      await this.#collectDirChanges(changed);
+      return [...changed];
+    });
+  }
+
+  /**
+   * Every scan runs to completion before the next begins.
+   *
+   * Overlapping scans corrupt each other rather than merely racing: one advances the baseline and prunes
+   * entries while the other is midway through a key snapshot it took earlier, so a path the first has
+   * already accounted for reads back as missing and is reported as a change that never happened. Observed
+   * directly — a file nothing had written was reported, which downstream is a wasted rebuild.
+   */
+  async #serialize<T>(work: () => Promise<T>): Promise<T> {
+    const run = this.#queue.then(work, work);
+    // Swallowed on the chain only; the caller still sees the rejection through `run`.
+    this.#queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /**
+   * Adopt writes the caller made itself — regenerated barrels, inserted imports — into the baseline so
+   * the next `collectChanges` does not report them as a user edit.
+   *
+   * Narrow race worth knowing: a user save of the same path landing between the caller's write and this
+   * call is baselined too, and therefore lost. It is sub-millisecond and no wider than the window the
+   * event-based watcher already had.
+   */
+  async absorb(paths: string[]): Promise<void> {
+    await this.#serialize(async () => {
+      if (!this.#primed) return;
+      await Promise.all(
+        paths.map(async (file) => {
+          const abs = path.resolve(file);
+          const stats = await stat(abs).catch(() => null);
+          if (!stats?.isFile()) {
+            this.#files.delete(abs);
+            return;
+          }
+          this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        }),
+      );
+    });
+  }
+
+  async #collectFileChanges(changed: Set<string>): Promise<void> {
+    await Promise.all(
+      [...this.#files.keys()].map(async (abs) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+        if (!stats) {
+          // Unreadable is not deleted. Dropping it here would both invent a change nobody made and stop
+          // tracking the file, so a later real edit would go unreported.
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+            return;
+          }
+          this.#files.delete(abs);
+          this.#unreadable.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        this.#unreadable.delete(abs);
+        if (!stats.isFile()) {
+          this.#files.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        const known = this.#files.get(abs);
+        if (known && known.mtimeMs === stats.mtimeMs && known.size === stats.size) return;
+        this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        changed.add(abs);
+      }),
+    );
+  }
+
+  /**
+   * A directory's own mtime moves when an entry is added or removed but not when a tracked file's
+   * content changes, so this finds creations and deletions the file pass cannot see.
+   */
+  async #collectDirChanges(changed: Set<string>): Promise<void> {
+    const moved: string[] = [];
+    const gone: string[] = [];
+    await Promise.all(
+      [...this.#dirs.entries()].map(async ([dir, mtimeMs]) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(dir);
+        if (!stats?.isDirectory()) {
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#markUnreadable(dir, err);
+            return;
+          }
+          gone.push(dir);
+          return;
+        }
+        // `UNREADABLE` is NaN, so a directory retained from a failed read always mismatches and is
+        // rewalked here — that retry is what lets a transient failure recover on its own.
+        if (stats.mtimeMs !== mtimeMs) moved.push(dir);
+      }),
+    );
+    for (const dir of gone) this.#forget(dir);
+    // Sequential: a moved directory can reveal a new subtree, and walking those in order keeps the
+    // number of concurrent `readdir` calls proportional to the change rather than to the tree.
+    for (const dir of moved) await this.#walk(dir, changed);
+  }
+
+  /**
+   * Re-read one directory, tracking entries that are new or changed. Recurses only into subdirectories
+   * that are new to the index; known ones are covered by their own mtime check in `#collectDirChanges`.
+   */
+  async #walk(dir: string, changed: Set<string> | null): Promise<void> {
+    const [listing, dirStat] = await Promise.all([SourceMtimeIndex.#readdirPath(dir), SourceMtimeIndex.#statPath(dir)]);
+    const entries = listing.entries;
+    const dirStats = dirStat.stats;
+    if (!entries || !dirStats?.isDirectory()) {
+      // A directory that cannot be read is not a directory that is gone. Forgetting it here is
+      // unrecoverable: nothing re-stats a dir the index has dropped, and the parent's own mtime does not
+      // move when a child merely becomes unreadable, so the whole subtree stays invisible for the life of
+      // the process. Measured: one `EACCES` at prime silently hid 2 of 3 files, permanently.
+      const err = listing.err ?? dirStat.err;
+      if (err && !SourceMtimeIndex.#isMissing(err)) {
+        this.#markUnreadable(dir, err);
+        return;
+      }
+      this.#forget(dir);
+      return;
+    }
+    const known = this.#dirs.has(dir);
+    this.#dirs.set(dir, dirStats.mtimeMs);
+    this.#unreadable.delete(dir);
+    const descend: string[] = [];
+    const present = new Set<string>();
+    let blind = false;
+    for (const entry of entries) {
+      if (SourceMtimeIndex.#skipDirent(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        descend.push(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (this.#classifier.classify(abs) === "ignore") continue;
+      present.add(abs);
+      const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+      if (!stats?.isFile()) {
+        // A file listed but not stat-able has no baseline, so an edit to it would compare against nothing.
+        // Leaving the directory stale is what brings it back; the file pass cannot, since it only revisits
+        // paths already tracked.
+        if (err && !SourceMtimeIndex.#isMissing(err)) {
+          this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+          blind = true;
+        }
+        continue;
+      }
+      this.#unreadable.delete(abs);
+      const previous = this.#files.get(abs);
+      if (previous && previous.mtimeMs === stats.mtimeMs && previous.size === stats.size) continue;
+      this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+      changed?.add(abs);
+    }
+    // Entries this directory used to hold and no longer does. Only worth scanning for a directory the
+    // index already knew, which during `prime` is none of them.
+    if (known) {
+      for (const abs of [...this.#files.keys()]) {
+        if (present.has(abs) || path.dirname(abs) !== dir) continue;
+        this.#files.delete(abs);
+        changed?.add(abs);
+      }
+    }
+    if (blind) this.#dirs.set(dir, UNREADABLE);
+    // Known subdirectories carry their own mtime check, so only unseen ones need walking. Concurrent
+    // because `prime` reaches every directory through here.
+    await Promise.all(descend.filter((sub) => !this.#dirs.has(sub)).map((sub) => this.#walk(sub, changed)));
+  }
+
+  /**
+   * Keep a directory the index could not read, flagged for retry on every scan, and keep whatever it
+   * already knows underneath it — those files stay tracked so a real edit is still caught the moment
+   * access returns.
+   */
+  #markUnreadable(dir: string, err: NodeJS.ErrnoException): void {
+    this.#dirs.set(dir, UNREADABLE);
+    this.#unreadable.set(dir, err.code ?? "EUNKNOWN");
+  }
+
+  /** Drop a directory and everything the index holds beneath it. */
+  #forget(dir: string): void {
+    const prefix = `${dir}${path.sep}`;
+    this.#dirs.delete(dir);
+    this.#unreadable.delete(dir);
+    for (const known of [...this.#dirs.keys()]) if (known.startsWith(prefix)) this.#dirs.delete(known);
+    // Otherwise a gap under a deleted directory is reported forever, since nothing revisits it to clear.
+    for (const known of [...this.#unreadable.keys()]) if (known.startsWith(prefix)) this.#unreadable.delete(known);
+  }
+
+  /** `null` stats with the errno kept, so callers can tell "not there" from "could not look". */
+  static async #statPath(abs: string): Promise<{ stats: Stats | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { stats: await stat(abs), err: null };
+    } catch (err) {
+      return { stats: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  static async #readdirPath(dir: string): Promise<{ entries: Dirent[] | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { entries: await readdir(dir, { withFileTypes: true }), err: null };
+    } catch (err) {
+      return { entries: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  /**
+   * Whether an errno means the path genuinely is not there, which is the only case where dropping it from
+   * the baseline is right. Everything else — `EACCES`, `EIO`, `EMFILE`, a stalled network mount — means the
+   * index failed to look, and treating that as a deletion both invents a change and blinds it to real ones.
+   */
+  static #isMissing(err: NodeJS.ErrnoException): boolean {
+    return err.code === "ENOENT" || err.code === "ENOTDIR";
+  }
+
+  /**
+   * Mirrors `HmrChangeClassifier`'s path rules for directory names — dotted names cover `.git` and
+   * `.akan`, which is where every build artifact lands. Symlinked entries are neither `isFile` nor
+   * `isDirectory` and so are skipped, matching `fs.watch`, which does not follow them either.
+   */
+  static #skipDirent(name: string): boolean {
+    return !name || name.startsWith(".") || name === "node_modules";
+  }
+
+  /** `WatchRootResolver` can return `apps/<app>/page` alongside `apps/`; walking both doubles the work. */
+  static #pruneNestedRoots(roots: string[]): string[] {
+    const resolved = [...new Set(roots.map((root) => path.resolve(root)))].sort();
+    return resolved.filter(
+      (root) => !resolved.some((other) => other !== root && root.startsWith(`${other}${path.sep}`)),
+    );
+  }
+}

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 };

package/incrementalBuilder/buildBatchRunner.ts

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { BuilderMessage } from "akanjs/server";
+import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
+
+/**
+ * Runs one `BuildBatchRequest` in a fresh process and resolves with what it produced.
+ *
+ * The watcher serializes every batch through its own work queue, so this deliberately has no pool: one
+ * worker exists at a time, and it exits before the next one starts. That is the whole point — the
+ * bundler arenas `Bun.build` never frees go back to the OS with the process.
+ *
+ * A worker that dies without reporting is not fatal. Every need it was given comes back as an error, the
+ * watcher reports a red build-status for that generation, and the last-good artifact keeps serving —
+ * the same contract a failed in-process build had. It must never take the watcher down with it: the
+ * watcher is the dev server's file watcher, so nothing would notice the fix.
+ */
+export class BuildBatchRunner {
+  static readonly #entryCandidates = (workspaceRoot: string) => [
+    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(import.meta.dir, "buildBatch.proc.js"),
+    path.join(import.meta.dir, "buildBatch.proc.ts"),
+  ];
+  #logger = new Logger("BuildBatchRunner");
+  #entry: string | null = null;
+  #workspaceRoot: string;
+  #cwd: string;
+  constructor({ workspaceRoot, cwd }: { workspaceRoot: string; cwd: string }) {
+    this.#workspaceRoot = workspaceRoot;
+    this.#cwd = cwd;
+  }
+
+  async #resolveEntry(): Promise<string> {
+    if (this.#entry) return this.#entry;
+    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    for (const candidate of candidates) {
+      if (!(await Bun.file(candidate).exists())) continue;
+      this.#entry = candidate;
+      return candidate;
+    }
+    throw new Error(`[build-batch] worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
+
+  /**
+   * `onMessage` receives everything the worker streams as it goes — `pages-updated`, `css-updated`,
+   * `build-status` — so the watcher can relay each one the moment it is produced instead of holding a
+   * page reload until the whole batch is done.
+   */
+  async run(
+    request: BuildBatchRequest,
+    onMessage: (message: BuilderMessage) => void = () => undefined,
+  ): Promise<BuildBatchResult> {
+    const started = Date.now();
+    const entry = await this.#resolveEntry();
+    let result: BuildBatchResult | null = null;
+    // The request travels in argv rather than over IPC so the worker can start on its first tick
+    // instead of waiting for a handshake it would have to synchronize against.
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+      cwd: this.#cwd,
+      env: process.env,
+      stdio: ["ignore", "inherit", "inherit"],
+      serialization: "advanced",
+      ipc: (message: BuildBatchMessage | BuilderMessage) => {
+        if (!message || typeof message !== "object") return;
+        if (message.type === "build-batch-result") result = message.data;
+        else onMessage(message);
+      },
+    });
+    const exitCode = await proc.exited;
+    if (result) {
+      this.#logger.verbose(
+        `[build-batch] generation=${request.generation} needs=${request.needs.join(",")} done in ${Date.now() - started}ms`,
+      );
+      return result;
+    }
+    const message = `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,
+    };
+  }
+}