@mandujs/core 0.19.0 → 0.20.0

package/src/runtime/ssr.ts

@@ -48,6 +48,8 @@ export interface SSROptions {
   routePattern?: string;
   /** CSS 파일 경로 (자동 주입, 기본: /.mandu/client/globals.css) */
   cssPath?: string | false;
+  /** Island 래핑이 이미 React 엘리먼트 레벨에서 완료됨 (중복 래핑 방지) */
+  islandPreWrapped?: boolean;
 }
 
 let projectRenderToString: ((element: ReactElement) => string) | null | undefined;
@@ -137,9 +139,23 @@ function generateHydrationScripts(
   }
 
   // Island 번들 modulepreload (성능 최적화 - prefetch only)
-  const bundle = manifest.bundles[routeId];
-  if (bundle) {
-    scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundle.js)}">`);
+  // Per-island bundles take precedence when available
+  const routeIslands = manifest.islands
+    ? Object.values(manifest.islands).filter((ib) => ib.route === routeId)
+    : [];
+
+  if (routeIslands.length > 0) {
+    for (const ib of routeIslands) {
+      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  } else {
+    // Fallback: route-level bundle (backward compat)
+    const bundle = manifest.bundles[routeId];
+    if (bundle) {
+      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
   }
 
   // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
@@ -160,8 +176,9 @@ export function wrapWithIsland(
   priority: HydrationPriority = "visible",
   bundleSrc?: string
 ): string {
-  const srcAttr = bundleSrc ? ` data-mandu-src="${escapeHtmlAttr(bundleSrc)}"` : "";
-  return `<div data-mandu-island="${escapeHtmlAttr(routeId)}"${srcAttr} data-mandu-priority="${escapeHtmlAttr(priority)}">${content}</div>`;
+  const cacheBustedSrc = bundleSrc ? `${bundleSrc}?t=${Date.now()}` : undefined;
+  const srcAttr = cacheBustedSrc ? ` data-mandu-src="${escapeHtmlAttr(cacheBustedSrc)}"` : "";
+  return `<div data-mandu-island="${escapeHtmlAttr(routeId)}"${srcAttr} data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">${content}</div>`;
 }
 
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
@@ -179,6 +196,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     enableClientRouter = false,
     routePattern,
     cssPath,
+    islandPreWrapped,
   } = options;
 
   // CSS 링크 태그 생성
@@ -188,51 +206,71 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 
+  // useHead/useSeoMeta SSR 수집
+  let collectedHeadTags = "";
+  let headReset: (() => void) | undefined;
+  let headGet: (() => string) | undefined;
+  try {
+    const mod = require("../client/use-head");
+    headReset = mod.resetSSRHead;
+    headGet = mod.getSSRHeadTags;
+    headReset?.();
+  } catch { /* client 모듈 로드 실패 시 무시 */ }
+
   const renderToString = getRenderToString();
   let content = renderToString(element);
 
+  // 렌더링 중 수집된 head 태그
+  collectedHeadTags = headGet?.() ?? "";
+
   // Island 래퍼 적용 (hydration 필요 시)
+  // islandPreWrapped가 true이면 React 엘리먼트 레벨에서 이미 래핑됨 → HTML 래핑 건너뜀
   const needsHydration =
     hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
-  if (needsHydration) {
+  if (needsHydration && !islandPreWrapped) {
     // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
     const bundle = bundleManifest.bundles[routeId];
     const bundleSrc = bundle?.js;
     content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
   }
 
-  // 서버 데이터 스크립트
+  // Zero-JS 모드: island이 없는 페이지에서는 클라이언트 JS 번들을 전송하지 않음
+  // HMR/DevTools는 dev 환경에서만 유지 (CSS 핫리로드 등)
   let dataScript = "";
-  if (serverData && routeId) {
-    const wrappedData = {
-      [routeId]: {
-        serverData,
-        timestamp: Date.now(),
-      },
-    };
-    dataScript = serializeServerData(wrappedData);
-  }
-
-  // Client-side Routing: 라우트 정보 주입
   let routeScript = "";
-  if (enableClientRouter && routeId) {
-    routeScript = generateRouteScript(routeId, routePattern || "", serverData);
-  }
-
-  // Hydration 스크립트
   let hydrationScripts = "";
-  if (needsHydration && bundleManifest) {
-    hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
-  }
-
-  // Client-side Router 스크립트
   let routerScript = "";
-  if (enableClientRouter && bundleManifest) {
-    routerScript = generateClientRouterScript(bundleManifest);
+
+  if (needsHydration) {
+    // 서버 데이터 스크립트 (클라이언트 hydration에서 사용)
+    if (serverData && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData,
+          timestamp: Date.now(),
+        },
+      };
+      dataScript = serializeServerData(wrappedData);
+    }
+
+    // Client-side Routing: 라우트 정보 주입
+    if (enableClientRouter && routeId) {
+      routeScript = generateRouteScript(routeId, routePattern || "", serverData);
+    }
+
+    // Hydration 스크립트 (vendor/runtime/island preloads)
+    if (bundleManifest) {
+      hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
+    }
+
+    // Client-side Router 스크립트
+    if (enableClientRouter && bundleManifest) {
+      routerScript = generateClientRouterScript(bundleManifest);
+    }
   }
 
-  // HMR 스크립트 (개발 모드)
+  // HMR 스크립트 (개발 모드 — island 유무와 무관하게 CSS 핫리로드 지원)
   let hmrScript = "";
   if (isDev && hmrPort) {
     hmrScript = generateHMRScript(hmrPort);
@@ -252,6 +290,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <title>${escapeHtmlText(title)}</title>
   ${cssLinkTag}
   ${headTags}
+  ${collectedHeadTags}
 </head>
 <body>
   <div id="root">${content}</div>

package/src/runtime/streaming-ssr.ts

@@ -18,8 +18,9 @@ import { serializeProps } from "../client/serialize";
 import type { Metadata, MetadataItem } from "../seo/types";
 import { injectSEOIntoOptions, resolveSEO, type SEOOptions } from "../seo/integration/ssr";
 import { PORTS, TIMEOUTS } from "../constants";
-import { escapeHtmlAttr, escapeJsonForInlineScript, escapeJsString } from "./escape";
+import { escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript, escapeJsString } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
+import { getRenderToString } from "./react-renderer";
 
 // ========== Types ==========
 
@@ -313,9 +314,9 @@ export function SuspenseIsland({
   const defaultFallback = React.createElement("div", {
     "data-mandu-island": routeId,
     "data-mandu-priority": priority,
-    "data-mandu-src": bundleSrc,
+    "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
     "data-mandu-loading": "true",
-    style: { minHeight: "50px" },
+    style: { display: "contents", minHeight: "50px" },
   }, React.createElement("div", {
     className: "mandu-loading-skeleton",
     style: {
@@ -334,7 +335,8 @@ export function SuspenseIsland({
     React.createElement("div", {
       "data-mandu-island": routeId,
       "data-mandu-priority": priority,
-      "data-mandu-src": bundleSrc,
+      "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
+      style: { display: "contents" },
     }, children)
   );
 }
@@ -391,15 +393,18 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 
-  // Import map (module scripts 전에 위치해야 함)
+  // Island wrapper (hydration이 필요한 경우)
+  const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
+
+  // Import map (module scripts 전에 위치해야 함 — hydration 필요 시에만)
   let importMapScript = "";
-  if (bundleManifest?.importMap && Object.keys(bundleManifest.importMap.imports).length > 0) {
+  if (needsHydration && bundleManifest.importMap && Object.keys(bundleManifest.importMap.imports).length > 0) {
     const importMapJson = escapeJsonForInlineScript(JSON.stringify(bundleManifest.importMap, null, 2));
     importMapScript = `<script type="importmap">${importMapJson}</script>`;
   }
 
-  // Loading skeleton 애니메이션 스타일
-  const loadingStyles = `
+  // Loading skeleton 애니메이션 스타일 (hydration 필요 시에만)
+  const loadingStyles = !needsHydration ? "" : `
 <style>
 @keyframes mandu-shimmer {
   0% { background-position: 200% 0; }
@@ -419,14 +424,12 @@ function generateHTMLShell(options: StreamingSSROptions): string {
 }
 </style>`;
 
-  // Island wrapper (hydration이 필요한 경우)
-  const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
   let islandOpenTag = "";
   if (needsHydration) {
     const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js || "";
+    const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
     const priority = hydration.priority || "visible";
-    islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}">`;
+    islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
   }
 
   // Import map은 module 스크립트보다 먼저 정의되어야 bare specifier 해석 가능
@@ -435,7 +438,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${escapeHtmlAttr(title)}</title>
+  <title>${escapeHtmlText(title)}</title>
   ${cssLinkTag}
   ${loadingStyles}
   ${importMapScript}
@@ -463,78 +466,81 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
 
   const scripts: string[] = [];
 
-  // 1. Critical 데이터 스크립트 (즉시 사용 가능)
-  if (criticalData && routeId) {
-    const wrappedData = {
-      [routeId]: {
-        serverData: criticalData,
-        timestamp: Date.now(),
-        streaming: true,
-      },
-    };
-    const json = escapeJsonForInlineScript(serializeProps(wrappedData));
-    scripts.push(`<script id="__MANDU_DATA__" type="application/json">${json}</script>`);
-    scripts.push(`<script>window.__MANDU_DATA_RAW__ = document.getElementById('__MANDU_DATA__').textContent;</script>`);
-  }
+  // Zero-JS 모드 판정: island이 없는 페이지에서는 클라이언트 번들을 전송하지 않음
+  const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
-  // 2. 라우트 정보 스크립트
-  if (enableClientRouter && routeId) {
-    const routeInfo = {
-      id: routeId,
-      pattern: routePattern || "",
-      params: {},
-      streaming: true,
-    };
-    const json = escapeJsonForInlineScript(JSON.stringify(routeInfo));
-    scripts.push(`<script>window.__MANDU_ROUTE__ = ${json};</script>`);
-  }
+  // 1~8: hydration이 필요한 경우에만 클라이언트 JS 관련 스크립트 삽입
+  if (needsHydration) {
+    // 1. Critical 데이터 스크립트 (즉시 사용 가능)
+    if (criticalData && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData: criticalData,
+          timestamp: Date.now(),
+          streaming: true,
+        },
+      };
+      const json = escapeJsonForInlineScript(serializeProps(wrappedData));
+      scripts.push(`<script id="__MANDU_DATA__" type="application/json">${json}</script>`);
+      scripts.push(`<script>window.__MANDU_DATA_RAW__ = document.getElementById('__MANDU_DATA__').textContent;</script>`);
+    }
 
-  // 3. Streaming 완료 마커 (클라이언트에서 감지용)
-  scripts.push(`<script>window.__MANDU_STREAMING_SHELL_READY__ = true;</script>`);
+    // 2. 라우트 정보 스크립트
+    if (enableClientRouter && routeId) {
+      const routeInfo = {
+        id: routeId,
+        pattern: routePattern || "",
+        params: {},
+        streaming: true,
+      };
+      const json = escapeJsonForInlineScript(JSON.stringify(routeInfo));
+      scripts.push(`<script>window.__MANDU_ROUTE__ = ${json};</script>`);
+    }
 
-  // 4. Vendor modulepreload (React, ReactDOM 등 - 캐시 효율 극대화)
-  if (bundleManifest?.shared.vendor) {
-    scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.vendor)}">`);
-  }
-  if (bundleManifest?.importMap?.imports) {
-    const imports = bundleManifest.importMap.imports;
-    if (imports["react-dom"] && imports["react-dom"] !== bundleManifest.shared.vendor) {
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(imports["react-dom"])}">`);
+    // 3. Streaming 완료 마커 (클라이언트 hydration에서 감지용)
+    scripts.push(`<script>window.__MANDU_STREAMING_SHELL_READY__ = true;</script>`);
+
+    // 4. Vendor modulepreload (React, ReactDOM 등 - 캐시 효율 극대화)
+    if (bundleManifest.shared.vendor) {
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.vendor)}">`);
     }
-    if (imports["react-dom/client"]) {
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(imports["react-dom/client"])}">`);
+    if (bundleManifest.importMap?.imports) {
+      const imports = bundleManifest.importMap.imports;
+      if (imports["react-dom"] && imports["react-dom"] !== bundleManifest.shared.vendor) {
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(imports["react-dom"])}">`);
+      }
+      if (imports["react-dom/client"]) {
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(imports["react-dom/client"])}">`);
+      }
     }
-  }
 
-  // 5. Runtime modulepreload (hydration 실행 전 미리 로드)
-  if (bundleManifest?.shared.runtime) {
-    scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.runtime)}">`);
-  }
+    // 5. Runtime modulepreload (hydration 실행 전 미리 로드)
+    if (bundleManifest.shared.runtime) {
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundleManifest.shared.runtime)}">`);
+    }
 
-  // 6. Island modulepreload
-  if (bundleManifest && routeId) {
+    // 6. Island modulepreload
     const bundle = bundleManifest.bundles[routeId];
     if (bundle) {
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(bundle.js)}">`);
+      const cacheBust = `${bundle.js}${bundle.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. 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)
-  if (hydration && hydration.strategy !== "none") {
+    // 7.5 React internals shim (must run before react-dom/client runs)
     scripts.push(REACT_INTERNALS_SHIM_SCRIPT);
-  }
 
-  // 8. Router 스크립트
-  if (enableClientRouter && bundleManifest?.shared?.router) {
-    scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.router)}"></script>`);
+    // 8. Router 스크립트
+    if (enableClientRouter && bundleManifest.shared?.router) {
+      scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.router)}"></script>`);
+    }
   }
 
-  // 9. HMR 스크립트 (개발 모드)
+  // 9. HMR 스크립트 (개발 모드 — Zero-JS 페이지에서도 CSS 핫리로드 지원)
   if (isDev && hmrPort) {
     scripts.push(generateHMRScript(hmrPort));
   }
@@ -545,7 +551,6 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   }
 
   // Island wrapper 닫기 (hydration이 필요한 경우)
-  const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
   const islandCloseTag = needsHydration ? "</div>" : "";
 
   return `${islandCloseTag}</div>
@@ -700,11 +705,34 @@ export async function renderToStream(
   }
 
   const encoder = new TextEncoder();
-  const htmlShell = generateHTMLShell(options);
-  // _skipHtmlClose가 true이면 </body></html> 생략 (deferred 스크립트 삽입용)
-  const htmlTail = options._skipHtmlClose
-    ? generateHTMLTailContent(options)
-    : generateHTMLTail(options);
+  const collectedHeadTags = collectStreamingHeadTags(element);
+  const resolvedOptions = collectedHeadTags
+    ? { ...options, headTags: [options.headTags, collectedHeadTags].filter(Boolean).join("\n") }
+    : options;
+  const htmlShell = generateHTMLShell(resolvedOptions);
+
+  // Reset SSR head before real render so streaming components push fresh tags
+  try {
+    const headMod = require("../client/use-head") as { resetSSRHead?: () => void; getSSRHeadTags?: () => string };
+    headMod.resetSSRHead?.();
+  } catch {}
+
+  // Lazy tail: collect late head tags injected during streaming render
+  function buildHtmlTail(): string {
+    const baseTail = resolvedOptions._skipHtmlClose
+      ? generateHTMLTailContent(resolvedOptions)
+      : generateHTMLTail(resolvedOptions);
+    try {
+      const headMod = require("../client/use-head") as { getSSRHeadTags?: () => string };
+      const lateHeadTags = headMod.getSSRHeadTags?.() ?? "";
+      if (lateHeadTags) {
+        const escaped = escapeJsonForInlineScript(JSON.stringify(lateHeadTags));
+        const script = `<script>(function(){var t=${escaped},d=document.createElement('div');d.innerHTML=t;var h=document.head;while(d.firstChild)h.appendChild(d.firstChild);})()</script>`;
+        return script + baseTail;
+      }
+    } catch {}
+    return baseTail;
+  }
 
   let shellSent = false;
   let timedOut = false;
@@ -823,7 +851,7 @@ export async function renderToStream(
           controller.enqueue(encoder.encode(generateErrorScript(timeoutError, routeId)));
 
           if (!tailSent) {
-            controller.enqueue(encoder.encode(htmlTail));
+            controller.enqueue(encoder.encode(buildHtmlTail()));
             tailSent = true;
             metrics.allReadyTime = Date.now() - metrics.startTime;
             onMetrics?.(metrics);
@@ -842,7 +870,7 @@ export async function renderToStream(
 
         if (done) {
           if (!tailSent) {
-            controller.enqueue(encoder.encode(htmlTail));
+            controller.enqueue(encoder.encode(buildHtmlTail()));
             tailSent = true;
             // allReady가 아직 안 끝났을 수 있으므로 현재 시점으로 기록
             if (metrics.allReadyTime === 0) {
@@ -875,7 +903,7 @@ export async function renderToStream(
         controller.enqueue(encoder.encode(generateErrorScript(err, routeId)));
 
         if (!tailSent) {
-          controller.enqueue(encoder.encode(htmlTail));
+          controller.enqueue(encoder.encode(buildHtmlTail()));
           tailSent = true;
           metrics.allReadyTime = Date.now() - metrics.startTime;
           onMetrics?.(metrics);
@@ -895,6 +923,21 @@ export async function renderToStream(
   });
 }
 
+function collectStreamingHeadTags(element: ReactElement): string {
+  try {
+    const mod = require("../client/use-head") as {
+      resetSSRHead?: () => void;
+      getSSRHeadTags?: () => string;
+    };
+    mod.resetSSRHead?.();
+    const renderToString = getRenderToString();
+    renderToString(element);
+    return mod.getSSRHeadTags?.() ?? "";
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Streaming SSR Response 생성
  *

package/src/spec/index.ts

@@ -1,3 +1,2 @@
 export * from "./schema";
 export * from "./load";
-export * from "./lock";

package/src/spec/schema.ts

@@ -234,5 +234,6 @@ export function getRouteHydration(route: RouteSpec): HydrationConfig {
  */
 export function needsHydration(route: RouteSpec): boolean {
   const hydration = getRouteHydration(route);
+  // "none" 이외의 전략만 hydration 필요 (island의 "never"는 strategy가 "none"으로 매핑됨)
   return route.kind === "page" && hydration.strategy !== "none";
 }

package/src/testing/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Mandu Testing Utilities
+ * 서버 없이 라우트/filling 단위 테스트
+ */
+
+import { ManduContext } from "../filling/context";
+import type { ManduFilling } from "../filling/filling";
+import type { RouteSpec, RoutesManifest } from "../spec/schema";
+
+// ========== Types ==========
+
+export interface TestRequestOptions {
+  method?: string;
+  query?: Record<string, string>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  params?: Record<string, string>;
+  /** Action 이름 — 자동으로 _action을 body에 삽입하고 ManduAction 헤더를 추가 */
+  action?: string;
+}
+
+// ========== testFilling ==========
+
+/**
+ * Filling 단위 테스트 — 서버 없이 직접 실행
+ *
+ * @example
+ * ```typescript
+ * import { testFilling } from "@mandujs/core/testing";
+ * import todoRoute from "./app/api/todos/route";
+ *
+ * const res = await testFilling(todoRoute, {
+ *   method: "GET",
+ *   query: { page: "2" },
+ * });
+ * expect(res.status).toBe(200);
+ *
+ * const data = await res.json();
+ * expect(data.todos).toHaveLength(10);
+ * ```
+ */
+export async function testFilling(
+  filling: ManduFilling,
+  options: TestRequestOptions = {}
+): Promise<Response> {
+  const {
+    method: rawMethod,
+    query,
+    body: rawBody,
+    headers: rawHeaders = {},
+    params = {},
+    action,
+  } = options;
+
+  // action 지정 시 자동으로 POST + _action body + ManduAction 헤더
+  const method = rawMethod ?? (action ? "POST" : "GET");
+  const headers = { ...rawHeaders };
+  let body = rawBody;
+
+  if (action) {
+    headers["X-Requested-With"] = "ManduAction";
+    headers["Accept"] = "application/json";
+    if (body && typeof body === "object" && !(body instanceof FormData)) {
+      body = { _action: action, ...(body as Record<string, unknown>) };
+    } else if (!body) {
+      body = { _action: action };
+    }
+  }
+
+  const url = new URL("http://localhost/test");
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const requestInit: RequestInit = {
+    method,
+    headers,
+  };
+
+  if (body !== undefined && method !== "GET" && method !== "HEAD") {
+    if (body instanceof FormData) {
+      requestInit.body = body;
+    } else {
+      requestInit.body = JSON.stringify(body);
+      (requestInit.headers as Record<string, string>)["Content-Type"] = "application/json";
+    }
+  }
+
+  const request = new Request(url.toString(), requestInit);
+  return filling.handle(request, params);
+}
+
+/**
+ * 간단한 Request 생성 헬퍼
+ *
+ * @example
+ * ```typescript
+ * const req = createTestRequest("/api/todos", { method: "POST", body: { title: "test" } });
+ * ```
+ */
+export function createTestRequest(
+  path: string,
+  options: TestRequestOptions = {}
+): Request {
+  const { method = "GET", query, body, headers = {} } = options;
+
+  const url = new URL(`http://localhost${path}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const requestInit: RequestInit = { method, headers: { ...headers } };
+
+  if (body !== undefined && method !== "GET" && method !== "HEAD") {
+    if (body instanceof FormData) {
+      requestInit.body = body;
+    } else {
+      requestInit.body = JSON.stringify(body);
+      (requestInit.headers as Record<string, string>)["Content-Type"] = "application/json";
+    }
+  }
+
+  return new Request(url.toString(), requestInit);
+}
+
+/**
+ * ManduContext 테스트용 생성 헬퍼
+ *
+ * @example
+ * ```typescript
+ * const ctx = createTestContext("/api/users/123", { params: { id: "123" } });
+ * expect(ctx.params.id).toBe("123");
+ * ```
+ */
+export function createTestContext(
+  path: string,
+  options: TestRequestOptions = {}
+): ManduContext {
+  const request = createTestRequest(path, options);
+  return new ManduContext(request, options.params);
+}
+
+// ========== Test Factories ==========
+
+/**
+ * Create a RoutesManifest from partial route definitions.
+ * Fills in sensible defaults so tests only specify the fields they care about.
+ *
+ * @example
+ * ```typescript
+ * const manifest = createTestManifest([
+ *   { id: "home", kind: "page", pattern: "/" },
+ *   { id: "api-users", kind: "api", pattern: "/api/users" },
+ * ]);
+ * ```
+ */
+export function createTestManifest(routes: Partial<RouteSpec>[]): RoutesManifest {
+  return {
+    version: 1,
+    routes: routes.map((r, i) => ({
+      id: r.id ?? `test-route-${i}`,
+      kind: r.kind ?? "page",
+      pattern: r.pattern ?? `/test-${i}`,
+      module: r.module ?? `app/test-${i}/page.tsx`,
+      componentModule:
+        (r.kind ?? "page") === "page"
+          ? (r.componentModule ?? r.module ?? `app/test-${i}/page.tsx`)
+          : undefined,
+      ...r,
+    })) as RouteSpec[],
+  };
+}
+
+/**
+ * Create a minimal island descriptor for testing hydration logic.
+ *
+ * @example
+ * ```typescript
+ * const island = createTestIsland("counter", "interaction");
+ * expect(island.__hydrate).toBe("interaction");
+ * ```
+ */
+export function createTestIsland(name: string, strategy: string = "visible") {
+  return { __island: true, __hydrate: strategy, __name: name };
+}