@mandujs/core 0.54.2 → 0.54.3

package/src/bundler/manifest-schema.ts

@@ -28,7 +28,8 @@
  *
  * URL safety model (applies to `shared.runtime`, `shared.vendor`,
  * `shared.router`, `shared.fastRefresh.glue`, `shared.fastRefresh.runtime`,
- * `bundles[].js`, `bundles[].css`, `islands[].js`, `importMap.imports[*]`):
+ * `bundles[].js`, `bundles[].css`, `islands[].js`, `partials[].js`,
+ * `importMap.imports[*]`):
  *
  *   ALLOW:  absolute paths rooted at `/.mandu/client/` ending in `.js` or `.css`.
  *           The bundler itself only ever emits this shape.
@@ -161,15 +162,20 @@ const BundleEntrySchema = z.object({
   priority: PrioritySchema,
 });
 
-const IslandEntrySchema = z.object({
-  js: safeManduUrl("islands[].js"),
-  route: z.string().min(1),
-  priority: PrioritySchema,
-});
-
-const FastRefreshSchema = z.object({
-  runtime: safeManduUrl("shared.fastRefresh.runtime"),
-  glue: safeManduUrl("shared.fastRefresh.glue"),
+const IslandEntrySchema = z.object({
+  js: safeManduUrl("islands[].js"),
+  route: z.string().min(1),
+  priority: PrioritySchema,
+});
+
+const PartialEntrySchema = z.object({
+  js: safeManduUrl("partials[].js"),
+  priority: PrioritySchema,
+});
+
+const FastRefreshSchema = z.object({
+  runtime: safeManduUrl("shared.fastRefresh.runtime"),
+  glue: safeManduUrl("shared.fastRefresh.glue"),
 });
 
 const SharedSchema = z.object({
@@ -219,10 +225,11 @@ export const BundleManifestSchema = z
   .object({
     version: z.number().int().min(1),
     buildTime: z.string().min(1),
-    env: z.enum(["development", "production"]),
-    bundles: z.record(z.string(), BundleEntrySchema),
-    islands: z.record(z.string(), IslandEntrySchema).optional(),
-    shared: SharedSchema,
+    env: z.enum(["development", "production"]),
+    bundles: z.record(z.string(), BundleEntrySchema),
+    islands: z.record(z.string(), IslandEntrySchema).optional(),
+    partials: z.record(z.string(), PartialEntrySchema).optional(),
+    shared: SharedSchema,
     importMap: ImportMapSchema.optional(),
   })
   .strict();

package/src/bundler/types.ts

@@ -55,18 +55,28 @@ export interface BundleManifest {
       priority: "immediate" | "visible" | "idle" | "interaction";
     }
   >;
-  /** Per-island bundles (code splitting: each island file gets its own JS bundle) */
-  islands?: Record<
-    string,
-    {
-      /** JavaScript bundle path */
+  /** Per-island bundles (code splitting: each island file gets its own JS bundle) */
+  islands?: Record<
+    string,
+    {
+      /** JavaScript bundle path */
       js: string;
       /** Route that owns this island */
       route: string;
       /** Hydration priority */
-      priority: "immediate" | "visible" | "idle" | "interaction";
-    }
-  >;
+      priority: "immediate" | "visible" | "idle" | "interaction";
+    }
+  >;
+  /** Inline partial bundles (from *.partial.tsx / *.partial.ts files) */
+  partials?: Record<
+    string,
+    {
+      /** JavaScript bundle path */
+      js: string;
+      /** Hydration priority */
+      priority: "immediate" | "visible" | "idle" | "interaction";
+    }
+  >;
   /** 공유 청크 */
   shared: {
     /** Hydration 런타임 */
@@ -113,12 +123,19 @@ export interface BundleStats {
 }
 
 /** Per-island code splitting entry (used by scanIslandFiles) */
-export interface IslandFileEntry {
-  name: string;
-  filePath: string;
-  routeId: string;
-  priority: "immediate" | "visible" | "idle" | "interaction";
-}
+export interface IslandFileEntry {
+  name: string;
+  filePath: string;
+  routeId: string;
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
+
+/** Inline partial bundle entry (used by scanPartialFiles) */
+export interface PartialFileEntry {
+  name: string;
+  filePath: string;
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
 
 /**
  * 번들러 옵션

package/src/client/island.ts

@@ -3,8 +3,9 @@
  * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
  */
 
-import type { ReactNode } from "react";
-import { getServerData as getGlobalServerData } from "./window-state";
+import type { ReactNode } from "react";
+import { serializeProps } from "./serialize";
+import { getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Island 정의 타입
@@ -335,26 +336,45 @@ export interface PartialConfig {
 /**
  * Partial Island 정의 타입
  */
-export interface PartialDefinition<TProps> {
-  /** Partial 컴포넌트 */
-  component: React.ComponentType<TProps>;
-  /** 초기 props (SSR에서 전달) */
-  initialProps?: TProps;
-  /** 하이드레이션 우선순위 */
-  priority?: "immediate" | "visible" | "idle" | "interaction";
-}
+export interface PartialDefinition<TProps> {
+  /** Partial 고유 ID. 기본값은 component displayName/name 입니다. */
+  id?: string;
+  /** Partial 컴포넌트 */
+  component: React.ComponentType<TProps>;
+  /** 초기 props (SSR에서 전달) */
+  initialProps?: TProps;
+  /** 하이드레이션 우선순위 */
+  priority?: "immediate" | "visible" | "idle" | "interaction";
+  /** 명시적 번들 URL. 기본값은 `/.mandu/client/{id}.partial.js` 입니다. */
+  src?: string;
+  /** 에러 시 표시할 UI */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+  /** 로딩 중 표시할 UI */
+  loading?: () => ReactNode;
+}
 
 /**
  * 컴파일된 Partial
  */
-export interface CompiledPartial<TProps> {
+export interface CompiledPartial<TProps> {
   /** Partial 정의 */
   definition: PartialDefinition<TProps>;
   /** Mandu Partial 마커 */
   __mandu_partial: true;
   /** Partial ID */
-  __mandu_partial_id?: string;
-}
+  __mandu_partial_id?: string;
+}
+
+function normalizePartialId(id: string): string {
+  return id
+    .trim()
+    .replace(/[^A-Za-z0-9_-]/g, "-")
+    .replace(/^-+|-+$/g, "") || "partial";
+}
+
+function priorityToHydrate(priority: NonNullable<PartialDefinition<unknown>["priority"]>): string {
+  return priority === "immediate" ? "load" : priority;
+}
 
 /**
  * Partial Island 생성
@@ -379,26 +399,56 @@ export interface CompiledPartial<TProps> {
  * }
  * ```
  */
-export function partial<TProps extends Record<string, unknown>>(
-  definition: PartialDefinition<TProps>
-): CompiledPartial<TProps> & {
-  Render: React.ComponentType<TProps>;
-} {
+export function partial<TProps extends Record<string, unknown>>(
+  definition: PartialDefinition<TProps>
+): CompiledPartial<TProps> & {
+  Render: React.ComponentType<TProps>;
+} {
   if (!definition.component) {
     throw new Error("[Mandu Partial] component is required");
   }
 
-  const compiled: CompiledPartial<TProps> = {
-    definition,
-    __mandu_partial: true,
-  };
-
-  // Render 컴포넌트 생성
-  const React = require("react");
-
-  const RenderComponent: React.FC<TProps> = (props) => {
-    return React.createElement(definition.component, props);
-  };
+  const partialId = normalizePartialId(
+    definition.id ||
+    definition.component.displayName ||
+    definition.component.name ||
+    "partial",
+  );
+  const normalizedDefinition: PartialDefinition<TProps> = {
+    ...definition,
+    id: partialId,
+  };
+
+  const compiled: CompiledPartial<TProps> = {
+    definition: normalizedDefinition,
+    __mandu_partial: true,
+    __mandu_partial_id: partialId,
+  };
+
+  // Render 컴포넌트 생성
+  const React = require("react");
+
+  const RenderComponent: React.FC<TProps> = (props) => {
+    const renderProps = Object.keys(props).length > 0
+      ? props
+      : (normalizedDefinition.initialProps ?? props);
+    const priority = normalizedDefinition.priority ?? "visible";
+    const bundleSrc = normalizedDefinition.src ?? `/.mandu/client/${partialId}.partial.js`;
+
+    return React.createElement(
+      "div",
+      {
+        "data-mandu-island": partialId,
+        "data-mandu-partial": partialId,
+        "data-mandu-src": bundleSrc,
+        "data-mandu-priority": priority,
+        "data-hydrate": priorityToHydrate(priority),
+        "data-props": serializeProps(renderProps),
+        style: { display: "contents" },
+      },
+      React.createElement(normalizedDefinition.component, renderProps),
+    );
+  };
 
   return Object.assign(compiled, { Render: RenderComponent });
 }

package/src/guard/config-guard.ts

@@ -187,13 +187,19 @@ export function formatConfigGuardResult(result: ConfigGuardResult): string {
   } else if (!result.lockfileExists) {
     lines.push("💡 Lockfile 없음");
     lines.push("   'mandu lock'으로 생성 권장");
-  } else {
-    lines.push("❌ 설정 무결성 검증 실패");
-
-    for (const error of result.errors) {
-      lines.push(`   🔴 ${error.message}`);
-    }
-  }
+  } else {
+    lines.push("❌ 설정 무결성 검증 실패");
+
+    for (const error of result.errors) {
+      lines.push(`   🔴 ${error.message}`);
+    }
+
+    lines.push("");
+    lines.push("   다음 단계:");
+    lines.push("   ↳ 변경 확인: mandu lock --diff");
+    lines.push("   ↳ 의도한 변경이면: mandu lock");
+    lines.push("   ↳ 패키지 업데이트 직후라면 새 Mandu 기본값으로 lockfile을 갱신하세요.");
+  }
 
   if (result.warnings.length > 0 && result.lockfileExists) {
     lines.push("");

package/src/guard/fs-routes-policy.ts

@@ -0,0 +1,51 @@
+import type { FSRoutesGuardConfig } from "./types";
+
+export const DEFAULT_FS_ROUTES_GUARD_POLICY: FSRoutesGuardConfig = {
+  noPageToPage: true,
+  pageCanImport: [
+    "client/pages",
+    "client/widgets",
+    "client/features",
+    "client/entities",
+    "client/shared",
+    "shared/contracts",
+    "shared/types",
+    "shared/utils/client",
+  ],
+  layoutCanImport: [
+    "client/app",
+    "client/widgets",
+    "client/shared",
+    "shared/contracts",
+    "shared/types",
+    "shared/utils/client",
+  ],
+  routeCanImport: [
+    "server/api",
+    "server/application",
+    "server/domain",
+    "server/infra",
+    "server/core",
+    "shared/contracts",
+    "shared/schema",
+    "shared/types",
+    "shared/utils/client",
+    "shared/utils/server",
+    "shared/env",
+  ],
+};
+
+function clonePolicy(policy: FSRoutesGuardConfig): FSRoutesGuardConfig {
+  return {
+    noPageToPage: policy.noPageToPage,
+    pageCanImport: policy.pageCanImport ? [...policy.pageCanImport] : undefined,
+    layoutCanImport: policy.layoutCanImport ? [...policy.layoutCanImport] : undefined,
+    routeCanImport: policy.routeCanImport ? [...policy.routeCanImport] : undefined,
+  };
+}
+
+export function getDefaultFsRoutesGuardPolicy(
+  enabled: boolean
+): FSRoutesGuardConfig | undefined {
+  return enabled ? clonePolicy(DEFAULT_FS_ROUTES_GUARD_POLICY) : undefined;
+}

package/src/guard/index.ts

@@ -120,12 +120,17 @@ export {
 // Architecture Guard - Watcher
 // ═══════════════════════════════════════════════════════════════════════════
 
-export {
-  createGuardWatcher,
-  checkFile,
-  checkDirectory,
-  clearAnalysisCache,
-} from "./watcher";
+export {
+  createGuardWatcher,
+  checkFile,
+  checkDirectory,
+  clearAnalysisCache,
+} from "./watcher";
+
+export {
+  DEFAULT_FS_ROUTES_GUARD_POLICY,
+  getDefaultFsRoutesGuardPolicy,
+} from "./fs-routes-policy";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Architecture Guard - Presets

package/src/runtime/__tests__/page-render-response.test.ts

@@ -1,6 +1,32 @@
 import { describe, expect, it } from "bun:test";
 import React from "react";
 import { renderPageResponse } from "../page-render-response";
+import type { BundleManifest } from "../../bundler/types";
+
+const HYDRATED_MANIFEST: BundleManifest = {
+  version: 1,
+  buildTime: "2026-05-19T00:00:00.000Z",
+  env: "production",
+  bundles: {
+    home: {
+      js: "/.mandu/client/home.island.js",
+      dependencies: ["_runtime", "_react"],
+      priority: "visible",
+    },
+  },
+  shared: {
+    runtime: "/.mandu/client/_runtime.js",
+    vendor: "/.mandu/client/_react.js",
+    router: "/.mandu/client/_router.js",
+  },
+  importMap: {
+    imports: {
+      react: "/.mandu/client/_react.js",
+      "react-dom": "/.mandu/client/_react-dom.js",
+      "react-dom/client": "/.mandu/client/_react-dom-client.js",
+    },
+  },
+};
 
 describe("runtime page render response orchestration", () => {
   it("pre-resolves async components on the non-streaming path", async () => {
@@ -51,4 +77,27 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain("stream-page");
     expect(html).toContain("Stream Page");
   });
+
+  it("serializes non-streaming loaderData as the route server data exactly once", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement("main", null, "hydrated-page"),
+      useStreaming: false,
+      title: "Hydrated Page",
+      headTags: "",
+      isDev: false,
+      routeId: "home",
+      routePattern: "/",
+      loaderData: { items: ["a", "b"] },
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: HYDRATED_MANIFEST,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('"home":{"serverData":{"items":["a","b"]}');
+    expect(html).not.toContain('"serverData":{"home"');
+  });
 });

package/src/runtime/page-render-response.ts

@@ -84,10 +84,6 @@ function renderNonStreamingPageResponse(
   app: React.ReactElement,
   options: PageRenderResponseOptions
 ): Response {
-  const serverData = options.loaderData
-    ? { [options.routeId]: { serverData: options.loaderData } }
-    : undefined;
-
   return renderSSR(app, {
     title: options.title,
     headTags: options.headTags,
@@ -96,7 +92,7 @@ function renderNonStreamingPageResponse(
     routeId: options.routeId,
     hydration: options.hydration,
     bundleManifest: options.bundleManifest,
-    serverData,
+    serverData: options.loaderData,
     enableClientRouter: true,
     routePattern: options.routePattern,
     cssPath: options.cssPath,

package/src/runtime/ssr.ts

@@ -46,7 +46,7 @@ export interface SSROptions {
   title?: string;
   lang?: string;
   /** 서버에서 로드한 데이터 (클라이언트로 전달) */
-  serverData?: Record<string, unknown>;
+  serverData?: unknown;
   /** Hydration 설정 */
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
@@ -255,19 +255,26 @@ function generateHydrationScripts(
     ? Object.values(manifest.islands).filter((ib) => ib.route === routeId)
     : [];
 
-  if (routeIslands.length > 0) {
-    for (const ib of routeIslands) {
-      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
+  if (routeIslands.length > 0) {
+    for (const ib of routeIslands) {
+      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
   } else {
     // Fallback: route-level bundle (backward compat)
     const bundle = manifest.bundles[routeId];
     if (bundle) {
       const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  if (manifest.partials) {
+    for (const partial of Object.values(manifest.partials)) {
+      const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
 
   // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
@@ -706,12 +713,14 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   const needsHydration =
     hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
-  if (needsHydration && !islandPreWrapped) {
-    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
-    const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js;
-    content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
-  }
+  if (needsHydration && !islandPreWrapped) {
+    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js;
+    if (bundleSrc) {
+      content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
+    }
+  }
 
   // Zero-JS 모드: island이 없는 페이지에서는 클라이언트 JS 번들을 전송하지 않음
   // HMR/DevTools는 dev 환경에서만 유지 (CSS 핫리로드 등)
@@ -722,10 +731,10 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 
   if (needsHydration) {
     // 서버 데이터 스크립트 (클라이언트 hydration에서 사용)
-    if (serverData && routeId) {
-      const wrappedData = {
-        [routeId]: {
-          serverData,
+    if (serverData !== undefined && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData,
           timestamp: Date.now(),
         },
       };
@@ -862,11 +871,11 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 /**
  * Client-side Routing: 현재 라우트 정보 스크립트 생성
  */
-function generateRouteScript(
-  routeId: string,
-  pattern: string,
-  _serverData?: Record<string, unknown>
-): string {
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  _serverData?: unknown
+): string {
   const routeInfo = {
     id: routeId,
     pattern,
@@ -1167,12 +1176,12 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
  */
 export async function renderWithHydration(
   element: ReactElement,
-  options: SSROptions & {
-    routeId: string;
-    serverData: Record<string, unknown>;
-    hydration: HydrationConfig;
-    bundleManifest: BundleManifest;
-  }
+  options: SSROptions & {
+    routeId: string;
+    serverData: unknown;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
 ): Promise<Response> {
   const html = renderToHTML(element, options);
   // Phase 7.2 R1 Agent C (H1) — same CSP header logic as renderSSR.

package/src/runtime/streaming-ssr.ts

@@ -613,13 +613,16 @@ function generateHTMLShell(options: StreamingSSROptions): string {
 }
 </style>`;
 
-  let islandOpenTag = "";
-  if (needsHydration) {
-    const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
-    const priority = hydration.priority || "visible";
-    islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
-  }
+  let islandOpenTag = "";
+  const hasRouteBundle = !!(needsHydration && bundleManifest.bundles[routeId]?.js);
+  if (needsHydration) {
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
+    const priority = hydration.priority || "visible";
+    if (hasRouteBundle) {
+      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
+    }
+  }
 
   // Phase 7.1 R2 Agent D: Fast Refresh preamble. Must land in <head>
   // BEFORE any island script evaluates — the stubs it installs for
@@ -697,7 +700,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   // 1~8: hydration이 필요한 경우에만 클라이언트 JS 관련 스크립트 삽입
   if (needsHydration) {
     // 1. Critical 데이터 스크립트 (즉시 사용 가능)
-    if (criticalData && routeId) {
+    if (criticalData !== undefined && routeId) {
       const wrappedData = {
         [routeId]: {
           serverData: criticalData,
@@ -746,10 +749,16 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
 
     // 6. Island modulepreload
     const bundle = bundleManifest.bundles[routeId];
-    if (bundle) {
-      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
+    if (bundle) {
+      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+    if (bundleManifest.partials) {
+      for (const partial of Object.values(bundleManifest.partials)) {
+        const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+      }
+    }
 
     // 7. Runtime 로드
     if (bundleManifest.shared.runtime) {
@@ -783,7 +792,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   }
 
   // Island wrapper 닫기 (hydration이 필요한 경우)
-  const islandCloseTag = needsHydration ? "</div>" : "";
+  const islandCloseTag = needsHydration && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
 
   return `${islandCloseTag}</div>
   ${scripts.join("\n  ")}`;