@mandujs/core 0.54.8 → 0.54.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.8",
+  "version": "0.54.10",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/agent/__tests__/context.test.ts

@@ -27,13 +27,31 @@ import {
   writeAgentVerifyReport,
 } from "../verify";
 
-async function writeFile(root: string, rel: string, content: string): Promise<void> {
-  const abs = path.join(root, rel);
-  await fs.mkdir(path.dirname(abs), { recursive: true });
-  await fs.writeFile(abs, content, "utf8");
-}
-
-describe("agent context", () => {
+async function writeFile(root: string, rel: string, content: string): Promise<void> {
+  const abs = path.join(root, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, content, "utf8");
+}
+
+async function runGit(root: string, args: string[]): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { ok: exitCode === 0, stdout, stderr };
+  } catch (error) {
+    return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+describe("agent context", () => {
   let root: string;
 
   beforeEach(async () => {
@@ -172,19 +190,48 @@ describe("agent context", () => {
       includeContract: false,
     });
 
-    expect(report.framework).toBe("mandu");
-    expect(report.ok).toBe(true);
-    expect(report.checks.map((check) => check.id)).toEqual(["manifest"]);
+    expect(report.framework).toBe("mandu");
+    expect(report.ok).toBe(true);
+    expect(report.checks.map((check) => check.id)).toEqual(["internal-api", "manifest"]);
     expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain("bun run typecheck");
     expect(report.nextRepairInput).toBe(".mandu/agent-verify.json");
 
     const result = await writeAgentVerifyReport(root, report);
     expect(result.path).toBe(agentVerifyReportPath(root));
     const parsed = JSON.parse(await fs.readFile(result.path, "utf8"));
-    expect(parsed.project.name).toBe("agent-app");
-  });
-
-  it("turns a verify report into repair actions", async () => {
+    expect(parsed.project.name).toBe("agent-app");
+  });
+
+  it("records changed file reasons and warns on internal API edits", async () => {
+    const version = await runGit(root, ["--version"]);
+    if (!version.ok) return;
+
+    expect((await runGit(root, ["init"])).ok).toBe(true);
+    await runGit(root, ["config", "user.email", "agent@example.com"]);
+    await runGit(root, ["config", "user.name", "Agent"]);
+    expect((await runGit(root, ["add", "."])).ok).toBe(true);
+    expect((await runGit(root, ["commit", "-m", "initial"])).ok).toBe(true);
+
+    await writeFile(root, "packages/core/src/runtime/internal-change.ts", "export const value = 1;\n");
+
+    const report = await buildAgentVerifyReport(root, {
+      includeDiagnose: false,
+      includeGuard: false,
+      includeContract: false,
+    });
+
+    const reason = report.changedFileReasons.find(
+      (entry) => entry.file === "packages/core/src/runtime/internal-change.ts",
+    );
+    expect(reason?.internalApi).toBe(true);
+    expect(reason?.recommendedChecks).toContain("bun run check:public-api && bun run check:target-boundaries");
+    expect(report.diagnostics.some((diag) => diag.code === "MANDU_VERIFY_INTERNAL_API_EDIT")).toBe(true);
+    expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain(
+      "bun run check:public-api && bun run check:target-boundaries",
+    );
+  });
+
+  it("turns a verify report into repair actions", async () => {
     await writeAgentVerifyReport(root, {
       schemaVersion: 1,
       framework: "mandu",
@@ -195,9 +242,10 @@ describe("agent context", () => {
         root,
         packageManager: "bun",
         configFile: null,
-      },
-      changedFiles: [],
-      gitAvailable: false,
+      },
+      changedFiles: [],
+      changedFileReasons: [],
+      gitAvailable: false,
       notes: [],
       ok: false,
       checks: [],

package/src/agent/types.ts

@@ -153,19 +153,27 @@ export interface AgentVerifyCheck {
   details?: Record<string, unknown>;
 }
 
-export interface AgentSuggestedCommand {
-  command: string;
-  reason: string;
-  required: boolean;
-}
-
-export interface AgentVerifyReport {
+export interface AgentSuggestedCommand {
+  command: string;
+  reason: string;
+  required: boolean;
+}
+
+export interface AgentChangedFileReason {
+  file: string;
+  reasons: string[];
+  recommendedChecks: string[];
+  internalApi: boolean;
+}
+
+export interface AgentVerifyReport {
   schemaVersion: 1;
   framework: "mandu";
   generatedAt: string;
-  project: AgentProjectSummary;
-  changedFiles: string[];
-  gitAvailable: boolean;
+  project: AgentProjectSummary;
+  changedFiles: string[];
+  changedFileReasons: AgentChangedFileReason[];
+  gitAvailable: boolean;
   notes: string[];
   ok: boolean;
   checks: AgentVerifyCheck[];

package/src/agent/verify.ts

@@ -7,8 +7,9 @@ import type { ContractViolation } from "../guard/contract-guard";
 import {
   buildAgentContext,
 } from "./context";
-import type {
-  AgentDiagnostic,
+import type {
+  AgentChangedFileReason,
+  AgentDiagnostic,
   AgentDiagnosticSeverity,
   AgentSuggestedCommand,
   AgentVerifyCheck,
@@ -208,7 +209,11 @@ function matchesChanged(
   return candidates.some((file) => changed.has(file));
 }
 
-function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic[]): AgentSuggestedCommand[] {
+function commandSuggestions(
+  changedFiles: string[],
+  diagnostics: AgentDiagnostic[],
+  changedFileReasons: AgentChangedFileReason[] = [],
+): AgentSuggestedCommand[] {
   const files = changedFiles.map(normalizePath).filter((value): value is string => Boolean(value));
   const out: AgentSuggestedCommand[] = [];
   const add = (command: string, reason: string, required: boolean) => {
@@ -240,15 +245,101 @@ function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic
   if (files.some((file) => file.startsWith("packages/mcp/"))) {
     add("bun test packages/mcp/tests", "MCP package files changed.", true);
   }
-  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
-    add("bun run check:publish", "Package metadata or lockfile changed.", true);
-  }
-  if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
+  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
+    add("bun run check:publish", "Package metadata or lockfile changed.", true);
+  }
+  if (changedFileReasons.some((entry) => entry.internalApi)) {
+    add("bun run check:public-api && bun run check:target-boundaries", "Internal framework boundaries changed.", true);
+  }
+  if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
     add("mandu agent repair --from .mandu/agent-verify.json", "Verification produced repairable diagnostics.", false);
   }
 
   return out;
-}
+}
+
+function isInternalApiEdit(file: string): boolean {
+  return [
+    "packages/core/src/runtime/",
+    "packages/core/src/bundler/",
+    "packages/core/src/server/",
+    "packages/core/src/guard/",
+    "packages/core/src/spec/",
+    "packages/core/src/router/",
+    "packages/core/src/internal/",
+  ].some((prefix) => file.startsWith(prefix));
+}
+
+function changedFileReason(file: string): AgentChangedFileReason {
+  const normalized = normalizePath(file) ?? file;
+  const reasons: string[] = [];
+  const recommendedChecks: string[] = [];
+
+  if (/\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Source code changed.");
+    recommendedChecks.push("bun run typecheck");
+  }
+  if (/\.test\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Test code changed.");
+    recommendedChecks.push(`bun test ${normalized}`);
+  }
+  if (normalized.startsWith("packages/cli/")) {
+    reasons.push("CLI behavior or documentation changed.");
+    recommendedChecks.push("bun test packages/cli/src");
+  }
+  if (normalized.startsWith("packages/mcp/")) {
+    reasons.push("MCP tool surface changed.");
+    recommendedChecks.push("bun test packages/mcp/tests");
+  }
+  if (normalized.startsWith("docs/") || normalized.endsWith("README.md") || normalized.endsWith("README.ko.md")) {
+    reasons.push("User-facing documentation changed.");
+    recommendedChecks.push("bun run check:docs-drift");
+  }
+  if (normalized === "package.json" || normalized === "bun.lock" || normalized.endsWith("/package.json")) {
+    reasons.push("Package metadata or dependency graph changed.");
+    recommendedChecks.push("bun run check:publish");
+  }
+
+  const internalApi = isInternalApiEdit(normalized);
+  if (internalApi) {
+    reasons.push("Framework internal API changed.");
+    recommendedChecks.push("bun run check:public-api && bun run check:target-boundaries");
+  }
+
+  return {
+    file: normalized,
+    reasons: reasons.length > 0 ? reasons : ["Changed file requires standard verification."],
+    recommendedChecks: [...new Set(recommendedChecks)],
+    internalApi,
+  };
+}
+
+function buildChangedFileReasons(changedFiles: string[]): AgentChangedFileReason[] {
+  return changedFiles
+    .map(normalizePath)
+    .filter((file): file is string => Boolean(file))
+    .map(changedFileReason);
+}
+
+function internalApiDiagnostics(changedFileReasons: AgentChangedFileReason[]): AgentDiagnostic[] {
+  return changedFileReasons
+    .filter((entry) => entry.internalApi)
+    .map((entry) => ({
+      code: "MANDU_VERIFY_INTERNAL_API_EDIT",
+      severity: "warning" as const,
+      title: "Internal framework API changed",
+      file: entry.file,
+      cause: "This file is part of Mandu's internal runtime/bundler/guard surface and can affect public behavior indirectly.",
+      suggestedFix: {
+        type: "run_command" as const,
+        command: "bun run check:public-api && bun run check:target-boundaries",
+        description: "Verify public API classification and target-safe import boundaries.",
+      },
+      docs: "docs/architect/public-api-boundary.md",
+      repairable: false,
+      source: "agent.verify",
+    }));
+}
 
 function check(
   id: string,
@@ -281,16 +372,22 @@ export async function buildAgentVerifyReport(
   rootDir: string = process.cwd(),
   options: BuildAgentVerifyOptions = {},
 ): Promise<AgentVerifyReport> {
-  const root = path.resolve(rootDir);
-  const changed = await collectChangedFiles(root, options);
-  const changedSet = new Set(changed.files.map(normalizePath).filter((value): value is string => Boolean(value)));
+  const root = path.resolve(rootDir);
+  const changed = await collectChangedFiles(root, options);
+  const changedSet = new Set(changed.files.map(normalizePath).filter((value): value is string => Boolean(value)));
+  const changedFileReasons = buildChangedFileReasons(changed.files);
   const context = await buildAgentContext(root, {
     includeDiagnose: false,
     includeGit: false,
   });
   const notes = [...changed.notes];
-  const checks: AgentVerifyCheck[] = [];
-  const diagnostics: AgentDiagnostic[] = [];
+  const checks: AgentVerifyCheck[] = [];
+  const diagnostics: AgentDiagnostic[] = [];
+  const internalDiagnostics = internalApiDiagnostics(changedFileReasons);
+  diagnostics.push(...internalDiagnostics);
+  checks.push(check("internal-api", "Internal API boundary", internalDiagnostics, {
+    changedFiles: changedFileReasons.filter((entry) => entry.internalApi).length,
+  }));
 
   if (options.includeDiagnose !== false) {
     try {
@@ -382,14 +479,15 @@ export async function buildAgentVerifyReport(
     schemaVersion: 1,
     framework: "mandu",
     generatedAt: new Date().toISOString(),
-    project: context.project,
-    changedFiles: changed.files,
-    gitAvailable: changed.gitAvailable,
+    project: context.project,
+    changedFiles: changed.files,
+    changedFileReasons,
+    gitAvailable: changed.gitAvailable,
     notes,
     ok,
     checks,
     diagnostics,
-    suggestedCommands: commandSuggestions(changed.files, diagnostics),
+    suggestedCommands: commandSuggestions(changed.files, diagnostics, changedFileReasons),
     nextRepairInput: AGENT_VERIFY_RELATIVE_PATH,
   };
 }

package/src/bundler/build.test.ts

@@ -248,7 +248,7 @@ describe("buildClientBundles vendor shims", () => {
       expect(noClientResult.success).toBe(false);
       expect(errors).toContain("no clientModule could be resolved");
       expect(errors).toContain("LoginForm.client");
-      expect(errors).toContain("partial({ component }).Render");
+      expect(errors).toContain("run mandu generate");
     } finally {
       await rm(missingRoot, { recursive: true, force: true });
     }

package/src/error/formatter.ts

@@ -21,15 +21,20 @@ export function formatErrorResponse(error: ManduError, options: FormatOptions =
 
   const response: Record<string, unknown> = {
     errorType: error.errorType,
-    code: error.code,
-    message: error.message,
-    summary: error.summary,
-    fix: error.fix,
-  };
-
-  if (error.route) {
-    response.route = error.route;
-  }
+    code: error.code,
+    message: error.message,
+    summary: error.summary,
+    cause: error.summary,
+    fix: error.fix,
+    filePath: error.fix.file,
+    solution: error.fix.suggestion,
+  };
+
+  if (error.route) {
+    response.route = error.route;
+    response.routeId = error.route.id;
+    response.routePattern = error.route.pattern;
+  }
 
   // 개발 모드에서만 디버그 정보 포함
   if (isDev && error.debug) {
@@ -60,27 +65,31 @@ export function formatErrorForConsole(error: ManduError, options: FormatOptions
   lines.push(`  ${error.message}`);
 
   // 요약
-  if (useColors) {
-    lines.push(`  ${CYAN}→ ${error.summary}${RESET}`);
-  } else {
-    lines.push(`  → ${error.summary}`);
-  }
+  if (useColors) {
+    lines.push(`  ${CYAN}→ ${error.summary}${RESET}`);
+  } else {
+    lines.push(`  → ${error.summary}`);
+  }
+  lines.push(`  Cause: ${error.summary}`);
 
   // 수정 안내
   lines.push("");
   if (useColors) {
     lines.push(`  ${YELLOW}Fix:${RESET} ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
     lines.push(`       ${error.fix.suggestion}`);
-  } else {
-    lines.push(`  Fix: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
-    lines.push(`       ${error.fix.suggestion}`);
-  }
+  } else {
+    lines.push(`  Fix: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
+    lines.push(`       ${error.fix.suggestion}`);
+  }
+  lines.push(`  File: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
+  lines.push(`  Solution: ${error.fix.suggestion}`);
 
   // 라우트 컨텍스트
-  if (error.route) {
-    lines.push("");
-    lines.push(`  Route: ${error.route.id} (${error.route.pattern})`);
-  }
+  if (error.route) {
+    lines.push("");
+    lines.push(`  Route ID: ${error.route.id}`);
+    lines.push(`  Route: ${error.route.pattern}`);
+  }
 
   // 디버그 정보 (개발 모드)
   if (isDev && includeStack && error.debug?.stack) {

package/src/generator/templates.test.ts

@@ -20,7 +20,7 @@ describe("generatePageComponent", () => {
     expect(() => generatePageComponent(route)).toThrow("no clientModule");
   });
 
-  test("still emits placeholders for static routes without hydration", () => {
+  test("imports the real page module for static routes instead of emitting a placeholder", () => {
     const route: RouteSpec = {
       id: "about",
       kind: "page",
@@ -29,6 +29,37 @@ describe("generatePageComponent", () => {
       componentModule: "app/about/page.tsx",
     };
 
-    expect(generatePageComponent(route)).toContain("About Page");
+    const generated = generatePageComponent(route);
+
+    expect(generated).toContain("Page Module: app/about/page.tsx");
+    expect(generated).toContain('import pageModule from "../../../../app/about/page.tsx"');
+    expect(generated).toContain("React.createElement(pageModule");
+    expect(generated).not.toContain("About Page");
+    expect(generated).not.toContain('React.createElement("p", null, "Route ID: about")');
+  });
+
+  test("renders route-level default-imported client components through the page module", () => {
+    const route: RouteSpec = {
+      id: "login",
+      kind: "page",
+      pattern: "/login",
+      module: "app/login/page.tsx",
+      componentModule: "app/login/page.tsx",
+      clientModule: "app/login/page.tsx",
+      hydration: {
+        strategy: "island",
+        priority: "immediate",
+        preload: false,
+      },
+    };
+
+    const generated = generatePageComponent(route);
+
+    expect(generated).toContain("Client Module: app/login/page.tsx");
+    expect(generated).toContain("Page Module: app/login/page.tsx");
+    expect(generated).toContain('import islandModule from "../../../../app/login/page.tsx"');
+    expect(generated).toContain("islandModule.definition.render");
+    expect(generated).toContain("React.createElement(islandModule");
+    expect(generated).not.toContain("Login Page");
   });
 });

package/src/generator/templates.ts

@@ -253,15 +253,19 @@ export function generatePageComponent(route: RouteSpec): string {
 
   // slotModule이 있으면 PageHandler 형식으로 생성 (filling 포함)
   if (route.slotModule) {
-    return generatePageHandlerWithSlot(route);
-  }
-
-  const pageName = toPascalCase(route.id);
-
-  // slotModule이 없으면 기존 방식
-  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
-// Route ID: ${route.id}
-// Pattern: ${route.pattern}
+    return generatePageHandlerWithSlot(route);
+  }
+
+  if (route.kind === "page" && route.componentModule) {
+    return generatePageComponentFromModule(route);
+  }
+
+  const pageName = toPascalCase(route.id);
+
+  // Legacy fallback for malformed historical manifests that lack componentModule.
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
 
 import React from "react";
 
@@ -277,8 +281,31 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
     React.createElement("p", null, "Pattern: ${route.pattern}")
   );
 }
-`;
-}
+`;
+}
+
+export function generatePageComponentFromModule(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const pageImportPath = computeSlotImportPath(route.componentModule!, GENERATED_RELATIVE_PATHS.webRoutes);
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Page Module: ${route.componentModule}
+
+import React from "react";
+import pageModule from "${pageImportPath}";
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+export default function ${pageName}Page(props: Props): React.ReactElement {
+  return React.createElement(pageModule as React.ComponentType<Props>, props);
+}
+`;
+}
 
 /**
  * Island-First Rendering: SSR이 island의 render 함수를 직접 사용
@@ -286,37 +313,51 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
  * - SSR과 클라이언트가 동일한 렌더링 로직 사용 → 불일치 구조적 방지
  * - slotModule 유무에 따라 두 가지 변형 생성
  */
-export function generatePageComponentWithIsland(route: RouteSpec): string {
-  const pageName = toPascalCase(route.id);
-  const clientImportPath = computeSlotImportPath(route.clientModule!, GENERATED_RELATIVE_PATHS.webRoutes);
-
-  // clientModule + slotModule → PageRegistration 형식
-  if (route.slotModule) {
-    const slotImportPath = computeSlotImportPath(route.slotModule!, GENERATED_RELATIVE_PATHS.webRoutes);
+export function generatePageComponentWithIsland(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const clientImportPath = computeSlotImportPath(route.clientModule!, GENERATED_RELATIVE_PATHS.webRoutes);
+  const pageImportPath = route.kind === "page" && route.componentModule
+    ? computeSlotImportPath(route.componentModule, GENERATED_RELATIVE_PATHS.webRoutes)
+    : null;
+  const pageModuleComment = route.kind === "page" && route.componentModule
+    ? `// Page Module: ${route.componentModule}\n`
+    : "";
+  const shouldImportPageModule = !!pageImportPath &&
+    normalizeRouteModulePath(route.componentModule) !== normalizeRouteModulePath(route.clientModule);
+  const pageImport = shouldImportPageModule ? `import pageModule from "${pageImportPath}";\n` : "";
+  const pageRenderTarget = shouldImportPageModule ? "pageModule" : "islandModule";
+  const renderHelper = generateClientBackedPageRenderHelper(pageRenderTarget, route.id);
+
+  // clientModule + slotModule → PageRegistration 형식
+  if (route.slotModule) {
+    const slotImportPath = computeSlotImportPath(route.slotModule!, GENERATED_RELATIVE_PATHS.webRoutes);
 
     return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Island-First Rendering + Slot Module
 // Route ID: ${route.id}
-// Pattern: ${route.pattern}
-// Client Module: ${route.clientModule}
-// Slot Module: ${route.slotModule}
-
-import React from "react";
-import filling from "${slotImportPath}";
-import islandModule from "${clientImportPath}";
-
-interface Props {
-  params: Record<string, string>;
-  loaderData?: unknown;
-}
-
-function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
-  const serverData = (loaderData || {}) as Record<string, unknown>;
-  const setupResult = islandModule.definition.setup(serverData);
-  return islandModule.definition.render(setupResult) as React.ReactElement;
-}
-
-// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
+// Pattern: ${route.pattern}
+// Client Module: ${route.clientModule}
+// Slot Module: ${route.slotModule}
+${pageModuleComment}
+
+import React from "react";
+import filling from "${slotImportPath}";
+import islandModule from "${clientImportPath}";
+${pageImport}
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+${renderHelper}
+
+function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  const serverData = (loaderData || {}) as Record<string, unknown>;
+  return renderClientBackedPage({ params, loaderData }, serverData);
+}
+
+// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
 export default {
   component: ${pageName}Page,
   filling: filling,
@@ -327,67 +368,124 @@ export default {
   // clientModule만 (slotModule 없음) → default export 컴포넌트
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Island-First Rendering: SSR이 island render 직접 사용
-// Route ID: ${route.id}
-// Pattern: ${route.pattern}
-// Client Module: ${route.clientModule}
-
-import React from "react";
-import islandModule from "${clientImportPath}";
-
-interface Props {
-  params: Record<string, string>;
-  loaderData?: unknown;
-}
-
-export default function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
-  const serverData = (loaderData || {}) as Record<string, unknown>;
-  const setupResult = islandModule.definition.setup(serverData);
-  return islandModule.definition.render(setupResult) as React.ReactElement;
-}
-`;
-}
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Client Module: ${route.clientModule}
+${pageModuleComment}
+
+import React from "react";
+import islandModule from "${clientImportPath}";
+${pageImport}
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+${renderHelper}
+
+export default function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  const serverData = (loaderData || {}) as Record<string, unknown>;
+  return renderClientBackedPage({ params, loaderData }, serverData);
+}
+`;
+}
 
 /**
  * slotModule이 있는 Page Route용 Handler 생성
  * - component와 filling을 함께 export
  * - server.ts에서 filling.executeLoader() 호출 가능
  */
-export function generatePageHandlerWithSlot(route: RouteSpec): string {
-  const pageName = toPascalCase(route.id);
-  const slotImportPath = computeSlotImportPath(route.slotModule!, GENERATED_RELATIVE_PATHS.serverRoutes);
-
-  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
-// Route ID: ${route.id}
-// Pattern: ${route.pattern}
-// Slot Module: ${route.slotModule}
-
-import React from "react";
-import filling from "${slotImportPath}";
-
-interface Props {
-  params: Record<string, string>;
-  loaderData?: unknown;
-}
-
-function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
-  return React.createElement("div", null,
-    React.createElement("h1", null, "${pageName} Page"),
-    React.createElement("p", null, "Route ID: ${route.id}"),
-    React.createElement("p", null, "Pattern: ${route.pattern}"),
-    loaderData ? React.createElement("pre", null, JSON.stringify(loaderData, null, 2)) : null
-  );
-}
-
-// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
+export function generatePageHandlerWithSlot(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const slotImportPath = computeSlotImportPath(route.slotModule!, GENERATED_RELATIVE_PATHS.serverRoutes);
+  const pageImportPath = route.kind === "page" && route.componentModule
+    ? computeSlotImportPath(route.componentModule, GENERATED_RELATIVE_PATHS.serverRoutes)
+    : null;
+  const pageImport = pageImportPath ? `import pageModule from "${pageImportPath}";\n` : "";
+  const pageRender = pageImportPath
+    ? `  return React.createElement(pageModule as React.ComponentType<Props>, { params, loaderData });`
+    : `  return React.createElement("div", null,
+    React.createElement("h1", null, "${pageName} Page"),
+    React.createElement("p", null, "Route ID: ${route.id}"),
+    React.createElement("p", null, "Pattern: ${route.pattern}"),
+    loaderData ? React.createElement("pre", null, JSON.stringify(loaderData, null, 2)) : null
+  );`;
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Slot Module: ${route.slotModule}
+
+import React from "react";
+import filling from "${slotImportPath}";
+${pageImport}
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+${pageRender}
+}
+
+// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
 export default {
   component: ${pageName}Page,
   filling: filling,
 };
-`;
-}
-
-/**
- * Convert string to PascalCase (handles kebab-case, snake_case)
+`;
+}
+
+function generateClientBackedPageRenderHelper(pageRenderTarget: string, routeId: string): string {
+  return `type ManduIslandModule = {
+  __mandu_island: true;
+  definition: {
+    setup: (serverData: Record<string, unknown>) => unknown;
+    render: (props: unknown) => React.ReactNode;
+  };
+};
+
+function isManduIslandModule(value: unknown): value is ManduIslandModule {
+  const candidate = value as Partial<ManduIslandModule> | null;
+  return !!(
+    candidate &&
+    typeof candidate === "object" &&
+    candidate.__mandu_island === true &&
+    typeof candidate.definition?.setup === "function" &&
+    typeof candidate.definition?.render === "function"
+  );
+}
+
+function renderClientBackedPage(props: Props, serverData: Record<string, unknown>): React.ReactElement {
+  if (isManduIslandModule(islandModule)) {
+    const setupResult = islandModule.definition.setup(serverData);
+    return islandModule.definition.render(setupResult) as React.ReactElement;
+  }
+
+  if (typeof ${pageRenderTarget} === "function") {
+    return React.createElement(${pageRenderTarget} as React.ComponentType<Props>, props);
+  }
+
+  if (typeof islandModule === "function") {
+    return React.createElement(islandModule as React.ComponentType<Record<string, unknown>>, serverData);
+  }
+
+  if (React.isValidElement(${pageRenderTarget})) {
+    return ${pageRenderTarget} as React.ReactElement;
+  }
+
+  if (React.isValidElement(islandModule)) {
+    return islandModule as React.ReactElement;
+  }
+
+  throw new Error("[Mandu] Route ${routeId} clientModule must export a Mandu island or React component.");
+}`;
+}
+
+/**
+ * Convert string to PascalCase (handles kebab-case, snake_case)
  * "todo-page" → "TodoPage"
  * "user_profile" → "UserProfile"
  */
@@ -398,6 +496,10 @@ function toPascalCase(str: string): string {
     .join("");
 }
 
-function pathDirname(filePath: string): string {
-  return filePath.replace(/\\/g, "/").split("/").slice(0, -1).join("/");
-}
+function pathDirname(filePath: string): string {
+  return filePath.replace(/\\/g, "/").split("/").slice(0, -1).join("/");
+}
+
+function normalizeRouteModulePath(filePath: string | undefined): string {
+  return (filePath ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+}

package/src/router/client-entry.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import {
   findClientComponentImports,
   findRouteLevelClientComponentImport,
+  findRouteLevelClientComponentImports,
 } from "./client-entry";
 
 describe("findClientComponentImports", () => {
@@ -15,7 +16,7 @@ describe("findClientComponentImports", () => {
       {
         module: "@/client/widgets/login-form/LoginForm.client",
         kind: "named",
-        names: ["LoginForm", "SubmitButton"],
+        names: ["LoginForm", "Button"],
       },
       {
         module: "./Header.client.tsx",
@@ -42,7 +43,7 @@ describe("findClientComponentImports", () => {
     });
   });
 
-  it("does not promote embedded client imports inside a larger server page", () => {
+  it("promotes a fragment wrapper with head-only elements and a bare client component", () => {
     const routeClient = findRouteLevelClientComponentImport(`
       import HomeApp from "@/client/pages/home/HomeApp.client";
 
@@ -54,10 +55,46 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toBeNull();
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+    });
+  });
+
+  it("detects a named-imported client component when the page returns only that component", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import { NotificationsPage } from "@/client/pages/notifications/NotificationsPage.client";
+
+      export default function Page() {
+        return <NotificationsPage />;
+      }
+    `);
+
+    expect(routeClient).toEqual({
+      module: "@/client/pages/notifications/NotificationsPage.client",
+      localName: "NotificationsPage",
+    });
   });
 
-  it("does not promote client imports when the page wrapper passes props", () => {
+  it("promotes embedded client imports inside a larger server page", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import HomeApp from "@/client/pages/home/HomeApp.client";
+
+      export default function HomePage() {
+        return <>
+          <header>Server shell</header>
+          <HomeApp />
+        </>;
+      }
+    `);
+
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+    });
+  });
+
+  it("promotes client imports when the page wrapper passes props", () => {
     const routeClient = findRouteLevelClientComponentImport(`
       import PledgePage from "@/client/pages/pledges/PledgePage.client";
 
@@ -66,6 +103,38 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toBeNull();
+    expect(routeClient).toEqual({
+      module: "@/client/pages/pledges/PledgePage.client",
+      localName: "PledgePage",
+    });
+  });
+
+  it("detects multiple rendered client imports in a server shell", () => {
+    const routeClients = findRouteLevelClientComponentImports(`
+      import { CommentsSection } from "@/client/widgets/comments-section/CommentsSection.client";
+      import { PledgeActions } from "@/client/widgets/pledge-actions/PledgeActions.client";
+
+      export default async function PledgePage({ params }) {
+        const pledge = await Promise.resolve(params.id);
+        return (
+          <main>
+            <article>{pledge}</article>
+            <PledgeActions pledgeId={params.id} />
+            <CommentsSection pledgeId={params.id} />
+          </main>
+        );
+      }
+    `);
+
+    expect(routeClients).toEqual([
+      {
+        module: "@/client/widgets/comments-section/CommentsSection.client",
+        localName: "CommentsSection",
+      },
+      {
+        module: "@/client/widgets/pledge-actions/PledgeActions.client",
+        localName: "PledgeActions",
+      },
+    ]);
   });
 });

package/src/router/client-entry.ts

@@ -62,7 +62,8 @@ export function findClientComponentImports(source: string): ClientComponentImpor
       for (const rawName of namedMatch[1].split(",")) {
         const name = rawName.trim();
         if (!name) continue;
-        names.push(name.split(/\s+as\s+/i)[0].trim());
+        const parts = name.split(/\s+as\s+/i).map((part) => part.trim()).filter(Boolean);
+        names.push(parts[1] ?? parts[0]);
       }
     }
 
@@ -100,19 +101,18 @@ export function findClientComponentImports(source: string): ClientComponentImpor
 }
 
 export function findRouteLevelClientComponentImport(source: string): RouteLevelClientComponentImport | null {
-  const defaultImports = findClientComponentImports(source).filter((entry) => {
-    const localName = entry.names[0] ?? "";
-    return entry.kind === "default" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName);
-  });
-
-  if (defaultImports.length !== 1) return null;
+  return findRouteLevelClientComponentImports(source)[0] ?? null;
+}
 
-  const entry = defaultImports[0];
-  const localName = entry.names[0];
-  if (!entry.module || !localName) return null;
-  if (!defaultExportReturnsOnlyClientComponent(source, localName)) return null;
+export function findRouteLevelClientComponentImports(source: string): RouteLevelClientComponentImport[] {
+  const candidates = findClientComponentImports(source).flatMap((entry) =>
+    entry.names
+      .filter((localName) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName))
+      .map((localName) => ({ module: entry.module, localName }))
+  );
 
-  return { module: entry.module, localName };
+  if (candidates.length === 0) return [];
+  return defaultExportRendersClientComponents(source, candidates);
 }
 
 export async function resolveClientImportModulePath(
@@ -141,7 +141,8 @@ export async function shouldPreserveExistingClientModule(
   if (source === null) return false;
   if (hasUseServerDirective(source)) return false;
   if (clientModuleIsRouteComponent(route, clientModule)) {
-    return hasUseClientDirective(source);
+    if (hasUseClientDirective(source)) return true;
+    return await routeComponentHasResolvableClientEntry(rootDir, clientModule, source);
   }
   return true;
 }
@@ -167,15 +168,28 @@ function expandClientModuleCandidates(basePath: string): string[] {
   ];
 }
 
-function defaultExportReturnsOnlyClientComponent(source: string, localName: string): boolean {
+function defaultExportRendersClientComponents(
+  source: string,
+  candidates: RouteLevelClientComponentImport[],
+): RouteLevelClientComponentImport[] {
   const functionBody = extractDefaultExportFunctionBody(source);
   if (functionBody !== null) {
-    const returned = extractOnlyReturnExpression(functionBody);
-    return returned !== null && isSelfClosingJsxElement(returned, localName);
+    const returned = extractTopLevelReturnExpression(functionBody);
+    return returned !== null ? jsxExpressionRendersClientComponents(returned, candidates) : [];
   }
 
   const arrowExpression = extractDefaultExportArrowExpression(source);
-  return arrowExpression !== null && isSelfClosingJsxElement(arrowExpression, localName);
+  if (arrowExpression !== null) {
+    return jsxExpressionRendersClientComponents(arrowExpression, candidates);
+  }
+
+  const arrowBody = extractDefaultExportArrowFunctionBody(source);
+  if (arrowBody !== null) {
+    const returned = extractTopLevelReturnExpression(arrowBody);
+    return returned !== null ? jsxExpressionRendersClientComponents(returned, candidates) : [];
+  }
+
+  return [];
 }
 
 function extractDefaultExportFunctionBody(source: string): string | null {
@@ -200,15 +214,109 @@ function extractDefaultExportArrowExpression(source: string): string | null {
   return semicolon === -1 ? rest : rest.slice(0, semicolon);
 }
 
-function extractOnlyReturnExpression(body: string): string | null {
-  const match = /^\s*return\s+([\s\S]*?)\s*;?\s*$/.exec(body);
-  return match?.[1]?.trim() ?? null;
+function extractDefaultExportArrowFunctionBody(source: string): string | null {
+  const match = /export\s+default\s+(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>\s*\{/m.exec(source);
+  if (!match) return null;
+
+  const openBrace = match.index + match[0].lastIndexOf("{");
+  const closeBrace = findMatchingBrace(source, openBrace);
+  if (closeBrace === -1) return null;
+  return source.slice(openBrace + 1, closeBrace);
+}
+
+function extractTopLevelReturnExpression(body: string): string | null {
+  let quote: '"' | "'" | "`" | null = null;
+  let lineComment = false;
+  let blockComment = false;
+  let braceDepth = 0;
+  let parenDepth = 0;
+  let bracketDepth = 0;
+
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    const next = body[i + 1];
+    const prev = body[i - 1];
+
+    if (lineComment) {
+      if (char === "\n" || char === "\r") lineComment = false;
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i++;
+      }
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote && prev !== "\\") quote = null;
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      i++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i++;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (braceDepth === 0 && parenDepth === 0 && bracketDepth === 0 && body.startsWith("return", i)) {
+      const before = body[i - 1] ?? "";
+      const after = body[i + "return".length] ?? "";
+      if (!isIdentifierChar(before) && !isIdentifierChar(after)) {
+        const expr = body.slice(i + "return".length).trim();
+        return trimTrailingSemicolon(expr);
+      }
+    }
+
+    if (char === "{") braceDepth++;
+    if (char === "}") braceDepth = Math.max(0, braceDepth - 1);
+    if (char === "(") parenDepth++;
+    if (char === ")") parenDepth = Math.max(0, parenDepth - 1);
+    if (char === "[") bracketDepth++;
+    if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+  }
+
+  return null;
+}
+
+function trimTrailingSemicolon(value: string): string {
+  const trimmed = value.trim();
+  return trimmed.endsWith(";") ? trimmed.slice(0, -1).trim() : trimmed;
 }
 
-function isSelfClosingJsxElement(expression: string, localName: string): boolean {
+function jsxExpressionRendersClientComponents(
+  expression: string,
+  candidates: RouteLevelClientComponentImport[],
+): RouteLevelClientComponentImport[] {
   const expr = stripWrappingParentheses(expression.trim());
+  const seen = new Set<string>();
+  const rendered: RouteLevelClientComponentImport[] = [];
+
+  for (const candidate of candidates) {
+    const key = `${candidate.module}\0${candidate.localName}`;
+    if (seen.has(key)) continue;
+    if (!jsxExpressionContainsClientElement(expr, candidate.localName)) continue;
+    seen.add(key);
+    rendered.push(candidate);
+  }
+
+  return rendered;
+}
+
+function jsxExpressionContainsClientElement(expression: string, localName: string): boolean {
   const escaped = escapeRegExp(localName);
-  return new RegExp(`^<${escaped}\\s*/>$`).test(expr);
+  return new RegExp(`<${escaped}(?:\\s|/|>)`).test(expression);
 }
 
 function stripWrappingParentheses(value: string): string {
@@ -287,6 +395,10 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function isIdentifierChar(value: string): boolean {
+  return /[A-Za-z0-9_$]/.test(value);
+}
+
 export async function validateClientModuleForBrowserBundle(
   route: RouteSpec,
   rootDir: string,
@@ -301,6 +413,9 @@ export async function validateClientModuleForBrowserBundle(
   }
 
   if (clientModuleIsRouteComponent(route) && !hasUseClientDirective(source)) {
+    if (await routeComponentHasResolvableClientEntry(rootDir, route.clientModule, source)) {
+      return null;
+    }
     return (
       `[${route.id}] Route component "${route.clientModule}" is configured as clientModule, ` +
       `but it is a server page (missing "use client"). Mandu will not bundle server pages into client islands. ` +
@@ -311,6 +426,20 @@ export async function validateClientModuleForBrowserBundle(
   return null;
 }
 
+async function routeComponentHasResolvableClientEntry(
+  rootDir: string,
+  routeModule: string,
+  source: string,
+): Promise<boolean> {
+  const routeLevelClientImports = findRouteLevelClientComponentImports(source);
+  for (const routeLevelClientImport of routeLevelClientImports) {
+    if ((await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module)) !== null) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export async function describeMissingHydrationClientModule(
   route: RouteSpec,
   rootDir: string,
@@ -350,8 +479,8 @@ export async function describeMissingHydrationClientModule(
 
   return (
     `${base}\n` +
-    `  The page imports client-looking modules, but inline .client.tsx imports are not route bundles:\n` +
+    `  The page imports client-looking modules, but none was linked into the route manifest:\n` +
     `${importList}\n` +
-    `  Fix: use partial({ component }).Render for embedded client regions, or expose a route-level client module.`
+    `  Fix: run mandu generate with the current source, or set an explicit route-level clientModule.`
   );
 }

package/src/router/fs-scanner.ts

@@ -31,7 +31,7 @@ import {
 import { mark, measure } from "../perf";
 import { METADATA_ROUTES } from "../routes/types";
 import {
-  findRouteLevelClientComponentImport,
+  findRouteLevelClientComponentImports,
   hasUseClientDirective,
   resolveClientImportModulePath,
 } from "./client-entry";
@@ -399,13 +399,17 @@ export class FSScanner {
         if (hasUseClient) {
           clientModule = modulePath;
         } else {
-          const routeLevelClientImport = findRouteLevelClientComponentImport(pageFileContent);
-          if (routeLevelClientImport) {
-            clientModule = await resolveClientImportModulePath(
+          const routeLevelClientImports = findRouteLevelClientComponentImports(pageFileContent);
+          for (const routeLevelClientImport of routeLevelClientImports) {
+            const resolvedClientImport = await resolveClientImportModulePath(
               rootDir,
               modulePath,
               routeLevelClientImport.module,
-            ) ?? undefined;
+            );
+            if (resolvedClientImport) {
+              clientModule = modulePath;
+              break;
+            }
           }
         }
       }