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

package/frontendBuild/fontPruner.ts

@@ -0,0 +1,206 @@
+import { rm, rmdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { isFontOptimizationEnabled } from "akanjs/client";
+import type { App } from "../commandDecorators";
+import { FontOptimizer } from "./fontOptimizer";
+
+const FONT_GLOB = "**/*.{woff2,woff,ttf,otf,ttc,eot}";
+const REFERRER_GLOB = "**/*.{css,js,mjs,cjs,json,html,htm,svg,xml,webmanifest}";
+
+export type FontKeepReason =
+  | { kind: "unoptimized" }
+  | { kind: "declared"; glob: string }
+  | { kind: "referenced"; referrer: string };
+
+export interface FontPruneResult {
+  removed: { file: string; bytes: number }[];
+  kept: { file: string; bytes: number; reason: FontKeepReason }[];
+  freedBytes: number;
+}
+
+/**
+ * Drops the font sources in a build's `public/` that no built surface reads. A font with `optimize` on is
+ * served from `/_akan/fonts` after subsetting, so its source is a build input — the image ships it and the
+ * runtime never opens it. Only `dist` is touched: an app's and a lib's own `public/` keep every file, because
+ * one lib's fonts are picked over differently by every app that mounts it and by other repos.
+ */
+export class FontPruner {
+  #app: App;
+  #keepGlobs: string[];
+  #publicRoot: string;
+  #artifactRoot: string;
+
+  constructor(app: App, { keepFonts = [] }: { keepFonts?: string[] } = {}) {
+    this.#app = app;
+    this.#keepGlobs = keepFonts;
+    this.#publicRoot = path.join(app.dist.cwdPath, "public");
+    this.#artifactRoot = path.join(app.dist.cwdPath, ".akan/artifact");
+  }
+
+  async prune(): Promise<FontPruneResult> {
+    const empty: FontPruneResult = { removed: [], kept: [], freedBytes: 0 };
+    if (!(await this.#isDirectory(this.#publicRoot))) return empty;
+    const candidates = await this.#collectCandidates();
+    if (!candidates.length) return empty;
+
+    const fonts = await new FontOptimizer(this.#app, "build").discoverFonts();
+    const unoptimizedSrcs = new Set<string>();
+    const optimizedSrcs = new Set<string>();
+    for (const font of fonts) {
+      const target = isFontOptimizationEnabled(font) ? optimizedSrcs : unoptimizedSrcs;
+      for (const fontPath of font.paths) target.add(path.posix.basename(fontPath.src));
+    }
+
+    const result: FontPruneResult = { removed: [], kept: [], freedBytes: 0 };
+    const undecided: typeof candidates = [];
+    for (const candidate of candidates) {
+      const reason = this.#staticKeepReason(candidate, unoptimizedSrcs);
+      if (reason) result.kept.push({ file: candidate.rel, bytes: candidate.bytes, reason });
+      else undecided.push(candidate);
+    }
+    if (undecided.length) {
+      const referrers = await this.#findReferrers(undecided, optimizedSrcs);
+      for (const candidate of undecided) {
+        const referrer = referrers.get(candidate.rel);
+        if (referrer)
+          result.kept.push({ file: candidate.rel, bytes: candidate.bytes, reason: { kind: "referenced", referrer } });
+        else result.removed.push({ file: candidate.rel, bytes: candidate.bytes });
+      }
+    }
+
+    await this.#remove(result.removed.map(({ file }) => file));
+    result.freedBytes = result.removed.reduce((total, { bytes }) => total + bytes, 0);
+    this.#report(result);
+    return result;
+  }
+
+  #staticKeepReason(candidate: { rel: string; basename: string }, unoptimizedSrcs: Set<string>): FontKeepReason | null {
+    if (unoptimizedSrcs.has(candidate.basename)) return { kind: "unoptimized" };
+    for (const glob of this.#keepGlobs) {
+      if (new Bun.Glob(glob).match(candidate.rel)) return { kind: "declared", glob };
+    }
+    return null;
+  }
+
+  async #collectCandidates() {
+    const candidates: { rel: string; basename: string; bytes: number }[] = [];
+    for await (const rel of new Bun.Glob(FONT_GLOB).scan({ cwd: this.#publicRoot, dot: false })) {
+      const entry = await stat(path.join(this.#publicRoot, rel)).catch(() => null);
+      if (!entry?.isFile()) continue;
+      candidates.push({ rel: rel.split(path.sep).join("/"), basename: path.basename(rel), bytes: entry.size });
+    }
+    return candidates;
+  }
+
+  /**
+   * Matched by basename rather than by URL, so a reference survives every spelling a referrer may use — an
+   * absolute or relative `url()`, and the percent-encoded form a font whose filename carries a space needs.
+   *
+   * The build's own bundles are read on weaker terms than `public/` and the compiled CSS: every route file's
+   * `fonts` declaration is inlined into the pages bundle, the client chunks and the CSR shell, so a declared
+   * source is in all three whether or not anything loads it. A hit there is therefore ignored for a font the
+   * optimizer already subset — that string is the declaration, not a fetch.
+   */
+  async #findReferrers(
+    candidates: { rel: string; basename: string }[],
+    optimizedSrcs: Set<string>,
+  ): Promise<Map<string, string>> {
+    const referrers = new Map<string, string>();
+    const authoritative = candidates;
+    const bundled = candidates.filter((candidate) => !optimizedSrcs.has(candidate.basename));
+    const roots: { dir: string; label: string; needles: typeof candidates }[] = [
+      { dir: this.#publicRoot, label: "public", needles: authoritative },
+      { dir: path.join(this.#artifactRoot, "styles"), label: ".akan/artifact/styles", needles: authoritative },
+      { dir: path.join(this.#artifactRoot, "client"), label: ".akan/artifact/client", needles: bundled },
+      { dir: path.join(this.#artifactRoot, "client-ssr"), label: ".akan/artifact/client-ssr", needles: bundled },
+      { dir: path.join(this.#artifactRoot, "server"), label: ".akan/artifact/server", needles: bundled },
+      { dir: path.join(this.#app.dist.cwdPath, "csr"), label: "csr", needles: bundled },
+    ];
+    for (const root of roots) {
+      const pending = root.needles.filter((candidate) => !referrers.has(candidate.rel));
+      if (!pending.length || !(await this.#isDirectory(root.dir))) continue;
+      await this.#scanRoot(root, pending, referrers);
+    }
+    return referrers;
+  }
+
+  async #scanRoot(
+    root: { dir: string; label: string },
+    pending: { rel: string; basename: string }[],
+    referrers: Map<string, string>,
+  ) {
+    const needles = pending.map((candidate) => ({
+      rel: candidate.rel,
+      forms: [...new Set([candidate.basename, encodeURIComponent(candidate.basename)])],
+    }));
+    for await (const rel of new Bun.Glob(REFERRER_GLOB).scan({ cwd: root.dir, dot: false })) {
+      const remaining = needles.filter((needle) => !referrers.has(needle.rel));
+      if (!remaining.length) return;
+      const text = await Bun.file(path.join(root.dir, rel))
+        .text()
+        .catch(() => "");
+      if (!text) continue;
+      for (const needle of remaining) {
+        if (needle.forms.some((form) => text.includes(form)))
+          referrers.set(needle.rel, `${root.label}/${rel.split(path.sep).join("/")}`);
+      }
+    }
+  }
+
+  async #remove(files: string[]) {
+    await Promise.all(files.map((file) => rm(path.join(this.#publicRoot, file), { force: true })));
+    const dirs = [...new Set(files.map((file) => path.posix.dirname(file)))]
+      .filter((dir) => dir !== "." && dir !== "/")
+      .sort((a, b) => b.length - a.length);
+    for (const dir of dirs) await rmdir(path.join(this.#publicRoot, dir)).catch(() => undefined);
+  }
+
+  /**
+   * The referrer roll-up is `info`, not `verbose`: a generated file that lists every asset in `public/` — a
+   * service-worker precache manifest is the usual one — is a real reference and keeps every font it names, so
+   * without this line a build that pruned nothing looks the same as a build with nothing to prune.
+   */
+  #report(result: FontPruneResult) {
+    if (!result.removed.length && !result.kept.length) return;
+    for (const { file, bytes } of result.removed)
+      this.#app.verbose(`[font-prune] dropped public/${file} (${FontPruner.formatBytes(bytes)})`);
+    for (const { file, reason } of result.kept)
+      this.#app.verbose(`[font-prune] kept public/${file} — ${FontPruner.describe(reason)}`);
+    const byReferrer = new Map<string, { files: number; bytes: number }>();
+    for (const { bytes, reason } of result.kept) {
+      if (reason.kind !== "referenced") continue;
+      const entry = byReferrer.get(reason.referrer) ?? { files: 0, bytes: 0 };
+      entry.files += 1;
+      entry.bytes += bytes;
+      byReferrer.set(reason.referrer, entry);
+    }
+    if (!byReferrer.size) return;
+    const ranked = [...byReferrer.entries()].sort(([, a], [, b]) => b.bytes - a.bytes);
+    const named = ranked
+      .slice(0, 3)
+      .map(([referrer, { files, bytes }]) => `${referrer} (${files}, ${FontPruner.formatBytes(bytes)})`);
+    const rest = ranked.length - named.length;
+    this.#app.logger.info(
+      `[font-prune] kept ${FontPruner.formatBytes(ranked.reduce((total, [, entry]) => total + entry.bytes, 0))} of fonts in public/ because these reference them: ${named.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}`,
+    );
+  }
+
+  static describe(reason: FontKeepReason) {
+    if (reason.kind === "unoptimized") return "declared with optimize: false, so the runtime CSS serves it";
+    if (reason.kind === "declared") return `kept by assets.keepFonts "${reason.glob}"`;
+    return `referenced by ${reason.referrer}`;
+  }
+
+  static formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+  }
+
+  async #isDirectory(dir: string) {
+    return await stat(dir).then(
+      (entry) => entry.isDirectory(),
+      () => false,
+    );
+  }
+}

package/frontendBuild/frontendBuild.test.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RoutesManifest } from "akanjs/server";
 import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
+import { CssCompiler, declaredCustomProperties, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
 import { DevChangePlanner } from "./devChangePlanner";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -54,10 +54,10 @@ describe("PagesEntrySourceGenerator", () => {
     );
   });
 
-  test("generates static import source for single-file CSR bundles", () => {
+  test("generates static import source for single-file CSR bundles", async () => {
     const indexAbs = path.resolve("/repo/apps/demo/page/_index.tsx");
     const adminAbs = path.resolve("/repo/apps/demo/page/admin.tsx");
-    const source = PagesEntrySourceGenerator.generateStatic([
+    const source = await PagesEntrySourceGenerator.generateStatic([
       { key: "./_index.tsx", moduleAbsPath: indexAbs },
       { key: "./admin.tsx", moduleAbsPath: adminAbs },
     ]);
@@ -88,7 +88,7 @@ describe("PagesEntrySourceGenerator", () => {
     await write(expressionPath, "export default async () => null;");
     await write(namedExportPath, "async function NamedExport() { return null; }\nexport { NamedExport as default };");
 
-    const source = PagesEntrySourceGenerator.generateStatic([
+    const source = await PagesEntrySourceGenerator.generateStatic([
       { key: "./_index.tsx", moduleAbsPath: indexPath },
       { key: "./admin.tsx", moduleAbsPath: adminPath },
       { key: "./typed.tsx", moduleAbsPath: typedPath },
@@ -123,7 +123,7 @@ describe("PagesBundleBuilder", () => {
       outdir,
       target: "bun",
       format: "esm",
-      plugins: [PagesBundleBuilder.createServerCssStubPlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     expect(result.success).toBe(true);
@@ -178,15 +178,96 @@ describe("CsrArtifactBuilder", () => {
     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);
+  test("creates inline stylesheet with the closing tag escaped", () => {
     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>");
   });
+
+  test("injects into the real head even when an inline bundle quotes body and head tags", () => {
+    const bundle = 'console.info("<body>", "</head>", "<!--");';
+    const html = [
+      "<!doctype html>",
+      "<html>",
+      "<head>",
+      `<script type="module">${bundle}</script>`,
+      "</head>",
+      '<body><div id="root"></div></body>',
+      "</html>",
+    ].join("\n");
+
+    const first = CsrArtifactBuilder.injectBeforeHeadEnd(html, "<style>a{}</style>");
+    const second = CsrArtifactBuilder.injectBeforeHeadEnd(first, "<style>b{}</style>");
+
+    expect(second.startsWith("<!doctype html>")).toBe(true);
+    expect(second.indexOf("<style>a{}</style>")).toBeGreaterThan(second.indexOf(bundle));
+    expect(second.indexOf("<style>b{}</style>")).toBeGreaterThan(second.indexOf("<style>a{}</style>"));
+    expect(second.indexOf("<style>b{}</style>")).toBeLessThan(second.indexOf("\n</head>"));
+  });
+
+  test("never prepends: without a head the snippet lands before body, else at the end", () => {
+    expect(CsrArtifactBuilder.injectBeforeHeadEnd("<html><body></body></html>", "<style></style>")).toBe(
+      "<html><style></style>\n<body></body></html>",
+    );
+    expect(CsrArtifactBuilder.injectBeforeHeadEnd("<div></div>", "<style></style>")).toBe(
+      "<div></div>\n<style></style>",
+    );
+  });
+
+  test("gives each basePath its own routes plus the routes outside every basePath", () => {
+    const entries = [
+      { key: "./_layout.tsx", moduleAbsPath: "/repo/page/_layout.tsx" },
+      { key: "./(sign)/signin.tsx", moduleAbsPath: "/repo/page/(sign)/signin.tsx" },
+      {
+        key: "./office/__root_layout.tsx",
+        moduleAbsPath: "/repo/.akan/generated/root-layouts/office__root_layout.tsx",
+      },
+      { key: "./office/_index.tsx", moduleAbsPath: "/repo/page/office/_index.tsx" },
+      {
+        key: "./(user)/soft/__root_layout.tsx",
+        moduleAbsPath: "/repo/.akan/generated/root-layouts/soft__root_layout.tsx",
+      },
+      { key: "./(user)/soft/home.tsx", moduleAbsPath: "/repo/page/(user)/soft/home.tsx" },
+    ];
+    const basePaths = ["office", "soft"];
+
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "office", basePaths).map((entry) => entry.key)).toEqual([
+      "./_layout.tsx",
+      "./(sign)/signin.tsx",
+      "./office/__root_layout.tsx",
+      "./office/_index.tsx",
+    ]);
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "soft", basePaths).map((entry) => entry.key)).toEqual([
+      "./_layout.tsx",
+      "./(sign)/signin.tsx",
+      "./(user)/soft/__root_layout.tsx",
+      "./(user)/soft/home.tsx",
+    ]);
+    expect(CsrArtifactBuilder.pageEntriesForBasePath(entries, "", [])).toEqual(entries);
+  });
+
+  test("keeps route stylesheets out of the browser bundle so the HTML links no CSS", async () => {
+    const root = await makeTempRoot();
+    const htmlPath = path.join(root, "src/index.html");
+    await write(
+      htmlPath,
+      '<!doctype html><html><head></head><body><script type="module" src="./index.csr.tsx"></script></body></html>',
+    );
+    await write(path.join(root, "src/index.csr.tsx"), 'import "./styles.css";\nconsole.info("boot");\n');
+    await write(path.join(root, "src/styles.css"), ":root { --foreground: #fff; }\n");
+
+    const result = await Bun.build({
+      target: "browser",
+      entrypoints: [htmlPath],
+      root: path.join(root, "src"),
+      outdir: path.join(root, "out"),
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.outputs.some((output) => output.path.endsWith(".css"))).toBe(false);
+    expect(await readFile(path.join(root, "out/index.html"), "utf8")).not.toContain("stylesheet");
+  });
 });
 
 describe("SsrBaseArtifactBuilder", () => {
@@ -391,6 +472,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 +523,77 @@ describe("CssCompiler", () => {
 
     expect(css).toContain(".text-fuchsia-500");
   });
+
+  test("reads declarations that prove a stylesheet arrived, ignoring theme variables that may not", () => {
+    expect(declaredCustomProperties(":root { --kakao: #fee500; --naver: #1ec800; }")).toEqual(["--kakao", "--naver"]);
+    expect(declaredCustomProperties("@theme inline {\n  --color-brand: var(--brand);\n}\n")).toEqual([]);
+    expect(declaredCustomProperties("@theme { --color-x: initial; }\n:root { --brand: #111; }")).toEqual(["--brand"]);
+    expect(declaredCustomProperties(".a { color: var(--kakao); }")).toEqual([]);
+    expect(declaredCustomProperties(":root{--a:#111}\n@media (min-width:1px){:root{--a:#222;--b:#333}}")).toEqual([
+      "--a",
+      "--b",
+    ]);
+  });
+
+  test("fails loudly on a stylesheet import that resolves to nothing", async () => {
+    const root = await makeTempRoot();
+    const cssPath = path.join(root, "apps/demo/page/styles.css");
+    await write(cssPath, '@import "../../../libs/shared/ui/tokens.css";\n');
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: path.join(root, "apps/demo"),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+
+    await expect(compiler.compileCss([cssPath], [])).rejects.toThrow(
+      /failed to resolve stylesheet import "\.\.\/\.\.\/\.\.\/libs\/shared\/ui\/tokens\.css"/,
+    );
+  });
+
+  test("reports every @import per base path so the written asset can be checked against it", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(path.join(appDir, "page/_index.tsx"), 'import "./styles.css";\nexport default () => null;\n');
+    await write(path.join(appDir, "page/styles.css"), '@import "../../../libs/shared/ui/brand.css";\n');
+    await write(path.join(root, "libs/shared/ui/brand.css"), ":root { --kakao: #fee500; --naver: #1ec800; }\n");
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: appDir,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [], basePaths: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+    const cssByBasePath = await compiler.getCssByBasePath();
+
+    expect(cssByBasePath[""]).toContain("--kakao");
+    expect(compiler.importedStylesheetsByBasePath[""]).toEqual([
+      { cssPath: path.join(root, "libs/shared/ui/brand.css"), declaredNames: ["--kakao", "--naver"] },
+    ]);
+  });
+
+  test("compiles lib-owned tokens ahead of the app stylesheets that may override them", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import "./styles.css";\nimport { Card } from "@libs/shared/ui";\nexport default () => <Card />;\n',
+    );
+    await write(path.join(appDir, "page/styles.css"), ":root { --brand: #111111; }\n");
+    await write(path.join(root, "libs/shared/ui/index.ts"), "export const Card = () => null;\n");
+    await write(path.join(root, "libs/shared/ui/tokens.css"), ":root { --kakao: #fee500; }\n");
+    await write(path.join(root, "libs/unused/ui/tokens.css"), ":root { --unused: #000000; }\n");
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: appDir,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: { "@libs/*": ["./libs/*"] } } }),
+    } as never);
+    const { cssPaths } = await compiler.discoverCssAndSources();
+
+    expect(cssPaths).toEqual([path.join(root, "libs/shared/ui/tokens.css"), path.join(appDir, "page/styles.css")]);
+  });
 });

package/frontendBuild/hmrWatcher.ts

@@ -209,7 +209,7 @@ export class HmrWatcher {
     // per-batch detail stays at verbose because a save-all trips this on every save.
     if (!this.#reportedCompensating) {
       this.#reportedCompensating = true;
-      this.#logger.info(
+      this.#logger.verbose(
         `[hmr] recovered ${unreported} change(s) that fs.watch did not report; Bun coalesces concurrent saves and drops all but one, so changes are resolved by mtime`,
       );
     }

package/frontendBuild/index.ts

@@ -9,6 +9,7 @@ export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
 export * from "./fontOptimizer";
+export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
 export * from "./hmrWatcher";
 export * from "./pagesBundleBuilder";
@@ -19,7 +20,6 @@ export * from "./routesManifestArtifactSerializer";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
 export * from "./styleContract";
-export * from "./styleGuard";
 export * from "./themeValidator";
 export * from "./vendorSpecifiers";
 export * from "./watchRootResolver";

package/frontendBuild/pagesBundleBuilder.ts

@@ -64,7 +64,7 @@ export class PagesBundleBuilder {
       define: this.#define(),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
-        PagesBundleBuilder.createServerCssStubPlugin(),
+        PagesBundleBuilder.createCssStubPlugin(),
         PagesBundleBuilder.createServerUseClientFetchPlugin(),
         await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig.externalLibs }),
         akanConfig.barrelImports.length > 0
@@ -137,9 +137,9 @@ export class PagesBundleBuilder {
     };
   }
 
-  static createServerCssStubPlugin(): BunPlugin {
+  static createCssStubPlugin(): BunPlugin {
     return {
-      name: "akan-server-css-stub",
+      name: "akan-css-stub",
       setup(build) {
         build.onLoad({ filter: /\.css$/ }, () => ({
           contents: "",

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -1,7 +1,6 @@
-import fs from "node:fs";
 import path from "node:path";
-import ts from "typescript";
 import type { PageEntry } from "../artifact/implicitRootLayout";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
 export class PagesEntrySourceGenerator {
   #pageEntries: PageEntry[];
@@ -22,101 +21,25 @@ export class PagesEntrySourceGenerator {
     return `export const pages = {\n${lines.join("\n")}\n};\n`;
   }
 
-  static generateStatic(pageEntries: PageEntry[]): string {
-    return new PagesEntrySourceGenerator(pageEntries).generateStatic();
+  static async generateStatic(pageEntries: PageEntry[]): Promise<string> {
+    return await new PagesEntrySourceGenerator(pageEntries).generateStatic();
   }
 
-  generateStatic(): string {
+  async generateStatic(): Promise<string> {
     const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
       const specifier = PagesEntrySourceGenerator.#toImportSpecifier(moduleAbsPath);
       return `import * as page${index} from ${JSON.stringify(specifier)};`;
     });
-    const entries = this.#pageEntries.map(({ key, moduleAbsPath }, index) => {
-      const isAsyncDefault = PagesEntrySourceGenerator.#hasAsyncDefaultExport(moduleAbsPath);
-      return `  ${JSON.stringify(key)}: { loader: async () => page${index}, isAsyncDefault: ${isAsyncDefault} },`;
-    });
+    const entries = await Promise.all(
+      this.#pageEntries.map(async ({ key, moduleAbsPath }, index) => {
+        const isAsyncDefault = await AsyncDefaultExportDetector.detect(moduleAbsPath);
+        return `  ${JSON.stringify(key)}: { loader: async () => page${index}, isAsyncDefault: ${isAsyncDefault} },`;
+      }),
+    );
     return `${imports.join("\n")}\nexport const pages = {\n${entries.join("\n")}\n};\n`;
   }
+
   static #toImportSpecifier(moduleAbsPath: string): string {
     return path.resolve(moduleAbsPath).split(path.sep).join("/");
   }
-
-  static #hasAsyncDefaultExport(moduleAbsPath: string): boolean {
-    try {
-      const source = fs.readFileSync(path.resolve(moduleAbsPath), "utf8");
-      const sourceFile = ts.createSourceFile(
-        moduleAbsPath,
-        source,
-        ts.ScriptTarget.Latest,
-        true,
-        PagesEntrySourceGenerator.#scriptKind(moduleAbsPath),
-      );
-      return PagesEntrySourceGenerator.#sourceFileHasAsyncDefaultExport(sourceFile);
-    } catch {
-      return false;
-    }
-  }
-
-  static #sourceFileHasAsyncDefaultExport(sourceFile: ts.SourceFile): boolean {
-    const asyncBindings = new Map<string, boolean>();
-    let defaultIdentifier: string | null = null;
-
-    for (const statement of sourceFile.statements) {
-      if (ts.isFunctionDeclaration(statement)) {
-        if (PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
-          return PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword);
-        }
-        if (statement.name) {
-          asyncBindings.set(
-            statement.name.text,
-            PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword),
-          );
-        }
-        continue;
-      }
-
-      if (ts.isVariableStatement(statement)) {
-        for (const declaration of statement.declarationList.declarations) {
-          if (!ts.isIdentifier(declaration.name)) continue;
-          asyncBindings.set(
-            declaration.name.text,
-            PagesEntrySourceGenerator.#isAsyncFunctionExpression(declaration.initializer),
-          );
-        }
-        continue;
-      }
-
-      if (ts.isExportAssignment(statement)) {
-        if (PagesEntrySourceGenerator.#isAsyncFunctionExpression(statement.expression)) return true;
-        if (ts.isIdentifier(statement.expression)) defaultIdentifier = statement.expression.text;
-        continue;
-      }
-
-      if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
-        const exportClause = statement.exportClause;
-        for (const specifier of exportClause.elements) {
-          if (specifier.name.text !== "default") continue;
-          defaultIdentifier = specifier.propertyName?.text ?? specifier.name.text;
-        }
-      }
-    }
-
-    return defaultIdentifier ? asyncBindings.get(defaultIdentifier) === true : false;
-  }
-
-  static #hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
-    return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false);
-  }
-
-  static #isAsyncFunctionExpression(node?: ts.Expression): boolean {
-    return Boolean(
-      node &&
-        (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
-        PagesEntrySourceGenerator.#hasModifier(node, ts.SyntaxKind.AsyncKeyword),
-    );
-  }
-
-  static #scriptKind(moduleAbsPath: string): ts.ScriptKind {
-    return moduleAbsPath.endsWith(".tsx") || moduleAbsPath.endsWith(".jsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
-  }
 }

package/frontendBuild/routeClientBuilder.ts

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