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

package/csrE2e/csrPageStack.e2e.test.ts

@@ -0,0 +1,187 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+const TAB_A = "/e2e/stack/tab-a";
+const TAB_B = "/e2e/stack/tab-b";
+const item = (id: string) => `/e2e/stack/item?id=${id}`;
+
+const routeOf = (pathWithSearch: string) => pathWithSearch.split("?")[0].replace(/^\/[^/]+/, "/:lang");
+const CURRENT = '[id^="pageContainer-"]:not([aria-hidden="true"])';
+const UNDER = '[id^="pageContainer-"][aria-hidden="true"]';
+
+describe.skipIf(!CsrE2eHarness.enabled)("CSR page stack (minimal, /e2e/stack)", () => {
+  let csr: CsrE2eHarness;
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({ app: "minimal" });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await csr?.close();
+  }, 60_000);
+
+  const itemIdsIn = async (scope: string, options?: { mounted?: boolean }) =>
+    await csr.text(`${scope} [data-e2e-probe="item"] [data-e2e="item-id"]`, options);
+  const currentInput = `${CURRENT} [data-e2e-probe="item"] [data-e2e="input"]`;
+
+  test("an entry of the same route is its own page, and the one it covers waits under it with its state", async () => {
+    await csr.open(TAB_A);
+    await csr.navigate(item("1"));
+    await csr.type(currentInput, "first");
+    await csr.navigate(item("2"));
+    expect(await itemIdsIn(CURRENT)).toEqual(["2"]);
+    expect(await itemIdsIn(UNDER)).toEqual(["1"]);
+    expect(await csr.values(currentInput)).toEqual([""]);
+    await csr.back();
+    expect(await itemIdsIn(CURRENT)).toEqual(["1"]);
+    expect(await csr.values(currentInput)).toEqual(["first"]);
+    expect(await csr.reloaded()).toBe(false);
+  }, 60_000);
+
+  test("the stack keeps three hidden entries under the previous one, releases older ones, and reveals each on back", async () => {
+    await csr.open(TAB_A);
+    for (const id of ["11", "12", "13"]) await csr.navigate(item(id));
+    await csr.type(currentInput, "thirteen");
+    for (const id of ["14", "15", "16"]) await csr.navigate(item(id));
+    expect((await itemIdsIn('[id^="pageContainer-"]', { mounted: true })).sort()).toEqual([
+      "12",
+      "13",
+      "14",
+      "15",
+      "16",
+    ]);
+    for (const expected of ["15", "14", "13"]) {
+      await csr.back();
+      expect(await itemIdsIn(CURRENT)).toEqual([expected]);
+    }
+    expect(await csr.values(currentInput)).toEqual(["thirteen"]);
+    await csr.back();
+    await csr.back();
+    expect(await itemIdsIn(CURRENT)).toEqual(["11"]);
+    expect(await csr.values(currentInput)).toEqual([""]);
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+
+  test("a replace within one route updates the page in place", async () => {
+    await csr.open(item("21"));
+    await csr.type(currentInput, "kept");
+    await csr.navigate(item("22"), "replace");
+    expect(await itemIdsIn(CURRENT)).toEqual(["22"]);
+    expect(await csr.values(currentInput)).toEqual(["kept"]);
+    expect((await csr.containers()).filter((container) => container.path.endsWith("/item"))).toHaveLength(1);
+  }, 60_000);
+
+  test("the page the session opened on is cached like any other cached page", async () => {
+    await csr.open(TAB_A);
+    const mountedAs = (await csr.probe("tab-a"))?.mountId;
+    await csr.navigate(TAB_B);
+    await csr.navigate(item("3"));
+    await csr.navigate(TAB_A);
+    expect((await csr.probe("tab-a"))?.mountId).toBe(mountedAs);
+    expect(await csr.reloaded()).toBe(false);
+  }, 60_000);
+
+  test("a cached page that is not visible pauses its effects and resumes them with its state", async () => {
+    await csr.open(TAB_B);
+    await csr.navigate(TAB_A);
+    const mountedAs = (await csr.probe("tab-a"))?.mountId;
+    await csr.navigate(TAB_B);
+    await csr.navigate(item("4"));
+    expect((await csr.containers()).find((container) => container.path.endsWith("/tab-a"))?.hidden).toBe(true);
+    expect(await csr.ticksOver("tab-a")).toBe(0);
+    await csr.navigate(TAB_A);
+    expect((await csr.probe("tab-a"))?.mountId).toBe(mountedAs);
+    expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
+  }, 60_000);
+
+  test("the page a transition-less switch left pauses at once, and runs again when switched back", async () => {
+    await csr.open(TAB_A);
+    const mountedAs = (await csr.probe("tab-a"))?.mountId;
+    await csr.navigate(TAB_B);
+    expect(await csr.ticksOver("tab-a")).toBe(0);
+    await csr.navigate(TAB_A);
+    expect((await csr.probe("tab-a"))?.mountId).toBe(mountedAs);
+    expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
+  }, 60_000);
+
+  test("every page container but the current one is inert and hidden from assistive tech", async () => {
+    await csr.open(TAB_A);
+    await csr.navigate(TAB_B);
+    await csr.navigate(item("5"));
+    const current = routeOf(await csr.currentPath());
+    const containers = await csr.containers();
+    expect(containers.filter((container) => !container.inert).map((container) => container.path)).toEqual([current]);
+    expect(containers.every((container) => container.inert === container.ariaHidden)).toBe(true);
+  }, 60_000);
+
+  test("only the current page offers the agent its tools, not the page kept under it for a swipe back", async () => {
+    await csr.open(TAB_A);
+    expect(await csr.agentTools()).toContain("bumpTabA");
+    await csr.navigate(item("7"));
+    const tools = await csr.agentTools();
+    expect(tools).toContain("bumpItem");
+    expect(tools).not.toContain("bumpTabA");
+    expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
+    await csr.back();
+    const back = await csr.agentTools();
+    expect(back).toContain("bumpTabA");
+    expect(back).not.toContain("bumpItem");
+  }, 60_000);
+
+  test("a page is focused while current and settled; the page under it stays live but unfocused", async () => {
+    await csr.open(TAB_A);
+    expect((await csr.probe("tab-a"))?.focused).toBe(true);
+    const focusCount = (await csr.probe("tab-a"))?.focusCount ?? 0;
+    await csr.navigate(item("8"));
+    expect(await csr.probe("tab-a")).toMatchObject({ activity: "prev", focused: false, mounted: true });
+    expect(await csr.probe("item")).toMatchObject({ activity: "current", focused: true });
+    await csr.back();
+    expect(await csr.probe("tab-a")).toMatchObject({ activity: "current", focused: true, focusCount: focusCount + 1 });
+  }, 60_000);
+
+  test("a reload keeps the stack: the page under the current one is back, the rest waits, and back walks it", async () => {
+    const runtimeItem = (id: string) => `${item(id)}&csr=true&akanMobileTarget=e2e`;
+    await csr.open(TAB_A);
+    await csr.navigate(runtimeItem("31"));
+    await csr.navigate(runtimeItem("32"));
+    await csr.reload();
+    expect(await itemIdsIn(CURRENT)).toEqual(["32"]);
+    expect(await itemIdsIn(UNDER)).toEqual(["31"]);
+    expect((await csr.containers()).some((container) => container.path.endsWith("/tab-a"))).toBe(false);
+    //? The first back after a reload mounts the entry under the one it reveals, which a boot left dormant.
+    await csr.back();
+    await csr.waitForText(`${CURRENT} [data-e2e-probe="item"] [data-e2e="item-id"]`, ["31"]);
+    await csr.back();
+    expect(routeOf(await csr.currentPath())).toBe("/:lang/e2e/stack/tab-a");
+    expect((await csr.probe("tab-a"))?.mounted).toBe(true);
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+
+  test("a popstate several entries away lands on that entry", async () => {
+    await csr.open(TAB_A);
+    for (const id of ["41", "42", "43"]) await csr.navigate(item(id));
+    await csr.go(-2);
+    expect(await itemIdsIn(CURRENT)).toEqual(["41"]);
+    expect(await csr.reloaded()).toBe(false);
+  }, 60_000);
+
+  test("the page under the current one pauses while the app is in the background", async () => {
+    await csr.open(TAB_A);
+    await csr.navigate(item("51"));
+    expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
+    await csr.setVisibility("hidden");
+    expect(await csr.ticksOver("tab-a")).toBe(0);
+    await csr.setVisibility("visible");
+    expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
+  }, 60_000);
+
+  test("back returns to the previous entry without a reload", async () => {
+    await csr.open(TAB_A);
+    await csr.navigate(item("6"));
+    await csr.back();
+    expect(routeOf(await csr.currentPath())).toBe("/:lang/e2e/stack/tab-a");
+    expect(await csr.text('[data-e2e-probe="tab-a"] [data-e2e="item-id"]')).toHaveLength(1);
+    expect(await csr.reloaded()).toBe(false);
+  }, 60_000);
+});

package/frontendBuild/csrDevArtifactWriter.ts

@@ -0,0 +1,169 @@
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import {
+  CSR_DEV_APP_FILE,
+  CSR_DEV_MANIFEST_FILE,
+  CSR_DEV_ROUTE_PREFIX,
+  type CsrDevLayout,
+  type CsrDevManifest,
+  csrDevModuleFile,
+} from "akanjs/server/hmr/csrDevManifest";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+
+export class CsrDevArtifactWriter {
+  static readonly #keptPatches = 40;
+  static readonly #keptVendors = 3;
+  readonly #outDir: string;
+
+  constructor(outDir: string) {
+    this.#outDir = outDir;
+  }
+
+  async reset(): Promise<void> {
+    await rm(this.#outDir, { recursive: true, force: true });
+    await mkdir(path.join(this.#outDir, "modules"), { recursive: true });
+  }
+
+  async readJson<T>(name: string): Promise<T | null> {
+    const file = Bun.file(path.join(this.#outDir, name));
+    if (!(await file.exists())) return null;
+    return (await file.json().catch(() => null)) as T | null;
+  }
+
+  async writeJson(name: string, value: unknown): Promise<void> {
+    await this.#writeAtomic(name, JSON.stringify(value));
+  }
+
+  async writeModules(compiled: CsrDevCompiledModule[]): Promise<void> {
+    await mkdir(path.join(this.#outDir, "modules"), { recursive: true });
+    const helpers = new Map(
+      compiled.flatMap((module) => (module.helpers ? [[module.helpers.hash, module.helpers]] : [])),
+    );
+    await Promise.all([
+      ...compiled.flatMap((module) => [
+        Bun.write(this.#modulePath(module.id, ".js"), module.factory),
+        ...(module.sourceMap ? [Bun.write(this.#modulePath(module.id, ".js.map"), module.sourceMap)] : []),
+      ]),
+      ...[...helpers.values()].map((shared) => Bun.write(this.#helpersPath(shared.hash), shared.definition)),
+    ]);
+  }
+
+  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 }),
+      ]),
+    );
+  }
+
+  async writeVendor(graph: CsrDevGraph): Promise<string> {
+    const ids = Object.keys(graph.modules)
+      .filter((id) => graph.modules[id]?.vendor)
+      .sort();
+    const stubs = new Set(Object.values(graph.modules).flatMap((module) => module.deps.filter(CsrDevPaths.isStub)));
+    const lines = [await this.#helperDefinitions(graph, ids), ...(await this.#defineLines(ids))];
+    for (const stub of [...stubs].sort()) {
+      const message = `[akan-csr] ${stub.slice(CsrDevPaths.stubPrefix.length)} is a Node built-in the browser does not have`;
+      lines.push(
+        `__akan.define(${JSON.stringify(stub)}, function () {\n  throw new Error(${JSON.stringify(message)});\n});\n`,
+      );
+    }
+    const code = lines.join("");
+    const vendorFile = `vendor-${Bun.hash(code).toString(36)}.js`;
+    await this.#writeAtomic(vendorFile, code);
+    return vendorFile;
+  }
+
+  async writeApp(graph: CsrDevGraph, generation: number): Promise<void> {
+    const ids = Object.keys(graph.modules)
+      .filter((id) => !graph.modules[id]?.vendor)
+      .sort();
+    const lines = await this.#defineLines(ids);
+    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);
+  }
+
+  async writePatch(generation: number, modules: CsrDevCompiledModule[]): Promise<string> {
+    const patchFile = `patch-${generation}.js`;
+    const blocks = modules.map(
+      (module, index) =>
+        [module.id, `${JSON.stringify(module.id)}: ${module.factory}${index < modules.length - 1 ? ",\n" : "\n"}`] as [
+          string,
+          string,
+        ],
+    );
+    const helpers = new Map(
+      modules.flatMap((module) => (module.helpers ? [[module.helpers.hash, module.helpers]] : [])),
+    );
+    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}`;
+  }
+
+  // The manifest goes last: the server renders shells from it, so it must never name a file not yet written.
+  async writeState(graph: CsrDevGraph, manifest: CsrDevManifest): Promise<void> {
+    await this.writeJson("graph.json", graph);
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
+  }
+
+  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;
+    });
+    const vendors = names
+      .filter((name) => /^vendor-[\w-]+\.js$/.test(name) && name !== vendorFile)
+      .map((name) => ({ name, mtimeMs: CsrDevPaths.mtimeOf(path.join(this.#outDir, name)) }))
+      .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 })));
+  }
+
+  async #helperDefinitions(graph: CsrDevGraph, ids: string[]): 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("");
+  }
+
+  async #defineLines(ids: string[]): Promise<string[]> {
+    return await Promise.all(
+      ids.map(
+        async (id) => `__akan.define(${JSON.stringify(id)}, ${await Bun.file(this.#modulePath(id, ".js")).text()});\n`,
+      ),
+    );
+  }
+
+  //? A factory's code starts on the line after its header, so each module's map is placed one line below it.
+  async #writeWithSourceMap(name: string, header: string, blocks: [id: string, text: string][], footer: string) {
+    const layout: CsrDevLayout = { lineCount: 0, modules: [] };
+    let line = CsrDevPaths.lineCount(header);
+    for (const [id, text] of blocks) {
+      layout.modules.push([id, line + 1]);
+      line += CsrDevPaths.lineCount(text);
+    }
+    const code = `${header}${blocks.map(([, text]) => text).join("")}${footer}//# sourceMappingURL=${name}.map\n`;
+    layout.lineCount = CsrDevPaths.lineCount(code);
+    await this.writeJson(`${name}.layout.json`, layout);
+    await this.#writeAtomic(name, code);
+  }
+
+  // A rename is atomic: the dev server may be streaming the previous app.js to a reloading page right now.
+  async #writeAtomic(name: string, content: string): Promise<void> {
+    const target = path.join(this.#outDir, name);
+    const temp = `${target}.${process.pid}.tmp`;
+    await Bun.write(temp, content);
+    await rename(temp, target);
+  }
+
+  #modulePath(id: string, extension: ".js" | ".js.map"): string {
+    return path.join(this.#outDir, csrDevModuleFile(id, extension));
+  }
+
+  #helpersPath(hash: string): string {
+    return path.join(this.#outDir, "modules", `helpers-${hash}.js`);
+  }
+}

package/frontendBuild/csrDevBundler.test.ts

@@ -0,0 +1,66 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+//* Pins the Bun behaviour CsrDevBundler is built on, so a Bun upgrade that changes it fails here, not in a browser.
+describe("Bun output the CSR registry bundle relies on", () => {
+  let dir: string;
+  const externalizeAll = {
+    name: "externalize-all",
+    setup(build: Bun.PluginBuilder) {
+      build.onResolve({ filter: /.*/ }, (args) =>
+        args.kind === "entry-point-build" ? undefined : { path: `akan-module:${args.path}`, external: true },
+      );
+    },
+  };
+
+  beforeAll(async () => {
+    dir = await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-bundler-"));
+    await Bun.write(path.join(dir, "a.ts"), "export const a = 1;\n");
+    await Bun.write(
+      path.join(dir, "entry.ts"),
+      'import value from "./a";\nexport * from "./a";\nexport const lazy = () => import("./a");\nconsole.log(value);\n',
+    );
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  const build = async (entrypoints: string[]) =>
+    await Bun.build({
+      entrypoints: entrypoints.map((file) => path.join(dir, file)),
+      root: dir,
+      target: "browser",
+      format: "cjs",
+      naming: { entry: "[dir]/[name].[ext]" },
+      plugins: [externalizeAll],
+    });
+
+  test("the CJS helpers keep the shapes CsrDevBundler rewrites", async () => {
+    const [output] = (await build(["entry.ts"])).outputs;
+    const code = (await output?.text()) ?? "";
+    expect(code).toContain("var __toESM = (mod, isNodeMode, target) => {");
+    expect(code).toContain("var __reExport = (target, mod, secondTarget) => {");
+    expect(code).toContain('require("akan-module:./a")');
+    expect(code).toContain('import("akan-module:./a")');
+  });
+
+  test("the helper preamble ends at the first path comment and names no factory argument", async () => {
+    const [output] = (await build(["entry.ts"])).outputs;
+    const code = (await output?.text()) ?? "";
+    const marker = code.search(/^\/\/ /m);
+    expect(marker).toBeGreaterThan(0);
+    const preamble = code.slice(0, marker);
+    expect(preamble).toMatch(/^var __toESM = /m);
+    expect(preamble).not.toMatch(/(?<![\w$.])(?:require|module|exports)(?![\w$]|\s*:)/);
+  });
+
+  test("a relative import of another entrypoint in the same build stays external", async () => {
+    const outputs = (await build(["entry.ts", "a.ts"])).outputs;
+    const entry = await outputs.find((output) => output.path.includes("entry"))?.text();
+    expect(entry).toContain('require("akan-module:./a")');
+    expect(entry).not.toContain("var a = 1");
+  });
+});

package/frontendBuild/csrDevBundler.ts

@@ -0,0 +1,256 @@
+import fs from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { CSR_DEV_DIRNAME, CSR_DEV_MANIFEST_FILE, type CsrDevManifest } from "akanjs/server/hmr/csrDevManifest";
+import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import type { App } from "../commandDecorators";
+import { bundleDefine } from "./bundleDefine";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
+import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+
+export interface CsrDevUpdate {
+  generation: number;
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds: string[];
+  moduleCount: number;
+}
+
+//* Dev-only CSR as a module registry. The build worker is a fresh process per save, so the graph, every module's
+//* factory and the resolutions live on disk under `.akan/artifact/csr-dev`.
+export class CsrDevBundler {
+  static readonly #formatVersion = 3;
+  readonly #app: App;
+  readonly #paths: CsrDevPaths;
+  readonly #outDir: string;
+  readonly #entryDir: string;
+  readonly #writer: CsrDevArtifactWriter;
+
+  constructor(app: App) {
+    this.#app = app;
+    this.#paths = new CsrDevPaths(app.workspace.workspaceRoot);
+    this.#outDir = path.join(app.cwdPath, ".akan/artifact", CSR_DEV_DIRNAME);
+    this.#entryDir = path.join(app.cwdPath, ".akan/generated", CSR_DEV_DIRNAME);
+    this.#writer = new CsrDevArtifactWriter(this.#outDir);
+  }
+
+  async update(changedFiles: string[] = []): Promise<CsrDevUpdate | null> {
+    const context = await this.#context();
+    if (context.pageEntries.length === 0) return null;
+    const manifest = await this.#writer.readJson<CsrDevManifest>(CSR_DEV_MANIFEST_FILE);
+    const graph = await this.#writer.readJson<CsrDevGraph>("graph.json");
+    const generation = (manifest?.generation ?? 0) + 1;
+    if (!manifest || !graph || graph.version !== 1 || graph.configKey !== context.configKey)
+      return await this.#fullBuild(context, generation, manifest ? "the dev bundle config changed" : "first build");
+    const metadataFile = changedFiles.find(isAkanRuntimeMetadataFile);
+    // `lib/useClient.ts` inlines signal and dictionary metadata through a macro at build time.
+    if (metadataFile) return await this.#fullBuild(context, generation, `${path.basename(metadataFile)} changed`);
+    return await this.#incrementalBuild(context, graph, manifest, changedFiles, generation);
+  }
+
+  async #context(): Promise<CsrDevContext> {
+    const akanConfig = await this.#app.getConfig();
+    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys());
+    const basePaths = [...akanConfig.basePaths];
+    const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
+    const define = bundleDefine(this.#app, "start", "csr");
+    const optimizeImports = [...akanConfig.optimizeImports];
+    const configKey = Bun.hash(
+      JSON.stringify([CsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, htmlBasePaths]),
+    ).toString(36);
+    return {
+      pageEntries,
+      basePaths,
+      htmlBasePaths,
+      define,
+      optimizeImports,
+      configKey,
+      refreshFile: this.#resolveRefreshRuntime(),
+    };
+  }
+
+  #resolveRefreshRuntime(): string {
+    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.#app.cwdPath);
+    const bases = [
+      this.#app.cwdPath,
+      this.#paths.root,
+      ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : []),
+    ];
+    for (const base of bases) {
+      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
+      if (resolved) return CsrDevPaths.realpath(resolved);
+    }
+    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
+  }
+
+  async #fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
+    await this.#writer.reset();
+    const entries = await this.#writeEntries(context);
+    const entryFiles = Object.values(entries.files);
+    const resolver = new CsrDevResolver({ paths: this.#paths, context, entryFiles });
+    await resolver.prepass();
+    const compiled = await this.#compiler(context, resolver).compile([...entryFiles, context.refreshFile], new Set());
+    const graph: CsrDevGraph = {
+      version: 1,
+      configKey: context.configKey,
+      refresh: this.#paths.idOf(context.refreshFile),
+      entries: this.#entryIds(entries.files),
+      modules: {},
+      resolution: {},
+      pending: [],
+    };
+    this.#merge(graph, resolver, compiled);
+    await this.#writer.writeModules(compiled);
+    const vendorFile = await this.#writer.writeVendor(graph);
+    await this.#writer.writeApp(graph, generation);
+    await this.#writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries });
+    await this.#writer.prune(vendorFile, generation);
+    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length };
+  }
+
+  async #incrementalBuild(
+    context: CsrDevContext,
+    graph: CsrDevGraph,
+    manifest: CsrDevManifest,
+    changedFiles: string[],
+    generation: number,
+  ): Promise<CsrDevUpdate | null> {
+    const entries = await this.#writeEntries(context);
+    const entryIds = this.#entryIds(entries.files);
+    await this.#forgetDeletedModules(graph);
+    const changed = await this.#changedModules(graph, changedFiles);
+    for (const file of entries.changed) changed.add(this.#paths.idOf(file));
+    const routesMoved = entries.changed.length > 0 || JSON.stringify(entryIds) !== JSON.stringify(graph.entries);
+    if (changed.size === 0) return null;
+
+    const resolver = new CsrDevResolver({
+      paths: this.#paths,
+      context,
+      entryFiles: Object.values(entries.files),
+      resolution: graph.resolution,
+    });
+    const known = new Set(Object.keys(graph.modules).map((id) => this.#paths.fileOf(id)));
+    let compiled: CsrDevCompiledModule[];
+    try {
+      compiled = await this.#compiler(context, resolver).compile(
+        [...changed].map((id) => this.#paths.fileOf(id)),
+        known,
+      );
+    } catch (error) {
+      graph.pending = [...changed];
+      await this.#writer.writeJson("graph.json", graph);
+      throw error;
+    }
+    const vendorJoined = compiled.some((module) => module.vendor && !graph.modules[module.id]);
+    this.#merge(graph, resolver, compiled);
+    graph.entries = entryIds;
+    await this.#writer.writeModules(compiled);
+    const vendorFile = vendorJoined ? await this.#writer.writeVendor(graph) : manifest.vendorFile;
+    await this.#writer.writeApp(graph, generation);
+    const changedIds = compiled.filter((module) => !module.vendor).map((module) => module.id);
+    const constantId = changedIds.find((id) => id.endsWith(".constant.ts"));
+    // A model class swapped under live store state would mix old and new instances; reload instead.
+    const reason = vendorJoined
+      ? "an npm module joined the graph"
+      : routesMoved
+        ? "the route table changed"
+        : constantId
+          ? `${path.basename(constantId)} changed`
+          : undefined;
+    const patchUrl = reason
+      ? undefined
+      : await this.#writer.writePatch(
+          generation,
+          compiled.filter((module) => !module.vendor),
+        );
+    await this.#writer.writeState(graph, { ...manifest, generation, vendorFile, entries: entryIds });
+    await this.#writer.prune(vendorFile, generation);
+    return {
+      generation,
+      reload: !!reason,
+      reason,
+      patchUrl,
+      changedIds,
+      moduleCount: Object.keys(graph.modules).length,
+    };
+  }
+
+  async #changedModules(graph: CsrDevGraph, changedFiles: string[]): Promise<Set<string>> {
+    const changed = new Set<string>(graph.pending.filter((id) => graph.modules[id]));
+    for (const file of changedFiles) {
+      const id = this.#paths.idOf(file);
+      if (graph.modules[id]) changed.add(id);
+    }
+    // Stat, not trust: a save made while CSR was unarmed, or a build that failed, never reached this graph. The hash
+    // settles it because route discovery rewrites the generated layout wrappers, touching them on every call.
+    for (const [id, module] of Object.entries(graph.modules)) {
+      if (module.vendor || changed.has(id)) continue;
+      const file = this.#paths.fileOf(id);
+      if (CsrDevPaths.mtimeOf(file) === module.mtimeMs) continue;
+      if ((await CsrDevPaths.hashOf(file)) !== module.hash) changed.add(id);
+    }
+    return changed;
+  }
+
+  // A deleted module leaves the graph instead of being rebuilt: rebuilding a missing file fails every save after it.
+  // An importer that still names it fails on its own rebuild, with the resolution error that says why.
+  async #forgetDeletedModules(graph: CsrDevGraph): Promise<void> {
+    const deleted = Object.keys(graph.modules).filter(
+      (id) => !graph.modules[id]?.vendor && !fs.existsSync(this.#paths.fileOf(id)),
+    );
+    for (const id of deleted) delete graph.modules[id];
+    await this.#writer.forgetModules(deleted);
+  }
+
+  async #writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.#entryDir, { recursive: true });
+    const files: Record<string, string> = {};
+    const changed: string[] = [];
+    for (const basePath of context.htmlBasePaths) {
+      const file = path.join(this.#entryDir, CsrArtifactBuilder.entryFilename(basePath));
+      const entryPages = CsrArtifactBuilder.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
+      const generator = new PagesEntrySourceGenerator(entryPages);
+      const pages = await generator.generateStatic({ fromDir: this.#entryDir });
+      const hot = await generator.generateHotReplace({
+        fromDir: this.#entryDir,
+        ownerId: this.#paths.idOf(file),
+        moduleIds: entryPages.map(({ moduleAbsPath }) => this.#paths.idOf(moduleAbsPath)),
+      });
+      const source = `import * as akanWebkit from "akanjs/webkit";\n${pages}\nvoid akanWebkit.bootCsr(pages);\n${hot}`;
+      const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
+      if (!unchanged) await Bun.write(file, source);
+      const entryFile = CsrDevPaths.realpath(file);
+      files[basePath] = entryFile;
+      if (!unchanged) changed.push(entryFile);
+    }
+    return { files, changed };
+  }
+
+  #compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
+    return new CsrDevModuleCompiler({ app: this.#app, paths: this.#paths, resolver, context, outDir: this.#outDir });
+  }
+
+  #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();
+  }
+
+  #entryIds(files: Record<string, string>): Record<string, string> {
+    return Object.fromEntries(Object.entries(files).map(([basePath, file]) => [basePath, this.#paths.idOf(file)]));
+  }
+}