@akanjs/devkit 3.0.0-alpha.74 → 3.0.0-alpha.76

package/artifact/implicitRootLayout.test.ts

@@ -102,4 +102,71 @@ describe("resolveSsrPageEntries", () => {
     );
     expect(generatedDictMacro).toContain("export const allDictionary = getAllDictionary();");
   });
+
+  test("awaits an async grouped root layout in the CSR bundle instead of mounting it as JSX", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(
+      path.join(pageRoot, "(user)", "_layout.tsx"),
+      "export default async function Layout({ children }) { await Promise.resolve(); return <div>{children}</div>; }\n",
+    );
+    await write(
+      path.join(pageRoot, "(sign)", "_layout.tsx"),
+      "export default function Layout({ children }) { return children; }\n",
+    );
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./(user)/_layout.tsx", "./(user)/self/_index.tsx", "./(sign)/_layout.tsx", "./(sign)/signin.tsx"],
+    });
+
+    const userRoot = entries.find((entry) => entry.key === "./(user)/__root_layout.tsx");
+    const userSource = await Bun.file(userRoot?.moduleAbsPath ?? "").text();
+    expect(userSource).toContain("<System.Provider");
+    expect(userSource).toContain("export default async function GeneratedLayout(");
+    expect(userSource).toContain('process.env.AKAN_PUBLIC_RENDER_ENV === "csr"');
+    expect(userSource).toContain("? await UserLayout({ params, searchParams, children })");
+    expect(userSource).toContain(": <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>;");
+    expect(userSource).toContain("      {layout}\n    </System.Provider>");
+
+    const signRoot = entries.find((entry) => entry.key === "./(sign)/__root_layout.tsx");
+    const signSource = await Bun.file(signRoot?.moduleAbsPath ?? "").text();
+    expect(signSource).toContain("<System.Provider");
+    expect(signSource).toContain("export default function GeneratedLayout(");
+    expect(signSource).not.toContain("await UserLayout(");
+    expect(signSource).toContain(
+      "      <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>\n    </System.Provider>",
+    );
+  });
+
+  test("returns the awaited node directly for an async nested root boundary", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(
+      path.join(pageRoot, "_layout.tsx"),
+      "export default function Layout({ children }) { return children; }\n",
+    );
+    await write(
+      path.join(pageRoot, "(home)", "_layout.tsx"),
+      "const Layout = async ({ children }) => children;\nexport default Layout;\n",
+    );
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./_layout.tsx", "./(home)/_layout.tsx", "./(home)/_index.tsx"],
+    });
+
+    const groupedRoot = entries.find((entry) => entry.key === "./(home)/__root_layout.tsx");
+    const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
+    expect(generatedSource).not.toContain("<System.Provider");
+    expect(generatedSource).toContain("export default async function GeneratedLayout(");
+    expect(generatedSource).toContain("? await UserLayout({ params, searchParams, children })");
+    expect(generatedSource).toContain("  return layout;\n}");
+  });
 });

package/artifact/implicitRootLayout.ts

@@ -1,6 +1,7 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
 export interface PageEntry {
   key: string;
@@ -191,6 +192,25 @@ async function writeGeneratedRootLayoutFile(opts: {
   const userImport = sourceSpecifier
     ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
     : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
+  const isAsyncUserLayout = opts.boundary.sourceAbsPath
+    ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
+    : false;
+  const userLayoutElement = "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>";
+  // React has no async client component, so the CSR bundle calls an async layout and awaits its node the way
+  // `RenderLayer` does for pages. The RSC render keeps the element: awaiting there would hold the shell behind
+  // the layout's own awaits instead of streaming it as its own Flight chunk.
+  const layoutSignature = isAsyncUserLayout
+    ? "export default async function GeneratedLayout"
+    : "export default function GeneratedLayout";
+  const layoutBinding = isAsyncUserLayout
+    ? `  const layout =
+    process.env.AKAN_PUBLIC_RENDER_ENV === "csr"
+      ? await UserLayout({ params, searchParams, children })
+      : ${userLayoutElement};
+`
+    : "";
+  const layoutChild = isAsyncUserLayout ? "{layout}" : userLayoutElement;
+  const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   const source = opts.includeSystemProvider
     ? `import type { LayoutProps, PageProps } from "akanjs/client";
 import { loadFonts } from "akanjs/client";
@@ -222,8 +242,8 @@ export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
 
-export default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {
-  return (
+${layoutSignature}({ children, params, searchParams }: LayoutProps) {
+${layoutBinding}  return (
     <System.Provider
       of={GeneratedLayout as never}
       appName=${JSON.stringify(opts.appName)}
@@ -239,7 +259,7 @@ export default function GeneratedLayout({ children, params, searchParams }: Layo
       wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect ?? true}
       allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}
     >
-      <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>
+      ${layoutChild}
     </System.Provider>
   );
 }
@@ -264,8 +284,8 @@ export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
 
-export default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {
-  return <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>;
+${layoutSignature}({ children, params, searchParams }: LayoutProps) {
+${layoutBinding}  return ${layoutReturn};
 }
 `;
   await Bun.write(absPath, source);

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

@@ -441,7 +441,7 @@ export function declaredCustomProperties(css: string): string[] {
   );
 }
 
-function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
+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/frontendBuild.test.ts

@@ -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", () => {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.74",
+  "version": "3.0.0-alpha.76",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.74",
+    "akanjs": "3.0.0-alpha.76",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/transforms/asyncDefaultExportDetector.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import type ts from "typescript";
+
+type TypeScript = typeof ts;
+
+export class AsyncDefaultExportDetector {
+  static #typescriptLoad: Promise<TypeScript> | undefined;
+
+  // `typescript` costs ~70 MB resident and this detector is reached from the cli entry through the root
+  // layout generator, so the compiler loads on first use rather than at import (`entryModuleGraph.test.ts`).
+  static #loadTypescript(): Promise<TypeScript> {
+    AsyncDefaultExportDetector.#typescriptLoad ??= import("typescript").then(
+      (mod) => (mod.default ?? mod) as TypeScript,
+    );
+    return AsyncDefaultExportDetector.#typescriptLoad;
+  }
+
+  static async detect(moduleAbsPath: string): Promise<boolean> {
+    try {
+      const typescript = await AsyncDefaultExportDetector.#loadTypescript();
+      const source = fs.readFileSync(path.resolve(moduleAbsPath), "utf8");
+      const sourceFile = typescript.createSourceFile(
+        moduleAbsPath,
+        source,
+        typescript.ScriptTarget.Latest,
+        true,
+        AsyncDefaultExportDetector.#scriptKind(typescript, moduleAbsPath),
+      );
+      return new AsyncDefaultExportDetector(typescript).detectInSourceFile(sourceFile);
+    } catch {
+      return false;
+    }
+  }
+
+  #ts: TypeScript;
+
+  constructor(typescript: TypeScript) {
+    this.#ts = typescript;
+  }
+
+  detectInSourceFile(sourceFile: ts.SourceFile): boolean {
+    const ts = this.#ts;
+    const asyncBindings = new Map<string, boolean>();
+    let defaultIdentifier: string | null = null;
+
+    for (const statement of sourceFile.statements) {
+      if (ts.isFunctionDeclaration(statement)) {
+        if (this.#hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+          return this.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword);
+        }
+        if (statement.name) {
+          asyncBindings.set(statement.name.text, this.#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, this.#isAsyncFunctionExpression(declaration.initializer));
+        }
+        continue;
+      }
+
+      if (ts.isExportAssignment(statement)) {
+        if (this.#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;
+  }
+
+  #hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
+    const ts = this.#ts;
+    return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false);
+  }
+
+  #isAsyncFunctionExpression(node?: ts.Expression): boolean {
+    const ts = this.#ts;
+    return Boolean(
+      node &&
+        (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+        this.#hasModifier(node, ts.SyntaxKind.AsyncKeyword),
+    );
+  }
+
+  static #scriptKind(typescript: TypeScript, moduleAbsPath: string): ts.ScriptKind {
+    return moduleAbsPath.endsWith(".tsx") || moduleAbsPath.endsWith(".jsx")
+      ? typescript.ScriptKind.TSX
+      : typescript.ScriptKind.TS;
+  }
+}