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

package/frontendBuild/csrDevResolver.test.ts

@@ -0,0 +1,239 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevContext } from "./csrDevTypes";
+
+const context: CsrDevContext = {
+  pageEntries: [],
+  basePaths: [],
+  htmlBasePaths: [],
+  define: {},
+  optimizeImports: [],
+  configKey: "key",
+  refreshFile: null,
+};
+
+describe("CsrDevResolver before its resolution build", () => {
+  let root: string;
+  let paths: CsrDevPaths;
+  const file = (relative: string) => path.join(paths.root, relative);
+  const resolver = (runtimeResolved: Record<string, string[]> = {}) =>
+    new CsrDevResolver({
+      paths,
+      context,
+      entryFiles: [],
+      resolution: { "node_modules/pkg/a.js": { dep: "node_modules/dep/index.js" } },
+      runtimeResolved,
+    });
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-resolver-"));
+    for (const relative of [
+      "apps/demo/ui/Card.tsx",
+      "node_modules/pkg/a.js",
+      "node_modules/pkg/b.js",
+      "node_modules/dep/index.js",
+      "node_modules/fresh/index.js",
+    ])
+      await Bun.write(path.join(root, relative), "export {};\n");
+    await Bun.write(path.join(root, "node_modules/fresh/package.json"), '{ "name": "fresh", "main": "index.js" }');
+    paths = new CsrDevPaths(root);
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("a file of the same package reuses what the browser build resolved for a sibling", () => {
+    expect(resolver().resolve(file("node_modules/pkg/b.js"), "dep")).toBe(file("node_modules/dep/index.js"));
+  });
+
+  test("but not what Bun's runtime resolver found for it: that ignores the browser condition", () => {
+    const withFallback = resolver({ "node_modules/pkg/a.js": ["dep"] });
+    expect(withFallback.resolve(file("node_modules/pkg/b.js"), "dep")).toBeNull();
+    expect(withFallback.serializeRuntimeResolved()).toEqual({ "node_modules/pkg/a.js": ["dep"] });
+  });
+
+  test("the resolution build clears a runtime resolution it records itself, so a sibling may reuse it again", async () => {
+    await Bun.write(
+      file("apps/demo/ui/Fresh.tsx"),
+      'import * as fresh from "fresh";\nexport const Fresh = () => fresh;\n',
+    );
+    const prepassed = new CsrDevResolver({
+      paths,
+      context,
+      entryFiles: [file("apps/demo/ui/Fresh.tsx")],
+      runtimeResolved: { "apps/demo/ui/Fresh.tsx": ["fresh"] },
+    });
+    await prepassed.prepass();
+    expect(prepassed.serializeRuntimeResolved()).toEqual({});
+  });
+
+  test("a relative import follows a file moved into a folder or renamed, which Bun's resolver cache does not", async () => {
+    const card = file("apps/demo/ui/Card.tsx");
+    await Bun.write(file("apps/demo/ui/Moved.tsx"), "export {};\n");
+    await Bun.write(file("apps/demo/ui/renamed.ts"), "export {};\n");
+    expect(CsrDevPaths.tryResolve("./Moved", path.dirname(card))).toBe(file("apps/demo/ui/Moved.tsx"));
+    expect(CsrDevPaths.tryResolve("./renamed", path.dirname(card))).toBe(file("apps/demo/ui/renamed.ts"));
+    await rm(file("apps/demo/ui/Moved.tsx"));
+    await Bun.write(file("apps/demo/ui/Moved/index.tsx"), "export {};\n");
+    await rm(file("apps/demo/ui/renamed.ts"));
+    await Bun.write(file("apps/demo/ui/renamed.tsx"), "export {};\n");
+
+    expect(resolver().resolve(card, "./Moved")).toBe(file("apps/demo/ui/Moved/index.tsx"));
+    expect(resolver().resolve(card, "./renamed")).toBe(file("apps/demo/ui/renamed.tsx"));
+    expect(() => resolver().resolve(card, "./Missing")).toThrow('cannot resolve "./Missing"');
+  });
+
+  test("a recorded target moved away since is reused by no sibling, nor by its importer, nor kept in the graph", () => {
+    const stale = new CsrDevResolver({
+      paths,
+      context,
+      entryFiles: [],
+      resolution: {
+        "node_modules/pkg/a.js": { dep: "node_modules/dep/old.js" },
+        "node_modules/pkg/b.js": { dep: "node_modules/dep/old.js" },
+      },
+    });
+    expect(stale.resolve(file("node_modules/pkg/b.js"), "dep")).toBeNull();
+    expect(stale.serialize()).toEqual({ "node_modules/pkg/a.js": {}, "node_modules/pkg/b.js": {} });
+  });
+
+  test("a new package in the user's code asks for the resolution build, and a typo fails like a missing file", () => {
+    expect(resolver().resolve(file("apps/demo/ui/Card.tsx"), "fresh")).toBeNull();
+    expect(() => resolver().resolve(file("apps/demo/ui/Card.tsx"), "frseh")).toThrow('cannot resolve "frseh"');
+    expect(resolver().resolve(file("node_modules/pkg/b.js"), "frseh")).toBeNull();
+  });
+});
+
+describe("CsrDevPaths.resolveOnDisk", () => {
+  let root: string;
+  const at = (relative: string) => path.join(root, relative);
+
+  beforeAll(async () => {
+    root = CsrDevPaths.realpath(await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-disk-")));
+    for (const relative of [
+      "pair/x.js",
+      "pair/x.mjs",
+      "fields/b.js",
+      "fields/m.js",
+      "fields/main.js",
+      "fields/index.js",
+      "dirmain/lib/index.js",
+      "dirmain/index.js",
+      "shadow/Foo/index.tsx",
+      "shadow/Page.tsx",
+      "sibling/x.ts",
+      "sibling/Page.tsx",
+      "slash/Foo/index.ts",
+      "slash/Foo.ts",
+      "slash/Page.tsx",
+      "req/index.js",
+      "req/main.js",
+      "req/m.js",
+      "modonly/index.js",
+      "modonly/m.js",
+      "dot/Foo.tsx",
+      "dot/Foo/index.tsx",
+      "dot/Foo/Sub/x.ts",
+      "bmap/lib/server.ts",
+      "bmap/lib/client.ts",
+      "bmap/entry.ts",
+    ])
+      await Bun.write(at(relative), "export {};\n");
+    await Bun.write(at("fields/package.json"), '{ "browser": "b.js", "module": "m.js", "main": "main.js" }');
+    await Bun.write(at("dirmain/package.json"), '{ "main": "lib" }');
+    await Bun.write(at("req/package.json"), '{ "module": "m.js", "main": "main.js" }');
+    await Bun.write(at("modonly/package.json"), '{ "module": "m.js" }');
+    await Bun.write(at("bmap/package.json"), '{ "browser": { "./lib/server.ts": "./lib/client.ts" } }');
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("weighs extensions as Bun's browser build does, a require call apart from an import", () => {
+    expect(CsrDevPaths.resolveOnDisk(at("pair/x"))).toBe(at("pair/x.mjs"));
+    expect(CsrDevPaths.resolveOnDisk(at("pair/x"), "require")).toBe(at("pair/x.js"));
+  });
+
+  test("enters a folder through browser, then module, then main (which may name a folder), then index", () => {
+    expect(CsrDevPaths.resolveOnDisk(at("fields"))).toBe(at("fields/b.js"));
+    expect(CsrDevPaths.resolveOnDisk(at("dirmain"))).toBe(at("dirmain/lib/index.js"));
+  });
+
+  test("a require call reads no module field: main when there is one, otherwise the index", () => {
+    expect(CsrDevPaths.resolveOnDisk(at("req"))).toBe(at("req/m.js"));
+    expect(CsrDevPaths.resolveOnDisk(at("req"), "require")).toBe(at("req/main.js"));
+    expect(CsrDevPaths.resolveOnDisk(at("modonly"), "require")).toBe(at("modonly/index.js"));
+  });
+
+  test("a bare import Bun cannot resolve here goes to a worker only when its package landed after this process began", async () => {
+    //? A package Bun's resolver misses in this process: it keeps node_modules listings, so one added by `bun add` while
+    //? the builder runs looks like this until a fresh process reads it.
+    await Bun.write(at("inst/node_modules/half/package.json"), '{ "name": "half", "main": "missing.js" }');
+    await Bun.write(at("inst/src/a.ts"), 'import "half";\n');
+    const started = (startedAt: number) =>
+      new CsrDevResolver({ paths: new CsrDevPaths(root), context, entryFiles: [], startedAt });
+    const before = started(Date.now() - 60_000);
+    expect(before.resolve(at("inst/src/a.ts"), "half")).toBeNull();
+    expect(before.resolve(at("inst/src/a.ts"), "half/formatt")).toBeNull();
+    expect(() => before.resolve(at("inst/src/a.ts"), "nowhere-to-be-found")).toThrow("cannot resolve");
+    //? Installed before the builder started: its listing is Bun's, so a miss is a typo or a half-typed import.
+    const after = started(Date.now() + 60_000);
+    expect(() => after.resolve(at("inst/src/a.ts"), "half/formatt")).toThrow("cannot resolve");
+  });
+
+  test('"." and ".." name the folder alone, as a trailing slash does', () => {
+    expect(CsrDevPaths.resolveRelative(at("dot/Foo"), ".")).toBe(at("dot/Foo/index.tsx"));
+    expect(CsrDevPaths.resolveRelative(at("dot/Foo/Sub"), "..")).toBe(at("dot/Foo/index.tsx"));
+  });
+
+  test("app code under a package.json that maps files with a browser object keeps the recorded answer", () => {
+    const resolver = new CsrDevResolver({
+      paths: new CsrDevPaths(root),
+      context,
+      entryFiles: [],
+      resolution: { "bmap/entry.ts": { "./lib/server": "bmap/lib/client.ts" } },
+    });
+    expect(resolver.resolve(at("bmap/entry.ts"), "./lib/server")).toBe(at("bmap/lib/client.ts"));
+  });
+
+  test("a specifier ending in a slash names the folder alone", () => {
+    expect(CsrDevPaths.resolveRelative(at("slash"), "./Foo/")).toBe(at("slash/Foo/index.ts"));
+    expect(CsrDevPaths.resolveRelative(at("slash"), "./Foo")).toBe(at("slash/Foo.ts"));
+  });
+
+  test("a recorded relative resolution stands while the disk resolves it the same way", async () => {
+    const paths = new CsrDevPaths(root);
+    const resolver = new CsrDevResolver({
+      paths,
+      context,
+      entryFiles: [],
+      resolution: {
+        "shadow/Page.tsx": { "./Foo": "shadow/Foo/index.tsx" },
+        "pair/entry.ts": { "./x": "pair/x.js" },
+      },
+    });
+    expect(resolver.resolve(at("pair/entry.ts"), "./x", "require")).toBe(at("pair/x.js"));
+    expect(resolver.resolve(at("pair/entry.ts"), "./x")).toBe(at("pair/x.mjs"));
+    expect(resolver.resolve(at("shadow/Page.tsx"), "./Foo")).toBe(at("shadow/Foo/index.tsx"));
+    await Bun.write(at("shadow/Foo.tsx"), "export {};\n");
+    expect(resolver.resolve(at("shadow/Page.tsx"), "./Foo")).toBe(at("shadow/Foo.tsx"));
+  });
+
+  test("a sibling with a stronger extension takes over a recorded import", async () => {
+    const resolver = new CsrDevResolver({
+      paths: new CsrDevPaths(root),
+      context,
+      entryFiles: [],
+      resolution: { "sibling/Page.tsx": { "./x": "sibling/x.ts" } },
+    });
+    expect(resolver.resolve(at("sibling/Page.tsx"), "./x")).toBe(at("sibling/x.ts"));
+    await Bun.write(at("sibling/x.tsx"), "export {};\n");
+    expect(resolver.resolve(at("sibling/Page.tsx"), "./x")).toBe(at("sibling/x.tsx"));
+  });
+});

package/frontendBuild/csrDevResolver.ts

@@ -20,6 +20,10 @@ export interface CsrDevResolverOptions {
   context: CsrDevContext;
   entryFiles: string[];
   resolution?: Record<string, Record<string, string>>;
+  /** Specifiers per importer id whose recorded resolution came from Bun's runtime resolver, not the browser build. */
+  runtimeResolved?: Record<string, string[]>;
+  /** When this process began: a package installed after it is one Bun's resolver here has not seen. */
+  startedAt?: number;
 }
 
 //* Resolution comes from a plain browser build: Bun's runtime resolver ignores the `browser` condition and picks Node
@@ -31,12 +35,25 @@ export class CsrDevResolver {
   readonly #entryFiles: string[];
   readonly #resolution = new Map<string, Map<string, string>>();
   readonly #fallbacks = new Set<string>();
+  readonly #runtimeResolved = new Map<string, Set<string>>();
+  readonly #browserMaps = new Map<string, boolean>();
+  readonly #startedAt: number;
   #prepassDone = false;
 
-  constructor({ paths, context, entryFiles, resolution = {} }: CsrDevResolverOptions) {
+  constructor({
+    paths,
+    context,
+    entryFiles,
+    resolution = {},
+    runtimeResolved = {},
+    startedAt = Date.now() - process.uptime() * 1000,
+  }: CsrDevResolverOptions) {
     this.#paths = paths;
+    this.#startedAt = startedAt;
     this.#context = context;
     this.#entryFiles = entryFiles;
+    for (const [importer, specifiers] of Object.entries(runtimeResolved))
+      this.#runtimeResolved.set(paths.fileOf(importer), new Set(specifiers));
     for (const [importer, bySpecifier] of Object.entries(resolution))
       this.#resolution.set(
         paths.fileOf(importer),
@@ -59,9 +76,10 @@ export class CsrDevResolver {
 
   async prepass(): Promise<void> {
     const result = await Bun.build({
-      entrypoints: [...this.#entryFiles, this.#context.refreshFile],
+      entrypoints: [...this.#entryFiles, ...(this.#context.refreshFile ? [this.#context.refreshFile] : [])],
       target: "browser",
       metafile: true,
+      external: [...(this.#context.externals ?? [])],
       env: "AKAN_PUBLIC_*",
       define: this.#context.define,
       optimizeImports: this.#context.optimizeImports,
@@ -78,23 +96,39 @@ export class CsrDevResolver {
           continue;
         }
         const target = path.resolve(record.path);
-        if (fs.existsSync(target)) this.#remember(importer, record.original, CsrDevPaths.realpath(target));
+        if (!fs.existsSync(target)) continue;
+        this.#remember(importer, record.original, CsrDevPaths.realpath(target));
+        this.#runtimeResolved.get(importer)?.delete(record.original);
       }
     }
     this.#prepassDone = true;
   }
 
-  resolve(importer: string, specifier: string): string | null {
+  resolve(importer: string, specifier: string, kind: "import" | "require" = "import"): string | null {
     if (this.#isInlineSpecifier(specifier)) return CsrDevResolver.inline;
     const known = this.#resolution.get(importer)?.get(specifier);
-    const usable = known && (CsrDevPaths.isStub(known) || fs.existsSync(known)) ? known : null;
-    const target = usable ?? this.#resolveUnknown(importer, specifier);
+    const usable = known && this.#stillAnswers(importer, specifier, known, kind) ? known : null;
+    const target = usable ?? this.#resolveUnknown(importer, specifier, kind);
     if (target === null || CsrDevPaths.isStub(target)) return target;
     if (!CsrDevPaths.isScript(target)) return CsrDevResolver.inline;
     if (!usable) this.#remember(importer, specifier, target);
     return target;
   }
 
+  //? A relative record in app code stands while the disk still resolves it to the same file, as Bun would: a sibling
+  //? with a stronger extension (`x.tsx` beside `x.ts`), a file beside the folder it went into, or a record a CommonJS
+  //? re-export folded onto another file (`./a` → `x.js`) resolves anew. A package's files, and app code under a
+  //? package.json that maps files with a `browser` object, keep the prepass's answer, which a disk lookup would only
+  //? approximate.
+  #stillAnswers(importer: string, specifier: string, known: string, kind: "import" | "require"): boolean {
+    if (CsrDevPaths.isStub(known)) return true;
+    if (!fs.existsSync(known)) return false;
+    if (!specifier.startsWith(".") || CsrDevPaths.isVendorFile(importer)) return true;
+    if (this.#hasBrowserMap(path.dirname(importer))) return true;
+    const onDisk = CsrDevPaths.resolveRelative(path.dirname(importer), specifier, kind);
+    return onDisk !== null && CsrDevPaths.realpath(onDisk) === known;
+  }
+
   isRegistryModule(file: string): boolean {
     if (!CsrDevPaths.isScript(file)) return false;
     const packageName = CsrDevResolver.#packageNameOf(file);
@@ -105,42 +139,109 @@ export class CsrDevResolver {
     });
   }
 
+  #hasBrowserMap(dir: string): boolean {
+    const cached = this.#browserMaps.get(dir);
+    if (cached !== undefined) return cached;
+    const pkgFile = path.join(dir, "package.json");
+    const parent = path.dirname(dir);
+    let mapped: boolean;
+    if (fs.existsSync(pkgFile)) {
+      try {
+        const browser = (JSON.parse(fs.readFileSync(pkgFile, "utf8")) as { browser?: unknown }).browser;
+        mapped = typeof browser === "object" && browser !== null;
+      } catch {
+        // An unreadable package.json maps nothing; Bun's build fails on it anyway.
+        mapped = false;
+      }
+    } else mapped = parent !== dir && this.#hasBrowserMap(parent);
+    this.#browserMaps.set(dir, mapped);
+    return mapped;
+  }
+
+  /** A module that left the graph takes its records with it. */
+  forget(importer: string): void {
+    this.#resolution.delete(importer);
+    this.#runtimeResolved.delete(importer);
+  }
+
+  serializeRuntimeResolved(): Record<string, string[]> {
+    return Object.fromEntries(
+      [...this.#runtimeResolved]
+        .filter(([, specifiers]) => specifiers.size > 0)
+        .map(([importer, specifiers]) => [this.#paths.idOf(importer), [...specifiers].sort()]),
+    );
+  }
+
+  // A target moved away is left out, so the graph does not carry it past a builder restart.
   serialize(): Record<string, Record<string, string>> {
     return Object.fromEntries(
       [...this.#resolution].map(([importer, bySpecifier]) => [
         this.#paths.idOf(importer),
         Object.fromEntries(
-          [...bySpecifier].map(([specifier, target]) => [
-            specifier,
-            CsrDevPaths.isStub(target) ? target : this.#paths.idOf(target),
-          ]),
+          [...bySpecifier]
+            .filter(([, target]) => CsrDevPaths.isStub(target) || fs.existsSync(target))
+            .map(([specifier, target]) => [specifier, CsrDevPaths.isStub(target) ? target : this.#paths.idOf(target)]),
         ),
       ]),
     );
   }
 
-  #resolveUnknown(importer: string, specifier: string): string | null {
+  //? Bun.resolveSync keeps what it found per directory until a build walks that directory again, so in the resident
+  //? builder it may hand back a file moved away since (`Foo.tsx` → `Foo/index.tsx`, `.ts` → `.tsx`). A relative import
+  //? is therefore looked up on the disk as it is now, and a bare one it names a missing file for goes to a fresh worker.
+  #resolveUnknown(importer: string, specifier: string, kind: "import" | "require"): string | null {
     if (specifier.startsWith("node:")) return `${CsrDevPaths.stubPrefix}${specifier}`;
     const relative = specifier.startsWith(".") || path.isAbsolute(specifier);
-    if (!relative && !this.#prepassDone) return null;
-    if (!relative) {
-      const sibling = this.#resolvedBySibling(importer, specifier);
-      if (sibling) return sibling;
+    const cannotResolve = () => new Error(`[csr-dev] cannot resolve "${specifier}" from ${this.#paths.idOf(importer)}`);
+    if (relative) {
+      const onDisk =
+        CsrDevPaths.resolveRelative(path.dirname(importer), specifier, kind) ??
+        CsrDevResolver.#onDisk(CsrDevPaths.tryResolve(specifier, path.dirname(importer)));
+      if (!onDisk) throw cannotResolve();
+      return CsrDevPaths.realpath(onDisk);
     }
+    //? Ahead of the prepass too: a new file's bare imports (`akanjs/ui`, `@apps/<app>/client`) are ones its package
+    //? already resolved, and asking for the prepass would hand every such save to a build worker.
+    const sibling = this.#resolvedBySibling(importer, specifier);
+    if (sibling) return sibling;
     const resolved = CsrDevPaths.tryResolve(specifier, path.dirname(importer));
-    if (!resolved) throw new Error(`[csr-dev] cannot resolve "${specifier}" from ${this.#paths.idOf(importer)}`);
+    const moved = resolved !== null && path.isAbsolute(resolved) && !fs.existsSync(resolved);
+    //? Bun keeps a process's node_modules listings: a package installed while the builder runs (`bun add`) resolves only
+    //? in a fresh process, so one installed since this process began goes to a worker. Any other miss, a subpath typo
+    //? of a package installed long ago included, fails here as the worker would.
+    const installed =
+      resolved === null && CsrDevPaths.installedSince(specifier, path.dirname(importer), this.#startedAt);
+    if (!this.#prepassDone || moved) {
+      //? A specifier no resolver finds in the user's own code is a typo, failed here like a missing relative file: the
+      //? resolution build a worker would run for it fails the same way. A package's `browser` field may map one away.
+      if (resolved === null && !installed && !CsrDevPaths.isVendorFile(importer)) throw cannotResolve();
+      return null;
+    }
+    if (!resolved) {
+      if (installed) return null;
+      throw cannotResolve();
+    }
     if (!path.isAbsolute(resolved)) return `${CsrDevPaths.stubPrefix}${specifier}`;
-    if (!relative) this.#fallbacks.add(specifier);
+    this.#fallbacks.add(specifier);
+    this.#runtimeResolved.set(importer, (this.#runtimeResolved.get(importer) ?? new Set<string>()).add(specifier));
     return CsrDevPaths.realpath(resolved);
   }
 
+  static #onDisk(resolved: string | null): string | null {
+    return resolved && path.isAbsolute(resolved) && fs.existsSync(resolved) ? resolved : null;
+  }
+
   //? The browser build tree-shakes the unused re-exports of a side-effect-free barrel, so their imports have no
   //? recorded resolution; a file of the same package resolves a bare specifier to the same target, conditions included.
+  //? Not one the runtime resolver found (it ignores the `browser` condition the prepass exists to honour), not the
+  //? importer's own record, and not a target moved away since.
   #resolvedBySibling(importer: string, specifier: string): string | null {
     const scope = CsrDevResolver.#packageScopeOf(importer);
     for (const [other, bySpecifier] of this.#resolution) {
       const target = bySpecifier.get(specifier);
-      if (target && CsrDevResolver.#packageScopeOf(other) === scope) return target;
+      if (!target || other === importer || this.#runtimeResolved.get(other)?.has(specifier)) continue;
+      if (!CsrDevPaths.isStub(target) && !fs.existsSync(target)) continue;
+      if (CsrDevResolver.#packageScopeOf(other) === scope) return target;
     }
     return null;
   }

package/frontendBuild/csrDevTypes.ts

@@ -15,7 +15,13 @@ export interface CsrDevGraph {
   entries: Record<string, string>;
   modules: Record<string, CsrDevGraphModule>;
   resolution: Record<string, Record<string, string>>;
+  /** Specifiers per importer id `resolution` holds from Bun's runtime resolver rather than the browser build. */
+  runtimeResolved?: Record<string, string[]>;
   pending: string[];
+  /** A build worker's failed round: the ids it built, and the files it failed in or named, by hash. */
+  failed?: { roots: string[]; files: Record<string, string> };
+  /** The stamp of the signal and dictionary sources the last whole build inlined; see `RegistryMetadataFingerprint`. */
+  metadata?: string;
 }
 
 export interface CsrDevContext {
@@ -25,7 +31,10 @@ export interface CsrDevContext {
   define: Record<string, string>;
   optimizeImports: string[];
   configKey: string;
-  refreshFile: string;
+  /** Null when the page already loads the React Refresh runtime (an SSR page's import map). */
+  refreshFile: string | null;
+  /** Bare specifiers the page already loads (an SSR page's import map): required as `vendor:<specifier>`, not compiled. */
+  externals?: readonly string[];
 }
 
 export interface CsrDevSharedHelpers {
@@ -44,3 +53,9 @@ export interface CsrDevCompiledModule {
   mtimeMs: number;
   hash: string;
 }
+
+/** Module factories by id and helper definitions by hash, kept in memory so app.js is written without a pass over the disk. */
+export interface CsrDevCode {
+  modules: Map<string, string>;
+  helpers: Map<string, string>;
+}

package/frontendBuild/csrEntryFiles.ts

@@ -0,0 +1,24 @@
+import path from "node:path";
+import type { PageEntry } from "../artifact/implicitRootLayout";
+
+//* The CSR entry file of each basePath's HTML, shared by the CSR artifact and the dev registry. Apart from both
+//* builders so the resident dev builder names entries without loading the artifact builder's CSS compiler (tailwindcss).
+export class CsrEntryFiles {
+  static entryFilename(basePath: string): string {
+    return `${basePath || "index"}.csr.tsx`;
+  }
+
+  static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
+    return pageEntries.filter((entry) => {
+      const entryBasePath = CsrEntryFiles.basePathOfPageKey(entry.key, basePaths);
+      return entryBasePath === null || entryBasePath === basePath;
+    });
+  }
+
+  static basePathOfPageKey(pageKey: string, basePaths: string[]): string | null {
+    const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
+    const segments = normalized.split("/");
+    const firstPublicSegment = segments.find((segment) => segment !== "[lang]" && !/^\(.+\)$/.test(segment));
+    return firstPublicSegment && basePaths.includes(firstPublicSegment) ? firstPublicSegment : null;
+  }
+}

package/frontendBuild/cssCompiler.ts

@@ -5,6 +5,7 @@ import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
+import { CsrEntryFiles } from "./csrEntryFiles";
 import { CssCandidateCache } from "./cssCandidateCache";
 import { CssImportResolver } from "./cssImportResolver";
 
@@ -393,8 +394,5 @@ export function declaredCustomProperties(css: string): string[] {
 }
 
 export function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
-  const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
-  const segments = normalized.split("/");
-  const firstPublicSegment = segments.find((segment) => segment !== "[lang]" && !/^\(.+\)$/.test(segment));
-  return firstPublicSegment && basePaths.includes(firstPublicSegment) ? firstPublicSegment : null;
+  return CsrEntryFiles.basePathOfPageKey(pageKey, basePaths);
 }