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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @akanjs/devkit
 
+## 2.3.11
+
+### Minor Changes
+
+- 595390a: feat: UiOverride 시스템 및 \_overrides.tsx 지원 추가
+
+  - `akanjs/ui/UiOverride` 추가: `Provider`, `createOverridable`, `useUiOverride`, `override` API로 UI 컴포넌트 커스터마이징 지원
+  - 모든 akanjs UI 컴포넌트(Button, Modal, Select, Table 등)에 `useUiOverride()` 통합
+  - 라우트 시스템에 `_overrides.tsx` 지원 추가 (routeConvention, routeTreeBuilder)
+  - qualityScanner에 `_overrides.tsx` 파일 검증 로직 추가
+  - 앱 예제: `apps/minimal`에 `_overrides.tsx`, `BrandModal`, `OverrideDemo` 추가
+  - `apps/akan` 문서에 UI 커스터마이징 가이드 페이지 추가
+  - devkit에 `no-throw-raw-error.grit` lint rule 추가
+  - `PushNotificationServer.ts` 리팩토링
+  - biome.json 업데이트 및 패키지 의존성 정리
+
+### Patch Changes
+
+- 5ce752a: enhance: add host option for staging server tests
+- 5ce752a: add host option for staging server tests
+- Updated dependencies [5ce752a]
+- Updated dependencies [5ce752a]
+- Updated dependencies [595390a]
+  - akanjs@2.4.0
+
 ## 2.3.10
 
 ### Patch Changes

package/akanConfig/akanConfig.test.ts

@@ -264,6 +264,8 @@ describe("AkanAppConfig", () => {
       `postgres@${runtimeDependencies.postgres}`,
       `protobufjs@${runtimeDependencies.protobufjs}`,
     ]);
+    expect(config.getMobileRuntimePackages()).toEqual(["firebase"]);
+    expect(config.getMissingMobileDependencySpecs()).toEqual([`firebase@${runtimeDependencies.firebase}`]);
   });
 
   test("normalizes multiple mobile targets and validates base paths", () => {

package/akanConfig/akanConfig.ts

@@ -51,6 +51,9 @@ const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] a
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
 const NATIVE_RUNTIME_PACKAGES = ["sharp"] as const;
 const DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
+// Native-only client packages that are not bundled into the base bootstrap; installed
+// on demand when a mobile target is built or started (e.g. firebase for push tokens).
+const MOBILE_RUNTIME_PACKAGES = ["firebase"] as const;
 const DATABASE_MODE_RUNTIME_PACKAGES = {
   single: [],
   multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
@@ -60,6 +63,7 @@ const AKAN_RUNTIME_PACKAGES = new Set<string>([
   ...SSR_RUNTIME_PACKAGES,
   ...NATIVE_RUNTIME_PACKAGES,
   ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
+  ...MOBILE_RUNTIME_PACKAGES,
   ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
 ]);
 const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
@@ -360,11 +364,20 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
   }
   getMissingDatabaseModeDependencySpecs(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
+    return this.#getMissingDependencySpecs(this.getDatabaseModeRuntimePackages(databaseMode));
+  }
+  getMobileRuntimePackages() {
+    return [...MOBILE_RUNTIME_PACKAGES];
+  }
+  getMissingMobileDependencySpecs() {
+    return this.#getMissingDependencySpecs(this.getMobileRuntimePackages());
+  }
+  #getMissingDependencySpecs(libs: readonly string[]) {
     const rootDependencies = {
       ...this.rootPackageJson.dependencies,
       ...this.rootPackageJson.devDependencies,
     };
-    return this.getDatabaseModeRuntimePackages(databaseMode)
+    return libs
       .filter((lib) => !rootDependencies[lib])
       .map((lib) => {
         const version = this.#resolveProductionDependencyVersion(lib);

package/artifact/implicitRootLayout.ts

@@ -16,6 +16,38 @@ async function appHasStModule(appCwdPath: string): Promise<boolean> {
 
 const IMPLICIT_LAYOUT_DIR = path.join(".akan", "generated", "root-layouts");
 const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
+const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
+const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+
+/**
+ * A `_overrides.tsx` manifest is a plain, server-safe module (`export default override({ Modal: BrandModal })`)
+ * with no `"use client"` directive. The `UiOverrideProvider` that consumes it is a client component, so the
+ * build emits a `"use client"` wrapper layout that reads the manifest's default map and mounts the provider
+ * around the subtree. As a normal `"use client"` module the wrapper participates in client-entry discovery and
+ * the RSC client manifest, so the server (as a client reference) and the client (as the real component) both
+ * resolve it — and the author never writes `"use client"`.
+ */
+async function writeGeneratedOverridesLayoutFile(opts: {
+  appCwdPath: string;
+  key: string;
+  userAbsPath: string;
+}): Promise<string> {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path.join(path.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path.relative(path.dirname(absPath), opts.userAbsPath).split(path.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source = `"use client";
+import { UiOverrideProvider } from "akanjs/ui";
+import { createElement, type ReactNode } from "react";
+import value from ${JSON.stringify(userSpecifier)};
+
+export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
+  return createElement(UiOverrideProvider, { value }, children);
+}
+`;
+  await Bun.write(absPath, source);
+  return absPath;
+}
 
 interface RootBoundary {
   sourceKey: string | null;
@@ -261,12 +293,25 @@ export async function resolveSsrPageEntries(opts: {
       return segments !== null && isRootBoundarySegments(segments, basePaths);
     }),
   );
-  const base = opts.pageKeys
-    .filter((key) => !rootLayoutKeys.has(key))
-    .map((key) => ({
-      key,
-      moduleAbsPath: path.resolve(absPageDir, key),
-    }));
+  const base = await Promise.all(
+    opts.pageKeys
+      .filter((key) => !rootLayoutKeys.has(key))
+      .map(async (key) => {
+        const userAbsPath = path.resolve(absPageDir, key);
+        // `_overrides.tsx` is served through a generated `"use client"` wrapper layout that mounts the provider,
+        // so the author writes no directive; the raw manifest becomes a build seed so its slot components (and
+        // the manifest itself) enter the client graph / RSC client manifest.
+        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),

package/artifact/routeSeedIndex.ts

@@ -50,7 +50,9 @@ export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey(key);
     const files = [path.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
+      // Overrides seed the client graph like layouts: every route under the prefix must pull the generated
+      // `"use client"` override wrapper (and its slot components) into the client bundle / RSC client manifest.
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);

package/executors.ts

@@ -262,6 +262,43 @@ function validateRouteSourceExports(
   }
 }
 
+/**
+ * Statically enforces that a `_overrides.tsx` route file is a logic-free activation manifest: a plain module
+ * (no `"use client"` — the framework generates the client wrapper) that only imports components and binds them
+ * to slots through a single `export default override({ Modal: BrandModal })`. It must not declare components
+ * inline or run logic — that keeps the override contract a thin binding layer rather than a second place to
+ * author UI. Slot names and value types are validated at compile time by `override`.
+ */
+function validateOverridesSourceExports(source: string, filePath: string) {
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const fail = (message: string): never => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride: ts.ExportAssignment | null = null;
+  for (const statement of sourceFile.statements) {
+    // A "use client" directive is unnecessary (the framework wraps the manifest) but harmless if present.
+    if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
+    // The manifest imports the app components it binds; imports and type-only decls carry no runtime logic.
+    if (ts.isImportDeclaration(statement)) continue;
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+    if (ts.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 (
+    !ts.isCallExpression(expression) ||
+    !ts.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 })"`,
+    );
+}
+
 export class Executor {
   static verbose = false;
   static setVerbose(verbose: boolean) {
@@ -1466,7 +1503,9 @@ export 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();

package/frontendBuild/devGeneratedIndexSync.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-generated-index-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const seedFacet = async (root: string, facet: string, { files, dirs }: { files: string[]; dirs: string[] }) => {
+  const dir = path.join(root, "libs", "util", facet);
+  await mkdir(dir, { recursive: true });
+  await Promise.all(files.map((name) => writeFile(path.join(dir, name), "export const x = 1;\n")));
+  await Promise.all(dirs.map((name) => mkdir(path.join(dir, name), { recursive: true })));
+  return dir;
+};
+
+const barrelFor = async (root: string, facet: string, seed: { files: string[]; dirs: string[]; trigger: string }) => {
+  const dir = await seedFacet(root, facet, seed);
+  const sync = new DevGeneratedIndexSync({ workspaceRoot: root });
+  const result = await sync.syncForBatch([path.join(dir, seed.trigger)]);
+  expect(result.errors).toEqual([]);
+  return readFile(path.join(dir, "index.ts"), "utf8");
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("DevGeneratedIndexSync facet barrels", () => {
+  test("camelCase facets export only clean camelCase names", async () => {
+    const content = await barrelFor(await makeTempRoot(), "srvkit", {
+      files: [
+        "aes.ts",
+        "cloudflareApi.ts",
+        "cloudflareApi.helper.ts", // dotted → skipped
+        "pushNotificationServer.type.ts", // dotted → skipped
+        "PushNotificationServer.ts", // PascalCase in camel facet → skipped
+        "my_snake.ts", // snake_case → skipped
+        "kebab-case.ts", // kebab-case → skipped
+      ],
+      dirs: ["storageApi", "BadDir"], // PascalCase dir → skipped
+      trigger: "aes.ts",
+    });
+    expect(content).toBe(`export * from "./aes";\nexport * from "./cloudflareApi";\nexport * from "./storageApi";\n`);
+  });
+
+  test("ui facet exports only clean PascalCase names", async () => {
+    const content = await barrelFor(await makeTempRoot(), "ui", {
+      files: [
+        "Globe.tsx",
+        "AkanLogo.tsx",
+        "Globe_Dynamic.tsx", // underscore → skipped
+        "lowerStart.tsx", // camelCase in ui facet → skipped
+      ],
+      dirs: ["Code", "badDir"], // camelCase dir → skipped
+      trigger: "Globe.tsx",
+    });
+    expect(content).toBe(`export * from "./AkanLogo";\nexport * from "./Code";\nexport * from "./Globe";\n`);
+  });
+});

package/frontendBuild/devGeneratedIndexSync.ts

@@ -4,6 +4,10 @@ import path from "node:path";
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit"]);
 const FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
 const FACET_EXCLUDED_FILE_RE = /(^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 FACET_PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+const FACET_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 const MODULE_UI_TYPES = ["Template", "Unit", "Util", "View", "Zone"] as const;
 const SERVICE_UI_TYPES = ["Util", "Zone"] as const;
 const SCALAR_UI_TYPES = ["Template", "Unit"] as const;
@@ -109,15 +113,17 @@ export class DevGeneratedIndexSync {
   }
 
   async #facetContent(dir: string): Promise<string | null> {
+    const nameCasePattern = path.basename(dir) === "ui" ? FACET_PASCAL_CASE_RE : FACET_CAMEL_CASE_RE;
     const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
     const exportNames = entries
       .flatMap((entry) => {
         const name = entry.name;
         if (name.startsWith(".")) return [];
-        if (entry.isDirectory()) return [name];
+        if (entry.isDirectory()) 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.11-rc.9",
+  "version": "2.3.12-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,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/qualityScanner.ts

@@ -15,6 +15,7 @@ export interface QualityWarning {
   file?: string;
   line?: number;
   locations?: Array<{ file: string; line: number }>;
+  fix?: string;
 }
 
 export interface QualityScanResult {
@@ -48,6 +49,14 @@ interface TopLevelDeclaration {
   node: ts.Statement;
 }
 
+interface ComponentFileDeclaration {
+  name: string;
+  kind: "interface" | "type" | "function" | "variable" | "class" | "enum";
+  line: number;
+  exported: boolean;
+  isDefaultExport: boolean;
+}
+
 const MAX_FILE_LINES = 2000;
 const PLACEHOLDER_EXPORT_NAMES = new Set([
   "aa",
@@ -105,6 +114,61 @@ const CONVENTION_SUFFIXES = [
   ".store.ts",
 ] as const;
 
+// Non-PascalCase exports the framework recognizes on page/layout route modules (see PageModule/LayoutModule
+// in pkgs/akanjs/client/csrTypes.ts). PascalCase route exports (Loading, NotFound, Error) pass the component
+// check, and the `default` export is handled separately.
+const PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId",
+]);
+
+// How to remediate each rule, keyed by rule id. Surfaced as a `fix:` line per warning (text + JSON output)
+// so the scan result tells the reader what to do, not just what is wrong.
+const RULE_FIXES: Record<string, string> = {
+  "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 — 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 — 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: string): string | undefined {
+  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];
+}
+
 export class AkanQualityScanner {
   async scan(workspaceRoot: string): Promise<QualityScanResult> {
     const targetFiles = await this.#collectTargetFiles(workspaceRoot);
@@ -120,7 +184,9 @@ export 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,
     };
   }
@@ -259,20 +325,45 @@ export class AkanQualityScanner {
 
   #scanComponentQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     if (!isComponentDeclarationFile(sourceFile.file)) return [];
-    const exportedNames = getExportedDeclarationNames(sourceFile.sourceFile);
-    const allowedInternalInterfaces = new Set([...exportedNames].map((name) => `${name}Props`));
+    const isPage = isPageRouteFile(sourceFile.file);
+    const declarations = getComponentFileDeclarations(sourceFile.sourceFile);
+    // Compound/namespaced components (e.g. `Like.WithDislike = WithDislike`) are valid without being exported.
+    const compoundComponentNames = getCompoundComponentNames(sourceFile.sourceFile);
+    // Components are the exported (or compound) PascalCase values; their "<Component>Props" interface may live here.
+    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: QualityWarning[] = [];
-    for (const declaration of getInternalTypeOrFunctionDeclarations(sourceFile.sourceFile)) {
-      if (exportedNames.has(declaration.name)) continue;
-      if (declaration.kind === "interface" && allowedInternalInterfaces.has(declaration.name)) continue;
-      warnings.push({
-        rule: "akan.file.component-internal-declaration",
-        scope: "file",
-        severity: "warning",
-        file: sourceFile.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.`,
-      });
+    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: sourceFile.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`,
+        });
+        continue;
+      }
+      // A non-exported PascalCase component attached as a compound member is an accepted pattern.
+      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: sourceFile.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`,
+        });
+      }
     }
     return warnings;
   }
@@ -358,6 +449,7 @@ export function formatQualityWarnings(warnings: QualityWarning[]) {
         ...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`),
       );
     }
+    if (warning.fix) lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -464,56 +556,77 @@ function isComponentDeclarationFile(file: string) {
   return root === "apps" && area === "page";
 }
 
-function getExportedDeclarationNames(sourceFile: ts.SourceFile) {
-  const names = new Set<string>();
+function getComponentFileDeclarations(sourceFile: ts.SourceFile): ComponentFileDeclaration[] {
+  const reExportedNames = new Set<string>();
   for (const statement of sourceFile.statements) {
     if (ts.isExportDeclaration(statement) && statement.exportClause && ts.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: ts.Statement): string[] {
-  if (ts.isFunctionDeclaration(statement) && statement.name) return [statement.name.text];
-  if (ts.isClassDeclaration(statement) && statement.name) return [statement.name.text];
-  if (ts.isInterfaceDeclaration(statement)) return [statement.name.text];
-  if (ts.isTypeAliasDeclaration(statement)) return [statement.name.text];
-  if (ts.isEnumDeclaration(statement)) return [statement.name.text];
-  if (ts.isVariableStatement(statement)) {
-    return statement.declarationList.declarations
-      .filter((declaration) => ts.isIdentifier(declaration.name))
-      .map((declaration) => (declaration.name as ts.Identifier).text);
-  }
-  return [];
-}
-
-function getInternalTypeOrFunctionDeclarations(sourceFile: ts.SourceFile) {
-  const declarations: Array<{ name: string; kind: "interface" | "type" | "function"; line: number }> = [];
+  const declarations: ComponentFileDeclaration[] = [];
   for (const statement of sourceFile.statements) {
-    if (isExported(statement)) continue;
-    if (ts.isInterfaceDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "interface", line: getLine(sourceFile, statement) });
-    } else if (ts.isTypeAliasDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "type", line: getLine(sourceFile, statement) });
-    } else if (ts.isFunctionDeclaration(statement) && statement.name) {
-      declarations.push({ name: statement.name.text, kind: "function", line: getLine(sourceFile, statement) });
-    } else if (ts.isVariableStatement(statement)) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name: string, kind: ComponentFileDeclaration["kind"], line: number) =>
+      declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts.isInterfaceDeclaration(statement)) add(statement.name.text, "interface", getLine(sourceFile, statement));
+    else if (ts.isTypeAliasDeclaration(statement)) add(statement.name.text, "type", getLine(sourceFile, statement));
+    else if (ts.isEnumDeclaration(statement)) add(statement.name.text, "enum", getLine(sourceFile, statement));
+    else if (ts.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile, statement));
+    else if (ts.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile, statement));
+    else if (ts.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer)) continue;
-        declarations.push({ name: declaration.name.text, kind: "function", line: getLine(sourceFile, declaration) });
+        if (!ts.isIdentifier(declaration.name)) continue;
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile, declaration));
       }
     }
   }
   return declarations;
 }
 
+// Detects compound/namespaced component assignments like `Like.WithDislike = WithDislike`. The PascalCase
+// member is the public component name; when the right side is a PascalCase identifier it is the local
+// definition. Both are treated as valid components so the definition and its "<Component>Props" may stay local.
+function getCompoundComponentNames(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement)) continue;
+    const { expression } = statement;
+    if (!ts.isBinaryExpression(expression) || expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken) continue;
+    if (!ts.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text)) continue;
+    names.add(expression.left.name.text);
+    if (ts.isIdentifier(expression.right) && isPascalCaseName(expression.right.text)) names.add(expression.right.text);
+  }
+  return names;
+}
+
+function isComponentValueKind(kind: ComponentFileDeclaration["kind"]) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+
+function isRestrictedInternalKind(kind: ComponentFileDeclaration["kind"]) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+
+function isAllowedComponentExport(declaration: ComponentFileDeclaration, isPage: boolean) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name)) return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+
+function isPascalCaseName(name: string) {
+  // PascalCase component names start uppercase and are not SCREAMING_SNAKE_CASE constants.
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+
+function isDefaultExportStatement(statement: ts.Statement) {
+  if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
+  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+}
+
 function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
   if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx")) return [];
   return getTopLevelDeclarations(sourceFile)