@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/frontendBuild/cssCompiler.ts

@@ -1,13 +1,14 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import { compile } from "tailwindcss";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
+import { CsrEntryFiles } from "./csrEntryFiles";
 import { CssCandidateCache } from "./cssCandidateCache";
 import { CssImportResolver } from "./cssImportResolver";
 
-const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] as const;
 const NON_SOURCE_EXT_RE = /\.(json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav)$/i;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
@@ -17,7 +18,6 @@ interface CssDiscovery {
   sourcePaths: string[];
 }
 
-/** One `@import` target and the custom properties it declares, which is what proves it arrived downstream. */
 export interface ImportedStylesheet {
   cssPath: string;
   declaredNames: string[];
@@ -32,32 +32,18 @@ export class CssCompiler {
     this.#app = app;
   }
 
-  /**
-   * Beside the sources rather than in `dist`, because the cache is keyed on source mtimes: a build and
-   * the dev server describe the same files, so they should share it rather than each pay the first scan.
-   */
+  // Beside the sources, not in `dist`: the build and the dev server scan the same files, so they share one cache.
   get #candidateCachePath() {
     return path.join(this.#app.cwdPath, ".akan/cache/cssCandidates.json");
   }
 
   #cssText: string | null = null;
   #cssTextByBasePath: Record<string, string> | null = null;
-  /**
-   * Import resolution memoised for the life of one compiler, which is one rebuild.
-   *
-   * The discovery BFS resolves the same specifier from every directory that imports it, and each miss
-   * costs up to 13 sequential `exists()` calls — the bare path, six extensions, six `index.*`. Nothing
-   * here outlives the rebuild, so there is no invalidation to get wrong.
-   */
+  // Memoised for one compiler, i.e. one rebuild: nothing outlives it, so there is nothing to invalidate.
   #fileExistsCache = new Map<string, Promise<boolean>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
-  /** Every stylesheet this compile reached, entry points and `@import` targets alike. */
   #discoveredCssPaths = new Set<string>();
-  /**
-   * `@import` targets per base path, so whoever writes the asset can check the file it actually wrote — the
-   * compiled text and the written artifact are two different places a declaration can go missing.
-   */
   importedStylesheetsByBasePath: Record<string, ImportedStylesheet[]> = {};
 
   #fileExists(absPath: string): Promise<boolean> {
@@ -107,41 +93,31 @@ export class CssCompiler {
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
     const rootPageKeys = pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === null);
+    const compileBasePath = async (basePath: string, basePathPageKeys: string[], label = basePath) => {
+      if (basePathPageKeys.length === 0) return [basePath, ""] as const;
+      const started = Date.now();
+      const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
+      const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+      this.importedStylesheetsByBasePath[basePath] = imported;
+      this.#logger.verbose(
+        `css base=${label} paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
+      );
+      return [basePath, css] as const;
+    };
     const cssEntries = await Promise.all([
-      (async () => {
-        if (rootPageKeys.length === 0) return ["", ""] as const;
-        const started = Date.now();
-        const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: rootPageKeys });
-        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
-        this.importedStylesheetsByBasePath[""] = imported;
-        this.#logger.verbose(
-          `css base=root paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
-        );
-        return ["", css] as const;
-      })(),
-      ...basePaths.map(async (basePath) => {
-        const basePathPageKeys = pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === basePath);
-        if (basePathPageKeys.length === 0) return [basePath, ""] as const;
-        const started = Date.now();
-        const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
-        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
-        this.importedStylesheetsByBasePath[basePath] = imported;
-        this.#logger.verbose(
-          `css base=${basePath} paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
-        );
-        return [basePath, css] as const;
-      }),
+      compileBasePath("", rootPageKeys, "root"),
+      ...basePaths.map((basePath) =>
+        compileBasePath(
+          basePath,
+          pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === basePath),
+        ),
+      ),
     ]);
     this.#cssTextByBasePath = Object.fromEntries(cssEntries);
     await this.#warnUnreachableStylesheets();
     return this.#cssTextByBasePath;
   }
 
-  /**
-   * A stylesheet under `page/` reaches the build only by being imported from a route source. One that nothing
-   * imports compiles to nothing and reports success, which is indistinguishable from an empty theme — so say it
-   * out loud once per compile rather than leaving it to be noticed as unstyled elements in the browser.
-   */
   async #warnUnreachableStylesheets() {
     const pageDir = path.join(this.#app.cwdPath, "page");
     const glob = new Bun.Glob("**/*.css");
@@ -225,11 +201,7 @@ export class CssCompiler {
     return { cssPaths, sourcePaths: [...sourceFiles] };
   }
 
-  /**
-   * `libs/<lib>/ui/tokens.css` of every lib the page graph reached, so a lib can own the fixed colours its own
-   * components need instead of each consuming app re-declaring them. Ordered ahead of the app's stylesheets:
-   * the app is the last word on any variable both declare.
-   */
+  // Lib tokens go ahead of the app's stylesheets, so the app has the last word on a variable both declare.
   async #libTokenStylesheets(sourceFiles: Set<string>): Promise<string[]> {
     const libsRoot = path.join(this.#app.workspace.workspaceRoot, "libs");
     const libNames = new Set<string>();
@@ -252,10 +224,7 @@ export class CssCompiler {
     return css;
   }
 
-  /**
-   * The collector is per compile rather than per compiler instance: `getCssByBasePath` compiles every base path
-   * concurrently, so instance state would mix one base path's imports into another's check.
-   */
+  // A per-compile collector: getCssByBasePath compiles base paths concurrently, so instance state would mix them.
   async #compileWithImports(
     cssPaths: string[],
     sourcePaths: string[],
@@ -279,7 +248,6 @@ export class CssCompiler {
 
     const sourceDirs = new Set<string>();
     for (const entry of compilers) {
-      if (!entry) continue;
       for (const s of entry.compiler.sources as { base: string }[]) sourceDirs.add(s.base);
     }
     const scanStarted = Date.now();
@@ -290,7 +258,6 @@ export class CssCompiler {
     const parts: string[] = [];
     const imported: ImportedStylesheet[] = [];
     for (const entry of compilers) {
-      if (!entry) continue;
       const part = entry.compiler.build(candidates);
       parts.push(part);
       for (const [cssPath, content] of entry.imported) {
@@ -317,28 +284,19 @@ export class CssCompiler {
     return { path: p, base: path.dirname(p), content };
   }
 
-  /**
-   * Every specifier is verified here, path-shaped ones included. An `@import` the pipeline cannot resolve is
-   * a build error and never a no-op: the vocabulary closure means a component whose token declaration failed
-   * to load renders unstyled, which nothing downstream can distinguish from a design choice.
-   */
+  // An unresolvable @import throws: under vocabulary closure a missing token file just renders unstyled.
   async #resolveCssImport(id: string, fromBase: string): Promise<string> {
     if (id.startsWith(".") || id.startsWith("/")) {
       const filePath = path.resolve(fromBase, id);
       if (await this.#fileExists(filePath)) return filePath;
       throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase} (no file at ${filePath})`);
     }
-    const resolver = await this.#getCssImportResolver();
-    const resolved = await resolver.resolve(id, fromBase);
+    this.#cssImportResolver ??= await CssImportResolver.create(this.#app);
+    const resolved = await this.#cssImportResolver.resolve(id, fromBase);
     if (resolved) return resolved;
     throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase}`);
   }
 
-  async #getCssImportResolver() {
-    if (this.#cssImportResolver) return this.#cssImportResolver;
-    this.#cssImportResolver = await CssImportResolver.create(this.#app);
-    return this.#cssImportResolver;
-  }
   async #loadModule(id: string, fromBase: string) {
     const p = require.resolve(id, { paths: [fromBase] });
     const mod = await import(p);
@@ -349,10 +307,7 @@ export class CssCompiler {
     fromBase: string,
     resolvePackage: Awaited<ReturnType<typeof createTsconfigPackageResolver>>,
   ): Promise<string | null> {
-    // Keyed by importer directory even for bare specifiers: the tsconfig resolver is
-    // directory-independent, but the `Bun.resolveSync` / `require.resolve` fallbacks below are not.
-    // The expensive part — the `exists()` probes — is deduplicated by absolute path instead, which is
-    // shared across every importer.
+    // Keyed by importer directory even for bare specifiers: the Bun/require fallbacks are directory-dependent.
     const cacheKey = `${fromBase}\0${id}`;
     let cached = this.#resolvedSpecifierCache.get(cacheKey);
     if (cached) return cached;
@@ -423,17 +378,14 @@ function resolveSourceWithRequire(id: string, fromBase: string): string | null {
 }
 
 function isSourceFile(filePath: string) {
-  return SOURCE_EXTS.includes(path.extname(filePath) as (typeof SOURCE_EXTS)[number]);
+  return SOURCE_EXTS.has(path.extname(filePath));
 }
 
 export function isIgnoredNodeModuleSource(filePath: string): boolean {
   return NODE_MODULES_RE.test(filePath) && !AKANJS_NODE_MODULE_RE.test(filePath);
 }
 
-/**
- * `@theme` blocks are stripped first: those variables are emitted only when a utility uses one, so their
- * absence from a build says nothing about whether the stylesheet arrived.
- */
+/** Skips `@theme` blocks: Tailwind emits those variables only when a utility uses one. */
 export function declaredCustomProperties(css: string): string[] {
   const withoutThemeBlocks = css.replace(/@theme[^{]*\{[^}]*\}/g, "");
   return [...new Set([...withoutThemeBlocks.matchAll(/(?:^|[\s;{])(--[\w-]+)\s*:/g)].map(([, name]) => name))].filter(
@@ -442,8 +394,5 @@ export function declaredCustomProperties(css: string): string[] {
 }
 
 export function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
-  const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
-  const segments = normalized.split("/");
-  const firstPublicSegment = segments.find((segment) => segment !== "[lang]" && !/^\(.+\)$/.test(segment));
-  return firstPublicSegment && basePaths.includes(firstPublicSegment) ? firstPublicSegment : null;
+  return CsrEntryFiles.basePathOfPageKey(pageKey, basePaths);
 }

package/frontendBuild/cssImportResolver.ts

@@ -25,8 +25,8 @@ export class CssImportResolver {
   async resolve(id: string, fromBase: string): Promise<string | null> {
     for (const resolve of [
       () => this.#resolveWithTsconfig(id),
-      () => this.#resolveWithBun(id, fromBase),
-      () => this.#resolveWithRequire(id, fromBase),
+      () => this.#resolveCssWith(fromBase, (base) => Bun.resolveSync(id, base)),
+      () => this.#resolveCssWith(fromBase, (base) => require.resolve(id, { paths: [base] })),
       () => this.#resolvePackageStyle(id, fromBase),
     ]) {
       const resolved = await resolve();
@@ -35,22 +35,10 @@ export class CssImportResolver {
     return null;
   }
 
-  #resolveWithBun(id: string, fromBase: string): string | null {
+  #resolveCssWith(fromBase: string, resolveFrom: (base: string) => string): string | null {
     for (const base of this.#resolutionBases(fromBase)) {
       try {
-        const resolved = Bun.resolveSync(id, base);
-        if (CssImportResolver.isCssFile(resolved)) return resolved;
-      } catch {
-        // Try the next known package resolution root.
-      }
-    }
-    return null;
-  }
-
-  #resolveWithRequire(id: string, fromBase: string): string | null {
-    for (const base of this.#resolutionBases(fromBase)) {
-      try {
-        const resolved = require.resolve(id, { paths: [base] });
+        const resolved = resolveFrom(base);
         if (CssImportResolver.isCssFile(resolved)) return resolved;
       } catch {
         // Try the next known package resolution root.
@@ -111,8 +99,7 @@ export class CssImportResolver {
           ? exportValue
           : exportValue?.style || exportValue?.import || exportValue?.default;
       if (exportedEntry) return await this.#firstExisting(path.resolve(pkgDir, exportedEntry));
-      //* A subpath names a file inside the package, so it resolves literally. Falling back to the package's own
-      //* style entry here would load a different stylesheet than the author asked for and report success.
+      //* A subpath resolves literally: the package's own style entry would silently load a different stylesheet.
       if (subpath !== ".") return await this.#firstExisting(path.resolve(pkgDir, subpath));
       return await this.#firstExisting(path.resolve(pkgDir, pkg.exports?.["."]?.style || pkg.style || "index.css"));
     } catch {
@@ -135,7 +122,7 @@ export class CssImportResolver {
 
   async #firstExisting(basePath: string): Promise<string | null> {
     for (const suffix of CSS_IMPORT_EXTS) {
-      const candidate = `${basePath}${suffix}`;
+      const candidate = path.normalize(`${basePath}${suffix}`);
       if (await Bun.file(candidate).exists()) return candidate;
     }
     return null;

package/frontendBuild/devChangePlanner.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import type { ChangeKind, DevChangeAction, DevChangePlan, DevChangeRole } from "akanjs/server";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 
-const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const CONFIG_BASENAMES = new Set(["akan.config.ts", "bunfig.toml", "tsconfig.json", "package.json"]);
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const CLIENT_SUFFIXES = [".Template.tsx", ".Unit.tsx", ".Util.tsx", ".View.tsx", ".Zone.tsx", ".store.ts"];
@@ -93,15 +93,15 @@ export class DevChangePlanner {
       roles.add("barrel");
       reasons.add(isGenerated ? "generated-index" : "barrel-facet-child");
     }
-    if (isSource && this.#isServerBiased(abs, parts)) {
+    if (isSource && this.#isServerBiased(base, parts)) {
       roles.add("server");
       reasons.add("server-path");
     }
-    if (isSource && this.#isClientBiased(abs, parts)) {
+    if (isSource && this.#isClientBiased(base, parts)) {
       roles.add("client");
       reasons.add("client-path");
     }
-    if (isSource && this.#isSharedBiased(abs, parts)) {
+    if (isSource && this.#isSharedBiased(base, parts)) {
       roles.add("shared");
       reasons.add("shared-path");
     }
@@ -123,8 +123,7 @@ export class DevChangePlanner {
     return roles;
   }
 
-  #isServerBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isServerBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("srvkit") ||
       SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
@@ -133,8 +132,7 @@ export class DevChangePlanner {
     );
   }
 
-  #isClientBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isClientBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("ui") ||
       parts.includes("webkit") ||
@@ -143,8 +141,7 @@ export class DevChangePlanner {
     );
   }
 
-  #isSharedBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isSharedBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("common") ||
       SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||

package/frontendBuild/devGeneratedIndexSync.test.ts

@@ -1,16 +1,10 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-generated-index-"));
-  tempRoots.push(root);
-  return root;
-};
+const makeTempRoot = tempDirs("akan-generated-index-");
 
 const seedFacet = async (root: string, facet: string, { files, dirs }: { files: string[]; dirs: string[] }) => {
   const dir = path.join(root, "libs", "util", facet);
@@ -28,23 +22,19 @@ const barrelFor = async (root: string, facet: string, seed: { files: string[]; d
   return readFile(path.join(dir, "index.ts"), "utf8");
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("DevGeneratedIndexSync facet barrels", () => {
   test("camelCase facets export only clean camelCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "srvkit", {
       files: [
         "aes.ts",
         "cloudflareApi.ts",
-        "cloudflareApi.helper.ts", // dotted → skipped
-        "pushNotificationServer.type.ts", // dotted → skipped
-        "PushNotificationServer.ts", // PascalCase in camel facet → skipped
-        "my_snake.ts", // snake_case → skipped
-        "kebab-case.ts", // kebab-case → skipped
+        "cloudflareApi.helper.ts",
+        "pushNotificationServer.type.ts",
+        "PushNotificationServer.ts",
+        "my_snake.ts",
+        "kebab-case.ts",
       ],
-      dirs: ["storageApi", "BadDir"], // PascalCase dir → skipped
+      dirs: ["storageApi", "BadDir"],
       trigger: "aes.ts",
     });
     expect(content).toBe(`export * from "./aes";\nexport * from "./cloudflareApi";\nexport * from "./storageApi";\n`);
@@ -52,13 +42,8 @@ describe("DevGeneratedIndexSync facet barrels", () => {
 
   test("ui facet exports only clean PascalCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "ui", {
-      files: [
-        "Globe.tsx",
-        "AkanLogo.tsx",
-        "Globe_Dynamic.tsx", // underscore → skipped
-        "lowerStart.tsx", // camelCase in ui facet → skipped
-      ],
-      dirs: ["Code", "badDir"], // camelCase dir → skipped
+      files: ["Globe.tsx", "AkanLogo.tsx", "Globe_Dynamic.tsx", "lowerStart.tsx"],
+      dirs: ["Code", "badDir"],
       trigger: "Globe.tsx",
     });
     expect(content).toBe(`export * from "./AkanLogo";\nexport * from "./Code";\nexport * from "./Globe";\n`);

package/frontendBuild/devGeneratedIndexSync.ts

@@ -1,12 +1,11 @@
 import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { capitalize } from "akanjs/common";
 import { FileSys } from "../fileSys";
 
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
 const FACET_EXCLUDED_FILE_RE = /(^index\.tsx?$|\.d\.ts$|\.(test|spec)\.(ts|tsx)$|\.css$|\.scss$|\.sass$)/;
-// `ui` exports PascalCase names only; `common`/`srvkit`/`webkit` export camelCase names only. Names with
-// dots, underscores, or hyphens (e.g. `foo.helper`, `Globe_Dynamic`, `kebab-case`) match neither and are skipped.
 const FACET_PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
 const FACET_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 const MODULE_UI_TYPES = ["Template", "Unit", "Util", "View", "Zone"] as const;
@@ -159,6 +158,4 @@ const exists = async (file: string) =>
     .then(() => true)
     .catch(() => false);
 
-const capitalize = (value: string) => `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
-
 const formatError = (err: unknown) => (err instanceof Error ? err.message : String(err));

package/frontendBuild/devRegistryBundler.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import type { App } from "../commandDecorators";
+import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
+import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
+import { CsrDevPatcher } from "./csrDevPatcher";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
+import { WatchRootResolver } from "./watchRootResolver";
+
+export interface CsrDevUpdate {
+  generation: number;
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds: string[];
+  moduleCount: number;
+  epoch?: number;
+  /** The registry did not exist before this build, so no tab holds a module of it. */
+  first?: boolean;
+}
+
+export interface CsrDevUpdateOptions {
+  /** Called once an update exists: for a patch before app.js is rewritten, for a reload after everything is on disk. */
+  announce?: (update: CsrDevUpdate) => void;
+  /** Files the registry must hold once this update is done; the ones it lacks are compiled into it. */
+  roots?: string[];
+  /**
+   * Compile only the roots the registry lacks: a route build asks for its entries, and a file saved meanwhile is the
+   * save's own patch to make, with the hold only that patch knows.
+   */
+  onlyRoots?: boolean;
+}
+
+export interface DevRegistryTarget {
+  dirName: string;
+  routePrefix: string;
+  library: boolean;
+}
+
+//* A dev module registry under `.akan/artifact/<dirName>`: this owns the context, the entries and the full build;
+//* `CsrDevPatcher` owns the incremental path, which the resident builder keeps in memory between saves.
+export abstract class DevRegistryBundler {
+  readonly outDir: string;
+  readonly routePrefix: string;
+  readonly paths: CsrDevPaths;
+  readonly writer: CsrDevArtifactWriter;
+  protected readonly app: App;
+  protected readonly entryDir: string;
+  /** A CSR entry holds the route table, so moving one reloads the tab; an SSR root is one more module to hold. */
+  abstract readonly reloadsOnEntryChange: boolean;
+
+  constructor(app: App, { dirName, routePrefix, library }: DevRegistryTarget) {
+    this.app = app;
+    this.routePrefix = routePrefix;
+    this.paths = new CsrDevPaths(app.workspace.workspaceRoot);
+    this.outDir = path.join(app.cwdPath, ".akan/artifact", dirName);
+    this.entryDir = path.join(app.cwdPath, ".akan/generated", dirName);
+    this.writer = new CsrDevArtifactWriter(this.outDir, { routePrefix, library });
+  }
+
+  /** Null when there is nothing to build. */
+  abstract context(): Promise<CsrDevContext | null>;
+
+  abstract writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }>;
+
+  /** Every file a full build compiles from, the entries included. */
+  protected abstract rootFiles(entryFiles: string[]): Promise<string[]>;
+
+  // A build worker: a throwaway patcher that starts from the disk, and builds everything itself when it cannot patch.
+  async update(changedFiles: string[] = [], options: CsrDevUpdateOptions = {}): Promise<CsrDevUpdate | null> {
+    const result = await new CsrDevPatcher(this).update(changedFiles, { ...options, allowWholeAppBuilds: true });
+    if (result.kind === "unchanged") return null;
+    if (result.kind === "update") return result.update;
+    const built = await this.fullBuild(result.context, result.generation, result.reason);
+    const update = result.first ? { ...built, first: true } : built;
+    options.announce?.(update);
+    return update;
+  }
+
+  /** Of these files, the ones the registry still reaches from its roots through imports: those it keeps building. */
+  async wantedRoots(files: string[], graph: CsrDevGraph): Promise<Set<string>> {
+    const reached = await this.reachable(graph);
+    return new Set(files.filter((file) => reached.has(this.paths.idOf(file))));
+  }
+
+  /** The ids its roots reach through imports, the refresh runtime included. */
+  async reachable(graph: CsrDevGraph): Promise<Set<string>> {
+    const roots = await this.rootFiles(Object.values(graph.entries).map((id) => this.paths.fileOf(id)));
+    const reached = new Set<string>();
+    const stack = [graph.refresh, ...roots.map((file) => this.paths.idOf(file))];
+    for (let id = stack.pop(); id !== undefined; id = stack.pop()) {
+      if (reached.has(id)) continue;
+      reached.add(id);
+      stack.push(...(graph.modules[id]?.deps ?? []));
+    }
+    return reached;
+  }
+
+  async holds(files: string[]): Promise<boolean> {
+    const graph = await this.writer.readJson<CsrDevGraph>("graph.json");
+    return graph !== null && files.every((file) => graph.modules[this.paths.idOf(file)] !== undefined);
+  }
+
+  /** A save of one goes to a whole build: `lib/useClient.ts` inlines what they declare through macros. */
+  isMetadataFile(file: string): boolean {
+    return isAkanRuntimeMetadataFile(file);
+  }
+
+  async metadataFingerprint(): Promise<string> {
+    const libsContainer = path.resolve(this.app.workspace.workspaceRoot, "libs");
+    const roots = await new WatchRootResolver(this.app).resolve();
+    // The whole container comes back when the lib dependencies are unknown (before the first sync).
+    const libRoots = roots.includes(libsContainer)
+      ? fs.readdirSync(libsContainer).map((name) => path.join(libsContainer, name))
+      : roots.filter((root) => path.dirname(root) === libsContainer);
+    return await RegistryMetadataFingerprint.of([path.resolve(this.app.cwdPath), ...libRoots], (file) =>
+      this.isMetadataFile(file),
+    );
+  }
+
+  //? Compiled before anything is written: a build that fails (a module the user broke) leaves the registry the tabs
+  //? and the next patch read as it was, where clearing the directory first left no registry at all.
+  async fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
+    const metadata = await this.metadataFingerprint();
+    const entries = await this.writeEntries(context);
+    const roots = await this.rootFiles(Object.values(entries.files));
+    const resolver = new CsrDevResolver({ paths: this.paths, context, entryFiles: roots });
+    await resolver.prepass();
+    const compiler = this.compiler(context, resolver);
+    const { modules: compiled } = await compiler.compile(
+      [...roots, ...(context.refreshFile ? [context.refreshFile] : [])],
+      new Set(),
+    );
+    const graph: CsrDevGraph = {
+      version: 1,
+      configKey: context.configKey,
+      refresh: context.refreshFile
+        ? this.paths.idOf(context.refreshFile)
+        : `${CsrDevPaths.vendorPrefix}react-refresh/runtime`,
+      entries: this.entryIds(entries.files),
+      modules: {},
+      resolution: {},
+      pending: [],
+      metadata,
+    };
+    this.merge(graph, resolver, compiled);
+    await this.writer.markBuilding();
+    await this.writer.writeModules(compiled);
+    const vendorFile = await this.writer.writeVendor(graph);
+    const epoch = Date.now();
+    await this.writer.writeApp(graph, { generation, vendorFile, epoch });
+    await this.writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries, epoch });
+    await this.writer.pruneAfterFullBuild(graph, vendorFile, { generation, assets: compiler.assets });
+    await this.writer.clearBuilding();
+    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length, epoch };
+  }
+
+  compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
+    return new CsrDevModuleCompiler({
+      app: this.app,
+      paths: this.paths,
+      resolver,
+      context,
+      outDir: this.outDir,
+      routePrefix: this.routePrefix,
+    });
+  }
+
+  merge(graph: CsrDevGraph, resolver: CsrDevResolver, compiled: CsrDevCompiledModule[]): void {
+    for (const module of compiled)
+      graph.modules[module.id] = {
+        vendor: module.vendor,
+        mtimeMs: module.mtimeMs,
+        hash: module.hash,
+        deps: module.deps.map((dep) => (CsrDevPaths.isStub(dep) ? dep : this.paths.idOf(dep))),
+        ...(module.helpers ? { helpers: module.helpers.hash } : {}),
+      };
+    //? Only what this round compiled leaves pending: a root another route's check failed on stays for its retry.
+    const compiledIds = new Set(compiled.map((module) => module.id));
+    graph.pending = graph.pending.filter((id) => !compiledIds.has(id));
+    graph.resolution = resolver.serialize();
+    graph.runtimeResolved = resolver.serializeRuntimeResolved();
+  }
+
+  entryIds(files: Record<string, string>): Record<string, string> {
+    return Object.fromEntries(Object.entries(files).map(([key, file]) => [key, this.paths.idOf(file)]));
+  }
+}