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

package/frontendBuild/csrDevModuleCompiler.ts

@@ -0,0 +1,262 @@
+import path from "node:path";
+import { CSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
+import type { BunPlugin } from "bun";
+import type { App } from "../commandDecorators";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevCompiledModule, CsrDevContext, CsrDevSharedHelpers } from "./csrDevTypes";
+import { RouteClientBuilder } from "./routeClientBuilder";
+
+interface OutputMetafile {
+  outputs: Record<string, { entryPoint?: string; inputs: Record<string, unknown> }>;
+}
+
+interface BuildRound {
+  modules: CsrDevCompiledModule[];
+  misses: string[];
+  tangled: string[];
+}
+
+export interface CsrDevModuleCompilerOptions {
+  app: App;
+  paths: CsrDevPaths;
+  resolver: CsrDevResolver;
+  context: CsrDevContext;
+  outDir: string;
+}
+
+//* Every module becomes its own CJS factory: one Bun.build with each import external, so a save re-runs only the
+//* modules it changed instead of reloading one scope-hoisted file.
+export class CsrDevModuleCompiler {
+  static readonly #storeRoot = /(?:^|\/)lib\/st\.ts$/;
+  static readonly #factoryArgument =
+    /(?<![\w$.])(?:require|module|exports|__akanImport|\$RefreshReg\$|\$RefreshSig\$)(?![\w$]|\s*:)/;
+  static readonly #helperPatches = [
+    ["__toESM", "(mod, isNodeMode, target)", "toESM"],
+    ["__reExport", "(target, mod, secondTarget)", "reExport"],
+  ] as const;
+  readonly #app: App;
+  readonly #paths: CsrDevPaths;
+  readonly #resolver: CsrDevResolver;
+  readonly #context: CsrDevContext;
+  readonly #outDir: string;
+
+  constructor({ app, paths, resolver, context, outDir }: CsrDevModuleCompilerOptions) {
+    this.#app = app;
+    this.#paths = paths;
+    this.#resolver = resolver;
+    this.#context = context;
+    this.#outDir = outDir;
+  }
+
+  async compile(startFiles: string[], known: Set<string>): Promise<CsrDevCompiledModule[]> {
+    const compiled = new Map<string, CsrDevCompiledModule>();
+    const seen = new Set([...known, ...startFiles]);
+    let frontier = [...new Set(startFiles)];
+    while (frontier.length > 0) {
+      const round = await this.#compileRound(frontier);
+      if (round.misses.length > 0 && !this.#resolver.prepassDone) {
+        this.#app.verbose(`[csr-dev] ${round.misses.length} unresolved import(s); rerunning the resolution build`);
+        await this.#resolver.prepass();
+        continue;
+      }
+      const next: string[] = [];
+      for (const module of round.modules) {
+        compiled.set(module.file, module);
+        for (const dep of module.deps) {
+          if (CsrDevPaths.isStub(dep) || seen.has(dep)) continue;
+          seen.add(dep);
+          next.push(dep);
+        }
+      }
+      frontier = next;
+    }
+    const { fallbacks } = this.#resolver;
+    if (fallbacks.size > 0)
+      this.#app.verbose(
+        `[csr-dev] ${fallbacks.size} import(s) outside the browser build's graph resolved with Bun's runtime resolver: ${[...fallbacks].slice(0, 5).join(", ")}${fallbacks.size > 5 ? ", ..." : ""}`,
+      );
+    return [...compiled.values()];
+  }
+
+  async #compileRound(files: string[]): Promise<Omit<BuildRound, "tangled">> {
+    const appFiles = files.filter((file) => !CsrDevPaths.isVendorFile(file));
+    const vendorFiles = files.filter((file) => CsrDevPaths.isVendorFile(file));
+    const rounds = await Promise.all([
+      appFiles.length > 0 ? this.#bunBuild(appFiles, false) : null,
+      vendorFiles.length > 0 ? this.#bunBuild(vendorFiles, true) : null,
+    ]);
+    const modules = rounds.flatMap((round) => round?.modules ?? []);
+    const misses = rounds.flatMap((round) => round?.misses ?? []);
+    // One entrypoint per build cannot inline another: Bun ignores an external for an absolute import of an entrypoint.
+    for (const file of rounds.flatMap((round) => round?.tangled ?? [])) {
+      const single = await this.#bunBuild([file], CsrDevPaths.isVendorFile(file));
+      if (single.tangled.length > 0)
+        throw new Error(`[csr-dev] ${this.#paths.idOf(file)} kept inlining another module`);
+      modules.push(...single.modules);
+      misses.push(...single.misses);
+    }
+    return { modules, misses };
+  }
+
+  async #bunBuild(files: string[], vendor: boolean): Promise<BuildRound> {
+    const mtimes = new Map(files.map((file) => [file, CsrDevPaths.mtimeOf(file)]));
+    const hashes = new Map(
+      await Promise.all(files.map(async (file) => [file, vendor ? "" : await CsrDevPaths.hashOf(file)] as const)),
+    );
+    const misses: string[] = [];
+    const result = await Bun.build({
+      entrypoints: files,
+      root: this.#paths.root,
+      target: "browser",
+      format: "cjs",
+      reactFastRefresh: !vendor,
+      sourcemap: vendor ? "none" : "external",
+      naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
+      publicPath: CSR_DEV_ROUTE_PREFIX,
+      metafile: true,
+      env: "AKAN_PUBLIC_*",
+      define: this.#context.define,
+      optimizeImports: this.#context.optimizeImports,
+      plugins: [this.#registryPlugin(vendor, misses)],
+    });
+    const { outputs } = result.metafile as unknown as OutputMetafile;
+    const sourceMaps = new Map(
+      result.outputs.filter((artifact) => artifact.kind === "sourcemap").map((artifact) => [artifact.path, artifact]),
+    );
+    const modules: CsrDevCompiledModule[] = [];
+    const tangled: string[] = [];
+    for (const artifact of result.outputs) {
+      if (artifact.kind === "asset") {
+        await Bun.write(path.join(this.#outDir, artifact.path), artifact);
+        continue;
+      }
+      if (artifact.kind !== "entry-point") continue;
+      const meta = outputs[artifact.path];
+      if (!meta?.entryPoint) throw new Error(`[csr-dev] no entry point recorded for ${artifact.path}`);
+      const file = CsrDevPaths.realpath(path.resolve(meta.entryPoint));
+      const inputs = Object.keys(meta.inputs).map((input) => CsrDevPaths.realpath(path.resolve(input)));
+      if (inputs.some((input) => input !== file && this.#resolver.isRegistryModule(input))) {
+        tangled.push(file);
+        continue;
+      }
+      const code = await artifact.text();
+      const id = this.#paths.idOf(file);
+      const sourceMap = sourceMaps.get(`${artifact.path}.map`);
+      modules.push({
+        id,
+        file,
+        vendor,
+        ...CsrDevModuleCompiler.#factory(id, code),
+        sourceMap: sourceMap ? this.#rebaseSourceMap(await sourceMap.text()) : undefined,
+        deps: this.#emittedDeps(code),
+        mtimeMs: mtimes.get(file) ?? CsrDevPaths.mtimeOf(file),
+        hash: hashes.get(file) ?? "",
+      });
+    }
+    return { modules, misses, tangled };
+  }
+
+  #registryPlugin(vendor: boolean, misses: string[]): BunPlugin {
+    return {
+      name: "akan-csr-registry",
+      setup: (build) => {
+        build.onLoad({ filter: /\.css$/ }, () => ({ contents: "", loader: "js" }));
+        if (!vendor)
+          build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+            if (CsrDevPaths.isVendorFile(args.path)) return undefined;
+            const normalized = RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(
+              await Bun.file(args.path).text(),
+            );
+            return normalized ? { contents: normalized, loader: "tsx" } : undefined;
+          });
+        build.onResolve({ filter: /.*/ }, (args) => {
+          if (args.kind === "entry-point-build" || !args.importer) return undefined;
+          const importer = CsrDevPaths.realpath(args.importer);
+          const target = this.#resolver.resolve(importer, args.path);
+          if (target === CsrDevResolver.inline) return undefined;
+          if (target === null) {
+            misses.push(`${args.path} from ${this.#paths.idOf(importer)}`);
+            return { path: `akan-miss:${args.path}`, external: true };
+          }
+          const external = CsrDevPaths.isStub(target)
+            ? target
+            : `${CsrDevPaths.modulePrefix}${this.#paths.idOf(target)}`;
+          return { path: external, external: true };
+        });
+      },
+    };
+  }
+
+  //? Bun writes sources relative to the working directory; the page shows them by workspace path instead. A package
+  //? barrel inlined into its importer (react-icons) would carry its whole text into every importer's map.
+  #rebaseSourceMap(text: string): string {
+    const map = JSON.parse(text) as { sources: string[]; sourcesContent?: (string | null)[] };
+    const files = map.sources.map((source) => path.resolve(source));
+    map.sources = files.map((file) => `/${this.#paths.idOf(file)}`);
+    map.sourcesContent = files.map((file, index) =>
+      CsrDevPaths.isVendorFile(file) ? null : (map.sourcesContent?.[index] ?? null),
+    );
+    return JSON.stringify(map);
+  }
+
+  // Read off the emitted code rather than onResolve: Bun resolves both arms of `NODE_ENV ? require(a) : require(b)`
+  // before dropping the dead one, and following it would pull every package's production build in too.
+  #emittedDeps(code: string): string[] {
+    const deps = new Set<string>();
+    const references = /\b(?:require|import|__akanImport)\("((?:akan-module|stub):[^"]+)"\)/g;
+    for (const [, reference] of code.matchAll(references)) {
+      if (!reference) continue;
+      deps.add(
+        CsrDevPaths.isStub(reference)
+          ? reference
+          : this.#paths.fileOf(reference.slice(CsrDevPaths.modulePrefix.length)),
+      );
+    }
+    return [...deps];
+  }
+
+  // Every rewrite keeps the line count, so a module's source map still lines up inside the factory.
+  static #factory(id: string, code: string): { factory: string; helpers: CsrDevSharedHelpers | null } {
+    const prefix = CsrDevPaths.modulePrefix;
+    let patched = code.replaceAll(`import("${prefix}`, `__akanImport("${prefix}`).replace(/^\/\/# debugId=.*$/m, "");
+    for (const [name, params, method] of CsrDevModuleCompiler.#helperPatches) {
+      const definition = `var ${name} = ${params} => {`;
+      if (patched.includes(definition))
+        patched = patched.replace(definition, `var ${name} = __akan.${method}, __bun${name} = ${params} => {`);
+      else if (patched.includes(`${name}(`))
+        throw new Error(
+          `[csr-dev] ${id}: Bun's ${name} helper no longer reads "${definition}"; CsrDevModuleCompiler must follow`,
+        );
+    }
+    // StoreRegistry.build merges into one global store instance, so every importer already holds the updated `st`:
+    // re-running the store root is the whole update, and bubbling past it would only reach the page modules.
+    if (CsrDevModuleCompiler.#storeRoot.test(id)) patched += "\nmodule.hot.accept();";
+    const shared = CsrDevModuleCompiler.#shareHelpers(patched);
+    return {
+      factory: `function (require, module, exports, $RefreshReg$, $RefreshSig$, __akanImport) {\n${shared?.code ?? patched}\n}`,
+      helpers: shared?.helpers ?? null,
+    };
+  }
+
+  //? Bun's interop helpers are everything before its first `// <path>` comment. One naming a factory argument would
+  //? bind to whichever module ran it first, so only a self-contained preamble is shared.
+  static #shareHelpers(code: string): { code: string; helpers: CsrDevSharedHelpers } | null {
+    const marker = code.search(/^\/\/ /m);
+    if (marker <= 0) return null;
+    const preamble = code.slice(0, marker);
+    const names = [...preamble.matchAll(/^(?:var|let|const|function)\s+([\w$]+)/gm)]
+      .map(([, name]) => name)
+      .filter((name): name is string => !!name);
+    if (names.length === 0 || CsrDevModuleCompiler.#factoryArgument.test(preamble)) return null;
+    const hash = Bun.hash(preamble).toString(36);
+    const binding = `var { ${names.join(", ")} } = __akan.helpers(${JSON.stringify(hash)});`;
+    return {
+      code: `${binding}${"\n".repeat(CsrDevPaths.lineCount(preamble))}${code.slice(marker)}`,
+      helpers: {
+        hash,
+        definition: `__akan.defineHelpers(${JSON.stringify(hash)}, function () {\n${preamble}return { ${names.join(", ")} };\n});\n`,
+      },
+    };
+  }
+}

package/frontendBuild/csrDevPaths.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export class CsrDevPaths {
+  static readonly modulePrefix = "akan-module:";
+  static readonly stubPrefix = "stub:";
+  readonly root: string;
+
+  constructor(workspaceRoot: string) {
+    this.root = CsrDevPaths.realpath(workspaceRoot);
+  }
+
+  idOf(file: string): string {
+    const real = CsrDevPaths.realpath(file);
+    const relative = path.relative(this.root, real);
+    const id = relative.startsWith("..") || path.isAbsolute(relative) ? real : relative;
+    return id.split(path.sep).join("/");
+  }
+
+  fileOf(id: string): string {
+    return path.isAbsolute(id) ? id : path.join(this.root, id);
+  }
+
+  static isStub(target: string): boolean {
+    return target.startsWith(CsrDevPaths.stubPrefix);
+  }
+
+  static isVendorFile(file: string): boolean {
+    return file.includes(`${path.sep}node_modules${path.sep}`);
+  }
+
+  static isScript(file: string): boolean {
+    return /\.[cm]?[jt]sx?$/.test(file);
+  }
+
+  static mtimeOf(file: string): number {
+    return fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? -1;
+  }
+
+  static async hashOf(file: string): Promise<string> {
+    const source = Bun.file(file);
+    return (await source.exists()) ? Bun.hash(await source.arrayBuffer()).toString(36) : "";
+  }
+
+  static realpath(file: string): string {
+    // A deleted file keeps its own path, so its id still matches the graph entry it leaves behind.
+    return fs.existsSync(file) ? fs.realpathSync(file) : path.resolve(file);
+  }
+
+  static tryResolve(specifier: string, from: string): string | null {
+    try {
+      return Bun.resolveSync(specifier, from);
+    } catch {
+      // Unresolvable is an answer here; the caller decides whether it is an error.
+      return null;
+    }
+  }
+
+  static lineCount(text: string): number {
+    let count = 0;
+    for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) count += 1;
+    return count;
+  }
+}

package/frontendBuild/csrDevResolver.ts

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevContext } from "./csrDevTypes";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
+
+interface MetafileImport {
+  path: string;
+  kind: string;
+  original?: string;
+  external?: boolean;
+}
+
+interface PrepassMetafile {
+  inputs: Record<string, { imports: MetafileImport[] }>;
+}
+
+export interface CsrDevResolverOptions {
+  paths: CsrDevPaths;
+  context: CsrDevContext;
+  entryFiles: string[];
+  resolution?: Record<string, Record<string, string>>;
+}
+
+//* Resolution comes from a plain browser build: Bun's runtime resolver ignores the `browser` condition and picks Node
+//* builds (`@firebase/util` resolves to its node-esm entry), which the registry build would then ship.
+export class CsrDevResolver {
+  static readonly inline = "inline";
+  readonly #paths: CsrDevPaths;
+  readonly #context: CsrDevContext;
+  readonly #entryFiles: string[];
+  readonly #resolution = new Map<string, Map<string, string>>();
+  readonly #fallbacks = new Set<string>();
+  #prepassDone = false;
+
+  constructor({ paths, context, entryFiles, resolution = {} }: CsrDevResolverOptions) {
+    this.#paths = paths;
+    this.#context = context;
+    this.#entryFiles = entryFiles;
+    for (const [importer, bySpecifier] of Object.entries(resolution))
+      this.#resolution.set(
+        paths.fileOf(importer),
+        new Map(
+          Object.entries(bySpecifier).map(([specifier, target]) => [
+            specifier,
+            CsrDevPaths.isStub(target) ? target : paths.fileOf(target),
+          ]),
+        ),
+      );
+  }
+
+  get prepassDone(): boolean {
+    return this.#prepassDone;
+  }
+
+  get fallbacks(): ReadonlySet<string> {
+    return this.#fallbacks;
+  }
+
+  async prepass(): Promise<void> {
+    const result = await Bun.build({
+      entrypoints: [...this.#entryFiles, this.#context.refreshFile],
+      target: "browser",
+      metafile: true,
+      env: "AKAN_PUBLIC_*",
+      define: this.#context.define,
+      optimizeImports: this.#context.optimizeImports,
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+    });
+    const { inputs } = result.metafile as unknown as PrepassMetafile;
+    for (const [input, { imports }] of Object.entries(inputs)) {
+      const importer = CsrDevPaths.realpath(path.resolve(input));
+      for (const record of imports) {
+        if (!record.original) continue;
+        if (record.external) {
+          if (record.original.startsWith("node:"))
+            this.#remember(importer, record.original, `${CsrDevPaths.stubPrefix}${record.original}`);
+          continue;
+        }
+        const target = path.resolve(record.path);
+        if (fs.existsSync(target)) this.#remember(importer, record.original, CsrDevPaths.realpath(target));
+      }
+    }
+    this.#prepassDone = true;
+  }
+
+  resolve(importer: string, specifier: string): 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);
+    if (target === null || CsrDevPaths.isStub(target)) return target;
+    if (!CsrDevPaths.isScript(target)) return CsrDevResolver.inline;
+    if (!usable) this.#remember(importer, specifier, target);
+    return target;
+  }
+
+  isRegistryModule(file: string): boolean {
+    if (!CsrDevPaths.isScript(file)) return false;
+    const packageName = CsrDevResolver.#packageNameOf(file);
+    if (packageName === null) return true;
+    return !this.#context.optimizeImports.some((pattern) => {
+      const base = CsrDevResolver.#patternBase(pattern);
+      return base === packageName || base.startsWith(`${packageName}/`);
+    });
+  }
+
+  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),
+          ]),
+        ),
+      ]),
+    );
+  }
+
+  #resolveUnknown(importer: string, specifier: string): 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 resolved = CsrDevPaths.tryResolve(specifier, path.dirname(importer));
+    if (!resolved) throw new Error(`[csr-dev] cannot resolve "${specifier}" from ${this.#paths.idOf(importer)}`);
+    if (!path.isAbsolute(resolved)) return `${CsrDevPaths.stubPrefix}${specifier}`;
+    if (!relative) this.#fallbacks.add(specifier);
+    return CsrDevPaths.realpath(resolved);
+  }
+
+  //? 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.
+  #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;
+    }
+    return null;
+  }
+
+  #remember(importer: string, specifier: string, target: string): void {
+    const byImporter = this.#resolution.get(importer) ?? new Map<string, string>();
+    this.#resolution.set(importer, byImporter.set(specifier, target));
+  }
+
+  //? Only the barrel a bare import names is inlined, so its icons tree-shake per importer; what the barrel itself
+  //? imports stays a registry module, keeping shared state such as react-icons' IconContext a single instance.
+  #isInlineSpecifier(specifier: string): boolean {
+    if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("node:")) return false;
+    return this.#context.optimizeImports.some((pattern) => {
+      const base = CsrDevResolver.#patternBase(pattern);
+      return specifier === base || specifier.startsWith(`${base}/`);
+    });
+  }
+
+  static #patternBase(pattern: string): string {
+    return pattern.endsWith("/*") ? pattern.slice(0, -2) : pattern;
+  }
+
+  static #packageNameOf(file: string): string | null {
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const index = file.lastIndexOf(marker);
+    if (index < 0) return null;
+    const [scope, name] = file.slice(index + marker.length).split(path.sep);
+    return (scope?.startsWith("@") ? `${scope}/${name}` : scope) || null;
+  }
+
+  static #packageScopeOf(file: string): string {
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const index = file.lastIndexOf(marker);
+    if (index < 0) return "";
+    const [scope, name] = file.slice(index + marker.length).split(path.sep);
+    return file.slice(0, index + marker.length) + (scope?.startsWith("@") ? `${scope}${path.sep}${name}` : scope);
+  }
+}

package/frontendBuild/csrDevTypes.ts

@@ -0,0 +1,46 @@
+import type { PageEntry } from "../artifact/implicitRootLayout";
+
+export interface CsrDevGraphModule {
+  vendor: boolean;
+  mtimeMs: number;
+  hash: string;
+  deps: string[];
+  helpers?: string;
+}
+
+export interface CsrDevGraph {
+  version: 1;
+  configKey: string;
+  refresh: string;
+  entries: Record<string, string>;
+  modules: Record<string, CsrDevGraphModule>;
+  resolution: Record<string, Record<string, string>>;
+  pending: string[];
+}
+
+export interface CsrDevContext {
+  pageEntries: PageEntry[];
+  basePaths: string[];
+  htmlBasePaths: string[];
+  define: Record<string, string>;
+  optimizeImports: string[];
+  configKey: string;
+  refreshFile: string;
+}
+
+export interface CsrDevSharedHelpers {
+  hash: string;
+  definition: string;
+}
+
+export interface CsrDevCompiledModule {
+  id: string;
+  file: string;
+  vendor: boolean;
+  factory: string;
+  helpers: CsrDevSharedHelpers | null;
+  sourceMap?: string;
+  deps: string[];
+  mtimeMs: number;
+  hash: string;
+}

package/frontendBuild/index.ts

@@ -4,6 +4,7 @@ export * from "./clientBuildTypes";
 export * from "./clientEntriesBundler";
 export * from "./clientEntryDiscovery";
 export * from "./csrArtifactBuilder";
+export * from "./csrDevBundler";
 export * from "./cssCompiler";
 export * from "./cssImportResolver";
 export * from "./devChangePlanner";

package/frontendBuild/pagesEntrySourceGenerator.ts

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