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

package/frontendBuild/csrDevResolver.ts

@@ -20,6 +20,8 @@ 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[]>;
 }
 
 //* Resolution comes from a plain browser build: Bun's runtime resolver ignores the `browser` condition and picks Node
@@ -31,12 +33,15 @@ 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>>();
   #prepassDone = false;
 
-  constructor({ paths, context, entryFiles, resolution = {} }: CsrDevResolverOptions) {
+  constructor({ paths, context, entryFiles, resolution = {}, runtimeResolved = {} }: CsrDevResolverOptions) {
     this.#paths = paths;
     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 +64,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 +84,35 @@ 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) ? 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 record stands until its file is gone, or until a file created beside the folder it went into takes the import
+  //? over (`Foo.tsx` next to `Foo/index.tsx`), as it does for Bun and every other build. Nothing else overturns it: the
+  //? prepass chose between sibling files and package fields as Bun does, which a disk lookup would only approximate.
+  #stillAnswers(importer: string, specifier: string, known: string): boolean {
+    if (CsrDevPaths.isStub(known)) return true;
+    if (!fs.existsSync(known)) return false;
+    if (!specifier.startsWith(".") || CsrDevPaths.isVendorFile(importer)) return true;
+    return !CsrDevPaths.isShadowed(path.resolve(path.dirname(importer), specifier), known);
+  }
+
   isRegistryModule(file: string): boolean {
     if (!CsrDevPaths.isScript(file)) return false;
     const packageName = CsrDevResolver.#packageNameOf(file);
@@ -105,42 +123,76 @@ export class CsrDevResolver {
     });
   }
 
+  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.resolveOnDisk(path.resolve(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);
+    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 && !CsrDevPaths.isVendorFile(importer)) throw cannotResolve();
+      return null;
+    }
+    if (!resolved) 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,11 @@ 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[];
+  /** The stamp of the signal and dictionary sources the last whole build inlined; see `RegistryMetadataFingerprint`. */
+  metadata?: string;
 }
 
 export interface CsrDevContext {
@@ -25,7 +29,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 +51,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);
 }

package/frontendBuild/devRegistryBundler.ts

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import type { App } from "../commandDecorators";
+import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
+import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
+import { CsrDevPatcher } from "./csrDevPatcher";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
+import { WatchRootResolver } from "./watchRootResolver";
+
+export interface CsrDevUpdate {
+  generation: number;
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds: string[];
+  moduleCount: number;
+  epoch?: number;
+  /** The registry did not exist before this build, so no tab holds a module of it. */
+  first?: boolean;
+}
+
+export interface CsrDevUpdateOptions {
+  /** Called once an update exists: for a patch before app.js is rewritten, for a reload after everything is on disk. */
+  announce?: (update: CsrDevUpdate) => void;
+  /** Files the registry must hold once this update is done; the ones it lacks are compiled into it. */
+  roots?: string[];
+  /**
+   * Compile only the roots the registry lacks: a route build asks for its entries, and a file saved meanwhile is the
+   * save's own patch to make, with the hold only that patch knows.
+   */
+  onlyRoots?: boolean;
+}
+
+export interface DevRegistryTarget {
+  dirName: string;
+  routePrefix: string;
+  library: boolean;
+}
+
+//* A dev module registry under `.akan/artifact/<dirName>`: this owns the context, the entries and the full build;
+//* `CsrDevPatcher` owns the incremental path, which the resident builder keeps in memory between saves.
+export abstract class DevRegistryBundler {
+  readonly outDir: string;
+  readonly routePrefix: string;
+  readonly paths: CsrDevPaths;
+  readonly writer: CsrDevArtifactWriter;
+  protected readonly app: App;
+  protected readonly entryDir: string;
+  /** A CSR entry holds the route table, so moving one reloads the tab; an SSR root is one more module to hold. */
+  abstract readonly reloadsOnEntryChange: boolean;
+
+  constructor(app: App, { dirName, routePrefix, library }: DevRegistryTarget) {
+    this.app = app;
+    this.routePrefix = routePrefix;
+    this.paths = new CsrDevPaths(app.workspace.workspaceRoot);
+    this.outDir = path.join(app.cwdPath, ".akan/artifact", dirName);
+    this.entryDir = path.join(app.cwdPath, ".akan/generated", dirName);
+    this.writer = new CsrDevArtifactWriter(this.outDir, { routePrefix, library });
+  }
+
+  /** Null when there is nothing to build. */
+  abstract context(): Promise<CsrDevContext | null>;
+
+  abstract writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }>;
+
+  /** Every file a full build compiles from, the entries included. */
+  protected abstract rootFiles(entryFiles: string[]): Promise<string[]>;
+
+  // A build worker: a throwaway patcher that starts from the disk, and builds everything itself when it cannot patch.
+  async update(changedFiles: string[] = [], options: CsrDevUpdateOptions = {}): Promise<CsrDevUpdate | null> {
+    const result = await new CsrDevPatcher(this).update(changedFiles, { ...options, allowWholeAppBuilds: true });
+    if (result.kind === "unchanged") return null;
+    if (result.kind === "update") return result.update;
+    const built = await this.fullBuild(result.context, result.generation, result.reason);
+    const update = result.first ? { ...built, first: true } : built;
+    options.announce?.(update);
+    return update;
+  }
+
+  /** Of these roots outside the graph, the ones something still reaches (an entry, a module's import): those stay pending. */
+  async wantedRoots(files: string[], graph: CsrDevGraph): Promise<Set<string>> {
+    const reached = new Set([...Object.values(graph.entries), ...Object.values(graph.modules).flatMap((m) => m.deps)]);
+    return new Set(files.filter((file) => reached.has(this.paths.idOf(file))));
+  }
+
+  async holds(files: string[]): Promise<boolean> {
+    const graph = await this.writer.readJson<CsrDevGraph>("graph.json");
+    return graph !== null && files.every((file) => graph.modules[this.paths.idOf(file)] !== undefined);
+  }
+
+  /** A save of one goes to a whole build: `lib/useClient.ts` inlines what they declare through macros. */
+  isMetadataFile(file: string): boolean {
+    return isAkanRuntimeMetadataFile(file);
+  }
+
+  async metadataFingerprint(): Promise<string> {
+    const libsContainer = path.resolve(this.app.workspace.workspaceRoot, "libs");
+    const roots = await new WatchRootResolver(this.app).resolve();
+    // The whole container comes back when the lib dependencies are unknown (before the first sync).
+    const libRoots = roots.includes(libsContainer)
+      ? fs.readdirSync(libsContainer).map((name) => path.join(libsContainer, name))
+      : roots.filter((root) => path.dirname(root) === libsContainer);
+    return await RegistryMetadataFingerprint.of([path.resolve(this.app.cwdPath), ...libRoots], (file) =>
+      this.isMetadataFile(file),
+    );
+  }
+
+  //? Compiled before anything is written: a build that fails (a module the user broke) leaves the registry the tabs
+  //? and the next patch read as it was, where clearing the directory first left no registry at all.
+  async fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
+    const metadata = await this.metadataFingerprint();
+    const entries = await this.writeEntries(context);
+    const roots = await this.rootFiles(Object.values(entries.files));
+    const resolver = new CsrDevResolver({ paths: this.paths, context, entryFiles: roots });
+    await resolver.prepass();
+    const compiler = this.compiler(context, resolver);
+    const { modules: compiled } = await compiler.compile(
+      [...roots, ...(context.refreshFile ? [context.refreshFile] : [])],
+      new Set(),
+    );
+    const graph: CsrDevGraph = {
+      version: 1,
+      configKey: context.configKey,
+      refresh: context.refreshFile
+        ? this.paths.idOf(context.refreshFile)
+        : `${CsrDevPaths.vendorPrefix}react-refresh/runtime`,
+      entries: this.entryIds(entries.files),
+      modules: {},
+      resolution: {},
+      pending: [],
+      metadata,
+    };
+    this.merge(graph, resolver, compiled);
+    await this.writer.markBuilding();
+    await this.writer.writeModules(compiled);
+    const vendorFile = await this.writer.writeVendor(graph);
+    const epoch = Date.now();
+    await this.writer.writeApp(graph, { generation, vendorFile, epoch });
+    await this.writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries, epoch });
+    await this.writer.pruneAfterFullBuild(graph, vendorFile, { generation, assets: compiler.assets });
+    await this.writer.clearBuilding();
+    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length, epoch };
+  }
+
+  compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
+    return new CsrDevModuleCompiler({
+      app: this.app,
+      paths: this.paths,
+      resolver,
+      context,
+      outDir: this.outDir,
+      routePrefix: this.routePrefix,
+    });
+  }
+
+  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();
+    graph.runtimeResolved = resolver.serializeRuntimeResolved();
+  }
+
+  entryIds(files: Record<string, string>): Record<string, string> {
+    return Object.fromEntries(Object.entries(files).map(([key, file]) => [key, this.paths.idOf(file)]));
+  }
+}

package/frontendBuild/hmrWatcher.test.ts

@@ -49,6 +49,57 @@ afterEach(() => {
 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 () => {

package/frontendBuild/hmrWatcher.ts

@@ -31,6 +31,7 @@ export class HmrWatcher {
   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;
@@ -39,7 +40,7 @@ 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;
@@ -119,6 +120,7 @@ export class HmrWatcher {
   }
 
   #scheduleFlush(): void {
+    this.#windowStartedAt ??= Date.now();
     if (this.#flushing) return;
     if (this.#timer) clearTimeout(this.#timer);
     this.#timer = setTimeout(() => this.#flush(), this.#debounceMs);
@@ -135,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}`);
         }
@@ -201,6 +209,12 @@ export class HmrWatcher {
     );
   }
 
+  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;

package/frontendBuild/index.ts

@@ -9,6 +9,7 @@ export * from "./cssCompiler";
 export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
+export * from "./devRegistryBundler";
 export * from "./fontOptimizer";
 export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
@@ -18,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";
@@ -9,7 +10,9 @@ 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 {
   bundlePath: string;
@@ -42,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`,
@@ -55,6 +65,7 @@ export class PagesBundleBuilder {
         asset: "assets/[name]-[hash].[ext]",
       },
       define: bundleDefine(this.#app, this.#command, "ssr"),
+      metafile: dev,
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
@@ -66,9 +77,10 @@ export class PagesBundleBuilder {
                 transformUseClient(source, {
                   path: args.path,
                   workspaceRoot,
+                  onClientModule,
                 }),
             })
-          : createUseClientBundlePlugin({ workspaceRoot }),
+          : createUseClientBundlePlugin({ workspaceRoot, onClientModule }),
       ],
     });
 
@@ -79,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(
@@ -95,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`;
   }

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -2,12 +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 {
@@ -72,7 +79,7 @@ ${entries.join("\n")}
   #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
     const known = this.#asyncDefaults.get(moduleAbsPath);
     if (known) return known;
-    const detected = AsyncDefaultExportDetector.detect(moduleAbsPath);
+    const detected = this.#detect(moduleAbsPath);
     this.#asyncDefaults.set(moduleAbsPath, detected);
     return detected;
   }