@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.91

package/frontendBuild/cssCompiler.ts

@@ -17,6 +17,12 @@ interface CssDiscovery {
   sourcePaths: string[];
 }
 
+/** One `@import` target and the custom properties it declares, which is what proves it arrived downstream. */
+export interface ImportedStylesheet {
+  cssPath: string;
+  declaredNames: string[];
+}
+
 export class CssCompiler {
   #logger = new Logger("CssCompiler");
   #transpiler = new Bun.Transpiler({ loader: "tsx" });
@@ -46,6 +52,13 @@ export class CssCompiler {
   #fileExistsCache = new Map<string, Promise<boolean>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
+  /** Every stylesheet this compile reached, entry points and `@import` targets alike. */
+  #discoveredCssPaths = new Set<string>();
+  /**
+   * `@import` targets per base path, so whoever writes the asset can check the file it actually wrote — the
+   * compiled text and the written artifact are two different places a declaration can go missing.
+   */
+  importedStylesheetsByBasePath: Record<string, ImportedStylesheet[]> = {};
 
   #fileExists(absPath: string): Promise<boolean> {
     let cached = this.#fileExistsCache.get(absPath);
@@ -76,13 +89,20 @@ export class CssCompiler {
   }
   async getCss({ refresh }: { refresh?: boolean } = {}) {
     if (this.#cssText !== null && !refresh) return this.#cssText;
+    this.#discoveredCssPaths.clear();
+    this.importedStylesheetsByBasePath = {};
     const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh });
-    this.#cssText = await this.compileCss(cssPaths, sourcePaths);
+    const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+    this.#cssText = css;
+    this.importedStylesheetsByBasePath = { "": imported };
+    await this.#warnUnreachableStylesheets();
     return this.#cssText;
   }
 
   async getCssByBasePath({ refresh }: { refresh?: boolean } = {}): Promise<Record<string, string>> {
     if (this.#cssTextByBasePath !== null && !refresh) return this.#cssTextByBasePath;
+    this.#discoveredCssPaths.clear();
+    this.importedStylesheetsByBasePath = {};
     const akanConfig = await this.#app.getConfig({ refresh });
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
@@ -92,7 +112,8 @@ export class CssCompiler {
         if (rootPageKeys.length === 0) return ["", ""] as const;
         const started = Date.now();
         const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: rootPageKeys });
-        const css = await this.compileCss(cssPaths, sourcePaths);
+        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+        this.importedStylesheetsByBasePath[""] = imported;
         this.#logger.verbose(
           `css base=root paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
         );
@@ -103,7 +124,8 @@ export class CssCompiler {
         if (basePathPageKeys.length === 0) return [basePath, ""] as const;
         const started = Date.now();
         const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
-        const css = await this.compileCss(cssPaths, sourcePaths);
+        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+        this.importedStylesheetsByBasePath[basePath] = imported;
         this.#logger.verbose(
           `css base=${basePath} paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
         );
@@ -111,9 +133,26 @@ export class CssCompiler {
       }),
     ]);
     this.#cssTextByBasePath = Object.fromEntries(cssEntries);
+    await this.#warnUnreachableStylesheets();
     return this.#cssTextByBasePath;
   }
 
+  /**
+   * A stylesheet under `page/` reaches the build only by being imported from a route source. One that nothing
+   * imports compiles to nothing and reports success, which is indistinguishable from an empty theme — so say it
+   * out loud once per compile rather than leaving it to be noticed as unstyled elements in the browser.
+   */
+  async #warnUnreachableStylesheets() {
+    const pageDir = path.join(this.#app.cwdPath, "page");
+    const glob = new Bun.Glob("**/*.css");
+    for await (const cssPath of glob.scan({ cwd: pageDir, absolute: true })) {
+      // `(libs)` is a link farm: the same file is discovered under its real path in `libs/`, never this one.
+      if (cssPath.includes(`${path.sep}(libs)${path.sep}`)) continue;
+      if (this.#discoveredCssPaths.has(cssPath)) continue;
+      this.#logger.warn(`css ${path.relative(this.#app.cwdPath, cssPath)} is imported by no route and never compiled`);
+    }
+  }
+
   async discoverCss({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     const { cssPaths } = await this.discoverCssAndSources({ refresh });
     return cssPaths;
@@ -180,22 +219,61 @@ export class CssCompiler {
       }
     }
 
-    return { cssPaths: [...cssFiles], sourcePaths: [...sourceFiles] };
+    const tokenPaths = await this.#libTokenStylesheets(sourceFiles);
+    const cssPaths = [...new Set([...tokenPaths, ...cssFiles])];
+    for (const cssPath of cssPaths) this.#discoveredCssPaths.add(cssPath);
+    return { cssPaths, sourcePaths: [...sourceFiles] };
+  }
+
+  /**
+   * `libs/<lib>/ui/tokens.css` of every lib the page graph reached, so a lib can own the fixed colours its own
+   * components need instead of each consuming app re-declaring them. Ordered ahead of the app's stylesheets:
+   * the app is the last word on any variable both declare.
+   */
+  async #libTokenStylesheets(sourceFiles: Set<string>): Promise<string[]> {
+    const libsRoot = path.join(this.#app.workspace.workspaceRoot, "libs");
+    const libNames = new Set<string>();
+    for (const filePath of sourceFiles) {
+      const relPath = path.relative(libsRoot, filePath);
+      if (relPath.startsWith("..") || path.isAbsolute(relPath)) continue;
+      const [libName] = relPath.split(path.sep);
+      if (libName) libNames.add(libName);
+    }
+    const tokenPaths = await Promise.all(
+      [...libNames].sort().map(async (libName) => {
+        const tokensPath = path.join(libsRoot, libName, "ui/tokens.css");
+        return (await this.#fileExists(tokensPath)) ? tokensPath : null;
+      }),
+    );
+    return tokenPaths.filter((tokensPath): tokensPath is string => !!tokensPath);
   }
   async compileCss(cssPaths: string[], sourcePaths: string[]): Promise<string> {
-    if (cssPaths.length === 0) return "";
+    const { css } = await this.#compileWithImports(cssPaths, sourcePaths);
+    return css;
+  }
+
+  /**
+   * The collector is per compile rather than per compiler instance: `getCssByBasePath` compiles every base path
+   * concurrently, so instance state would mix one base path's imports into another's check.
+   */
+  async #compileWithImports(
+    cssPaths: string[],
+    sourcePaths: string[],
+  ): Promise<{ css: string; imported: ImportedStylesheet[] }> {
+    if (cssPaths.length === 0) return { css: "", imported: [] };
 
     const compileStarted = Date.now();
     const compilers = await Promise.all(
       cssPaths.map(async (cssPath) => {
         const css = await Bun.file(cssPath).text();
         const base = path.dirname(cssPath);
+        const imported = new Map<string, string>();
         const compiler = await compile(css, {
           base,
-          loadStylesheet: (id, fromBase) => this.#loadStylesheet(id, fromBase),
+          loadStylesheet: (id, fromBase) => this.#loadStylesheet(id, fromBase, imported),
           loadModule: (id, fromBase) => this.#loadModule(id, fromBase),
         });
-        return { cssPath, compiler };
+        return { cssPath, compiler, imported };
       }),
     );
 
@@ -210,24 +288,46 @@ export class CssCompiler {
       `css candidates scanned count=${candidates.length} sources=${sourcePaths.length} dirs=${sourceDirs.size} in ${Date.now() - scanStarted}ms`,
     );
     const parts: string[] = [];
+    const imported: ImportedStylesheet[] = [];
     for (const entry of compilers) {
       if (!entry) continue;
-      parts.push(entry.compiler.build(candidates));
+      const part = entry.compiler.build(candidates);
+      parts.push(part);
+      for (const [cssPath, content] of entry.imported) {
+        const declaredNames = declaredCustomProperties(content);
+        imported.push({ cssPath, declaredNames });
+        if (declaredNames.length === 0 || declaredNames.some((name) => part.includes(`${name}:`))) continue;
+        this.#logger.warn(
+          `css @import ${cssPath} was loaded by ${entry.cssPath} but none of its ${declaredNames.length} declaration(s) reached the compiled CSS`,
+        );
+      }
     }
     this.#logger.verbose(
       `css compiled paths=${cssPaths.length} candidates=${candidates.length} in ${Date.now() - compileStarted}ms`,
     );
-    return parts.join("\n");
+    return { css: parts.join("\n"), imported };
   }
 
-  async #loadStylesheet(id: string, fromBase: string) {
+  async #loadStylesheet(id: string, fromBase: string, imported?: Map<string, string>) {
     const p = await this.#resolveCssImport(id, fromBase);
+    this.#discoveredCssPaths.add(p);
     const content = await Bun.file(p).text();
+    imported?.set(p, content);
+    this.#logger.verbose(`css import "${id}" from ${fromBase} -> ${p} (${content.length} bytes)`);
     return { path: p, base: path.dirname(p), content };
   }
 
+  /**
+   * Every specifier is verified here, path-shaped ones included. An `@import` the pipeline cannot resolve is
+   * a build error and never a no-op: the vocabulary closure means a component whose token declaration failed
+   * to load renders unstyled, which nothing downstream can distinguish from a design choice.
+   */
   async #resolveCssImport(id: string, fromBase: string): Promise<string> {
-    if (id.startsWith(".") || id.startsWith("/")) return path.resolve(fromBase, id);
+    if (id.startsWith(".") || id.startsWith("/")) {
+      const filePath = path.resolve(fromBase, id);
+      if (await this.#fileExists(filePath)) return filePath;
+      throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase} (no file at ${filePath})`);
+    }
     const resolver = await this.#getCssImportResolver();
     const resolved = await resolver.resolve(id, fromBase);
     if (resolved) return resolved;
@@ -330,7 +430,18 @@ export function isIgnoredNodeModuleSource(filePath: string): boolean {
   return NODE_MODULES_RE.test(filePath) && !AKANJS_NODE_MODULE_RE.test(filePath);
 }
 
-function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
+/**
+ * `@theme` blocks are stripped first: those variables are emitted only when a utility uses one, so their
+ * absence from a build says nothing about whether the stylesheet arrived.
+ */
+export function declaredCustomProperties(css: string): string[] {
+  const withoutThemeBlocks = css.replace(/@theme[^{]*\{[^}]*\}/g, "");
+  return [...new Set([...withoutThemeBlocks.matchAll(/(?:^|[\s;{])(--[\w-]+)\s*:/g)].map(([, name]) => name))].filter(
+    (name): name is string => !!name,
+  );
+}
+
+export function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
   const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
   const segments = normalized.split("/");
   const firstPublicSegment = segments.find((segment) => segment !== "[lang]" && !/^\(.+\)$/.test(segment));

package/frontendBuild/cssImportResolver.ts

@@ -106,14 +106,15 @@ export class CssImportResolver {
       const pkg = await Bun.file(pkgPath).json();
       const subpath = id === pkgName ? "." : `.${id.slice(pkgName.length)}`;
       const exportValue = pkg.exports?.[subpath];
-      const styleEntry =
-        (typeof exportValue === "string"
+      const exportedEntry =
+        typeof exportValue === "string"
           ? exportValue
-          : exportValue?.style || exportValue?.import || exportValue?.default) ||
-        pkg.exports?.["."]?.style ||
-        pkg.style ||
-        "index.css";
-      return await this.#firstExisting(path.resolve(pkgDir, styleEntry));
+          : exportValue?.style || exportValue?.import || exportValue?.default;
+      if (exportedEntry) return await this.#firstExisting(path.resolve(pkgDir, exportedEntry));
+      //* A subpath names a file inside the package, so it resolves literally. Falling back to the package's own
+      //* style entry here would load a different stylesheet than the author asked for and report success.
+      if (subpath !== ".") return await this.#firstExisting(path.resolve(pkgDir, subpath));
+      return await this.#firstExisting(path.resolve(pkgDir, pkg.exports?.["."]?.style || pkg.style || "index.css"));
     } catch {
       return null;
     }

package/frontendBuild/devGeneratedIndexSync.ts

@@ -1,5 +1,6 @@
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { FileSys } from "../fileSys";
 
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
@@ -101,7 +102,7 @@ export class DevGeneratedIndexSync {
     const current = await readFile(indexPath, "utf8").catch(() => null);
     if (current === content) return false;
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, content);
+    await FileSys.writeTextAtomic(indexPath, content);
     return true;
   }
 

package/frontendBuild/fontOptimizer.ts

@@ -43,7 +43,9 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
-  static readonly #cacheVersion = 1;
+  // 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") {
     this.#app = app;
@@ -96,9 +98,18 @@ export class FontOptimizer {
       }
       // `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.#hashFontConfig(await this.#collectAutoSubsetText()) });
+        sources.push({ autoSubsetText: this.#cacheDigest(await this.#collectAutoSubsetText()) });
     }
-    return this.#hashFontConfig({ version: FontOptimizer.#cacheVersion, fonts, sources });
+    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.
+   */
+  #cacheDigest(value: unknown) {
+    return new Bun.CryptoHasher("sha256").update(this.#stableStringify(value)).digest("hex");
   }
 
   async #fileStamp(filePath: string): Promise<{ mtimeMs: number; size: number } | null> {
@@ -387,26 +398,34 @@ export class FontOptimizer {
     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.
+   */
   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);
-    const roots = [...["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
+    const roots = [...["page", "ui", "lib"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
     const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,html,md}");
     const parts: string[] = [];
-    await Promise.all(
-      roots.map(async (root) => {
-        if (
-          !(await stat(root).then(
-            (entry) => entry.isDirectory(),
-            () => false,
-          ))
-        )
-          return;
-        for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
-          parts.push(await Bun.file(filePath).text());
-        }
-      }),
-    );
+    for (const root of [...new Set(roots)].sort()) {
+      const isDir = await stat(root).then(
+        (entry) => entry.isDirectory(),
+        () => false,
+      );
+      if (!isDir) continue;
+      const filePaths: string[] = [];
+      for await (const filePath of glob.scan({ cwd: root, absolute: true })) filePaths.push(filePath);
+      for (const filePath of filePaths.sort()) parts.push(await Bun.file(filePath).text());
+    }
     return parts.join("");
   }
 

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);
+  });
+});