@mandujs/core 0.54.17 → 0.54.18

package/src/runtime/ssr.ts

@@ -8,10 +8,11 @@ import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
 import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
-import { generateFastRefreshPreamble } from "../bundler/dev";
+import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
 import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
-import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
 
 /**
  * Issue #192 — `@view-transition` at-rule block.
@@ -275,8 +276,16 @@ function generateHydrationScripts(
       scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
     }
   }
-
-  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
+
+  if (manifest.boundaries) {
+    for (const boundary of Object.values(manifest.boundaries)) {
+      if (boundary.route !== routeId) continue;
+      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(manifest.shared.runtime)}"></script>`);
   }
@@ -703,7 +712,9 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   } catch { /* client 모듈 로드 실패 시 무시 */ }
 
   const renderToString = getRenderToString();
-  let content = renderToString(element);
+  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
+    renderToString(element),
+  );
 
   // 렌더링 중 수집된 head 태그
   collectedHeadTags = headGet?.() ?? "";

package/src/runtime/streaming-ssr.ts

@@ -23,9 +23,13 @@ import { escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript, escapeJsStri
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 import { getRenderToString } from "./react-renderer";
 import { mark, measure } from "../perf";
-import { generateFastRefreshPreamble } from "../bundler/dev";
-import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
-import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
+import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
+import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
+import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
+import {
+  createManduClientBoundaryRenderScope,
+  renderWithManduClientBoundaryManifest,
+} from "../internal/client-boundary";
 
 /**
  * Issue #192 — `@view-transition` at-rule, mirror of the constant in
@@ -110,10 +114,12 @@ export interface StreamingSSROptions {
   // Note: deferredData는 renderWithDeferredData의 deferredPromises로 대체됨
   /** Hydration 설정 */
   hydration?: HydrationConfig;
-  /** 번들 매니페스트 */
-  bundleManifest?: BundleManifest;
-  /** 추가 head 태그 (SEO metadata와 병합됨) */
-  headTags?: string;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** React element already contains its own island wrapper. */
+  islandPreWrapped?: boolean;
+  /** 추가 head 태그 (SEO metadata와 병합됨) */
+  headTags?: string;
   /**
    * SEO 메타데이터 (Layout 체인 또는 단일 객체)
    * - 배열: [rootLayout, ...nestedLayouts, page] 순서로 병합
@@ -550,9 +556,10 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     isDev = false,
     transitions = true,
     prefetch = true,
-    spa = true,
-    layoutChain,
-  } = options;
+    spa = true,
+    layoutChain,
+    islandPreWrapped = false,
+  } = options;
 
   // Issue #233 — layout-key for SPA cross-layout detection. Mirror of the
   // block in `ssr.ts::renderToHTML`; see that call-site for the full
@@ -627,7 +634,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
     const priority = hydration.priority || "visible";
     const hydrate = priorityToHydrateStrategy(priority);
-    if (hasRouteBundle) {
+    if (hasRouteBundle && !islandPreWrapped) {
       islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" data-hydrate="${escapeHtmlAttr(hydrate)}" style="display:contents">`;
     }
   }
@@ -695,10 +702,11 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     bundleManifest,
     isDev = false,
     hmrPort,
-    enableClientRouter = false,
-    hydration,
-    devtools,
-  } = options;
+    enableClientRouter = false,
+    hydration,
+    devtools,
+    islandPreWrapped = false,
+  } = options;
 
   const scripts: string[] = [];
 
@@ -755,11 +763,21 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
       scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.runtime)}">`);
     }
 
-    // 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)}">`);
+    // 6. Island modulepreload
+    const routeIslands = bundleManifest.islands
+      ? Object.values(bundleManifest.islands).filter((island) => island.route === routeId)
+      : [];
+    if (routeIslands.length > 0) {
+      for (const island of routeIslands) {
+        const cacheBust = `${island.js}${island.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+      }
+    } else {
+      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 (bundleManifest.partials) {
       for (const partial of Object.values(bundleManifest.partials)) {
@@ -767,10 +785,18 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
         scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
       }
     }
-
-    // 7. Runtime 로드
-    if (bundleManifest.shared.runtime) {
-      scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.runtime)}"></script>`);
+
+    if (bundleManifest.boundaries) {
+      for (const boundary of Object.values(bundleManifest.boundaries)) {
+        if (boundary.route !== routeId) continue;
+        const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+      }
+    }
+
+    // 7. Runtime 로드
+    if (bundleManifest.shared.runtime) {
+      scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.runtime)}"></script>`);
     }
 
     // 7.5 React internals shim (must run before react-dom/client runs)
@@ -798,9 +824,9 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   if (isDev && shouldInjectDevtoolsStreaming(devtools, bundleManifest)) {
     scripts.push(generateStreamingDevtoolsScript(bundleManifest));
   }
-
-  // Island wrapper 닫기 (hydration이 필요한 경우)
-  const islandCloseTag = needsHydration && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
+
+  // Island wrapper 닫기 (hydration이 필요한 경우)
+  const islandCloseTag = needsHydration && !islandPreWrapped && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
 
   return `${islandCloseTag}</div>
   ${scripts.join("\n  ")}`;
@@ -1028,9 +1054,13 @@ export async function renderToStream(
     warnStreamingCaveats(isDev);
     streamingWarnings.markWarned();
   }
-
-  const encoder = new TextEncoder();
-  const collectedHeadTags = collectStreamingHeadTags(element);
+
+  const encoder = new TextEncoder();
+  const collectedHeadTags = renderWithManduClientBoundaryManifest(
+    options.routeId,
+    options.bundleManifest,
+    () => collectStreamingHeadTags(element),
+  );
   const resolvedOptions = collectedHeadTags
     ? { ...options, headTags: [options.headTags, collectedHeadTags].filter(Boolean).join("\n") }
     : options;
@@ -1072,44 +1102,53 @@ export async function renderToStream(
   // try/catch safely returns an empty string in that case, and any
   // `useHead`-pushed tags from async components are instead picked
   // up by `buildHtmlTail` on the way out. No additional wiring is
-  // needed on this code path.
-  // 실패 시 throw → renderStreamingResponse에서 500 처리
-  const renderToReadableStream = getRenderToReadableStream();
-  const reactStream = await renderToReadableStream(element, {
-    onError: (error: Error) => {
-      if (timedOut) return;
-
-      metrics.hasError = true;
-      const streamingError: StreamingError = {
-        error,
-        isShellError: !shellSent,
-        recoverable: shellSent,
-        timestamp: Date.now(),
-      };
-
-      console.error("[Mandu Streaming] React render error:", error);
-
-      if (!shellSent) {
-        // Shell 전 에러 - 콜백만 호출 (throw는 하지 않음, 이미 스트림 시작됨)
-        onShellError?.(streamingError);
-      } else {
-        // Shell 후 에러 - 스트림에 에러 스크립트 삽입됨
-        onStreamError?.(streamingError);
-      }
-
-      onError?.(error);
-    },
-  });
-
-  // allReady는 백그라운드에서 메트릭용으로만 사용 (대기 안 함!)
-  reactStream.allReady.then(() => {
-    metrics.allReadyTime = Date.now() - metrics.startTime;
-    if (isDev) {
-      console.log(`[Mandu Streaming] All ready: ${routeId} (${metrics.allReadyTime}ms)`);
-    }
-  }).catch(() => {
-    // 에러는 onError에서 이미 처리됨
-  });
+  // needed on this code path.
+  // 실패 시 throw → renderStreamingResponse에서 500 처리
+  const renderToReadableStream = getRenderToReadableStream();
+  const renderBoundaryScope = createManduClientBoundaryRenderScope(
+    routeId,
+    resolvedOptions.bundleManifest,
+  );
+  const scopedElement = renderBoundaryScope.wrapElement(element);
+  const reactStream = await renderBoundaryScope(() =>
+    renderToReadableStream(scopedElement, {
+      onError: (error: Error) => {
+        if (timedOut) return;
+
+        metrics.hasError = true;
+        const streamingError: StreamingError = {
+          error,
+          isShellError: !shellSent,
+          recoverable: shellSent,
+          timestamp: Date.now(),
+        };
+
+        console.error("[Mandu Streaming] React render error:", error);
+
+        if (!shellSent) {
+          // Shell 전 에러 - 콜백만 호출 (throw는 하지 않음, 이미 스트림 시작됨)
+          onShellError?.(streamingError);
+        } else {
+          // Shell 후 에러 - 스트림에 에러 스크립트 삽입됨
+          onStreamError?.(streamingError);
+        }
+
+        onError?.(error);
+      },
+    }),
+  );
+
+  // allReady는 백그라운드에서 메트릭용으로만 사용 (대기 안 함!)
+  renderBoundaryScope(() => {
+    reactStream.allReady.then(() => {
+      metrics.allReadyTime = Date.now() - metrics.startTime;
+      if (isDev) {
+        console.log(`[Mandu Streaming] All ready: ${routeId} (${metrics.allReadyTime}ms)`);
+      }
+    }).catch(() => {
+      // 에러는 onError에서 이미 처리됨
+    });
+  });
 
   // Custom stream으로 래핑 (Shell + React Content + Tail)
   let tailSent = false;
@@ -1118,10 +1157,12 @@ export async function renderToStream(
     ? metrics.startTime + streamTimeout
     : null;
 
-  async function readWithTimeout(): Promise<ReadableStreamReadResult<Uint8Array> | null> {
-    if (!deadline) {
-      return reader.read() as Promise<ReadableStreamReadResult<Uint8Array>>;
-    }
+  async function readWithTimeout(): Promise<ReadableStreamReadResult<Uint8Array> | null> {
+    if (!deadline) {
+      return renderBoundaryScope(() =>
+        reader.read() as Promise<ReadableStreamReadResult<Uint8Array>>
+      );
+    }
 
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
@@ -1133,10 +1174,12 @@ export async function renderToStream(
       timeoutId = setTimeout(() => resolve({ kind: "timeout" }), remaining);
     });
 
-    const readPromise = reader
-      .read()
-      .then((result) => ({ kind: "read" as const, result: result as ReadableStreamReadResult<Uint8Array> }))
-      .catch((error: unknown) => ({ kind: "error" as const, error }));
+    const readPromise = renderBoundaryScope(() =>
+      reader
+        .read()
+        .then((result) => ({ kind: "read" as const, result: result as ReadableStreamReadResult<Uint8Array> }))
+        .catch((error: unknown) => ({ kind: "error" as const, error }))
+    );
 
     const result = await Promise.race([readPromise, timeoutPromise]);
 

package/src/spec/schema.ts

@@ -8,7 +8,7 @@ export type SpecHydrationStrategy = z.infer<typeof SpecHydrationStrategy>;
 export const HydrationPriority = z.enum(["immediate", "visible", "idle", "interaction"]);
 export type HydrationPriority = z.infer<typeof HydrationPriority>;
 
-export const HydrationConfig = z.object({
+export const HydrationConfig = z.object({
   /**
    * Hydration 전략
    * - none: 순수 Static HTML (JS 없음)
@@ -32,10 +32,35 @@ export const HydrationConfig = z.object({
    */
   preload: z.boolean().default(false),
 });
-
-export type HydrationConfig = z.infer<typeof HydrationConfig>;
-
-// ========== Loader 설정 ==========
+
+export type HydrationConfig = z.infer<typeof HydrationConfig>;
+
+// ========== Client Boundary Metadata ==========
+
+export const RouteClientBoundarySource = z.object({
+  file: z.string().min(1),
+  line: z.number().int().positive(),
+  column: z.number().int().positive(),
+});
+export type RouteClientBoundarySource = z.infer<typeof RouteClientBoundarySource>;
+
+export const RouteClientBoundary = z.object({
+  id: z.string().min(1),
+  routeId: z.string().min(1),
+  module: z.string().min(1),
+  importSpecifier: z.string().min(1).optional(),
+  exportName: z.string().min(1),
+  localName: z.string().min(1),
+  hydrate: z.string().min(1).default("visible"),
+  ordinal: z.number().int().nonnegative(),
+  propsSource: z.enum(["inline", "route-data", "data-props", "none", "unknown"]).default("inline"),
+  propsKeys: z.array(z.string()).optional(),
+  hasSpreadProps: z.boolean().optional(),
+  source: RouteClientBoundarySource,
+});
+export type RouteClientBoundary = z.infer<typeof RouteClientBoundary>;
+
+// ========== Loader 설정 ==========
 
 export const LoaderConfig = z.object({
   /**
@@ -75,6 +100,7 @@ const RouteSpecBase = {
   slotModule: z.string().optional(),
   clientModule: z.string().optional(),
   clientExportName: z.string().optional(),
+  boundaries: z.array(RouteClientBoundary).optional(),
   contractModule: z.string().optional(),
   hydration: HydrationConfig.optional(),
   loader: LoaderConfig.optional(),