@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.80

package/frontendBuild/fontPruner.test.ts

@@ -0,0 +1,220 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { FontPruner } from "./fontPruner";
+
+const tempRoots: string[] = [];
+
+interface Tree {
+  layout?: string;
+  publicFiles?: Record<string, string>;
+  artifactFiles?: Record<string, string>;
+  csrFiles?: Record<string, string>;
+}
+
+const write = async (root: string, files: Record<string, string>) => {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, content);
+  }
+};
+
+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 cwdPath = path.join(root, "apps/demo");
+  const distPath = path.join(root, "dist/apps/demo");
+  await mkdir(path.join(cwdPath, "page"), { recursive: true });
+  await writeFile(path.join(cwdPath, "page/_layout.tsx"), layout);
+  await write(path.join(distPath, "public"), publicFiles);
+  await write(path.join(distPath, ".akan/artifact"), artifactFiles);
+  await write(path.join(distPath, "csr"), csrFiles);
+  const app = {
+    cwdPath,
+    dist: { cwdPath: distPath },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => ["./_layout.tsx"],
+    getPageRoots: async () => [],
+    verbose: () => undefined,
+    logger: { info: () => undefined, warn: () => undefined },
+  } as unknown as App;
+  return { app, distPath };
+};
+
+const layoutWith = (extra = "") => `
+export const fonts = [
+  {
+    name: "pretendard",${extra}
+    paths: [{ src: "/libs/shared/fonts/Pretendard-Bold.woff2", weight: 700 }],
+  },
+];
+export default function Layout() {
+  return null;
+}
+`;
+
+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({
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x".repeat(2048) },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/Pretendard-Bold.woff2"]);
+    expect(result.freedBytes).toBe(2048);
+    expect(await exists(distPath, "libs/shared/fonts/Pretendard-Bold.woff2")).toBe(false);
+  });
+
+  test("drops a font no declaration and no surface mentions", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/NotoSansKR.ttf"]);
+    expect(await exists(distPath, "libs/shared/fonts/NotoSansKR.ttf")).toBe(false);
+  });
+
+  test("keeps a font a stylesheet in public loads by url", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: {
+        "libs/shared/fonts/Assistant-Bold.woff2": "x",
+        "libs/shared/excalidraw.css": '@font-face{src:url("/libs/shared/fonts/Assistant-Bold.woff2")}',
+      },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept).toEqual([
+      {
+        file: "libs/shared/fonts/Assistant-Bold.woff2",
+        bytes: 1,
+        reason: { kind: "referenced", referrer: "public/libs/shared/excalidraw.css" },
+      },
+    ]);
+    expect(await exists(distPath, "libs/shared/fonts/Assistant-Bold.woff2")).toBe(true);
+  });
+
+  test("keeps a font whose filename a referrer percent-encodes", async () => {
+    const { app } = await makeApp({
+      publicFiles: {
+        "fonts/Lemon Milk Pro Medium.otf": "x",
+        "brand.css": "@font-face{src:url(/fonts/Lemon%20Milk%20Pro%20Medium.otf)}",
+      },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "referenced", referrer: "public/brand.css" });
+  });
+
+  test("keeps the source of a font declared with optimize: false", async () => {
+    const { app, distPath } = await makeApp({
+      layout: layoutWith("\n    optimize: false,"),
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "unoptimized" });
+    expect(await exists(distPath, "libs/shared/fonts/Pretendard-Bold.woff2")).toBe(true);
+  });
+
+  test("keeps a font matched by an assets.keepFonts glob", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/Assistant-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app, { keepFonts: ["libs/shared/fonts/Assistant-*.woff2"] }).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "declared", glob: "libs/shared/fonts/Assistant-*.woff2" });
+    expect(await exists(distPath, "libs/shared/fonts/Assistant-Bold.woff2")).toBe(true);
+  });
+
+  test("ignores the declaration the build inlines into its own bundles", async () => {
+    const { app } = await makeApp({
+      artifactFiles: {
+        "server/pages-abc.js": 'const fonts=[{paths:[{src:"/libs/shared/fonts/Pretendard-Bold.woff2"}]}]',
+      },
+      csrFiles: { "index.html": '<script>src:"/libs/shared/fonts/Pretendard-Bold.woff2"</script>' },
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/Pretendard-Bold.woff2"]);
+  });
+
+  test("keeps a font a bundle loads that no declaration names", async () => {
+    const { app } = await makeApp({
+      artifactFiles: { "client/chunk-abc.js": 'new FontFace("x","url(/fonts/Runtime-Regular.woff2)")' },
+      publicFiles: { "fonts/Runtime-Regular.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "referenced", referrer: ".akan/artifact/client/chunk-abc.js" });
+  });
+
+  test("keeps a font the compiled stylesheet still points at", async () => {
+    const { app } = await makeApp({
+      artifactFiles: { "styles/root-abc.css": "@font-face{src:url(/libs/shared/fonts/Pretendard-Bold.woff2)}" },
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({
+      kind: "referenced",
+      referrer: ".akan/artifact/styles/root-abc.css",
+    });
+  });
+
+  test("leaves non-font assets alone", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "logo.png": "x", "video.mp4": "x", "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    await new FontPruner(app).prune();
+
+    expect(await exists(distPath, "logo.png")).toBe(true);
+    expect(await exists(distPath, "video.mp4")).toBe(true);
+    expect(await exists(distPath, "libs/shared/fonts/NotoSansKR.ttf")).toBe(false);
+  });
+
+  test("does nothing when the build shipped no public directory", async () => {
+    const { app } = await makeApp();
+    await rm(path.join(app.dist.cwdPath, "public"), { recursive: true, force: true });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result).toEqual({ removed: [], kept: [], freedBytes: 0 });
+  });
+
+  test("removes a directory the prune emptied", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    await new FontPruner(app).prune();
+
+    expect(await Bun.file(path.join(distPath, "public/libs/shared/fonts")).exists()).toBe(false);
+  });
+});

package/frontendBuild/fontPruner.ts

@@ -0,0 +1,206 @@
+import { rm, rmdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { isFontOptimizationEnabled } from "akanjs/client";
+import type { App } from "../commandDecorators";
+import { FontOptimizer } from "./fontOptimizer";
+
+const FONT_GLOB = "**/*.{woff2,woff,ttf,otf,ttc,eot}";
+const REFERRER_GLOB = "**/*.{css,js,mjs,cjs,json,html,htm,svg,xml,webmanifest}";
+
+export type FontKeepReason =
+  | { kind: "unoptimized" }
+  | { kind: "declared"; glob: string }
+  | { kind: "referenced"; referrer: string };
+
+export interface FontPruneResult {
+  removed: { file: string; bytes: number }[];
+  kept: { file: string; bytes: number; reason: FontKeepReason }[];
+  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.
+ */
+export class FontPruner {
+  #app: App;
+  #keepGlobs: string[];
+  #publicRoot: string;
+  #artifactRoot: string;
+
+  constructor(app: App, { keepFonts = [] }: { keepFonts?: string[] } = {}) {
+    this.#app = app;
+    this.#keepGlobs = keepFonts;
+    this.#publicRoot = path.join(app.dist.cwdPath, "public");
+    this.#artifactRoot = path.join(app.dist.cwdPath, ".akan/artifact");
+  }
+
+  async prune(): Promise<FontPruneResult> {
+    const empty: FontPruneResult = { removed: [], kept: [], freedBytes: 0 };
+    if (!(await this.#isDirectory(this.#publicRoot))) return empty;
+    const candidates = await this.#collectCandidates();
+    if (!candidates.length) return empty;
+
+    const fonts = await new FontOptimizer(this.#app, "build").discoverFonts();
+    const unoptimizedSrcs = new Set<string>();
+    const optimizedSrcs = new Set<string>();
+    for (const font of fonts) {
+      const target = isFontOptimizationEnabled(font) ? optimizedSrcs : unoptimizedSrcs;
+      for (const fontPath of font.paths) target.add(path.posix.basename(fontPath.src));
+    }
+
+    const result: FontPruneResult = { removed: [], kept: [], freedBytes: 0 };
+    const undecided: typeof candidates = [];
+    for (const candidate of candidates) {
+      const reason = this.#staticKeepReason(candidate, unoptimizedSrcs);
+      if (reason) result.kept.push({ file: candidate.rel, bytes: candidate.bytes, reason });
+      else undecided.push(candidate);
+    }
+    if (undecided.length) {
+      const referrers = await this.#findReferrers(undecided, optimizedSrcs);
+      for (const candidate of undecided) {
+        const referrer = referrers.get(candidate.rel);
+        if (referrer)
+          result.kept.push({ file: candidate.rel, bytes: candidate.bytes, reason: { kind: "referenced", referrer } });
+        else result.removed.push({ file: candidate.rel, bytes: candidate.bytes });
+      }
+    }
+
+    await this.#remove(result.removed.map(({ file }) => file));
+    result.freedBytes = result.removed.reduce((total, { bytes }) => total + bytes, 0);
+    this.#report(result);
+    return result;
+  }
+
+  #staticKeepReason(candidate: { rel: string; basename: string }, unoptimizedSrcs: Set<string>): FontKeepReason | null {
+    if (unoptimizedSrcs.has(candidate.basename)) return { kind: "unoptimized" };
+    for (const glob of this.#keepGlobs) {
+      if (new Bun.Glob(glob).match(candidate.rel)) return { kind: "declared", glob };
+    }
+    return null;
+  }
+
+  async #collectCandidates() {
+    const candidates: { rel: string; basename: string; bytes: number }[] = [];
+    for await (const rel of new Bun.Glob(FONT_GLOB).scan({ cwd: this.#publicRoot, dot: false })) {
+      const entry = await stat(path.join(this.#publicRoot, rel)).catch(() => null);
+      if (!entry?.isFile()) continue;
+      candidates.push({ rel: rel.split(path.sep).join("/"), basename: path.basename(rel), bytes: entry.size });
+    }
+    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.
+   */
+  async #findReferrers(
+    candidates: { rel: string; basename: string }[],
+    optimizedSrcs: Set<string>,
+  ): Promise<Map<string, string>> {
+    const referrers = new Map<string, string>();
+    const authoritative = candidates;
+    const bundled = candidates.filter((candidate) => !optimizedSrcs.has(candidate.basename));
+    const roots: { dir: string; label: string; needles: typeof candidates }[] = [
+      { dir: this.#publicRoot, label: "public", needles: authoritative },
+      { dir: path.join(this.#artifactRoot, "styles"), label: ".akan/artifact/styles", needles: authoritative },
+      { dir: path.join(this.#artifactRoot, "client"), label: ".akan/artifact/client", needles: bundled },
+      { dir: path.join(this.#artifactRoot, "client-ssr"), label: ".akan/artifact/client-ssr", needles: bundled },
+      { dir: path.join(this.#artifactRoot, "server"), label: ".akan/artifact/server", needles: bundled },
+      { dir: path.join(this.#app.dist.cwdPath, "csr"), label: "csr", needles: bundled },
+    ];
+    for (const root of roots) {
+      const pending = root.needles.filter((candidate) => !referrers.has(candidate.rel));
+      if (!pending.length || !(await this.#isDirectory(root.dir))) continue;
+      await this.#scanRoot(root, pending, referrers);
+    }
+    return referrers;
+  }
+
+  async #scanRoot(
+    root: { dir: string; label: string },
+    pending: { rel: string; basename: string }[],
+    referrers: Map<string, string>,
+  ) {
+    const needles = pending.map((candidate) => ({
+      rel: candidate.rel,
+      forms: [...new Set([candidate.basename, encodeURIComponent(candidate.basename)])],
+    }));
+    for await (const rel of new Bun.Glob(REFERRER_GLOB).scan({ cwd: root.dir, dot: false })) {
+      const remaining = needles.filter((needle) => !referrers.has(needle.rel));
+      if (!remaining.length) return;
+      const text = await Bun.file(path.join(root.dir, rel))
+        .text()
+        .catch(() => "");
+      if (!text) continue;
+      for (const needle of remaining) {
+        if (needle.forms.some((form) => text.includes(form)))
+          referrers.set(needle.rel, `${root.label}/${rel.split(path.sep).join("/")}`);
+      }
+    }
+  }
+
+  async #remove(files: string[]) {
+    await Promise.all(files.map((file) => rm(path.join(this.#publicRoot, file), { force: true })));
+    const dirs = [...new Set(files.map((file) => path.posix.dirname(file)))]
+      .filter((dir) => dir !== "." && dir !== "/")
+      .sort((a, b) => b.length - a.length);
+    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.
+   */
+  #report(result: FontPruneResult) {
+    if (!result.removed.length && !result.kept.length) return;
+    for (const { file, bytes } of result.removed)
+      this.#app.verbose(`[font-prune] dropped public/${file} (${FontPruner.formatBytes(bytes)})`);
+    for (const { file, reason } of result.kept)
+      this.#app.verbose(`[font-prune] kept public/${file} — ${FontPruner.describe(reason)}`);
+    const byReferrer = new Map<string, { files: number; bytes: number }>();
+    for (const { bytes, reason } of result.kept) {
+      if (reason.kind !== "referenced") continue;
+      const entry = byReferrer.get(reason.referrer) ?? { files: 0, bytes: 0 };
+      entry.files += 1;
+      entry.bytes += bytes;
+      byReferrer.set(reason.referrer, entry);
+    }
+    if (!byReferrer.size) return;
+    const ranked = [...byReferrer.entries()].sort(([, a], [, b]) => b.bytes - a.bytes);
+    const named = ranked
+      .slice(0, 3)
+      .map(([referrer, { files, bytes }]) => `${referrer} (${files}, ${FontPruner.formatBytes(bytes)})`);
+    const rest = ranked.length - named.length;
+    this.#app.logger.info(
+      `[font-prune] kept ${FontPruner.formatBytes(ranked.reduce((total, [, entry]) => total + entry.bytes, 0))} of fonts in public/ because these reference them: ${named.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}`,
+    );
+  }
+
+  static describe(reason: FontKeepReason) {
+    if (reason.kind === "unoptimized") return "declared with optimize: false, so the runtime CSS serves it";
+    if (reason.kind === "declared") return `kept by assets.keepFonts "${reason.glob}"`;
+    return `referenced by ${reason.referrer}`;
+  }
+
+  static formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+  }
+
+  async #isDirectory(dir: string) {
+    return await stat(dir).then(
+      (entry) => entry.isDirectory(),
+      () => false,
+    );
+  }
+}

package/frontendBuild/frontendBuild.test.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RoutesManifest } from "akanjs/server";
 import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
+import { CssCompiler, declaredCustomProperties, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
 import { DevChangePlanner } from "./devChangePlanner";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -54,10 +54,10 @@ describe("PagesEntrySourceGenerator", () => {
     );
   });
 
-  test("generates static import source for single-file CSR bundles", () => {
+  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 = PagesEntrySourceGenerator.generateStatic([
+    const source = await PagesEntrySourceGenerator.generateStatic([
       { key: "./_index.tsx", moduleAbsPath: indexAbs },
       { key: "./admin.tsx", moduleAbsPath: adminAbs },
     ]);
@@ -88,7 +88,7 @@ describe("PagesEntrySourceGenerator", () => {
     await write(expressionPath, "export default async () => null;");
     await write(namedExportPath, "async function NamedExport() { return null; }\nexport { NamedExport as default };");
 
-    const source = PagesEntrySourceGenerator.generateStatic([
+    const source = await PagesEntrySourceGenerator.generateStatic([
       { key: "./_index.tsx", moduleAbsPath: indexPath },
       { key: "./admin.tsx", moduleAbsPath: adminPath },
       { key: "./typed.tsx", moduleAbsPath: typedPath },
@@ -123,7 +123,7 @@ describe("PagesBundleBuilder", () => {
       outdir,
       target: "bun",
       format: "esm",
-      plugins: [PagesBundleBuilder.createServerCssStubPlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     expect(result.success).toBe(true);
@@ -178,15 +178,96 @@ describe("CsrArtifactBuilder", () => {
     expect(inlined).not.toContain("src=");
   });
 
-  test("creates inline stylesheet and strips external stylesheet links", () => {
-    const html =
-      '<head><link rel="stylesheet" href="/_akan/styles/akanjs.css" data-akan-css="active" /><link rel="stylesheet" href="./generated.css" /></head>';
-    const stripped = CsrArtifactBuilder.stripBundledStylesheetLinks(html);
+  test("creates inline stylesheet with the closing tag escaped", () => {
     const style = CsrArtifactBuilder.createInlineStyle("body::before{content:'</style>';}");
 
-    expect(stripped).toBe("<head></head>");
     expect(style).toBe("<style data-akan-css=\"active\">\nbody::before{content:'<\\/style>';}\n</style>");
   });
+
+  test("injects into the real head even when an inline bundle quotes body and head tags", () => {
+    const bundle = 'console.info("<body>", "</head>", "<!--");';
+    const html = [
+      "<!doctype html>",
+      "<html>",
+      "<head>",
+      `<script type="module">${bundle}</script>`,
+      "</head>",
+      '<body><div id="root"></div></body>',
+      "</html>",
+    ].join("\n");
+
+    const first = CsrArtifactBuilder.injectBeforeHeadEnd(html, "<style>a{}</style>");
+    const second = CsrArtifactBuilder.injectBeforeHeadEnd(first, "<style>b{}</style>");
+
+    expect(second.startsWith("<!doctype html>")).toBe(true);
+    expect(second.indexOf("<style>a{}</style>")).toBeGreaterThan(second.indexOf(bundle));
+    expect(second.indexOf("<style>b{}</style>")).toBeGreaterThan(second.indexOf("<style>a{}</style>"));
+    expect(second.indexOf("<style>b{}</style>")).toBeLessThan(second.indexOf("\n</head>"));
+  });
+
+  test("never prepends: without a head the snippet lands before body, else at the end", () => {
+    expect(CsrArtifactBuilder.injectBeforeHeadEnd("<html><body></body></html>", "<style></style>")).toBe(
+      "<html><style></style>\n<body></body></html>",
+    );
+    expect(CsrArtifactBuilder.injectBeforeHeadEnd("<div></div>", "<style></style>")).toBe(
+      "<div></div>\n<style></style>",
+    );
+  });
+
+  test("gives each basePath its own routes plus the routes outside every basePath", () => {
+    const entries = [
+      { key: "./_layout.tsx", moduleAbsPath: "/repo/page/_layout.tsx" },
+      { key: "./(sign)/signin.tsx", moduleAbsPath: "/repo/page/(sign)/signin.tsx" },
+      {
+        key: "./office/__root_layout.tsx",
+        moduleAbsPath: "/repo/.akan/generated/root-layouts/office__root_layout.tsx",
+      },
+      { key: "./office/_index.tsx", moduleAbsPath: "/repo/page/office/_index.tsx" },
+      {
+        key: "./(user)/soft/__root_layout.tsx",
+        moduleAbsPath: "/repo/.akan/generated/root-layouts/soft__root_layout.tsx",
+      },
+      { key: "./(user)/soft/home.tsx", moduleAbsPath: "/repo/page/(user)/soft/home.tsx" },
+    ];
+    const basePaths = ["office", "soft"];
+
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "office", basePaths).map((entry) => entry.key)).toEqual([
+      "./_layout.tsx",
+      "./(sign)/signin.tsx",
+      "./office/__root_layout.tsx",
+      "./office/_index.tsx",
+    ]);
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "soft", basePaths).map((entry) => entry.key)).toEqual([
+      "./_layout.tsx",
+      "./(sign)/signin.tsx",
+      "./(user)/soft/__root_layout.tsx",
+      "./(user)/soft/home.tsx",
+    ]);
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "", [])).toEqual(entries);
+  });
+
+  test("keeps route stylesheets out of the browser bundle so the HTML links no CSS", async () => {
+    const root = await makeTempRoot();
+    const htmlPath = path.join(root, "src/index.html");
+    await write(
+      htmlPath,
+      '<!doctype html><html><head></head><body><script type="module" src="./index.csr.tsx"></script></body></html>',
+    );
+    await write(path.join(root, "src/index.csr.tsx"), 'import "./styles.css";\nconsole.info("boot");\n');
+    await write(path.join(root, "src/styles.css"), ":root { --foreground: #fff; }\n");
+
+    const result = await Bun.build({
+      target: "browser",
+      entrypoints: [htmlPath],
+      root: path.join(root, "src"),
+      outdir: path.join(root, "out"),
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.outputs.some((output) => output.path.endsWith(".css"))).toBe(false);
+    expect(await readFile(path.join(root, "out/index.html"), "utf8")).not.toContain("stylesheet");
+  });
 });
 
 describe("SsrBaseArtifactBuilder", () => {
@@ -391,6 +472,20 @@ describe("CssImportResolver", () => {
     expect(await resolver.resolve("@libs/ui/missing", root)).toBeNull();
   });
 
+  test("never substitutes the package stylesheet for a subpath that does not exist", async () => {
+    const root = await makeTempRoot();
+    await write(
+      path.join(root, "node_modules/vendor/package.json"),
+      JSON.stringify({ name: "vendor", style: "index.css" }),
+    );
+    await write(path.join(root, "node_modules/vendor/index.css"), ".vendor {}\n");
+
+    const resolver = new CssImportResolver(root, {});
+
+    expect(await resolver.resolve("vendor", root)).toBe(path.join(root, "node_modules/vendor/index.css"));
+    expect(await resolver.resolve("vendor/ui/tokens.css", root)).toBeNull();
+  });
+
   test("resolves css from single-package Akan workspace subpaths", async () => {
     const root = await makeTempRoot();
     await write(path.join(root, "pkgs/akanjs/ui/styles.css"), "body {}\n");
@@ -428,4 +523,77 @@ describe("CssCompiler", () => {
 
     expect(css).toContain(".text-fuchsia-500");
   });
+
+  test("reads declarations that prove a stylesheet arrived, ignoring theme variables that may not", () => {
+    expect(declaredCustomProperties(":root { --kakao: #fee500; --naver: #1ec800; }")).toEqual(["--kakao", "--naver"]);
+    expect(declaredCustomProperties("@theme inline {\n  --color-brand: var(--brand);\n}\n")).toEqual([]);
+    expect(declaredCustomProperties("@theme { --color-x: initial; }\n:root { --brand: #111; }")).toEqual(["--brand"]);
+    expect(declaredCustomProperties(".a { color: var(--kakao); }")).toEqual([]);
+    expect(declaredCustomProperties(":root{--a:#111}\n@media (min-width:1px){:root{--a:#222;--b:#333}}")).toEqual([
+      "--a",
+      "--b",
+    ]);
+  });
+
+  test("fails loudly on a stylesheet import that resolves to nothing", async () => {
+    const root = await makeTempRoot();
+    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);
+
+    await expect(compiler.compileCss([cssPath], [])).rejects.toThrow(
+      /failed to resolve stylesheet import "\.\.\/\.\.\/\.\.\/libs\/shared\/ui\/tokens\.css"/,
+    );
+  });
+
+  test("reports every @import per base path so the written asset can be checked against it", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(path.join(appDir, "page/_index.tsx"), 'import "./styles.css";\nexport default () => null;\n');
+    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,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [], basePaths: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+    const cssByBasePath = await compiler.getCssByBasePath();
+
+    expect(cssByBasePath[""]).toContain("--kakao");
+    expect(compiler.importedStylesheetsByBasePath[""]).toEqual([
+      { cssPath: path.join(root, "libs/shared/ui/brand.css"), declaredNames: ["--kakao", "--naver"] },
+    ]);
+  });
+
+  test("compiles lib-owned tokens ahead of the app stylesheets that may override them", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import "./styles.css";\nimport { Card } from "@libs/shared/ui";\nexport default () => <Card />;\n',
+    );
+    await write(path.join(appDir, "page/styles.css"), ":root { --brand: #111111; }\n");
+    await write(path.join(root, "libs/shared/ui/index.ts"), "export const Card = () => null;\n");
+    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,
+      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/hmrWatcher.ts

@@ -209,7 +209,7 @@ export class HmrWatcher {
     // per-batch detail stays at verbose because a save-all trips this on every save.
     if (!this.#reportedCompensating) {
       this.#reportedCompensating = true;
-      this.#logger.info(
+      this.#logger.verbose(
         `[hmr] recovered ${unreported} change(s) that fs.watch did not report; Bun coalesces concurrent saves and drops all but one, so changes are resolved by mtime`,
       );
     }