@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/frontendBuild/precompressArtifacts.ts

@@ -2,17 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
+import { FontPruner } from "./fontPruner";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
-/**
- * Quality 11 is roughly 100x slower than gzip, so it is spent only where it pays: there is one CSS asset
- * per basePath and it is the largest single file the app ships, worth ~20% over gzip for ~0.2s. Raising the
- * several hundred JS chunks from 9 to 11 costs ~12s of build time to save a few hundred KB, so they stay at 9.
- */
+// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath, not for hundreds of JS chunks.
 const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
 const DEFAULT_BROTLI_QUALITY = 9;
 const GZIP_LEVEL = 9;
+const { formatBytes } = FontPruner;
 
 export interface PrecompressArtifactsResult {
   files: number;
@@ -22,8 +20,7 @@ export interface PrecompressArtifactsResult {
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  //* styles too: WebRouter serves both prefixes through the same sidecar-aware #fileResponse, and the
-  //* one CSS asset per basePath is the largest uncompressed payload the app ships.
+  //* WebRouter serves client/ and styles/ through the same sidecar-aware #fileResponse.
   const roots = [
     path.join(app.dist.cwdPath, ".akan/artifact/client"),
     path.join(app.dist.cwdPath, ".akan/artifact/styles"),
@@ -47,7 +44,7 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
     if (!(await shouldPrecompress(filePath))) continue;
     const bytes = await Bun.file(filePath).bytes();
-    const buffer = toArrayBuffer(bytes);
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
     const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
     const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
     await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
@@ -75,13 +72,3 @@ async function shouldPrecompress(filePath: string): Promise<boolean> {
   if (!(await file.exists())) return false;
   return file.size >= MIN_COMPRESS_BYTES;
 }
-
-function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
-}

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,22 +1,17 @@
 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 { toClientReferencePath } from "../transforms/rscUseClientTransform";
+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_EXTERNALS = [
-  "react",
-  "react-dom",
-  "react-dom/client",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "akanjs/fetch",
-] as const;
 const SSR_CLIENT_ALIAS_EXTERNALS = [
   "react",
   "react-dom",
@@ -24,39 +19,33 @@ const SSR_CLIENT_ALIAS_EXTERNALS = [
   "react/jsx-runtime",
   "react/jsx-dev-runtime",
 ] as const;
+const SSR_CLIENT_EXTERNALS = [...SSR_CLIENT_ALIAS_EXTERNALS, "akanjs/fetch"] as const;
 
 export interface BuildRouteClientOptions {
   app: App;
   seeds: string[];
+  /** Every route's seeds: a build that runs at all bundles the whole app, since two builds each copy shared modules. */
+  graphSeeds?: string[];
   artifact: BaseBuildArtifact;
   knownEntries?: Set<string>;
   routeId?: string;
   command?: "build" | "start";
   discovery?: ClientEntryDiscovery;
-  /**
-   * Client entries resolved by the caller, which skips discovery and bundles exactly this list.
-   *
-   * `AllRoutesBuilder` passes every route's entries at once so they share one `Bun.build`. Chunk
-   * splitting is scoped to a single invocation, so a dependency reachable from entries spread across
-   * several invocations is emitted once per invocation — mermaid landed in `apps/akan` four times that
-   * way. Dev keeps one build per route and leaves this unset.
-   */
+  /** 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 {
-  /** Newly-emitted manifest rows keyed by `${absEntry}#${exportName}`. */
   manifestDelta: ClientManifest;
-  /** Newly-emitted ssrManifest rows keyed by entry URL. */
   ssrManifestDelta: SsrManifest;
-  /** Absolute paths of the `"use client"` leaves this build added. */
   newEntries: string[];
-  /** Absolute paths of all `"use client"` leaves discovered from this route's seeds. */
   discoveredEntries?: string[];
-  /** Absolute source files included in the browser bundles for new entries. */
   clientDeps: string[];
-  /** Absolute source files included in the browser bundle, grouped by original client entry. */
   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 {
@@ -67,45 +56,56 @@ interface BootstrapEntries {
 export class RouteClientBuilder {
   #app: App;
   #seeds: string[];
+  #graphSeeds?: string[];
   #knownEntries: Set<string>;
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
   #entries?: string[];
+  #browser: "chunks" | "registry";
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
     this.#seeds = options.seeds;
+    this.#graphSeeds = options.graphSeeds;
     this.#knownEntries = options.knownEntries ?? new Set<string>();
     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> {
-    const discovered =
-      this.#entries ??
-      (await (this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app))).discover(this.#seeds));
-    const entries = discovered.filter((e) => !this.#knownEntries.has(e));
-    if (entries.length === 0) return this.#emptyResult(discovered);
+    const discovered = this.#entries ?? (await (await this.#getDiscovery()).discover(this.#seeds));
+    if (discovered.every((e) => this.#knownEntries.has(e))) return this.#emptyResult(discovered);
+    const entries = this.#graphSeeds
+      ? [...new Set([...discovered, ...(await (await this.#getDiscovery()).discover(this.#graphSeeds))])].sort()
+      : 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);
     const manifestDelta: ClientManifest = {};
     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);
@@ -119,22 +119,37 @@ 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;
-      for (const dep of sortedDeps) clientDeps.add(dep);
+      if (routeEntries.has(originalEntry)) for (const dep of sortedDeps) clientDeps.add(dep);
     }
 
     return {
       manifestDelta,
       ssrManifestDelta: { moduleLoading: null, moduleMap: ssrModuleMap },
-      newEntries: entries,
+      newEntries: entries.filter((e) => !this.#knownEntries.has(e)),
       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,
     };
   }
 
+  async #getDiscovery(): Promise<ClientEntryDiscovery> {
+    this.#discovery ??= await GraphClientEntryDiscovery.create(this.#app);
+    return this.#discovery;
+  }
+
   #emptyResult(discoveredEntries: string[] = []): BuildRouteClientResult {
     return {
       manifestDelta: {},
@@ -206,31 +221,58 @@ export class RouteClientBuilder {
   }
 
   async #scanExportNames(absEntry: string): Promise<string[]> {
-    const source = await Bun.file(absEntry).text();
-    const transpiler = new Bun.Transpiler({ loader: this.#loaderFor(absEntry) });
-    return transpiler.scan(source).exports;
+    return scanUseClientExports(await Bun.file(absEntry).text(), absEntry, this.#app.workspace.workspaceRoot);
   }
 
-  #loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-    if (absPath.endsWith(".tsx")) return "tsx";
-    if (absPath.endsWith(".jsx")) return "jsx";
-    if (absPath.endsWith(".ts")) return "ts";
-    return "js";
+  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`;
   }
 
-  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`;
+  //? 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> {
@@ -238,12 +280,8 @@ export class RouteClientBuilder {
     return { [Bun.resolveSync("akanjs/fetch", serverEntry)]: "akanjs/fetch" };
   }
 
-  /**
-   * `target: "bun"` is load-bearing: these chunks are `await import()`-ed by the SSR renderer, so a dependency
-   * resolved through its `browser` export condition can touch `document` at module scope and throw mid-render,
-   * degrading the whole document to client rendering. Bun's `conditions` only adds to the target's defaults —
-   * `browser` still wins — so the target itself has to say server.
-   */
+  // `target: "bun"` is load-bearing: a `browser` export condition can touch `document` at module scope mid-SSR, and
+  // Bun's `conditions` only add to the target's defaults, so the target itself must say server.
   static resolveSsrClientBundleOptions(command: "build" | "start"): {
     target: ClientBundleTarget;
     external: readonly string[];

package/frontendBuild/routesManifestArtifactSerializer.ts

@@ -1,5 +1,5 @@
-import path from "node:path";
-import type { RoutesManifest, SsrManifestEntry } from "akanjs/server";
+import type { RoutesManifest } from "akanjs/server";
+import { RoutesManifestStore } from "akanjs/server/artifact/routesManifestStore";
 
 export type SerializedRoutesManifest = Omit<RoutesManifest, "knownEntries"> &
   Partial<Pick<RoutesManifest, "knownEntries">>;
@@ -11,7 +11,7 @@ export class RoutesManifestArtifactSerializer {
 
   constructor(manifest: RoutesManifest, artifactDir: string, options: { production?: boolean } = {}) {
     this.#manifest = manifest;
-    this.#artifactDir = path.resolve(artifactDir);
+    this.#artifactDir = artifactDir;
     this.#production = options.production ?? false;
   }
 
@@ -24,39 +24,8 @@ export class RoutesManifestArtifactSerializer {
   }
 
   serialize(): SerializedRoutesManifest {
-    const serialized: SerializedRoutesManifest = {
-      ...this.#manifest,
-      knownEntries: this.#manifest.knownEntries.map((entry) => this.#serializeArtifactPath(entry)),
-    };
+    const serialized: SerializedRoutesManifest = RoutesManifestStore.serialize(this.#manifest, this.#artifactDir);
     if (this.#production) delete serialized.knownEntries;
-    return {
-      ...serialized,
-      clientManifest: Object.fromEntries(
-        Object.entries(this.#manifest.clientManifest).map(([key, row]) => [this.#serializeArtifactPath(key), row]),
-      ),
-      ssrManifest: {
-        ...this.#manifest.ssrManifest,
-        moduleMap: Object.fromEntries(
-          Object.entries(this.#manifest.ssrManifest.moduleMap).map(([entryUrl, byName]) => [
-            entryUrl,
-            Object.fromEntries(
-              Object.entries(byName).map(([name, entry]) => [
-                name,
-                {
-                  ...entry,
-                  id: this.#serializeArtifactPath(entry.id),
-                  chunks: entry.chunks.map((chunk) => this.#serializeArtifactPath(chunk)),
-                } satisfies SsrManifestEntry,
-              ]),
-            ),
-          ]),
-        ),
-      },
-    };
-  }
-
-  #serializeArtifactPath(artifactPath: string): string {
-    if (!path.isAbsolute(artifactPath)) return artifactPath;
-    return path.relative(this.#artifactDir, artifactPath).split(path.sep).join("/");
+    return serialized;
   }
 }

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