@akanjs/devkit 3.0.0-beta.3 → 3.0.0-beta.30

package/frontendBuild/hmrWatcher.test.ts

@@ -1,24 +1,17 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { Logger } from "akanjs/common";
+import { tempDirs } from "../testHelpers";
 import { type ChangeBatch, HmrWatcher } from "./hmrWatcher";
 
-/**
- * These run against the real Bun watcher rather than a fake, because the behaviour under test only
- * exists there: Bun 1.3.14's recursive `fs.watch` reports about one path per ~200ms coalescing window and
- * discards the rest (`local/optimize-resource/06-watcher-dropped-event.md`). A fake that delivered every
- * event would pass no matter what the watcher did with them.
- */
+// The real Bun watcher, not a fake: the dropped-event behaviour under test only exists there.
 const STREAM_WARMUP_MS = 600;
 const SETTLE_MS = 1_500;
 const TEST_TIMEOUT_MS = 15_000;
 
 const started: HmrWatcher[] = [];
-const roots: string[] = [];
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Every level `HmrWatcher` can reach, so adding a log line cannot fail a test for the wrong reason. */
 const silentLogger = {
   trace: () => undefined,
   verbose: () => undefined,
@@ -29,12 +22,6 @@ const silentLogger = {
   error: () => undefined,
 } as unknown as Logger;
 
-const makeRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-hmr-watcher-"));
-  roots.push(root);
-  return root;
-};
-
 const seed = async (root: string, rel: string, content = "export const x = 1;\n") => {
   const abs = path.join(root, rel);
   await mkdir(path.dirname(abs), { recursive: true });
@@ -56,12 +43,63 @@ const watch = async (root: string) => {
   return { watcher, batches, seen: () => new Set(batches.flatMap((batch) => batch.files)) };
 };
 
-afterEach(async () => {
+afterEach(() => {
   for (const watcher of started.splice(0)) watcher.stop();
-  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
+const makeRoot = tempDirs("akan-hmr-watcher-");
 
 describe("HmrWatcher", () => {
+  test(
+    "marks when a batch's window opened and when it was handed over",
+    async () => {
+      const root = await makeRoot();
+      const source = await seed(root, "lib/a.ts");
+      const { batches } = await watch(root);
+
+      const writtenAt = Date.now();
+      await writeFile(source, "export const x = 2;\n");
+      await sleep(SETTLE_MS);
+
+      const trace = batches.filter((batch) => batch.files.includes(source)).at(-1)?.trace;
+      expect(trace?.eventAt).toBeGreaterThanOrEqual(writtenAt);
+      expect(trace?.flushAt).toBeGreaterThanOrEqual(trace?.eventAt ?? Number.POSITIVE_INFINITY);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "takes its debounce window from AKAN_DEV_WATCH_DEBOUNCE_MS when no option names one",
+    async () => {
+      const previous = process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+      process.env.AKAN_DEV_WATCH_DEBOUNCE_MS = "400";
+      try {
+        const root = await makeRoot();
+        const source = await seed(root, "lib/a.ts");
+        const batches: ChangeBatch[] = [];
+        // Without the verification scan, which would otherwise hand the batch over at 250ms.
+        const watcher = new HmrWatcher({
+          roots: [root],
+          logger: silentLogger,
+          verifyDelayMs: 0,
+          onBatch: (batch) => void batches.push(batch),
+        });
+        started.push(watcher);
+        await watcher.start();
+        await sleep(STREAM_WARMUP_MS);
+
+        await writeFile(source, "export const x = 3;\n");
+        await sleep(SETTLE_MS);
+
+        const trace = batches.find((batch) => batch.files.includes(source))?.trace;
+        expect((trace?.flushAt ?? 0) - (trace?.eventAt ?? 0)).toBeGreaterThanOrEqual(395);
+      } finally {
+        if (previous === undefined) delete process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+        else process.env.AKAN_DEV_WATCH_DEBOUNCE_MS = previous;
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
   test(
     "reports every file of a save-all",
     async () => {
@@ -69,15 +107,12 @@ describe("HmrWatcher", () => {
       const files = await Promise.all([0, 1, 2, 3, 4].map((i) => seed(root, `lib/File${i}.ts`)));
       const { batches, seen, watcher } = await watch(root);
 
-      // No gaps between writes, so they share one coalescing window and Bun names at most one of them.
       for (const [i, abs] of files.entries()) await writeFile(abs, `export const x = ${i}00;\n`);
       await sleep(SETTLE_MS);
 
       expect(batches.length).toBeGreaterThan(0);
       for (const abs of files) expect([...seen()]).toContain(abs);
-      // Not asserted as non-zero: the point is that the outcome above holds whether or not Bun drops
-      // events, so this suite keeps passing if the upstream defect is ever fixed. The counter is the
-      // signal for when the compensation can be removed.
+      // Not `> 0`: the suite must keep passing if Bun ever stops dropping events.
       expect(watcher.unreportedChanges).toBeGreaterThanOrEqual(0);
     },
     TEST_TIMEOUT_MS,
@@ -90,8 +125,6 @@ describe("HmrWatcher", () => {
       const source = await seed(root, "lib/a.ts");
       const { seen, batches } = await watch(root);
 
-      // What every build ends with: a burst under `.akan/`, which the classifier ignores. Before this
-      // was handled, the burst was the one path Bun reported and the save right after it was invisible.
       const artifactDir = path.join(root, ".akan", "artifact", "server");
       await mkdir(artifactDir, { recursive: true });
       for (let i = 0; i < 60; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(8192));
@@ -100,8 +133,6 @@ describe("HmrWatcher", () => {
       await sleep(SETTLE_MS);
 
       expect([...seen()]).toContain(source);
-      // Exactly one batch for one save. Bun does deliver a real event for some paths the scan has already
-      // emitted, and counting both produced a second generation and a second build for no change.
       expect(batches.filter((batch) => batch.files.includes(source))).toHaveLength(1);
     },
     TEST_TIMEOUT_MS,
@@ -119,7 +150,6 @@ describe("HmrWatcher", () => {
       for (let i = 0; i < 20; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(4096));
       await sleep(SETTLE_MS);
 
-      // The verification scan is triggered by ignored paths, so it must not invent work from them either.
       expect(batches).toEqual([]);
     },
     TEST_TIMEOUT_MS,
@@ -161,7 +191,7 @@ describe("HmrWatcher", () => {
     TEST_TIMEOUT_MS,
   );
 
-  test.skipIf(process.getuid?.() === 0)(
+  test.skipIf(process.getuid?.() === 0 || process.platform === "win32")(
     "warns at startup when part of the tree cannot be read",
     async () => {
       const root = await makeRoot();
@@ -176,12 +206,9 @@ describe("HmrWatcher", () => {
       });
       started.push(watcher);
       await watcher.start();
-      // Restored before asserting, not after: a failed assertion would otherwise leave a directory `rm`
-      // cannot traverse, and the leak would fail the *next* test instead of this one.
+      // Restored before asserting: a failed assertion would leave a directory `rm` cannot traverse.
       await chmod(path.dirname(hidden), 0o755);
 
-      // At startup rather than at the first save, because an unreadable root means edits under it never
-      // rebuild — waiting for a save to reveal that means waiting for the save that silently does nothing.
       expect(warnings).toHaveLength(1);
       expect(warnings[0]).toContain("will not rebuild");
       expect(warnings[0]).toContain("EACCES");

package/frontendBuild/hmrWatcher.ts

@@ -12,24 +12,12 @@ export interface WatcherOptions {
   debounceMs?: number;
   logger: Logger;
   onBatch: (batch: ChangeBatch) => void | Promise<void>;
-  /**
-   * Delay before re-checking mtimes for changes `fs.watch` never reported. Must clear Bun's ~200ms
-   * coalescing window, or a write late in the same window as a delivered event stays invisible.
-   */
+  /** Delay (ms, default 250) before the mtime re-check; must outlast Bun's ~200ms fs.watch coalescing window. */
   verifyDelayMs?: number;
 }
 
-/**
- * Recursive filesystem watcher with debounced batching. We deliberately keep
- * classification coarse (`code` / `css` / `config`) so the orchestrator can
- * decide whether a full rebuild-and-reload or a narrower action (e.g. CSS
- * hot-swap) is sufficient.
- *
- * Bun's event payloads are treated as a hint, not the answer: its recursive `fs.watch` reports about one
- * path per coalescing window and silently discards the rest, so what changed is resolved against a
- * `SourceMtimeIndex` instead (see that class for the measurements). Events still drive *when* to look,
- * which is what keeps this cheap — Bun does reliably deliver at least one event per window.
- */
+// Bun delivers at least one fs.watch event per coalescing window but drops the other paths, so events decide
+// when to look and the SourceMtimeIndex decides what changed.
 export class HmrWatcher {
   readonly #roots: string[];
   readonly #debounceMs: number;
@@ -38,12 +26,12 @@ export class HmrWatcher {
   readonly #logger: Logger;
   readonly #watchers: fs.FSWatcher[] = [];
   readonly #pending = new Map<string, Exclude<ChangeKind, "ignore">>();
-  /** Paths the watcher's own events named since the last batch — diagnostics only, see `#queue`. */
   readonly #hinted = new Set<string>();
   readonly #classifier = new HmrChangeClassifier();
   readonly #index: SourceMtimeIndex;
   #timer: ReturnType<typeof setTimeout> | null = null;
   #verifyTimer: ReturnType<typeof setTimeout> | null = null;
+  #windowStartedAt: number | null = null;
   #stopped = false;
   #flushing = false;
   #unreportedChanges = 0;
@@ -52,26 +40,19 @@ export class HmrWatcher {
 
   constructor(opts: WatcherOptions) {
     this.#roots = [...new Set(opts.roots.map((r) => path.resolve(r)))];
-    this.#debounceMs = opts.debounceMs ?? 80;
+    this.#debounceMs = opts.debounceMs ?? HmrWatcher.#envDebounceMs() ?? 30;
     this.#verifyDelayMs = opts.verifyDelayMs ?? 250;
     this.#onBatch = opts.onBatch;
     this.#logger = opts.logger;
     this.#index = new SourceMtimeIndex({ roots: this.#roots, classifier: this.#classifier });
   }
 
-  /**
-   * How many changes the mtime scan found that `fs.watch` never reported. Non-zero means this watcher is
-   * compensating for the Bun defect rather than the defect being absent, which is the number to watch if
-   * it is ever fixed upstream.
-   */
+  /** Changes the mtime scan found that fs.watch never reported; non-zero means it is compensating for Bun. */
   get unreportedChanges(): number {
     return this.#unreportedChanges;
   }
 
-  /**
-   * Watchers are installed before the baseline is taken, so an edit made during priming is reported by
-   * the event side even though the baseline already reflects it.
-   */
+  /** Installs the watchers before priming, so an edit made while priming is still reported by the event side. */
   async start(): Promise<void> {
     for (const root of this.#roots) {
       try {
@@ -88,8 +69,7 @@ export class HmrWatcher {
     }
     try {
       await this.#index.prime();
-      // Before the first batch, because a root that is unreadable at boot blinds the whole session and
-      // waiting for a save to surface it means waiting for a save that never rebuilds.
+      // At boot: edits under an unreadable root never rebuild, so no later save would surface it.
       this.#reportCoverageGaps();
       this.#logger.verbose(`[hmr] tracking ${this.#index.trackedFileCount} source files for change verification`);
     } catch (err) {
@@ -112,23 +92,14 @@ export class HmrWatcher {
     }
   }
 
-  /**
-   * Adopt writes the batch handler made itself (regenerated barrels, inserted imports) so the
-   * verification scan does not spend a second generation rebuilding content this one already consumed.
-   */
+  /** Baseline the batch handler's own writes so the verification scan does not rebuild them a second time. */
   async absorb(paths: string[]): Promise<void> {
     if (paths.length === 0) return;
     await this.#index.absorb(paths);
   }
 
-  /**
-   * An event says only *that* something happened, never reliably *what*. So with a baseline in hand it is
-   * used purely to decide when to look, and the mtime scan names the files.
-   *
-   * Taking the payload as well would double-report: Bun does deliver a real event for some of the paths a
-   * scan has already emitted, and adding it back here produced a second batch for the same save — one more
-   * generation and one more build for no change.
-   */
+  // Once primed, a payload only schedules a scan: Bun also delivers events for paths the scan already emitted,
+  // so adding payloads to the batch double-reports a save.
   #queue(abs: string): void {
     const kind = this.#classifier.classify(abs);
     if (!this.#index.primed) {
@@ -138,20 +109,18 @@ export class HmrWatcher {
       this.#scheduleFlush();
       return;
     }
-    // An ignored path still means a window happened. That is the shape of the original bug — every build
-    // ends in a burst under `.akan/`, and the burst is what Bun reports instead of the save beside it.
-    // Rescheduling on each one folds a build's whole burst into a single scan once it goes quiet.
+    // An ignored path (a build's .akan/ burst) still marks a coalescing window that may hide a real save.
     if (kind === "ignore") {
       this.#scheduleVerify();
       return;
     }
-    // Recorded only so `unreportedChanges` can tell which changes the events did name; it never decides
-    // what is in a batch.
+    // Diagnostics only, for `unreportedChanges`; it never decides what is in a batch.
     this.#hinted.add(abs);
     this.#scheduleFlush();
   }
 
   #scheduleFlush(): void {
+    this.#windowStartedAt ??= Date.now();
     if (this.#flushing) return;
     if (this.#timer) clearTimeout(this.#timer);
     this.#timer = setTimeout(() => this.#flush(), this.#debounceMs);
@@ -168,13 +137,19 @@ export class HmrWatcher {
     try {
       while (!this.#stopped) {
         await this.#mergeDetectedChanges();
-        if (this.#pending.size === 0) break;
+        if (this.#pending.size === 0) {
+          this.#windowStartedAt = null;
+          break;
+        }
         const files = Array.from(this.#pending.keys());
         const kinds = new Set(this.#pending.values());
+        const flushAt = Date.now();
+        const trace = { eventAt: this.#windowStartedAt ?? flushAt, flushAt };
+        this.#windowStartedAt = null;
         this.#pending.clear();
         this.#hinted.clear();
         try {
-          await this.#onBatch({ files, kinds });
+          await this.#onBatch({ files, kinds, trace });
         } catch (e) {
           this.#logger.error(`[hmr] onBatch error: ${(e as Error).message}`);
         }
@@ -186,10 +161,6 @@ export class HmrWatcher {
     }
   }
 
-  /**
-   * Fold in everything the mtime index has seen change, since a delivered event names at most one of the
-   * paths that moved in its window.
-   */
   async #mergeDetectedChanges(): Promise<void> {
     const detected = await this.#index.collectChanges().catch((err) => {
       this.#logger.error(`[hmr] mtime scan failed: ${(err as Error).message}`);
@@ -205,8 +176,6 @@ export class HmrWatcher {
     }
     if (unreported === 0) return;
     this.#unreportedChanges += unreported;
-    // Once at info, so it is visible that the watcher is compensating rather than the defect being absent;
-    // per-batch detail stays at verbose because a save-all trips this on every save.
     if (!this.#reportedCompensating) {
       this.#reportedCompensating = true;
       this.#logger.verbose(
@@ -218,13 +187,6 @@ export class HmrWatcher {
     );
   }
 
-  /**
-   * Say so when part of the tree cannot be read, and say so again when it recovers.
-   *
-   * A blind spot here means edits under that path are not rebuilt at all, which is indistinguishable from
-   * the dev server being broken. Keyed on the gap list itself so a persistent failure logs once rather than
-   * once per save, while a *different* gap appearing still gets its own line.
-   */
   #reportCoverageGaps(): void {
     const gaps = this.#index.coverageGaps;
     const key = gaps
@@ -247,10 +209,13 @@ export class HmrWatcher {
     );
   }
 
-  /**
-   * One scan after the coalescing window closes. A write that lands in the same window as an already
-   * delivered event produces no further event of its own, so nothing else would ever look for it.
-   */
+  static #envDebounceMs(): number | null {
+    const raw = process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+    const ms = raw ? Number(raw) : Number.NaN;
+    return Number.isInteger(ms) && ms >= 0 ? ms : null;
+  }
+
+  // A write in the same window as a delivered event raises no event of its own, so one scan follows each window.
   #scheduleVerify(): void {
     if (this.#stopped || this.#verifyDelayMs <= 0) return;
     if (this.#verifyTimer) clearTimeout(this.#verifyTimer);
@@ -260,16 +225,8 @@ export class HmrWatcher {
     }, this.#verifyDelayMs);
   }
 
-  /**
-   * Terminates rather than looping: a scan that finds nothing schedules nothing, and the build writes its
-   * artifacts under `.akan/` — which the classifier ignores — while codegen writes are content-guarded,
-   * so a rebuild does not move a tracked mtime.
-   *
-   * The one case that does schedule another is a directory the index could not date reliably (Linux stamps
-   * directory mtimes on a 1ms clock, see `SourceMtimeIndex`). That still terminates: the next scan is
-   * `verifyDelayMs` later, by which point the timestamp has settled unless something is writing to that
-   * directory right now — in which case looking again is the right answer anyway.
-   */
+  // Terminates: build output lands in ignored .akan/ and codegen writes are content-guarded, so a rebuild moves no
+  // tracked mtime; only an unsettled directory schedules another scan.
   async #verify(): Promise<void> {
     if (this.#stopped || this.#flushing) return;
     await this.#mergeDetectedChanges();

package/frontendBuild/index.ts

@@ -4,10 +4,12 @@ export * from "./clientBuildTypes";
 export * from "./clientEntriesBundler";
 export * from "./clientEntryDiscovery";
 export * from "./csrArtifactBuilder";
+export * from "./csrDevBundler";
 export * from "./cssCompiler";
 export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
+export * from "./devRegistryBundler";
 export * from "./fontOptimizer";
 export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
@@ -17,8 +19,10 @@ export * from "./pagesEntrySourceGenerator";
 export * from "./precompressArtifacts";
 export * from "./routeClientBuilder";
 export * from "./routesManifestArtifactSerializer";
+export * from "./serverGraphFile";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
+export * from "./ssrDevBundler";
 export * from "./styleContract";
 export * from "./themeValidator";
 export * from "./vendorSpecifiers";

package/frontendBuild/pagesBundleBuilder.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { PageEntry } from "../artifact/implicitRootLayout";
@@ -5,18 +6,17 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { createExternalizeFrameworkPlugin } from "../transforms/externalizeFrameworkPlugin";
+import { loaderFor } from "../transforms/moduleSyntax";
 import { transformUseClient } from "../transforms/rscUseClientTransform";
 import { createUseClientBundlePlugin } from "../transforms/useClientBundlePlugin";
+import { bundleDefine } from "./bundleDefine";
+import { CsrDevPaths } from "./csrDevPaths";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+import { ServerGraphFile } from "./serverGraphFile";
 
 export interface BuildPagesBundleResult {
-  /** Absolute path to the emitted `pages-[hash].js`. */
   bundlePath: string;
-  /**
-   * Monotonic build identifier. Bun.build emits a fresh filename whenever
-   * any input changes, but importers still benefit from a `?v=<buildId>`
-   * query-string cache bust — `buildId` is that value.
-   */
+  /** Cache-bust value for `import(bundlePath?v=<buildId>)`. */
   buildId: number;
   splitting: boolean;
   entryBytes: number;
@@ -27,10 +27,6 @@ export interface BuildPagesBundleResult {
 
 const VIRTUAL_PAGES_ENTRY = "akan-pages-entry";
 
-/**
- * Build the server-side pages bundle. The RSC worker loads the result with
- * `await import(bundlePath?v=buildId)`.
- */
 export class PagesBundleBuilder {
   #app: App;
   #command: "build" | "start";
@@ -49,6 +45,13 @@ export class PagesBundleBuilder {
       this.#pageEntries ?? (await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys()));
     const entrySource = PagesEntrySourceGenerator.generate(resolvedEntries);
     const workspaceRoot = this.#app.workspace.workspaceRoot;
+    const dev = this.#command === "start";
+    const clientExports: Record<string, string[]> = {};
+    const onClientModule = dev
+      ? (file: string, exports: string[]) => {
+          clientExports[CsrDevPaths.realpath(file)] = exports;
+        }
+      : undefined;
     const result = await Bun.build({
       entrypoints: [VIRTUAL_PAGES_ENTRY],
       outdir: `${this.#artifactDir}/server`,
@@ -61,7 +64,8 @@ export class PagesBundleBuilder {
         chunk: "chunks/[name]-[hash].[ext]",
         asset: "assets/[name]-[hash].[ext]",
       },
-      define: this.#define(),
+      define: bundleDefine(this.#app, this.#command, "ssr"),
+      metafile: dev,
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
@@ -73,9 +77,10 @@ export class PagesBundleBuilder {
                 transformUseClient(source, {
                   path: args.path,
                   workspaceRoot,
+                  onClientModule,
                 }),
             })
-          : createUseClientBundlePlugin({ workspaceRoot }),
+          : createUseClientBundlePlugin({ workspaceRoot, onClientModule }),
       ],
     });
 
@@ -86,6 +91,8 @@ export class PagesBundleBuilder {
 
     const bundlePath = path.resolve(entryArtifact.path);
     const buildId = Date.now();
+    if (dev && result.metafile)
+      await ServerGraphFile.write(this.#artifactDir, this.#serverGraph(result.metafile, clientExports));
     const outputBytes = result.outputs.reduce((sum, output) => sum + output.size, 0);
     const chunkCount = result.outputs.filter((output) => output.kind === "chunk").length;
     this.#app.verbose(
@@ -102,6 +109,15 @@ export class PagesBundleBuilder {
     };
   }
 
+  #serverGraph(metafile: Bun.BuildMetafile, clientExports: Record<string, string[]>) {
+    const inputs = Object.keys(metafile.inputs)
+      .filter((input) => !input.includes("node_modules"))
+      .map((input) => path.resolve(input))
+      .filter((input) => fs.existsSync(input))
+      .map((input) => CsrDevPaths.realpath(input));
+    return { inputs, clientExports };
+  }
+
   get #artifactDir(): string {
     return `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
   }
@@ -110,17 +126,6 @@ export class PagesBundleBuilder {
     return process.env.AKAN_SERVER_PAGES_SPLITTING === "1";
   }
 
-  #define(): Record<string, string> {
-    const nodeEnv = this.#command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
-    return {
-      "process.env.NODE_ENV": JSON.stringify(nodeEnv),
-      "process.env.AKAN_PUBLIC_RENDER_ENV": JSON.stringify("ssr"),
-      ...Object.fromEntries(
-        Object.entries(this.#app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
-      ),
-    };
-  }
-
   static createPagesEntryPlugin(source: string): BunPlugin {
     return {
       name: "akan-pages-entry",
@@ -176,10 +181,3 @@ export class PagesBundleBuilder {
       );
   }
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -2,11 +2,19 @@ import path from "node:path";
 import type { PageEntry } from "../artifact/implicitRootLayout";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
+export interface PagesEntrySourceOptions {
+  /** Detects an async default export; a caller that outlives one generation keeps its own cache across saves. */
+  isAsyncDefault?: (moduleAbsPath: string) => Promise<boolean>;
+}
+
 export class PagesEntrySourceGenerator {
   #pageEntries: PageEntry[];
+  readonly #asyncDefaults = new Map<string, Promise<boolean>>();
+  readonly #detect: (moduleAbsPath: string) => Promise<boolean>;
 
-  constructor(pageEntries: PageEntry[]) {
+  constructor(pageEntries: PageEntry[], { isAsyncDefault }: PagesEntrySourceOptions = {}) {
     this.#pageEntries = pageEntries;
+    this.#detect = isAsyncDefault ?? ((moduleAbsPath) => AsyncDefaultExportDetector.detect(moduleAbsPath));
   }
 
   static generate(pageEntries: PageEntry[]): string {
@@ -21,25 +29,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 = this.#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}`;
+  }
 }