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

package/frontendBuild/csrDevArtifactWriter.ts

@@ -1,28 +1,62 @@
-import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import fs from "node:fs";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import {
+  appGenerationOf,
   CSR_DEV_APP_FILE,
+  CSR_DEV_KEPT_PATCHES,
   CSR_DEV_MANIFEST_FILE,
-  CSR_DEV_ROUTE_PREFIX,
+  CSR_DEV_PATCHING_MARKER,
   type CsrDevLayout,
   type CsrDevManifest,
   csrDevModuleFile,
 } from "akanjs/server/hmr/csrDevManifest";
+import { FileSys } from "../fileSys";
 import { CsrDevPaths } from "./csrDevPaths";
-import type { CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevCode, CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+
+export interface CsrDevArtifactWriterOptions {
+  /** Where the dev server serves `outDir`; a patch is announced by its URL. */
+  routePrefix: string;
+  /** `app.js` starts no entry: an SSR page requires the modules its RSC payload names, one at a time. */
+  library?: boolean;
+}
 
 export class CsrDevArtifactWriter {
-  static readonly #keptPatches = 40;
   static readonly #keptVendors = 3;
+  static readonly #buildingMarker = ".building";
   readonly #outDir: string;
+  readonly #routePrefix: string;
+  readonly #library: boolean;
 
-  constructor(outDir: string) {
+  constructor(outDir: string, { routePrefix, library = false }: CsrDevArtifactWriterOptions) {
     this.#outDir = outDir;
+    this.#routePrefix = routePrefix;
+    this.#library = library;
   }
 
-  async reset(): Promise<void> {
-    await rm(this.#outDir, { recursive: true, force: true });
-    await mkdir(path.join(this.#outDir, "modules"), { recursive: true });
+  //? Set between a whole build's first write and its last: module files are named by id and overwritten in place, so a
+  //? build cut short there leaves new modules under the previous graph and app.js, which no patch may read.
+  async markBuilding(): Promise<void> {
+    await Bun.write(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker), String(process.pid));
+  }
+
+  async clearBuilding(): Promise<void> {
+    await CsrDevArtifactWriter.#remove(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker));
+  }
+
+  async isBuilding(): Promise<boolean> {
+    return await Bun.file(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker)).exists();
+  }
+
+  //? A reload's generation has no patch: one an attempt cut short left under that number would be applied by a tab
+  //? catching up (catchUp reloads only when the file is missing).
+  async forgetPatch(generation: number): Promise<void> {
+    await Promise.all(
+      [`patch-${generation}.js`, `patch-${generation}.js.layout.json`].map((name) =>
+        CsrDevArtifactWriter.#remove(path.join(this.#outDir, name)),
+      ),
+    );
   }
 
   async readJson<T>(name: string): Promise<T | null> {
@@ -49,11 +83,26 @@ export class CsrDevArtifactWriter {
     ]);
   }
 
+  //? A module whose file is missing is left out rather than failing the read: the patcher compiles it again.
+  async readCode(graph: CsrDevGraph): Promise<CsrDevCode> {
+    const ids = Object.keys(graph.modules).filter((id) => !graph.modules[id]?.vendor && this.hasModule(id));
+    const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))];
+    const [modules, helpers] = await Promise.all([
+      Promise.all(ids.map(async (id) => [id, await Bun.file(this.#modulePath(id, ".js")).text()] as const)),
+      Promise.all(hashes.map(async (hash) => [hash, await Bun.file(this.#helpersPath(hash)).text()] as const)),
+    ]);
+    return { modules: new Map(modules), helpers: new Map(helpers) };
+  }
+
+  hasModule(id: string): boolean {
+    return fs.existsSync(this.#modulePath(id, ".js"));
+  }
+
   async forgetModules(ids: string[]): Promise<void> {
     await Promise.all(
       ids.flatMap((id) => [
-        rm(this.#modulePath(id, ".js"), { force: true }),
-        rm(this.#modulePath(id, ".js.map"), { force: true }),
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js")),
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js.map")),
       ]),
     );
   }
@@ -76,14 +125,22 @@ export class CsrDevArtifactWriter {
     return vendorFile;
   }
 
-  async writeApp(graph: CsrDevGraph, generation: number): Promise<void> {
+  //? A library app.js names the vendor file and epoch it was built with: a tab that booted it beside another build's
+  //? vendor file (a whole build landing between its render and its load) tells, and keeps the right epoch for hello.
+  async writeApp(
+    graph: CsrDevGraph,
+    { generation, vendorFile, epoch }: Pick<CsrDevManifest, "generation" | "vendorFile" | "epoch">,
+    code?: CsrDevCode,
+  ): Promise<void> {
     const ids = Object.keys(graph.modules)
       .filter((id) => !graph.modules[id]?.vendor)
       .sort();
-    const lines = await this.#defineLines(ids);
+    const lines = await this.#defineLines(ids, code);
     const blocks = ids.map((id, index) => [id, lines[index] ?? ""] as [string, string]);
-    const start = `__akan.start(${JSON.stringify({ generation, refresh: graph.refresh })});\n`;
-    await this.#writeWithSourceMap(CSR_DEV_APP_FILE, await this.#helperDefinitions(graph, ids), blocks, start);
+    const start = this.#library
+      ? `__akan.startLibrary(${JSON.stringify({ generation, refresh: graph.refresh, bootstrap: graph.entries[""], vendorFile, epoch })});\n`
+      : `__akan.start(${JSON.stringify({ generation, refresh: graph.refresh })});\n`;
+    await this.#writeWithSourceMap(CSR_DEV_APP_FILE, await this.#helperDefinitions(graph, ids, code), blocks, start);
   }
 
   async writePatch(generation: number, modules: CsrDevCompiledModule[]): Promise<string> {
@@ -100,7 +157,7 @@ export class CsrDevArtifactWriter {
     );
     const header = `${[...helpers.values()].map((shared) => shared.definition).join("")}__akan.update(${generation}, {\n`;
     await this.#writeWithSourceMap(patchFile, header, blocks, "});\n");
-    return `${CSR_DEV_ROUTE_PREFIX}${patchFile}`;
+    return `${this.#routePrefix}${patchFile}`;
   }
 
   // The manifest goes last: the server renders shells from it, so it must never name a file not yet written.
@@ -109,11 +166,39 @@ export class CsrDevArtifactWriter {
     await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
   }
 
+  //? The open tabs need only the patch file and the manifest naming it, so they hear of a patch before the rest lands:
+  //? the module files and graph.json (read only by the next build), then app.js (a full rewrite). The manifest says
+  //? which generation app.js holds, and the shell holds a tab booting in that gap until it does. A crash in the gap is
+  //? recovered by the next build, which sees the edited files' mtimes differ from graph.json and compiles them again.
+  async commitPatch(
+    graph: CsrDevGraph,
+    manifest: CsrDevManifest,
+    announce: () => void,
+    { modules, code }: { modules: CsrDevCompiledModule[]; code?: CsrDevCode },
+  ): Promise<void> {
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
+    announce();
+    await CsrDevArtifactWriter.#appWriteDelay();
+    await this.writeModules(modules);
+    await this.writeJson("graph.json", graph);
+    await this.writeApp(graph, manifest, code);
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, { ...manifest, appGeneration: manifest.generation });
+  }
+
+  // A process that died between announcing a patch and rewriting app.js left every booting tab one generation behind.
+  async healApp(graph: CsrDevGraph, manifest: CsrDevManifest, code?: CsrDevCode): Promise<CsrDevManifest> {
+    if (appGenerationOf(manifest) >= manifest.generation) return manifest;
+    await this.writeApp(graph, manifest, code);
+    const healed = { ...manifest, appGeneration: manifest.generation };
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, healed);
+    return healed;
+  }
+
   async prune(vendorFile: string, generation: number): Promise<void> {
     const names = await readdir(this.#outDir);
     const stale = names.filter((name) => {
       const patch = /^patch-(\d+)\.js(?:\.layout\.json)?$/.exec(name);
-      return patch ? Number(patch[1]) <= generation - CsrDevArtifactWriter.#keptPatches : false;
+      return patch ? Number(patch[1]) <= generation - CSR_DEV_KEPT_PATCHES : false;
     });
     const vendors = names
       .filter((name) => /^vendor-[\w-]+\.js$/.test(name) && name !== vendorFile)
@@ -121,19 +206,55 @@ export class CsrDevArtifactWriter {
       .sort((a, b) => b.mtimeMs - a.mtimeMs)
       .slice(CsrDevArtifactWriter.#keptVendors - 1)
       .map(({ name }) => name);
-    await Promise.all([...stale, ...vendors].map((name) => rm(path.join(this.#outDir, name), { force: true })));
+    await Promise.all(
+      [...stale, ...vendors].map((name) => CsrDevArtifactWriter.#remove(path.join(this.#outDir, name))),
+    );
   }
 
-  async #helperDefinitions(graph: CsrDevGraph, ids: string[]): Promise<string> {
+  //? A whole build writes over the registry before it instead of clearing it first, so it clears what that one left:
+  //? the modules and helpers it no longer holds, every patch (each was made against the previous registry), the assets
+  //? this build did not write (by path: a file's mtime and this process's clock need not agree on a mounted volume),
+  //? temp files of a write cut short, and the marker of a builder that died mid-patch.
+  async pruneAfterFullBuild(
+    graph: CsrDevGraph,
+    vendorFile: string,
+    { generation, assets }: { generation: number; assets: string[] },
+  ): Promise<void> {
+    const kept = new Set(
+      Object.keys(graph.modules).flatMap((id) => [this.#modulePath(id, ".js"), this.#modulePath(id, ".js.map")]),
+    );
+    for (const module of Object.values(graph.modules)) if (module.helpers) kept.add(this.#helpersPath(module.helpers));
+    for (const asset of assets) kept.add(path.resolve(asset));
+    const listed = async (dir: string) =>
+      (await readdir(path.join(this.#outDir, dir)).catch(() => [] as string[])).map((name) =>
+        path.join(this.#outDir, dir, name),
+      );
+    const stale = [
+      ...(await listed("modules")).filter((file) => !kept.has(file)),
+      ...(await listed("assets")).filter((file) => !kept.has(file)),
+      ...(await listed(".")).filter((file) => {
+        const name = path.basename(file);
+        return /^patch-\d+\.js(?:\.layout\.json)?$/.test(name) || name.endsWith(".tmp");
+      }),
+      path.join(this.#outDir, CSR_DEV_PATCHING_MARKER),
+    ];
+    await Promise.all(stale.map((file) => CsrDevArtifactWriter.#remove(file)));
+    await this.prune(vendorFile, generation);
+  }
+
+  async #helperDefinitions(graph: CsrDevGraph, ids: string[], code?: CsrDevCode): Promise<string> {
     const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))].sort();
-    return (await Promise.all(hashes.map((hash) => Bun.file(this.#helpersPath(hash)).text()))).join("");
+    return (
+      await Promise.all(hashes.map(async (hash) => code?.helpers.get(hash) ?? Bun.file(this.#helpersPath(hash)).text()))
+    ).join("");
   }
 
-  async #defineLines(ids: string[]): Promise<string[]> {
+  async #defineLines(ids: string[], code?: CsrDevCode): Promise<string[]> {
     return await Promise.all(
-      ids.map(
-        async (id) => `__akan.define(${JSON.stringify(id)}, ${await Bun.file(this.#modulePath(id, ".js")).text()});\n`,
-      ),
+      ids.map(async (id) => {
+        const factory = code?.modules.get(id) ?? (await Bun.file(this.#modulePath(id, ".js")).text());
+        return `__akan.define(${JSON.stringify(id)}, ${factory});\n`;
+      }),
     );
   }
 
@@ -156,7 +277,20 @@ export class CsrDevArtifactWriter {
     const target = path.join(this.#outDir, name);
     const temp = `${target}.${process.pid}.tmp`;
     await Bun.write(temp, content);
-    await rename(temp, target);
+    await FileSys.replace(temp, target);
+  }
+
+  //? Best effort, after the tabs already have the update: Windows refuses to delete a file a reader holds open (the
+  //? server streaming it to a tab), and throwing here would send a patch that already went out to a build worker.
+  //? A file that stays is removed by a later prune.
+  static async #remove(file: string): Promise<void> {
+    await rm(file, { force: true }).catch(() => undefined);
+  }
+
+  //? A test-only hook that widens the gap between the patch and app.js, so an E2E can boot a tab inside it.
+  static async #appWriteDelay(): Promise<void> {
+    const ms = Number(process.env.AKAN_CSR_DEV_APP_WRITE_DELAY_MS);
+    if (Number.isInteger(ms) && ms > 0) await Bun.sleep(ms);
   }
 
   #modulePath(id: string, extension: ".js" | ".js.map"): string {

package/frontendBuild/csrDevBundler.ts

@@ -1,66 +1,34 @@
-import fs from "node:fs";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { CSR_DEV_DIRNAME, CSR_DEV_MANIFEST_FILE, type CsrDevManifest } from "akanjs/server/hmr/csrDevManifest";
-import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import { CSR_DEV_DIRNAME, CSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 import { bundleDefine } from "./bundleDefine";
-import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
-import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
 import { CsrDevPaths } from "./csrDevPaths";
-import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevContext } from "./csrDevTypes";
+import { CsrEntryFiles } from "./csrEntryFiles";
+import { DevRegistryBundler } from "./devRegistryBundler";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
-export interface CsrDevUpdate {
-  generation: number;
-  reload: boolean;
-  reason?: string;
-  patchUrl?: string;
-  changedIds: string[];
-  moduleCount: number;
-}
-
-//* Dev-only CSR as a module registry. The build worker is a fresh process per save, so the graph, every module's
-//* factory and the resolutions live on disk under `.akan/artifact/csr-dev`.
-export class CsrDevBundler {
+//* Dev-only CSR as a module registry, under `.akan/artifact/csr-dev`: one entry per basePath boots every page.
+export class CsrDevBundler extends DevRegistryBundler {
   static readonly #formatVersion = 3;
-  readonly #app: App;
-  readonly #paths: CsrDevPaths;
-  readonly #outDir: string;
-  readonly #entryDir: string;
-  readonly #writer: CsrDevArtifactWriter;
+  readonly reloadsOnEntryChange = true;
+  //? Detecting a page's async default parses it with TypeScript: on apps/akan every page each save cost ~100ms.
+  readonly #asyncDefaults = new Map<string, { mtimeMs: number; detected: Promise<boolean> }>();
 
   constructor(app: App) {
-    this.#app = app;
-    this.#paths = new CsrDevPaths(app.workspace.workspaceRoot);
-    this.#outDir = path.join(app.cwdPath, ".akan/artifact", CSR_DEV_DIRNAME);
-    this.#entryDir = path.join(app.cwdPath, ".akan/generated", CSR_DEV_DIRNAME);
-    this.#writer = new CsrDevArtifactWriter(this.#outDir);
+    super(app, { dirName: CSR_DEV_DIRNAME, routePrefix: CSR_DEV_ROUTE_PREFIX, library: false });
   }
 
-  async update(changedFiles: string[] = []): Promise<CsrDevUpdate | null> {
-    const context = await this.#context();
-    if (context.pageEntries.length === 0) return null;
-    const manifest = await this.#writer.readJson<CsrDevManifest>(CSR_DEV_MANIFEST_FILE);
-    const graph = await this.#writer.readJson<CsrDevGraph>("graph.json");
-    const generation = (manifest?.generation ?? 0) + 1;
-    if (!manifest || !graph || graph.version !== 1 || graph.configKey !== context.configKey)
-      return await this.#fullBuild(context, generation, manifest ? "the dev bundle config changed" : "first build");
-    const metadataFile = changedFiles.find(isAkanRuntimeMetadataFile);
-    // `lib/useClient.ts` inlines signal and dictionary metadata through a macro at build time.
-    if (metadataFile) return await this.#fullBuild(context, generation, `${path.basename(metadataFile)} changed`);
-    return await this.#incrementalBuild(context, graph, manifest, changedFiles, generation);
-  }
-
-  async #context(): Promise<CsrDevContext> {
-    const akanConfig = await this.#app.getConfig();
-    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys());
+  async context(): Promise<CsrDevContext | null> {
+    const akanConfig = await this.app.getConfig();
+    const pageEntries = await resolveSsrPageEntriesForApp(this.app, await this.app.getPageKeys());
+    if (pageEntries.length === 0) return null;
     const basePaths = [...akanConfig.basePaths];
     const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
-    const define = bundleDefine(this.#app, "start", "csr");
+    const define = bundleDefine(this.app, "start", "csr");
     const optimizeImports = [...akanConfig.optimizeImports];
     const configKey = Bun.hash(
       JSON.stringify([CsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, htmlBasePaths]),
@@ -76,152 +44,21 @@ export class CsrDevBundler {
     };
   }
 
-  #resolveRefreshRuntime(): string {
-    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.#app.cwdPath);
-    const bases = [
-      this.#app.cwdPath,
-      this.#paths.root,
-      ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : []),
-    ];
-    for (const base of bases) {
-      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
-      if (resolved) return CsrDevPaths.realpath(resolved);
-    }
-    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
-  }
-
-  async #fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
-    await this.#writer.reset();
-    const entries = await this.#writeEntries(context);
-    const entryFiles = Object.values(entries.files);
-    const resolver = new CsrDevResolver({ paths: this.#paths, context, entryFiles });
-    await resolver.prepass();
-    const compiled = await this.#compiler(context, resolver).compile([...entryFiles, context.refreshFile], new Set());
-    const graph: CsrDevGraph = {
-      version: 1,
-      configKey: context.configKey,
-      refresh: this.#paths.idOf(context.refreshFile),
-      entries: this.#entryIds(entries.files),
-      modules: {},
-      resolution: {},
-      pending: [],
-    };
-    this.#merge(graph, resolver, compiled);
-    await this.#writer.writeModules(compiled);
-    const vendorFile = await this.#writer.writeVendor(graph);
-    await this.#writer.writeApp(graph, generation);
-    await this.#writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries });
-    await this.#writer.prune(vendorFile, generation);
-    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length };
-  }
-
-  async #incrementalBuild(
-    context: CsrDevContext,
-    graph: CsrDevGraph,
-    manifest: CsrDevManifest,
-    changedFiles: string[],
-    generation: number,
-  ): Promise<CsrDevUpdate | null> {
-    const entries = await this.#writeEntries(context);
-    const entryIds = this.#entryIds(entries.files);
-    await this.#forgetDeletedModules(graph);
-    const changed = await this.#changedModules(graph, changedFiles);
-    for (const file of entries.changed) changed.add(this.#paths.idOf(file));
-    const routesMoved = entries.changed.length > 0 || JSON.stringify(entryIds) !== JSON.stringify(graph.entries);
-    if (changed.size === 0) return null;
-
-    const resolver = new CsrDevResolver({
-      paths: this.#paths,
-      context,
-      entryFiles: Object.values(entries.files),
-      resolution: graph.resolution,
-    });
-    const known = new Set(Object.keys(graph.modules).map((id) => this.#paths.fileOf(id)));
-    let compiled: CsrDevCompiledModule[];
-    try {
-      compiled = await this.#compiler(context, resolver).compile(
-        [...changed].map((id) => this.#paths.fileOf(id)),
-        known,
-      );
-    } catch (error) {
-      graph.pending = [...changed];
-      await this.#writer.writeJson("graph.json", graph);
-      throw error;
-    }
-    const vendorJoined = compiled.some((module) => module.vendor && !graph.modules[module.id]);
-    this.#merge(graph, resolver, compiled);
-    graph.entries = entryIds;
-    await this.#writer.writeModules(compiled);
-    const vendorFile = vendorJoined ? await this.#writer.writeVendor(graph) : manifest.vendorFile;
-    await this.#writer.writeApp(graph, generation);
-    const changedIds = compiled.filter((module) => !module.vendor).map((module) => module.id);
-    const constantId = changedIds.find((id) => id.endsWith(".constant.ts"));
-    // A model class swapped under live store state would mix old and new instances; reload instead.
-    const reason = vendorJoined
-      ? "an npm module joined the graph"
-      : routesMoved
-        ? "the route table changed"
-        : constantId
-          ? `${path.basename(constantId)} changed`
-          : undefined;
-    const patchUrl = reason
-      ? undefined
-      : await this.#writer.writePatch(
-          generation,
-          compiled.filter((module) => !module.vendor),
-        );
-    await this.#writer.writeState(graph, { ...manifest, generation, vendorFile, entries: entryIds });
-    await this.#writer.prune(vendorFile, generation);
-    return {
-      generation,
-      reload: !!reason,
-      reason,
-      patchUrl,
-      changedIds,
-      moduleCount: Object.keys(graph.modules).length,
-    };
-  }
-
-  async #changedModules(graph: CsrDevGraph, changedFiles: string[]): Promise<Set<string>> {
-    const changed = new Set<string>(graph.pending.filter((id) => graph.modules[id]));
-    for (const file of changedFiles) {
-      const id = this.#paths.idOf(file);
-      if (graph.modules[id]) changed.add(id);
-    }
-    // Stat, not trust: a save made while CSR was unarmed, or a build that failed, never reached this graph. The hash
-    // settles it because route discovery rewrites the generated layout wrappers, touching them on every call.
-    for (const [id, module] of Object.entries(graph.modules)) {
-      if (module.vendor || changed.has(id)) continue;
-      const file = this.#paths.fileOf(id);
-      if (CsrDevPaths.mtimeOf(file) === module.mtimeMs) continue;
-      if ((await CsrDevPaths.hashOf(file)) !== module.hash) changed.add(id);
-    }
-    return changed;
-  }
-
-  // A deleted module leaves the graph instead of being rebuilt: rebuilding a missing file fails every save after it.
-  // An importer that still names it fails on its own rebuild, with the resolution error that says why.
-  async #forgetDeletedModules(graph: CsrDevGraph): Promise<void> {
-    const deleted = Object.keys(graph.modules).filter(
-      (id) => !graph.modules[id]?.vendor && !fs.existsSync(this.#paths.fileOf(id)),
-    );
-    for (const id of deleted) delete graph.modules[id];
-    await this.#writer.forgetModules(deleted);
-  }
-
-  async #writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
-    await mkdir(this.#entryDir, { recursive: true });
+  async writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.entryDir, { recursive: true });
     const files: Record<string, string> = {};
     const changed: string[] = [];
     for (const basePath of context.htmlBasePaths) {
-      const file = path.join(this.#entryDir, CsrArtifactBuilder.entryFilename(basePath));
-      const entryPages = CsrArtifactBuilder.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
-      const generator = new PagesEntrySourceGenerator(entryPages);
-      const pages = await generator.generateStatic({ fromDir: this.#entryDir });
+      const file = path.join(this.entryDir, CsrEntryFiles.entryFilename(basePath));
+      const entryPages = CsrEntryFiles.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
+      const generator = new PagesEntrySourceGenerator(entryPages, {
+        isAsyncDefault: (moduleAbsPath) => this.#isAsyncDefault(moduleAbsPath),
+      });
+      const pages = await generator.generateStatic({ fromDir: this.entryDir });
       const hot = await generator.generateHotReplace({
-        fromDir: this.#entryDir,
-        ownerId: this.#paths.idOf(file),
-        moduleIds: entryPages.map(({ moduleAbsPath }) => this.#paths.idOf(moduleAbsPath)),
+        fromDir: this.entryDir,
+        ownerId: this.paths.idOf(file),
+        moduleIds: entryPages.map(({ moduleAbsPath }) => this.paths.idOf(moduleAbsPath)),
       });
       const source = `import * as akanWebkit from "akanjs/webkit";\n${pages}\nvoid akanWebkit.bootCsr(pages);\n${hot}`;
       const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
@@ -233,24 +70,26 @@ export class CsrDevBundler {
     return { files, changed };
   }
 
-  #compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
-    return new CsrDevModuleCompiler({ app: this.#app, paths: this.#paths, resolver, context, outDir: this.#outDir });
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return entryFiles;
   }
 
-  #merge(graph: CsrDevGraph, resolver: CsrDevResolver, compiled: CsrDevCompiledModule[]): void {
-    for (const module of compiled)
-      graph.modules[module.id] = {
-        vendor: module.vendor,
-        mtimeMs: module.mtimeMs,
-        hash: module.hash,
-        deps: module.deps.map((dep) => (CsrDevPaths.isStub(dep) ? dep : this.#paths.idOf(dep))),
-        ...(module.helpers ? { helpers: module.helpers.hash } : {}),
-      };
-    graph.pending = [];
-    graph.resolution = resolver.serialize();
+  #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
+    const mtimeMs = CsrDevPaths.mtimeOf(moduleAbsPath);
+    const cached = this.#asyncDefaults.get(moduleAbsPath);
+    if (cached?.mtimeMs === mtimeMs) return cached.detected;
+    const detected = AsyncDefaultExportDetector.detect(moduleAbsPath);
+    this.#asyncDefaults.set(moduleAbsPath, { mtimeMs, detected });
+    return detected;
   }
 
-  #entryIds(files: Record<string, string>): Record<string, string> {
-    return Object.fromEntries(Object.entries(files).map(([basePath, file]) => [basePath, this.#paths.idOf(file)]));
+  #resolveRefreshRuntime(): string {
+    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.app.cwdPath);
+    const bases = [this.app.cwdPath, this.paths.root, ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : [])];
+    for (const base of bases) {
+      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
+      if (resolved) return CsrDevPaths.realpath(resolved);
+    }
+    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
   }
 }

package/frontendBuild/csrDevModuleCompiler.test.ts

@@ -0,0 +1,89 @@
+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 type { App } from "../commandDecorators";
+import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
+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,
+};
+
+//? esbuild's own interop helpers, as a pre-bundled chunk ships them (@mermaid-js/parser's dist/chunks).
+const prebundled = `var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
+var parts = {};
+__reExport(parts, { a: 1 });
+var wrapped = __toESM({ b: 2 });
+export { parts, wrapped };
+`;
+
+describe("CsrDevModuleCompiler", () => {
+  let root: string;
+  const file = (relative: string) => path.join(root, relative);
+  const compile = async (relative: string) => {
+    const paths = new CsrDevPaths(root);
+    const compiler = new CsrDevModuleCompiler({
+      app: { verbose: () => undefined } as unknown as App,
+      paths,
+      resolver: new CsrDevResolver({ paths, context, entryFiles: [] }),
+      context,
+      outDir: file("out"),
+      routePrefix: "/_akan/registry/",
+    });
+    return await compiler.compile([file(relative)], new Set());
+  };
+
+  beforeAll(async () => {
+    root = CsrDevPaths.realpath(await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-compiler-")));
+    await Bun.write(file("node_modules/prebundled/chunk.mjs"), prebundled);
+    await Bun.write(file("node_modules/bare-reexport/index.mjs"), "export const parts = __reExport({}, { a: 1 });\n");
+    await Bun.write(file("node_modules/bare-toesm/index.mjs"), "export const wrapped = __toESM({ b: 2 });\n");
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("a pre-bundled file keeps its own __reExport and __toESM, which Bun leaves in place of its own", async () => {
+    const { modules } = await compile("node_modules/prebundled/chunk.mjs");
+    const [module] = modules;
+    expect(module?.id).toBe("node_modules/prebundled/chunk.mjs");
+    const factory = module?.factory ?? "";
+    expect(factory).toContain("var __reExport = (target, mod, secondTarget) => (");
+    expect(factory).toContain("var __toESM = (mod, isNodeMode, target) => (");
+    expect(factory).not.toContain("__akan.reExport");
+    expect(factory).not.toContain("__akan.toESM");
+    expect(() => new Function(`return (${factory});`)).not.toThrow();
+  });
+
+  test.each([
+    ["__reExport", "node_modules/bare-reexport/index.mjs"],
+    ["__toESM", "node_modules/bare-toesm/index.mjs"],
+  ])("a %s call with no definition anywhere still stops the build", async (name, relative) => {
+    await expect(compile(relative)).rejects.toThrow(`Bun's ${name} helper no longer reads`);
+  });
+});