@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/frontendBuild/clientEntryDiscovery.ts

@@ -1,61 +1,56 @@
+import fs from "node:fs";
 import path from "node:path";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import type { AkanConfig, ClientEntryDiscovery, ScannedImport } from "./clientBuildTypes";
 
 const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
-const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
-// File extensions whose imports can't produce React client components and that
-// the bundler handles via dedicated loaders. Skipping them avoids resolver
-// noise (Bun's scanImports surfaces CSS / asset imports too).
+// Bun's scanImports also surfaces CSS and asset imports, none of which can be a client component.
 const NON_SOURCE_EXT_RE = /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav)$/i;
 type PackageResolver = Awaited<ReturnType<typeof createTsconfigPackageResolver>>;
 
-/**
- * Everything the traversal ever asks of a file, which is why its text is not kept.
- *
- * `imports` is empty for a client entry: the walk stops there, so they are never scanned.
- */
 interface FileFacts {
   isClientEntry: boolean;
   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);
 
-/**
- * Graph-based `"use client"` discovery, seeded from an explicit file list.
- *
- * Walks imports — including dynamic `import()` — while flattening barrel
- * specifiers through the same `BarrelAnalyzer` the runtime plugin uses, so
- * the traversal matches the module graph the bundler will actually see.
- */
+/** `"use client"` discovery over the import graph (dynamic imports included), flattening barrels as the bundler does. */
 export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #akanConfig: Pick<AkanConfig, "barrelImports">;
   #resolvePackage: PackageResolver;
   #analyzer: BarrelAnalyzer;
   #tsTranspiler = new Bun.Transpiler({ loader: "tsx" });
-  #fileExistsCache = new Map<string, Promise<boolean>>();
-  /**
-   * Derived facts per file, never the source text.
-   *
-   * This instance lives as long as the builder process does — it is rebuilt only when the akan config
-   * changes — so caching whole source texts (and a second, barrel-rewritten copy of each) meant the
-   * watcher held every source file it had ever walked for the whole dev session. Nothing downstream
-   * wanted the text: the walk needs one boolean and one import list per file, and both were already
-   * cached separately under the same key.
-   */
+  #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>>();
-  /** Keys of the three caches above whose answer was "not there" — see `#forgetMissing`. */
-  #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;
@@ -70,61 +65,63 @@ 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;
-    // Parent files cache the transitive result of their imports, so a changed
-    // child can affect any reachable-entry cache above it.
+    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();
   }
 
-  /**
-   * Drop every "there is no such file" answer, because a batch may be what created it.
-   *
-   * These caches are keyed by extension-less path and by `dir\0specifier`, neither of which maps back
-   * to the path that just appeared, so a negative recorded before a module existed is unreachable any
-   * other way — and this instance lives as long as the builder process. Positive answers are kept:
-   * they are keyed by a real path, which arrives in `files` when it changes or goes away.
-   */
-  #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,
+    );
   }
 
-  /**
-   * Read a file once and keep only what the traversal asks of it. The text itself is dropped as soon
-   * as the boolean and the import list are out of it — see `#factsCache`.
-   */
   #facts(file: string): Promise<FileFacts | null> {
     const absPath = path.resolve(file);
     let cached = this.#factsCache.get(absPath);
@@ -134,7 +131,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
           .text()
           .catch(() => null);
         if (content === null) return null;
-        // A client entry ends the walk, so its imports are never needed.
+        this.#readFiles.add(absPath);
         if (USE_CLIENT_RE.test(content)) return { isClientEntry: true, imports: [] };
         return { isClientEntry: false, imports: this.#scanImports(await this.#rewrite(content)) };
       })();
@@ -162,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);
@@ -223,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

@@ -3,7 +3,8 @@ import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
-import { getPageKeyBasePath } from "./cssCompiler";
+import { bundleDefine } from "./bundleDefine";
+import { CsrEntryFiles } from "./csrEntryFiles";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
@@ -61,10 +62,9 @@ export class CsrArtifactBuilder {
       splitting: false,
       minify: true,
       env: "AKAN_PUBLIC_*",
-      define: this.#define(),
+      define: bundleDefine(this.#app, this.#command, "csr"),
       optimizeImports: akanConfig.optimizeImports,
-      // The base artifact's compiled sheet is the only stylesheet, as it is for SSR: a raw `.css` reached through
-      // the route graph is Tailwind source, and every root layout stylesheet in the graph would land in every HTML.
+      // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
       plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
@@ -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 {
@@ -118,17 +115,6 @@ export class CsrArtifactBuilder {
     return path.join(this.#generatedDir, filename);
   }
 
-  #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("csr"),
-      ...Object.fromEntries(
-        Object.entries(this.#app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
-      ),
-    };
-  }
-
   async #createEntryFile(basePath: string, pageEntries: PageEntry[]): Promise<readonly [string, string]> {
     return [
       this.#generatedPath(CsrArtifactBuilder.entryFilename(basePath)),
@@ -168,7 +154,7 @@ void bootCsr(pages);
 
   async #inlineCsrArtifacts(cssAssets: Record<string, CssAsset>): Promise<void> {
     const jsFiles = new Set<string>();
-    for (const htmlPath of await this.#htmlOutputPaths()) {
+    for (const htmlPath of await this.#listOutputFiles((filePath) => filePath.endsWith(".html"))) {
       const htmlFile = Bun.file(htmlPath);
       if (!(await htmlFile.exists())) continue;
       const basePath = CsrArtifactBuilder.basePathOfHtml(htmlPath);
@@ -210,10 +196,6 @@ void bootCsr(pages);
     return { html: next, jsFiles };
   }
 
-  async #htmlOutputPaths(): Promise<string[]> {
-    return await this.#listOutputFiles((filePath) => filePath.endsWith(".html"));
-  }
-
   async #listOutputFiles(predicate: (filePath: string) => boolean): Promise<string[]> {
     const glob = new Bun.Glob("**/*");
     const files: string[] = [];
@@ -223,12 +205,8 @@ void bootCsr(pages);
     return files.sort();
   }
 
-  /**
-   * Bun's HTML bundler hoists the module script into `<head>`, so once that script is inline its source is part
-   * of the text being searched — and a React bundle contains `<body` and `</head>` as strings. Positions are
-   * taken on a copy with script, style and comment bodies blanked, and the snippet always lands after whatever
-   * was injected before it: prepending would reverse the cascade order the caller chose.
-   */
+  // Bun hoists the module script into <head> and a React bundle contains "</head>" as text, so positions come from a
+  // copy with script/style/comment bodies blanked. Never prepends: that would reverse the caller's cascade order.
   static injectBeforeHeadEnd(html: string, snippet: string): string {
     const scannable = CsrArtifactBuilder.blankEmbeddedContent(html);
     const headEnd = scannable.search(/<\/head\s*>/i);

package/frontendBuild/csrDevArtifactWriter.test.ts

@@ -0,0 +1,151 @@
+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("a module a package's browser field turns off is written empty, and a Node built-in still throws", async () => {
+    const { writer, graph, dir } = await makeWriter();
+    graph.modules["a.ts"] = { vendor: false, mtimeMs: 0, hash: "", deps: ["stub:empty:fs", "stub:path"] };
+    const vendor = readFileSync(path.join(dir, await writer.writeVendor(graph)), "utf8");
+    expect(vendor).toContain('__akan.define("stub:empty:fs", function () {});');
+    expect(vendor).toContain("[akan-csr] path is a Node built-in the browser does not have");
+  });
+
+  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);
+  });
+});