@akanjs/devkit 3.0.0-alpha.3 → 3.0.0-alpha.30

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,6 +430,17 @@ export function isIgnoredNodeModuleSource(filePath: string): boolean {
   return NODE_MODULES_RE.test(filePath) && !AKANJS_NODE_MODULE_RE.test(filePath);
 }
 
+/**
+ * `@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,
+  );
+}
+
 function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
   const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
   const segments = normalized.split("/");

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/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/precompressArtifacts.ts

@@ -1,26 +1,41 @@
 import fs from "node:fs";
 import path from "node:path";
+import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
+/**
+ * Quality 11 is roughly 100x slower than gzip, so it is spent only where it pays: there is one CSS asset
+ * per basePath and it is the largest single file the app ships, worth ~20% over gzip for ~0.2s. Raising the
+ * several hundred JS chunks from 9 to 11 costs ~12s of build time to save a few hundred KB, so they stay at 9.
+ */
+const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+const DEFAULT_BROTLI_QUALITY = 9;
+const GZIP_LEVEL = 9;
 
 export interface PrecompressArtifactsResult {
   files: number;
   inputBytes: number;
   outputBytes: number;
+  brotliBytes: number;
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  const roots = [path.join(app.dist.cwdPath, ".akan/artifact/client")];
-  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0 };
+  //* styles too: WebRouter serves both prefixes through the same sidecar-aware #fileResponse, and the
+  //* one CSS asset per basePath is the largest uncompressed payload the app ships.
+  const roots = [
+    path.join(app.dist.cwdPath, ".akan/artifact/client"),
+    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+  ];
+  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
   await Promise.all(roots.map((root) => precompressRoot(root, result)));
   if (result.files > 0) {
     app.verbose(
-      `[precompress] wrote ${result.files} gzip sidecars (${formatBytes(result.inputBytes)} -> ${formatBytes(
+      `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
         result.outputBytes,
-      )})`,
+      )} / br ${formatBytes(result.brotliBytes)})`,
     );
   }
   return result;
@@ -32,16 +47,29 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
     if (!(await shouldPrecompress(filePath))) continue;
     const bytes = await Bun.file(filePath).bytes();
-    const gz = Bun.gzipSync(toArrayBuffer(bytes));
-    await Bun.write(`${filePath}.gz`, gz);
+    const buffer = toArrayBuffer(bytes);
+    const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
+    const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
+    await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
     result.outputBytes += gz.byteLength;
+    result.brotliBytes += br.byteLength;
   }
 }
 
+function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
+  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+  return zlib.brotliCompressSync(buffer, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: buffer.byteLength,
+    },
+  });
+}
+
 async function shouldPrecompress(filePath: string): Promise<boolean> {
-  if (filePath.endsWith(".gz")) return false;
+  if (filePath.endsWith(".gz") || filePath.endsWith(".br")) return false;
   if (!COMPRESSIBLE_EXTS.has(path.extname(filePath).toLowerCase())) return false;
   const file = Bun.file(filePath);
   if (!(await file.exists())) return false;

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";
@@ -33,6 +33,15 @@ export interface BuildRouteClientOptions {
   routeId?: string;
   command?: "build" | "start";
   discovery?: ClientEntryDiscovery;
+  /**
+   * Client entries resolved by the caller, which skips discovery and bundles exactly this list.
+   *
+   * `AllRoutesBuilder` passes every route's entries at once so they share one `Bun.build`. Chunk
+   * splitting is scoped to a single invocation, so a dependency reachable from entries spread across
+   * several invocations is emitted once per invocation — mermaid landed in `apps/akan` four times that
+   * way. Dev keeps one build per route and leaves this unset.
+   */
+  entries?: string[];
 }
 
 export interface BuildRouteClientResult {
@@ -61,6 +70,7 @@ export class RouteClientBuilder {
   #knownEntries: Set<string>;
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
+  #entries?: string[];
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
@@ -68,11 +78,13 @@ export class RouteClientBuilder {
     this.#knownEntries = options.knownEntries ?? new Set<string>();
     this.#command = options.command ?? "start";
     this.#discovery = options.discovery;
+    this.#entries = options.entries;
   }
 
   async build(): Promise<BuildRouteClientResult> {
-    const discovery = this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app));
-    const discovered = await discovery.discover(this.#seeds);
+    const discovered =
+      this.#entries ??
+      (await (this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app))).discover(this.#seeds));
     const entries = discovered.filter((e) => !this.#knownEntries.has(e));
     if (entries.length === 0) return this.#emptyResult(discovered);
 
@@ -151,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();
@@ -227,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";
@@ -110,7 +110,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 +192,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 +201,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 +210,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}`,
+      );
+    }
+  }
 }

package/frontendBuild/vendorSpecifiers.ts

@@ -11,6 +11,7 @@ export const VENDOR_SPECIFIERS = [
   "akanjs/base",
   "akanjs/common",
   "akanjs/constant",
+  "akanjs/fetch",
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];

package/getCredentials.ts

@@ -1,5 +1,3 @@
-import yaml from "js-yaml";
-
 import type { AppExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 
@@ -12,7 +10,7 @@ interface Secret {
 
 export const getCredentials = async (app: AppExecutor, environment: string): Promise<AppSecret> => {
   const content = await FileSys.readText(`${app.workspace.workspaceRoot}/infra/app/values/${app.name}-secret.yaml`);
-  const secret = yaml.load(content) as Secret;
+  const secret = Bun.YAML.parse(content) as Secret;
   const appSecret = secret[environment];
   if (!appSecret) throw new Error(`No secret found for ${app.name} in ${environment}`);
   return appSecret;