@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.26

package/frontendBuild/routeClientBuilder.ts

@@ -1,12 +1,15 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import type { BaseBuildArtifact, ClientManifest, SsrManifest } from "akanjs/server";
+import type { BaseBuildArtifact, ClientManifest, ClientManifestEntry, SsrManifest } from "akanjs/server";
+import { SSR_DEV_CHUNK, SSR_DEV_ID_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
+import { loaderFor } from "../transforms/moduleSyntax";
 import { scanUseClientExports, toClientReferencePath } from "../transforms/rscUseClientTransform";
 import type { ClientBundleTarget, ClientEntryDiscovery } from "./clientBuildTypes";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { CsrDevPaths } from "./csrDevPaths";
 import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
 
 const SSR_CLIENT_ALIAS_EXTERNALS = [
@@ -30,6 +33,8 @@ export interface BuildRouteClientOptions {
   discovery?: ClientEntryDiscovery;
   /** Pre-resolved client entries: skips discovery and bundles exactly this list. */
   entries?: string[];
+  /** Defaults to `registry` under `start`: the browser loads each entry from the SSR dev registry, so only `client-ssr` builds. */
+  browser?: "chunks" | "registry";
 }
 
 export interface BuildRouteClientResult {
@@ -39,6 +44,8 @@ export interface BuildRouteClientResult {
   discoveredEntries?: string[];
   clientDeps: string[];
   clientDepsByEntry?: Record<string, string[]>;
+  /** Registry mode: the entries the manifest rows name, which the SSR dev registry must hold before they are served. */
+  registryEntries?: string[];
 }
 
 interface BootstrapEntries {
@@ -54,6 +61,7 @@ export class RouteClientBuilder {
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
   #entries?: string[];
+  #browser: "chunks" | "registry";
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
@@ -63,6 +71,7 @@ export class RouteClientBuilder {
     this.#command = options.command ?? "start";
     this.#discovery = options.discovery;
     this.#entries = options.entries;
+    this.#browser = options.browser ?? (this.#command === "start" ? "registry" : "chunks");
   }
 
   async build(): Promise<BuildRouteClientResult> {
@@ -73,8 +82,11 @@ export class RouteClientBuilder {
       : discovered.filter((e) => !this.#knownEntries.has(e));
 
     const bootstrapEntries = await this.#createBootstrapEntries(entries);
-    const browserBundle = await this.#buildBrowserBundle(bootstrapEntries);
+    //? Registry mode builds no browser bundle: the SSR bundle has the same entries, exports and imports to read.
+    const registry = this.#browser === "registry" ? new CsrDevPaths(this.#app.workspace.workspaceRoot) : null;
+    const browserBundle = registry ? null : await this.#buildBrowserBundle(bootstrapEntries);
     const ssrBundle = await this.#buildSsrBundle(bootstrapEntries);
+    const referenceBundle = browserBundle ?? ssrBundle;
 
     const acceptedEntries = new Set(entries);
     const routeEntries = new Set(discovered);
@@ -82,15 +94,18 @@ export class RouteClientBuilder {
     const ssrModuleMap: SsrManifest["moduleMap"] = {};
     const clientDeps = new Set<string>();
     const clientDepsByEntry: Record<string, string[]> = {};
-    for (const [key, row] of Object.entries(browserBundle.manifest)) {
+    for (const [key, bundleRow] of Object.entries(referenceBundle.manifest)) {
       const manifestEntry = RouteClientBuilder.resolveOriginalManifestEntry(
         key,
         bootstrapEntries.originalByBuildEntry,
-        browserBundle.clientReferenceIdByAbsPath,
+        referenceBundle.clientReferenceIdByAbsPath,
         this.#app.workspace.workspaceRoot,
       );
       if (!manifestEntry) continue;
       if (!acceptedEntries.has(manifestEntry.originalEntry)) continue;
+      const row = registry
+        ? RouteClientBuilder.#registryRow(registry, manifestEntry.originalEntry, bundleRow)
+        : bundleRow;
       manifestDelta[manifestEntry.key] = row;
 
       const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(manifestEntry.buildEntry);
@@ -104,7 +119,7 @@ export class RouteClientBuilder {
       const originalEntry = path.resolve(bootstrapEntries.originalByBuildEntry.get(buildEntry) ?? buildEntry);
       if (!acceptedEntries.has(originalEntry)) continue;
       const deps = new Set<string>([originalEntry]);
-      for (const dep of browserBundle.entryDepsByAbsPath.get(buildEntry) ?? []) deps.add(path.resolve(dep));
+      for (const dep of referenceBundle.entryDepsByAbsPath.get(buildEntry) ?? []) deps.add(path.resolve(dep));
       const sortedDeps = [...deps].sort();
       clientDepsByEntry[originalEntry] = sortedDeps;
       if (routeEntries.has(originalEntry)) for (const dep of sortedDeps) clientDeps.add(dep);
@@ -117,6 +132,16 @@ export class RouteClientBuilder {
       discoveredEntries: discovered,
       clientDeps: [...clientDeps].sort(),
       clientDepsByEntry,
+      ...(registry ? { registryEntries: [...acceptedEntries].sort() } : {}),
+    };
+  }
+
+  static #registryRow(paths: CsrDevPaths, entry: string, row: ClientManifestEntry): ClientManifestEntry {
+    return {
+      id: `${SSR_DEV_ID_PREFIX}${paths.idOf(entry)}`,
+      chunks: [SSR_DEV_CHUNK, SSR_DEV_CHUNK],
+      name: row.name,
+      async: true,
     };
   }
 
@@ -199,19 +224,55 @@ export class RouteClientBuilder {
     return scanUseClientExports(await Bun.file(absEntry).text(), absEntry, this.#app.workspace.workspaceRoot);
   }
 
-  static normalizeNamedDefaultFunctionForFastRefresh(source: string): string | null {
-    let changed = false;
-    const defaultNames: string[] = [];
-    const next = source.replace(
-      /(^|\n)(\s*)export\s+default\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)(?=\s*(?:<|\())/g,
-      (match, lineStart: string, indent: string, asyncKeyword: string | undefined, name: string) => {
-        changed = true;
-        defaultNames.push(name);
-        return `${lineStart}${indent}${asyncKeyword ?? ""}function ${name}`;
-      },
-    );
-    if (!changed) return null;
-    return `${next}\n${defaultNames.map((name) => `export default ${name};`).join("\n")}\n`;
+  static normalizeNamedDefaultFunctionForFastRefresh(
+    source: string,
+    { path: filePath }: { path?: string } = {},
+  ): string | null {
+    const declared = RouteClientBuilder.#declaredNamedDefaultFunctions(source, filePath);
+    if (declared.length === 0) return null;
+    let next = "";
+    let cursor = 0;
+    for (const { index, text, lineStart, indent, asyncKeyword, name } of declared) {
+      next += `${source.slice(cursor, index)}${lineStart}${indent}${asyncKeyword}function ${name}`;
+      cursor = index + text.length;
+    }
+    next += source.slice(cursor);
+    return `${next}\n${declared.map(({ name }) => `export default ${name};`).join("\n")}\n`;
+  }
+
+  //? The pattern also matches inside strings and comments (a docs page quoting code), so every candidate is renamed to
+  //? a probe export and only the ones the parser reports as exports are declarations.
+  static #declaredNamedDefaultFunctions(source: string, filePath?: string) {
+    const candidates = [
+      ...source.matchAll(/(^|\n)(\s*)export\s+default\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)(?=\s*(?:<|\())/g),
+    ].map((match) => ({
+      index: match.index,
+      text: match[0],
+      lineStart: match[1] ?? "",
+      indent: match[2] ?? "",
+      asyncKeyword: match[3] ?? "",
+      name: match[4] ?? "",
+    }));
+    if (candidates.length === 0) return [];
+    const probeName = (idx: number) => `__akanNamedDefault${idx}`;
+    let probe = "";
+    let cursor = 0;
+    candidates.forEach(({ index, text, lineStart, indent, asyncKeyword }, idx) => {
+      probe += `${source.slice(cursor, index)}${lineStart}${indent}export ${asyncKeyword}function ${probeName(idx)}`;
+      cursor = index + text.length;
+    });
+    probe += source.slice(cursor);
+    const exported = RouteClientBuilder.#scanExports(probe, filePath);
+    return candidates.filter((_, idx) => exported.has(probeName(idx)));
+  }
+
+  static #scanExports(source: string, filePath?: string): Set<string> {
+    try {
+      return new Set(new Bun.Transpiler({ loader: filePath ? loaderFor(filePath) : "tsx" }).scan(source).exports);
+    } catch {
+      // Unparseable source is left alone, so the bundler reports its syntax error at the real line.
+      return new Set();
+    }
   }
 
   static resolveSsrClientRuntimeAliases(): Record<string, string> {

package/frontendBuild/serverGraphFile.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { type ServerGraph, ServerGraphFile } from "./serverGraphFile";
+
+//? Resolved, as the graph holds real paths: on Windows a missing `/repo/...` resolves onto the current drive.
+const at = (relative: string) => path.resolve("/repo/apps/a", relative);
+
+const graph: ServerGraph = {
+  inputs: [at("page/_index.tsx"), at("lib/task.constant.ts"), at("ui/Card.tsx")],
+  clientExports: { [at("ui/Card.tsx")]: ["Card", "CardBody"] },
+};
+const touches = (files: string[], exportsNow: string[] | null = ["CardBody", "Card"]) =>
+  ServerGraphFile.touches(graph, files, () => exportsNow);
+
+describe("ServerGraphFile.touches", () => {
+  test("a file the server graph never read changes nothing it renders", async () => {
+    expect(await touches([at("ui/OnlyClient.tsx")])).toBe(false);
+  });
+
+  test("a module the server renders counts", async () => {
+    expect(await touches([at("lib/task.constant.ts")])).toBe(true);
+  });
+
+  test("a client module that keeps its export names does not count, in any order", async () => {
+    expect(await touches([at("ui/Card.tsx")])).toBe(false);
+  });
+
+  test("a client module whose names changed, or that stopped being one, counts", async () => {
+    expect(await touches([at("ui/Card.tsx")], ["Card"])).toBe(true);
+    expect(await touches([at("ui/Card.tsx")], null)).toBe(true);
+  });
+
+  test("without a graph every save counts", async () => {
+    expect(await ServerGraphFile.touches(null, [at("ui/OnlyClient.tsx")], () => null)).toBe(true);
+  });
+
+  test("a changed file the build just read for the first time counts: a failed import was waiting for it", async () => {
+    const next: ServerGraph = { ...graph, inputs: [...graph.inputs, at("ui/card.ts")] };
+    expect(await ServerGraphFile.touches(graph, [at("ui/card.ts")], () => null, next)).toBe(true);
+    expect(await ServerGraphFile.touches(graph, [at("ui/card.ts")], () => null)).toBe(false);
+  });
+
+  test("a failed build keeps the last good graph and carries its files to the next build's check", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-server-graph-"));
+    try {
+      await ServerGraphFile.write(dir, graph);
+      await ServerGraphFile.carry(dir, [at("page/_index.tsx")]);
+      const kept = await ServerGraphFile.read(dir);
+      expect(kept?.inputs).toEqual(graph.inputs);
+      expect(kept?.carried).toEqual([at("page/_index.tsx")]);
+      expect(await ServerGraphFile.touches(kept, [at("ui/Card.tsx")], () => ["Card", "CardBody"])).toBe(false);
+      const changed = [at("ui/Card.tsx"), ...(kept?.carried ?? [])];
+      expect(await ServerGraphFile.touches(kept, changed, () => ["Card", "CardBody"])).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a graph written again inside one mtime tick is read afresh", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-server-graph-"));
+    try {
+      const file = path.join(dir, ServerGraphFile.fileName);
+      const tick = new Date(Math.floor(Date.now() / 1000) * 1000);
+      await ServerGraphFile.write(dir, graph);
+      fs.utimesSync(file, tick, tick);
+      await ServerGraphFile.read(dir);
+      await ServerGraphFile.carry(dir, [at("page/_index.tsx")]);
+      fs.utimesSync(file, tick, tick);
+      expect((await ServerGraphFile.read(dir))?.carried).toEqual([at("page/_index.tsx")]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/frontendBuild/serverGraphFile.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FileSys } from "../fileSys";
+import { hasUseClientDirective, scanUseClientExports } from "../transforms/rscUseClientTransform";
+import { CsrDevPaths } from "./csrDevPaths";
+
+export interface ServerGraph {
+  /** Real paths of the workspace sources the dev pages bundle read. */
+  inputs: string[];
+  /** Export names of every `"use client"` module among them: the server holds each only as a reference by name. */
+  clientExports: Record<string, string[]>;
+  /** Files saved in batches whose pages build failed since this graph was written: the next build's changes too. */
+  carried?: string[];
+}
+
+//* What the dev server bundle read, written by every dev pages build that succeeds, so a save can be told apart as one
+//* the server renders (it needs an RSC refresh) or one only the client registry holds. A failed build keeps the last
+//* good graph and carries its files over, so the fixing save still refreshes what the failed ones changed.
+export class ServerGraphFile {
+  static readonly fileName = "server-graph.json";
+  static #cache: { file: string; stamp: string; graph: ServerGraph } | null = null;
+
+  static async read(artifactDir: string): Promise<ServerGraph | null> {
+    const file = path.join(artifactDir, ServerGraphFile.fileName);
+    const stat = fs.statSync(file, { throwIfNoEntry: false });
+    if (!stat) return null;
+    //? Not the mtime alone: two writes inside one mtime tick (seen on Linux) read back the first. A write replaces the
+    //? file, so its inode moves too.
+    const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    const cached = ServerGraphFile.#cache;
+    if (cached?.file === file && cached.stamp === stamp) return cached.graph;
+    const graph = (await Bun.file(file)
+      .json()
+      .catch(() => null)) as ServerGraph | null;
+    if (graph) ServerGraphFile.#cache = { file, stamp, graph };
+    return graph;
+  }
+
+  static async write(artifactDir: string, graph: ServerGraph): Promise<void> {
+    const file = path.join(artifactDir, ServerGraphFile.fileName);
+    const temp = `${file}.${process.pid}.tmp`;
+    await Bun.write(temp, JSON.stringify(graph));
+    await FileSys.replace(temp, file);
+  }
+
+  static async carry(artifactDir: string, files: string[]): Promise<void> {
+    const graph = await ServerGraphFile.read(artifactDir);
+    if (!graph || files.length === 0) return;
+    const carried = [...new Set([...(graph.carried ?? []), ...files.map((file) => CsrDevPaths.realpath(file))])];
+    await ServerGraphFile.write(artifactDir, { ...graph, carried });
+  }
+
+  // `exportsNow` answers a client module's current export names, or null once it is no longer one. `next` is the graph
+  // the build just wrote: a changed file it reads for the first time (a module a failed import was waiting for) counts.
+  static async touches(
+    graph: ServerGraph | null,
+    files: string[],
+    exportsNow: (file: string) => string[] | null | Promise<string[] | null>,
+    next?: ServerGraph | null,
+  ): Promise<boolean> {
+    if (!graph) return true;
+    const inputs = new Set(graph.inputs);
+    const joined = new Set((next?.inputs ?? []).filter((input) => !inputs.has(input)));
+    for (const rawFile of files) {
+      const file = CsrDevPaths.realpath(rawFile);
+      if (joined.has(file)) return true;
+      if (!inputs.has(file)) continue;
+      const before = graph.clientExports[file];
+      if (!before) return true;
+      //? The server holds a "use client" module only as references by name: an edit that keeps them renders the same.
+      const now = await exportsNow(file);
+      if (!now || ServerGraphFile.#names(now) !== ServerGraphFile.#names(before)) return true;
+    }
+    return false;
+  }
+
+  static async clientExportsOf(file: string): Promise<string[] | null> {
+    const source = await Bun.file(file)
+      .text()
+      .catch(() => null);
+    if (source === null || !hasUseClientDirective(source)) return null;
+    try {
+      return scanUseClientExports(source, file);
+    } catch {
+      // A module the server can no longer read as client references is a server change; the pages build says why.
+      return null;
+    }
+  }
+
+  static #names(exports: string[]): string {
+    return [...exports].sort().join(",");
+  }
+}

package/frontendBuild/ssrDevBundler.ts

@@ -0,0 +1,85 @@
+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 } 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;
+  }
+
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return [...entryFiles, ...(await this.clientEntries())];
+  }
+}

package/incrementalBuilder/buildBatch.proc.ts

@@ -11,10 +11,12 @@ import {
   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";
 
@@ -32,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;
   }
 
@@ -45,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",
@@ -102,7 +111,21 @@ class BuildBatch {
   }
 
   async #updateCsrRegistry(started: number): Promise<void> {
-    const update = await new CsrDevBundler(this.#app).update(this.#request.changedFiles);
+    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;
@@ -110,17 +133,48 @@ class BuildBatch {
     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)`,
     );
-    this.#emit({
-      type: "csr-updated",
-      data: {
-        generation: update.generation,
-        mode: "registry",
-        reload: update.reload,
-        reason: update.reason,
-        patchUrl: update.patchUrl,
-        changedIds: update.changedIds,
-      },
-    });
+  }
+
+  // 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.
@@ -129,8 +183,16 @@ class BuildBatch {
     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: {
@@ -138,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)}`),
+      );
     }
   }
 
@@ -213,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,
@@ -221,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 };