@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/runtime/streaming-ssr.ts

@@ -13,7 +13,11 @@ import { getRenderToReadableStream } from "./react-renderer";
 import type { ReactElement, ReactNode } from "react";
 import React, { Suspense } from "react";
 import type { BundleManifest } from "../bundler/types";
-import { isSafeManduUrl } from "../bundler/manifest-schema";
+import { isSafePublishedManduUrl } from "../bundler/manifest-schema";
+import {
+  scopeBundleManifestToGeneration,
+  scopeClientAssetUrl,
+} from "../bundler/generation";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { serializeProps } from "../client/serialize";
 import type { Metadata, MetadataItem } from "../seo/types";
@@ -23,13 +27,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/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";
+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
@@ -114,12 +118,12 @@ export interface StreamingSSROptions {
   // Note: deferredData는 renderWithDeferredData의 deferredPromises로 대체됨
   /** Hydration 설정 */
   hydration?: HydrationConfig;
-  /** 번들 매니페스트 */
-  bundleManifest?: BundleManifest;
-  /** React element already contains its own island wrapper. */
-  islandPreWrapped?: boolean;
-  /** 추가 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] 순서로 병합
@@ -229,12 +233,18 @@ function shouldInjectDevtoolsStreaming(
  * Emits `<script type="module" src="/.mandu/client/_devtools.js?v=BUILD">`
  * with a `buildTime`-keyed cache-bust (or `Date.now()` fallback).
  */
-function generateStreamingDevtoolsScript(manifest: BundleManifest | undefined): string {
-  const cacheBust = manifest?.buildTime
-    ? `?v=${encodeURIComponent(manifest.buildTime)}`
-    : `?t=${Date.now()}`;
-  return `<script type="module" src="/.mandu/client/_devtools.js${cacheBust}"></script>`;
-}
+function generateStreamingDevtoolsScript(manifest: BundleManifest | undefined): string {
+  const src = scopeClientAssetUrl(
+    "/.mandu/client/_devtools.js",
+    manifest?.generationId,
+  );
+  const key = manifest?.buildTime ? "v" : "t";
+  const value = manifest?.buildTime
+    ? encodeURIComponent(manifest.buildTime)
+    : Date.now();
+  const cacheBust = `${src.includes("?") ? "&" : "?"}${key}=${value}`;
+  return `<script type="module" src="${src}${cacheBust}"></script>`;
+}
 
 /** @internal — surface for the shared test suite in tests/runtime/devtools-inject.test.ts. */
 export const _testOnly_shouldInjectDevtoolsStreaming = shouldInjectDevtoolsStreaming;
@@ -396,7 +406,7 @@ function generateErrorScript(error: Error, routeId: string): string {
  * Island를 Suspense로 감싸는 래퍼
  * Streaming SSR에서 Island별 점진적 렌더링 지원
  */
-export function SuspenseIsland({
+export function SuspenseIsland({
   children,
   fallback,
   routeId,
@@ -407,16 +417,16 @@ export function SuspenseIsland({
   fallback?: ReactNode;
   routeId: string;
   priority?: HydrationPriority;
-  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" },
+  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: {
@@ -432,19 +442,19 @@ export function SuspenseIsland({
   return React.createElement(
     Suspense,
     { fallback: fallback || 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,
-      style: { display: "contents" },
-    }, children)
-  );
-}
-
-function priorityToHydrateStrategy(priority: HydrationPriority): string {
-  return priority === "immediate" ? "load" : priority;
-}
+    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 컴포넌트
@@ -556,10 +566,10 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     isDev = false,
     transitions = true,
     prefetch = true,
-    spa = true,
-    layoutChain,
-    islandPreWrapped = false,
-  } = 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,17 +637,19 @@ function generateHTMLShell(options: StreamingSSROptions): string {
 }
 </style>`;
 
-  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";
-    const hydrate = priorityToHydrateStrategy(priority);
-    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">`;
-    }
-  }
+  let islandOpenTag = "";
+  const hasRouteBundle = !!(needsHydration && bundleManifest.bundles[routeId]?.js);
+  if (needsHydration) {
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js
+      ? `${bundle.js}${bundle.js.includes("?") ? "&" : "?"}t=${Date.now()}`
+      : "";
+    const priority = hydration.priority || "visible";
+    const hydrate = priorityToHydrateStrategy(priority);
+    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">`;
+    }
+  }
 
   // Phase 7.1 R2 Agent D: Fast Refresh preamble. Must land in <head>
   // BEFORE any island script evaluates — the stubs it installs for
@@ -657,7 +669,13 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     // (protocol, traversal, non-/.mandu paths, >2KB) — fail closed so
     // an attacker-controlled <script src> cannot slip in via a
     // manipulated .mandu/manifest.json.
-    if (fr && fr.glue && fr.runtime && isSafeManduUrl(fr.glue) && isSafeManduUrl(fr.runtime)) {
+    if (
+      fr &&
+      fr.glue &&
+      fr.runtime &&
+      isSafePublishedManduUrl(fr.glue) &&
+      isSafePublishedManduUrl(fr.runtime)
+    ) {
       fastRefreshPreamble = generateFastRefreshPreamble(fr.glue, fr.runtime);
       const resolvedNonce = resolveStreamingCspNonce(options.cspNonce);
       if (resolvedNonce) {
@@ -702,11 +720,11 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     bundleManifest,
     isDev = false,
     hmrPort,
-    enableClientRouter = false,
-    hydration,
-    devtools,
-    islandPreWrapped = false,
-  } = options;
+    enableClientRouter = false,
+    hydration,
+    devtools,
+    islandPreWrapped = false,
+  } = options;
 
   const scripts: string[] = [];
 
@@ -716,7 +734,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   // 1~8: hydration이 필요한 경우에만 클라이언트 JS 관련 스크립트 삽입
   if (needsHydration) {
     // 1. Critical 데이터 스크립트 (즉시 사용 가능)
-    if (criticalData !== undefined && routeId) {
+    if (criticalData !== undefined && routeId) {
       const wrappedData = {
         [routeId]: {
           serverData: criticalData,
@@ -763,40 +781,40 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
       scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.runtime)}">`);
     }
 
-    // 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)) {
-        const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-      }
-    }
-
-    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>`);
+    // 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)) {
+        const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+      }
+    }
+
+    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)
@@ -824,9 +842,9 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   if (isDev && shouldInjectDevtoolsStreaming(devtools, bundleManifest)) {
     scripts.push(generateStreamingDevtoolsScript(bundleManifest));
   }
-
-  // Island wrapper 닫기 (hydration이 필요한 경우)
-  const islandCloseTag = needsHydration && !islandPreWrapped && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
+
+  // Island wrapper 닫기 (hydration이 필요한 경우)
+  const islandCloseTag = needsHydration && !islandPreWrapped && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
 
   return `${islandCloseTag}</div>
   ${scripts.join("\n  ")}`;
@@ -992,9 +1010,19 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
               }
             }
             if (!updated) location.reload();
-          } else if (msg.type === 'error') {
-            console.error('[Mandu HMR] Build error:', msg.data && msg.data.message);
-          }
+          } else if (msg.type === 'error') {
+            var errorData = msg.data || {};
+            console.error('[Mandu HMR] Build error:', errorData.message);
+            window.dispatchEvent(new CustomEvent('__MANDU_ERROR__', { detail: {
+              name: errorData.name || 'BuildError',
+              message: errorData.message || 'Build failed',
+              stack: errorData.stack || '',
+              kind: 'manual',
+              timestamp: errorData.timestamp || Date.now(),
+              routeId: errorData.routeId,
+              url: window.location.pathname + window.location.search
+            }}));
+          }
         } catch(err) {}
       };
       ws.onclose = function() { scheduleReconnect(); };
@@ -1019,12 +1047,16 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
  * - Shell 전 에러는 throw → Response 레이어에서 500 처리
  * - Shell 후 에러는 에러 스크립트 삽입
  */
-export async function renderToStream(
-  element: ReactElement,
-  options: StreamingSSROptions = {}
-): Promise<ReadableStream<Uint8Array>> {
-  mark("ssr:render");
-  const {
+export async function renderToStream(
+  element: ReactElement,
+  options: StreamingSSROptions = {}
+): Promise<ReadableStream<Uint8Array>> {
+  mark("ssr:render");
+  const scopedBundleManifest = scopeBundleManifestToGeneration(options.bundleManifest);
+  const renderOptions = scopedBundleManifest === options.bundleManifest
+    ? options
+    : { ...options, bundleManifest: scopedBundleManifest };
+  const {
     onShellReady,
     onAllReady,
     onShellError,
@@ -1035,7 +1067,7 @@ export async function renderToStream(
     routeId = "unknown",
     criticalData,
     streamTimeout,
-  } = options;
+  } = renderOptions;
 
   // 메트릭 수집
   const metrics: StreamingMetrics = {
@@ -1054,17 +1086,24 @@ export async function renderToStream(
     warnStreamingCaveats(isDev);
     streamingWarnings.markWarned();
   }
-
-  const encoder = new TextEncoder();
+
+  const encoder = new TextEncoder();
   const collectedHeadTags = renderWithManduClientBoundaryManifest(
-    options.routeId,
-    options.bundleManifest,
+    renderOptions.routeId,
+    renderOptions.bundleManifest,
     () => collectStreamingHeadTags(element),
   );
-  const resolvedOptions = collectedHeadTags
-    ? { ...options, headTags: [options.headTags, collectedHeadTags].filter(Boolean).join("\n") }
-    : options;
-  const htmlShell = generateHTMLShell(resolvedOptions);
+  const resolvedOptions = collectedHeadTags
+    ? {
+        ...renderOptions,
+        headTags: [renderOptions.headTags, collectedHeadTags].filter(Boolean).join("\n"),
+      }
+    : renderOptions;
+  const htmlShell = generateHTMLShell(resolvedOptions);
+  const resolvedNonce = STREAMING_OPTIONS_TO_NONCE.get(resolvedOptions as object);
+  if (resolvedNonce && resolvedOptions !== options) {
+    STREAMING_OPTIONS_TO_NONCE.set(options as object, resolvedNonce);
+  }
 
   // Reset SSR head before real render so streaming components push fresh tags
   try {
@@ -1102,53 +1141,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 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에서 이미 처리됨
-    });
-  });
+  // 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;
@@ -1157,12 +1196,12 @@ export async function renderToStream(
     ? metrics.startTime + streamTimeout
     : null;
 
-  async function readWithTimeout(): Promise<ReadableStreamReadResult<Uint8Array> | null> {
-    if (!deadline) {
-      return renderBoundaryScope(() =>
-        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) {
@@ -1174,12 +1213,12 @@ export async function renderToStream(
       timeoutId = setTimeout(() => resolve({ kind: "timeout" }), remaining);
     });
 
-    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 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]);