@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/frontendBuild/buildRouteClient.test.ts

@@ -1,33 +1,17 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
 import { createTsconfigPackageResolver } from "../transforms/barrelImportsPlugin";
 import { CLIENT_BUNDLE_NAMING } from "./clientBuildTypes";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 import { RouteClientBuilder } from "./routeClientBuilder";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-client-entry-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const makeTempRoot = tempDirs("akan-client-entry-");
 
 describe("route client store bootstrap", () => {
   test("wraps client entries with app client bootstrap before re-exporting components", () => {
-    const original = "/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx";
+    const original = path.resolve("/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx");
     const source = RouteClientBuilder.createStoreBootstrapEntrySource({
       appName: "akan",
       originalEntry: original,
@@ -147,6 +131,57 @@ describe("route client store bootstrap", () => {
     );
   });
 
+  test("bundles every route's entries into one graph so a page never loads a module twice", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    const pageA = path.join(appDir, "page/a.tsx");
+    const pageB = path.join(appDir, "page/b.tsx");
+    const entryA = path.join(appDir, "ui/A.tsx");
+    const entryB = path.join(appDir, "ui/B.tsx");
+    const shared = path.join(appDir, "common/shared.ts");
+    await write(pageA, 'import { A } from "../ui/A";\nexport default A;\n');
+    await write(pageB, 'import { B } from "../ui/B";\nexport default B;\n');
+    await write(entryA, '"use client";\nimport { mark } from "../common/shared";\nexport const A = () => mark;\n');
+    await write(entryB, '"use client";\nimport { mark } from "../common/shared";\nexport const B = () => mark;\n');
+    await write(shared, 'export const mark = "shared-module-marker";\n');
+    const app = {
+      name: "demo",
+      cwdPath: appDir,
+      dist: { cwdPath: path.join(root, "dist/apps/demo") },
+      workspace: { workspaceRoot: root },
+      getConfig: async () => ({ barrelImports: [], optimizeImports: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+      getPublicEnv: () => ({}),
+    } as never;
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, async () => null);
+    const build = (seeds: string[], knownEntries: Set<string>) =>
+      new RouteClientBuilder({
+        app,
+        seeds,
+        graphSeeds: [pageA, pageB],
+        knownEntries,
+        discovery,
+        artifact: {} as never,
+      }).build();
+
+    const first = await build([pageA], new Set());
+    const second = await build([pageB], new Set(first.newEntries));
+
+    expect(first.newEntries).toEqual([entryA, entryB]);
+    expect(first.discoveredEntries).toEqual([entryA]);
+    expect(first.clientDeps).not.toContain(entryB);
+    expect(Object.keys(first.clientDepsByEntry ?? {}).sort()).toEqual([entryA, entryB]);
+    expect(second.newEntries).toEqual([]);
+    expect(second.discoveredEntries).toEqual([entryB]);
+    expect(Object.keys(second.manifestDelta)).toEqual([]);
+    const clientOut = path.join(appDir, ".akan/artifact/client");
+    const outputs = [...new Bun.Glob("**/*.js").scanSync(clientOut)];
+    const carriers = await Promise.all(
+      outputs.map(async (file) => (await Bun.file(path.join(clientOut, file)).text()).includes("shared-module-marker")),
+    );
+    expect(carriers.filter(Boolean)).toHaveLength(1);
+  });
+
   test("discovers client entries from installed akanjs package sources", async () => {
     const root = await makeTempRoot();
     const seed = path.join(root, "apps/demo/page/_index.tsx");
@@ -159,24 +194,14 @@ describe("route client store bootstrap", () => {
     await write(uiEntry, 'export { ClientPathWrapper } from "./System/Client";\n');
     await write(clientEntry, '"use client";\nexport const ClientPathWrapper = () => null;\n');
 
+    const entryFiles = new Map([
+      ["akanjs/ui", uiEntry],
+      ["akanjs/ui/System/Client.tsx", clientEntry],
+    ]);
     const discovery = new GraphClientEntryDiscovery({ barrelImports: ["akanjs/ui"] }, async (specifier) => {
-      if (specifier === "akanjs/ui") {
-        return {
-          pkgName: "akanjs/ui",
-          entryFile: uiEntry,
-          pkgDir: path.dirname(uiEntry),
-          preserveFilePath: true,
-        };
-      }
-      if (specifier === "akanjs/ui/System/Client.tsx") {
-        return {
-          pkgName: "akanjs/ui/System/Client.tsx",
-          entryFile: clientEntry,
-          pkgDir: path.dirname(clientEntry),
-          preserveFilePath: true,
-        };
-      }
-      return null;
+      const entryFile = entryFiles.get(specifier);
+      if (!entryFile) return null;
+      return { pkgName: specifier, entryFile, pkgDir: path.dirname(entryFile), preserveFilePath: true };
     });
 
     expect(await discovery.discover([seed])).toEqual([clientEntry]);

package/frontendBuild/bundleDefine.ts

@@ -0,0 +1,12 @@
+import type { App } from "../commandDecorators";
+
+export const bundleDefine = (app: App, command: "build" | "start", renderEnv: "ssr" | "csr") => {
+  const nodeEnv = command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
+  return {
+    "process.env.NODE_ENV": JSON.stringify(nodeEnv),
+    "process.env.AKAN_PUBLIC_RENDER_ENV": JSON.stringify(renderEnv),
+    ...Object.fromEntries(
+      Object.entries(app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
+    ),
+  };
+};

package/frontendBuild/clientBuildTypes.ts

@@ -10,39 +10,14 @@ export interface BuildClientOptions {
   outputDir?: string;
   servePrefix?: string;
   mode?: "production" | "test";
-  /** Additional Bun plugins applied to the client bundle build. */
   plugins?: BunPlugin[];
-  /**
-   * Legacy fallback: additional directories to filesystem-scan for
-   * `"use client"` entry points. Only used when `workspaceRoot` /
-   * `tsconfigPaths` are not provided (in which case we fall back to the old
-   * filesystem-scan strategy). Prefer the graph-based discovery.
-   */
+  /** Legacy filesystem-scan roots, used only when `workspaceRoot` / `tsconfigPaths` are absent. */
   extraClientScanRoots?: string[];
-  /**
-   * Environment variables to inline into the browser bundle via `define`.
-   * Keys are the original `process.env` names. Each key is emitted as
-   * `process.env.<KEY>` so existing server/client shared code that reads
-   * `process.env.AKAN_PUBLIC_*` keeps working unchanged.
-   */
+  /** Inlined via `define` as `process.env.<KEY>`. */
   publicEnv?: Record<string, string>;
-  /**
-   * Workspace root used by the graph-based client-entry discovery to resolve
-   * tsconfig-aliased specifiers (`@libs/shared/ui`, `@apps/<name>/client`,
-   * ...). When provided together with `tsconfigPaths`, discovery traverses
-   * the import graph starting from `appDir` instead of doing a filesystem
-   * scan, so `"use client"` files that no route transitively imports (e.g.
-   * unused editor components in a shared UI package) stay out of the client
-   * bundle.
-   */
+  /** With `tsconfigPaths`, discovery walks the import graph from `appDir` instead of scanning the filesystem. */
   workspaceRoot?: string;
-  /** Workspace tsconfig `compilerOptions.paths`. See `workspaceRoot`. */
   tsconfigPaths?: Record<string, string[]>;
-  /**
-   * Barrel specifiers whose imports are flattened by `barrelImportsPlugin`.
-   * Discovery rewrites barrel imports with the same analyzer before scanning,
-   * so the traversal sees the same leaf files the bundler will see.
-   */
   barrelImports?: string[];
 }
 
@@ -73,10 +48,7 @@ export interface BundleClientEntriesOptions {
   entries: string[];
   plugins?: BunPlugin[];
   outputSubdir?: string;
-  /**
-   * Future Fast Refresh hook. Bun only injects the React Refresh transform;
-   * the browser runtime/update protocol still needs to be provided by Akan.
-   */
+  /** Bun only injects the React Refresh transform; the browser runtime and update protocol are Akan's. */
   reactFastRefresh?: boolean;
 }
 
@@ -92,13 +64,10 @@ export interface BundleClientEntriesInternalOptions extends BundleClientEntriesO
 export interface BundleClientEntriesResult {
   manifest: ClientManifest;
   ssrManifest: SsrManifest;
-  /** Absolute path → serve URL for every entry point we produced. */
   entryUrlsByAbsPath: Map<string, string>;
-  /** Absolute source entry path → emitted entry file absolute path. */
   entryOutputAbsByAbsPath: Map<string, string>;
-  /** Absolute source files that Bun included for each client entry bundle. */
   entryDepsByAbsPath: Map<string, string[]>;
-  /** Absolute source entry path → workspace-relative client reference id. */
+  /** Workspace-relative client reference id per absolute source entry. */
   clientReferenceIdByAbsPath: Map<string, string>;
 }
 

package/frontendBuild/clientEntriesBundler.ts

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import type { SsrManifest, SsrManifestEntry } from "akanjs/server";
 import type { BunPlugin } from "bun";
-import { toClientReferencePath } from "../transforms/rscUseClientTransform";
+import { scanUseClientExports, toClientReferencePath } from "../transforms/rscUseClientTransform";
+import { bundleDefine } from "./bundleDefine";
 import {
   type BundleClientEntriesInternalOptions,
   type BundleClientEntriesResult,
@@ -13,11 +14,6 @@ import {
   type OpaqueEntryAliases,
 } from "./clientBuildTypes";
 
-/**
- * Low-level primitive shared by the eager base build and the lazy per-route
- * builds. Takes a flat entrypoints list, runs `Bun.build`, and extracts a
- * `ClientManifest` / `SsrManifest` covering only those entries.
- */
 export class ClientEntriesBundler {
   #app: BundleClientEntriesInternalOptions["app"];
   #entries: string[];
@@ -29,7 +25,6 @@ export class ClientEntriesBundler {
   #target: ClientBundleTarget;
   #outputSubdir: string;
   #reactFastRefresh: boolean;
-  #artifactDir: string;
   #outdir: string;
   #servePrefix: string;
   #manifest: ClientManifest = {};
@@ -52,8 +47,8 @@ export class ClientEntriesBundler {
     this.#target = options.target ?? "browser";
     this.#outputSubdir = options.outputSubdir ?? "client";
     this.#reactFastRefresh = options.reactFastRefresh ?? false;
-    this.#artifactDir = `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
-    this.#outdir = `${this.#artifactDir}/${this.#outputSubdir}`;
+    const artifactDir = `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
+    this.#outdir = `${artifactDir}/${this.#outputSubdir}`;
     this.#servePrefix = `/_akan/${this.#outputSubdir}`;
   }
 
@@ -68,7 +63,7 @@ export class ClientEntriesBundler {
       format: "esm",
       naming: CLIENT_BUNDLE_NAMING,
       metafile: true,
-      define: this.#getDefine(),
+      define: bundleDefine(this.#app, this.#command, "ssr"),
       minify: this.#command === "build",
       optimizeImports: akanConfig.optimizeImports,
       reactFastRefresh: this.#command === "start" && this.#outputSubdir === "client" && this.#reactFastRefresh,
@@ -100,17 +95,6 @@ export class ClientEntriesBundler {
     };
   }
 
-  #getDefine(): 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("ssr"),
-      ...Object.fromEntries(
-        Object.entries(this.#app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
-      ),
-    };
-  }
-
   async #createOpaqueEntryAliases(): Promise<OpaqueEntryAliases> {
     const aliasDir = path.join(this.#app.cwdPath, ".akan", "generated", "client-entry-alias", this.#outputSubdir);
     fs.mkdirSync(aliasDir, { recursive: true });
@@ -141,22 +125,10 @@ export class ClientEntriesBundler {
   }
 
   async #scanEntryExportNames(absEntry: string): Promise<string[]> {
-    const source = await Bun.file(absEntry).text();
-    const transpiler = new Bun.Transpiler({ loader: this.#loaderForEntry(absEntry) });
-    return transpiler.scan(source).exports;
+    return scanUseClientExports(await Bun.file(absEntry).text(), absEntry, this.#app.workspace.workspaceRoot);
   }
 
-  #loaderForEntry(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-    if (absPath.endsWith(".tsx")) return "tsx";
-    if (absPath.endsWith(".jsx")) return "jsx";
-    if (absPath.endsWith(".ts")) return "ts";
-    return "js";
-  }
-
-  /**
-   * Build a BunPlugin that marks a fixed set of bare specifiers as external via `onResolve`,
-   * as opposed to `Bun.build({ external })`, so macro-time imports still resolve normally.
-   */
+  // `onResolve` rather than `Bun.build({ external })`, so macro-time imports still resolve normally.
   #createExternalSpecifiersPlugin(): BunPlugin {
     const set = new Set(this.#external);
     const subpathSet = new Set(this.#externalSubpaths);
@@ -182,11 +154,8 @@ export class ClientEntriesBundler {
     exactExternals: Set<string>,
     subpathExternals: Set<string>,
   ): boolean {
-    if (exactExternals.has(specifier)) return true;
-    if (subpathExternals.has(specifier)) return true;
-    for (const external of subpathExternals) {
-      if (specifier.startsWith(`${external}/`)) return true;
-    }
+    if (exactExternals.has(specifier) || subpathExternals.has(specifier)) return true;
+    for (const external of subpathExternals) if (specifier.startsWith(`${external}/`)) return true;
     return false;
   }
 

package/frontendBuild/clientEntryDiscovery.ts

@@ -1,24 +1,17 @@
 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[];
@@ -26,33 +19,18 @@ interface FileFacts {
 
 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.
-   */
+  // 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>>();
   #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>();
@@ -83,20 +61,12 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
       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.
+    // Reachable-entry results are transitive, so a changed child invalidates every ancestor.
     this.#reachableEntriesCache.clear();
     this.#forgetMissing();
   }
 
-  /**
-   * 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.
-   */
+  // Negatives are keyed by extension-less path or `dir\0specifier`, which a new file's path cannot reach, so all go.
   #forgetMissing(): void {
     for (const key of this.#missingFiles) this.#fileExistsCache.delete(key);
     for (const key of this.#unresolvedPaths) this.#resolvedFileCache.delete(key);
@@ -121,10 +91,6 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
     return cached;
   }
 
-  /**
-   * 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 +100,6 @@ 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.
         if (USE_CLIENT_RE.test(content)) return { isClientEntry: true, imports: [] };
         return { isClientEntry: false, imports: this.#scanImports(await this.#rewrite(content)) };
       })();

package/frontendBuild/csrArtifactBuilder.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 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 { 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()],
     });
 
@@ -118,17 +118,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 +157,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 +199,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 +208,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/cssCandidateCache.test.ts

@@ -17,18 +17,12 @@ describe("CssCandidateCache token extraction", () => {
     expect(candidates).toEqual(expect.arrayContaining(["w-full", "hover:bg-muted", "md:w-1/2", "text-[#fff]"]));
   });
 
-  // A candidate that opens with `[` used to be torn into `_td` + `px-3`, so every descendant-variant
-  // rule in the framework compiled to nothing and its element rendered unstyled with no diagnostic.
   test("keeps an arbitrary variant that starts with a bracket", async () => {
     const candidates = await scan(`const c = "[&_td]:px-3 [&>*]:gap-2 [&_tbody_tr]:border-t";`);
     expect(candidates).toEqual(expect.arrayContaining(["[&_td]:px-3", "[&>*]:gap-2", "[&_tbody_tr]:border-t"]));
     expect(candidates).not.toContain("_td");
   });
 
-  // A labelled tuple type looks like an arbitrary property, and compiles to a rule whose declaration is
-  // TypeScript. `optimize()` cannot parse that, and drops far more than the offending rule on its way
-  // out — every variant in the build went missing, so nothing hovered, focused or responded to a
-  // breakpoint. Tailwind writes a space in an arbitrary value as `_`, so whitespace rules the token out.
   test("ignores a labelled tuple type that only looks like an arbitrary property", async () => {
     const candidates = await scan(
       `type A = [key: string, make: () => unknown][];\ntype B = [setQueryArgs: (a: Args) => Args, options?: Policy];`,

package/frontendBuild/cssCandidateCache.ts

@@ -1,18 +1,7 @@
 import { stat } from "node:fs/promises";
 
-/**
- * Every identifier-ish token in a source file is a potential tailwind class. The leading alternation
- * matters: an arbitrary variant starts with `[` (`[&_td]:px-3`, `[&>*]:gap-2`), and a pattern anchored
- * on a word character tears it into `_td` plus `px-3` instead — both meaningless, so the rule compiles
- * to nothing and the element silently renders unstyled.
- *
- * Brackets must hold no whitespace. Tailwind spells a space in an arbitrary value `_`, so a bracket
- * group containing one is never a class — but it is exactly the shape of a labelled tuple type
- * (`[key: string, make: () => unknown]`). Scanned as a candidate, that compiles to an arbitrary
- * *property* rule carrying TypeScript as its declaration, which the lightningcss pass in `optimize()`
- * cannot parse; its error recovery then drops a whole span of the stylesheet — in practice every
- * variant rule in the build, leaving hover, focus, responsive and dark styles silently absent.
- */
+// The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole. Brackets hold no whitespace: a labelled
+// tuple type scanned as a class compiles to a rule lightningcss cannot parse, and it then drops every variant rule.
 const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:\[[^\]\s]+\][\w:/.-]*)*/g;
 
 interface CachedFile {
@@ -26,19 +15,9 @@ interface CacheFile {
   files: Record<string, CachedFile>;
 }
 
-/**
- * Tailwind candidate tokens per source file, cached on disk across builds.
- *
- * The scan reads the **full text** of every source file on every CSS rebuild — measured at 385-508ms
- * per save on `apps/akan`. Phase 2 moved css compilation into a per-generation batch worker, so an
- * in-memory cache (what `03-phase3-topology-and-trim.md` §3.4 originally proposed) buys nothing: the
- * process that would hold it exits before the next save. Disk is what survives the worker, a builder
- * recycle and a dev-host restart alike, which is the same reasoning §3.3 used for the font cache.
- *
- * Keyed on (mtime, size) per file, so a save re-reads only the files in that batch.
- */
+/** Tailwind candidates per source file, on disk: the batch worker that compiles CSS exits before the next save. */
 export class CssCandidateCache {
-  /** Bump when the token regex or the entry shape changes, so stale extractions are not reused. */
+  // Bump when the token regex or the entry shape changes, so stale extractions are not reused.
   static readonly #version = 3;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
@@ -58,7 +37,6 @@ export class CssCandidateCache {
     return this.#rescanned;
   }
 
-  /** A cache that cannot be read or is a version behind simply starts empty — it is only an optimisation. */
   async load(): Promise<this> {
     const raw = (await Bun.file(this.#path)
       .json()
@@ -71,12 +49,7 @@ export class CssCandidateCache {
     return this;
   }
 
-  /**
-   * The file's candidate tokens, read from disk only when its (mtime, size) no longer matches.
-   *
-   * Read errors propagate, as they did before this cache existed: a source file the compiler cannot
-   * read is a broken build, not a cache miss to paper over.
-   */
+  // A read error propagates: an unreadable source is a broken build, not a cache miss.
   async candidatesFor(file: string): Promise<string[]> {
     const stats = await stat(file).catch(() => null);
     const cached = this.#entries.get(file);
@@ -94,13 +67,6 @@ export class CssCandidateCache {
     return candidates;
   }
 
-  /**
-   * Persist, dropping files the scan no longer reaches so a renamed or deleted module does not keep
-   * feeding its classes to the compiler forever.
-   *
-   * A rebuild that re-read nothing writes nothing: the boot double-build and any CSS rebuild triggered
-   * by something other than a source edit would otherwise rewrite the whole file for no change.
-   */
   async save(present: Set<string>): Promise<void> {
     for (const file of [...this.#entries.keys()]) {
       if (present.has(file)) continue;
@@ -111,8 +77,7 @@ export class CssCandidateCache {
     this.#dirty = false;
     const files: Record<string, CachedFile> = {};
     for (const [file, entry] of this.#entries) files[file] = entry;
-    // A cache that cannot be written is a slow build, not a failed one — a read-only checkout must
-    // still compile.
+    // An unwritable cache is a slow build, not a failed one: a read-only checkout must still compile.
     await Bun.write(
       this.#path,
       JSON.stringify({ version: CssCandidateCache.#version, files } satisfies CacheFile),