@akanjs/cli 2.3.11-rc.9 → 2.3.12-rc.0

package/incrementalBuilder.proc.js

@@ -721,6 +721,7 @@ var WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"];
 var SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"];
 var NATIVE_RUNTIME_PACKAGES = ["sharp"];
 var DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"];
+var MOBILE_RUNTIME_PACKAGES = ["firebase"];
 var DATABASE_MODE_RUNTIME_PACKAGES = {
   single: [],
   multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
@@ -730,6 +731,7 @@ var AKAN_RUNTIME_PACKAGES = new Set([
   ...SSR_RUNTIME_PACKAGES,
   ...NATIVE_RUNTIME_PACKAGES,
   ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
+  ...MOBILE_RUNTIME_PACKAGES,
   ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat()
 ]);
 var DEFAULT_AKAN_IMAGE_CONFIG = {
@@ -1013,11 +1015,20 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
   }
   getMissingDatabaseModeDependencySpecs(databaseMode = this.defaultDatabaseMode) {
+    return this.#getMissingDependencySpecs(this.getDatabaseModeRuntimePackages(databaseMode));
+  }
+  getMobileRuntimePackages() {
+    return [...MOBILE_RUNTIME_PACKAGES];
+  }
+  getMissingMobileDependencySpecs() {
+    return this.#getMissingDependencySpecs(this.getMobileRuntimePackages());
+  }
+  #getMissingDependencySpecs(libs) {
     const rootDependencies = {
       ...this.rootPackageJson.dependencies,
       ...this.rootPackageJson.devDependencies
     };
-    return this.getDatabaseModeRuntimePackages(databaseMode).filter((lib) => !rootDependencies[lib]).map((lib) => {
+    return libs.filter((lib) => !rootDependencies[lib]).map((lib) => {
       const version = this.#resolveProductionDependencyVersion(lib);
       if (!version)
         throw new Error(`Dependency ${lib} not found in package.json`);
@@ -2691,6 +2702,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;
@@ -3714,7 +3750,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();
@@ -8822,6 +8862,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)
@@ -9014,9 +9073,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),
@@ -9048,7 +9115,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]);
@@ -11434,6 +11501,8 @@ import path28 from "path";
 var BARREL_FACETS2 = new Set(["common", "srvkit", "ui", "webkit"]);
 var FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
 var FACET_EXCLUDED_FILE_RE = /(^index\.tsx?$|\.d\.ts$|\.(test|spec)\.(ts|tsx)$|\.css$|\.scss$|\.sass$)/;
+var FACET_PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+var FACET_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 var MODULE_UI_TYPES = ["Template", "Unit", "Util", "View", "Zone"];
 var SERVICE_UI_TYPES = ["Util", "Zone"];
 var SCALAR_UI_TYPES = ["Template", "Unit"];
@@ -11530,18 +11599,20 @@ class DevGeneratedIndexSync {
     return this.#moduleContent(path28.dirname(indexPath));
   }
   async#facetContent(dir) {
+    const nameCasePattern = path28.basename(dir) === "ui" ? FACET_PASCAL_CASE_RE : FACET_CAMEL_CASE_RE;
     const entries = await readdir2(dir, { withFileTypes: true }).catch(() => []);
     const exportNames = entries.flatMap((entry) => {
       const name = entry.name;
       if (name.startsWith("."))
         return [];
       if (entry.isDirectory())
-        return [name];
+        return nameCasePattern.test(name) ? [name] : [];
       if (!entry.isFile())
         return [];
       if (!FACET_SOURCE_FILE_RE.test(name) || FACET_EXCLUDED_FILE_RE.test(name))
         return [];
-      return [name.replace(FACET_SOURCE_FILE_RE, "")];
+      const exportName = name.replace(FACET_SOURCE_FILE_RE, "");
+      return nameCasePattern.test(exportName) ? [exportName] : [];
     }).sort();
     if (exportNames.length === 0)
       return null;
@@ -15698,6 +15769,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) {
@@ -15713,7 +15820,7 @@ class AkanQualityScanner {
     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
     };
   }
@@ -15838,22 +15945,43 @@ class AkanQualityScanner {
   #scanComponentQuality(sourceFile2) {
     if (!isComponentDeclarationFile(sourceFile2.file))
       return [];
-    const exportedNames = getExportedDeclarationNames(sourceFile2.sourceFile);
-    const allowedInternalInterfaces = new Set([...exportedNames].map((name) => `${name}Props`));
+    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 getInternalTypeOrFunctionDeclarations(sourceFile2.sourceFile)) {
-      if (exportedNames.has(declaration.name))
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
         continue;
-      if (declaration.kind === "interface" && allowedInternalInterfaces.has(declaration.name))
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
         continue;
-      warnings.push({
-        rule: "akan.file.component-internal-declaration",
-        scope: "file",
-        severity: "warning",
-        file: sourceFile2.file,
-        line: declaration.line,
-        message: `Component file should not declare non-exported ${declaration.kind} "${declaration.name}". Only a "<Component>Props" interface may stay internal; move other types or helpers to a separate file in ui/, webkit/, or common/ by purpose.`
-      });
+      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;
   }
@@ -15932,6 +16060,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;
   });
 }
@@ -16023,61 +16153,75 @@ function isComponentDeclarationFile(file) {
     return true;
   return root === "apps" && area === "page";
 }
-function getExportedDeclarationNames(sourceFile2) {
-  const names = new Set;
+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) {
-        names.add(element.name.text);
-        if (element.propertyName)
-          names.add(element.propertyName.text);
-      }
-      continue;
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
     }
-    if (!isExported(statement))
-      continue;
-    for (const name of getStatementDeclarationNames(statement))
-      names.add(name);
   }
-  return names;
-}
-function getStatementDeclarationNames(statement) {
-  if (ts11.isFunctionDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isClassDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isInterfaceDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isTypeAliasDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isEnumDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts11.isIdentifier(declaration.name)).map((declaration) => declaration.name.text);
-  }
-  return [];
-}
-function getInternalTypeOrFunctionDeclarations(sourceFile2) {
   const declarations = [];
   for (const statement of sourceFile2.statements) {
-    if (isExported(statement))
-      continue;
-    if (ts11.isInterfaceDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "interface", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isTypeAliasDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "type", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isFunctionDeclaration(statement) && statement.name) {
-      declarations.push({ name: statement.name.text, kind: "function", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isVariableStatement(statement)) {
+    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) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts11.isIdentifier(declaration.name))
           continue;
-        declarations.push({ name: declaration.name.text, kind: "function", line: getLine(sourceFile2, declaration) });
+        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 [];

package/index.js

@@ -719,6 +719,7 @@ var WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"];
 var SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"];
 var NATIVE_RUNTIME_PACKAGES = ["sharp"];
 var DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"];
+var MOBILE_RUNTIME_PACKAGES = ["firebase"];
 var DATABASE_MODE_RUNTIME_PACKAGES = {
   single: [],
   multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
@@ -728,6 +729,7 @@ var AKAN_RUNTIME_PACKAGES = new Set([
   ...SSR_RUNTIME_PACKAGES,
   ...NATIVE_RUNTIME_PACKAGES,
   ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
+  ...MOBILE_RUNTIME_PACKAGES,
   ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat()
 ]);
 var DEFAULT_AKAN_IMAGE_CONFIG = {
@@ -1011,11 +1013,20 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
   }
   getMissingDatabaseModeDependencySpecs(databaseMode = this.defaultDatabaseMode) {
+    return this.#getMissingDependencySpecs(this.getDatabaseModeRuntimePackages(databaseMode));
+  }
+  getMobileRuntimePackages() {
+    return [...MOBILE_RUNTIME_PACKAGES];
+  }
+  getMissingMobileDependencySpecs() {
+    return this.#getMissingDependencySpecs(this.getMobileRuntimePackages());
+  }
+  #getMissingDependencySpecs(libs) {
     const rootDependencies = {
       ...this.rootPackageJson.dependencies,
       ...this.rootPackageJson.devDependencies
     };
-    return this.getDatabaseModeRuntimePackages(databaseMode).filter((lib) => !rootDependencies[lib]).map((lib) => {
+    return libs.filter((lib) => !rootDependencies[lib]).map((lib) => {
       const version = this.#resolveProductionDependencyVersion(lib);
       if (!version)
         throw new Error(`Dependency ${lib} not found in package.json`);
@@ -2689,6 +2700,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;
@@ -3712,7 +3748,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();
@@ -8820,6 +8860,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)
@@ -9012,9 +9071,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),
@@ -9046,7 +9113,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]);
@@ -11432,6 +11499,8 @@ import path28 from "path";
 var BARREL_FACETS2 = new Set(["common", "srvkit", "ui", "webkit"]);
 var FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
 var FACET_EXCLUDED_FILE_RE = /(^index\.tsx?$|\.d\.ts$|\.(test|spec)\.(ts|tsx)$|\.css$|\.scss$|\.sass$)/;
+var FACET_PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+var FACET_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 var MODULE_UI_TYPES = ["Template", "Unit", "Util", "View", "Zone"];
 var SERVICE_UI_TYPES = ["Util", "Zone"];
 var SCALAR_UI_TYPES = ["Template", "Unit"];
@@ -11528,18 +11597,20 @@ class DevGeneratedIndexSync {
     return this.#moduleContent(path28.dirname(indexPath));
   }
   async#facetContent(dir) {
+    const nameCasePattern = path28.basename(dir) === "ui" ? FACET_PASCAL_CASE_RE : FACET_CAMEL_CASE_RE;
     const entries = await readdir2(dir, { withFileTypes: true }).catch(() => []);
     const exportNames = entries.flatMap((entry) => {
       const name = entry.name;
       if (name.startsWith("."))
         return [];
       if (entry.isDirectory())
-        return [name];
+        return nameCasePattern.test(name) ? [name] : [];
       if (!entry.isFile())
         return [];
       if (!FACET_SOURCE_FILE_RE.test(name) || FACET_EXCLUDED_FILE_RE.test(name))
         return [];
-      return [name.replace(FACET_SOURCE_FILE_RE, "")];
+      const exportName = name.replace(FACET_SOURCE_FILE_RE, "");
+      return nameCasePattern.test(exportName) ? [exportName] : [];
     }).sort();
     if (exportNames.length === 0)
       return null;
@@ -15696,6 +15767,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) {
@@ -15711,7 +15818,7 @@ class AkanQualityScanner {
     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
     };
   }
@@ -15836,22 +15943,43 @@ class AkanQualityScanner {
   #scanComponentQuality(sourceFile2) {
     if (!isComponentDeclarationFile(sourceFile2.file))
       return [];
-    const exportedNames = getExportedDeclarationNames(sourceFile2.sourceFile);
-    const allowedInternalInterfaces = new Set([...exportedNames].map((name) => `${name}Props`));
+    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 getInternalTypeOrFunctionDeclarations(sourceFile2.sourceFile)) {
-      if (exportedNames.has(declaration.name))
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
         continue;
-      if (declaration.kind === "interface" && allowedInternalInterfaces.has(declaration.name))
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
         continue;
-      warnings.push({
-        rule: "akan.file.component-internal-declaration",
-        scope: "file",
-        severity: "warning",
-        file: sourceFile2.file,
-        line: declaration.line,
-        message: `Component file should not declare non-exported ${declaration.kind} "${declaration.name}". Only a "<Component>Props" interface may stay internal; move other types or helpers to a separate file in ui/, webkit/, or common/ by purpose.`
-      });
+      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;
   }
@@ -15930,6 +16058,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;
   });
 }
@@ -16021,61 +16151,75 @@ function isComponentDeclarationFile(file) {
     return true;
   return root === "apps" && area === "page";
 }
-function getExportedDeclarationNames(sourceFile2) {
-  const names = new Set;
+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) {
-        names.add(element.name.text);
-        if (element.propertyName)
-          names.add(element.propertyName.text);
-      }
-      continue;
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
     }
-    if (!isExported(statement))
-      continue;
-    for (const name of getStatementDeclarationNames(statement))
-      names.add(name);
-  }
-  return names;
-}
-function getStatementDeclarationNames(statement) {
-  if (ts11.isFunctionDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isClassDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isInterfaceDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isTypeAliasDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isEnumDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts11.isIdentifier(declaration.name)).map((declaration) => declaration.name.text);
   }
-  return [];
-}
-function getInternalTypeOrFunctionDeclarations(sourceFile2) {
   const declarations = [];
   for (const statement of sourceFile2.statements) {
-    if (isExported(statement))
-      continue;
-    if (ts11.isInterfaceDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "interface", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isTypeAliasDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "type", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isFunctionDeclaration(statement) && statement.name) {
-      declarations.push({ name: statement.name.text, kind: "function", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isVariableStatement(statement)) {
+    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) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts11.isIdentifier(declaration.name))
           continue;
-        declarations.push({ name: declaration.name.text, kind: "function", line: getLine(sourceFile2, declaration) });
+        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 [];
@@ -17032,6 +17176,31 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
       throw error;
     }
   }
+  async confirmMobileDependencyInstall(installSpecs) {
+    return await confirm3({
+      message: [`Mobile builds require missing dependencies: ${installSpecs.join(", ")}.`, "Install them now?"].join(" "),
+      default: true
+    });
+  }
+  async syncMobileDependencies(app, akanConfig3) {
+    const installSpecs = akanConfig3.getMissingMobileDependencySpecs();
+    if (installSpecs.length === 0)
+      return;
+    const shouldInstall = await this.confirmMobileDependencyInstall(installSpecs);
+    if (!shouldInstall)
+      throw new Error(`Mobile builds require missing dependencies: ${installSpecs.join(", ")}.`);
+    const spinner2 = app.workspace.spinning("Installing mobile dependencies...");
+    try {
+      await app.workspace.spawn("bun", ["add", ...installSpecs], {
+        stdio: "inherit"
+      });
+      await app.workspace.getPackageJson({ refresh: true });
+      spinner2.succeed("Installed mobile dependencies");
+    } catch (error) {
+      spinner2.fail("Failed to install mobile dependencies");
+      throw error;
+    }
+  }
   async createApplication(appName, workspace, { start = false, libs = [] } = {}) {
     const spinner2 = workspace.spinning("Creating application...");
     const app = await this.applicationRunner.createApplication(appName, workspace, libs);
@@ -17153,6 +17322,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     noAllowProvisioningUpdates = false
   } = {}) {
     await app.scanSync({ write });
+    await this.syncMobileDependencies(app, await app.getConfig());
     await this.applicationRunner.startIos(app, {
       open,
       operation,
@@ -17181,6 +17351,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     regenerate = false
   } = {}) {
     await app.scanSync({ write });
+    await this.syncMobileDependencies(app, await app.getConfig());
     await this.applicationRunner.startAndroid(app, {
       open,
       operation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.11-rc.9",
+  "version": "2.3.12-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.11-rc.9",
+    "akanjs": "2.3.12-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/facetIndex/index.ts

@@ -12,18 +12,24 @@ interface Options {
 
 const sourceFilePattern = /\.(ts|tsx)$/;
 const excludedFilePattern = /(^index\.tsx?$|\.d\.ts$|\.(test|spec)\.(ts|tsx)$|\.css$|\.scss$|\.sass$)/;
+// `ui` exports PascalCase names only; `common`/`srvkit`/`webkit` export camelCase names only. Names with
+// dots, underscores, or hyphens (e.g. `foo.helper`, `Globe_Dynamic`, `kebab-case`) match neither and are skipped.
+const pascalCasePattern = /^[A-Z][A-Za-z0-9]*$/;
+const camelCasePattern = /^[a-z][A-Za-z0-9]*$/;
+const nameCasePatternForFacet = (facet: string) => (facet === "ui" ? pascalCasePattern : camelCasePattern);
 
 export default async function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dict = {}, options: Options = {}) {
   const { exec, facet } = options;
   if (!exec || !facet || !(await exec.exists(facet))) return null;
 
+  const nameCasePattern = nameCasePatternForFacet(facet);
   const { files, dirs } = await exec.getFilesAndDirs(facet);
   const exportNames = [
     ...files
       .filter((filename) => sourceFilePattern.test(filename) && !excludedFilePattern.test(filename))
       .map((filename) => filename.replace(sourceFilePattern, "")),
     ...dirs.filter((dirname) => !dirname.startsWith(".")),
-  ].sort();
+  ].filter((name) => nameCasePattern.test(name)).sort();
 
   if (exportNames.length === 0) return null;
   return {

package/templates/workspaceRoot/.cursor/rules/application-test-commands.mdc.template

@@ -10,7 +10,7 @@ alwaysApply: true
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
 
 ```bash
-cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akansoft AKAN_PUBLIC_SERVE_DOMAIN="akamir.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=neul,apptest,seon bun main.js
+cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akansoft AKAN_PUBLIC_SERVE_DOMAIN="akanjs.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=operator,office,homepage bun main.js
 ```
 
 - Adjust `<appName>`, `AKAN_PUBLIC_APP_NAME`, and `AKAN_PUBLIC_BASE_PATHS` to match the app being tested.

package/templates/workspaceRoot/.cursor/rules/typescript-imports.mdc.template

@@ -9,5 +9,5 @@ alwaysApply: false
 - Use Bun and ESM assumptions from the root `tsconfig.json`.
 - Prefer path aliases over deep relative imports when crossing package boundaries.
 - Use `akanjs/*` for framework facets, `@apps/*` for apps, `@libs/*` for shared libs, and `@contract/*` for contract code.
-- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/puffinplace/client`, and `@apps/puffinplace/server`.
+- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/myapp/client`, and `@apps/myapp/server`.
 - Let Biome organize imports instead of manually reshuffling unrelated imports.