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

package/frontendBuild/csrDevResolver.ts

@@ -0,0 +1,234 @@
+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>>;
+  /** 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
+//* 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>();
+  readonly #runtimeResolved = new Map<string, Set<string>>();
+  #prepassDone = false;
+
+  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),
+        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 ? [this.#context.refreshFile] : [])],
+      target: "browser",
+      metafile: true,
+      external: [...(this.#context.externals ?? [])],
+      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)) continue;
+        this.#remember(importer, record.original, CsrDevPaths.realpath(target));
+        this.#runtimeResolved.get(importer)?.delete(record.original);
+      }
+    }
+    this.#prepassDone = true;
+  }
+
+  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 && 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);
+    if (packageName === null) return true;
+    return !this.#context.optimizeImports.some((pattern) => {
+      const base = CsrDevResolver.#patternBase(pattern);
+      return base === packageName || base.startsWith(`${packageName}/`);
+    });
+  }
+
+  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]
+            .filter(([, target]) => CsrDevPaths.isStub(target) || fs.existsSync(target))
+            .map(([specifier, target]) => [specifier, CsrDevPaths.isStub(target) ? target : this.#paths.idOf(target)]),
+        ),
+      ]),
+    );
+  }
+
+  //? 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);
+    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));
+    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}`;
+    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 || 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;
+  }
+
+  #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,59 @@
+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>>;
+  /** 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 {
+  pageEntries: PageEntry[];
+  basePaths: string[];
+  htmlBasePaths: string[];
+  define: Record<string, string>;
+  optimizeImports: string[];
+  configKey: 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 {
+  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;
+}
+
+/** 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

@@ -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";