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

package/applicationBuildRunner.ts

@@ -60,9 +60,8 @@ 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.
+// Mangling renames classes, and `this.constructor.name` names loggers, exceptions and guards; `minify.keepNames`
+// is a no-op 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 = [
@@ -77,6 +76,7 @@ export class ApplicationBuildRunner {
   #app: App;
   #fast: boolean;
   #reporter?: BuildProgressReporter;
+  #spinner?: boolean;
   #startedAt = Date.now();
   #phases: BuildPhaseResult[] = [];
 
@@ -88,18 +88,15 @@ 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 };
+    this.#spinner = spinner;
     const { web, assets } = await this.#app.getConfig();
-    await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
-      spinner,
-    });
-    if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck(), undefined, phaseOptions);
+    await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));
+    if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck());
     await this.#runPhase(
       "backend",
       "Compiling backend",
       () => this.#buildBackend(),
       (result) => `${result.entrypoints} entrypoints, ${result.outputs} outputs`,
-      phaseOptions,
     );
     await this.#runPhase(
       "ssr",
@@ -111,14 +108,12 @@ export class ApplicationBuildRunner {
           : web.ssr
             ? "skipped"
             : "disabled by akan.config.ts web.ssr",
-      phaseOptions,
     );
     await this.#runPhase(
       "csr",
       "Building CSR assets",
-      async () => (web.csr ? await this.#buildCsr() : null),
+      async () => (web.csr ? await new CsrArtifactBuilder(this.#app, "build").build() : null),
       (result) => result?.outputDir ?? (web.csr ? "skipped" : "disabled by akan.config.ts web.csr"),
-      phaseOptions,
     );
     await this.#runPhase(
       "assets",
@@ -128,7 +123,6 @@ export class ApplicationBuildRunner {
         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(
       "compress",
@@ -138,11 +132,8 @@ export class ApplicationBuildRunner {
         result.files > 0
           ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
-      phaseOptions,
     );
-    await this.#runPhase("metadata", "Writing production metadata", () => this.#buildAppMeta(), undefined, {
-      spinner,
-    });
+    await this.#runPhase("metadata", "Writing production metadata", () => this.#buildAppMeta());
     return {
       phases: this.#phases,
       durationMs: Date.now() - this.#startedAt,
@@ -154,7 +145,7 @@ export class ApplicationBuildRunner {
   async typecheck(options: TypecheckOptions = {}) {
     const { clean = false, incremental = true } = options;
     await this.#app.getPageKeys({ refresh: true });
-    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig({ incremental });
+    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig(incremental);
     if (clean) await rm(path.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
     await this.#checkProjectInChildProcess(tsconfigPath);
   }
@@ -164,19 +155,17 @@ export class ApplicationBuildRunner {
     label: string,
     task: () => Promise<T>,
     summarize?: (result: T) => string | undefined,
-    options: BuildPhaseRunOptions = {},
   ) {
     this.#reporter?.phaseStart?.({ id, label });
     const phaseStartedAt = Date.now();
-    const spinner = options.spinner
+    const spinner = this.#spinner
       ? new Spinner(label, { prefix: `${BUILD_PHASE_EMOJIS[id]} ${id}` }).start()
       : undefined;
     try {
       const result = await task();
       const phase = { id, label, durationMs: Date.now() - phaseStartedAt, summary: summarize?.(result) };
       this.#phases.push(phase);
-      const summary = phase.summary ? `: ${phase.summary}` : "";
-      spinner?.succeed(`${label}${summary}`);
+      spinner?.succeed(`${label}${phase.summary ? `: ${phase.summary}` : ""}`);
       this.#reporter?.phaseDone?.(phase);
       return result;
     } catch (error) {
@@ -215,57 +204,43 @@ export class ApplicationBuildRunner {
   }
 
   async #buildBackend() {
-    const akanConfig = await this.#app.getConfig();
-    const backendExternals = [
-      ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
-    ];
-    const { web } = akanConfig;
+    const { externalLibs, web } = await this.#app.getConfig();
     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}`);
     }
-    const backendConfig = {
+    const sharedConfig = {
       outdir: this.#app.dist.cwdPath,
       target: "bun",
       minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+      // `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)] : [],
     } satisfies Omit<Bun.BuildConfig, "entrypoints">;
-    //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot
-    //* parse (minimal: server.js import 79ms → 24ms, 59MB → 36MB RSS).
+    const backendConfig = { ...sharedConfig, plugins: [this.#createExternalSpecifiersPlugin(externalLibs)] };
+    //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot parse.
     const [mainResult, serverResult] = [
       await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[0]] }),
       await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[1]], splitting: true }),
     ];
-    const backendResult = { outputs: [...mainResult.outputs, ...serverResult.outputs] };
     // 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", {
+          ...backendConfig,
           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", {
+      ...sharedConfig,
       entrypoints: [this.#resolveConsoleRuntimeBuildEntry()],
-      outdir: this.#app.dist.cwdPath,
-      target: "bun",
-      minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "console-runtime.[ext]", chunk: "chunk-[hash].[ext]" },
-      define: { "process.env.NODE_ENV": JSON.stringify("production") },
     });
     await this.#writeConsoleShim();
+    const results = [mainResult, serverResult, rscWorkerResult, consoleRuntimeResult];
     return {
       entrypoints: backendEntryPoints.length + (rscWorkerResult ? 2 : 1),
-      outputs:
-        backendResult.outputs.length + (rscWorkerResult?.outputs.length ?? 0) + consoleRuntimeResult.outputs.length + 1,
+      outputs: results.reduce((sum, result) => sum + (result?.outputs.length ?? 0), 1),
     };
   }
 
@@ -310,10 +285,6 @@ void run().catch((error) => {
     }
   }
 
-  async #buildCsr() {
-    return await new CsrArtifactBuilder(this.#app, "build").build();
-  }
-
   async #buildSsr() {
     const pageKeys = await this.#app.getPageKeys();
     if (pageKeys.length === 0) {
@@ -325,7 +296,7 @@ void run().catch((error) => {
     return { base, allRoutes };
   }
 
-  async #writeTypecheckTsconfig({ incremental = true }: TypecheckOptions = {}) {
+  async #writeTypecheckTsconfig(incremental: boolean) {
     const typecheckDir = path.join(this.#app.cwdPath, ".akan", "typecheck");
     await mkdir(typecheckDir, { recursive: true });
     //* TypeScript's `include` globs do not cross a symlink, so synced lib pages need their real path.
@@ -394,11 +365,10 @@ void run().catch((error) => {
     return result;
   }
 
-  #createExternalSpecifiersPlugin(specifiers: readonly string[]): BunPlugin {
-    const uniqueSpecifiers = [...new Set(specifiers)];
-    const escaped = uniqueSpecifiers.map((specifier) => specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  #createExternalSpecifiersPlugin(externalLibs: readonly string[]): BunPlugin {
+    const specifiers = new Set([...externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]);
+    const escaped = [...specifiers].map((specifier) => specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
     const filter = new RegExp(`^(${escaped.join("|")})(?:/.*)?$`);
-
     return {
       name: "akan-backend-externalize-specifiers",
       setup(build) {
@@ -407,9 +377,5 @@ void run().catch((error) => {
     };
   }
 
-  static formatBytes(bytes: number): string {
-    if (bytes < 1024) return `${bytes}B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
-  }
+  static formatBytes = FontPruner.formatBytes;
 }

package/applicationReleasePackager.ts

@@ -63,13 +63,7 @@ export class ApplicationReleasePackager {
     await rm(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
 
     const releaseRoot = this.#app.workspace.workspaceRoot;
-    // Pass a path relative to cwd so tar never sees a Windows drive letter (e.g. "C:\...")
-    // which GNU tar would interpret as a remote "host:file" spec.
-    const releaseArchivePath = path
-      .relative(releaseRoot, `${releaseRoot}/releases/builds/${this.#app.name}-release.tar.gz`)
-      .split(path.sep)
-      .join("/");
-    await this.#app.workspace.spawn("tar", ["-zcf", releaseArchivePath, "-C", buildRoot, "./"], { cwd: releaseRoot });
+    await this.#tar(releaseRoot, `${releaseRoot}/releases/builds/${this.#app.name}-release.tar.gz`, buildRoot);
     await this.#writeCsrZipIfPresent();
     return { platformVersion };
   }
@@ -112,26 +106,19 @@ export class ApplicationReleasePackager {
     await this.#writeSourceTsconfig(sourceRoot, libDeps);
     await Bun.write(`${sourceRoot}/README.md`, readme);
     const sourceCwd = this.#app.workspace.cwdPath;
-    // Pass a path relative to cwd so tar never sees a Windows drive letter (e.g. "C:\...")
-    // which GNU tar would interpret as a remote "host:file" spec.
-    const sourceArchivePath = path
-      .relative(sourceCwd, `${sourceCwd}/releases/sources/${this.#app.name}-source.tar.gz`)
-      .split(path.sep)
-      .join("/");
-    await this.#app.workspace.spawn("tar", ["-zcf", sourceArchivePath, "-C", sourceRoot, "./"], { cwd: sourceCwd });
+    await this.#tar(sourceCwd, `${sourceCwd}/releases/sources/${this.#app.name}-source.tar.gz`, sourceRoot);
+  }
+
+  async #tar(cwd: string, archivePath: string, sourceDir: string) {
+    // Relative to cwd so tar never sees a Windows drive letter ("C:\..."), which GNU tar reads as a remote "host:file".
+    const relativeArchivePath = path.relative(cwd, archivePath).split(path.sep).join("/");
+    await this.#app.workspace.spawn("tar", ["-zcf", relativeArchivePath, "-C", sourceDir, "./"], { cwd });
   }
 
   async #resetSourceRoot(sourceRoot: string): Promise<void> {
-    if (await FileSys.dirExists(sourceRoot)) {
-      const maxRetry = 3;
-      for (let i = 0; i < maxRetry; i++) {
-        try {
-          await rm(sourceRoot, { recursive: true, force: true });
-        } catch {
-          //
-        }
-      }
-    }
+    if (await FileSys.dirExists(sourceRoot))
+      for (let attempt = 0; attempt < 3; attempt++)
+        await rm(sourceRoot, { recursive: true, force: true }).catch(() => undefined);
     await mkdir(sourceRoot, { recursive: true });
   }
 
@@ -147,6 +134,17 @@ export class ApplicationReleasePackager {
     await Bun.write(`${sourceRoot}/tsconfig.json`, JSON.stringify(tsconfig, null, 2));
   }
 
+  static #envSetup = `  cat <<EOF >> .env
+  # ENV For Server => debug | debug.local | develop | develop.local | main | main.local
+  SERVER_ENV=debug.local
+  # Run Mode For Server => federation | batch | all
+  SERVER_MODE=federation
+  # ENV For Client => debug | debug.local | develop | develop.local | main | main.local
+  AKAN_PUBLIC_CLIENT_ENV=debug.local
+  ANALYZE=false
+  EOF
+`;
+
   #confidentialReadme(): string {
     return `# ${this.#app.name}
   본 프로젝트의 소스코드 및 관련자료는 모두 비밀정보로 관리됩니다.
@@ -157,16 +155,7 @@ export class ApplicationReleasePackager {
   bun install -g bun
   bun i
 
-  cat <<EOF >> .env
-  # ENV For Server => debug | debug.local | develop | develop.local | main | main.local
-  SERVER_ENV=debug.local
-  # Run Mode For Server => federation | batch | all
-  SERVER_MODE=federation
-  # ENV For Client => debug | debug.local | develop | develop.local | main | main.local
-  AKAN_PUBLIC_CLIENT_ENV=debug.local
-  ANALYZE=false
-  EOF
-
+${ApplicationReleasePackager.#envSetup}
   akn start-backend ${this.#app.name}
   # or akn start-frontend ${this.#app.name}, etc
   \`\`\`
@@ -185,16 +174,7 @@ export class ApplicationReleasePackager {
   ## Get Started
   Run the code below.
   \`\`\`
-  cat <<EOF >> .env
-  # ENV For Server => debug | debug.local | develop | develop.local | main | main.local
-  SERVER_ENV=debug.local
-  # Run Mode For Server => federation | batch | all
-  SERVER_MODE=federation
-  # ENV For Client => debug | debug.local | develop | develop.local | main | main.local
-  AKAN_PUBLIC_CLIENT_ENV=debug.local
-  ANALYZE=false
-  EOF
-
+${ApplicationReleasePackager.#envSetup}
   akan start ${this.#app.name}
   \`\`\`
 

package/applicationTestPreload.ts

@@ -8,7 +8,7 @@ export interface SignalTestPreloadTarget {
 
 export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarget) {
   const candidates: string[] = [];
-  const addResolvedPackageCandidate = (basePath: string) => {
+  for (const basePath of [target.cwdPath, process.cwd(), path.dirname(Bun.main), import.meta.dir]) {
     try {
       candidates.push(
         path.join(path.dirname(Bun.resolveSync("akanjs/package.json", basePath)), SIGNAL_TEST_PRELOAD_PATH),
@@ -16,13 +16,7 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
     } catch {
       // Source workspaces and published installs can resolve Akan packages from different roots.
     }
-  };
-
-  addResolvedPackageCandidate(target.cwdPath);
-  addResolvedPackageCandidate(process.cwd());
-  addResolvedPackageCandidate(path.dirname(Bun.main));
-  addResolvedPackageCandidate(import.meta.dir);
-
+  }
   candidates.push(
     path.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH),
     path.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH),
@@ -33,10 +27,7 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
   );
 
   const uniqueCandidates = [...new Set(candidates)];
-  for (const candidate of uniqueCandidates) {
-    if (await Bun.file(candidate).exists()) return candidate;
-  }
-
+  for (const candidate of uniqueCandidates) if (await Bun.file(candidate).exists()) return candidate;
   throw new Error(
     `Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.\nProbed paths:\n${uniqueCandidates
       .map((candidate) => `  - ${candidate}`)

package/artifact/implicitRootLayout.test.ts

@@ -1,25 +1,9 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
 import { resolveSsrPageEntries } from "./implicitRootLayout";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-implicit-root-layout-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const makeTempRoot = tempDirs("akan-implicit-root-layout-");
 
 describe("resolveSsrPageEntries", () => {
   test("inherits root layout static exports for grouped root boundaries", async () => {

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,19 +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 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)}
@@ -265,29 +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 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;
@@ -295,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);
@@ -310,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,
@@ -338,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[]> {