@mandujs/core 0.54.7 → 0.54.9

package/package.json

@@ -1,200 +1,200 @@
-{
-  "name": "@mandujs/core",
-  "version": "0.54.7",
-  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./a11y": "./src/a11y/index.ts",
-    "./agent": "./src/agent/index.ts",
-    "./auth": "./src/auth/index.ts",
-    "./auth/login": "./src/auth/login.ts",
-    "./auth/password": "./src/auth/password.ts",
-    "./auth/reset": "./src/auth/reset.ts",
-    "./auth/verification": "./src/auth/verification.ts",
-    "./client": "./src/client/index.ts",
-    "./client/rpc": "./src/client/rpc.ts",
-    "./contract": "./src/contract/index.ts",
-    "./contract/rpc": "./src/contract/rpc.ts",
-    "./content": "./src/content/index.ts",
-    "./content/prebuild": "./src/content/prebuild.ts",
-    "./content/collection": "./src/content/collection.ts",
-    "./content/sidebar": "./src/content/sidebar.ts",
-    "./content/slug": "./src/content/slug.ts",
-    "./content/llms-txt": "./src/content/llms-txt.ts",
-    "./content/schema": "./src/content/schema.ts",
-    "./config": "./src/config/index.ts",
-    "./config/mandu": "./src/config/mandu.ts",
-    "./config/validate": "./src/config/validate.ts",
-    "./db": "./src/db/index.ts",
-    "./db/migrations": "./src/db/migrations/index.ts",
-    "./db/migrations/history-table": "./src/db/migrations/history-table.ts",
-    "./db/migrations/runner": "./src/db/migrations/runner.ts",
-    "./deploy": "./src/deploy/index.ts",
-    "./design": "./src/design/index.ts",
-    "./desktop": "./src/desktop/index.ts",
-    "./desktop/worker": "./src/desktop/worker.ts",
-    "./email": "./src/email/index.ts",
-    "./filling": "./src/filling/index.ts",
-    "./filling/cookie-codec": "./src/filling/cookie-codec.ts",
-    "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
-    "./kitchen": "./src/kitchen/index.ts",
-    "./logging": "./src/logging/index.ts",
-    "./middleware": "./src/middleware/index.ts",
-    "./middleware/csrf": "./src/middleware/csrf.ts",
-    "./middleware/oauth": "./src/middleware/oauth/index.ts",
-    "./middleware/secure": "./src/middleware/secure/index.ts",
-    "./middleware/rate-limit": "./src/middleware/rate-limit/index.ts",
-    "./middleware/session": "./src/middleware/session.ts",
-    "./testing": "./src/testing/index.ts",
-    "./testing/db": "./src/testing/db.ts",
-    "./testing/mocks": "./src/testing/mocks.ts",
-    "./testing/reporter": "./src/testing/reporter.ts",
-    "./testing/server": "./src/testing/server.ts",
-    "./testing/session": "./src/testing/session.ts",
-    "./testing/snapshot": "./src/testing/snapshot.ts",
-    "./plugins": "./src/plugins/index.ts",
-    "./plugins/define": "./src/plugins/define.ts",
-    "./plugins/runner": "./src/plugins/runner.ts",
-    "./error": "./src/error/index.ts",
-    "./i18n": "./src/i18n/index.ts",
-    "./id": "./src/id/index.ts",
-    "./observability": "./src/observability/index.ts",
-    "./openapi/generator": "./src/openapi/generator.ts",
-    "./perf": "./src/perf/index.ts",
-    "./perf/hmr-markers": "./src/perf/hmr-markers.ts",
-    "./perf/user-marks": "./src/perf/user-marks.ts",
-    "./resource": "./src/resource/index.ts",
-    "./resource/ddl/diff": "./src/resource/ddl/diff.ts",
-    "./resource/ddl/emit": "./src/resource/ddl/emit.ts",
-    "./resource/ddl/snapshot": "./src/resource/ddl/snapshot.ts",
-    "./resource/ddl/type-map": "./src/resource/ddl/type-map.ts",
-    "./resource/ddl/types": "./src/resource/ddl/types.ts",
-    "./resource/generator-repo": "./src/resource/generator-repo.ts",
-    "./resource/parser": "./src/resource/parser.ts",
-    "./resource/schema": "./src/resource/schema.ts",
-    "./router": "./src/router/index.ts",
-    "./routes": "./src/routes/index.ts",
-    "./runtime": "./src/runtime/index.ts",
-    "./runtime/cache": "./src/runtime/cache.ts",
-    "./runtime/router": "./src/runtime/router.ts",
-    "./runtime/server": "./src/runtime/server.ts",
-    "./scheduler": "./src/scheduler/index.ts",
-    "./storage/s3": "./src/storage/s3/index.ts",
-    "./guard": "./src/guard/index.ts",
-    "./guard/define-rule": "./src/guard/define-rule.ts",
-    "./guard/design-inline-class": "./src/guard/design-inline-class.ts",
-    "./guard/rule-presets": "./src/guard/rule-presets.ts",
-    "./guard/tsgolint-bridge": "./src/guard/tsgolint-bridge.ts",
-    "./bundler": "./src/bundler/index.ts",
-    "./bundler/prerender": "./src/bundler/prerender.ts",
-    "./bundler/safe-build": "./src/bundler/safe-build.ts",
-    "./bundler/types": "./src/bundler/types.ts",
-    "./bundler/hmr-types": "./src/bundler/hmr-types.ts",
-    "./bundler/scenario-matrix": "./src/bundler/scenario-matrix.ts",
-    "./bundler/vendor-cache-types": "./src/bundler/vendor-cache-types.ts",
-    "./bundler/manifest-schema": "./src/bundler/manifest-schema.ts",
-    "./bundler/analyzer": "./src/bundler/analyzer.ts",
-    "./bundler/budget": "./src/bundler/budget.ts",
-    "./bundler/plugins": "./src/bundler/plugins/index.ts",
-    "./bundler/plugins/block-generated-imports": "./src/bundler/plugins/block-generated-imports.ts",
-    "./bundler/generate-static-params": "./src/bundler/generate-static-params.ts",
-    "./diagnose": "./src/diagnose/index.ts",
-    "./dev-error-overlay": "./src/dev-error-overlay/index.ts",
-    "./middleware/compose": "./src/middleware/compose.ts",
-    "./middleware/define": "./src/middleware/define.ts",
-    "./middleware/bridge": "./src/middleware/bridge.ts",
-    "./client/hydrate": "./src/client/hydrate.ts",
-    "./runtime/fast-refresh-types": "./src/runtime/fast-refresh-types.ts",
-    "./components/Image": "./src/components/Image.tsx"
-  },
-  "files": [
-    "src/**/*",
-    "scripts/postinstall-lock.ts"
-  ],
-  "scripts": {
-    "postinstall": "bun ./scripts/postinstall-lock.ts",
-    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
-    "test:hydration": "bun test tests/hydration",
-    "test:streaming": "bun test tests/streaming-ssr",
-    "test:watch": "bun test --watch"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^15.0.0"
-  },
-  "keywords": [
-    "mandu",
-    "framework",
-    "agent",
-    "ai",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/konamgil/mandu.git",
-    "directory": "packages/core"
-  },
-  "author": "konamgil",
-  "license": "MPL-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "bun": ">=1.3.12"
-  },
-  "peerDependencies": {
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-refresh": ">=0.18.0",
-    "@tailwindcss/cli": ">=4.0.0",
-    "webview-bun": "^2.4.0",
-    "axe-core": ">=4.8.0",
-    "jsdom": ">=24.0.0",
-    "happy-dom": ">=15.0.0",
-    "@babel/core": "^7.29.0",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "eslint": "^9.0.0",
-    "eslint-plugin-react-compiler": "^19.0.0 || ^1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@tailwindcss/cli": {
-      "optional": true
-    },
-    "react-refresh": {
-      "optional": true
-    },
-    "webview-bun": {
-      "optional": true
-    },
-    "axe-core": {
-      "optional": true
-    },
-    "jsdom": {
-      "optional": true
-    },
-    "happy-dom": {
-      "optional": true
-    },
-    "@babel/core": {
-      "optional": true
-    },
-    "babel-plugin-react-compiler": {
-      "optional": true
-    },
-    "eslint": {
-      "optional": true
-    },
-    "eslint-plugin-react-compiler": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "chokidar": "^5.0.0",
-    "fast-glob": "^3.3.2",
-    "glob": "^13.0.0",
-    "minimatch": "^10.1.1",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "@mandujs/core",
+  "version": "0.54.9",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./a11y": "./src/a11y/index.ts",
+    "./agent": "./src/agent/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/login": "./src/auth/login.ts",
+    "./auth/password": "./src/auth/password.ts",
+    "./auth/reset": "./src/auth/reset.ts",
+    "./auth/verification": "./src/auth/verification.ts",
+    "./client": "./src/client/index.ts",
+    "./client/rpc": "./src/client/rpc.ts",
+    "./contract": "./src/contract/index.ts",
+    "./contract/rpc": "./src/contract/rpc.ts",
+    "./content": "./src/content/index.ts",
+    "./content/prebuild": "./src/content/prebuild.ts",
+    "./content/collection": "./src/content/collection.ts",
+    "./content/sidebar": "./src/content/sidebar.ts",
+    "./content/slug": "./src/content/slug.ts",
+    "./content/llms-txt": "./src/content/llms-txt.ts",
+    "./content/schema": "./src/content/schema.ts",
+    "./config": "./src/config/index.ts",
+    "./config/mandu": "./src/config/mandu.ts",
+    "./config/validate": "./src/config/validate.ts",
+    "./db": "./src/db/index.ts",
+    "./db/migrations": "./src/db/migrations/index.ts",
+    "./db/migrations/history-table": "./src/db/migrations/history-table.ts",
+    "./db/migrations/runner": "./src/db/migrations/runner.ts",
+    "./deploy": "./src/deploy/index.ts",
+    "./design": "./src/design/index.ts",
+    "./desktop": "./src/desktop/index.ts",
+    "./desktop/worker": "./src/desktop/worker.ts",
+    "./email": "./src/email/index.ts",
+    "./filling": "./src/filling/index.ts",
+    "./filling/cookie-codec": "./src/filling/cookie-codec.ts",
+    "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
+    "./kitchen": "./src/kitchen/index.ts",
+    "./logging": "./src/logging/index.ts",
+    "./middleware": "./src/middleware/index.ts",
+    "./middleware/csrf": "./src/middleware/csrf.ts",
+    "./middleware/oauth": "./src/middleware/oauth/index.ts",
+    "./middleware/secure": "./src/middleware/secure/index.ts",
+    "./middleware/rate-limit": "./src/middleware/rate-limit/index.ts",
+    "./middleware/session": "./src/middleware/session.ts",
+    "./testing": "./src/testing/index.ts",
+    "./testing/db": "./src/testing/db.ts",
+    "./testing/mocks": "./src/testing/mocks.ts",
+    "./testing/reporter": "./src/testing/reporter.ts",
+    "./testing/server": "./src/testing/server.ts",
+    "./testing/session": "./src/testing/session.ts",
+    "./testing/snapshot": "./src/testing/snapshot.ts",
+    "./plugins": "./src/plugins/index.ts",
+    "./plugins/define": "./src/plugins/define.ts",
+    "./plugins/runner": "./src/plugins/runner.ts",
+    "./error": "./src/error/index.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./id": "./src/id/index.ts",
+    "./observability": "./src/observability/index.ts",
+    "./openapi/generator": "./src/openapi/generator.ts",
+    "./perf": "./src/perf/index.ts",
+    "./perf/hmr-markers": "./src/perf/hmr-markers.ts",
+    "./perf/user-marks": "./src/perf/user-marks.ts",
+    "./resource": "./src/resource/index.ts",
+    "./resource/ddl/diff": "./src/resource/ddl/diff.ts",
+    "./resource/ddl/emit": "./src/resource/ddl/emit.ts",
+    "./resource/ddl/snapshot": "./src/resource/ddl/snapshot.ts",
+    "./resource/ddl/type-map": "./src/resource/ddl/type-map.ts",
+    "./resource/ddl/types": "./src/resource/ddl/types.ts",
+    "./resource/generator-repo": "./src/resource/generator-repo.ts",
+    "./resource/parser": "./src/resource/parser.ts",
+    "./resource/schema": "./src/resource/schema.ts",
+    "./router": "./src/router/index.ts",
+    "./routes": "./src/routes/index.ts",
+    "./runtime": "./src/runtime/index.ts",
+    "./runtime/cache": "./src/runtime/cache.ts",
+    "./runtime/router": "./src/runtime/router.ts",
+    "./runtime/server": "./src/runtime/server.ts",
+    "./scheduler": "./src/scheduler/index.ts",
+    "./storage/s3": "./src/storage/s3/index.ts",
+    "./guard": "./src/guard/index.ts",
+    "./guard/define-rule": "./src/guard/define-rule.ts",
+    "./guard/design-inline-class": "./src/guard/design-inline-class.ts",
+    "./guard/rule-presets": "./src/guard/rule-presets.ts",
+    "./guard/tsgolint-bridge": "./src/guard/tsgolint-bridge.ts",
+    "./bundler": "./src/bundler/index.ts",
+    "./bundler/prerender": "./src/bundler/prerender.ts",
+    "./bundler/safe-build": "./src/bundler/safe-build.ts",
+    "./bundler/types": "./src/bundler/types.ts",
+    "./bundler/hmr-types": "./src/bundler/hmr-types.ts",
+    "./bundler/scenario-matrix": "./src/bundler/scenario-matrix.ts",
+    "./bundler/vendor-cache-types": "./src/bundler/vendor-cache-types.ts",
+    "./bundler/manifest-schema": "./src/bundler/manifest-schema.ts",
+    "./bundler/analyzer": "./src/bundler/analyzer.ts",
+    "./bundler/budget": "./src/bundler/budget.ts",
+    "./bundler/plugins": "./src/bundler/plugins/index.ts",
+    "./bundler/plugins/block-generated-imports": "./src/bundler/plugins/block-generated-imports.ts",
+    "./bundler/generate-static-params": "./src/bundler/generate-static-params.ts",
+    "./diagnose": "./src/diagnose/index.ts",
+    "./dev-error-overlay": "./src/dev-error-overlay/index.ts",
+    "./middleware/compose": "./src/middleware/compose.ts",
+    "./middleware/define": "./src/middleware/define.ts",
+    "./middleware/bridge": "./src/middleware/bridge.ts",
+    "./client/hydrate": "./src/client/hydrate.ts",
+    "./runtime/fast-refresh-types": "./src/runtime/fast-refresh-types.ts",
+    "./components/Image": "./src/components/Image.tsx"
+  },
+  "files": [
+    "src/**/*",
+    "scripts/postinstall-lock.ts"
+  ],
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall-lock.ts",
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
+    "test:hydration": "bun test tests/hydration",
+    "test:streaming": "bun test tests/streaming-ssr",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0"
+  },
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MPL-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.12"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-refresh": ">=0.18.0",
+    "@tailwindcss/cli": ">=4.0.0",
+    "webview-bun": "^2.4.0",
+    "axe-core": ">=4.8.0",
+    "jsdom": ">=24.0.0",
+    "happy-dom": ">=15.0.0",
+    "@babel/core": "^7.29.0",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-compiler": "^19.0.0 || ^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/cli": {
+      "optional": true
+    },
+    "react-refresh": {
+      "optional": true
+    },
+    "webview-bun": {
+      "optional": true
+    },
+    "axe-core": {
+      "optional": true
+    },
+    "jsdom": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
+    },
+    "@babel/core": {
+      "optional": true
+    },
+    "babel-plugin-react-compiler": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    },
+    "eslint-plugin-react-compiler": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.2",
+    "glob": "^13.0.0",
+    "minimatch": "^10.1.1",
+    "zod": "^3.23.8"
+  }
+}

package/src/devtools/client/components/panel/islands-panel.tsx

@@ -183,28 +183,28 @@ export function IslandsPanel({ islands }: IslandsPanelProps): React.ReactElement
     );
   }, [islands]);
 
-  if (islands.length === 0) {
-    return (
-      <div style={styles.container}>
-        <div style={styles.emptyState}>
-          <p>
-            아직 등록된 Island가 없습니다.<br />
-            Island 컴포넌트를 사용하면 여기에 상태가 표시됩니다.
-          </p>
-        </div>
-      </div>
-    );
-  }
+  if (islands.length === 0) {
+    return (
+      <div style={styles.container}>
+        <div style={styles.emptyState}>
+          <p>
+            아직 hydration 이벤트가 없습니다.<br />
+            정적 상태는 mandu.runtime.status에서 확인하세요.
+          </p>
+        </div>
+      </div>
+    );
+  }
 
   return (
     <div style={styles.container}>
       {/* Header Stats */}
       <div style={styles.header}>
         <div style={styles.stats}>
-          <div style={styles.stat}>
-            <span>전체:</span>
-            <span style={styles.statValue}>{stats.total}</span>
-          </div>
+          <div style={styles.stat}>
+            <span>Mounts:</span>
+            <span style={styles.statValue}>{stats.total}</span>
+          </div>
           <div style={styles.stat}>
             <span>Ready</span>
             <span style={styles.statValue}>{stats.hydrated}</span>

package/src/devtools/client/components/panel/panel-container.tsx

@@ -28,7 +28,7 @@ export interface PanelContainerProps {
 
 export const TABS: TabDefinition[] = [
   { id: 'errors', label: 'Issues', icon: 'ERR', testId: testIds.tabErrors },
-  { id: 'islands', label: 'Islands', icon: 'ISL', testId: testIds.tabIslands },
+  { id: 'islands', label: 'Client Mounts', icon: 'HYD', testId: testIds.tabIslands },
   { id: 'network', label: 'Network', icon: 'NET', testId: testIds.tabNetwork },
   { id: 'guard', label: 'Guard', icon: 'GRD', testId: testIds.tabGuard },
   { id: 'preview', label: 'Changes', icon: 'CHG', testId: testIds.tabPreview },

package/src/generator/templates.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import type { RouteSpec } from "../spec/schema";
+import { generatePageComponent } from "./templates";
+
+describe("generatePageComponent", () => {
+  test("refuses to emit a placeholder for hydrating routes without a clientModule", () => {
+    const route: RouteSpec = {
+      id: "login",
+      kind: "page",
+      pattern: "/login",
+      module: "app/login/page.tsx",
+      componentModule: "app/login/page.tsx",
+      hydration: {
+        strategy: "full",
+        priority: "immediate",
+        preload: false,
+      },
+    };
+
+    expect(() => generatePageComponent(route)).toThrow("no clientModule");
+  });
+
+  test("imports the real page module for static routes instead of emitting a placeholder", () => {
+    const route: RouteSpec = {
+      id: "about",
+      kind: "page",
+      pattern: "/about",
+      module: "app/about/page.tsx",
+      componentModule: "app/about/page.tsx",
+    };
+
+    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

@@ -1,4 +1,4 @@
-import type { RouteSpec } from "../spec/schema";
+import { needsHydration, type RouteSpec } from "../spec/schema";
 import { GENERATED_RELATIVE_PATHS } from "../paths";
 
 export function generateApiHandler(route: RouteSpec): string {
@@ -238,23 +238,34 @@ function computeSlotImportPath(slotModule: string, fromDir: string): string {
   return result;
 }
 
-export function generatePageComponent(route: RouteSpec): string {
-  // Island-First: clientModule이 있으면 Island render를 SSR에서 직접 사용
-  if (route.clientModule) {
-    return generatePageComponentWithIsland(route);
-  }
-
-  // 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}
+export function generatePageComponent(route: RouteSpec): string {
+  // Island-First: clientModule이 있으면 Island render를 SSR에서 직접 사용
+  if (route.clientModule) {
+    return generatePageComponentWithIsland(route);
+  }
+
+  if (needsHydration(route)) {
+    throw new Error(
+      `[${route.id}] Route has hydration strategy "${route.hydration?.strategy}" but no clientModule. ` +
+      "Refusing to generate a placeholder page because it would disagree with runtime hydration state.",
+    );
+  }
+
+  // slotModule이 있으면 PageHandler 형식으로 생성 (filling 포함)
+  if (route.slotModule) {
+    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";
 
@@ -270,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 함수를 직접 사용
@@ -279,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,
@@ -320,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"
  */
@@ -391,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

@@ -42,7 +42,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,6 +54,24 @@ describe("findClientComponentImports", () => {
       }
     `);
 
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+    });
+  });
+
+  it("does not promote 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).toBeNull();
   });
 

package/src/router/client-entry.ts

@@ -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;
 }
@@ -171,11 +172,11 @@ function defaultExportReturnsOnlyClientComponent(source: string, localName: stri
   const functionBody = extractDefaultExportFunctionBody(source);
   if (functionBody !== null) {
     const returned = extractOnlyReturnExpression(functionBody);
-    return returned !== null && isSelfClosingJsxElement(returned, localName);
+    return returned !== null && jsxExpressionRendersClientComponent(returned, localName);
   }
 
   const arrowExpression = extractDefaultExportArrowExpression(source);
-  return arrowExpression !== null && isSelfClosingJsxElement(arrowExpression, localName);
+  return arrowExpression !== null && jsxExpressionRendersClientComponent(arrowExpression, localName);
 }
 
 function extractDefaultExportFunctionBody(source: string): string | null {
@@ -205,12 +206,41 @@ function extractOnlyReturnExpression(body: string): string | null {
   return match?.[1]?.trim() ?? null;
 }
 
-function isSelfClosingJsxElement(expression: string, localName: string): boolean {
+function jsxExpressionRendersClientComponent(expression: string, localName: string): boolean {
+  const expr = stripWrappingParentheses(expression.trim());
+  return isBareClientElement(expr, localName) || isHeadOnlyFragmentWrapper(expr, localName);
+}
+
+function isBareClientElement(expression: string, localName: string): boolean {
   const expr = stripWrappingParentheses(expression.trim());
   const escaped = escapeRegExp(localName);
   return new RegExp(`^<${escaped}\\s*/>$`).test(expr);
 }
 
+function isHeadOnlyFragmentWrapper(expression: string, localName: string): boolean {
+  const expr = stripWrappingParentheses(expression.trim());
+  const fragmentMatch = /^<>\s*([\s\S]*?)\s*<\/>$/.exec(expr);
+  if (!fragmentMatch) return false;
+
+  const escaped = escapeRegExp(localName);
+  const clientElementPattern = new RegExp(`<${escaped}(?:\\s[^>]*)?(?:/>|>)`, "g");
+  const matches = [...(fragmentMatch[1] ?? "").matchAll(clientElementPattern)];
+  if (matches.length !== 1) return false;
+  const clientElement = matches[0][0];
+  if (!isBareClientElement(clientElement, localName)) return false;
+
+  const rest = (fragmentMatch[1] ?? "")
+    .replace(clientElement, "")
+    .replace(/<meta\b[^>]*\/>/gi, "")
+    .replace(/<link\b[^>]*\/>/gi, "")
+    .replace(/<base\b[^>]*\/>/gi, "")
+    .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, "")
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+    .trim();
+
+  return rest.length === 0;
+}
+
 function stripWrappingParentheses(value: string): string {
   let current = value.trim();
   while (current.startsWith("(") && current.endsWith(")")) {
@@ -301,6 +331,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 +344,16 @@ export async function validateClientModuleForBrowserBundle(
   return null;
 }
 
+async function routeComponentHasResolvableClientEntry(
+  rootDir: string,
+  routeModule: string,
+  source: string,
+): Promise<boolean> {
+  const routeLevelClientImport = findRouteLevelClientComponentImport(source);
+  if (!routeLevelClientImport) return false;
+  return (await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module)) !== null;
+}
+
 export async function describeMissingHydrationClientModule(
   route: RouteSpec,
   rootDir: string,

package/src/router/fs-scanner.ts

@@ -401,11 +401,14 @@ export class FSScanner {
         } else {
           const routeLevelClientImport = findRouteLevelClientComponentImport(pageFileContent);
           if (routeLevelClientImport) {
-            clientModule = await resolveClientImportModulePath(
+            const resolvedClientImport = await resolveClientImportModulePath(
               rootDir,
               modulePath,
               routeLevelClientImport.module,
-            ) ?? undefined;
+            );
+            if (resolvedClientImport) {
+              clientModule = modulePath;
+            }
           }
         }
       }