@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.110

package/akanContext.ts

@@ -15,7 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -130,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";
@@ -666,23 +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)) {
-        if (!isScannedAppRootEntry(entry.name)) continue;
-        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.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);

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(
@@ -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

@@ -50,7 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(groupedRoot?.seedAbsPaths).toContain(groupedLayoutPath);
 
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
-    expect(generatedSource).toContain('import * as inheritedLayout from "../../../page/_layout.tsx";');
+    // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
+    expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
+    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
     expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");
@@ -102,4 +104,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;
@@ -184,16 +185,40 @@ async function writeGeneratedRootLayoutFile(opts: {
   const clientImport = opts.includeStInit
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
+  // Both user modules go through `resolveRouteModule`: a `rootLayout()` chain and the legacy named exports read
+  // the same afterwards, and this file never has to know which shape the app wrote.
+  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedLayout from ${JSON.stringify(inheritedSourceSpecifier)};\n`
-    : "const inheritedLayout = {};\n";
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = routePrefixForSegments(opts.boundary.segments);
+  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
-    : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\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";
+    ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { loadFonts, resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
@@ -222,8 +247,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,12 +264,14 @@ 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>
   );
 }
 `
-    : `import type { LayoutProps, PageProps } from "akanjs/client";
+    : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 export async function generateHead(props: PageProps) {
   if (userLayout.generateHead) return userLayout.generateHead(props);
@@ -264,8 +291,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", () => {

package/biome.base.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.12/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -170,10 +170,37 @@
       "includes": ["{apps,libs}/**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
     },
+    {
+      "includes": ["{apps,libs}/**/*.ts", "{apps,libs}/**/*.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-deprecated-log-level.grit"]
+    },
     {
       "includes": ["{apps,libs}/**/*.signal.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
     },
+    {
+      "includes": ["{apps,libs}/**/*.Util.tsx", "{apps,libs}/**/*.Zone.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-model-type-in-util-zone.grit"]
+    },
+    {
+      "includes": ["{apps,libs}/**/ui/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-async-component-in-ui.grit"]
+    },
+    {
+      "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/*.ts",
+        "{apps,libs}/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit"]
+    },
     {
       "includes": [
         "**/ui/**/*.ts",

package/biomeBase.ts

@@ -6,4 +6,4 @@ export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
 // Biome disagrees with the shipped base config therefore fails to load it at all, which is why the version is
 // pinned here instead of resolved to latest at create time. Bump this and `biome.base.json` in one commit, and run
 // `biome migrate --write` in the workspace root and in `pkgs/@akanjs/devkit` so both configs move together.
-export const biomeVersion = "2.5.8";
+export const biomeVersion = "2.5.12";

package/capacitorApp.ts

@@ -123,6 +123,16 @@ interface MaterializeCapacitorConfigOptions {
 }
 type MobilePlatform = "ios" | "android";
 
+/**
+ * `AppExecutor.spawn`'s own options plus the two the Capacitor config is written from before the spawn:
+ * the platform the command targets, and — for iOS — whether it targets a device or a simulator, which
+ * decide the `capacitor.config.json` that command reads.
+ */
+type SpawnMobileOptions = Parameters<AppExecutor["spawn"]>[2] & {
+  platform?: MobilePlatform;
+  iosRunTargetKind?: IosRunTargetKind;
+};
+
 export interface LocalDevHostResolution {
   host: string;
   source: "override" | "detected" | "loopback" | "platform";

package/cloud/globalConfig.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { chmod, mkdir } from "node:fs/promises";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import {
@@ -29,9 +29,16 @@ export class GlobalConfig {
       remoteEnvServers: akanConfig.remoteEnvServers ?? defaultAkanGlobalConfig.remoteEnvServers,
     };
   }
+  /**
+   * This file holds the cloud jwt, a refresh token that does not expire, and the LLM api key, so it is
+   * written owner-only — the same `0600` the runtime gives its control socket. `Bun.write` takes no mode
+   * and lands on `0666 & ~umask` (0644 on a default shell), so the mode is applied after the write; an
+   * existing world-readable file is tightened by the next write rather than left as it was found.
+   */
   static async #setAkanGlobalConfig(akanConfig: AkanGlobalConfig) {
-    await mkdir(basePath, { recursive: true });
+    await mkdir(basePath, { recursive: true, mode: 0o700 });
     await Bun.write(configPath, JSON.stringify(akanConfig, null, 2));
+    await chmod(configPath, 0o600);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();