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

package/frontendBuild/buildRouteClient.test.ts

@@ -162,6 +162,7 @@ describe("route client store bootstrap", () => {
         knownEntries,
         discovery,
         artifact: {} as never,
+        browser: "chunks",
       }).build();
 
     const first = await build([pageA], new Set());
@@ -234,3 +235,63 @@ describe("route client store bootstrap", () => {
     });
   });
 });
+
+describe("fast refresh named default function", () => {
+  test("hoists a named default function into a declaration plus a trailing default export", () => {
+    const source = `export default async function Page<T>(props: T) {\n  return null;\n}\n`;
+    const next = RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(source, { path: "/app/page.tsx" });
+    expect(next).toBe(`async function Page<T>(props: T) {\n  return null;\n}\n\nexport default Page;\n`);
+  });
+
+  test("leaves code quoted in a template literal or a comment alone", () => {
+    const source = [
+      `import { page } from "akanjs/client";`,
+      `const snippet = \``,
+      `export default function Page() {`,
+      `  return <div />;`,
+      `}\`;`,
+      `/*`,
+      `export default function Commented() {}`,
+      `*/`,
+      `export default page().render(() => <pre>{snippet}</pre>);`,
+      "",
+    ].join("\n");
+    expect(
+      RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(source, { path: "/app/page.tsx" }),
+    ).toBeNull();
+  });
+
+  test("rewrites only the real declaration when the same name is also quoted", () => {
+    const source = [
+      "const snippet = `",
+      "export default function Page() {}",
+      "`;",
+      "export default function Page() {",
+      "  return snippet;",
+      "}",
+      "",
+    ].join("\n");
+    const next = RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(source, { path: "/app/page.tsx" });
+    expect(next).toBe(
+      [
+        "const snippet = `",
+        "export default function Page() {}",
+        "`;",
+        "function Page() {",
+        "  return snippet;",
+        "}",
+        "",
+        "export default Page;",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("leaves a file it cannot parse to the bundler", () => {
+    expect(
+      RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh("export default function Page( {", {
+        path: "/app/page.tsx",
+      }),
+    ).toBeNull();
+  });
+});

package/frontendBuild/bundleDefine.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import type { App } from "../commandDecorators";
+import { bundleDefine } from "./bundleDefine";
+
+describe("bundleDefine", () => {
+  test("spells the public env in one order whatever order the process holds it in", () => {
+    const appWith = (env: Record<string, string>) => ({ getPublicEnv: () => env }) as unknown as App;
+    const builder = bundleDefine(appWith({ AKAN_PUBLIC_Z: "1", AKAN_PUBLIC_A: "2" }), "start", "ssr");
+    const worker = bundleDefine(appWith({ AKAN_PUBLIC_A: "2", AKAN_PUBLIC_Z: "1" }), "start", "ssr");
+    expect(JSON.stringify(builder)).toBe(JSON.stringify(worker));
+  });
+});

package/frontendBuild/bundleDefine.ts

@@ -5,8 +5,12 @@ export const bundleDefine = (app: App, command: "build" | "start", renderEnv: "s
   return {
     "process.env.NODE_ENV": JSON.stringify(nodeEnv),
     "process.env.AKAN_PUBLIC_RENDER_ENV": JSON.stringify(renderEnv),
+    //? Sorted: Windows hands a child its environment sorted, while keys the config sets at runtime trail the parent's,
+    //? and the dev registries hash this object to tell a worker's build from the builder's.
     ...Object.fromEntries(
-      Object.entries(app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
+      Object.entries(app.getPublicEnv())
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
     ),
   };
 };

package/frontendBuild/clientEntryDiscovery.test.ts

@@ -0,0 +1,112 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+
+const dirs: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(dirs.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("GraphClientEntryDiscovery", () => {
+  test("a walk an invalidation overtook answers its caller but leaves nothing stale for the next one", async () => {
+    for (const yields of [0, 5, 10, 20, 40, 80]) {
+      const dir = await mkdtemp(path.join(os.tmpdir(), "akan-discovery-"));
+      dirs.push(dir);
+      const file = (name: string) => path.join(dir, name);
+      await Bun.write(file("S.tsx"), 'import "./A";\n');
+      await Bun.write(file("A.tsx"), 'import "./B";\nimport "./D";\n');
+      await Bun.write(file("B.tsx"), "export const b = 1;\n");
+      await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+      await Bun.write(file("D.tsx"), "export const d = 1;\n");
+      const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+      expect(await discovery.discover([file("S.tsx")])).toEqual([]);
+
+      await Bun.write(file("B.tsx"), 'import "./C";\nexport const b = 1;\n');
+      await Bun.write(file("D.tsx"), "export const d = 2;\n");
+      discovery.invalidate([file("D.tsx")]);
+      const walk = discovery.discover([file("S.tsx")]);
+      for (let tick = 0; tick < yields; tick++) await Promise.resolve();
+      discovery.invalidate([file("B.tsx")]);
+      await walk;
+      expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
+    }
+  });
+
+  const tempDir = async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-discovery-"));
+    dirs.push(dir);
+    return (name: string) => path.join(dir, name);
+  };
+
+  test("an entry moved into a folder, or to another extension, is found once the move is invalidated", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./ui/Chart";\nimport "./ui/Card";\n');
+    await Bun.write(file("ui/Chart.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await Bun.write(file("ui/Card.tsx"), '"use client";\nexport const Card = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.tsx"), file("ui/Chart.tsx")]);
+
+    await rm(file("ui/Chart.tsx"));
+    await Bun.write(file("ui/Chart/index.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await rm(file("ui/Card.tsx"));
+    await Bun.write(file("ui/Card.ts"), '"use client";\nexport const Card = () => null;\n');
+    discovery.invalidate([file("ui/Chart.tsx"), file("ui/Chart/index.tsx"), file("ui/Card.tsx"), file("ui/Card.ts")]);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.ts"), file("ui/Chart/index.tsx")]);
+  });
+
+  test("a resolution still in flight when its target appears is not what the next walk reads", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./B";\n');
+    await Bun.write(file("B.tsx"), 'import "@demo/C";\nexport const b = 1;\n');
+    const gate = Promise.withResolvers<void>();
+    const seen = Promise.withResolvers<void>();
+    let calls = 0;
+    const resolvePackage = async () => {
+      calls += 1;
+      const exists = await Bun.file(file("C.tsx")).exists();
+      if (calls === 1) {
+        seen.resolve();
+        await gate.promise;
+      }
+      return exists ? { entryFile: file("C.tsx") } : null;
+    };
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, resolvePackage as never);
+    const walk = discovery.discover([file("S.tsx")]);
+    await seen.promise;
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    discovery.invalidate([file("C.tsx")]);
+    gate.resolve();
+    await walk;
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a dense import cycle is walked once per file, not once per path", async () => {
+    const file = await tempDir();
+    const names = Array.from({ length: 12 }, (_, idx) => `M${idx}.tsx`);
+    for (const name of names)
+      await Bun.write(file(name), names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join(""));
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    await Bun.write(
+      file("M11.tsx"),
+      `${names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join("")}import "./C";\n`,
+    );
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    const started = performance.now();
+    expect(await discovery.discover([file("M0.tsx")])).toEqual([file("C.tsx")]);
+    expect(performance.now() - started).toBeLessThan(2_000);
+    expect(await discovery.discover([file("M5.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a file walked inside an import cycle keeps no partial result for a walk that starts at it", async () => {
+    const file = await tempDir();
+    await Bun.write(file("A.tsx"), 'import "./B";\nimport "./C";\n');
+    await Bun.write(file("B.tsx"), 'import "./A";\n');
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("A.tsx")])).toEqual([file("C.tsx")]);
+    expect(await discovery.discover([file("B.tsx")])).toEqual([file("C.tsx")]);
+  });
+});

package/frontendBuild/clientEntryDiscovery.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
@@ -17,6 +18,21 @@ interface FileFacts {
   imports: ScannedImport[];
 }
 
+interface Lookup<T> {
+  epoch: number;
+  promise: Promise<T>;
+  found?: boolean;
+}
+
+interface DiscoveryWalk {
+  visiting: Set<string>;
+  //? Walked below a file the walk was already inside (an import cycle): their result lacks what that file reaches.
+  partial: Set<string>;
+  //? Every file's result within this walk, partial ones included: the file the cycle went back to is an ancestor here
+  //? and brings the rest itself, and re-walking each path through a dense cycle grows exponentially.
+  memo: Map<string, Set<string>>;
+}
+
 const shouldSkipNodeModule = (absPath: string) => NODE_MODULES_RE.test(absPath) && !AKANJS_NODE_MODULE_RE.test(absPath);
 
 /** `"use client"` discovery over the import graph (dynamic imports included), flattening barrels as the bundler does. */
@@ -25,15 +41,16 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #resolvePackage: PackageResolver;
   #analyzer: BarrelAnalyzer;
   #tsTranspiler = new Bun.Transpiler({ loader: "tsx" });
-  #fileExistsCache = new Map<string, Promise<boolean>>();
+  #fileExistsCache = new Map<string, Lookup<boolean>>();
   // Facts, never source text: this instance lives as long as the builder process, so texts would pin every file walked.
   #factsCache = new Map<string, Promise<FileFacts | null>>();
-  #resolvedFileCache = new Map<string, Promise<string | null>>();
-  #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
+  #resolvedFileCache = new Map<string, Lookup<string | null>>();
+  #resolvedSpecifierCache = new Map<string, Lookup<string | null>>();
   #reachableEntriesCache = new Map<string, Set<string>>();
-  #missingFiles = new Set<string>();
-  #unresolvedPaths = new Set<string>();
-  #unresolvedSpecifiers = new Set<string>();
+  #readFiles = new Set<string>();
+  //? Bumped by every invalidation: a walk that began before one computed from facts it may have read stale, so it
+  //? answers its caller but caches nothing (a registry check walks this instance beside the slow lane's route builds).
+  #epoch = 0;
 
   constructor(akanConfig: Pick<AkanConfig, "barrelImports">, resolvePackage: PackageResolver) {
     this.#akanConfig = akanConfig;
@@ -48,47 +65,61 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   async discover(seeds: string[]): Promise<string[]> {
     const entries = new Set<string>();
     for (const seed of seeds) {
-      for (const entry of await this.#discoverFromFile(seed, new Set())) entries.add(entry);
+      const walk: DiscoveryWalk = { visiting: new Set(), partial: new Set(), memo: new Map() };
+      for (const entry of await this.#discoverFromFile(seed, walk)) entries.add(entry);
     }
     return Array.from(entries).sort();
   }
 
   invalidate(files: string[]): void {
+    if (files.length === 0) return;
+    let moved = false;
     for (const file of files) {
       const absPath = path.resolve(file);
+      const exists = fs.existsSync(absPath);
+      if (exists !== this.#readFiles.has(absPath)) moved = true;
+      if (!exists) this.#readFiles.delete(absPath);
       this.#factsCache.delete(absPath);
       this.#fileExistsCache.delete(absPath);
-      this.#reachableEntriesCache.delete(absPath);
     }
-    if (files.length === 0) return;
+    this.#epoch += 1;
     // Reachable-entry results are transitive, so a changed child invalidates every ancestor.
     this.#reachableEntriesCache.clear();
-    this.#forgetMissing();
+    //? A file gone, or one never read, can leave a found resolution on its old target (`Chart.tsx` to
+    //? `Chart/index.tsx`), so a move drops them all; a save of a file already read keeps them (a walk re-resolving
+    //? every package cost 3x). Misses lapse with the epoch on their own (#lookup).
+    if (!moved) return;
+    this.#fileExistsCache.clear();
+    this.#resolvedFileCache.clear();
+    this.#resolvedSpecifierCache.clear();
   }
 
-  // Negatives are keyed by extension-less path or `dir\0specifier`, which a new file's path cannot reach, so all go.
-  #forgetMissing(): void {
-    for (const key of this.#missingFiles) this.#fileExistsCache.delete(key);
-    for (const key of this.#unresolvedPaths) this.#resolvedFileCache.delete(key);
-    for (const key of this.#unresolvedSpecifiers) this.#resolvedSpecifierCache.delete(key);
-    this.#missingFiles.clear();
-    this.#unresolvedPaths.clear();
-    this.#unresolvedSpecifiers.clear();
+  //? A found answer outlives later epochs; a miss, or a lookup still in flight, answers only walks of its own epoch, so
+  //? a file created meanwhile is looked up again.
+  #lookup<T>(cache: Map<string, Lookup<T>>, key: string, run: () => Promise<T>, isFound: (value: T) => boolean) {
+    const cached = cache.get(key);
+    if (cached && (cached.found || cached.epoch === this.#epoch)) return cached.promise;
+    const entry: Lookup<T> = { epoch: this.#epoch, promise: run() };
+    entry.promise.then(
+      (value) => {
+        entry.found = isFound(value);
+      },
+      () => {
+        entry.found = false;
+      },
+    );
+    cache.set(key, entry);
+    return entry.promise;
   }
 
   async #fileExists(p: string): Promise<boolean> {
     const absPath = path.resolve(p);
-    let cached = this.#fileExistsCache.get(absPath);
-    if (!cached) {
-      cached = Bun.file(absPath)
-        .exists()
-        .then((exists) => {
-          if (!exists) this.#missingFiles.add(absPath);
-          return exists;
-        });
-      this.#fileExistsCache.set(absPath, cached);
-    }
-    return cached;
+    return await this.#lookup(
+      this.#fileExistsCache,
+      absPath,
+      () => Bun.file(absPath).exists(),
+      (exists) => exists,
+    );
   }
 
   #facts(file: string): Promise<FileFacts | null> {
@@ -100,6 +131,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
           .text()
           .catch(() => null);
         if (content === null) return null;
+        this.#readFiles.add(absPath);
         if (USE_CLIENT_RE.test(content)) return { isClientEntry: true, imports: [] };
         return { isClientEntry: false, imports: this.#scanImports(await this.#rewrite(content)) };
       })();
@@ -127,57 +159,71 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
 
   async #resolveFileCandidate(absPathNoExt: string): Promise<string | null> {
     const cacheKey = path.resolve(absPathNoExt);
-    let cached = this.#resolvedFileCache.get(cacheKey);
-    if (cached) return cached;
-    cached = (async () => {
-      if (await this.#fileExists(cacheKey)) return cacheKey;
-      for (const ext of SOURCE_EXTS) {
-        const f = `${cacheKey}${ext}`;
-        if (await this.#fileExists(f)) return f;
-      }
-      for (const ext of SOURCE_EXTS) {
-        const f = path.join(cacheKey, `index${ext}`);
-        if (await this.#fileExists(f)) return f;
-      }
-      this.#unresolvedPaths.add(cacheKey);
-      return null;
-    })();
-    this.#resolvedFileCache.set(cacheKey, cached);
-    return cached;
+    return await this.#lookup(
+      this.#resolvedFileCache,
+      cacheKey,
+      async () => {
+        if (await this.#fileExists(cacheKey)) return cacheKey;
+        for (const ext of SOURCE_EXTS) {
+          const f = `${cacheKey}${ext}`;
+          if (await this.#fileExists(f)) return f;
+        }
+        for (const ext of SOURCE_EXTS) {
+          const f = path.join(cacheKey, `index${ext}`);
+          if (await this.#fileExists(f)) return f;
+        }
+        return null;
+      },
+      (file) => file !== null,
+    );
   }
 
   async #resolveSpecifier(spec: string, importerDir: string): Promise<string | null> {
     const cacheKey = `${importerDir}\0${spec}`;
-    let cached = this.#resolvedSpecifierCache.get(cacheKey);
-    if (cached) return cached;
-    cached = (async () => {
-      if (spec.startsWith(".") || spec.startsWith("/")) {
-        const abs = spec.startsWith("/") ? spec : path.resolve(importerDir, spec);
-        return this.#resolveFileCandidate(abs);
-      }
-      const pkg = await this.#resolvePackage(spec);
-      if (pkg) return pkg.entryFile;
-      this.#unresolvedSpecifiers.add(cacheKey);
-      return null;
-    })();
-    this.#resolvedSpecifierCache.set(cacheKey, cached);
-    return cached;
+    return await this.#lookup(
+      this.#resolvedSpecifierCache,
+      cacheKey,
+      async () => {
+        if (spec.startsWith(".") || spec.startsWith("/")) {
+          const abs = spec.startsWith("/") ? spec : path.resolve(importerDir, spec);
+          return await this.#resolveFileCandidate(abs);
+        }
+        const pkg = await this.#resolvePackage(spec);
+        return pkg ? pkg.entryFile : null;
+      },
+      (file) => file !== null,
+    );
   }
 
-  async #discoverFromFile(file: string, visiting: Set<string>): Promise<Set<string>> {
+  async #discoverFromFile(file: string, walk: DiscoveryWalk): Promise<Set<string>> {
+    const epoch = this.#epoch;
     const absPath = path.resolve(file);
     const cached = this.#reachableEntriesCache.get(absPath);
     if (cached) return new Set(cached);
-    if (visiting.has(absPath) || shouldSkipNodeModule(absPath)) return new Set();
+    const memo = walk.memo.get(absPath);
+    if (memo) {
+      //? Reused from another path: whatever this path is walking now inherits its gap and stays out of the cache.
+      if (walk.partial.has(absPath)) for (const onPath of walk.visiting) walk.partial.add(onPath);
+      return new Set(memo);
+    }
+    if (walk.visiting.has(absPath)) {
+      let below = false;
+      for (const onPath of walk.visiting) {
+        if (below) walk.partial.add(onPath);
+        else below = onPath === absPath;
+      }
+      return new Set();
+    }
+    if (shouldSkipNodeModule(absPath)) return new Set();
 
-    visiting.add(absPath);
+    walk.visiting.add(absPath);
     const entries = new Set<string>();
     const facts = await this.#facts(absPath);
-    if (!facts) return this.#finishDiscovery(absPath, visiting, entries);
+    if (!facts) return this.#finishDiscovery(absPath, walk, entries, epoch);
 
     if (facts.isClientEntry) {
       entries.add(absPath);
-      return this.#finishDiscovery(absPath, visiting, entries);
+      return this.#finishDiscovery(absPath, walk, entries, epoch);
     }
 
     const importerDir = path.dirname(absPath);
@@ -188,15 +234,16 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
       const resolved = await this.#resolveSpecifier(spec, importerDir);
       if (!resolved) continue;
       if (shouldSkipNodeModule(resolved)) continue;
-      for (const entry of await this.#discoverFromFile(resolved, visiting)) entries.add(entry);
+      for (const entry of await this.#discoverFromFile(resolved, walk)) entries.add(entry);
     }
 
-    return this.#finishDiscovery(absPath, visiting, entries);
+    return this.#finishDiscovery(absPath, walk, entries, epoch);
   }
 
-  #finishDiscovery(absPath: string, visiting: Set<string>, entries: Set<string>): Set<string> {
-    visiting.delete(absPath);
-    this.#reachableEntriesCache.set(absPath, entries);
+  #finishDiscovery(absPath: string, walk: DiscoveryWalk, entries: Set<string>, epoch: number): Set<string> {
+    walk.visiting.delete(absPath);
+    walk.memo.set(absPath, entries);
+    if (epoch === this.#epoch && !walk.partial.has(absPath)) this.#reachableEntriesCache.set(absPath, entries);
     return new Set(entries);
   }
 }

package/frontendBuild/csrArtifactBuilder.ts

@@ -4,7 +4,7 @@ import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
 import { bundleDefine } from "./bundleDefine";
-import { getPageKeyBasePath } from "./cssCompiler";
+import { CsrEntryFiles } from "./csrEntryFiles";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
@@ -80,10 +80,7 @@ export class CsrArtifactBuilder {
 
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
-    return pageEntries.filter((entry) => {
-      const entryBasePath = getPageKeyBasePath(entry.key, basePaths);
-      return entryBasePath === null || entryBasePath === basePath;
-    });
+    return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);
   }
 
   static htmlFilename(basePath: string): string {
@@ -91,7 +88,7 @@ export class CsrArtifactBuilder {
   }
 
   static entryFilename(basePath: string): string {
-    return `${basePath || "index"}.csr.tsx`;
+    return CsrEntryFiles.entryFilename(basePath);
   }
 
   static basePathOfHtml(htmlPath: string): string {

package/frontendBuild/csrDevArtifactWriter.test.ts

@@ -0,0 +1,143 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  CSR_DEV_MANIFEST_FILE,
+  CSR_DEV_ROUTE_PREFIX,
+  type CsrDevManifest,
+  csrDevModuleFile,
+} from "akanjs/server/hmr/csrDevManifest";
+import { CsrDevArtifactWriter, type CsrDevArtifactWriterOptions } from "./csrDevArtifactWriter";
+import type { CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+
+const dirs: string[] = [];
+const module: CsrDevCompiledModule = {
+  id: "a.ts",
+  file: "/a.ts",
+  vendor: false,
+  factory: "function () {}",
+  helpers: null,
+  deps: [],
+  mtimeMs: 0,
+  hash: "",
+};
+const readModule = (dir: string) => readFileSync(path.join(dir, csrDevModuleFile("a.ts", ".js")), "utf8");
+const makeWriter = async (
+  options: CsrDevArtifactWriterOptions = { routePrefix: CSR_DEV_ROUTE_PREFIX },
+  entries: Record<string, string> = {},
+) => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-writer-"));
+  dirs.push(dir);
+  const writer = new CsrDevArtifactWriter(dir, options);
+  const graph: CsrDevGraph = {
+    version: 1,
+    configKey: "key",
+    refresh: "refresh.js",
+    entries,
+    modules: { "a.ts": { vendor: false, mtimeMs: 0, hash: "", deps: [] } },
+    resolution: {},
+    pending: [],
+  };
+  await writer.writeModules([module]);
+  const read = () => ({
+    manifest: JSON.parse(readFileSync(path.join(dir, CSR_DEV_MANIFEST_FILE), "utf8")) as CsrDevManifest,
+    app: readFileSync(path.join(dir, "app.js"), "utf8"),
+  });
+  return { writer, graph, read, dir };
+};
+
+afterAll(async () => {
+  await Promise.all(dirs.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("CsrDevArtifactWriter", () => {
+  test("announces a patch before the module files, graph.json and app.js catch up", async () => {
+    const { writer, graph, read, dir } = await makeWriter();
+    await writer.writeApp(graph, { generation: 4, vendorFile: "v.js" });
+    const edited = { ...module, factory: "function () { edited(); }" };
+    let atAnnounce: (ReturnType<typeof read> & { graph: boolean; module: string }) | null = null;
+    await writer.commitPatch(
+      graph,
+      { version: 1, generation: 5, appGeneration: 4, vendorFile: "v.js", entries: {} },
+      () => {
+        atAnnounce = { ...read(), graph: existsSync(path.join(dir, "graph.json")), module: readModule(dir) };
+      },
+      { modules: [edited] },
+    );
+    expect(atAnnounce).toMatchObject({ manifest: { generation: 5, appGeneration: 4 }, graph: false });
+    expect((atAnnounce as { app: string } | null)?.app).toContain('"generation":4');
+    expect((atAnnounce as { module: string } | null)?.module).not.toContain("edited");
+    const after = read();
+    expect(after.manifest).toMatchObject({ generation: 5, appGeneration: 5 });
+    expect(after.app).toContain('"generation":5');
+    expect(after.app).toContain("edited()");
+    expect(existsSync(path.join(dir, "graph.json"))).toBe(true);
+  });
+
+  test("rewrites an app.js a crash left behind the manifest's generation", async () => {
+    const { writer, graph, read } = await makeWriter();
+    await writer.writeApp(graph, { generation: 5, vendorFile: "v.js" });
+    const behind: CsrDevManifest = { version: 1, generation: 6, appGeneration: 5, vendorFile: "v.js", entries: {} };
+    await writer.writeJson(CSR_DEV_MANIFEST_FILE, behind);
+    const healed = await writer.healApp(graph, behind);
+    expect(healed.appGeneration).toBe(6);
+    expect(read().manifest.appGeneration).toBe(6);
+    expect(read().app).toContain('"generation":6');
+  });
+
+  test("leaves an app.js that already holds the manifest's generation alone", async () => {
+    const { writer, graph } = await makeWriter();
+    const current: CsrDevManifest = { version: 1, generation: 3, vendorFile: "v.js", entries: {} };
+    expect(await writer.healApp(graph, current)).toBe(current);
+  });
+
+  test("a library app.js starts its bootstrap module, and a patch is announced under the writer's route", async () => {
+    const { writer, graph, dir } = await makeWriter(
+      { routePrefix: "/_akan/ssr-dev/", library: true },
+      { "": "boot.ts" },
+    );
+    await writer.writeApp(graph, { generation: 2, vendorFile: "v.js", epoch: 7 });
+    expect(readFileSync(path.join(dir, "app.js"), "utf8")).toContain(
+      '__akan.startLibrary({"generation":2,"refresh":"refresh.js","bootstrap":"boot.ts","vendorFile":"v.js","epoch":7});',
+    );
+    expect(await writer.writePatch(3, [module])).toBe("/_akan/ssr-dev/patch-3.js");
+  });
+
+  test("after a whole build, clears what the registry before it left and keeps what the build wrote", async () => {
+    const { writer, graph, dir } = await makeWriter();
+    const gone = { ...module, id: "gone.ts" };
+    await writer.writeModules([gone]);
+    await writer.writePatch(7, [module]);
+    await Bun.write(path.join(dir, "assets/old-abc.png"), "old");
+    await Bun.write(path.join(dir, ".patching"), "123");
+    await Bun.write(path.join(dir, "manifest.json.4242.tmp"), "{");
+    await Bun.write(path.join(dir, "assets/new-def.png"), "new");
+    await writer.pruneAfterFullBuild(graph, "vendor-a.js", {
+      generation: 8,
+      assets: [path.join(dir, "assets/new-def.png")],
+    });
+    expect(existsSync(path.join(dir, csrDevModuleFile("a.ts", ".js")))).toBe(true);
+    expect(existsSync(path.join(dir, csrDevModuleFile("gone.ts", ".js")))).toBe(false);
+    expect(existsSync(path.join(dir, "patch-7.js"))).toBe(false);
+    expect(existsSync(path.join(dir, "patch-7.js.layout.json"))).toBe(false);
+    expect(existsSync(path.join(dir, "assets/old-abc.png"))).toBe(false);
+    expect(existsSync(path.join(dir, "assets/new-def.png"))).toBe(true);
+    expect(existsSync(path.join(dir, ".patching"))).toBe(false);
+    expect(existsSync(path.join(dir, "manifest.json.4242.tmp"))).toBe(false);
+  });
+
+  test("a reload drops a patch file left under its generation, and a whole build is marked while it writes", async () => {
+    const { writer, dir } = await makeWriter();
+    await writer.writePatch(6, [module]);
+    await writer.forgetPatch(6);
+    expect(existsSync(path.join(dir, "patch-6.js"))).toBe(false);
+    expect(existsSync(path.join(dir, "patch-6.js.layout.json"))).toBe(false);
+    expect(await writer.isBuilding()).toBe(false);
+    await writer.markBuilding();
+    expect(await writer.isBuilding()).toBe(true);
+    await writer.clearBuilding();
+    expect(await writer.isBuilding()).toBe(false);
+  });
+});