@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.81

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: "📝",
 };
@@ -56,7 +63,6 @@ const SSR_RENDER_EXTERNALS = [
 export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",
@@ -78,6 +84,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 +99,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 +185,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 +194,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}`);
@@ -188,17 +208,20 @@ export class ApplicationBuildRunner {
       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,
-      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: true,
+          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,
@@ -209,8 +232,9 @@ export class ApplicationBuildRunner {
     });
     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", () => {

package/biome.base.json

@@ -0,0 +1,340 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noConsole": {
+          "level": "error",
+          "options": {
+            "allow": ["assert", "error", "info", "warn"]
+          }
+        },
+        "noArrayIndexKey": "off",
+        "noShadowRestrictedNames": "off",
+        "noUnnecessaryConditions": {
+          "level": "warn"
+        }
+      },
+      "correctness": {
+        "noUnusedFunctionParameters": "off",
+        "noUnusedImports": {
+          "level": "error",
+          "fix": "safe"
+        },
+        "useParseIntRadix": "off",
+        "useExhaustiveDependencies": "off",
+        "useHookAtTopLevel": "off"
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "error",
+          "fix": "safe",
+          "options": {
+            "attributes": ["classList"],
+            "functions": ["cn"]
+          }
+        }
+      },
+      "a11y": "off",
+      "complexity": {
+        "noStaticOnlyClass": "off"
+      },
+      "style": {
+        "useTemplate": {
+          "level": "warn",
+          "fix": "safe"
+        }
+      }
+    },
+    "domains": {
+      "project": "recommended",
+      "react": "recommended",
+      "test": "recommended",
+      "types": "all"
+    }
+  },
+  "javascript": {
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    },
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": [
+        "**/env.client.local.ts",
+        "**/env.client.debug.ts",
+        "**/env.client.develop.ts",
+        "**/env.client.main.ts",
+        "**/env.client.testing.ts",
+        "**/env.server.local.ts",
+        "**/env.server.develop.ts",
+        "**/env.server.main.ts",
+        "**/env.server.testing.ts",
+        "**/env.server.type.ts",
+        "apps/*/lib/cnst.ts",
+        "apps/*/lib/dict.ts",
+        "apps/*/lib/db.ts",
+        "apps/*/lib/srv.ts",
+        "apps/*/lib/st.ts",
+        "apps/*/lib/sig.ts",
+        "apps/*/lib/useClient.ts",
+        "apps/*/lib/useServer.ts",
+        "apps/*/client.ts",
+        "apps/*/server.ts",
+        "apps/*/lib/*/index.tsx",
+        "libs/*/lib/cnst.ts",
+        "libs/*/lib/dict.ts",
+        "libs/*/lib/db.ts",
+        "libs/*/lib/srv.ts",
+        "libs/*/lib/st.ts",
+        "libs/*/lib/sig.ts",
+        "libs/*/lib/useClient.ts",
+        "libs/*/lib/useServer.ts",
+        "libs/*/client.ts",
+        "libs/*/server.ts",
+        "libs/*/index.ts",
+        "libs/*/lib/*/index.tsx",
+        "apps/*/lib/__lib/**",
+        "libs/*/lib/__lib/**"
+      ],
+      "linter": { "enabled": false },
+      "formatter": { "enabled": false },
+      "assist": { "enabled": false }
+    },
+    {
+      "includes": [
+        "apps/**/*.ts",
+        "apps/**/*.tsx",
+        "libs/**/*.ts",
+        "libs/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx",
+        "!**/*.constant.ts",
+        "!**/common/**",
+        "!**/env/**"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
+        "./node_modules/@akanjs/devkit/lint/no-use-client-in-server.grit"
+      ]
+    },
+    {
+      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.store.ts"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
+    },
+    {
+      "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",
+        "**/ui/**/*.tsx",
+        "**/webkit/**/*.ts",
+        "**/webkit/**/*.tsx",
+        "**/common/**/*.ts",
+        "**/page/**/*.tsx",
+        "**/*.constant.ts",
+        "**/*.store.ts",
+        "**/*.Template.tsx",
+        "**/*.Unit.tsx",
+        "**/*.Util.tsx",
+        "**/*.View.tsx",
+        "**/*.Zone.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-bang-comment-in-client.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"]
+    },
+    {
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/index.ts",
+        "{apps,libs}/**/index.tsx",
+        "{apps,libs}/**/cnst.ts",
+        "{apps,libs}/**/db.ts",
+        "{apps,libs}/**/dict.ts",
+        "{apps,libs}/**/option.ts",
+        "{apps,libs}/**/sig.ts",
+        "{apps,libs}/**/srv.ts",
+        "{apps,libs}/**/st.ts",
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.signal.test.ts",
+        "{apps,libs}/**/*.service.test.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-import-external-library.grit",
+        "./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"
+      ]
+    },
+    {
+      "includes": [
+        "apps/**/*.tsx",
+        "libs/**/*.tsx",
+        "apps/**/ui/**/*.ts",
+        "libs/**/ui/**/*.ts",
+        "apps/**/webkit/**/*.ts",
+        "libs/**/webkit/**/*.ts",
+        "apps/**/page/**/*.ts",
+        "libs/**/page/**/*.ts",
+        "apps/**/common/**/*.ts",
+        "libs/**/common/**/*.ts",
+        "apps/**/*.store.ts",
+        "libs/**/*.store.ts",
+        "apps/**/*.constant.ts",
+        "libs/**/*.constant.ts",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-server-in-client.grit"]
+    },
+    {
+      "includes": [
+        "apps/**/*.document.ts",
+        "libs/**/*.document.ts",
+        "apps/**/*.dictionary.ts",
+        "libs/**/*.dictionary.ts",
+        "apps/**/*.service.ts",
+        "libs/**/*.service.ts",
+        "apps/**/*.signal.ts",
+        "libs/**/*.signal.ts",
+        "apps/**/srvkit/**/*.ts",
+        "libs/**/srvkit/**/*.ts",
+        "apps/**/common/**/*.ts",
+        "libs/**/common/**/*.ts",
+        "apps/**/*.constant.ts",
+        "libs/**/*.constant.ts",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-client-in-server.grit"]
+    },
+    {
+      "includes": [
+        "apps/**/*.ts",
+        "apps/**/*.tsx",
+        "libs/**/*.ts",
+        "libs/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-raw-palette-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-arbitrary-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-daisyui-legacy-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-inline-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-interpolated-arbitrary-class.grit"
+      ]
+    }
+  ]
+}

package/biomeBase.ts

@@ -0,0 +1,9 @@
+/** `extends` target for a workspace `biome.json`; Biome resolves it through node_modules. */
+export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
+
+// Biome moves rules between groups across minors — `noUnnecessaryConditions` sat in `nursery` at 2.4 and moved to
+// `suspicious` at 2.5 — and the stale position is a hard "unknown key" error, not a warning. A workspace whose
+// 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";

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";