@akanjs/devkit 1.0.20 → 2.1.0-rc.1

package/frontendBuild/fontOptimizer.ts

@@ -0,0 +1,427 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type {
+  ReactFont,
+  ReactFontDeclaration,
+  ReactFontFace,
+  ReactFontPath,
+  ReactFontStyle,
+  ReactFontSubset,
+} from "akanjs/client";
+import {
+  type FontCategory,
+  generateFontFace,
+  getMetricsForFamily,
+  readMetrics,
+  resolveCategoryFallbacks,
+} from "fontaine";
+import { createFont, woff2 } from "fonteditor-core";
+import subsetFont from "subset-font";
+import ts from "typescript";
+import type { App } from "../commandDecorators";
+
+const FONT_URL_PREFIX = "/_akan/fonts";
+const DEFAULT_FONT_SUBSETS: ReactFontSubset[] = ["latin"];
+
+export interface OptimizeAppFontsResult {
+  css: string;
+  fonts: ReactFont[];
+  files: string[];
+}
+
+export type FontOptimizerCommand = "build" | "start";
+
+export class FontOptimizer {
+  #app: App;
+  #command: FontOptimizerCommand;
+  #artifactRoot: string;
+  #files: string[] = [];
+  #cssParts: string[] = [];
+  #woff2Ready: Promise<void> | null = null;
+
+  static #ksX1001Text: string | null = null;
+
+  constructor(app: App, command: FontOptimizerCommand = "start") {
+    this.#app = app;
+    this.#command = command;
+    this.#artifactRoot = path.join(command === "build" ? app.dist.cwdPath : app.cwdPath, ".akan/artifact");
+  }
+
+  async optimize(): Promise<OptimizeAppFontsResult> {
+    const fonts = await this.discoverFonts();
+    for (const font of fonts) {
+      if (!this.#isFontOptimizationEnabled(font)) continue;
+      await this.#optimizeFont(font);
+    }
+    const fontUtilityCss = this.#buildFontUtilityRules(fonts);
+    if (fontUtilityCss) this.#cssParts.push(fontUtilityCss);
+    return { css: this.#cssParts.join("\n"), fonts, files: this.#files };
+  }
+
+  async discoverFonts(): Promise<ReactFont[]> {
+    const pageKeys = await this.#app.getPageKeys();
+    const fonts: ReactFont[] = [];
+    await Promise.all(
+      pageKeys.map(async (key) => {
+        const filePath = path.resolve(this.#app.cwdPath, "page", key);
+        const file = Bun.file(filePath);
+        if (!(await file.exists())) return;
+        fonts.push(...this.#extractFontsExport(await file.text(), filePath));
+      }),
+    );
+    return this.#dedupeFonts(fonts);
+  }
+
+  async #optimizeFont(font: ReactFont) {
+    const faceCss: string[] = [];
+    for (const face of this.#getFontFaces(font)) {
+      const sourcePath = await this.#resolveFontSourcePath(face.src);
+      if (!sourcePath) {
+        this.#app.logger.warn(`[font] source not found: ${face.src}`);
+        continue;
+      }
+
+      const outputPath = path.join(this.#artifactRoot, face.optimizedSrc.replace(/^\/_akan\//, ""));
+      await mkdir(path.dirname(outputPath), { recursive: true });
+
+      const sourceBuffer = Buffer.from(await Bun.file(sourcePath).arrayBuffer());
+      const outputBuffer =
+        font.subset === false
+          ? await this.#convertToWoff2(sourceBuffer, sourcePath)
+          : await subsetFont(sourceBuffer, await this.#getSubsetText(font), { targetFormat: "woff2" });
+      await Bun.write(outputPath, outputBuffer);
+      this.#files.push(outputPath);
+
+      faceCss.push(this.#buildOptimizedFontFaceRule(font, face));
+      const fallbackCss = await this.#buildFontaineFallbackCss(font, face, outputPath);
+      if (fallbackCss) faceCss.push(fallbackCss);
+    }
+
+    if (faceCss.length > 0) this.#cssParts.push(...faceCss, this.#buildRootVariableRule(font));
+  }
+
+  #extractFontsExport(source: string, filePath: string): ReactFont[] {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const fonts: ReactFont[] = [];
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+      const isExported = modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+      if (!isExported) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "fonts") continue;
+        const value = declaration.initializer ? this.#literalToValue(declaration.initializer) : null;
+        if (Array.isArray(value)) {
+          fonts.push(...(value as ReactFont[]).map((font) => this.#withFontDefaults(font)));
+        }
+      }
+    }
+    return fonts;
+  }
+
+  #literalToValue(node: ts.Node): unknown {
+    if (ts.isStringLiteralLike(node)) return node.text;
+    if (ts.isNumericLiteral(node)) return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (ts.isArrayLiteralExpression(node)) return node.elements.map((element) => this.#literalToValue(element));
+    if (ts.isObjectLiteralExpression(node)) {
+      const obj: Record<string, unknown> = {};
+      for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const name = this.#getPropertyName(prop.name);
+        if (!name) continue;
+        obj[name] = this.#literalToValue(prop.initializer);
+      }
+      return obj;
+    }
+    if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node)) {
+      return this.#literalToValue(node.expression);
+    }
+    return undefined;
+  }
+
+  #getPropertyName(name: ts.PropertyName): string | null {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+    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;
+  }
+
+  #getFontVariableName(font: ReactFont) {
+    return font.variable ?? `--font-${font.name}`;
+  }
+
+  #getFontFallbackName(font: ReactFont) {
+    return font.fallbackName ?? `${font.name} fallback`;
+  }
+
+  #isFontOptimizationEnabled(font: ReactFont) {
+    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));
+    return font.paths
+      .map((fontPath) => {
+        const style = fontPath.style ?? "normal";
+        return {
+          font,
+          path: fontPath,
+          src: fontPath.src,
+          weight: fontPath.weight,
+          style,
+          optimizedSrc: this.#getOptimizedFontSrc(font, fontPath),
+        };
+      })
+      .filter((face) => enabledStyles.has(face.style));
+  }
+
+  #getOptimizedFontSrc(font: ReactFont, fontPath: ReactFontPath) {
+    const style = fontPath.style ?? "normal";
+    const hash = this.#hashFontConfig({
+      name: font.name,
+      src: fontPath.src,
+      weight: fontPath.weight,
+      style,
+      display: font.display,
+      subset: font.subset,
+      subsets: this.#getFontSubsets(font),
+      subsetText: font.subsetText,
+      subsetFiles: font.subsetFiles,
+      declarations: [...(font.declarations ?? []), ...(fontPath.declarations ?? [])],
+    });
+    return `${FONT_URL_PREFIX}/${this.#slugFontPart(font.name)}-${this.#slugFontPart(String(fontPath.weight))}-${style}-${hash}.woff2`;
+  }
+
+  #hashFontConfig(value: unknown) {
+    const input = this.#stableStringify(value);
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+      hash ^= input.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+  }
+
+  #stableStringify(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map((item) => this.#stableStringify(item)).join(",")}]`;
+    if (value && typeof value === "object") {
+      const entries = Object.entries(value as Record<string, unknown>)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b));
+      return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${this.#stableStringify(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+  }
+
+  #slugFontPart(value: string) {
+    return (
+      value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "font"
+    );
+  }
+
+  async #resolveFontSourcePath(src: string) {
+    if (!src.startsWith("/")) return null;
+    const rel = src.replace(/^\//, "");
+    const candidates = [
+      this.#command === "build" ? path.join(this.#app.dist.cwdPath, "public", rel) : null,
+      path.join(this.#app.cwdPath, "public", rel),
+      this.#resolveWorkspacePublicPath(rel),
+    ].filter(Boolean) as string[];
+    for (const candidate of candidates) {
+      if (await Bun.file(candidate).exists()) return candidate;
+    }
+    return null;
+  }
+
+  async #convertToWoff2(buffer: Buffer, sourcePath: string) {
+    await this.#initWoff2();
+    const font = createFont(buffer, { type: this.#getFontType(sourcePath, buffer) });
+    return font.write({ type: "woff2", toBuffer: true });
+  }
+
+  async #initWoff2() {
+    this.#woff2Ready ??= woff2.init().then(() => undefined);
+    return this.#woff2Ready;
+  }
+
+  #getFontType(sourcePath: string, buffer: Buffer) {
+    const signature = buffer.toString("ascii", 0, 4);
+    if (signature === "wOFF") return "woff";
+    if (signature === "wOF2") return "woff2";
+    if (signature === "OTTO") return "otf";
+    const ext = path.extname(sourcePath).slice(1).toLowerCase();
+    if (ext === "otf" || ext === "woff" || ext === "woff2") return ext;
+    return "ttf";
+  }
+
+  #resolveWorkspacePublicPath(rel: string) {
+    const [root, dep, ...rest] = rel.split("/");
+    if (root !== "libs" || !dep || rest.length === 0) return null;
+    return path.join(this.#app.workspace.workspaceRoot, "libs", dep, "public", ...rest);
+  }
+
+  async #getSubsetText(font: ReactFont) {
+    const parts = new Set<string>();
+    const subsets = this.#getFontSubsets(font);
+    for (const subset of subsets) parts.add(await this.#getSubsetPresetText(subset));
+    if (font.subsetText) parts.add(font.subsetText);
+    for (const filePath of font.subsetFiles ?? []) {
+      const abs = path.isAbsolute(filePath) ? filePath : path.join(this.#app.cwdPath, filePath);
+      const file = Bun.file(abs);
+      if (await file.exists()) parts.add(await file.text());
+    }
+    return [...parts].join("");
+  }
+
+  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 === "ks-x-1001") return FontOptimizer.#getKsX1001Text();
+    if (subset === "auto") return this.#collectAutoSubsetText();
+    return "";
+  }
+
+  async #collectAutoSubsetText() {
+    const roots = ["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir));
+    const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,html,md}");
+    const parts: string[] = [];
+    await Promise.all(
+      roots.map(async (root) => {
+        if (!(await Bun.file(root).exists())) return;
+        for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
+          parts.push(await Bun.file(filePath).text());
+        }
+      }),
+    );
+    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 {
+      const decoder = new TextDecoder("euc-kr");
+      const chars = new Set<string>();
+      for (let lead = 0xa1; lead <= 0xfe; lead++) {
+        for (let trail = 0xa1; trail <= 0xfe; trail++) {
+          const char = decoder.decode(Uint8Array.of(lead, trail));
+          if (char && char !== "\uFFFD") chars.add(char);
+        }
+      }
+      FontOptimizer.#ksX1001Text = [...chars].join("");
+    } catch {
+      FontOptimizer.#ksX1001Text = FontOptimizer.#rangeTextStatic(0xac00, 0xd7a3);
+    }
+    return FontOptimizer.#ksX1001Text;
+  }
+
+  static #rangeTextStatic(start: number, end: number) {
+    let text = "";
+    for (let code = start; code <= end; code++) text += String.fromCodePoint(code);
+    return text;
+  }
+
+  #buildOptimizedFontFaceRule(font: ReactFont, face: ReactFontFace) {
+    const declarations = [
+      ["font-family", this.#quote(font.name)],
+      ["src", `url(${this.#quote(face.optimizedSrc)}) format("woff2")`],
+      ["font-weight", String(face.weight)],
+      ["font-style", face.style],
+      ["font-display", font.display ?? "swap"],
+      ...this.#toDeclarationEntries(font.declarations),
+      ...this.#toDeclarationEntries(face.path.declarations),
+    ];
+    return `@font-face {\n${declarations.map(([prop, value]) => `  ${prop}: ${value};`).join("\n")}\n}`;
+  }
+
+  async #buildFontaineFallbackCss(font: ReactFont, face: ReactFontFace, outputPath: string) {
+    if (font.adjustFontFallback === false) return "";
+    const metrics = await readMetrics(outputPath).catch(() => null);
+    if (!metrics) return "";
+    const fallbacks = resolveCategoryFallbacks({
+      fontFamily: font.name,
+      fallbacks: font.fallbacks ?? {},
+      metrics: { ...metrics, category: font.category },
+    });
+    const css: string[] = [];
+    for (let i = fallbacks.length - 1; i >= 0; i--) {
+      const fallback = fallbacks[i];
+      const fallbackMetrics = await getMetricsForFamily(fallback);
+      if (!fallbackMetrics) continue;
+      css.push(
+        generateFontFace(
+          { ...metrics, category: font.category as FontCategory | undefined },
+          {
+            name: this.#getFontFallbackName(font),
+            font: fallback,
+            metrics: fallbackMetrics,
+            "font-weight": String(face.weight),
+            "font-style": face.style,
+          },
+        ),
+      );
+    }
+    return css.join("");
+  }
+
+  #buildRootVariableRule(font: ReactFont) {
+    return `:root { ${this.#getFontVariableName(font)}: ${this.#quote(font.name)}, ${this.#quote(
+      this.#getFontFallbackName(font),
+    )}; }`;
+  }
+
+  #buildFontUtilityRules(fonts: ReactFont[]) {
+    const rules: string[] = [];
+    const seen = new Set<string>();
+    for (const font of fonts) {
+      const className = font.className || `font-${font.name}`;
+      const selector = `.${this.#escapeCssClassName(className)}`;
+      const rule = `${selector} { font-family: var(${this.#getFontVariableName(font)}); }`;
+      if (seen.has(rule)) continue;
+      seen.add(rule);
+      rules.push(rule);
+    }
+    return rules.join("\n");
+  }
+
+  #escapeCssClassName(value: string) {
+    return value.replace(/^-?\d|[^a-zA-Z0-9_-]/g, (part) =>
+      [...part].map((char) => `\\${char.codePointAt(0)?.toString(16)} `).join(""),
+    );
+  }
+
+  #toDeclarationEntries(declarations: ReactFontDeclaration[] = []) {
+    return declarations.map((declaration) => [declaration.prop, declaration.value] as const);
+  }
+
+  #quote(value: string) {
+    return JSON.stringify(value);
+  }
+}

package/frontendBuild/frontendBuild.test.ts

@@ -0,0 +1,204 @@
+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 { fileURLToPath } from "node:url";
+import type { RoutesManifest } from "akanjs/server";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
+import { CssImportResolver } from "./cssImportResolver";
+import { HmrChangeClassifier } from "./hmrChangeClassifier";
+import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
+
+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 })));
+});
+
+describe("PagesEntrySourceGenerator", () => {
+  test("generates dynamic import source using absolute module paths", () => {
+    const source = PagesEntrySourceGenerator.generate([
+      { key: "./_index.tsx", moduleAbsPath: "/repo/apps/demo/page/_index.tsx" },
+      { key: "./admin.tsx", moduleAbsPath: "/repo/apps/demo/page/admin.tsx" },
+    ]);
+
+    expect(source).toBe(
+      [
+        "export const pages = {",
+        '  "./_index.tsx": () => import("/repo/apps/demo/page/_index.tsx"),',
+        '  "./admin.tsx": () => import("/repo/apps/demo/page/admin.tsx"),',
+        "};",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("generates static import source for single-file CSR bundles", () => {
+    const source = PagesEntrySourceGenerator.generateStatic([
+      { key: "./_index.tsx", moduleAbsPath: "/repo/apps/demo/page/_index.tsx" },
+      { key: "./admin.tsx", moduleAbsPath: "/repo/apps/demo/page/admin.tsx" },
+    ]);
+
+    expect(source).toBe(
+      [
+        'import * as page0 from "/repo/apps/demo/page/_index.tsx";',
+        'import * as page1 from "/repo/apps/demo/page/admin.tsx";',
+        "export const pages = {",
+        '  "./_index.tsx": async () => page0,',
+        '  "./admin.tsx": async () => page1,',
+        "};",
+        "",
+      ].join("\n"),
+    );
+  });
+});
+
+describe("CsrArtifactBuilder", () => {
+  test("replaces module script src with inline script", async () => {
+    const html = [
+      "<html>",
+      "<head></head>",
+      "<body>",
+      '<script type="module" crossorigin src="./chunk.js"></script>',
+      "</body>",
+      "</html>",
+    ].join("\n");
+
+    const inlined = await CsrArtifactBuilder.replaceModuleScriptSrc(html, (src) => {
+      expect(src).toBe("./chunk.js");
+      return 'console.log("</script>");';
+    });
+
+    expect(inlined).toContain('<script type="module">\nconsole.log("<\\/script>");\n</script>');
+    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);
+    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>");
+  });
+});
+
+describe("RoutesManifestArtifactSerializer", () => {
+  test("serializes absolute artifact paths relative to artifact directory", () => {
+    const manifest = {
+      knownEntries: ["/repo/dist/apps/demo/.akan/artifact/pages.js", "already-relative.js"],
+      clientManifest: {
+        "/repo/dist/apps/demo/.akan/artifact/client.js": { file: "client.js" },
+      },
+      ssrManifest: {
+        moduleMap: {
+          "/entry": {
+            default: {
+              id: "/repo/dist/apps/demo/.akan/artifact/server/page.js",
+              chunks: ["/repo/dist/apps/demo/.akan/artifact/chunks/a.js", "chunks/b.js"],
+              name: "default",
+            },
+          },
+        },
+      },
+    } as unknown as RoutesManifest;
+
+    const serialized = RoutesManifestArtifactSerializer.serialize(manifest, "/repo/dist/apps/demo/.akan/artifact");
+    expect(serialized.knownEntries).toEqual(["pages.js", "already-relative.js"]);
+    expect(Object.keys(serialized.clientManifest)).toEqual(["client.js"]);
+    expect(serialized.ssrManifest.moduleMap["/entry"]?.default?.id).toBe("server/page.js");
+    expect(serialized.ssrManifest.moduleMap["/entry"]?.default?.chunks).toEqual(["chunks/a.js", "chunks/b.js"]);
+
+    const production = RoutesManifestArtifactSerializer.serialize(manifest, "/repo/dist/apps/demo/.akan/artifact", {
+      production: true,
+    });
+    expect(production.knownEntries).toBeUndefined();
+  });
+});
+
+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");
+  });
+});
+
+describe("CssImportResolver", () => {
+  test("identifies package names and css files", () => {
+    expect(CssImportResolver.getPackageName("@scope/pkg/button")).toBe("@scope/pkg");
+    expect(CssImportResolver.getPackageName("plain-package/styles")).toBe("plain-package");
+    expect(CssImportResolver.getPackageName("@broken")).toBeNull();
+    expect(CssImportResolver.isCssFile("/repo/style.css")).toBe(true);
+    expect(CssImportResolver.isCssFile("/repo/style.scss")).toBe(false);
+  });
+
+  test("resolves css from exact and wildcard tsconfig paths", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "styles/global.css"), "body {}\n");
+    await write(path.join(root, "libs/ui/button/styles.css"), ".button {}\n");
+
+    const resolver = new CssImportResolver(root, {
+      "@styles/global": ["styles/global"],
+      "@libs/ui/*": ["libs/ui/*"],
+    });
+
+    expect(await resolver.resolve("@styles/global", root)).toBe(path.join(root, "styles/global.css"));
+    expect(await resolver.resolve("@libs/ui/button", root)).toBe(path.join(root, "libs/ui/button/styles.css"));
+    expect(await resolver.resolve("@libs/ui/missing", 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");
+
+    const resolver = new CssImportResolver(root, {
+      "akanjs/ui/*": ["pkgs/akanjs/ui/*"],
+    });
+
+    expect(await resolver.resolve("akanjs/ui/styles.css", root)).toBe(path.join(root, "pkgs/akanjs/ui/styles.css"));
+  });
+});
+
+describe("CssCompiler", () => {
+  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);
+  });
+
+  test("includes Tailwind candidates from installed akanjs ui sources", async () => {
+    const root = await makeTempRoot();
+    const cssPath = path.join(root, "node_modules/akanjs/ui/styles.css");
+    const uiSource = path.join(root, "node_modules/akanjs/ui/Button.tsx");
+    const tailwindCssPath = fileURLToPath(await import.meta.resolve("tailwindcss/index.css"));
+    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 },
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+    const css = await compiler.compileCss([cssPath], []);
+
+    expect(css).toContain(".text-fuchsia-500");
+  });
+});

package/frontendBuild/hmrChangeClassifier.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import type { ChangeKind } from "akanjs/server";
+
+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"]);
+
+export class HmrChangeClassifier {
+  classify(abs: string): ChangeKind {
+    if (this.#isUninteresting(abs)) return "ignore";
+    const base = path.basename(abs);
+    if (CONFIG_BASENAMES.has(base)) return "config";
+    const ext = path.extname(abs).toLowerCase();
+    if (CSS_EXTS.has(ext)) return "css";
+    if (SOURCE_EXTS.has(ext)) return "code";
+    return "ignore";
+  }
+
+  #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.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;
+    return false;
+  }
+}