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

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

package/frontendBuild/ssrDevBundler.ts

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