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

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,37 @@
+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")]);
+    }
+  });
+});

package/frontendBuild/clientEntryDiscovery.ts

@@ -34,6 +34,9 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #missingFiles = new Set<string>();
   #unresolvedPaths = new Set<string>();
   #unresolvedSpecifiers = 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;
@@ -61,6 +64,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
       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();
@@ -165,6 +169,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   }
 
   async #discoverFromFile(file: string, visiting: Set<string>): Promise<Set<string>> {
+    const epoch = this.#epoch;
     const absPath = path.resolve(file);
     const cached = this.#reachableEntriesCache.get(absPath);
     if (cached) return new Set(cached);
@@ -173,11 +178,11 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
     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, visiting, entries, epoch);
 
     if (facts.isClientEntry) {
       entries.add(absPath);
-      return this.#finishDiscovery(absPath, visiting, entries);
+      return this.#finishDiscovery(absPath, visiting, entries, epoch);
     }
 
     const importerDir = path.dirname(absPath);
@@ -191,12 +196,12 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
       for (const entry of await this.#discoverFromFile(resolved, visiting)) entries.add(entry);
     }
 
-    return this.#finishDiscovery(absPath, visiting, entries);
+    return this.#finishDiscovery(absPath, visiting, entries, epoch);
   }
 
-  #finishDiscovery(absPath: string, visiting: Set<string>, entries: Set<string>): Set<string> {
+  #finishDiscovery(absPath: string, visiting: Set<string>, entries: Set<string>, epoch: number): Set<string> {
     visiting.delete(absPath);
-    this.#reachableEntriesCache.set(absPath, entries);
+    if (epoch === this.#epoch) 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);
+  });
+});

package/frontendBuild/csrDevArtifactWriter.ts

@@ -1,28 +1,62 @@
-import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import fs from "node:fs";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import {
+  appGenerationOf,
   CSR_DEV_APP_FILE,
+  CSR_DEV_KEPT_PATCHES,
   CSR_DEV_MANIFEST_FILE,
-  CSR_DEV_ROUTE_PREFIX,
+  CSR_DEV_PATCHING_MARKER,
   type CsrDevLayout,
   type CsrDevManifest,
   csrDevModuleFile,
 } from "akanjs/server/hmr/csrDevManifest";
+import { FileSys } from "../fileSys";
 import { CsrDevPaths } from "./csrDevPaths";
-import type { CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevCode, CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+
+export interface CsrDevArtifactWriterOptions {
+  /** Where the dev server serves `outDir`; a patch is announced by its URL. */
+  routePrefix: string;
+  /** `app.js` starts no entry: an SSR page requires the modules its RSC payload names, one at a time. */
+  library?: boolean;
+}
 
 export class CsrDevArtifactWriter {
-  static readonly #keptPatches = 40;
   static readonly #keptVendors = 3;
+  static readonly #buildingMarker = ".building";
   readonly #outDir: string;
+  readonly #routePrefix: string;
+  readonly #library: boolean;
 
-  constructor(outDir: string) {
+  constructor(outDir: string, { routePrefix, library = false }: CsrDevArtifactWriterOptions) {
     this.#outDir = outDir;
+    this.#routePrefix = routePrefix;
+    this.#library = library;
   }
 
-  async reset(): Promise<void> {
-    await rm(this.#outDir, { recursive: true, force: true });
-    await mkdir(path.join(this.#outDir, "modules"), { recursive: true });
+  //? Set between a whole build's first write and its last: module files are named by id and overwritten in place, so a
+  //? build cut short there leaves new modules under the previous graph and app.js, which no patch may read.
+  async markBuilding(): Promise<void> {
+    await Bun.write(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker), String(process.pid));
+  }
+
+  async clearBuilding(): Promise<void> {
+    await CsrDevArtifactWriter.#remove(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker));
+  }
+
+  async isBuilding(): Promise<boolean> {
+    return await Bun.file(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker)).exists();
+  }
+
+  //? A reload's generation has no patch: one an attempt cut short left under that number would be applied by a tab
+  //? catching up (catchUp reloads only when the file is missing).
+  async forgetPatch(generation: number): Promise<void> {
+    await Promise.all(
+      [`patch-${generation}.js`, `patch-${generation}.js.layout.json`].map((name) =>
+        CsrDevArtifactWriter.#remove(path.join(this.#outDir, name)),
+      ),
+    );
   }
 
   async readJson<T>(name: string): Promise<T | null> {
@@ -49,11 +83,26 @@ export class CsrDevArtifactWriter {
     ]);
   }
 
+  //? A module whose file is missing is left out rather than failing the read: the patcher compiles it again.
+  async readCode(graph: CsrDevGraph): Promise<CsrDevCode> {
+    const ids = Object.keys(graph.modules).filter((id) => !graph.modules[id]?.vendor && this.hasModule(id));
+    const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))];
+    const [modules, helpers] = await Promise.all([
+      Promise.all(ids.map(async (id) => [id, await Bun.file(this.#modulePath(id, ".js")).text()] as const)),
+      Promise.all(hashes.map(async (hash) => [hash, await Bun.file(this.#helpersPath(hash)).text()] as const)),
+    ]);
+    return { modules: new Map(modules), helpers: new Map(helpers) };
+  }
+
+  hasModule(id: string): boolean {
+    return fs.existsSync(this.#modulePath(id, ".js"));
+  }
+
   async forgetModules(ids: string[]): Promise<void> {
     await Promise.all(
       ids.flatMap((id) => [
-        rm(this.#modulePath(id, ".js"), { force: true }),
-        rm(this.#modulePath(id, ".js.map"), { force: true }),
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js")),
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js.map")),
       ]),
     );
   }
@@ -76,14 +125,22 @@ export class CsrDevArtifactWriter {
     return vendorFile;
   }
 
-  async writeApp(graph: CsrDevGraph, generation: number): Promise<void> {
+  //? A library app.js names the vendor file and epoch it was built with: a tab that booted it beside another build's
+  //? vendor file (a whole build landing between its render and its load) tells, and keeps the right epoch for hello.
+  async writeApp(
+    graph: CsrDevGraph,
+    { generation, vendorFile, epoch }: Pick<CsrDevManifest, "generation" | "vendorFile" | "epoch">,
+    code?: CsrDevCode,
+  ): Promise<void> {
     const ids = Object.keys(graph.modules)
       .filter((id) => !graph.modules[id]?.vendor)
       .sort();
-    const lines = await this.#defineLines(ids);
+    const lines = await this.#defineLines(ids, code);
     const blocks = ids.map((id, index) => [id, lines[index] ?? ""] as [string, string]);
-    const start = `__akan.start(${JSON.stringify({ generation, refresh: graph.refresh })});\n`;
-    await this.#writeWithSourceMap(CSR_DEV_APP_FILE, await this.#helperDefinitions(graph, ids), blocks, start);
+    const start = this.#library
+      ? `__akan.startLibrary(${JSON.stringify({ generation, refresh: graph.refresh, bootstrap: graph.entries[""], vendorFile, epoch })});\n`
+      : `__akan.start(${JSON.stringify({ generation, refresh: graph.refresh })});\n`;
+    await this.#writeWithSourceMap(CSR_DEV_APP_FILE, await this.#helperDefinitions(graph, ids, code), blocks, start);
   }
 
   async writePatch(generation: number, modules: CsrDevCompiledModule[]): Promise<string> {
@@ -100,7 +157,7 @@ export class CsrDevArtifactWriter {
     );
     const header = `${[...helpers.values()].map((shared) => shared.definition).join("")}__akan.update(${generation}, {\n`;
     await this.#writeWithSourceMap(patchFile, header, blocks, "});\n");
-    return `${CSR_DEV_ROUTE_PREFIX}${patchFile}`;
+    return `${this.#routePrefix}${patchFile}`;
   }
 
   // The manifest goes last: the server renders shells from it, so it must never name a file not yet written.
@@ -109,11 +166,39 @@ export class CsrDevArtifactWriter {
     await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
   }
 
+  //? The open tabs need only the patch file and the manifest naming it, so they hear of a patch before the rest lands:
+  //? the module files and graph.json (read only by the next build), then app.js (a full rewrite). The manifest says
+  //? which generation app.js holds, and the shell holds a tab booting in that gap until it does. A crash in the gap is
+  //? recovered by the next build, which sees the edited files' mtimes differ from graph.json and compiles them again.
+  async commitPatch(
+    graph: CsrDevGraph,
+    manifest: CsrDevManifest,
+    announce: () => void,
+    { modules, code }: { modules: CsrDevCompiledModule[]; code?: CsrDevCode },
+  ): Promise<void> {
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
+    announce();
+    await CsrDevArtifactWriter.#appWriteDelay();
+    await this.writeModules(modules);
+    await this.writeJson("graph.json", graph);
+    await this.writeApp(graph, manifest, code);
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, { ...manifest, appGeneration: manifest.generation });
+  }
+
+  // A process that died between announcing a patch and rewriting app.js left every booting tab one generation behind.
+  async healApp(graph: CsrDevGraph, manifest: CsrDevManifest, code?: CsrDevCode): Promise<CsrDevManifest> {
+    if (appGenerationOf(manifest) >= manifest.generation) return manifest;
+    await this.writeApp(graph, manifest, code);
+    const healed = { ...manifest, appGeneration: manifest.generation };
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, healed);
+    return healed;
+  }
+
   async prune(vendorFile: string, generation: number): Promise<void> {
     const names = await readdir(this.#outDir);
     const stale = names.filter((name) => {
       const patch = /^patch-(\d+)\.js(?:\.layout\.json)?$/.exec(name);
-      return patch ? Number(patch[1]) <= generation - CsrDevArtifactWriter.#keptPatches : false;
+      return patch ? Number(patch[1]) <= generation - CSR_DEV_KEPT_PATCHES : false;
     });
     const vendors = names
       .filter((name) => /^vendor-[\w-]+\.js$/.test(name) && name !== vendorFile)
@@ -121,19 +206,55 @@ export class CsrDevArtifactWriter {
       .sort((a, b) => b.mtimeMs - a.mtimeMs)
       .slice(CsrDevArtifactWriter.#keptVendors - 1)
       .map(({ name }) => name);
-    await Promise.all([...stale, ...vendors].map((name) => rm(path.join(this.#outDir, name), { force: true })));
+    await Promise.all(
+      [...stale, ...vendors].map((name) => CsrDevArtifactWriter.#remove(path.join(this.#outDir, name))),
+    );
   }
 
-  async #helperDefinitions(graph: CsrDevGraph, ids: string[]): Promise<string> {
+  //? A whole build writes over the registry before it instead of clearing it first, so it clears what that one left:
+  //? the modules and helpers it no longer holds, every patch (each was made against the previous registry), the assets
+  //? this build did not write (by path: a file's mtime and this process's clock need not agree on a mounted volume),
+  //? temp files of a write cut short, and the marker of a builder that died mid-patch.
+  async pruneAfterFullBuild(
+    graph: CsrDevGraph,
+    vendorFile: string,
+    { generation, assets }: { generation: number; assets: string[] },
+  ): Promise<void> {
+    const kept = new Set(
+      Object.keys(graph.modules).flatMap((id) => [this.#modulePath(id, ".js"), this.#modulePath(id, ".js.map")]),
+    );
+    for (const module of Object.values(graph.modules)) if (module.helpers) kept.add(this.#helpersPath(module.helpers));
+    for (const asset of assets) kept.add(path.resolve(asset));
+    const listed = async (dir: string) =>
+      (await readdir(path.join(this.#outDir, dir)).catch(() => [] as string[])).map((name) =>
+        path.join(this.#outDir, dir, name),
+      );
+    const stale = [
+      ...(await listed("modules")).filter((file) => !kept.has(file)),
+      ...(await listed("assets")).filter((file) => !kept.has(file)),
+      ...(await listed(".")).filter((file) => {
+        const name = path.basename(file);
+        return /^patch-\d+\.js(?:\.layout\.json)?$/.test(name) || name.endsWith(".tmp");
+      }),
+      path.join(this.#outDir, CSR_DEV_PATCHING_MARKER),
+    ];
+    await Promise.all(stale.map((file) => CsrDevArtifactWriter.#remove(file)));
+    await this.prune(vendorFile, generation);
+  }
+
+  async #helperDefinitions(graph: CsrDevGraph, ids: string[], code?: CsrDevCode): Promise<string> {
     const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))].sort();
-    return (await Promise.all(hashes.map((hash) => Bun.file(this.#helpersPath(hash)).text()))).join("");
+    return (
+      await Promise.all(hashes.map(async (hash) => code?.helpers.get(hash) ?? Bun.file(this.#helpersPath(hash)).text()))
+    ).join("");
   }
 
-  async #defineLines(ids: string[]): Promise<string[]> {
+  async #defineLines(ids: string[], code?: CsrDevCode): Promise<string[]> {
     return await Promise.all(
-      ids.map(
-        async (id) => `__akan.define(${JSON.stringify(id)}, ${await Bun.file(this.#modulePath(id, ".js")).text()});\n`,
-      ),
+      ids.map(async (id) => {
+        const factory = code?.modules.get(id) ?? (await Bun.file(this.#modulePath(id, ".js")).text());
+        return `__akan.define(${JSON.stringify(id)}, ${factory});\n`;
+      }),
     );
   }
 
@@ -156,7 +277,20 @@ export class CsrDevArtifactWriter {
     const target = path.join(this.#outDir, name);
     const temp = `${target}.${process.pid}.tmp`;
     await Bun.write(temp, content);
-    await rename(temp, target);
+    await FileSys.replace(temp, target);
+  }
+
+  //? Best effort, after the tabs already have the update: Windows refuses to delete a file a reader holds open (the
+  //? server streaming it to a tab), and throwing here would send a patch that already went out to a build worker.
+  //? A file that stays is removed by a later prune.
+  static async #remove(file: string): Promise<void> {
+    await rm(file, { force: true }).catch(() => undefined);
+  }
+
+  //? A test-only hook that widens the gap between the patch and app.js, so an E2E can boot a tab inside it.
+  static async #appWriteDelay(): Promise<void> {
+    const ms = Number(process.env.AKAN_CSR_DEV_APP_WRITE_DELAY_MS);
+    if (Number.isInteger(ms) && ms > 0) await Bun.sleep(ms);
   }
 
   #modulePath(id: string, extension: ".js" | ".js.map"): string {