@mandujs/core 0.19.0 → 0.19.2

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;
@@ -139,7 +141,8 @@ function generateHydrationScripts(
   // Island 번들 modulepreload (성능 최적화 - prefetch only)
   const bundle = manifest.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)}">`);
   }
 
   // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
@@ -160,8 +163,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 +183,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     enableClientRouter = false,
     routePattern,
     cssPath,
+    islandPreWrapped,
   } = options;
 
   // CSS 링크 태그 생성
@@ -188,51 +193,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 +277,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

@@ -15,11 +15,12 @@ import React, { Suspense } from "react";
 import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 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 { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
+import type { Metadata, MetadataItem } from "../seo/types";
+import { injectSEOIntoOptions, resolveSEO, type SEOOptions } from "../seo/integration/ssr";
+import { PORTS, TIMEOUTS } from "../constants";
+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>
@@ -699,12 +704,16 @@ export async function renderToStream(
     streamingWarnings.markWarned();
   }
 
-  const encoder = new TextEncoder();
-  const htmlShell = generateHTMLShell(options);
-  // _skipHtmlClose가 true이면 </body></html> 생략 (deferred 스크립트 삽입용)
-  const htmlTail = options._skipHtmlClose
-    ? generateHTMLTailContent(options)
-    : generateHTMLTail(options);
+  const encoder = new TextEncoder();
+  const collectedHeadTags = collectStreamingHeadTags(element);
+  const resolvedOptions = collectedHeadTags
+    ? { ...options, headTags: [options.headTags, collectedHeadTags].filter(Boolean).join("\n") }
+    : options;
+  const htmlShell = generateHTMLShell(resolvedOptions);
+  // _skipHtmlClose가 true이면 </body></html> 생략 (deferred 스크립트 삽입용)
+  const htmlTail = resolvedOptions._skipHtmlClose
+    ? generateHTMLTailContent(resolvedOptions)
+    : generateHTMLTail(resolvedOptions);
 
   let shellSent = false;
   let timedOut = false;
@@ -892,8 +901,23 @@ export async function renderToStream(
         }
       } catch {}
     },
-  });
-}
+  });
+}
+
+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,144 @@
+/**
+ * Mandu Testing Utilities
+ * 서버 없이 라우트/filling 단위 테스트
+ */
+
+import { ManduContext } from "../filling/context";
+import type { ManduFilling } from "../filling/filling";
+
+// ========== 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);
+}

package/src/watcher/watcher.ts

@@ -56,6 +56,17 @@ const DEFAULT_CONFIG: Partial<WatcherConfig> = {
  * Monitors file changes and emits warnings based on architecture rules.
  * Never blocks operations - only warns.
  */
+/**
+ * Windows reserved device names that cannot be used as file/directory names.
+ * These cause EISDIR/ENOENT errors when file watchers try to access them.
+ * See: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
+ */
+const WINDOWS_RESERVED_NAMES = new Set([
+  "CON", "PRN", "AUX", "NUL",
+  "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+  "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+]);
+
 export class FileWatcher {
   private config: WatcherConfig;
   private chokidarWatcher: FSWatcher | null = null;
@@ -118,6 +129,9 @@ export class FileWatcher {
         const basename = path.basename(filePath);
         // Ignore directories in the ignore list
         if (ignoredSet.has(basename)) return true;
+        // Filter out Windows reserved device names (#12)
+        // These cause EISDIR errors when chokidar tries to scandir them
+        if (WINDOWS_RESERVED_NAMES.has(basename.toUpperCase().replace(/\..*$/, ""))) return true;
         // For files, only watch matching extensions
         if (stats?.isFile() && extSet.size > 0) {
           const ext = path.extname(filePath);
@@ -158,7 +172,19 @@ export class FileWatcher {
     });
 
     this.chokidarWatcher.on("error", (error: unknown) => {
-      console.error(`[Watch] Error:`, error instanceof Error ? error.message : String(error));
+      const message = error instanceof Error ? error.message : String(error);
+      // Suppress EISDIR errors from Windows reserved device names (#12)
+      // e.g. "EISDIR: illegal operation on a directory, scandir 'C:\...\nul'"
+      if (message.includes("EISDIR")) {
+        const pathMatch = message.match(/scandir\s+'([^']+)'/);
+        if (pathMatch) {
+          const baseName = pathMatch[1].split(/[/\\]/).pop() || "";
+          if (WINDOWS_RESERVED_NAMES.has(baseName.toUpperCase())) {
+            return; // Silently ignore — these are not real directories
+          }
+        }
+      }
+      console.error(`[Watch] Error:`, message);
     });
 
     this._active = true;