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

package/frontendBuild/pagesBundleBuilder.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { PageEntry } from "../artifact/implicitRootLayout";
@@ -9,7 +10,9 @@ import { loaderFor } from "../transforms/moduleSyntax";
 import { transformUseClient } from "../transforms/rscUseClientTransform";
 import { createUseClientBundlePlugin } from "../transforms/useClientBundlePlugin";
 import { bundleDefine } from "./bundleDefine";
+import { CsrDevPaths } from "./csrDevPaths";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+import { ServerGraphFile } from "./serverGraphFile";
 
 export interface BuildPagesBundleResult {
   bundlePath: string;
@@ -42,6 +45,13 @@ export class PagesBundleBuilder {
       this.#pageEntries ?? (await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys()));
     const entrySource = PagesEntrySourceGenerator.generate(resolvedEntries);
     const workspaceRoot = this.#app.workspace.workspaceRoot;
+    const dev = this.#command === "start";
+    const clientExports: Record<string, string[]> = {};
+    const onClientModule = dev
+      ? (file: string, exports: string[]) => {
+          clientExports[CsrDevPaths.realpath(file)] = exports;
+        }
+      : undefined;
     const result = await Bun.build({
       entrypoints: [VIRTUAL_PAGES_ENTRY],
       outdir: `${this.#artifactDir}/server`,
@@ -55,6 +65,7 @@ export class PagesBundleBuilder {
         asset: "assets/[name]-[hash].[ext]",
       },
       define: bundleDefine(this.#app, this.#command, "ssr"),
+      metafile: dev,
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
@@ -66,9 +77,10 @@ export class PagesBundleBuilder {
                 transformUseClient(source, {
                   path: args.path,
                   workspaceRoot,
+                  onClientModule,
                 }),
             })
-          : createUseClientBundlePlugin({ workspaceRoot }),
+          : createUseClientBundlePlugin({ workspaceRoot, onClientModule }),
       ],
     });
 
@@ -79,6 +91,8 @@ export class PagesBundleBuilder {
 
     const bundlePath = path.resolve(entryArtifact.path);
     const buildId = Date.now();
+    if (dev && result.metafile)
+      await ServerGraphFile.write(this.#artifactDir, this.#serverGraph(result.metafile, clientExports));
     const outputBytes = result.outputs.reduce((sum, output) => sum + output.size, 0);
     const chunkCount = result.outputs.filter((output) => output.kind === "chunk").length;
     this.#app.verbose(
@@ -95,6 +109,15 @@ export class PagesBundleBuilder {
     };
   }
 
+  #serverGraph(metafile: Bun.BuildMetafile, clientExports: Record<string, string[]>) {
+    const inputs = Object.keys(metafile.inputs)
+      .filter((input) => !input.includes("node_modules"))
+      .map((input) => path.resolve(input))
+      .filter((input) => fs.existsSync(input))
+      .map((input) => CsrDevPaths.realpath(input));
+    return { inputs, clientExports };
+  }
+
   get #artifactDir(): string {
     return `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
   }

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -2,11 +2,19 @@ import path from "node:path";
 import type { PageEntry } from "../artifact/implicitRootLayout";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
+export interface PagesEntrySourceOptions {
+  /** Detects an async default export; a caller that outlives one generation keeps its own cache across saves. */
+  isAsyncDefault?: (moduleAbsPath: string) => Promise<boolean>;
+}
+
 export class PagesEntrySourceGenerator {
   #pageEntries: PageEntry[];
+  readonly #asyncDefaults = new Map<string, Promise<boolean>>();
+  readonly #detect: (moduleAbsPath: string) => Promise<boolean>;
 
-  constructor(pageEntries: PageEntry[]) {
+  constructor(pageEntries: PageEntry[], { isAsyncDefault }: PagesEntrySourceOptions = {}) {
     this.#pageEntries = pageEntries;
+    this.#detect = isAsyncDefault ?? ((moduleAbsPath) => AsyncDefaultExportDetector.detect(moduleAbsPath));
   }
 
   static generate(pageEntries: PageEntry[]): string {
@@ -21,25 +29,67 @@ export class PagesEntrySourceGenerator {
     return `export const pages = {\n${lines.join("\n")}\n};\n`;
   }
 
-  static async generateStatic(pageEntries: PageEntry[]): Promise<string> {
-    return await new PagesEntrySourceGenerator(pageEntries).generateStatic();
+  static async generateStatic(pageEntries: PageEntry[], { fromDir }: { fromDir?: string } = {}): Promise<string> {
+    return await new PagesEntrySourceGenerator(pageEntries).generateStatic({ fromDir });
   }
 
-  async generateStatic(): Promise<string> {
+  // `fromDir` makes the specifiers relative: Bun inlines an absolute import of a file that is also an entrypoint.
+  async generateStatic({ fromDir }: { fromDir?: string } = {}): Promise<string> {
     const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
-      const specifier = PagesEntrySourceGenerator.#toImportSpecifier(moduleAbsPath);
+      const specifier = fromDir
+        ? PagesEntrySourceGenerator.#toRelativeSpecifier(fromDir, moduleAbsPath)
+        : PagesEntrySourceGenerator.#toImportSpecifier(moduleAbsPath);
       return `import * as page${index} from ${JSON.stringify(specifier)};`;
     });
     const entries = await Promise.all(
       this.#pageEntries.map(async ({ key, moduleAbsPath }, index) => {
-        const isAsyncDefault = await AsyncDefaultExportDetector.detect(moduleAbsPath);
+        const isAsyncDefault = await this.#isAsyncDefault(moduleAbsPath);
         return `  ${JSON.stringify(key)}: { loader: async () => page${index}, isAsyncDefault: ${isAsyncDefault} },`;
       }),
     );
     return `${imports.join("\n")}\nexport const pages = {\n${entries.join("\n")}\n};\n`;
   }
 
+  // Route HMR in the dev registry bundle: `akanWebkit` is the entry's namespace import of `akanjs/webkit`.
+  async generateHotReplace({
+    fromDir,
+    ownerId,
+    moduleIds,
+  }: {
+    fromDir: string;
+    ownerId: string;
+    moduleIds: string[];
+  }): Promise<string> {
+    const entries = await Promise.all(
+      this.#pageEntries.map(async ({ key, moduleAbsPath }) => {
+        const specifier = PagesEntrySourceGenerator.#toRelativeSpecifier(fromDir, moduleAbsPath);
+        const isAsyncDefault = await this.#isAsyncDefault(moduleAbsPath);
+        return `    ${JSON.stringify(key)}: { loader: async () => require(${JSON.stringify(specifier)}), isAsyncDefault: ${isAsyncDefault} },`;
+      }),
+    );
+    return `__akan.accept(${JSON.stringify(ownerId)}, ${JSON.stringify(moduleIds)}, async () => {
+  const replaced = await akanWebkit.replacePages({
+${entries.join("\n")}
+  });
+  if (!replaced) throw new Error("the route table no longer matches the pages it was built from");
+});
+`;
+  }
+
+  #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
+    const known = this.#asyncDefaults.get(moduleAbsPath);
+    if (known) return known;
+    const detected = this.#detect(moduleAbsPath);
+    this.#asyncDefaults.set(moduleAbsPath, detected);
+    return detected;
+  }
+
   static #toImportSpecifier(moduleAbsPath: string): string {
     return path.resolve(moduleAbsPath).split(path.sep).join("/");
   }
+
+  static #toRelativeSpecifier(fromDir: string, moduleAbsPath: string): string {
+    const relative = path.relative(fromDir, path.resolve(moduleAbsPath)).split(path.sep).join("/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+  }
 }

package/frontendBuild/registryMetadataFingerprint.test.ts

@@ -0,0 +1,63 @@
+import { afterAll, beforeAll, 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 { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
+
+describe("RegistryMetadataFingerprint", () => {
+  let root: string;
+  let later = Date.now() / 1000 + 60;
+  const file = (relative: string) => path.join(root, relative);
+  const touch = (relative: string) => {
+    later += 1;
+    fs.utimesSync(file(relative), later, later);
+  };
+  const ssrMetadata = (target: string) =>
+    isAkanRuntimeMetadataFile(target) && !target.endsWith(".dictionary.ts") && path.basename(target) !== "dict.ts";
+  const stamp = async (isMetadataFile = isAkanRuntimeMetadataFile) =>
+    await RegistryMetadataFingerprint.of([root], isMetadataFile);
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(os.tmpdir(), "akan-registry-metadata-"));
+    for (const relative of [
+      "lib/sig.ts",
+      "lib/dict.ts",
+      "lib/useClient.ts",
+      "lib/user/user.signal.ts",
+      "lib/user/user.dictionary.ts",
+      "lib/user/User.Zone.tsx",
+      "lib/user/user.signal.test.ts",
+    ])
+      await Bun.write(file(relative), "export {};\n");
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("moves with a signal save and stays with a component save", async () => {
+    const before = await stamp();
+    touch("lib/user/User.Zone.tsx");
+    touch("lib/user/user.signal.test.ts");
+    expect(await stamp()).toBe(before);
+    touch("lib/user/user.signal.ts");
+    expect(await stamp()).not.toBe(before);
+  });
+
+  test("a registry that inlines no dictionary is not moved by a dictionary save", async () => {
+    const ssrBefore = await stamp(ssrMetadata);
+    const csrBefore = await stamp();
+    touch("lib/user/user.dictionary.ts");
+    touch("lib/dict.ts");
+    expect(await stamp(ssrMetadata)).toBe(ssrBefore);
+    expect(await stamp()).not.toBe(csrBefore);
+  });
+
+  test("a root without a lib folder counts for nothing", async () => {
+    expect(await RegistryMetadataFingerprint.of([root, path.join(root, "lib/user")], isAkanRuntimeMetadataFile)).toBe(
+      await stamp(),
+    );
+  });
+});

package/frontendBuild/registryMetadataFingerprint.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+
+//* The sources `lib/useClient.ts` reads through its macros, which no registry graph lists as a dependency. A registry
+//* records their stamp, so a builder that loads one built before a signal or dictionary save rebuilds it, whichever
+//* process saw that save (a builder restarted for it never finishes the rebuild it started).
+export class RegistryMetadataFingerprint {
+  static readonly #sources = new Bun.Glob("**/*.{signal,dictionary}.ts");
+  static readonly #libFiles = ["sig.ts", "dict.ts", "useClient.ts"];
+
+  /** `roots` are app and lib directories; only the metadata files under each one's `lib/` count. */
+  static async of(roots: string[], isMetadataFile: (file: string) => boolean): Promise<string> {
+    const stamps: string[] = [];
+    for (const root of new Set(roots)) {
+      const libDir = path.join(root, "lib");
+      if (!fs.existsSync(libDir)) continue;
+      const files = RegistryMetadataFingerprint.#libFiles.map((name) => path.join(libDir, name));
+      for await (const relative of RegistryMetadataFingerprint.#sources.scan({ cwd: libDir, onlyFiles: true }))
+        files.push(path.join(libDir, relative));
+      for (const file of files) {
+        if (!isMetadataFile(file)) continue;
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        if (stat) stamps.push(`${file}:${stat.mtimeMs}:${stat.size}`);
+      }
+    }
+    return Bun.hash(stamps.sort((a, b) => a.localeCompare(b)).join("\n")).toString(36);
+  }
+}

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(",");
+  }
+}