@mandujs/core 0.54.13 → 0.54.15

package/src/runtime/server.ts

@@ -93,7 +93,7 @@ import {
 } from "./static-files";
 export { __clearStaticEtagCacheForTests } from "./static-files";
 import { extractShellHtml, createPPRResponse } from "./ppr";
-import { renderPageResponse } from "./page-render-response";
+import { renderPageResponse, type InlineClientHydrationTarget } from "./page-render-response";
 import { isRedirectResponse } from "./redirect";
 import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
@@ -479,8 +479,12 @@ export type ErrorLoader = () => Promise<{ default: ErrorComponent }>;
  * - component: React 컴포넌트
  * - filling: Slot의 ManduFilling 인스턴스 (loader 포함)
  */
-export interface PageRegistration {
-  component: React.ComponentType<{ params: Record<string, string>; loaderData?: unknown }>;
+export interface PageRegistration {
+  component: React.ComponentType<{
+    params: Record<string, string>;
+    loaderData?: unknown;
+    __manduHydration?: InlineClientHydrationTarget;
+  }>;
   filling?: ManduFilling<unknown>;
   /** #186: page 모듈의 static `metadata` export (선택) */
   metadata?: Metadata;
@@ -502,15 +506,20 @@ export type PageHandler = () => Promise<PageRegistration>;
  */
 export type MetadataHandler = () => Promise<unknown>;
 
-export interface AppContext {
-  routeId: string;
-  url: string;
-  params: Record<string, string>;
-  /** SSR loader에서 로드한 데이터 */
-  loaderData?: unknown;
-}
-
-type RouteComponent = (props: { params: Record<string, string>; loaderData?: unknown }) => React.ReactElement;
+export interface AppContext {
+  routeId: string;
+  url: string;
+  params: Record<string, string>;
+  /** SSR loader에서 로드한 데이터 */
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}
+
+type RouteComponent = (props: {
+  params: Record<string, string>;
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}) => React.ReactElement;
 type CreateAppFn = (context: AppContext) => React.ReactElement;
 
 // ========== Server Registry (인스턴스별 분리) ==========
@@ -1086,8 +1095,8 @@ async function wrapWithLayouts(
 }
 
 // Default createApp implementation (registry 기반)
-function createDefaultAppFactory(registry: ServerRegistry) {
-  return function defaultCreateApp(context: AppContext): React.ReactElement {
+function createDefaultAppFactory(registry: ServerRegistry) {
+  return function defaultCreateApp(context: AppContext): React.ReactElement {
     const Component = registry.routeComponents.get(context.routeId);
 
     if (!Component) {
@@ -1097,14 +1106,53 @@ function createDefaultAppFactory(registry: ServerRegistry) {
       );
     }
 
-    return React.createElement(Component, {
-      params: context.params,
-      loaderData: context.loaderData,
-    });
-  };
-}
-
-const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+    return React.createElement(Component, {
+      params: context.params,
+      loaderData: context.loaderData,
+      __manduHydration: context.__manduHydration,
+    });
+  };
+}
+
+async function resolveInlineClientHydrationTarget(
+  route: {
+    id: string;
+    clientModule?: string;
+    clientExportName?: string;
+    hydration?: HydrationConfig;
+  },
+  rootDir: string,
+  src: string,
+): Promise<InlineClientHydrationTarget | undefined> {
+  if (!route.clientModule || !route.clientExportName || !src) {
+    return undefined;
+  }
+
+  try {
+    const module = await import(path.join(rootDir, route.clientModule));
+    const exportName = route.clientExportName;
+    const component = exportName === "default"
+      ? module.default
+      : module[exportName] ?? module.default;
+
+    if (!component) return undefined;
+
+    return {
+      routeId: route.id,
+      src,
+      priority: route.hydration?.priority ?? "visible",
+      component,
+    };
+  } catch (error) {
+    console.warn(
+      `[Mandu] Failed to resolve inline client hydration target for "${route.id}":`,
+      error,
+    );
+    return undefined;
+  }
+}
+
+const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
 
 // ========== Request Handler ==========
 
@@ -2017,8 +2065,19 @@ function extractTitleText(titleHtml: string): string | null {
 /**
  * SSR 렌더링 (Streaming/Non-streaming)
  */
-async function renderPageSSR(
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig; errorModule?: string; loadingModule?: string; notFoundModule?: string },
+async function renderPageSSR(
+  route: {
+    id: string;
+    pattern: string;
+    layoutChain?: string[];
+    streaming?: boolean;
+    hydration?: HydrationConfig;
+    errorModule?: string;
+    loadingModule?: string;
+    notFoundModule?: string;
+    clientModule?: string;
+    clientExportName?: string;
+  },
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
@@ -2028,15 +2087,30 @@ async function renderPageSSR(
 ): Promise<Result<Response>> {
   const settings = registry.settings;
   const defaultAppCreator = createDefaultAppFactory(registry);
-  const appCreator = registry.createAppFn || defaultAppCreator;
-
-  try {
-    let app = appCreator({
-      routeId: route.id,
-      url,
-      params,
-      loaderData,
-    });
+  const appCreator = registry.createAppFn || defaultAppCreator;
+
+  try {
+    const useStreaming = route.streaming !== undefined
+      ? route.streaming
+      : settings.streaming;
+    const needsIslandHydration = !!(
+      route.hydration &&
+      route.hydration.strategy !== "none" &&
+      settings.bundleManifest
+    );
+    const routeBundle = settings.bundleManifest?.bundles[route.id];
+    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
+    const inlineClientHydration = needsIslandHydration && !useStreaming
+      ? await resolveInlineClientHydrationTarget(route, settings.rootDir, bundleSrc)
+      : undefined;
+
+    let app = appCreator({
+      routeId: route.id,
+      url,
+      params,
+      loaderData,
+      __manduHydration: inlineClientHydration,
+    });
 
     // Phase 18.β — per-route Suspense wrapper (Next.js `loading.tsx` parity).
     // If the route declared a `loading.tsx`, wrap the page element in a
@@ -2064,20 +2138,13 @@ async function renderPageSSR(
 
     // Island 래핑: 레이아웃 적용 전에 페이지 콘텐츠만 island div로 감쌈
     // 이렇게 하면 레이아웃은 island 바깥에 위치하여 하이드레이션 시 레이아웃이 유지됨
-    const needsIslandHydration = !!(
-      route.hydration &&
-      route.hydration.strategy !== "none" &&
-      settings.bundleManifest
-    );
-    const routeBundle = settings.bundleManifest?.bundles[route.id];
-    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
-    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0;
-
-    if (needsIslandHydration && !needsIslandWrap && settings.isDev) {
-      console.warn(
-        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
-        `Run mandu build/generate and ensure the route has a clientModule.`,
-      );
+    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0 && !inlineClientHydration;
+
+    if (needsIslandHydration && bundleSrc.length === 0 && settings.isDev) {
+      console.warn(
+        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
+        `Run mandu build/generate and ensure the route has a clientModule.`,
+      );
     }
 
     if (needsIslandWrap) {
@@ -2098,12 +2165,7 @@ async function renderPageSSR(
     // #186: layout chain + page metadata 병합
     const builtMeta = await buildSSRMetadata(route, params, url, registry);
 
-    // Streaming SSR 모드 결정
-    const useStreaming = route.streaming !== undefined
-      ? route.streaming
-      : settings.streaming;
-
-    const pageResponse = await renderPageResponse({
+    const pageResponse = await renderPageResponse({
       app,
       useStreaming,
       title: builtMeta.title,
@@ -2114,11 +2176,12 @@ async function renderPageSSR(
       routePattern: route.pattern,
       layoutChain: route.layoutChain,
       hydration: route.hydration,
-      bundleManifest: settings.bundleManifest,
-      loaderData,
-      cssPath: settings.cssPath,
-      islandPreWrapped: needsIslandWrap,
-      transitions: settings.transitions,
+      bundleManifest: settings.bundleManifest,
+      loaderData,
+      cssPath: settings.cssPath,
+      islandPreWrapped: needsIslandWrap,
+      inlineClientHydration,
+      transitions: settings.transitions,
       prefetch: settings.prefetch,
       spa: settings.spa,
       devtools: settings.devtools,

package/src/runtime/streaming-ssr.ts

@@ -390,7 +390,7 @@ function generateErrorScript(error: Error, routeId: string): string {
  * Island를 Suspense로 감싸는 래퍼
  * Streaming SSR에서 Island별 점진적 렌더링 지원
  */
-export function SuspenseIsland({
+export function SuspenseIsland({
   children,
   fallback,
   routeId,
@@ -401,14 +401,16 @@ export function SuspenseIsland({
   fallback?: ReactNode;
   routeId: string;
   priority?: HydrationPriority;
-  bundleSrc?: string;
-}): ReactElement {
-  const defaultFallback = React.createElement("div", {
-    "data-mandu-island": routeId,
-    "data-mandu-priority": priority,
-    "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
-    "data-mandu-loading": "true",
-    style: { display: "contents", minHeight: "50px" },
+  bundleSrc?: string;
+}): ReactElement {
+  const hydrate = priorityToHydrateStrategy(priority);
+  const defaultFallback = React.createElement("div", {
+    "data-mandu-island": routeId,
+    "data-mandu-priority": priority,
+    "data-hydrate": hydrate,
+    "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
+    "data-mandu-loading": "true",
+    style: { display: "contents", minHeight: "50px" },
   }, React.createElement("div", {
     className: "mandu-loading-skeleton",
     style: {
@@ -424,14 +426,19 @@ export function SuspenseIsland({
   return React.createElement(
     Suspense,
     { fallback: fallback || defaultFallback },
-    React.createElement("div", {
-      "data-mandu-island": routeId,
-      "data-mandu-priority": priority,
-      "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
-      style: { display: "contents" },
-    }, children)
-  );
-}
+    React.createElement("div", {
+      "data-mandu-island": routeId,
+      "data-mandu-priority": priority,
+      "data-hydrate": hydrate,
+      "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
+      style: { display: "contents" },
+    }, children)
+  );
+}
+
+function priorityToHydrateStrategy(priority: HydrationPriority): string {
+  return priority === "immediate" ? "load" : priority;
+}
 
 /**
  * Deferred 데이터를 위한 Suspense 컴포넌트
@@ -619,8 +626,9 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     const bundle = bundleManifest.bundles[routeId];
     const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
     const priority = hydration.priority || "visible";
+    const hydrate = priorityToHydrateStrategy(priority);
     if (hasRouteBundle) {
-      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
+      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" data-hydrate="${escapeHtmlAttr(hydrate)}" style="display:contents">`;
     }
   }