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

package/frontendBuild/csrArtifactBuilder.ts

@@ -1,14 +1,18 @@
 import { mkdir, rm, unlink } from "node:fs/promises";
 import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
-import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { getPageKeyBasePath } from "./cssCompiler";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
 export interface BuildCsrArtifactResult {
   outputDir: string;
 }
 
+type CssAsset = NonNullable<BaseBuildArtifact["cssAssets"]>[string];
+
 export class CsrArtifactBuilder {
   #app: App;
   #command: "build" | "start";
@@ -29,31 +33,39 @@ export class CsrArtifactBuilder {
 
     const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
     const akanConfig = await this.#app.getConfig();
-    const artifact = await this.#loadCsrArtifact();
-    const csrBasePaths = [...akanConfig.basePaths];
-    const htmlEntries = csrBasePaths.length > 0 ? csrBasePaths : ["index"];
+    const cssAssets = await this.#loadCssAssets();
+    const basePaths = [...akanConfig.basePaths];
+    const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
     await rm(this.#outputDir, { recursive: true, force: true });
-    await mkdir(path.join(this.#app.cwdPath, ".akan/generated/csr"), { recursive: true });
-    const generatedHtmlFiles = Object.fromEntries(htmlEntries.map((basePath) => this.#createHtmlFile(basePath)));
+    await mkdir(this.#generatedDir, { recursive: true });
+    const generatedFiles = Object.fromEntries(
+      (
+        await Promise.all(
+          htmlBasePaths.map(async (basePath) => [
+            this.#createHtmlFile(basePath),
+            await this.#createEntryFile(
+              basePath,
+              CsrArtifactBuilder.pageEntriesForBasePath(pageEntries, basePath, basePaths),
+            ),
+          ]),
+        )
+      ).flat(),
+    );
 
     const result = await Bun.build({
       target: "browser",
-      entrypoints: Object.keys(generatedHtmlFiles),
-      files: {
-        ...generatedHtmlFiles,
-        [`${this.#app.cwdPath}/.akan/generated/csr/csr.tsx`]: `
-import { bootCsr } from "akanjs/webkit";
-${PagesEntrySourceGenerator.generateStatic(pageEntries)}
-void bootCsr(pages);
-  `,
-      },
-      root: `${this.#app.cwdPath}/.akan/generated/csr`,
+      entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
+      files: generatedFiles,
+      root: this.#generatedDir,
       outdir: this.#outputDir,
       splitting: false,
       minify: true,
       env: "AKAN_PUBLIC_*",
       define: this.#define(),
       optimizeImports: akanConfig.optimizeImports,
+      // The base artifact's compiled sheet is the only stylesheet, as it is for SSR: a raw `.css` reached through
+      // the route graph is Tailwind source, and every root layout stylesheet in the graph would land in every HTML.
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     if (!result.success) {
@@ -61,11 +73,32 @@ void bootCsr(pages);
       throw new Error(`[csr-build] failed${logs ? `\n${logs}` : ""}`);
     }
 
-    await this.#inlineCsrArtifacts(artifact.cssAssets ?? {});
+    await this.#inlineCsrArtifacts(cssAssets);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
 
+  /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
+  static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
+    return pageEntries.filter((entry) => {
+      const entryBasePath = getPageKeyBasePath(entry.key, basePaths);
+      return entryBasePath === null || entryBasePath === basePath;
+    });
+  }
+
+  static htmlFilename(basePath: string): string {
+    return `${basePath || "index"}.html`;
+  }
+
+  static entryFilename(basePath: string): string {
+    return `${basePath || "index"}.csr.tsx`;
+  }
+
+  static basePathOfHtml(htmlPath: string): string {
+    const name = path.basename(htmlPath, ".html");
+    return name === "index" ? "" : name;
+  }
+
   get #outputDir(): string {
     return path.join(
       this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
@@ -73,6 +106,18 @@ void bootCsr(pages);
     );
   }
 
+  get #generatedDir(): string {
+    return path.join(this.#app.cwdPath, ".akan/generated/csr");
+  }
+
+  get #artifactDir(): string {
+    return path.join(this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath, ".akan/artifact");
+  }
+
+  #generatedPath(filename: string): string {
+    return path.join(this.#generatedDir, filename);
+  }
+
   #define(): Record<string, string> {
     const nodeEnv = this.#command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
     return {
@@ -84,10 +129,19 @@ void bootCsr(pages);
     };
   }
 
+  async #createEntryFile(basePath: string, pageEntries: PageEntry[]): Promise<readonly [string, string]> {
+    return [
+      this.#generatedPath(CsrArtifactBuilder.entryFilename(basePath)),
+      `import { bootCsr } from "akanjs/webkit";
+${await PagesEntrySourceGenerator.generateStatic(pageEntries)}
+void bootCsr(pages);
+`,
+    ] as const;
+  }
+
   #createHtmlFile(basePath: string): readonly [string, string] {
-    const filename = `${basePath}.html`;
     return [
-      `${this.#app.cwdPath}/.akan/generated/csr/${filename}`,
+      this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath)),
       `<!doctype html>
 <html lang="${this.#lang}">
   <head>
@@ -98,41 +152,40 @@ void bootCsr(pages);
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="./csr.tsx"></script>
+    <script type="module" src="./${CsrArtifactBuilder.entryFilename(basePath)}"></script>
   </body>
 </html>
   `,
     ] as const;
   }
 
-  async #loadCsrArtifact(): Promise<Pick<BaseBuildArtifact, "cssAssets">> {
-    const artifactDir = path.join(
-      this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
-      ".akan/artifact",
-    );
-    const artifactFile = Bun.file(path.join(artifactDir, "base-artifact.json"));
-    if (!(await artifactFile.exists())) return { cssAssets: {} };
-    const artifact = (await artifactFile.json()) as Pick<BaseBuildArtifact, "cssAssets">;
-    return { cssAssets: artifact.cssAssets ?? {} };
+  async #loadCssAssets(): Promise<Record<string, CssAsset>> {
+    const artifactFile = Bun.file(path.join(this.#artifactDir, "base-artifact.json"));
+    if (!(await artifactFile.exists())) return {};
+    const artifact = (await artifactFile.json()) as Partial<Pick<BaseBuildArtifact, "cssAssets">>;
+    return artifact.cssAssets ?? {};
   }
 
-  async #inlineCsrArtifacts(cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>): Promise<void> {
+  async #inlineCsrArtifacts(cssAssets: Record<string, CssAsset>): Promise<void> {
     const jsFiles = new Set<string>();
-    const cssFiles = new Set<string>();
     for (const htmlPath of await this.#htmlOutputPaths()) {
       const htmlFile = Bun.file(htmlPath);
       if (!(await htmlFile.exists())) continue;
-      const basePath = path.basename(htmlPath, ".html") === "index" ? "" : path.basename(htmlPath, ".html");
-      const inlined = await this.#inlineHtmlAssets(await htmlFile.text(), htmlPath, cssAssets[basePath]);
+      const basePath = CsrArtifactBuilder.basePathOfHtml(htmlPath);
+      const cssAsset = cssAssets[basePath];
+      if (!cssAsset) {
+        this.#app.logger.warn(
+          `[csr-build] base-artifact.json has no compiled stylesheet for ${basePath || "root"}; ${path.basename(htmlPath)} ships without CSS`,
+        );
+      }
+      const inlined = await this.#inlineHtmlAssets(await htmlFile.text(), htmlPath, cssAsset);
       for (const filePath of inlined.jsFiles) jsFiles.add(filePath);
-      for (const filePath of inlined.cssFiles) cssFiles.add(filePath);
       await Bun.write(htmlPath, inlined.html);
     }
     for (const filePath of jsFiles) await unlink(filePath).catch(() => undefined);
-    for (const filePath of cssFiles) await unlink(filePath).catch(() => undefined);
-    const remainingJs = await this.#listOutputFiles((filePath) => filePath.endsWith(".js"));
-    const remainingCss = await this.#listOutputFiles((filePath) => filePath.endsWith(".css"));
-    const remainingAssets = [...remainingJs, ...remainingCss];
+    const remainingAssets = await this.#listOutputFiles(
+      (filePath) => filePath.endsWith(".js") || filePath.endsWith(".css"),
+    );
     if (remainingAssets.length > 0) {
       throw new Error(`[csr-build] expected single-file HTML, but CSR assets remain:\n${remainingAssets.join("\n")}`);
     }
@@ -141,44 +194,20 @@ void bootCsr(pages);
   async #inlineHtmlAssets(
     html: string,
     htmlPath: string,
-    cssAsset?: { cssUrl: string; cssRelPath: string },
-  ): Promise<{ html: string; jsFiles: string[]; cssFiles: string[] }> {
+    cssAsset?: CssAsset,
+  ): Promise<{ html: string; jsFiles: string[] }> {
+    let next = html;
+    if (cssAsset) {
+      const css = await Bun.file(path.join(this.#artifactDir, cssAsset.cssRelPath)).text();
+      next = CsrArtifactBuilder.injectBeforeHeadEnd(next, CsrArtifactBuilder.createInlineStyle(css));
+    }
     const jsFiles: string[] = [];
-    const cssFiles = CsrArtifactBuilder.collectStylesheetHrefs(html).map((href) =>
-      CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, href),
-    );
-    let next = CsrArtifactBuilder.stripBundledStylesheetLinks(html);
     next = await CsrArtifactBuilder.replaceModuleScriptSrc(next, async (src) => {
       const jsPath = CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, src);
       jsFiles.push(jsPath);
       return await Bun.file(jsPath).text();
     });
-    const bundledCss = (
-      await Promise.all(
-        cssFiles.map((cssFile) =>
-          Bun.file(cssFile)
-            .text()
-            .catch(() => ""),
-        ),
-      )
-    )
-      .filter(Boolean)
-      .join("\n");
-    if (bundledCss) {
-      const style = CsrArtifactBuilder.createInlineStyle(bundledCss);
-      if (!next.includes(style)) next = CsrArtifactBuilder.injectBeforeHeadEnd(next, style);
-    }
-    if (cssAsset) {
-      const cssPath = path.join(
-        this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
-        ".akan/artifact",
-        cssAsset.cssRelPath,
-      );
-      const css = await Bun.file(cssPath).text();
-      const style = CsrArtifactBuilder.createInlineStyle(css);
-      if (!next.includes(style)) next = CsrArtifactBuilder.injectBeforeHeadEnd(next, style);
-    }
-    return { html: next, jsFiles, cssFiles };
+    return { html: next, jsFiles };
   }
 
   async #htmlOutputPaths(): Promise<string[]> {
@@ -194,23 +223,26 @@ void bootCsr(pages);
     return files.sort();
   }
 
+  /**
+   * Bun's HTML bundler hoists the module script into `<head>`, so once that script is inline its source is part
+   * of the text being searched — and a React bundle contains `<body` and `</head>` as strings. Positions are
+   * taken on a copy with script, style and comment bodies blanked, and the snippet always lands after whatever
+   * was injected before it: prepending would reverse the cascade order the caller chose.
+   */
   static injectBeforeHeadEnd(html: string, snippet: string): string {
-    const matches = [...html.matchAll(/<\/head\s*>/gi)];
-    const bodyStart = html.search(/<body(?:\s|>)/i);
-    const headEnd = matches
-      .filter((match) => match.index !== undefined && (bodyStart === -1 || match.index < bodyStart))
-      .at(-1);
-    if (!headEnd || headEnd.index === undefined) return `${snippet}\n${html}`;
-    return `${html.slice(0, headEnd.index)}${snippet}\n${html.slice(headEnd.index)}`;
-  }
-
-  static stripBundledStylesheetLinks(html: string): string {
-    return html.replace(/<link\b(?=[^>]*\brel=["']stylesheet["'])[^>]*>\s*/gi, "");
+    const scannable = CsrArtifactBuilder.blankEmbeddedContent(html);
+    const headEnd = scannable.search(/<\/head\s*>/i);
+    if (headEnd !== -1) return `${html.slice(0, headEnd)}${snippet}\n${html.slice(headEnd)}`;
+    const bodyStart = scannable.search(/<body(?:\s|>)/i);
+    if (bodyStart !== -1) return `${html.slice(0, bodyStart)}${snippet}\n${html.slice(bodyStart)}`;
+    return `${html}\n${snippet}`;
   }
 
-  static collectStylesheetHrefs(html: string): string[] {
-    const linkRe = /<link\b(?=[^>]*\brel=["']stylesheet["'])(?=[^>]*\bhref=["']([^"']+)["'])[^>]*>/gi;
-    return [...html.matchAll(linkRe)].map((match) => match[1]).filter((href): href is string => !!href);
+  static blankEmbeddedContent(html: string): string {
+    return html.replace(
+      /<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->/gi,
+      (match) => " ".repeat(match.length),
+    );
   }
 
   static createInlineStyle(css: string): string {

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/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("");
   }