@mandujs/core 0.9.16 → 0.9.18

package/src/runtime/streaming-ssr.ts

@@ -0,0 +1,838 @@
+/**
+ * Mandu Streaming SSR
+ * React 18 renderToReadableStream 기반 점진적 HTML 스트리밍
+ *
+ * 특징:
+ * - TTFB 최소화 (Shell 즉시 전송)
+ * - Suspense 경계에서 fallback → 실제 컨텐츠 스트리밍
+ * - Critical/Deferred 데이터 분리
+ * - Island Architecture와 완벽 통합
+ */
+
+// Bun에서는 react-dom/server.browser에서 renderToReadableStream을 가져옴
+// Node.js 환경에서는 renderToPipeableStream 사용 필요
+import { renderToReadableStream } from "react-dom/server.browser";
+import type { ReactElement, ReactNode } from "react";
+import React, { Suspense } from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig, HydrationPriority } from "../spec/schema";
+import { serializeProps } from "../client/serialize";
+
+// ========== Types ==========
+
+/**
+ * Streaming SSR 에러 타입
+ */
+export interface StreamingError {
+  error: Error;
+  /** Shell 전송 전 에러인지 여부 */
+  isShellError: boolean;
+  /** 복구 가능 여부 */
+  recoverable: boolean;
+  /** 타임스탬프 */
+  timestamp: number;
+}
+
+/**
+ * Streaming SSR 메트릭
+ */
+export interface StreamingMetrics {
+  /** Shell ready까지 걸린 시간 (ms) */
+  shellReadyTime: number;
+  /** All ready까지 걸린 시간 (ms) */
+  allReadyTime: number;
+  /** Deferred chunk 개수 */
+  deferredChunkCount: number;
+  /** 에러 발생 여부 */
+  hasError: boolean;
+  /** 시작 시간 */
+  startTime: number;
+}
+
+export interface StreamingSSROptions {
+  /** 페이지 타이틀 */
+  title?: string;
+  /** HTML lang 속성 */
+  lang?: string;
+  /** 라우트 ID */
+  routeId?: string;
+  /** 라우트 패턴 */
+  routePattern?: string;
+  /** Critical 데이터 (Shell과 함께 즉시 전송) - JSON-serializable object만 허용 */
+  criticalData?: Record<string, unknown>;
+  /** Deferred 데이터 (Suspense 후 스트리밍) */
+  deferredData?: Record<string, unknown>;
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** 추가 head 태그 */
+  headTags?: string;
+  /** 개발 모드 여부 */
+  isDev?: boolean;
+  /** HMR 포트 */
+  hmrPort?: number;
+  /** Client-side Router 활성화 */
+  enableClientRouter?: boolean;
+  /** Streaming 타임아웃 (ms) */
+  streamTimeout?: number;
+  /** Shell 렌더링 후 콜백 */
+  onShellReady?: () => void;
+  /** 모든 컨텐츠 렌더링 후 콜백 */
+  onAllReady?: () => void;
+  /** Shell 전 에러 콜백 (500 반환 가능) */
+  onShellError?: (error: StreamingError) => void;
+  /** 스트리밍 중 에러 콜백 (이미 응답 시작됨 - fallback UI 삽입) */
+  onStreamError?: (error: StreamingError) => void;
+  /** 에러 콜백 (deprecated - onShellError/onStreamError 사용 권장) */
+  onError?: (error: Error) => void;
+  /** 메트릭 콜백 (observability) */
+  onMetrics?: (metrics: StreamingMetrics) => void;
+}
+
+export interface StreamingLoaderResult<T = unknown> {
+  /** 즉시 로드할 Critical 데이터 */
+  critical?: T;
+  /** 지연 로드할 Deferred 데이터 (Promise) */
+  deferred?: Promise<T>;
+}
+
+// ========== Serialization Guards ==========
+
+/**
+ * 값이 JSON-serializable인지 검증
+ * Date, Map, Set, BigInt 등은 serializeProps에서 처리되지만
+ * 함수, Symbol, undefined는 문제가 됨
+ */
+function isJSONSerializable(value: unknown, path: string = "root", isDev: boolean = false): { valid: boolean; issues: string[] } {
+  const issues: string[] = [];
+
+  function check(val: unknown, currentPath: string): void {
+    if (val === undefined) {
+      issues.push(`${currentPath}: undefined는 JSON으로 직렬화할 수 없습니다`);
+      return;
+    }
+
+    if (val === null) return;
+
+    const type = typeof val;
+
+    if (type === "function") {
+      issues.push(`${currentPath}: function은 JSON으로 직렬화할 수 없습니다`);
+      return;
+    }
+
+    if (type === "symbol") {
+      issues.push(`${currentPath}: symbol은 JSON으로 직렬화할 수 없습니다`);
+      return;
+    }
+
+    if (type === "bigint") {
+      // serializeProps에서 처리됨 - 경고만
+      if (isDev) {
+        console.warn(`[Mandu Streaming] ${currentPath}: BigInt가 감지됨 - 문자열로 변환됩니다`);
+      }
+      return;
+    }
+
+    if (val instanceof Date || val instanceof Map || val instanceof Set || val instanceof URL || val instanceof RegExp) {
+      // serializeProps에서 처리됨
+      return;
+    }
+
+    if (Array.isArray(val)) {
+      val.forEach((item, index) => check(item, `${currentPath}[${index}]`));
+      return;
+    }
+
+    if (type === "object") {
+      for (const [key, v] of Object.entries(val as Record<string, unknown>)) {
+        check(v, `${currentPath}.${key}`);
+      }
+      return;
+    }
+
+    // string, number, boolean은 OK
+  }
+
+  check(value, path);
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}
+
+/**
+ * criticalData 검증 및 경고
+ * 개발 모드에서는 throw, 프로덕션에서는 경고만
+ */
+function validateCriticalData(data: Record<string, unknown> | undefined, isDev: boolean): void {
+  if (!data) return;
+
+  const result = isJSONSerializable(data, "criticalData", isDev);
+
+  if (!result.valid) {
+    const message = `[Mandu Streaming] criticalData 직렬화 문제:\n${result.issues.join("\n")}`;
+
+    if (isDev) {
+      throw new Error(message);
+    } else {
+      console.error(message);
+    }
+  }
+}
+
+// ========== Streaming Warnings ==========
+
+/**
+ * 프록시/버퍼링 관련 경고 (개발 모드)
+ */
+function warnStreamingCaveats(isDev: boolean): void {
+  if (!isDev) return;
+
+  console.log(`[Mandu Streaming] 💡 Streaming SSR 주의사항:
+  - nginx/cloudflare 등 reverse proxy 사용 시 버퍼링 비활성화 필요
+    (nginx: proxy_buffering off; X-Accel-Buffering: no)
+  - compression 미들웨어가 chunk를 모으면 스트리밍 이점 사라짐
+  - Transfer-Encoding: chunked 헤더가 유지되어야 함`);
+}
+
+// ========== Error HTML Generation ==========
+
+/**
+ * 스트리밍 중 에러 시 삽입할 에러 스크립트 생성
+ * Shell 이후 에러는 이 방식으로 클라이언트에 전달
+ */
+function generateErrorScript(error: Error, routeId: string): string {
+  const safeMessage = error.message
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/"/g, "\\u0022");
+
+  return `<script>
+(function() {
+  window.__MANDU_STREAMING_ERROR__ = {
+    routeId: "${routeId}",
+    message: "${safeMessage}",
+    timestamp: ${Date.now()}
+  };
+  console.error("[Mandu Streaming] 렌더링 중 에러:", "${safeMessage}");
+  window.dispatchEvent(new CustomEvent('mandu:streaming-error', {
+    detail: window.__MANDU_STREAMING_ERROR__
+  }));
+})();
+</script>`;
+}
+
+// ========== Suspense Wrappers ==========
+
+/**
+ * Island를 Suspense로 감싸는 래퍼
+ * Streaming SSR에서 Island별 점진적 렌더링 지원
+ */
+export function SuspenseIsland({
+  children,
+  fallback,
+  routeId,
+  priority = "visible",
+  bundleSrc,
+}: {
+  children: ReactNode;
+  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,
+    "data-mandu-loading": "true",
+    style: { minHeight: "50px" },
+  }, React.createElement("div", {
+    className: "mandu-loading-skeleton",
+    style: {
+      background: "linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)",
+      backgroundSize: "200% 100%",
+      animation: "mandu-shimmer 1.5s infinite",
+      height: "100%",
+      minHeight: "50px",
+      borderRadius: "4px",
+    },
+  }));
+
+  return React.createElement(
+    Suspense,
+    { fallback: fallback || defaultFallback },
+    React.createElement("div", {
+      "data-mandu-island": routeId,
+      "data-mandu-priority": priority,
+      "data-mandu-src": bundleSrc,
+    }, children)
+  );
+}
+
+/**
+ * Deferred 데이터를 위한 Suspense 컴포넌트
+ * 데이터가 준비되면 children 렌더링
+ */
+export function DeferredData<T>({
+  promise,
+  children,
+  fallback,
+}: {
+  promise: Promise<T>;
+  children: (data: T) => ReactNode;
+  fallback?: ReactNode;
+}): ReactElement {
+  // React 18 use() 훅 대신 Suspense + throw promise 패턴 사용
+  const AsyncComponent = React.lazy(async () => {
+    const data = await promise;
+    return {
+      default: () => React.createElement(React.Fragment, null, children(data)),
+    };
+  });
+
+  return React.createElement(
+    Suspense,
+    { fallback: fallback || React.createElement("span", null, "Loading...") },
+    React.createElement(AsyncComponent, null)
+  );
+}
+
+// ========== HTML Generation ==========
+
+/**
+ * Streaming용 HTML Shell 생성 (<!DOCTYPE> ~ <div id="root">)
+ */
+function generateHTMLShell(options: StreamingSSROptions): string {
+  const {
+    title = "Mandu App",
+    lang = "ko",
+    headTags = "",
+    bundleManifest,
+  } = options;
+
+  // Import map (module scripts 전에 위치해야 함)
+  let importMapScript = "";
+  if (bundleManifest?.importMap && Object.keys(bundleManifest.importMap.imports).length > 0) {
+    const importMapJson = JSON.stringify(bundleManifest.importMap, null, 2);
+    importMapScript = `<script type="importmap">${importMapJson}</script>`;
+  }
+
+  // Loading skeleton 애니메이션 스타일
+  const loadingStyles = `
+<style>
+@keyframes mandu-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+.mandu-loading-skeleton {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: mandu-shimmer 1.5s infinite;
+}
+.mandu-stream-pending {
+  opacity: 0;
+  transition: opacity 0.3s ease-in;
+}
+.mandu-stream-ready {
+  opacity: 1;
+}
+</style>`;
+
+  return `<!DOCTYPE html>
+<html lang="${lang}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  ${loadingStyles}
+  ${headTags}
+  ${importMapScript}
+</head>
+<body>
+  <div id="root">`;
+}
+
+/**
+ * Streaming용 HTML Tail 생성 (</div id="root"> ~ </html>)
+ */
+function generateHTMLTail(options: StreamingSSROptions): string {
+  const {
+    routeId,
+    routePattern,
+    criticalData,
+    deferredData,
+    bundleManifest,
+    isDev = false,
+    hmrPort,
+    enableClientRouter = false,
+    hydration,
+  } = options;
+
+  const scripts: string[] = [];
+
+  // 1. Critical 데이터 스크립트 (즉시 사용 가능)
+  if (criticalData && routeId) {
+    const wrappedData = {
+      [routeId]: {
+        serverData: criticalData,
+        timestamp: Date.now(),
+        streaming: true,
+      },
+    };
+    const json = serializeProps(wrappedData)
+      .replace(/</g, "\\u003c")
+      .replace(/>/g, "\\u003e")
+      .replace(/&/g, "\\u0026");
+    scripts.push(`<script id="__MANDU_DATA__" type="application/json">${json}</script>`);
+    scripts.push(`<script>window.__MANDU_DATA_RAW__ = document.getElementById('__MANDU_DATA__').textContent;</script>`);
+  }
+
+  // 2. 라우트 정보 스크립트
+  if (enableClientRouter && routeId) {
+    const routeInfo = {
+      id: routeId,
+      pattern: routePattern || "",
+      params: {},
+      streaming: true,
+    };
+    const json = JSON.stringify(routeInfo)
+      .replace(/</g, "\\u003c")
+      .replace(/>/g, "\\u003e");
+    scripts.push(`<script>window.__MANDU_ROUTE__ = ${json};</script>`);
+  }
+
+  // 3. Streaming 완료 마커 (클라이언트에서 감지용)
+  scripts.push(`<script>window.__MANDU_STREAMING_SHELL_READY__ = true;</script>`);
+
+  // 4. Island modulepreload
+  if (bundleManifest && routeId) {
+    const bundle = bundleManifest.bundles[routeId];
+    if (bundle) {
+      scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
+    }
+  }
+
+  // 5. Runtime 로드
+  if (bundleManifest?.shared.runtime) {
+    scripts.push(`<script type="module" src="${bundleManifest.shared.runtime}"></script>`);
+  }
+
+  // 6. Router 스크립트
+  if (enableClientRouter && bundleManifest?.shared?.router) {
+    scripts.push(`<script type="module" src="${bundleManifest.shared.router}"></script>`);
+  }
+
+  // 7. HMR 스크립트 (개발 모드)
+  if (isDev && hmrPort) {
+    scripts.push(generateHMRScript(hmrPort));
+  }
+
+  return `</div>
+  ${scripts.join("\n  ")}
+</body>
+</html>`;
+}
+
+/**
+ * Deferred 데이터 인라인 스크립트 생성
+ * Streaming 중에 데이터 도착 시 DOM에 주입
+ */
+function generateDeferredDataScript(routeId: string, key: string, data: unknown): string {
+  const json = serializeProps({ [key]: data })
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+
+  return `<script>
+(function() {
+  window.__MANDU_DEFERRED__ = window.__MANDU_DEFERRED__ || {};
+  window.__MANDU_DEFERRED__["${routeId}"] = window.__MANDU_DEFERRED__["${routeId}"] || {};
+  Object.assign(window.__MANDU_DEFERRED__["${routeId}"], ${json});
+  window.dispatchEvent(new CustomEvent('mandu:deferred-data', { detail: { routeId: "${routeId}", key: "${key}" } }));
+})();
+</script>`;
+}
+
+/**
+ * HMR 스크립트 생성
+ */
+function generateHMRScript(port: number): string {
+  const hmrPort = port + 1;
+  return `<script>
+(function() {
+  var ws = null;
+  var reconnectAttempts = 0;
+  var maxReconnectAttempts = 10;
+
+  function connect() {
+    try {
+      ws = new WebSocket('ws://localhost:${hmrPort}');
+      ws.onopen = function() {
+        console.log('[Mandu HMR] Connected');
+        reconnectAttempts = 0;
+      };
+      ws.onmessage = function(e) {
+        try {
+          var msg = JSON.parse(e.data);
+          if (msg.type === 'reload' || msg.type === 'island-update') {
+            console.log('[Mandu HMR] Reloading...');
+            location.reload();
+          }
+        } catch(err) {}
+      };
+      ws.onclose = function() {
+        if (reconnectAttempts < maxReconnectAttempts) {
+          reconnectAttempts++;
+          setTimeout(connect, 1000 * reconnectAttempts);
+        }
+      };
+    } catch(err) {
+      setTimeout(connect, 1000);
+    }
+  }
+  connect();
+})();
+</script>`;
+}
+
+// ========== Main Streaming Functions ==========
+
+/**
+ * React 컴포넌트를 ReadableStream으로 렌더링
+ * Bun/Web Streams API 기반
+ *
+ * 에러 처리:
+ * - Shell 전 에러: onShellError 호출 → 500 응답 가능
+ * - Shell 후 에러: onStreamError 호출 → 에러 스크립트 삽입
+ */
+export async function renderToStream(
+  element: ReactElement,
+  options: StreamingSSROptions = {}
+): Promise<ReadableStream<Uint8Array>> {
+  const {
+    streamTimeout = 10000,
+    onShellReady,
+    onAllReady,
+    onShellError,
+    onStreamError,
+    onError,
+    onMetrics,
+    isDev = false,
+    routeId = "unknown",
+    criticalData,
+  } = options;
+
+  // 메트릭 수집
+  const metrics: StreamingMetrics = {
+    shellReadyTime: 0,
+    allReadyTime: 0,
+    deferredChunkCount: 0,
+    hasError: false,
+    startTime: Date.now(),
+  };
+
+  // criticalData 직렬화 검증
+  validateCriticalData(criticalData, isDev);
+
+  // 스트리밍 주의사항 경고 (첫 요청 시 1회만)
+  if (isDev && !(globalThis as any).__MANDU_STREAMING_WARNED__) {
+    warnStreamingCaveats(isDev);
+    (globalThis as any).__MANDU_STREAMING_WARNED__ = true;
+  }
+
+  const encoder = new TextEncoder();
+  const htmlShell = generateHTMLShell(options);
+  const htmlTail = generateHTMLTail(options);
+
+  let shellSent = false;
+  let hasShellError = false;
+
+  // React renderToReadableStream 호출
+  let reactStream: ReadableStream<Uint8Array>;
+  try {
+    reactStream = await renderToReadableStream(element, {
+      onError: (error: Error) => {
+        metrics.hasError = true;
+        const streamingError: StreamingError = {
+          error,
+          isShellError: !shellSent,
+          recoverable: shellSent, // Shell 후면 복구 가능 (에러 스크립트 삽입)
+          timestamp: Date.now(),
+        };
+
+        console.error("[Mandu Streaming] React render error:", error);
+
+        if (!shellSent) {
+          hasShellError = true;
+          onShellError?.(streamingError);
+        } else {
+          onStreamError?.(streamingError);
+        }
+
+        // deprecated 콜백 호환
+        onError?.(error);
+      },
+    });
+  } catch (error) {
+    // renderToReadableStream 자체 실패 (Shell 전 에러)
+    metrics.hasError = true;
+    const err = error instanceof Error ? error : new Error(String(error));
+    const streamingError: StreamingError = {
+      error: err,
+      isShellError: true,
+      recoverable: false,
+      timestamp: Date.now(),
+    };
+
+    onShellError?.(streamingError);
+    onError?.(err);
+
+    // 에러 응답을 위한 빈 스트림 반환
+    throw err;
+  }
+
+  // Shell 준비 완료 대기 (타임아웃 포함)
+  const timeoutPromise = new Promise<void>((_, reject) =>
+    setTimeout(() => reject(new Error("Shell render timeout")), streamTimeout)
+  );
+
+  try {
+    await Promise.race([reactStream.allReady, timeoutPromise]);
+  } catch {
+    // Timeout이나 에러 시에도 계속 진행 (이미 일부 렌더링된 경우)
+    if (isDev) {
+      console.warn("[Mandu Streaming] Shell render timed out or errored, continuing with partial content");
+    }
+  }
+
+  // Custom stream으로 래핑 (Shell + React Content + Tail)
+  let tailSent = false;
+  const reader = reactStream.getReader();
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      // Shell 전 에러면 에러 HTML 반환
+      if (hasShellError) {
+        const errorHtml = `<!DOCTYPE html>
+<html><head><title>Error</title></head>
+<body><h1>500 Server Error</h1><p>렌더링 중 오류가 발생했습니다.</p></body></html>`;
+        controller.enqueue(encoder.encode(errorHtml));
+        controller.close();
+        return;
+      }
+
+      // 1. HTML Shell 전송 (즉시 TTFB)
+      controller.enqueue(encoder.encode(htmlShell));
+      shellSent = true;
+      metrics.shellReadyTime = Date.now() - metrics.startTime;
+      onShellReady?.();
+    },
+
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+
+        if (done) {
+          if (!tailSent) {
+            // 2. HTML Tail 전송 (스크립트, 데이터)
+            controller.enqueue(encoder.encode(htmlTail));
+            tailSent = true;
+            metrics.allReadyTime = Date.now() - metrics.startTime;
+            onAllReady?.();
+            onMetrics?.(metrics);
+          }
+          controller.close();
+          return;
+        }
+
+        // 3. React 컨텐츠 스트리밍
+        controller.enqueue(value);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        metrics.hasError = true;
+
+        console.error("[Mandu Streaming] Pull error:", err);
+
+        // 스트리밍 중 에러 - 에러 스크립트 삽입
+        const streamingError: StreamingError = {
+          error: err,
+          isShellError: false,
+          recoverable: true,
+          timestamp: Date.now(),
+        };
+        onStreamError?.(streamingError);
+
+        // 에러 스크립트 삽입
+        controller.enqueue(encoder.encode(generateErrorScript(err, routeId)));
+
+        if (!tailSent) {
+          controller.enqueue(encoder.encode(htmlTail));
+          tailSent = true;
+          metrics.allReadyTime = Date.now() - metrics.startTime;
+          onMetrics?.(metrics);
+        }
+        controller.close();
+      }
+    },
+
+    cancel() {
+      reader.cancel();
+    },
+  });
+}
+
+/**
+ * Streaming SSR Response 생성
+ *
+ * 헤더 설명:
+ * - Transfer-Encoding: chunked - 스트리밍 필수
+ * - X-Accel-Buffering: no - nginx 버퍼링 비활성화
+ * - Cache-Control: no-transform - 중간 프록시 변환 방지
+ */
+export async function renderStreamingResponse(
+  element: ReactElement,
+  options: StreamingSSROptions = {}
+): Promise<Response> {
+  try {
+    const stream = await renderToStream(element, options);
+
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Transfer-Encoding": "chunked",
+        // Streaming 관련 헤더
+        "X-Content-Type-Options": "nosniff",
+        // nginx 버퍼링 비활성화 힌트
+        "X-Accel-Buffering": "no",
+        // 캐시 및 변환 방지 (Streaming은 동적)
+        "Cache-Control": "no-cache, no-store, must-revalidate, no-transform",
+        // Cloudflare 등 CDN 힌트
+        "CDN-Cache-Control": "no-store",
+      },
+    });
+  } catch (error) {
+    // Shell 전 에러 시 500 응답
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error("[Mandu Streaming] Response generation failed:", err);
+
+    return new Response(
+      `<!DOCTYPE html><html><head><title>500 Error</title></head>
+<body><h1>500 Server Error</h1><p>${err.message}</p></body></html>`,
+      {
+        status: 500,
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+        },
+      }
+    );
+  }
+}
+
+/**
+ * Deferred 데이터와 함께 Streaming SSR 렌더링
+ * Critical 데이터는 즉시, Deferred 데이터는 준비되면 스트리밍
+ */
+export async function renderWithDeferredData(
+  element: ReactElement,
+  options: StreamingSSROptions & {
+    deferredPromises?: Record<string, Promise<unknown>>;
+  }
+): Promise<Response> {
+  const { deferredPromises = {}, routeId = "default", ...restOptions } = options;
+
+  // Deferred 데이터 스크립트를 추가할 TransformStream
+  const encoder = new TextEncoder();
+  const deferredScripts: string[] = [];
+
+  // Deferred promises 처리
+  const deferredEntries = Object.entries(deferredPromises);
+  if (deferredEntries.length > 0) {
+    // 병렬로 모든 deferred 데이터 대기
+    Promise.all(
+      deferredEntries.map(async ([key, promise]) => {
+        try {
+          const data = await promise;
+          deferredScripts.push(generateDeferredDataScript(routeId, key, data));
+        } catch (error) {
+          console.error(`[Mandu Streaming] Deferred data error for ${key}:`, error);
+        }
+      })
+    );
+  }
+
+  // 기본 스트림 생성
+  const baseStream = await renderToStream(element, { ...restOptions, routeId });
+
+  // Deferred 스크립트 주입을 위한 Transform
+  const transformStream = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+    },
+    flush(controller) {
+      // 모든 deferred 스크립트 추가
+      for (const script of deferredScripts) {
+        controller.enqueue(encoder.encode(script));
+      }
+    },
+  });
+
+  const finalStream = baseStream.pipeThrough(transformStream);
+
+  return new Response(finalStream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Transfer-Encoding": "chunked",
+      "X-Content-Type-Options": "nosniff",
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+    },
+  });
+}
+
+// ========== Loader Helpers ==========
+
+/**
+ * Streaming Loader 헬퍼
+ * Critical과 Deferred 데이터를 분리하여 반환
+ *
+ * @example
+ * ```typescript
+ * export const loader = createStreamingLoader(async (ctx) => {
+ *   return {
+ *     critical: await getEssentialData(ctx),
+ *     deferred: fetchOptionalData(ctx), // Promise 그대로 전달
+ *   };
+ * });
+ * ```
+ */
+export function createStreamingLoader<TCritical, TDeferred>(
+  loaderFn: (ctx: unknown) => Promise<StreamingLoaderResult<{ critical: TCritical; deferred: TDeferred }>>
+) {
+  return async (ctx: unknown) => {
+    const result = await loaderFn(ctx);
+    return {
+      critical: result.critical,
+      deferred: result.deferred,
+    };
+  };
+}
+
+/**
+ * Deferred 데이터 프라미스 래퍼
+ * Streaming 중 데이터 준비되면 클라이언트로 전송
+ */
+export function defer<T>(promise: Promise<T>): Promise<T> {
+  return promise;
+}
+
+// ========== Exports ==========
+
+export {
+  generateHTMLShell,
+  generateHTMLTail,
+  generateDeferredDataScript,
+};