@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/artifact/implicitRootLayout.ts

@@ -1,4 +1,3 @@
-import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
@@ -11,23 +10,17 @@ export interface PageEntry {
 
 const LAYOUT_KEY_RE = /^\.\/(.+\/)?_layout\.(tsx|ts|jsx|js)$/;
 
-async function appHasStModule(appCwdPath: string): Promise<boolean> {
-  return Bun.file(path.join(appCwdPath, "lib", "st.ts")).exists();
-}
-
 const IMPLICIT_LAYOUT_DIR = path.join(".akan", "generated", "root-layouts");
 const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
 const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
 const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
 
-/**
- * A `_overrides.tsx` manifest is a plain, server-safe module (`export default override({ Modal: BrandModal })`)
- * with no `"use client"` directive. The `UiOverrideProvider` that consumes it is a client component, so the
- * build emits a `"use client"` wrapper layout that reads the manifest's default map and mounts the provider
- * around the subtree. As a normal `"use client"` module the wrapper participates in client-entry discovery and
- * the RSC client manifest, so the server (as a client reference) and the client (as the real component) both
- * resolve it — and the author never writes `"use client"`.
- */
+const importSpecifier = (fromAbsPath: string, toAbsPath: string) => {
+  const rel = path.relative(path.dirname(fromAbsPath), toAbsPath).split(path.sep).join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+};
+
+// UiOverrideProvider is a client component, so `_overrides.tsx` mounts through a generated "use client" layout.
 async function writeGeneratedOverridesLayoutFile(opts: {
   appCwdPath: string;
   key: string;
@@ -35,12 +28,10 @@ async function writeGeneratedOverridesLayoutFile(opts: {
 }): Promise<string> {
   const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
   const absPath = path.join(path.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
-  const userRel = path.relative(path.dirname(absPath), opts.userAbsPath).split(path.sep).join("/");
-  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
   const source = `"use client";
 import { UiOverrideProvider } from "akanjs/ui";
 import { createElement, type ReactNode } from "react";
-import value from ${JSON.stringify(userSpecifier)};
+import value from ${JSON.stringify(importSpecifier(absPath, opts.userAbsPath))};
 
 export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
   return createElement(UiOverrideProvider, { value }, children);
@@ -73,10 +64,6 @@ function implicitRootLayoutAbsPath(appCwdPath: string, segments: string[]): stri
   return path.join(path.resolve(appCwdPath), IMPLICIT_LAYOUT_DIR, filename);
 }
 
-function implicitDictionaryMacroAbsPath(appCwdPath: string): string {
-  return path.join(path.resolve(appCwdPath), IMPLICIT_DICT_DIR, "useDict.ts");
-}
-
 export function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
   const firstVisibleIndex = segments.findIndex((segment) => !/^\(.+\)$/.test(segment));
   if (firstVisibleIndex === -1) return segments.length <= 1;
@@ -99,10 +86,7 @@ function findRootBoundaries(pageKeys: string[], appCwdPath: string, basePaths: I
       segments,
     });
   }
-  const hasExplicitRootBoundary = [...boundaries.values()].some((boundary) => boundary.segments.length === 0);
-  if (!hasExplicitRootBoundary && boundaries.size === 0) {
-    boundaries.set("", { sourceKey: null, sourceAbsPath: null, segments: [] });
-  }
+  if (boundaries.size === 0) boundaries.set("", { sourceKey: null, sourceAbsPath: null, segments: [] });
   return [...boundaries.values()].sort((a, b) => a.segments.join("/").localeCompare(b.segments.join("/")));
 }
 
@@ -123,11 +107,6 @@ function findExplicitRootLayoutAbsPath(pageKeys: string[], appCwdPath: string):
   return rootLayoutKey ? path.resolve(appCwdPath, "page", rootLayoutKey.replace(/^\.\//, "")) : null;
 }
 
-function routePrefixForSegments(segments: string[]): string | null {
-  const visible = segments.filter((segment) => !/^\(.+\)$/.test(segment));
-  return visible[0] ?? null;
-}
-
 async function assertEnvClientConvention(appCwdPath: string, appName: string) {
   const envPath = path.join(appCwdPath, "env", "env.client.ts");
   if (!(await Bun.file(envPath).exists())) {
@@ -138,8 +117,7 @@ async function assertEnvClientConvention(appCwdPath: string, appName: string) {
 }
 
 async function writeGeneratedDictionaryMacroFile(appCwdPath: string, appName: string): Promise<string> {
-  const absPath = implicitDictionaryMacroAbsPath(appCwdPath);
-  await mkdir(path.dirname(absPath), { recursive: true });
+  const absPath = path.join(path.resolve(appCwdPath), IMPLICIT_DICT_DIR, "useDict.ts");
   await Bun.write(
     absPath,
     `import { getAllDictionary } from "@apps/${appName}/lib/dict" with { type: "macro" };
@@ -163,35 +141,20 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? await writeGeneratedDictionaryMacroFile(opts.appCwdPath, opts.appName)
     : null;
   const absPath = implicitRootLayoutAbsPath(opts.appCwdPath, opts.boundary.segments);
-  await mkdir(path.dirname(absPath), { recursive: true });
-  const dictMacroRel = dictMacroAbsPath
-    ? path.relative(path.dirname(absPath), dictMacroAbsPath).split(path.sep).join("/")
-    : null;
-  const dictMacroSpecifier = dictMacroRel ? (dictMacroRel.startsWith(".") ? dictMacroRel : `./${dictMacroRel}`) : null;
-  const sourceRel = opts.boundary.sourceAbsPath
-    ? path.relative(path.dirname(absPath), opts.boundary.sourceAbsPath).split(path.sep).join("/")
-    : null;
-  const sourceSpecifier = sourceRel ? (sourceRel.startsWith(".") ? sourceRel : `./${sourceRel}`) : null;
+  const dictMacroSpecifier = dictMacroAbsPath ? importSpecifier(absPath, dictMacroAbsPath) : null;
+  const sourceSpecifier = opts.boundary.sourceAbsPath ? importSpecifier(absPath, opts.boundary.sourceAbsPath) : null;
   const inheritedSourceAbsPath =
     opts.rootSourceAbsPath && opts.rootSourceAbsPath !== opts.boundary.sourceAbsPath ? opts.rootSourceAbsPath : null;
-  const inheritedSourceRel = inheritedSourceAbsPath
-    ? path.relative(path.dirname(absPath), inheritedSourceAbsPath).split(path.sep).join("/")
-    : null;
-  const inheritedSourceSpecifier = inheritedSourceRel
-    ? inheritedSourceRel.startsWith(".")
-      ? inheritedSourceRel
-      : `./${inheritedSourceRel}`
-    : null;
+  const inheritedSourceSpecifier = inheritedSourceAbsPath ? importSpecifier(absPath, inheritedSourceAbsPath) : null;
   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.
+  //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
   const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
     ? `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 prefix = opts.boundary.segments.find((segment) => !/^\(.+\)$/.test(segment)) ?? null;
   const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
     ? `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`
@@ -200,9 +163,8 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? 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.
+  // React has no async client component, so CSR awaits an async layout's node; RSC keeps the element, since
+  // awaiting there would hold the shell behind the layout's own awaits instead of streaming it.
   const layoutSignature = isAsyncUserLayout
     ? "export default async function GeneratedLayout"
     : "export default function GeneratedLayout";
@@ -215,6 +177,19 @@ async function writeGeneratedRootLayoutFile(opts: {
     : "";
   const layoutChild = isAsyncUserLayout ? "{layout}" : userLayoutElement;
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
+  const layoutExports = `export async function generateHead(props: PageProps) {
+  if (userLayout.generateHead) return userLayout.generateHead(props);
+  if (userLayout.head !== undefined) return userLayout.head;
+  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);
+  return inheritedLayout.head;
+}
+
+export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
+export const Error = userLayout.Error ?? inheritedLayout.Error;
+export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
+
+${layoutSignature}({ children, params, searchParams }: LayoutProps) {
+${layoutBinding}  return `;
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
 import { loadFonts, resolveRouteModule } from "akanjs/client";
@@ -229,26 +204,7 @@ if (defaultFonts.length > 1) throw new Error("[route-convention] only one defaul
 const defaultFont = defaultFonts[0];
 const defaultFontClassName = defaultFont ? (defaultFont.className ?? \`font-\${defaultFont.name}\`) : undefined;
 
-export async function generateHead(props: PageProps) {
-  if (userLayout.generateHead) return userLayout.generateHead(props);
-  if (userLayout.head !== undefined) return userLayout.head;
-  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);
-  return inheritedLayout.head;
-}
-
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
-export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
-export const Error = userLayout.Error ?? inheritedLayout.Error;
-export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
-
-${layoutSignature}({ children, params, searchParams }: LayoutProps) {
-${layoutBinding}  return (
+${layoutExports}(
     <System.Provider
       of={GeneratedLayout as never}
       appName=${JSON.stringify(opts.appName)}
@@ -258,7 +214,6 @@ ${layoutBinding}  return (
       theme={userLayout.theme ?? inheritedLayout.theme}
       fonts={loadFonts(userFonts)}
       className={defaultFontClassName}
-      gaTrackingId={userLayout.gaTrackingId ?? inheritedLayout.gaTrackingId}
       layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}
       reconnect={userLayout.reconnect ?? inheritedLayout.reconnect ?? false}
       wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect ?? true}
@@ -273,36 +228,13 @@ ${layoutBinding}  return (
 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);
-  if (userLayout.head !== undefined) return userLayout.head;
-  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);
-  return inheritedLayout.head;
-}
-
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
-export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
-export const Error = userLayout.Error ?? inheritedLayout.Error;
-export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
-
-${layoutSignature}({ children, params, searchParams }: LayoutProps) {
-${layoutBinding}  return ${layoutReturn};
+${layoutExports}${layoutReturn};
 }
 `;
   await Bun.write(absPath, source);
   return absPath;
 }
 
-/**
- * When no root `page/_layout.*` exists on disk, merge a generated implicit root layout
- * (with generated client runtime registration and optional `void st` when `lib/st.ts` exists).
- */
 export async function resolveSsrPageEntries(opts: {
   appCwdPath: string;
   appName: string;
@@ -310,7 +242,7 @@ export async function resolveSsrPageEntries(opts: {
   basePaths?: Iterable<string>;
 }): Promise<PageEntry[]> {
   const absPageDir = path.resolve(opts.appCwdPath, "page");
-  const hasSt = await appHasStModule(opts.appCwdPath);
+  const hasSt = await Bun.file(path.join(opts.appCwdPath, "lib", "st.ts")).exists();
   const basePaths = opts.basePaths ?? [];
   const rootSourceAbsPath = findExplicitRootLayoutAbsPath(opts.pageKeys, opts.appCwdPath);
   const rootBoundaries = findRootBoundaries(opts.pageKeys, opts.appCwdPath, basePaths);
@@ -325,9 +257,7 @@ export async function resolveSsrPageEntries(opts: {
       .filter((key) => !rootLayoutKeys.has(key))
       .map(async (key) => {
         const userAbsPath = path.resolve(absPageDir, key);
-        // `_overrides.tsx` is served through a generated `"use client"` wrapper layout that mounts the provider,
-        // so the author writes no directive; the raw manifest becomes a build seed so its slot components (and
-        // the manifest itself) enter the client graph / RSC client manifest.
+        //? The raw manifest is a seed, so it and its slot components enter the client graph and RSC client manifest.
         if (OVERRIDES_KEY_RE.test(key)) {
           const moduleAbsPath = await writeGeneratedOverridesLayoutFile({
             appCwdPath: opts.appCwdPath,
@@ -353,9 +283,7 @@ export async function resolveSsrPageEntries(opts: {
       seedAbsPaths: [...new Set([boundary.sourceAbsPath, rootSourceAbsPath].filter((absPath) => absPath !== null))],
     })),
   );
-  const entries = [...base, ...generated];
-  entries.sort((a, b) => a.key.localeCompare(b.key));
-  return entries;
+  return [...base, ...generated].sort((a, b) => a.key.localeCompare(b.key));
 }
 
 export async function resolveSsrPageEntriesForApp(app: App, pageKeys: string[]): Promise<PageEntry[]> {

package/artifact/routeSeedIndex.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import path from "node:path";
 import { computeRouteSeedIndex, serializeRouteSeedIndexForArtifact } from "./routeSeedIndex";
 
 describe("computeRouteSeedIndex", () => {
@@ -19,10 +20,10 @@ describe("computeRouteSeedIndex", () => {
     ]);
 
     const leaf = index.entries.find((entry) => entry.routeId === "/:lang/foo");
-    expect(leaf?.seeds).toContain("/app/page/foo.tsx");
-    expect(leaf?.seeds).not.toContain("/app/page/foo/_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/page/_layout.tsx");
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/foo.tsx"));
+    expect(leaf?.seeds).not.toContain(path.resolve("/app/page/foo/_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/_layout.tsx"));
 
     expect(() =>
       computeRouteSeedIndex([
@@ -42,8 +43,8 @@ describe("computeRouteSeedIndex", () => {
       { key: "./robots.txt.tsx", moduleAbsPath: "/app/page/robots.txt.tsx" },
     ]);
     const robots = index.entries.find((entry) => entry.routeId === "/robots.txt");
-    expect(robots?.seeds).not.toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(robots?.seeds).not.toContain("/app/page/_layout.tsx");
+    expect(robots?.seeds).not.toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(robots?.seeds).not.toContain(path.resolve("/app/page/_layout.tsx"));
   });
 
   test("serializes seed paths relative to the artifact directory", () => {

package/artifact/routeSeedIndex.ts

@@ -1,29 +1,13 @@
 import path from "node:path";
 import { assertUniqueRoutePatterns, compareRouteSpecificity, parseRouteModuleKey } from "akanjs/common";
+import {
+  ROUTE_SEED_INDEX_JSON,
+  type RouteSeedEntry,
+  type RouteSeedIndex,
+} from "akanjs/server/artifact/routeSeedIndexStore";
 import type { PageEntry } from "./implicitRootLayout";
 
-/**
- * Build-time utilities for the route seed index. `computeRouteSeedIndex`
- * takes resolved `PageEntry` rows (`key` plus absolute module path — files
- * under `app/` or the generated implicit root layout) and produces — for every
- * route — the list of source files that seed the `"use client"` graph walk.
- *
- * The result is serialized to `route-seed-index.json` by
- * `saveRouteSeedIndex` so the runtime server can call
- * `loadRouteSeedIndex` to restore it without re-importing `pages.ts`
- * (which no longer exists) or reparsing loader sources.
- */
-
-export interface RouteSeedEntry {
-  routeId: string;
-  pattern: string;
-  seeds: string[];
-}
-
-export interface RouteSeedIndex {
-  entries: RouteSeedEntry[];
-  globalLayoutFiles: string[];
-}
+export { ROUTE_SEED_INDEX_JSON, type RouteSeedEntry, type RouteSeedIndex };
 
 export type SerializedRouteSeedEntry = Pick<RouteSeedEntry, "routeId"> &
   Partial<Pick<RouteSeedEntry, "pattern" | "seeds">>;
@@ -33,10 +17,6 @@ export interface SerializedRouteSeedIndex {
   globalLayoutFiles?: string[];
 }
 
-/**
- * Compute the route seed index from `PageEntry`s (disk paths or generated
- * implicit root layout absolute paths).
- */
 export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex {
   const layoutsByPrefix = new Map<string, string[]>();
   const pagesBySegments: Array<{
@@ -51,11 +31,8 @@ export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex
     const parsed = parseRouteModuleKey(key);
     const files = [path.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path.resolve(seed))];
     if (parsed.kind === "layout" || parsed.kind === "overrides") {
-      // Overrides seed the client graph like layouts: every route under the prefix must pull the generated
-      // `"use client"` override wrapper (and its slot components) into the client bundle / RSC client manifest.
-      const prefix = parsed.routeSegments.join("/");
-      const prev = layoutsByPrefix.get(prefix) ?? [];
-      layoutsByPrefix.set(prefix, [...prev, ...files]);
+      //? Every route under an overrides prefix needs its "use client" wrapper in the client graph, as with a layout.
+      layoutsByPrefix.getOrInsert(parsed.routeSegments.join("/"), []).push(...files);
     } else if (parsed.kind === "page") {
       pagesBySegments.push({
         key,
@@ -68,9 +45,7 @@ export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex
   }
   assertUniqueRoutePatterns(pagesBySegments);
 
-  const rootLayouts = layoutsByPrefix.get("") ?? [];
-  const globalLayoutFiles = rootLayouts;
-
+  const globalLayoutFiles = layoutsByPrefix.get("") ?? [];
   const seedEntries: RouteSeedEntry[] = [];
   for (const { pattern, segments, files, includeOwnLayout } of pagesBySegments) {
     const layouts: string[] = [];
@@ -84,26 +59,18 @@ export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex
     const routeId = pattern || "/";
     seedEntries.push({ routeId, pattern: routeId, seeds });
   }
-  // Static segments must beat `:param` ones at match time, otherwise
-  // `/persona/new` resolves to `[personaId]=new`. Sort once at build time
-  // so the runtime matcher can stay first-match-wins.
+  // Static segments must beat `:param` ones (`/persona/new` is not `[personaId]=new`); the runtime is first-match-wins.
   seedEntries.sort((a, b) => compareRouteSpecificity(a.pattern, b.pattern));
   return { entries: seedEntries, globalLayoutFiles };
 }
 
-export const ROUTE_SEED_INDEX_JSON = "route-seed-index.json";
-
 export function serializeRouteSeedIndexForArtifact(
   index: RouteSeedIndex,
   artifactDir: string,
   options: { production?: boolean } = {},
 ): SerializedRouteSeedIndex {
   const normalizedArtifactDir = path.resolve(artifactDir);
-  if (options.production) {
-    return {
-      entries: index.entries.map((entry) => ({ routeId: entry.routeId })),
-    };
-  }
+  if (options.production) return { entries: index.entries.map((entry) => ({ routeId: entry.routeId })) };
   return {
     entries: index.entries.map((entry) => ({
       ...entry,

package/biome.base.json

@@ -154,7 +154,12 @@
       ]
     },
     {
-      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
     },
     {

package/biomeBase.ts

@@ -1,9 +1,6 @@
 /** `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.
+// Pinned: Biome moves rules between groups across minors and a stale position is a hard config error. Bump it with
+// `biome.base.json` in one commit, running `biome migrate --write` in the workspace root and in this package.
 export const biomeVersion = "2.5.12";

package/capacitorApp.test.ts

@@ -1,6 +1,5 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { AkanMobileTargetConfig } from "./akanConfig";
 import {
@@ -24,16 +23,12 @@ import {
   sanitizeIosNativeRunEnv,
   selectLocalDevHost,
   sortIosRunTargets,
+  toIosInfoPlistUsageDescriptions,
   writeRootCapacitorConfig,
 } from "./capacitorApp";
+import { tempDirs } from "./testHelpers";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-capacitor-app-"));
-  tempRoots.push(root);
-  return root;
-};
+const makeTempRoot = tempDirs("akan-capacitor-app-");
 
 const baseTarget: AkanMobileTargetConfig = {
   name: "default",
@@ -49,10 +44,6 @@ const baseTarget: AkanMobileTargetConfig = {
   files: { android: { "app/google-services.json": "private/google-services.json" } },
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("materializeCapacitorConfig", () => {
   test("writes only Capacitor fields for release config", () => {
     const config = materializeCapacitorConfig(
@@ -234,7 +225,7 @@ describe("iOS native run helpers", () => {
     expect(deviceCommand.xcodebuildArgs).toContain("id=device-1");
     expect(deviceCommand.xcodebuildArgs).toContain("App QA");
     expect(deviceCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app"),
     );
 
     const simulatorCommand = buildIosNativeRunCommand({
@@ -243,7 +234,7 @@ describe("iOS native run helpers", () => {
     });
     expect(simulatorCommand.xcodebuildArgs).toContain("platform=iOS Simulator,id=sim-1");
     expect(simulatorCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app"),
     );
   });
 
@@ -370,3 +361,28 @@ describe("raiseGradleMinSdkVersion", () => {
     expect(raiseGradleMinSdkVersion("minSdkVersion = 28", 26)).toBeNull();
   });
 });
+
+describe("toIosInfoPlistUsageDescriptions", () => {
+  test("writes Apple's real Info.plist keys, not NS + the description name", () => {
+    expect(
+      toIosInfoPlistUsageDescriptions({
+        cameraUsageDescription: "camera",
+        photoAddUsageDescription: "add",
+        photoUsageDescription: "read",
+        locationAlwaysUsageDescription: "always",
+      }),
+    ).toEqual({
+      NSCameraUsageDescription: "camera",
+      NSPhotoLibraryAddUsageDescription: "add",
+      NSPhotoLibraryUsageDescription: "read",
+      NSLocationAlwaysAndWhenInUseUsageDescription: "always",
+      NSLocationAlwaysUsageDescription: "always",
+    });
+  });
+
+  test("keeps the NS prefix convention for a key it does not know", () => {
+    expect(toIosInfoPlistUsageDescriptions({ bluetoothAlwaysUsageDescription: "ble" })).toEqual({
+      NSBluetoothAlwaysUsageDescription: "ble",
+    });
+  });
+});