@akanjs/devkit 3.0.0-alpha.7 → 3.0.0-alpha.71

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";
@@ -391,6 +391,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 +442,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`,
       );
     }

package/frontendBuild/index.ts

@@ -9,6 +9,7 @@ export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
 export * from "./fontOptimizer";
+export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
 export * from "./hmrWatcher";
 export * from "./pagesBundleBuilder";

package/frontendBuild/routeClientBuilder.ts

@@ -4,7 +4,7 @@ import type { BaseBuildArtifact, ClientManifest, SsrManifest } from "akanjs/serv
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { toClientReferencePath } from "../transforms/rscUseClientTransform";
-import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import type { ClientBundleTarget, ClientEntryDiscovery } from "./clientBuildTypes";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
@@ -163,12 +163,11 @@ export class RouteClientBuilder {
   }
 
   async #buildSsrBundle(bootstrapEntries: BootstrapEntries) {
-    const externalOptions = RouteClientBuilder.resolveSsrClientExternalOptions(this.#command);
     return new ClientEntriesBundler({
       app: this.#app,
       entries: bootstrapEntries.buildEntries,
       plugins: [await createBarrelImportsPlugin(this.#app)],
-      ...externalOptions,
+      ...RouteClientBuilder.resolveSsrClientBundleOptions(this.#command),
       outputSubdir: "client-ssr",
       command: this.#command,
     }).bundle();
@@ -239,20 +238,28 @@ export class RouteClientBuilder {
     return { [Bun.resolveSync("akanjs/fetch", serverEntry)]: "akanjs/fetch" };
   }
 
-  static resolveSsrClientExternalOptions(command: "build" | "start"): {
+  /**
+   * `target: "bun"` is load-bearing: these chunks are `await import()`-ed by the SSR renderer, so a dependency
+   * resolved through its `browser` export condition can touch `document` at module scope and throw mid-render,
+   * degrading the whole document to client rendering. Bun's `conditions` only adds to the target's defaults —
+   * `browser` still wins — so the target itself has to say server.
+   */
+  static resolveSsrClientBundleOptions(command: "build" | "start"): {
+    target: ClientBundleTarget;
     external: readonly string[];
     externalSubpaths?: readonly string[];
     externalAliases?: Record<string, string>;
   } {
     if (command === "start") {
       return {
+        target: "bun",
         external: SSR_CLIENT_EXTERNALS,
         externalSubpaths: ["akanjs/fetch"],
         externalAliases: RouteClientBuilder.resolveSsrClientRuntimeAliases(),
       };
     }
 
-    return { external: SSR_CLIENT_ALIAS_EXTERNALS };
+    return { target: "bun", external: SSR_CLIENT_ALIAS_EXTERNALS };
   }
 
   static resolveAkanServerEntry(): string {

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -5,7 +5,7 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
 import type { App } from "../commandDecorators";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
-import { CssCompiler } from "./cssCompiler";
+import { CssCompiler, type ImportedStylesheet } from "./cssCompiler";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
@@ -77,6 +77,7 @@ export class SsrBaseArtifactBuilder {
       branches: [...akanConfig.branches],
       i18n: akanConfig.i18n,
       imageConfig: akanConfig.images,
+      web: akanConfig.web,
       deepLinkAssociations: Object.values(akanConfig.mobile.targets)
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({
@@ -110,7 +111,7 @@ export class SsrBaseArtifactBuilder {
     const ssrBundle = await new ClientEntriesBundler({
       app: this.#app,
       entries: [rscSegmentOutletEntry],
-      ...RouteClientBuilder.resolveSsrClientExternalOptions(this.#command),
+      ...RouteClientBuilder.resolveSsrClientBundleOptions(this.#command),
       outputSubdir: "client-ssr",
       command: this.#command,
     }).bundle();
@@ -192,7 +193,7 @@ export class SsrBaseArtifactBuilder {
         Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
           const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
           if (!cssText) return [];
-          return [this.#writeCssAsset(basePath, cssText)];
+          return [this.#writeCssAsset(basePath, cssText, cssCompiler.importedStylesheetsByBasePath[basePath] ?? [])];
         }),
       ),
     );
@@ -201,7 +202,7 @@ export class SsrBaseArtifactBuilder {
     return { cssCompiler, optimizedFonts, cssAssets };
   }
 
-  async #writeCssAsset(basePath: string, cssText: string) {
+  async #writeCssAsset(basePath: string, cssText: string, imported: ImportedStylesheet[]) {
     const cssAssetName = basePath || "root";
     const preparedCssText = await prepareCssAsset(this.#command, basePath, cssText);
     const cssHash = Bun.hash(`${basePath}\n${preparedCssText}`).toString(36);
@@ -210,7 +211,23 @@ export class SsrBaseArtifactBuilder {
       `/_akan/styles/${cssAssetName}-${cssHash}.css`,
     ];
     await Bun.write(path.join(this.#absArtifactDir, cssRelPath), preparedCssText);
+    SsrBaseArtifactBuilder.#warnDroppedImports(this.#app, cssRelPath, preparedCssText, imported);
     this.#app.verbose(`[base-artifact] wrote ${preparedCssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
     return [basePath, { cssUrl, cssRelPath }] as const;
   }
+
+  /**
+   * Checked against the file written here rather than against the compiled text, because this is the stylesheet
+   * `base-artifact.json` points at and therefore the only one an SSR render serves. A declaration can survive
+   * the compile and still be missing from the asset — a build that ships CSS to the CSR bundle and not to the
+   * server is indistinguishable, in the browser, from a theme that was never written.
+   */
+  static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
+    for (const { cssPath, declaredNames } of imported) {
+      if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;
+      app.logger.warn(
+        `[base-artifact] @import ${cssPath} declares ${declaredNames.length} custom propert${declaredNames.length === 1 ? "y" : "ies"} and none of them are in ${cssRelPath}`,
+      );
+    }
+  }
 }