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

package/frontendBuild/fontOptimizer.ts

@@ -21,10 +21,6 @@ export interface OptimizeAppFontsResult {
   files: string[];
 }
 
-/**
- * Lets a boot that changed nothing about its fonts skip re-subsetting them. `files` is stored relative
- * to the artifact root so the `build` and `start` roots keep independent, relocatable caches.
- */
 interface FontOptimizerCache {
   version: number;
   key: string;
@@ -43,8 +39,6 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
-  // 2: the key moved to sha256 over a deterministically ordered `auto` text, so v1 entries cannot be
-  // compared against and their subsets were built from `page`/`ui` only.
   static readonly #cacheVersion = 2;
 
   constructor(app: App, command: FontOptimizerCommand = "start") {
@@ -76,10 +70,7 @@ export class FontOptimizer {
     return path.join(this.#artifactRoot, "fontCache.json");
   }
 
-  /**
-   * Null means "do not cache this run": a source we cannot stat is a source whose staleness we cannot
-   * detect, and the uncached path is also the one that warns about it.
-   */
+  // null skips the cache: an unstat-able source's staleness is undetectable, and the uncached path warns about it.
   async #buildCacheKey(fonts: ReactFont[]): Promise<string | null> {
     const sources: unknown[] = [];
     for (const font of fonts) {
@@ -96,18 +87,13 @@ export class FontOptimizer {
         if (!stamp) return null;
         sources.push({ subsetFile: filePath, ...stamp });
       }
-      // `auto` derives the subset from app source text, which no font config hash can capture.
       if (this.#getFontSubsets(font).includes("auto"))
         sources.push({ autoSubsetText: this.#cacheDigest(await this.#collectAutoSubsetText()) });
     }
     return this.#cacheDigest({ version: FontOptimizer.#cacheVersion, fonts, sources });
   }
 
-  /**
-   * Cache keys get a cryptographic digest, not the 32-bit FNV `#hashFontConfig` computes for filenames:
-   * a collision there serves a stale subset as if it were current, while a filename only has to be short
-   * and stable.
-   */
+  // sha256, not #hashFontConfig's 32-bit FNV: a key collision would serve a stale subset as current.
   #cacheDigest(value: unknown) {
     return new Bun.CryptoHasher("sha256").update(this.#stableStringify(value)).digest("hex");
   }
@@ -152,13 +138,11 @@ export class FontOptimizer {
         const file = Bun.file(filePath);
         if (!(await file.exists())) return;
         const source = await file.text();
-        // A `.fonts()` stage or a `fonts` declaration cannot exist in text that never mentions it, and parsing the
-        // route files that never declare one is what a cached optimize() otherwise spends its time on.
         if (!source.includes("fonts")) return;
         fonts.push(...this.#extractFontsExport(source, filePath));
       }),
     );
-    return this.#dedupeFonts(fonts);
+    return [...new Map(fonts.map((font) => [JSON.stringify(font), font] as const)).values()];
   }
 
   async #optimizeFont(font: ReactFont) {
@@ -186,12 +170,6 @@ export class FontOptimizer {
     if (faceCss.length > 0) this.#cssParts.push(...faceCss, this.#buildRootVariableRule(font));
   }
 
-  /**
-   * The font list of a route file, from the `.fonts([…])` stage of its default-exported `rootLayout()` chain
-   * or from the legacy `export const fonts`. Only an inline literal is readable, because the build enumerates
-   * routes without evaluating them — and a list it cannot read is warned about rather than skipped in silence:
-   * the runtime still emits `/_akan/fonts` preloads for fonts nothing subset, and every one of them 404s.
-   */
   #extractFontsExport(source: string, filePath: string): ReactFont[] {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
     const declaration = this.#findFontsDeclaration(sourceFile);
@@ -203,7 +181,7 @@ export class FontOptimizer {
       this.#app.logger.warn(
         `[font] ${path.relative(this.#app.cwdPath, filePath)} declares fonts the build cannot read without evaluating the module — write the list inline, or nothing is subset for it and every /_akan/fonts request 404s`,
       );
-    return fonts.map((font) => this.#withFontDefaults(font));
+    return fonts.map((font) => ({ ...font, subsets: font.subsets ?? [...DEFAULT_FONT_SUBSETS] }));
   }
 
   #isReadableFont(value: unknown): value is ReactFont {
@@ -231,7 +209,7 @@ export class FontOptimizer {
     return null;
   }
 
-  /** Walks a `rootLayout()` chain from its outermost call inward, so the stage that wins at runtime is the one read. */
+  // Outermost call first, so `??=` keeps the stage that wins at runtime.
   #findChainStageArgument(expression: ts.Expression, stageName: string): ts.Expression | null {
     let node = this.#unwrapExpression(expression);
     let argument: ts.Expression | null = null;
@@ -284,16 +262,6 @@ export class FontOptimizer {
     return null;
   }
 
-  #dedupeFonts(fonts: ReactFont[]) {
-    const map = new Map<string, ReactFont>();
-    for (const font of fonts) map.set(JSON.stringify(font), font);
-    return [...map.values()];
-  }
-
-  #withFontDefaults(font: ReactFont): ReactFont {
-    return { ...font, subsets: font.subsets ?? [...DEFAULT_FONT_SUBSETS] };
-  }
-
   #getFontSubsets(font: ReactFont): ReactFontSubset[] {
     return font.subsets ?? DEFAULT_FONT_SUBSETS;
   }
@@ -310,12 +278,8 @@ export class FontOptimizer {
     return font.optimize !== false;
   }
 
-  #getFontStyles(font: ReactFont): ReactFontStyle[] {
-    return font.styles?.length ? font.styles : ["normal"];
-  }
-
   #getFontFaces(font: ReactFont): ReactFontFace[] {
-    const enabledStyles = new Set(this.#getFontStyles(font));
+    const enabledStyles = new Set<ReactFontStyle>(font.styles?.length ? font.styles : ["normal"]);
     return font.paths
       .map((fontPath) => {
         const style = fontPath.style ?? "normal";
@@ -393,8 +357,7 @@ export class FontOptimizer {
     return null;
   }
 
-  /** `subset-font`, `fonteditor-core` and `fontaine` are imported here rather than at module scope so a
-   * cache hit — the common case once the cache exists — loads none of them. */
+  // The font libraries are imported lazily so a cache hit loads none of them.
   async #buildFontBuffer(font: ReactFont, sourceBuffer: Buffer, sourcePath: string) {
     if (font.subset === false) return this.#convertToWoff2(sourceBuffer, sourcePath);
     const { default: subsetFont } = await import("subset-font");
@@ -403,16 +366,12 @@ export class FontOptimizer {
 
   async #convertToWoff2(buffer: Buffer, sourcePath: string) {
     const { createFont } = await import("fonteditor-core");
-    await this.#initWoff2();
+    this.#woff2Ready ??= import("fonteditor-core").then(({ woff2 }) => woff2.init()).then(() => undefined);
+    await this.#woff2Ready;
     const font = createFont(buffer, { type: this.#getFontType(sourcePath, buffer) });
     return font.write({ type: "woff2", toBuffer: true });
   }
 
-  async #initWoff2() {
-    this.#woff2Ready ??= import("fonteditor-core").then(({ woff2 }) => woff2.init()).then(() => undefined);
-    return this.#woff2Ready;
-  }
-
   #getFontType(sourcePath: string, buffer: Buffer) {
     const signature = buffer.toString("ascii", 0, 4);
     if (signature === "wOFF") return "woff";
@@ -443,25 +402,15 @@ export class FontOptimizer {
   }
 
   async #getSubsetPresetText(subset: ReactFontSubset) {
-    if (subset === "latin") return this.#rangeText(0x20, 0x7e);
-    if (subset === "latin-ext") return `${this.#rangeText(0x20, 0x7e)}${this.#rangeText(0xa0, 0x024f)}`;
+    if (subset === "latin") return FontOptimizer.#rangeText(0x20, 0x7e);
+    if (subset === "latin-ext")
+      return `${FontOptimizer.#rangeText(0x20, 0x7e)}${FontOptimizer.#rangeText(0xa0, 0x024f)}`;
     if (subset === "ks-x-1001") return FontOptimizer.#getKsX1001Text();
     if (subset === "auto") return this.#collectAutoSubsetText();
     return "";
   }
 
-  /**
-   * Every source that can put a glyph on screen, concatenated in a **stable** order.
-   *
-   * The order is load-bearing even though a glyph set is not: `#buildCacheKey` hashes this string, so
-   * reading the roots concurrently and pushing as each file resolved made the key depend on i/o
-   * scheduling — measured 8 distinct keys over 8 runs against unchanged sources, which means the cache
-   * never hit and every build re-subset the fonts.
-   *
-   * `lib` is in the roots because that is where user-facing text actually lives: a dictionary's
-   * `[en, ko]` pairs are the Korean in the app, and a subset built from `page` and `ui` alone renders
-   * them as tofu — while hashing the same partial text also stopped a new label from invalidating.
-   */
+  // Keep the order stable: #buildCacheKey hashes this text. `lib` counts because dictionaries hold user-visible text.
   async #collectAutoSubsetText() {
     //* Synced lib pages hold app-visible text too, and a glob never crosses the symlink that mounts them.
     const libPageRoots = (await this.#app.getPageRoots()).filter((root) => root.keyPrefix).map((root) => root.dir);
@@ -481,12 +430,6 @@ export class FontOptimizer {
     return parts.join("");
   }
 
-  #rangeText(start: number, end: number) {
-    let text = "";
-    for (let code = start; code <= end; code++) text += String.fromCodePoint(code);
-    return text;
-  }
-
   static #getKsX1001Text() {
     if (FontOptimizer.#ksX1001Text) return FontOptimizer.#ksX1001Text;
     try {
@@ -500,12 +443,12 @@ export class FontOptimizer {
       }
       FontOptimizer.#ksX1001Text = [...chars].join("");
     } catch {
-      FontOptimizer.#ksX1001Text = FontOptimizer.#rangeTextStatic(0xac00, 0xd7a3);
+      FontOptimizer.#ksX1001Text = FontOptimizer.#rangeText(0xac00, 0xd7a3);
     }
     return FontOptimizer.#ksX1001Text;
   }
 
-  static #rangeTextStatic(start: number, end: number) {
+  static #rangeText(start: number, end: number) {
     let text = "";
     for (let code = start; code <= end; code++) text += String.fromCodePoint(code);
     return text;

package/frontendBuild/fontPruner.test.ts

@@ -1,11 +1,11 @@
-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 { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
 import { FontPruner } from "./fontPruner";
 
-const tempRoots: string[] = [];
+const tempRoot = tempDirs("akan-devkit-font-prune-");
 
 interface Tree {
   layout?: string;
@@ -23,8 +23,7 @@ const write = async (root: string, files: Record<string, string>) => {
 };
 
 const makeApp = async ({ layout = layoutWith(), publicFiles = {}, artifactFiles = {}, csrFiles = {} }: Tree = {}) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-font-prune-"));
-  tempRoots.push(root);
+  const root = await tempRoot();
   const cwdPath = path.join(root, "apps/demo");
   const distPath = path.join(root, "dist/apps/demo");
   await mkdir(path.join(cwdPath, "page"), { recursive: true });
@@ -58,10 +57,6 @@ export default function Layout() {
 
 const exists = (distPath: string, rel: string) => Bun.file(path.join(distPath, "public", rel)).exists();
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("FontPruner", () => {
   test("drops a subset font's source and reports the bytes freed", async () => {
     const { app, distPath } = await makeApp({

package/frontendBuild/fontPruner.ts

@@ -18,12 +18,7 @@ export interface FontPruneResult {
   freedBytes: number;
 }
 
-/**
- * Drops the font sources in a build's `public/` that no built surface reads. A font with `optimize` on is
- * served from `/_akan/fonts` after subsetting, so its source is a build input — the image ships it and the
- * runtime never opens it. Only `dist` is touched: an app's and a lib's own `public/` keep every file, because
- * one lib's fonts are picked over differently by every app that mounts it and by other repos.
- */
+/** Deletes the fonts in the build's `dist/…/public` that nothing reads; source `public/` trees are never touched. */
 export class FontPruner {
   #app: App;
   #keepGlobs: string[];
@@ -92,15 +87,8 @@ export class FontPruner {
     return candidates;
   }
 
-  /**
-   * Matched by basename rather than by URL, so a reference survives every spelling a referrer may use — an
-   * absolute or relative `url()`, and the percent-encoded form a font whose filename carries a space needs.
-   *
-   * The build's own bundles are read on weaker terms than `public/` and the compiled CSS: every route file's
-   * `fonts` declaration is inlined into the pages bundle, the client chunks and the CSR shell, so a declared
-   * source is in all three whether or not anything loads it. A hit there is therefore ignored for a font the
-   * optimizer already subset — that string is the declaration, not a fetch.
-   */
+  // Basename match (plain and percent-encoded) covers every url() spelling. The bundles inline each route's `fonts`
+  // declaration, so a bundle hit counts only for a font the optimizer did not subset.
   async #findReferrers(
     candidates: { rel: string; basename: string }[],
     optimizedSrcs: Set<string>,
@@ -155,11 +143,8 @@ export class FontPruner {
     for (const dir of dirs) await rmdir(path.join(this.#publicRoot, dir)).catch(() => undefined);
   }
 
-  /**
-   * The referrer roll-up is `info`, not `verbose`: a generated file that lists every asset in `public/` — a
-   * service-worker precache manifest is the usual one — is a real reference and keeps every font it names, so
-   * without this line a build that pruned nothing looks the same as a build with nothing to prune.
-   */
+  // The roll-up is `info`: a precache manifest listing all of public/ keeps every font, which otherwise looks like
+  // a build with nothing to prune.
   #report(result: FontPruneResult) {
     if (!result.removed.length && !result.kept.length) return;
     for (const { file, bytes } of result.removed)

package/frontendBuild/frontendBuild.test.ts

@@ -1,9 +1,9 @@
-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 { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RoutesManifest } from "akanjs/server";
+import { tempDirs, writeText as write } from "../testHelpers";
 import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 import { CssCompiler, declaredCustomProperties, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
@@ -15,33 +15,19 @@ import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
 import { prepareCssAsset } from "./ssrBaseArtifactBuilder";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-frontend-"));
-  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-devkit-frontend-");
 
 describe("PagesEntrySourceGenerator", () => {
   const toSpecifier = (absPath: string) => path.resolve(absPath).split(path.sep).join("/");
+  const indexAbs = path.resolve("/repo/apps/demo/page/_index.tsx");
+  const adminAbs = path.resolve("/repo/apps/demo/page/admin.tsx");
+  const entries = [
+    { key: "./_index.tsx", moduleAbsPath: indexAbs },
+    { key: "./admin.tsx", moduleAbsPath: adminAbs },
+  ];
 
   test("generates dynamic import source using forward-slash module paths", () => {
-    const indexAbs = path.resolve("/repo/apps/demo/page/_index.tsx");
-    const adminAbs = path.resolve("/repo/apps/demo/page/admin.tsx");
-    const source = PagesEntrySourceGenerator.generate([
-      { key: "./_index.tsx", moduleAbsPath: indexAbs },
-      { key: "./admin.tsx", moduleAbsPath: adminAbs },
-    ]);
+    const source = PagesEntrySourceGenerator.generate(entries);
 
     expect(source).toBe(
       [
@@ -55,12 +41,7 @@ describe("PagesEntrySourceGenerator", () => {
   });
 
   test("generates static import source for single-file CSR bundles", async () => {
-    const indexAbs = path.resolve("/repo/apps/demo/page/_index.tsx");
-    const adminAbs = path.resolve("/repo/apps/demo/page/admin.tsx");
-    const source = await PagesEntrySourceGenerator.generateStatic([
-      { key: "./_index.tsx", moduleAbsPath: indexAbs },
-      { key: "./admin.tsx", moduleAbsPath: adminAbs },
-    ]);
+    const source = await PagesEntrySourceGenerator.generateStatic(entries);
 
     expect(source).toBe(
       [
@@ -333,13 +314,14 @@ describe("RoutesManifestArtifactSerializer", () => {
 describe("HmrChangeClassifier", () => {
   test("classifies code, css, config, and ignored files", () => {
     const classifier = new HmrChangeClassifier();
-    expect(classifier.classify("/repo/apps/demo/page/_index.tsx")).toBe("code");
-    expect(classifier.classify("/repo/apps/demo/page/styles.css")).toBe("css");
-    expect(classifier.classify("/repo/apps/demo/akan.config.ts")).toBe("config");
-    expect(classifier.classify("/repo/apps/demo/.DS_Store")).toBe("ignore");
-    expect(classifier.classify(`/repo/apps/demo/node_modules/pkg/index.ts`)).toBe("ignore");
-    expect(classifier.classify(`/repo/apps/demo/.akan/generated/page.tsx`)).toBe("ignore");
-    expect(classifier.classify("/repo/apps/demo/public/logo.png")).toBe("ignore");
+    const app = path.resolve("/repo/apps/demo");
+    expect(classifier.classify(path.join(app, "page/_index.tsx"))).toBe("code");
+    expect(classifier.classify(path.join(app, "page/styles.css"))).toBe("css");
+    expect(classifier.classify(path.join(app, "akan.config.ts"))).toBe("config");
+    expect(classifier.classify(path.join(app, ".DS_Store"))).toBe("ignore");
+    expect(classifier.classify(path.join(app, "node_modules/pkg/index.ts"))).toBe("ignore");
+    expect(classifier.classify(path.join(app, ".akan/generated/page.tsx"))).toBe("ignore");
+    expect(classifier.classify(path.join(app, "public/logo.png"))).toBe("ignore");
   });
 });
 
@@ -394,16 +376,16 @@ describe("DevGeneratedIndexSync", () => {
 
 describe("DevChangePlanner", () => {
   test("classifies server, client, shared, and generated barrel changes", () => {
-    const root = "/repo";
+    const root = path.resolve("/repo");
     const planner = new DevChangePlanner({ workspaceRoot: root });
-    const generatedIndex = `${root}/libs/shared/common/index.ts`;
+    const generatedIndex = path.join(root, "libs/shared/common/index.ts");
     const plan = planner.plan({
       generation: 7,
       files: [
-        `${root}/libs/shared/lib/admin/admin.service.ts`,
-        `${root}/libs/shared/lib/admin/Admin.Template.tsx`,
-        `${root}/libs/shared/lib/admin/admin.constant.ts`,
-        `${root}/libs/shared/common/foo.ts`,
+        path.join(root, "libs/shared/lib/admin/admin.service.ts"),
+        path.join(root, "libs/shared/lib/admin/Admin.Template.tsx"),
+        path.join(root, "libs/shared/lib/admin/admin.constant.ts"),
+        path.join(root, "libs/shared/common/foo.ts"),
       ],
       kinds: ["code"],
       generatedFiles: [generatedIndex],
@@ -429,21 +411,22 @@ describe("DevChangePlanner", () => {
   });
 
   test("recycles builder for macro-backed dictionary and signal metadata changes", () => {
-    const root = "/repo";
+    const root = path.resolve("/repo");
     const planner = new DevChangePlanner({ workspaceRoot: root });
+    const dictionaryFile = path.join(root, "apps/demo/lib/_demo/demo.dictionary.ts");
     const dictionaryPlan = planner.plan({
       generation: 3,
-      files: [`${root}/apps/demo/lib/_demo/demo.dictionary.ts`],
+      files: [dictionaryFile],
       kinds: ["code"],
     });
     const signalPlan = planner.plan({
       generation: 4,
-      files: [`${root}/libs/shared/lib/admin/admin.signal.ts`],
+      files: [path.join(root, "libs/shared/lib/admin/admin.signal.ts")],
       kinds: ["code"],
     });
 
     expect(dictionaryPlan.actions).toEqual(["rebuild-client", "restart-backend", "restart-builder"]);
-    expect(dictionaryPlan.reasonByFile[`${root}/apps/demo/lib/_demo/demo.dictionary.ts`]).toContain("runtime-metadata");
+    expect(dictionaryPlan.reasonByFile[dictionaryFile]).toContain("runtime-metadata");
     expect(signalPlan.actions).toContain("restart-builder");
   });
 });
@@ -499,6 +482,14 @@ describe("CssImportResolver", () => {
 });
 
 describe("CssCompiler", () => {
+  const cssCompilerFor = (root: string, cwdPath: string, app: object = {}) =>
+    new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath,
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+      ...app,
+    } as never);
+
   test("scans installed akanjs sources while ignoring other node_modules", async () => {
     expect(isIgnoredNodeModuleSource("/repo/node_modules/react/index.js")).toBe(true);
     expect(isIgnoredNodeModuleSource("/repo/node_modules/akanjs/ui/Button.tsx")).toBe(false);
@@ -512,13 +503,8 @@ describe("CssCompiler", () => {
     await write(cssPath, `@import ${JSON.stringify(tailwindCssPath)};\n@source "./**/*";\n`);
     await write(uiSource, 'export const Button = () => <button className="text-fuchsia-500" />;\n');
 
-    const compiler = new CssCompiler({
-      workspace: { workspaceRoot: root },
-      // The candidate cache lands under `<cwdPath>/.akan/cache`, so point it at this test's temp root
-      // rather than wherever the suite happens to run from.
-      cwdPath: root,
-      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
-    } as never);
+    // The candidate cache lands under `<cwdPath>/.akan/cache`, so keep it inside this test's temp root.
+    const compiler = cssCompilerFor(root, root);
     const css = await compiler.compileCss([cssPath], []);
 
     expect(css).toContain(".text-fuchsia-500");
@@ -540,11 +526,7 @@ describe("CssCompiler", () => {
     const cssPath = path.join(root, "apps/demo/page/styles.css");
     await write(cssPath, '@import "../../../libs/shared/ui/tokens.css";\n');
 
-    const compiler = new CssCompiler({
-      workspace: { workspaceRoot: root },
-      cwdPath: path.join(root, "apps/demo"),
-      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
-    } as never);
+    const compiler = cssCompilerFor(root, path.join(root, "apps/demo"));
 
     await expect(compiler.compileCss([cssPath], [])).rejects.toThrow(
       /failed to resolve stylesheet import "\.\.\/\.\.\/\.\.\/libs\/shared\/ui\/tokens\.css"/,
@@ -558,13 +540,10 @@ describe("CssCompiler", () => {
     await write(path.join(appDir, "page/styles.css"), '@import "../../../libs/shared/ui/brand.css";\n');
     await write(path.join(root, "libs/shared/ui/brand.css"), ":root { --kakao: #fee500; --naver: #1ec800; }\n");
 
-    const compiler = new CssCompiler({
-      workspace: { workspaceRoot: root },
-      cwdPath: appDir,
+    const compiler = cssCompilerFor(root, appDir, {
       getPageKeys: async () => ["./_index.tsx"],
       getConfig: async () => ({ barrelImports: [], basePaths: [] }),
-      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
-    } as never);
+    });
     const cssByBasePath = await compiler.getCssByBasePath();
 
     expect(cssByBasePath[""]).toContain("--kakao");
@@ -585,13 +564,11 @@ describe("CssCompiler", () => {
     await write(path.join(root, "libs/shared/ui/tokens.css"), ":root { --kakao: #fee500; }\n");
     await write(path.join(root, "libs/unused/ui/tokens.css"), ":root { --unused: #000000; }\n");
 
-    const compiler = new CssCompiler({
-      workspace: { workspaceRoot: root },
-      cwdPath: appDir,
+    const compiler = cssCompilerFor(root, appDir, {
       getPageKeys: async () => ["./_index.tsx"],
       getConfig: async () => ({ barrelImports: [] }),
       getTsConfig: async () => ({ compilerOptions: { paths: { "@libs/*": ["./libs/*"] } } }),
-    } as never);
+    });
     const { cssPaths } = await compiler.discoverCssAndSources();
 
     expect(cssPaths).toEqual([path.join(root, "libs/shared/ui/tokens.css"), path.join(appDir, "page/styles.css")]);

package/frontendBuild/hmrChangeClassifier.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import type { ChangeKind } from "akanjs/server";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 
-const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const CSS_EXTS = new Set([".css"]);
 const CONFIG_BASENAMES = new Set(["akan.config.ts", "bunfig.toml", "tsconfig.json", "package.json"]);
 
@@ -19,7 +19,7 @@ export class HmrChangeClassifier {
   #isUninteresting(abs: string): boolean {
     const base = path.basename(abs);
     if (!base) return true;
-    if (base.startsWith(".")) return true; // .git, .DS_Store, vim swaps, etc.
+    if (base.startsWith(".")) return true;
     if (base.endsWith("~") || base.endsWith(".swp") || base.endsWith(".swx") || base.endsWith(".tmp")) return true;
     if (abs.includes(`${path.sep}node_modules${path.sep}`)) return true;
     if (abs.includes(`${path.sep}.akan${path.sep}`)) return true;

package/frontendBuild/hmrWatcher.test.ts

@@ -1,24 +1,17 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { Logger } from "akanjs/common";
+import { tempDirs } from "../testHelpers";
 import { type ChangeBatch, HmrWatcher } from "./hmrWatcher";
 
-/**
- * These run against the real Bun watcher rather than a fake, because the behaviour under test only
- * exists there: Bun 1.3.14's recursive `fs.watch` reports about one path per ~200ms coalescing window and
- * discards the rest (`local/optimize-resource/06-watcher-dropped-event.md`). A fake that delivered every
- * event would pass no matter what the watcher did with them.
- */
+// The real Bun watcher, not a fake: the dropped-event behaviour under test only exists there.
 const STREAM_WARMUP_MS = 600;
 const SETTLE_MS = 1_500;
 const TEST_TIMEOUT_MS = 15_000;
 
 const started: HmrWatcher[] = [];
-const roots: string[] = [];
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Every level `HmrWatcher` can reach, so adding a log line cannot fail a test for the wrong reason. */
 const silentLogger = {
   trace: () => undefined,
   verbose: () => undefined,
@@ -29,12 +22,6 @@ const silentLogger = {
   error: () => undefined,
 } as unknown as Logger;
 
-const makeRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-hmr-watcher-"));
-  roots.push(root);
-  return root;
-};
-
 const seed = async (root: string, rel: string, content = "export const x = 1;\n") => {
   const abs = path.join(root, rel);
   await mkdir(path.dirname(abs), { recursive: true });
@@ -56,10 +43,10 @@ const watch = async (root: string) => {
   return { watcher, batches, seen: () => new Set(batches.flatMap((batch) => batch.files)) };
 };
 
-afterEach(async () => {
+afterEach(() => {
   for (const watcher of started.splice(0)) watcher.stop();
-  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
+const makeRoot = tempDirs("akan-hmr-watcher-");
 
 describe("HmrWatcher", () => {
   test(
@@ -69,15 +56,12 @@ describe("HmrWatcher", () => {
       const files = await Promise.all([0, 1, 2, 3, 4].map((i) => seed(root, `lib/File${i}.ts`)));
       const { batches, seen, watcher } = await watch(root);
 
-      // No gaps between writes, so they share one coalescing window and Bun names at most one of them.
       for (const [i, abs] of files.entries()) await writeFile(abs, `export const x = ${i}00;\n`);
       await sleep(SETTLE_MS);
 
       expect(batches.length).toBeGreaterThan(0);
       for (const abs of files) expect([...seen()]).toContain(abs);
-      // Not asserted as non-zero: the point is that the outcome above holds whether or not Bun drops
-      // events, so this suite keeps passing if the upstream defect is ever fixed. The counter is the
-      // signal for when the compensation can be removed.
+      // Not `> 0`: the suite must keep passing if Bun ever stops dropping events.
       expect(watcher.unreportedChanges).toBeGreaterThanOrEqual(0);
     },
     TEST_TIMEOUT_MS,
@@ -90,8 +74,6 @@ describe("HmrWatcher", () => {
       const source = await seed(root, "lib/a.ts");
       const { seen, batches } = await watch(root);
 
-      // What every build ends with: a burst under `.akan/`, which the classifier ignores. Before this
-      // was handled, the burst was the one path Bun reported and the save right after it was invisible.
       const artifactDir = path.join(root, ".akan", "artifact", "server");
       await mkdir(artifactDir, { recursive: true });
       for (let i = 0; i < 60; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(8192));
@@ -100,8 +82,6 @@ describe("HmrWatcher", () => {
       await sleep(SETTLE_MS);
 
       expect([...seen()]).toContain(source);
-      // Exactly one batch for one save. Bun does deliver a real event for some paths the scan has already
-      // emitted, and counting both produced a second generation and a second build for no change.
       expect(batches.filter((batch) => batch.files.includes(source))).toHaveLength(1);
     },
     TEST_TIMEOUT_MS,
@@ -119,7 +99,6 @@ describe("HmrWatcher", () => {
       for (let i = 0; i < 20; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(4096));
       await sleep(SETTLE_MS);
 
-      // The verification scan is triggered by ignored paths, so it must not invent work from them either.
       expect(batches).toEqual([]);
     },
     TEST_TIMEOUT_MS,
@@ -161,7 +140,7 @@ describe("HmrWatcher", () => {
     TEST_TIMEOUT_MS,
   );
 
-  test.skipIf(process.getuid?.() === 0)(
+  test.skipIf(process.getuid?.() === 0 || process.platform === "win32")(
     "warns at startup when part of the tree cannot be read",
     async () => {
       const root = await makeRoot();
@@ -176,12 +155,9 @@ describe("HmrWatcher", () => {
       });
       started.push(watcher);
       await watcher.start();
-      // Restored before asserting, not after: a failed assertion would otherwise leave a directory `rm`
-      // cannot traverse, and the leak would fail the *next* test instead of this one.
+      // Restored before asserting: a failed assertion would leave a directory `rm` cannot traverse.
       await chmod(path.dirname(hidden), 0o755);
 
-      // At startup rather than at the first save, because an unreadable root means edits under it never
-      // rebuild — waiting for a save to reveal that means waiting for the save that silently does nothing.
       expect(warnings).toHaveLength(1);
       expect(warnings[0]).toContain("will not rebuild");
       expect(warnings[0]).toContain("EACCES");