@akanjs/cli 2.3.11-rc.1 → 2.3.11-rc.10

package/incrementalBuilder.proc.js

@@ -666,6 +666,7 @@ import {
 import { readFileSync as readFileSync3 } from "fs";
 import { copyFile, mkdir as mkdir2, readdir as readDirEntries, stat as stat2 } from "fs/promises";
 import path7 from "path";
+import { pathToFileURL } from "url";
 import {
   capitalize,
   isRouteSourceFile,
@@ -1107,6 +1108,63 @@ var decreaseBuildNum = async (app) => {
   const akanConfigContent = akanConfig.replace(`buildNum: ${appConfig.mobile.buildNum}`, `buildNum: ${appConfig.mobile.buildNum - 1}`);
   fs.writeFileSync(akanConfigPath, akanConfigContent);
 };
+// pkgs/@akanjs/devkit/firebaseMessagingSw.ts
+var FIREBASE_WEB_SDK_VERSION = "12.13.0";
+function normalizeFirebaseClientConfig(config) {
+  if (!config || typeof config !== "object")
+    return null;
+  const value = config;
+  if (typeof value.apiKey !== "string" || typeof value.projectId !== "string" || typeof value.messagingSenderId !== "string" || typeof value.appId !== "string") {
+    return null;
+  }
+  return {
+    apiKey: value.apiKey,
+    ...typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {},
+    projectId: value.projectId,
+    ...typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {},
+    messagingSenderId: value.messagingSenderId,
+    appId: value.appId
+  };
+}
+function createFirebaseMessagingServiceWorker(config) {
+  const configJson = JSON.stringify(config);
+  return `/* Generated by Akan.js. Do not edit. */
+const firebaseConfig = ${configJson};
+
+if (firebaseConfig) {
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
+
+  firebase.initializeApp(firebaseConfig);
+  const messaging = firebase.messaging();
+
+  const notificationUrl = (payload) =>
+    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
+
+  messaging.onBackgroundMessage((payload) => {
+    const title = payload?.notification?.title || "";
+    const options = {
+      body: payload?.notification?.body,
+      icon: payload?.notification?.icon,
+      image: payload?.notification?.image,
+      data: {
+        url: notificationUrl(payload),
+        FCM_MSG: payload,
+      },
+    };
+    self.registration.showNotification(title, options);
+  });
+}
+
+self.addEventListener("notificationclick", (event) => {
+  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
+  event.notification?.close();
+  if (!url) return;
+  event.waitUntil(clients.openWindow(url));
+});
+`;
+}
+
 // pkgs/@akanjs/devkit/getDirname.ts
 import path2 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -1392,6 +1450,7 @@ ${errorText}, ${warningText} found`];
 
 // pkgs/@akanjs/devkit/scanInfo.ts
 import path5 from "path";
+import { rm } from "fs/promises";
 
 // pkgs/@akanjs/devkit/dependencyScanner.ts
 import { builtinModules } from "module";
@@ -1710,8 +1769,10 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
+var generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"];
 var appRootAllowedDirs = new Set([
   ".akan",
   "android",
@@ -1755,11 +1816,17 @@ var rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 var isAllowedTestFile = (filename) => testFilePattern.test(filename);
 var isAllowedLibRootFile = (filename) => libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 var getScanPath = (exec, relativePath) => path5.posix.join(`${exec.type}s`, exec.name, relativePath.split(path5.sep).join("/"));
+async function clearGeneratedRootCapacitorConfigs(exec) {
+  if (exec.type !== "app")
+    return;
+  await Promise.all(generatedRootCapacitorConfigFiles.map((filename) => rm(exec.getPath(filename), { force: true })));
+}
 var getModuleNameFromPath = (kind, modulePath) => {
   const dirname = path5.basename(modulePath);
   return kind === "service" ? dirname.replace(/^_+/, "") : dirname;
 };
 async function assertScanConvention(exec, libRoot) {
+  await clearGeneratedRootCapacitorConfigs(exec);
   const violations = [];
   const addViolation = (relativePath, reason) => {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);
@@ -2624,6 +2691,31 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
     throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
   }
 }
+function validateOverridesSourceExports(source, filePath) {
+  const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const fail = (message) => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride = null;
+  for (const statement of sourceFile.statements) {
+    if (ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression))
+      continue;
+    if (ts3.isImportDeclaration(statement))
+      continue;
+    if (ts3.isInterfaceDeclaration(statement) || ts3.isTypeAliasDeclaration(statement))
+      continue;
+    if (ts3.isExportAssignment(statement) && !statement.isExportEquals) {
+      defaultOverride = statement;
+      continue;
+    }
+    fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
+  }
+  if (!defaultOverride)
+    fail(`_overrides.tsx must "export default override({ ... })"`);
+  const expression = defaultOverride.expression;
+  if (!ts3.isCallExpression(expression) || !ts3.isIdentifier(expression.expression) || expression.expression.text !== "override")
+    fail(`_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`);
+}
 
 class Executor {
   static verbose = false;
@@ -3576,6 +3668,8 @@ class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}
     });
+    if (type === "build")
+      Object.assign(process.env, env);
     return { env };
   }
   #publicEnv = null;
@@ -3645,7 +3739,11 @@ class AppExecutor extends SysExecutor {
         throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
       }
       const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
-      validateRouteSourceExports(await Bun.file(absPath).text(), absPath, parsed.kind, { rootLayout: isRootLayout });
+      const routeSource = await Bun.file(absPath).text();
+      if (parsed.kind === "overrides")
+        validateOverridesSourceExports(routeSource, absPath);
+      else
+        validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
       pageKeys.push(key);
     }
     pageKeys.sort();
@@ -3686,8 +3784,30 @@ class AppExecutor extends SysExecutor {
     });
     if (write)
       await this.syncAssets(scanInfo.getScanResult().libDeps);
+    if (write)
+      await this.#syncFirebaseMessagingSw();
     return scanInfo;
   }
+  async#syncFirebaseMessagingSw() {
+    const swRelPath = "public/firebase-messaging-sw.js";
+    if (await FileSys.fileExists(this.getPath(swRelPath)))
+      return;
+    const envClientPath = path7.join(this.cwdPath, "env", "env.client.ts");
+    if (!await FileSys.fileExists(envClientPath))
+      return;
+    let firebaseConfig = null;
+    try {
+      const envUrl = pathToFileURL(envClientPath);
+      envUrl.searchParams.set("t", String(Date.now()));
+      const envModule = await import(envUrl.href);
+      firebaseConfig = normalizeFirebaseClientConfig(envModule.env?.firebase);
+    } catch {
+      return;
+    }
+    if (!firebaseConfig)
+      return;
+    await this.writeFile(swRelPath, createFirebaseMessagingServiceWorker(firebaseConfig), { overwrite: false });
+  }
   async increaseBuildNum() {
     await increaseBuildNum(this);
   }
@@ -4170,6 +4290,7 @@ var BACKEND_RESTART_DEBOUNCE_MS = 120;
 var BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
 var BACKEND_RECOVERY_BASE_DELAY_MS = 1000;
 var BACKEND_RECOVERY_MAX_DELAY_MS = 30000;
+var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -4372,6 +4493,7 @@ class AkanAppHost {
   #pendingRestartReason = null;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail = [];
   #lastGoodFrontend = {};
   #buildStatusByPhase = new Map;
   #pendingBuildStatusReplay = [];
@@ -4423,6 +4545,7 @@ class AkanAppHost {
     this.#backendStartStatus = startStatus;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
+    this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
       stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
@@ -4456,6 +4579,37 @@ class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
+    if (this.withInk) {
+      this.#forwardBackendStream(backend.stderr, "stderr");
+      this.#forwardBackendStream(backend.stdout, "stdout");
+    }
+  }
+  #recordBackendStderr(chunk) {
+    const lines = chunk.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+      return;
+    this.#backendStderrTail.push(...lines);
+    if (this.#backendStderrTail.length > BACKEND_STDERR_TAIL_LIMIT) {
+      this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
+    }
+  }
+  async#forwardBackendStream(stream, kind) {
+    if (!stream)
+      return;
+    const decoder = new TextDecoder;
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text.trim())
+          continue;
+        if (kind === "stderr") {
+          this.#recordBackendStderr(text);
+          this.logger.warn(`[backend] ${text.trimEnd()}`);
+        } else {
+          this.logger.verbose(`[backend] ${text.trimEnd()}`);
+        }
+      }
+    } catch {}
   }
   #nextBackendBuildStatusGeneration(generation) {
     if (typeof generation === "number") {
@@ -4580,6 +4734,11 @@ class AkanAppHost {
     });
     this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(`[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`);
+    if (this.#backendStderrTail.length > 0) {
+      this.logger.warn(`[backend-recovery] recent backend stderr:
+${this.#backendStderrTail.join(`
+`)}`);
+    }
     this.#backendRecoveryTimer = setTimeout(() => {
       this.#backendRecoveryTimer = null;
       if (this.#backend)
@@ -4956,7 +5115,6 @@ var workflowSyncStatePath = (target) => `${workflowSyncDir}/${syncStateSlug(targ
 var generatedFilePathsForTarget = (targetRoot, reason = "Generated files were refreshed by sync.") => [
   { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-  { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/index.ts`, action: "sync", reason }
 ];
 var writeGeneratedSyncState = async (workspace, state) => {
@@ -5945,6 +6103,117 @@ ${values.map((value) => `    ${value}: t([${JSON.stringify(titleize(value))}, ${
   return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
 };
 var parseValues = (value) => value?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
+var hasSourceParseErrors = (content, fileName = "source.ts") => hasParseDiagnostics(sourceFileFor(fileName, content));
+var findClassDeclaration = (source, className) => {
+  let found = null;
+  const visit = (node) => {
+    if (found)
+      return;
+    if (ts4.isClassDeclaration(node) && node.name?.text === className) {
+      found = node;
+      return;
+    }
+    ts4.forEachChild(node, visit);
+  };
+  ts4.forEachChild(source, visit);
+  return found;
+};
+var firstHeritageCall = (node) => {
+  const expression = (node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [])[0]?.expression;
+  return expression && ts4.isCallExpression(expression) ? expression : null;
+};
+var factoryArrowOf = (call) => {
+  const arg = call.arguments.find((argument) => ts4.isArrowFunction(argument) || ts4.isFunctionExpression(argument));
+  return arg && (ts4.isArrowFunction(arg) || ts4.isFunctionExpression(arg)) ? arg : null;
+};
+var hasClassMethod = (content, className, methodName) => {
+  const node = findClassDeclaration(sourceFileFor("service.ts", content), className);
+  return Boolean(node?.members.some((member) => ts4.isMethodDeclaration(member) && nodeName(member.name) === methodName));
+};
+var insertClassMethod = (content, className, methodBlock) => {
+  const source = sourceFileFor("service.ts", content);
+  const node = findClassDeclaration(source, className);
+  if (!node)
+    return null;
+  const closeBrace = node.getEnd() - 1;
+  if (content[closeBrace] !== "}")
+    return null;
+  const lead = content.slice(0, closeBrace).endsWith(`
+`) ? "" : `
+`;
+  return spliceText(content, closeBrace, closeBrace, `${lead}${methodBlock}
+`);
+};
+var arrowParamInnerRegion = (content, source, arrow) => {
+  if (arrow.parameters.length > 0) {
+    return {
+      start: arrow.parameters[0].getStart(source),
+      end: arrow.parameters[arrow.parameters.length - 1].getEnd()
+    };
+  }
+  const open = content.indexOf("(", arrow.getStart(source));
+  if (open < 0)
+    return null;
+  const close = content.indexOf(")", open);
+  if (close < 0)
+    return null;
+  return { start: open + 1, end: close };
+};
+var factoryParamEdit = (content, source, arrow, plan) => {
+  if (arrow.parameters.length > 1)
+    return null;
+  const region = arrowParamInnerRegion(content, source, arrow);
+  if (!region)
+    return null;
+  if (arrow.parameters.length === 0) {
+    return { ...region, text: plan.mode === "destructure" ? `{ ${plan.name} }` : plan.name };
+  }
+  const param = arrow.parameters[0];
+  if (plan.mode === "positional")
+    return nodeName(param.name) === plan.name ? "unchanged" : null;
+  if (!ts4.isObjectBindingPattern(param.name))
+    return null;
+  const names = param.name.elements.map((element) => ts4.isIdentifier(element.name) ? element.name.text : null);
+  if (names.some((name) => name === null))
+    return null;
+  if (names.includes(plan.name))
+    return "unchanged";
+  return {
+    start: param.getStart(source),
+    end: param.getEnd(),
+    text: `{ ${[...names, plan.name].join(", ")} }`
+  };
+};
+var factoryObjectOf = (source, className) => {
+  const node = findClassDeclaration(source, className);
+  const call = node ? firstHeritageCall(node) : null;
+  const arrow = call ? factoryArrowOf(call) : null;
+  const object = arrow ? firstObjectReturnedByArrow(arrow) : null;
+  return arrow && object ? { arrow, object } : null;
+};
+var hasSignalFactoryEntry = (content, className, entryName) => {
+  const located = factoryObjectOf(sourceFileFor("signal.ts", content), className);
+  return Boolean(located?.object.properties.some((property) => propertyName(property) === entryName));
+};
+var insertSignalFactoryEntry = (content, className, entryName, entryLine, param) => {
+  const source = sourceFileFor("signal.ts", content);
+  const located = factoryObjectOf(source, className);
+  if (!located)
+    return null;
+  const locator = locatedObject(source, located.object);
+  if (locator.fields.some((field) => field.name === entryName))
+    return content;
+  const paramEdit = factoryParamEdit(content, source, located.arrow, param);
+  if (paramEdit === null)
+    return null;
+  const withEntry = insertOrderedFieldLine(content, locator, entryName, entryLine, {
+    fieldIndent: "  ",
+    closingIndent: ""
+  });
+  if (withEntry === content)
+    return null;
+  return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
+};
 
 // pkgs/@akanjs/devkit/workflow/moduleIndex.ts
 var indexFileKinds = [
@@ -6662,7 +6931,9 @@ var createWorkflowStepRegistry = ({
   createScalar,
   createUi,
   addField,
-  addEnumField
+  addEnumField,
+  addMutation,
+  addSlice
 }) => {
   const inspect = async () => {
     return;
@@ -6738,7 +7009,19 @@ var createWorkflowStepRegistry = ({
       defaultValue: workflowStringInput(plan.inputs.default)
     })),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
-    [workflowStepKey("add-enum-field", "update-option")]: inspect
+    [workflowStepKey("add-enum-field", "update-option")]: inspect,
+    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addMutation({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      mutation: workflowStringInput(plan.inputs.mutation)
+    })),
+    [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addSlice({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      slice: workflowStringInput(plan.inputs.slice)
+    })),
+    [workflowStepKey("add-slice", "update-signal-slice")]: inspect
   };
 };
 class WorkflowExecutor {
@@ -7485,13 +7768,59 @@ var resourceList = [
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" }
 ];
 var cursorMcpConfigPath = ".cursor/mcp.json";
+var claudeMcpConfigPath = ".mcp.json";
+var codexMcpConfigPath = ".codex/config.toml";
+var akanMcpInstallTargets = ["cursor", "claude", "codex"];
+var akanMcpInstallConfigPaths = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  codex: codexMcpConfigPath
+};
 var cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+var claudeProjectDir = "$CLAUDE_PROJECT_DIR";
+var akanMcpCommand = (mode, { cd } = {}) => cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 var createAkanCursorMcpServer = (mode = "readonly") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`]
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })]
+});
+var createAkanClaudeMcpServer = (mode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })]
 });
+var createAkanMcpServer = (target, mode = "readonly") => target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
 var akanCursorMcpServer = createAkanCursorMcpServer();
+var codexMcpServerTableHeader = "[mcp_servers.akan]";
+var createAkanCodexMcpServerBlock = (mode = "readonly") => `${codexMcpServerTableHeader}
+command = "bash"
+args = ["-lc", "${akanMcpCommand(mode)}"]
+`;
+var codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+var upsertCodexMcpServerBlock = (existing, block, { force = false } = {}) => {
+  const nextBlock = block.endsWith(`
+`) ? block : `${block}
+`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim())
+      return nextBlock;
+    return `${existing.replace(/\s*$/, "")}
+
+${nextBlock}`;
+  }
+  if (match[0].trim() === nextBlock.trim())
+    return existing;
+  if (!force)
+    throw new Error(`${codexMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+  const start = match.index ?? 0;
+  const before = existing.slice(0, start);
+  const after = existing.slice(start + match[0].length);
+  const separator = after && !after.startsWith(`
+`) ? `
+` : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
 var renderDoctorText = (result) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -7514,7 +7843,6 @@ var generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",
@@ -8508,7 +8836,7 @@ Caused by: ${ApplicationBuildReporter.formatError(error.cause)}` : "";
   }
 }
 // pkgs/@akanjs/devkit/applicationBuildRunner.ts
-import { mkdir as mkdir8, rm as rm3 } from "fs/promises";
+import { mkdir as mkdir8, rm as rm4 } from "fs/promises";
 import path37 from "path";
 
 // pkgs/@akanjs/devkit/frontendBuild/allRoutesBuilder.ts
@@ -8523,6 +8851,25 @@ async function appHasStModule(appCwdPath) {
 }
 var IMPLICIT_LAYOUT_DIR = path13.join(".akan", "generated", "root-layouts");
 var IMPLICIT_DICT_DIR = path13.join(".akan", "generated", "dict");
+var IMPLICIT_OVERRIDES_DIR = path13.join(".akan", "generated", "overrides");
+var OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+async function writeGeneratedOverridesLayoutFile(opts) {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path13.join(path13.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path13.relative(path13.dirname(absPath), opts.userAbsPath).split(path13.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source2 = `"use client";
+import { UiOverrideProvider } from "akanjs/ui";
+import { createElement, type ReactNode } from "react";
+import value from ${JSON.stringify(userSpecifier)};
+
+export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
+  return createElement(UiOverrideProvider, { value }, children);
+}
+`;
+  await Bun.write(absPath, source2);
+  return absPath;
+}
 function getRootBoundarySegments(key) {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match)
@@ -8715,9 +9062,17 @@ async function resolveSsrPageEntries(opts) {
     const segments = getRootBoundarySegments(key);
     return segments !== null && isRootBoundarySegments(segments, basePaths);
   }));
-  const base = opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map((key) => ({
-    key,
-    moduleAbsPath: path13.resolve(absPageDir, key)
+  const base = await Promise.all(opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map(async (key) => {
+    const userAbsPath = path13.resolve(absPageDir, key);
+    if (OVERRIDES_KEY_RE.test(key)) {
+      const moduleAbsPath = await writeGeneratedOverridesLayoutFile({
+        appCwdPath: opts.appCwdPath,
+        key,
+        userAbsPath
+      });
+      return { key, moduleAbsPath, seedAbsPaths: [userAbsPath] };
+    }
+    return { key, moduleAbsPath: userAbsPath };
   }));
   const generated = await Promise.all(rootBoundaries.map(async (boundary) => ({
     key: implicitRootLayoutKey(boundary.segments),
@@ -8749,7 +9104,7 @@ function computeRouteSeedIndex(pageEntries) {
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey2(key);
     const files = [path14.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path14.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);
@@ -10266,7 +10621,7 @@ class AllRoutesBuilder {
   }
 }
 // pkgs/@akanjs/devkit/frontendBuild/csrArtifactBuilder.ts
-import { mkdir as mkdir5, rm, unlink } from "fs/promises";
+import { mkdir as mkdir5, rm as rm2, unlink } from "fs/promises";
 import path24 from "path";
 
 // pkgs/@akanjs/devkit/frontendBuild/pagesEntrySourceGenerator.ts
@@ -10396,7 +10751,7 @@ class CsrArtifactBuilder {
     const artifact = await this.#loadCsrArtifact();
     const csrBasePaths = [...akanConfig2.basePaths];
     const htmlEntries = csrBasePaths.length > 0 ? csrBasePaths : ["index"];
-    await rm(this.#outputDir, { recursive: true, force: true });
+    await rm2(this.#outputDir, { recursive: true, force: true });
     await mkdir5(path24.join(this.#app.cwdPath, ".akan/generated/csr"), { recursive: true });
     const generatedHtmlFiles = Object.fromEntries(htmlEntries.map((basePath2) => this.#createHtmlFile(basePath2)));
     const result = await Bun.build({
@@ -11130,7 +11485,7 @@ class DevChangePlanner {
 }
 var uniqueResolved = (files) => [...new Set(files.map((file) => path27.resolve(file)))].sort();
 // pkgs/@akanjs/devkit/frontendBuild/devGeneratedIndexSync.ts
-import { mkdir as mkdir6, readdir as readdir2, readFile, rm as rm2, stat as stat3, writeFile } from "fs/promises";
+import { mkdir as mkdir6, readdir as readdir2, readFile, rm as rm3, stat as stat3, writeFile } from "fs/promises";
 import path28 from "path";
 var BARREL_FACETS2 = new Set(["common", "srvkit", "ui", "webkit"]);
 var FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
@@ -11213,7 +11568,7 @@ class DevGeneratedIndexSync {
     if (content === null) {
       if (!await exists(indexPath))
         return false;
-      await rm2(indexPath, { force: true });
+      await rm3(indexPath, { force: true });
       return true;
     }
     const current = await readFile(indexPath, "utf8").catch(() => null);
@@ -12360,7 +12715,7 @@ class ApplicationBuildRunner {
     await this.#app.getPageKeys({ refresh: true });
     const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig({ incremental });
     if (clean)
-      await rm3(path37.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
+      await rm4(path37.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
     await this.#checkProjectInChildProcess(tsconfigPath);
   }
   async#runPhase(id, label, task, summarize, options = {}) {
@@ -12560,7 +12915,7 @@ void run().catch((error) => {
   }
 }
 // pkgs/@akanjs/devkit/applicationReleasePackager.ts
-import { cp, mkdir as mkdir9, rm as rm4 } from "fs/promises";
+import { cp, mkdir as mkdir9, rm as rm5 } from "fs/promises";
 import path38 from "path";
 
 // pkgs/@akanjs/devkit/uploadRelease.ts
@@ -12667,7 +13022,7 @@ class ApplicationReleasePackager {
     const platformVersion = akanConfig2.mobile.version;
     const buildRoot = `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}`;
     if (await FileSys.dirExists(buildRoot))
-      await rm4(buildRoot, { recursive: true, force: true });
+      await rm5(buildRoot, { recursive: true, force: true });
     await mkdir9(buildRoot, { recursive: true });
     if (rebuild || !await FileSys.dirExists(`${this.#app.dist.cwdPath}/backend`))
       await this.#build();
@@ -12676,7 +13031,7 @@ class ApplicationReleasePackager {
     await mkdir9(buildPath, { recursive: true });
     await cp(`${this.#app.dist.cwdPath}/backend`, `${buildPath}/backend`, { recursive: true });
     await cp(this.#app.dist.cwdPath, buildRoot, { recursive: true });
-    await rm4(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
+    await rm5(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
     const releaseRoot = this.#app.workspace.workspaceRoot;
     const releaseArchivePath = path38.relative(releaseRoot, `${releaseRoot}/releases/builds/${this.#app.name}-release.tar.gz`).split(path38.sep).join("/");
     await this.#app.workspace.spawn("tar", ["-zcf", releaseArchivePath, "-C", buildRoot, "./"], { cwd: releaseRoot });
@@ -12692,7 +13047,7 @@ class ApplicationReleasePackager {
       `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-appBuild.zip`,
       "./csr"
     ]);
-    await rm4("./csr", { recursive: true, force: true });
+    await rm5("./csr", { recursive: true, force: true });
   }
   async#writeSourceArchive({ readme }) {
     const sourceRoot = `${this.#app.workspace.workspaceRoot}/releases/sources/${this.#app.name}`;
@@ -12703,7 +13058,7 @@ class ApplicationReleasePackager {
     await Promise.all([".next", "ios", "android", "public/libs"].map(async (path39) => {
       const targetPath = `${sourceRoot}/apps/${this.#app.name}/${path39}`;
       if (await FileSys.dirExists(targetPath))
-        await rm4(targetPath, { recursive: true, force: true });
+        await rm5(targetPath, { recursive: true, force: true });
     }));
     const syncPaths = [".husky", ".gitignore", "package.json"];
     await Promise.all(syncPaths.map((path39) => cp(`${this.#app.workspace.cwdPath}/${path39}`, `${sourceRoot}/${path39}`, { recursive: true })));
@@ -12718,7 +13073,7 @@ class ApplicationReleasePackager {
       const maxRetry = 3;
       for (let i = 0;i < maxRetry; i++) {
         try {
-          await rm4(sourceRoot, { recursive: true, force: true });
+          await rm5(sourceRoot, { recursive: true, force: true });
         } catch {}
       }
     }
@@ -12807,11 +13162,15 @@ async function resolveSignalTestPreloadPath(target) {
   addResolvedPackageCandidate(path39.dirname(Bun.main));
   addResolvedPackageCandidate(import.meta.dir);
   candidates.push(path39.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(path39.dirname(Bun.main), "../../akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH));
-  for (const candidate of [...new Set(candidates)]) {
+  const uniqueCandidates = [...new Set(candidates)];
+  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}`);
+  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.
+Probed paths:
+${uniqueCandidates.map((candidate) => `  - ${candidate}`).join(`
+`)}`);
 }
 // pkgs/@akanjs/devkit/builder.ts
 import { existsSync as existsSync2 } from "fs";
@@ -12947,7 +13306,7 @@ class Builder {
   }
 }
 // pkgs/@akanjs/devkit/capacitorApp.ts
-import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm5, writeFile as writeFile2 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm6, writeFile as writeFile2 } from "fs/promises";
 import os from "os";
 import path41 from "path";
 import { select as select2 } from "@inquirer/prompts";
@@ -13158,7 +13517,7 @@ var rootCapacitorConfigFilenames = [
 ];
 var rootCapacitorConfigPaths = (appRoot) => rootCapacitorConfigFilenames.map((file) => path41.join(appRoot, file));
 async function clearRootCapacitorConfigs(appRoot) {
-  await Promise.all(rootCapacitorConfigPaths(appRoot).map((file) => rm5(file, { force: true })));
+  await Promise.all(rootCapacitorConfigPaths(appRoot).map((file) => rm6(file, { force: true })));
 }
 async function writeRootCapacitorConfig(appRoot, content) {
   await clearRootCapacitorConfigs(appRoot);
@@ -13179,6 +13538,7 @@ var getLocalIP = () => {
 var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var asString = (value) => typeof value === "string" ? value : undefined;
 var firstString = (...values) => values.find((value) => typeof value === "string");
+var resolveIosApnsEnvironment = ({ operation }) => operation === "release" ? "production" : "development";
 var scoreIosDeviceTarget = (target) => {
   const state = target.state?.toLowerCase() ?? "";
   return (state.includes("available") ? 4 : 0) + (state.includes("wired") ? 2 : 0) + (state.includes("paired") ? 1 : 0);
@@ -13484,6 +13844,8 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
   const experimentalConfig = isRecord2(experimental) ? experimental : undefined;
   const pluginsConfig = isRecord2(plugins) ? plugins : {};
   const keyboardPluginConfig = isRecord2(pluginsConfig.Keyboard) ? pluginsConfig.Keyboard : {};
+  const pushNotificationsPluginConfig = isRecord2(pluginsConfig.PushNotifications) ? pluginsConfig.PushNotifications : {};
+  const usesPushNotifications = target.permissions?.includes("push") ?? false;
   const config = {
     ...capacitorConfig,
     appId,
@@ -13492,6 +13854,12 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
     plugins: {
       CapacitorCookies: { enabled: true },
       ...pluginsConfig,
+      ...usesPushNotifications || isRecord2(pluginsConfig.PushNotifications) ? {
+        PushNotifications: {
+          ...usesPushNotifications ? { presentationOptions: ["badge", "sound", "alert"] } : {},
+          ...pushNotificationsPluginConfig
+        }
+      } : {},
       Keyboard: {
         resize: "none",
         ...keyboardPluginConfig
@@ -13563,9 +13931,9 @@ class CapacitorApp {
     await mkdir11(this.targetRoot, { recursive: true });
     if (regenerate) {
       if (!platform || platform === "ios")
-        await rm5(path41.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
+        await rm6(path41.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
       if (!platform || platform === "android")
-        await rm5(path41.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
+        await rm6(path41.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
     }
     const project = this.project;
     await this.project.load();
@@ -13587,7 +13955,7 @@ class CapacitorApp {
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -13730,7 +14098,7 @@ ${error.message}`;
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -13864,7 +14232,7 @@ ${error.message}`;
     const htmlSource = path41.join(this.app.dist.cwdPath, "csr", targetHtmlFilename(this.target));
     if (!await Bun.file(htmlSource).exists())
       throw new Error(`CSR html for mobile target '${this.target.name}' not found: ${htmlSource}`);
-    await rm5(this.targetWebRoot, { recursive: true, force: true });
+    await rm6(this.targetWebRoot, { recursive: true, force: true });
     await mkdir11(this.targetWebRoot, { recursive: true });
     await Bun.write(path41.join(this.targetWebRoot, "index.html"), this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()));
   }
@@ -13945,7 +14313,7 @@ ${error.message}`;
     await this.project.android.setVersionCode(this.target.buildNum);
     await this.project.android.setAppName(this.target.appName);
   }
-  async#applyPermissions() {
+  async#applyPermissions({ operation, env }) {
     for (const permission of this.target.permissions ?? []) {
       if (permission === "camera")
         await this.addCamera();
@@ -13954,7 +14322,7 @@ ${error.message}`;
       else if (permission === "location")
         await this.addLocation();
       else if (permission === "push")
-        await this.addPush();
+        await this.addPush({ operation, env });
     }
   }
   async#applyDeepLinks(platform, { operation, env }) {
@@ -13973,7 +14341,7 @@ ${error.message}`;
         await this.#setUrlSchemesInIos(schemes);
       }
       if (domains.length > 0)
-        await this.#setAssociatedDomainsInIos(domains);
+        await this.#setAssociatedDomainsInIos(domains, { operation, env });
       return;
     }
     if (platform === "android") {
@@ -14067,12 +14435,64 @@ ${error.message}`;
     this.#setPermissionsInAndroid(["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"]);
     this.#setFeaturesInAndroid(["android.hardware.location.gps"]);
   }
-  async addPush() {
+  async addPush({ operation, env }) {
     await this.#setPermissionInIos({
       userNotificationsUsageDescription: "$(PRODUCT_NAME) uses notifications to keep you updated."
     });
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { UIBackgroundModes: ["remote-notification"] }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { UIBackgroundModes: ["remote-notification"] }),
+      this.#writeEntitlementsInIos(this.target.deepLinks?.domains ?? [], { operation, env }),
+      this.#ensurePushAppDelegateInIos()
+    ]);
     this.#setPermissionsInAndroid(["POST_NOTIFICATIONS"]);
   }
+  async#ensurePushAppDelegateInIos() {
+    const appDelegatePath = path41.join(this.app.cwdPath, this.iosProjectPath, "App/AppDelegate.swift");
+    if (!await Bun.file(appDelegatePath).exists())
+      return;
+    const editor = await FileEditor.create(appDelegatePath);
+    let content = editor.getContent();
+    if (!content.includes("import FirebaseCore")) {
+      content = content.replace("import Capacitor", `import Capacitor
+import FirebaseCore`);
+    }
+    if (!content.includes("import FirebaseMessaging")) {
+      content = content.replace("import FirebaseCore", `import FirebaseCore
+import FirebaseMessaging`);
+    }
+    if (!content.includes("FirebaseApp.configure()")) {
+      content = content.replace(/\n(\s*)return true/, `
+$1FirebaseApp.configure()
+
+$1return true`);
+    }
+    if (!content.includes("didRegisterForRemoteNotificationsWithDeviceToken")) {
+      const delegateMethods = `
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        Messaging.messaging().apnsToken = deviceToken
+        NotificationCenter.default.post(
+            name: .capacitorDidRegisterForRemoteNotifications,
+            object: deviceToken
+        )
+    }
+
+    func application(_ application: UIApplication,
+                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
+        NotificationCenter.default.post(
+            name: .capacitorDidFailToRegisterForRemoteNotifications,
+            object: error
+        )
+    }
+`;
+      content = content.replace(`
+    func applicationWillResignActive`, `${delegateMethods}
+    func applicationWillResignActive`);
+    }
+    if (content !== editor.getContent())
+      await editor.setContent(content).save();
+  }
   async#setPermissionInIos(permissions) {
     const updateNs = Object.fromEntries(Object.entries(permissions).map(([key, value]) => [`NS${capitalize5(key)}`, value]));
     await Promise.all([
@@ -14090,25 +14510,35 @@ ${error.message}`;
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes })
     ]);
   }
-  async#setAssociatedDomainsInIos(domains) {
+  async#setAssociatedDomainsInIos(domains, { operation, env }) {
+    await this.#writeEntitlementsInIos(domains, { operation, env });
+  }
+  async#writeEntitlementsInIos(domains, runConfig) {
     const entitlementsRelPath = "App/App.entitlements";
     const entitlementsPath = path41.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
     const values = domains.map((domain) => `applinks:${domain}`);
+    const usesPush = this.target.permissions?.includes("push") ?? false;
+    const apsEnvironment = resolveIosApnsEnvironment(runConfig);
     const body = [
       '<?xml version="1.0" encoding="UTF-8"?>',
       '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
       '<plist version="1.0">',
       "<dict>",
-      "  <key>com.apple.developer.associated-domains</key>",
-      "  <array>",
-      ...values.map((value) => `    <string>${value}</string>`),
-      "  </array>",
+      ...usesPush ? ["  <key>aps-environment</key>", `  <string>${apsEnvironment}</string>`] : [],
+      ...values.length > 0 ? [
+        "  <key>com.apple.developer.associated-domains</key>",
+        "  <array>",
+        ...values.map((value) => `    <string>${value}</string>`),
+        "  </array>"
+      ] : [],
       "</dict>",
       "</plist>",
       ""
     ].join(`
 `);
-    await writeFile2(entitlementsPath, body);
+    const currentBody = await Bun.file(entitlementsPath).exists() ? await Bun.file(entitlementsPath).text() : undefined;
+    if (currentBody !== body)
+      await writeFile2(entitlementsPath, body);
     await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
   }
   async#setCodeSignEntitlementsInIos(entitlementsRelPath) {
@@ -14212,7 +14642,7 @@ ${filter}$1`);
     for (const permission of permissions) {
       if (this.#hasPermissionInAndroid(permission)) {
         this.app.logger.info(`${permission} already exists in android`);
-        return this;
+        continue;
       }
       this.app.logger.info(`Adding ${permission} to android`);
       this.project.android.getAndroidManifest().injectFragment("manifest", `<uses-permission android:name="android.permission.${permission}" />`);
@@ -14228,7 +14658,7 @@ ${filter}$1`);
     return Array.from(usesPermission).map((permission) => permission.getAttribute("android:name"));
   }
   #hasPermissionInAndroid(permission) {
-    return this.#getPermissionsInAndroid().includes(permission);
+    return this.#getPermissionsInAndroid().includes(`android.permission.${permission}`);
   }
 }
 // pkgs/@akanjs/devkit/commandDecorators/targetMeta.ts
@@ -15324,6 +15754,42 @@ var CONVENTION_SUFFIXES = [
   ".signal.ts",
   ".store.ts"
 ];
+var PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId"
+]);
+var RULE_FIXES = {
+  "akan.global.duplicate-exported-function-name": "Rename one of the exports, or if they are the same thing, extract it into one shared module and import it in both places.",
+  "akan.global.duplicate-exported-function-body": "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
+  "akan.file.recommended-max-lines": "Split the file by responsibility \u2014 move Zones, Utils, or subcomponents into sibling files.",
+  "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
+  "akan.file.placeholder-export": "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
+  "akan.file.global-declaration": "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
+  "akan.file.window-augmentation": "Move the Window augmentation into an approved browser integration file and keep it isolated.",
+  "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
+  "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.file.component-internal-declaration": "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
+  "akan.file.component-export": "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix \u2014 only PascalCase components and their `<Component>Props` interface belong here.",
+  "akan.layout.app-root-file": "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-file": "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+  "akan.layout.module-ui-file": "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component."
+};
+function getRuleFix(rule) {
+  if (rule.startsWith("akan.convention"))
+    return "Keep only the model's allowed declarations in this file; move other logic to the matching domain file (service, document, store, etc.).";
+  return RULE_FIXES[rule];
+}
 
 class AkanQualityScanner {
   async scan(workspaceRoot) {
@@ -15332,13 +15798,14 @@ class AkanQualityScanner {
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanSingleFileQuality(sourceFile2)),
+      ...sourceFiles.flatMap((sourceFile2) => this.#scanComponentQuality(sourceFile2)),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanConventionQuality(sourceFile2)),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanLayoutQuality(sourceFile2))
     ];
     return {
       workspaceRoot,
       scannedFiles: sourceFiles.length,
-      warnings: warnings.sort(compareWarnings),
+      warnings: warnings.map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) })).sort(compareWarnings),
       suggestedRules: SUGGESTED_RULES
     };
   }
@@ -15388,7 +15855,8 @@ class AkanQualityScanner {
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile2) => getExportedFunctionLikes(sourceFile2));
     const warnings = [];
-    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+    const nameCheckedDeclarations = exportedFunctionLikes.filter((declaration) => !declaration.duplicateNameExempt);
+    for (const [name, declarations] of groupBy(nameCheckedDeclarations, (declaration) => declaration.name)) {
       if (declarations.length < 2)
         continue;
       warnings.push({
@@ -15459,6 +15927,49 @@ class AkanQualityScanner {
     }
     return warnings;
   }
+  #scanComponentQuality(sourceFile2) {
+    if (!isComponentDeclarationFile(sourceFile2.file))
+      return [];
+    const isPage = isPageRouteFile(sourceFile2.file);
+    const declarations = getComponentFileDeclarations(sourceFile2.sourceFile);
+    const compoundComponentNames = getCompoundComponentNames(sourceFile2.sourceFile);
+    const componentNames = declarations.filter((declaration) => declaration.exported && isComponentValueKind(declaration.kind)).filter((declaration) => isPascalCaseName(declaration.name)).map((declaration) => declaration.name);
+    const allowedComponentNames = new Set([...componentNames, ...compoundComponentNames]);
+    const allowedPropsInterfaces = new Set([...allowedComponentNames].map((name) => `${name}Props`));
+    const warnings = [];
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
+        continue;
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
+        continue;
+      if (declaration.exported) {
+        if (isAllowedComponentExport(declaration, isPage))
+          continue;
+        warnings.push({
+          rule: "akan.file.component-export",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`
+        });
+        continue;
+      }
+      if (isComponentValueKind(declaration.kind) && compoundComponentNames.has(declaration.name))
+        continue;
+      if (isRestrictedInternalKind(declaration.kind)) {
+        warnings.push({
+          rule: "akan.file.component-internal-declaration",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`
+        });
+      }
+    }
+    return warnings;
+  }
   #scanConventionQuality(sourceFile2) {
     const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile2.file.endsWith(candidate));
     if (!suffix)
@@ -15534,6 +16045,8 @@ function formatQualityWarnings(warnings) {
     if (warning.locations?.length) {
       lines.push(...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`));
     }
+    if (warning.fix)
+      lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -15542,6 +16055,7 @@ function formatQualityLocation(file, line) {
 }
 function getExportedFunctionLikes(sourceFile2) {
   const declarations = [];
+  const nameExempt = isPageRouteFile(sourceFile2.file) || isUiComponentFile(sourceFile2.file);
   for (const statement of sourceFile2.sourceFile.statements) {
     if (ts11.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -15549,7 +16063,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "function",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body),
+        duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
       });
     }
     if (ts11.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -15558,7 +16073,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "class",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement),
+        duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, isEnumClassStatement(sourceFile2.sourceFile, statement))
       });
     }
     if (ts11.isVariableStatement(statement) && isExported(statement)) {
@@ -15570,16 +16086,127 @@ function getExportedFunctionLikes(sourceFile2) {
           kind: "function-variable",
           file: sourceFile2.file,
           line: getLine(sourceFile2.sourceFile, declaration),
-          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer)
+          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer),
+          duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
         });
       }
     }
   }
   return declarations;
 }
+function isPageRouteFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+function isUiComponentFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "ui";
+}
+function isConventionDuplicateNameExempt(file, isEnumClass) {
+  if (!isInLibModule(file))
+    return false;
+  if (file.endsWith(".tsx"))
+    return true;
+  if (file.endsWith(".document.ts") || file.endsWith(".service.ts") || file.endsWith(".signal.ts") || file.endsWith(".store.ts"))
+    return true;
+  if (file.endsWith(".constant.ts"))
+    return !isEnumClass;
+  return false;
+}
+function isInLibModule(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+function isEnumClassStatement(sourceFile2, statement) {
+  if (!ts11.isClassDeclaration(statement))
+    return false;
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts11.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText(sourceFile2).startsWith("enumOf(");
+}
 function getExportedClassNames(sourceFile2) {
   return sourceFile2.statements.filter((statement) => ts11.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
 }
+function isComponentDeclarationFile(file) {
+  if (!file.endsWith(".tsx"))
+    return false;
+  const segments = file.split("/");
+  const [root, , area] = segments;
+  if (root !== "apps" && root !== "libs")
+    return false;
+  if (area === "lib" || area === "ui")
+    return true;
+  return root === "apps" && area === "page";
+}
+function getComponentFileDeclarations(sourceFile2) {
+  const reExportedNames = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (ts11.isExportDeclaration(statement) && statement.exportClause && ts11.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
+    }
+  }
+  const declarations = [];
+  for (const statement of sourceFile2.statements) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts11.isInterfaceDeclaration(statement))
+      add(statement.name.text, "interface", getLine(sourceFile2, statement));
+    else if (ts11.isTypeAliasDeclaration(statement))
+      add(statement.name.text, "type", getLine(sourceFile2, statement));
+    else if (ts11.isEnumDeclaration(statement))
+      add(statement.name.text, "enum", getLine(sourceFile2, statement));
+    else if (ts11.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile2, statement));
+    else if (ts11.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile2, statement));
+    else if (ts11.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts11.isIdentifier(declaration.name))
+          continue;
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile2, declaration));
+      }
+    }
+  }
+  return declarations;
+}
+function getCompoundComponentNames(sourceFile2) {
+  const names = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (!ts11.isExpressionStatement(statement))
+      continue;
+    const { expression } = statement;
+    if (!ts11.isBinaryExpression(expression) || expression.operatorToken.kind !== ts11.SyntaxKind.EqualsToken)
+      continue;
+    if (!ts11.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+      continue;
+    names.add(expression.left.name.text);
+    if (ts11.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+      names.add(expression.right.text);
+  }
+  return names;
+}
+function isComponentValueKind(kind) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+function isRestrictedInternalKind(kind) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+function isAllowedComponentExport(declaration, isPage) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name))
+    return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+function isPascalCaseName(name) {
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+function isDefaultExportStatement(statement) {
+  if (ts11.isExportAssignment(statement))
+    return !statement.isExportEquals;
+  return !!(ts11.getCombinedModifierFlags(statement) & ts11.ModifierFlags.Default);
+}
 function getPlaceholderExportWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith("/index.ts") && !sourceFile2.file.endsWith("/index.tsx"))
     return [];
@@ -15595,11 +16222,7 @@ function getPlaceholderExportWarnings(sourceFile2) {
 function getDictionaryTextWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith(".dictionary.ts"))
     return [];
-  const stalePatterns = [
-    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
-    { pattern: /settting/, label: "misspelling: settting" },
-    { pattern: /\uBC30\uB108 \uC218/, label: "stale copied Korean domain noun: \uBC30\uB108 \uC218" }
-  ];
+  const stalePatterns = [{ pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" }];
   return stalePatterns.flatMap(({ pattern, label }) => findPatternLines(sourceFile2.content, pattern).map((line) => ({
     rule: "akan.file.dictionary-stale-text",
     scope: "file",
@@ -15720,10 +16343,8 @@ function getConventionDescription(suffix, modelName) {
 }
 function getLibRootFile(file) {
   const segments = file.split("/");
-  if (segments[0] === "libs" && segments.length === 4 && segments[2] === "lib")
+  if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];
-  if (segments[0] === "apps" && segments.length === 5 && segments[2] === "lib")
-    return segments[4];
   return null;
 }
 function getModuleUiWarning(file) {