@mandujs/core 0.54.16 → 0.54.18

package/src/runtime/handlers.ts

@@ -23,7 +23,7 @@ import {
   type PageRegistration,
 } from "./server";
 import { registerManifest } from "./registry";
-import { needsHydration, type RoutesManifest } from "../spec/schema";
+import { needsHydration, type RouteClientBoundary, type RoutesManifest } from "../spec/schema";
 
 type RouteModule = Record<string, unknown>;
 
@@ -84,7 +84,7 @@ function createMethodDispatcher(module: RouteModule, routeId: string) {
   };
 }
 
-export interface RegisterHandlersOptions {
+export interface RegisterHandlersOptions {
   /**
    * Module import function (dev: importFresh, start: standard import).
    * The optional `opts.changedFile` is forwarded into Phase 7.0 B5's
@@ -92,7 +92,17 @@ export interface RegisterHandlersOptions {
    * module's import graph, `importFn` returns the cached bundle in ~0.1 ms
    * instead of re-running Bun.build.
    */
-  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>;
+  importFn: (
+    modulePath: string,
+    opts?: {
+      changedFile?: string;
+      clientBoundaryTransform?: {
+        routeId: string;
+        hydrate?: string;
+        boundaries?: RouteClientBoundary[];
+      };
+    },
+  ) => Promise<unknown>;
   /** Set for tracking already registered layout paths */
   registeredLayouts: Set<string>;
   /** Clear layout cache on reload */
@@ -115,9 +125,23 @@ export async function registerManifestHandlers(
   rootDir: string,
   options: RegisterHandlersOptions
 ): Promise<void> {
-  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
-  const importOpts: { changedFile?: string } | undefined =
-    changedFile !== undefined ? { changedFile } : undefined;
+  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
+  const baseImportOpts: { changedFile?: string } | undefined =
+    changedFile !== undefined ? { changedFile } : undefined;
+  const importOptsForRoute = (route?: RoutesManifest["routes"][number]) => {
+    const boundaryTransform = route?.kind === "page" && route.boundaries?.length
+        ? {
+            routeId: route.id,
+            hydrate: route.hydration?.priority ?? "visible",
+            boundaries: route.boundaries,
+          }
+      : undefined;
+    if (!baseImportOpts && !boundaryTransform) return undefined;
+    return {
+      ...baseImportOpts,
+      ...(boundaryTransform ? { clientBoundaryTransform: boundaryTransform } : {}),
+    };
+  };
 
   if (isReload) {
     registeredLayouts.clear();
@@ -134,19 +158,19 @@ export async function registerManifestHandlers(
     // runtime dispatcher invokes the default export on each request
     // so HMR reloads pick up edits automatically (same pattern as
     // API routes below).
-    if (route.kind === "metadata") {
-      const modulePath = path.resolve(rootDir, route.module);
-      registerMetadataHandler(route.id, async () => {
-        return importFn(modulePath, importOpts);
-      });
-      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
-      continue;
+    if (route.kind === "metadata") {
+      const modulePath = path.resolve(rootDir, route.module);
+      registerMetadataHandler(route.id, async () => {
+        return importFn(modulePath, importOptsForRoute(route));
+      });
+      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
+      continue;
     }
 
-    if (route.kind === "api") {
-      const modulePath = path.resolve(rootDir, route.module);
-      try {
-        const module = (await importFn(modulePath, importOpts)) as RouteModule;
+    if (route.kind === "api") {
+      const modulePath = path.resolve(rootDir, route.module);
+      try {
+        const module = (await importFn(modulePath, importOptsForRoute(route))) as RouteModule;
         let handler: unknown = module.default ?? module.handler ?? module;
 
         // 1) ManduFilling instance
@@ -193,7 +217,7 @@ export async function registerManifestHandlers(
               // Layout modules must export a default component. Runtime
               // validation in `renderToHTML` / page-loader asserts this —
               // so casting the unknown `importFn` result is safe here.
-              return importFn(absLayoutPath, importOpts);
+              return importFn(absLayoutPath, baseImportOpts);
             }) as Parameters<typeof registerLayoutLoader>[1]);
             registeredLayouts.add(layoutPath);
             console.log(`  🎨 Layout: ${layoutPath}`);
@@ -204,7 +228,7 @@ export async function registerManifestHandlers(
       // Use PageHandler if slotModule exists (filling.loader support)
       if (route.slotModule) {
         registerPageHandler(route.id, async () => {
-          const mod = (await importFn(componentPath, importOpts)) as Record<string, unknown>;
+          const mod = (await importFn(componentPath, importOptsForRoute(route))) as Record<string, unknown>;
           // Normalize the page module shape. Users write pages in two styles:
           //   (a) `export default function Page() {…}` + `export const filling = …`
           //   (b) `export default { component: …, filling: … }`
@@ -242,7 +266,7 @@ export async function registerManifestHandlers(
           `  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
       } else {
-        registerPageLoader(route.id, (() => importFn(componentPath, importOpts)) as Parameters<typeof registerPageLoader>[1]);
+        registerPageLoader(route.id, (() => importFn(componentPath, importOptsForRoute(route))) as Parameters<typeof registerPageLoader>[1]);
         console.log(
           `  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
@@ -252,7 +276,7 @@ export async function registerManifestHandlers(
 
   // Phase 6.3: register `app/not-found.tsx` if it exists. Global, one per
   // app — the server falls through to the built-in 404 if unregistered.
-  await registerAppNotFound(rootDir, importFn, importOpts);
+  await registerAppNotFound(rootDir, importFn, baseImportOpts);
 }
 
 /**
@@ -260,11 +284,11 @@ export async function registerManifestHandlers(
  * project root and register it as the app-level 404 handler. Silent
  * no-op if no file exists — the server's built-in 404 covers that case.
  */
-async function registerAppNotFound(
-  rootDir: string,
-  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>,
-  importOpts?: { changedFile?: string },
-): Promise<void> {
+async function registerAppNotFound(
+  rootDir: string,
+  importFn: RegisterHandlersOptions["importFn"],
+  importOpts?: { changedFile?: string },
+): Promise<void> {
   const candidates = [
     "app/not-found.tsx",
     "app/not-found.ts",

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

@@ -125,11 +125,14 @@ async function resolveAndWrapInlineClientHydration(
     };
   }
 
-  if (typeof type === "function" && isAsyncFunctionComponent(type)) {
-    const rendered = await (type as (props: Record<string, unknown>) => React.ReactNode | Promise<React.ReactNode>)(
+  if (typeof type === "function" && !isClassComponent(type)) {
+    const rendered = await renderFunctionComponentForInlineHydration(
+      type,
       element.props ?? {},
     );
-    return resolveAndWrapInlineClientHydration(rendered, target, counter);
+    if (rendered.ok) {
+      return resolveAndWrapInlineClientHydration(rendered.node, target, counter);
+    }
   }
 
   const props = element.props;
@@ -154,6 +157,42 @@ function isAsyncFunctionComponent(type: Function): boolean {
     (type as { constructor?: { name?: string } }).constructor?.name === "AsyncFunction";
 }
 
+function isClassComponent(type: Function): boolean {
+  return !!type.prototype?.isReactComponent;
+}
+
+async function renderFunctionComponentForInlineHydration(
+  type: Function,
+  props: Record<string, unknown>,
+): Promise<{ ok: true; node: React.ReactNode } | { ok: false }> {
+  const render = type as (props: Record<string, unknown>) => React.ReactNode | Promise<React.ReactNode>;
+  if (isAsyncFunctionComponent(type)) {
+    return { ok: true, node: await render(props) };
+  }
+
+  if (functionComponentLooksHookDependent(type)) {
+    return { ok: false };
+  }
+
+  try {
+    return { ok: true, node: await render(props) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function functionComponentLooksHookDependent(type: Function): boolean {
+  let source = "";
+  try {
+    source = Function.prototype.toString.call(type);
+  } catch {
+    return true;
+  }
+
+  return /\bReact\.use[A-Za-z0-9_$]*\s*\(/.test(source) ||
+    /\buse[A-Z][A-Za-z0-9_$]*\s*\(/.test(source);
+}
+
 function priorityToHydrate(priority: InlineClientHydrationTarget["priority"]): string {
   return priority === "immediate" ? "load" : priority;
 }
@@ -175,6 +214,7 @@ async function renderStreamingPageResponse(
     criticalData: options.loaderData as Record<string, unknown> | undefined,
     enableClientRouter: true,
     cssPath: options.cssPath,
+    islandPreWrapped: !!options.islandPreWrapped,
     transitions: options.transitions,
     prefetch: options.prefetch,
     spa: options.spa,

package/src/runtime/server.ts

@@ -1124,16 +1124,13 @@ async function resolveInlineClientHydrationTarget(
   rootDir: string,
   src: string,
 ): Promise<InlineClientHydrationTarget | undefined> {
-  if (!route.clientModule || !route.clientExportName || !src) {
+  if (!route.clientModule || !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;
+    const component = resolveInlineClientHydrationComponent(module, route);
 
     if (!component) return undefined;
 
@@ -1152,6 +1149,46 @@ async function resolveInlineClientHydrationTarget(
   }
 }
 
+function resolveInlineClientHydrationComponent(
+  module: Record<string, unknown>,
+  route: { id: string; clientModule?: string; clientExportName?: string },
+): unknown {
+  if (module.default) return module.default;
+
+  const candidates = [
+    route.clientExportName && route.clientExportName !== "default" ? route.clientExportName : undefined,
+    inferInlineClientExportNameFromPath(route.clientModule),
+    inferInlineClientExportNameFromRouteId(route.id),
+  ].filter((candidate, index, values): candidate is string =>
+    !!candidate && values.indexOf(candidate) === index
+  );
+
+  for (const candidate of candidates) {
+    if (module[candidate]) return module[candidate];
+  }
+
+  const runtimeExports = Object.keys(module).filter((name) => name !== "__esModule");
+  return runtimeExports.length === 1 ? module[runtimeExports[0]] : undefined;
+}
+
+function inferInlineClientExportNameFromPath(clientModulePath: string | undefined): string | undefined {
+  if (!clientModulePath) return undefined;
+  const basename = path.basename(clientModulePath).replace(/\.[cm]?[jt]sx?$/, "");
+  const withoutClientSuffix = basename.replace(/\.(client|island)$/, "");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(withoutClientSuffix)
+    ? withoutClientSuffix
+    : undefined;
+}
+
+function inferInlineClientExportNameFromRouteId(routeId: string): string | undefined {
+  const pascal = routeId
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(pascal) ? pascal : undefined;
+}
+
 const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
 
 // ========== Request Handler ==========

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(),