@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.100

package/akanContext.ts

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { capitalize } from "akanjs/common";
+import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
@@ -14,6 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
+import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -128,15 +130,29 @@ export type CursorMcpConfig = {
   mcpServers?: Record<string, unknown>;
 };
 
-export const resourceList = [
+export const guidelineResourceUri = (name: string) => `akan://guidelines/${name}`;
+
+/**
+ * Resources that exist whatever the workspace holds. The guideline entries are **not** here: they are
+ * one per directory under `cli/guidelines/`, and a hardcoded pair listed 2 of 31 while `readResource`
+ * threw on the other 29. `buildResourceList` is the only place the two halves meet.
+ */
+const staticResourceList = [
   { uri: "akan://docs/framework", name: "Akan framework guide", mimeType: "text/markdown" },
-  { uri: "akan://guidelines/framework", name: "Framework guideline", mimeType: "text/markdown" },
-  { uri: "akan://guidelines/modelSignal", name: "Model signal guideline", mimeType: "text/markdown" },
   { uri: "akan://workspace/summary", name: "Workspace summary", mimeType: "application/json" },
   { uri: "akan://workspace/apps", name: "Workspace apps", mimeType: "application/json" },
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" },
 ];
 
+export const buildResourceList = (guidelineNames: readonly string[]) => [
+  ...staticResourceList,
+  ...guidelineNames.map((name) => ({
+    uri: guidelineResourceUri(name),
+    name: `${name} guideline`,
+    mimeType: "text/markdown",
+  })),
+];
+
 export const cursorMcpConfigPath = ".cursor/mcp.json";
 // Claude Code reads project-scoped MCP servers from `.mcp.json` at the workspace root.
 export const claudeMcpConfigPath = ".mcp.json";
@@ -275,6 +291,8 @@ const validationCommands = [
   "akan test <app-or-lib-or-pkg>",
   "akan build <app-name>",
   "akan doctor --strict --format json",
+  "akan quality scan [--format json]",
+  "akan quality ssr [--format json]",
 ];
 
 const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
@@ -313,36 +331,6 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
 const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
-const appRootAllowFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지 (agentsIndex.ts); scanInfo.ts 의 appRootAllowedFiles 와 동기
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const appRootAllowDirs = new Set([
-  ".akan",
-  "android",
-  "common",
-  "env",
-  "ios",
-  "lib",
-  "page",
-  "private",
-  "public",
-  "script",
-  "srvkit",
-  "ui",
-  "webkit",
-]);
-
 const safeReadDir = async (dirPath: string) => {
   try {
     return (await readdir(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
@@ -647,6 +635,30 @@ export class AkanContextAnalyzer {
     };
   }
 
+  // The conventions in AGENTS.md ship with the package, but nothing re-renders them on `bun update` — a workspace
+  // keeps whichever release wrote its block until someone re-runs the install. Comparing the stamp against the
+  // running devkit is the only signal that the guide an agent is reading is older than the framework it describes.
+  static async #agentGuideDrift(workspace: WorkspaceExecutor) {
+    const installed = await readDevkitVersion();
+    if (!installed) return null;
+    const content = await safeReadText(path.join(workspace.workspaceRoot, "AGENTS.md"));
+    if (content === null) return null;
+    const stamped = extractBlockVersion(content);
+    if (stamped === installed) return null;
+    const hint = "Re-render the AGENTS.md managed block from the installed framework release.";
+    if (!stamped)
+      return {
+        code: "agent-guide-unstamped",
+        message: `AGENTS.md carries no generated-version stamp, so its conventions may predate @akanjs/devkit ${installed}`,
+        hint,
+      };
+    return {
+      code: "agent-guide-stale",
+      message: `AGENTS.md was generated by @akanjs/devkit ${stamped}, but ${installed} is installed`,
+      hint,
+    };
+  }
+
   static async doctor(
     workspace: WorkspaceExecutor,
     {
@@ -668,22 +680,25 @@ export class AkanContextAnalyzer {
       ),
     ];
 
-    for (const app of context.apps) {
-      const appPath = path.join(workspace.workspaceRoot, app.path);
-      for (const entry of await safeReadDir(appPath)) {
-        const allowed = entry.isDirectory() ? appRootAllowDirs.has(entry.name) : appRootAllowFiles.has(entry.name);
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sysPath = path.join(workspace.workspaceRoot, sys.path);
+      for (const entry of await safeReadDir(sysPath)) {
+        if (!isScannedRootEntry(sys.type, entry.name)) continue;
+        const allowed = entry.isDirectory()
+          ? rootAllowedDirs[sys.type].has(entry.name)
+          : rootAllowedFiles[sys.type].has(entry.name);
         if (!allowed) {
           const action = repairAction(
             "module-shape",
-            `akan repair module-shape --app ${app.name}`,
-            "Review app root shape and remove or move the unknown entry.",
+            `akan repair module-shape --app ${sys.name}`,
+            `Review ${sys.type} root shape and remove or move the unknown entry.`,
             false,
           );
           diagnostics.push({
             severity: "error",
-            code: "app-root-unknown-entry",
-            path: `${app.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            code: `${sys.type}-root-unknown-entry`,
+            path: `${sys.path}/${entry.name}`,
+            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}`,
             repairActions: [action],
           });
           repairActions.push(action);
@@ -691,6 +706,19 @@ export class AkanContextAnalyzer {
       }
     }
 
+    const agentDrift = await AkanContextAnalyzer.#agentGuideDrift(workspace);
+    if (agentDrift) {
+      const action = repairAction("generated", "akan agent install agents-md", agentDrift.hint, true);
+      diagnostics.push({
+        severity: "warning",
+        code: agentDrift.code,
+        path: "AGENTS.md",
+        message: agentDrift.message,
+        repairActions: [action],
+      });
+      repairActions.push(action);
+    }
+
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {
         if (!module.abstract.exists) {

package/akanMcpContract.ts

@@ -391,10 +391,31 @@ export const applyMcpTools: McpToolDefinition[] = [
   },
 ];
 
-export const listAkanMcpTools = (mode: "readonly" | "plan" | "apply" = "readonly") => {
-  if (mode === "readonly") return readonlyMcpTools;
-  if (mode === "plan") return [...readonlyMcpTools, ...planMcpTools];
-  return [...readonlyMcpTools, ...planMcpTools, ...applyMcpTools];
+/**
+ * `guidelineNames` fills the `get_guideline` enum. Without it the argument is a bare string and a model
+ * has to guess one of the ~30 directory names, which it cannot see from here — the names are a
+ * filesystem listing, so they can only arrive from a caller that already read it.
+ */
+export const listAkanMcpTools = (
+  mode: "readonly" | "plan" | "apply" = "readonly",
+  { guidelineNames = [] }: { guidelineNames?: readonly string[] } = {},
+) => {
+  const tools =
+    mode === "readonly"
+      ? readonlyMcpTools
+      : mode === "plan"
+        ? [...readonlyMcpTools, ...planMcpTools]
+        : [...readonlyMcpTools, ...planMcpTools, ...applyMcpTools];
+  if (guidelineNames.length === 0) return tools;
+  return tools.map((tool) =>
+    tool.name === "get_guideline"
+      ? {
+          ...tool,
+          description: `${tool.description ?? ""} One of: ${guidelineNames.join(", ")}.`.trim(),
+          inputSchema: { ...tool.inputSchema, properties: { name: { type: "string", enum: [...guidelineNames] } } },
+        }
+      : tool,
+  );
 };
 
 export const createAkanValidationContract = (listTools = listAkanMcpTools) => ({

package/appSelectionMemory.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { FileSys } from "./fileSys";
+
+interface StoredSelection {
+  apps: string[];
+}
+
+/**
+ * The apps the last interactive pick chose, so `akan start` + Enter repeats a multi-app session instead
+ * of re-ticking it. Advisory only: a missing, unreadable or stale file just means nothing is pre-ticked.
+ */
+export class AppSelectionMemory {
+  static pathIn(workspaceRoot: string) {
+    return path.join(workspaceRoot, "local", ".akan", "lastStart.json");
+  }
+  static async read(workspaceRoot: string): Promise<string[]> {
+    const stored = await Bun.file(AppSelectionMemory.pathIn(workspaceRoot))
+      .json()
+      .catch(() => null);
+    const apps = (stored as StoredSelection | null)?.apps;
+    return Array.isArray(apps) ? apps.filter((name): name is string => typeof name === "string") : [];
+  }
+  static async write(workspaceRoot: string, apps: string[]) {
+    await FileSys.writeJson(AppSelectionMemory.pathIn(workspaceRoot), { apps } satisfies StoredSelection).catch(
+      () => undefined,
+    );
+  }
+}

package/applicationBuildRunner.test.ts

@@ -1,10 +1,45 @@
 import { describe, expect, test } from "bun:test";
-import { AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
+import { rm } from "node:fs/promises";
+import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
     expect(AKAN_OPTIONAL_BACKEND_EXTERNALS).toEqual(
-      expect.arrayContaining(["@libsql/client", "bullmq", "croner", "ioredis", "postgres", "protobufjs"]),
+      expect.arrayContaining(["@libsql/client", "bullmq", "ioredis", "postgres", "protobufjs"]),
     );
   });
+
+  test("keeps backend identifiers so a class names its own logger and stack frames", () => {
+    expect(AKAN_BACKEND_MINIFY.identifiers).toBe(false);
+    expect(AKAN_BACKEND_MINIFY.whitespace).toBe(true);
+    expect(AKAN_BACKEND_MINIFY.syntax).toBe(true);
+  });
+
+  test("a bundler that mangles identifiers loses the class name a Logger reads", async () => {
+    const dir = `${process.env.TMPDIR ?? "/tmp"}/akan-minify-${Bun.randomUUIDv7()}`;
+    const entry = `${dir}/entry.ts`;
+    await Bun.write(
+      entry,
+      `const serve = () => class Service { readonly name = this.constructor.name; };
+export class SampleService extends serve() {}
+console.info(new SampleService().name);
+`,
+    );
+    const build = async (minify: Bun.BuildConfig["minify"]) => {
+      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: `${dir}/out` });
+      expect(result.success).toBe(true);
+      const proc = Bun.spawn([process.execPath, result.outputs[0].path], { stdout: "pipe" });
+      return (await new Response(proc.stdout).text()).trim();
+    };
+    try {
+      expect(await build(AKAN_BACKEND_MINIFY)).toBe("SampleService");
+      expect(await build(true)).not.toBe("SampleService");
+      // Bun 1.4.2 accepts `keepNames` and ignores it; drop this expectation once it keeps the name.
+      expect(await build({ whitespace: true, syntax: true, identifiers: true, keepNames: true })).not.toBe(
+        "SampleService",
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -7,7 +7,13 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
-import { AllRoutesBuilder, CsrArtifactBuilder, precompressArtifacts, SsrBaseArtifactBuilder } from "./frontendBuild";
+import {
+  AllRoutesBuilder,
+  CsrArtifactBuilder,
+  FontPruner,
+  precompressArtifacts,
+  SsrBaseArtifactBuilder,
+} from "./frontendBuild";
 import { Spinner } from "./spinner";
 
 export interface TypecheckOptions {
@@ -15,7 +21,7 @@ export interface TypecheckOptions {
   incremental?: boolean;
 }
 
-export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "compress" | "metadata";
+export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
 
 export type BuildPhaseResult = ApplicationBuildPhaseResult & { id: BuildPhaseId };
 export type BuildResult = ApplicationBuildResult;
@@ -37,6 +43,7 @@ const BUILD_PHASE_EMOJIS: Record<BuildPhaseId, string> = {
   backend: "📦",
   ssr: "🧭",
   csr: "🎨",
+  assets: "✂️",
   compress: "🗜️",
   metadata: "📝",
 };
@@ -53,10 +60,14 @@ const SSR_RENDER_EXTERNALS = [
   "react-server-dom-webpack/client.browser",
 ] as const;
 
+// Identifier mangling renames every class, and `this.constructor.name` is what names a service's logger, an
+// `Exception`, a guard, and every frame of a stack trace — for ~2% of boot on server bytes nothing downloads.
+// `minify.keepNames` typechecks and does nothing as of Bun 1.4.2.
+export const AKAN_BACKEND_MINIFY = { whitespace: true, syntax: true, identifiers: false } as const;
+
 export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",
@@ -78,6 +89,7 @@ export class ApplicationBuildRunner {
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     const phaseOptions = { spinner };
+    const { web, assets } = await this.#app.getConfig();
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
       spinner,
     });
@@ -92,18 +104,30 @@ export class ApplicationBuildRunner {
     await this.#runPhase(
       "ssr",
       "Building SSR route artifacts",
-      () => this.#buildSsr(),
+      async () => (web.ssr ? await this.#buildSsr() : null),
       (result) =>
         result
           ? `${result.allRoutes.manifest.routeIds.length} routes, ${result.allRoutes.manifest.knownEntries.length} entries`
-          : "skipped",
+          : web.ssr
+            ? "skipped"
+            : "disabled by akan.config.ts web.ssr",
       phaseOptions,
     );
     await this.#runPhase(
       "csr",
       "Building CSR assets",
-      () => this.#buildCsr(),
-      (result) => result?.outputDir ?? "skipped",
+      async () => (web.csr ? await this.#buildCsr() : null),
+      (result) => result?.outputDir ?? (web.csr ? "skipped" : "disabled by akan.config.ts web.csr"),
+      phaseOptions,
+    );
+    await this.#runPhase(
+      "assets",
+      "Trimming unread static assets",
+      async () => (assets.pruneFonts ? await new FontPruner(this.#app, assets).prune() : null),
+      (result) =>
+        result
+          ? `${result.removed.length} font file(s) dropped, ${ApplicationBuildRunner.formatBytes(result.freedBytes)} freed; ${result.kept.length} kept`
+          : "disabled by akan.config.ts assets.pruneFonts",
       phaseOptions,
     );
     await this.#runPhase(
@@ -112,7 +136,7 @@ export class ApplicationBuildRunner {
       () => precompressArtifacts(this.#app),
       (result) =>
         result.files > 0
-          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> ${ApplicationBuildRunner.formatBytes(result.outputBytes)}`
+          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
       phaseOptions,
     );
@@ -166,7 +190,7 @@ export class ApplicationBuildRunner {
     const akanConfig = await this.#app.getConfig();
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
-      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.docker.content),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
     ]);
   }
 
@@ -175,6 +199,7 @@ export class ApplicationBuildRunner {
     const backendExternals = [
       ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
     ];
+    const { web } = akanConfig;
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
@@ -183,34 +208,38 @@ export class ApplicationBuildRunner {
       entrypoints: backendEntryPoints,
       outdir: this.#app.dist.cwdPath,
       target: "bun",
-      minify: true,
-      naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
-      define: { "process.env.NODE_ENV": JSON.stringify("production") },
-      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
-    });
-    const rscWorkerResult = await this.#buildOrThrow("rsc-worker", {
-      entrypoints: [this.#resolveRscWorkerBuildEntry()],
-      outdir: this.#app.dist.cwdPath,
-      target: "bun",
-      minify: true,
+      minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
-      conditions: ["react-server"],
-      // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
       plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
     });
+    // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
+    const rscWorkerResult = web.ssr
+      ? await this.#buildOrThrow("rsc-worker", {
+          entrypoints: [this.#resolveRscWorkerBuildEntry()],
+          outdir: this.#app.dist.cwdPath,
+          target: "bun",
+          minify: AKAN_BACKEND_MINIFY,
+          naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+          conditions: ["react-server"],
+          // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
+          define: { "process.env.NODE_ENV": JSON.stringify("production") },
+          plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
+        })
+      : null;
     const consoleRuntimeResult = await this.#buildOrThrow("console-runtime", {
       entrypoints: [this.#resolveConsoleRuntimeBuildEntry()],
       outdir: this.#app.dist.cwdPath,
       target: "bun",
-      minify: true,
+      minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "console-runtime.[ext]", chunk: "chunk-[hash].[ext]" },
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
     });
     await this.#writeConsoleShim();
     return {
-      entrypoints: backendEntryPoints.length + 2,
-      outputs: backendResult.outputs.length + rscWorkerResult.outputs.length + consoleRuntimeResult.outputs.length + 1,
+      entrypoints: backendEntryPoints.length + (rscWorkerResult ? 2 : 1),
+      outputs:
+        backendResult.outputs.length + (rscWorkerResult?.outputs.length ?? 0) + consoleRuntimeResult.outputs.length + 1,
     };
   }
 

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;
@@ -55,7 +56,7 @@ interface RootBoundary {
   segments: string[];
 }
 
-function getRootBoundarySegments(key: string): string[] | null {
+export function getRootBoundarySegments(key: string): string[] | null {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match) return null;
   const prefix = match[1]?.replace(/\/$/, "");
@@ -76,7 +77,7 @@ function implicitDictionaryMacroAbsPath(appCwdPath: string): string {
   return path.join(path.resolve(appCwdPath), IMPLICIT_DICT_DIR, "useDict.ts");
 }
 
-function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
+export function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
   const firstVisibleIndex = segments.findIndex((segment) => !/^\(.+\)$/.test(segment));
   if (firstVisibleIndex === -1) return segments.length <= 1;
   if (segments.slice(firstVisibleIndex + 1).some((segment) => /^\(.+\)$/.test(segment))) return false;
@@ -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/artifact/routeSeedIndex.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, test } from "bun:test";
 import { computeRouteSeedIndex, serializeRouteSeedIndexForArtifact } from "./routeSeedIndex";
 
 describe("computeRouteSeedIndex", () => {