@mandujs/core 0.7.2 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/filling/auth.ts

@@ -1,8 +1,8 @@
 /**
  * Mandu Auth Guards - 인증/인가 헬퍼 🔐
  *
- * Guard에서 사용할 수 있는 타입-안전 인증 헬퍼
- * 인증 실패 시 적절한 에러를 throw하여 Guard 체인 중단
+ * beforeHandle에서 사용할 수 있는 타입-안전 인증 헬퍼
+ * 인증 실패 시 적절한 에러를 throw하여 체인 중단
  */
 
 import type { ManduContext } from "./context";
@@ -57,12 +57,12 @@ export interface UserWithRoles extends BaseUser {
 }
 
 // ============================================
-// 🔐 Auth Guard Helpers
+// 🔐 Auth Helpers
 // ============================================
 
 /**
  * 인증된 사용자 필수
- * Guard에서 user가 없으면 AuthenticationError throw
+ * beforeHandle에서 user가 없으면 AuthenticationError throw
  *
  * @param ctx ManduContext
  * @param key store에서 user를 찾을 키 (기본: 'user')
@@ -70,21 +70,21 @@ export interface UserWithRoles extends BaseUser {
  * @throws AuthenticationError
  *
  * @example
- * ```typescript
+ * typescript
  * import { requireUser } from '@mandujs/core'
  *
  * export default Mandu.filling()
- *   .guard(async (ctx) => {
+ *   .beforeHandle(async (ctx) => {
  *     // JWT 토큰 검증 후 user 저장
  *     const user = await verifyToken(ctx.headers.get('Authorization'));
  *     ctx.set('user', user);
- *     return ctx.next();
+ *     // void 반환 시 계속 진행
  *   })
  *   .get((ctx) => {
  *     const user = requireUser(ctx);  // User 타입 확정, 없으면 401
- *     return ctx.ok({ message: `Hello, ${user.id}!` });
+ *     return ctx.ok({ message: "Hello, " + user.id + "!" });
  *   })
- * ```
+ *
  */
 export function requireUser<T extends BaseUser = BaseUser>(
   ctx: ManduContext,
@@ -114,12 +114,12 @@ export function requireUser<T extends BaseUser = BaseUser>(
  * @throws AuthorizationError (역할 불일치)
  *
  * @example
- * ```typescript
- * .guard((ctx) => {
+ * typescript
+ * .beforeHandle((ctx) => {
  *   requireRole(ctx, 'admin', 'moderator');  // admin 또는 moderator만 허용
- *   return ctx.next();
+ *   // void 반환 시 계속 진행
  * })
- * ```
+ *
  */
 export function requireRole<T extends UserWithRole = UserWithRole>(
   ctx: ManduContext,
@@ -133,7 +133,7 @@ export function requireRole<T extends UserWithRole = UserWithRole>(
 
   if (!roles.includes(user.role)) {
     throw new AuthorizationError(
-      `Required role: ${roles.join(" or ")}`,
+      "Required role: " + roles.join(" or "),
       roles
     );
   }
@@ -152,12 +152,12 @@ export function requireRole<T extends UserWithRole = UserWithRole>(
  * @throws AuthorizationError (역할 불일치)
  *
  * @example
- * ```typescript
- * .guard((ctx) => {
+ * typescript
+ * .beforeHandle((ctx) => {
  *   requireAnyRole(ctx, 'editor', 'admin');  // editor 또는 admin 역할 필요
- *   return ctx.next();
+ *   // void 반환 시 계속 진행
  * })
- * ```
+ *
  */
 export function requireAnyRole<T extends UserWithRoles = UserWithRoles>(
   ctx: ManduContext,
@@ -173,7 +173,7 @@ export function requireAnyRole<T extends UserWithRoles = UserWithRoles>(
 
   if (!hasRole) {
     throw new AuthorizationError(
-      `Required one of roles: ${roles.join(", ")}`,
+      "Required one of roles: " + roles.join(", "),
       roles
     );
   }
@@ -191,12 +191,12 @@ export function requireAnyRole<T extends UserWithRoles = UserWithRoles>(
  * @throws AuthorizationError (역할 불일치)
  *
  * @example
- * ```typescript
- * .guard((ctx) => {
+ * typescript
+ * .beforeHandle((ctx) => {
  *   requireAllRoles(ctx, 'verified', 'premium');  // verified AND premium 필요
- *   return ctx.next();
+ *   // void 반환 시 계속 진행
  * })
- * ```
+ *
  */
 export function requireAllRoles<T extends UserWithRoles = UserWithRoles>(
   ctx: ManduContext,
@@ -212,7 +212,7 @@ export function requireAllRoles<T extends UserWithRoles = UserWithRoles>(
 
   if (missingRoles.length > 0) {
     throw new AuthorizationError(
-      `Missing required roles: ${missingRoles.join(", ")}`,
+      "Missing required roles: " + missingRoles.join(", "),
       roles
     );
   }
@@ -221,28 +221,28 @@ export function requireAllRoles<T extends UserWithRoles = UserWithRoles>(
 }
 
 // ============================================
-// 🔐 Auth Guard Factory
+// 🔐 Auth Handler Factory
 // ============================================
 
 /**
- * 인증 Guard 생성 팩토리
- * 반복되는 인증 로직을 Guard로 변환
+ * 인증 beforeHandle 생성 팩토리
+ * 반복되는 인증 로직을 beforeHandle로 변환
  *
  * @example
- * ```typescript
- * const authGuard = createAuthGuard(async (ctx) => {
+ * typescript
+ * const authHandler = createAuthGuard(async (ctx) => {
  *   const token = ctx.headers.get('Authorization')?.replace('Bearer ', '');
  *   if (!token) return null;
  *   return await verifyJwt(token);
  * });
  *
  * export default Mandu.filling()
- *   .guard(authGuard)
+ *   .beforeHandle(authHandler)
  *   .get((ctx) => {
  *     const user = requireUser(ctx);
  *     return ctx.ok({ user });
  *   })
- * ```
+ *
  */
 export function createAuthGuard<T extends BaseUser>(
   authenticator: (ctx: ManduContext) => T | null | Promise<T | null>,
@@ -253,13 +253,13 @@ export function createAuthGuard<T extends BaseUser>(
 ) {
   const { key = "user", onUnauthenticated } = options;
 
-  return async (ctx: ManduContext): Promise<symbol | Response> => {
+  return async (ctx: ManduContext): Promise<Response | void> => {
     try {
       const user = await authenticator(ctx);
 
       if (user) {
         ctx.set(key, user);
-        return ctx.next();
+        return; // void 반환 시 계속 진행
       }
 
       if (onUnauthenticated) {
@@ -277,24 +277,24 @@ export function createAuthGuard<T extends BaseUser>(
 }
 
 /**
- * 역할 기반 Guard 생성 팩토리
+ * 역할 기반 beforeHandle 생성 팩토리
  *
  * @example
- * ```typescript
+ * typescript
  * const adminOnly = createRoleGuard('admin');
  * const editorOrAdmin = createRoleGuard('editor', 'admin');
  *
  * export default Mandu.filling()
- *   .guard(authGuard)
- *   .guard(adminOnly)  // admin만 접근 가능
+ *   .beforeHandle(authHandler)
+ *   .beforeHandle(adminOnly)  // admin만 접근 가능
  *   .delete((ctx) => ctx.noContent())
- * ```
+ *
  */
 export function createRoleGuard(...allowedRoles: string[]) {
-  return (ctx: ManduContext): symbol | Response => {
+  return (ctx: ManduContext): Response | void => {
     try {
       requireRole(ctx, ...allowedRoles);
-      return ctx.next();
+      return; // void 반환 시 계속 진행
     } catch (error) {
       if (error instanceof AuthenticationError) {
         return ctx.unauthorized(error.message);

package/src/filling/filling.ts

@@ -10,17 +10,23 @@ import { createContract, type ContractDefinition, type ContractInstance } from "
 import {
   type LifecycleStore,
   type OnRequestHandler,
+  type OnParseHandler,
   type BeforeHandleHandler,
   type AfterHandleHandler,
+  type MapResponseHandler,
   type OnErrorHandler,
   type AfterResponseHandler,
   createLifecycleStore,
   executeLifecycle,
+  type ExecuteOptions,
 } from "../runtime/lifecycle";
 
 /** Handler function type */
 export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
 
+/** Guard function type (alias of BeforeHandle) */
+export type Guard = BeforeHandleHandler;
+
 /** HTTP methods */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
@@ -133,16 +139,41 @@ export class ManduFilling<TLoaderData = unknown> {
     return this;
   }
 
+  onParse(fn: OnParseHandler): this {
+    this.config.lifecycle.onParse.push({ fn, scope: "local" });
+    return this;
+  }
+
   beforeHandle(fn: BeforeHandleHandler): this {
     this.config.lifecycle.beforeHandle.push({ fn, scope: "local" });
     return this;
   }
 
+  /**
+   * Guard alias (beforeHandle와 동일)
+   * 인증/인가, 요청 차단 등에 사용
+   */
+  guard(fn: Guard): this {
+    return this.beforeHandle(fn);
+  }
+
+  /**
+   * Middleware alias (guard와 동일)
+   */
+  use(fn: Guard): this {
+    return this.guard(fn);
+  }
+
   afterHandle(fn: AfterHandleHandler): this {
     this.config.lifecycle.afterHandle.push({ fn, scope: "local" });
     return this;
   }
 
+  mapResponse(fn: MapResponseHandler): this {
+    this.config.lifecycle.mapResponse.push({ fn, scope: "local" });
+    return this;
+  }
+
   onError(fn: OnErrorHandler): this {
     this.config.lifecycle.onError.push({ fn, scope: "local" });
     return this;
@@ -156,7 +187,8 @@ export class ManduFilling<TLoaderData = unknown> {
   async handle(
     request: Request,
     params: Record<string, string> = {},
-    routeContext?: { routeId: string; pattern: string }
+    routeContext?: { routeId: string; pattern: string },
+    options?: ExecuteOptions
   ): Promise<Response> {
     const ctx = new ManduContext(request, params);
     const method = request.method.toUpperCase() as HttpMethod;
@@ -165,7 +197,7 @@ export class ManduFilling<TLoaderData = unknown> {
       return ctx.json({ status: "error", message: `Method ${method} not allowed`, allowed: Array.from(this.config.handlers.keys()) }, 405);
     }
     const lifecycleWithDefaults = this.createLifecycleWithDefaults(routeContext);
-    return executeLifecycle(lifecycleWithDefaults, ctx, async () => handler(ctx));
+    return executeLifecycle(lifecycleWithDefaults, ctx, async () => handler(ctx), options);
   }
 
   private createLifecycleWithDefaults(routeContext?: { routeId: string; pattern: string }): LifecycleStore {

package/src/filling/index.ts

@@ -1,21 +1,21 @@
-/**
- * Mandu Filling Module - 만두소 🥟
- */
-
-export { ManduContext, NEXT_SYMBOL, ValidationError, CookieManager } from "./context";
-export type { CookieOptions } from "./context";
-export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
-export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
-
-// Auth Guards
-export {
-  AuthenticationError,
-  AuthorizationError,
-  requireUser,
-  requireRole,
-  requireAnyRole,
-  requireAllRoles,
-  createAuthGuard,
-  createRoleGuard,
-} from "./auth";
-export type { BaseUser, UserWithRole, UserWithRoles } from "./auth";
+/**
+ * Mandu Filling Module - 만두소 🥟
+ */
+
+export { ManduContext, ValidationError, CookieManager } from "./context";
+export type { CookieOptions } from "./context";
+export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
+export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
+
+// Auth Guards
+export {
+  AuthenticationError,
+  AuthorizationError,
+  requireUser,
+  requireRole,
+  requireAnyRole,
+  requireAllRoles,
+  createAuthGuard,
+  createRoleGuard,
+} from "./auth";
+export type { BaseUser, UserWithRole, UserWithRoles } from "./auth";

package/src/filling/tmpclaude-2fc1-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/filling

package/src/filling/tmpclaude-59ee-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/filling

package/src/filling/tmpclaude-7608-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/filling

package/src/filling/tmpclaude-a102-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/filling

package/src/filling/tmpclaude-bf2c-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/filling

package/src/runtime/index.ts

@@ -3,5 +3,6 @@ export * from "./router";
 export * from "./server";
 export * from "./cors";
 export * from "./env";
-export * from "./compose";
-export * from "./lifecycle";
+export * from "./compose";
+export * from "./lifecycle";
+export * from "./trace";

package/src/runtime/lifecycle.ts

@@ -18,6 +18,7 @@
  */
 
 import type { ManduContext } from "../filling/context";
+import { createTracer } from "./trace";
 
 /**
  * 훅 스코프
@@ -115,6 +116,8 @@ export function createLifecycleStore(): LifecycleStore {
 export interface ExecuteOptions {
   /** 바디 파싱이 필요한 메서드 */
   parseBodyMethods?: string[];
+  /** 트레이스 활성화 */
+  trace?: boolean;
 }
 
 const DEFAULT_PARSE_BODY_METHODS = ["POST", "PUT", "PATCH"];
@@ -147,59 +150,74 @@ export async function executeLifecycle(
   options: ExecuteOptions = {}
 ): Promise<Response> {
   const { parseBodyMethods = DEFAULT_PARSE_BODY_METHODS } = options;
+  const tracer = createTracer(ctx, options.trace);
   let response: Response;
 
   try {
     // 1. onRequest
+    const endRequest = tracer.begin("request");
     for (const hook of lifecycle.onRequest) {
       await hook.fn(ctx);
     }
+    endRequest();
 
     // 2. onParse (바디가 있는 메서드만)
     if (parseBodyMethods.includes(ctx.req.method)) {
+      const endParse = tracer.begin("parse");
       for (const hook of lifecycle.onParse) {
         await hook.fn(ctx);
       }
+      endParse();
     }
 
     // 3. beforeHandle (Guard 역할)
+    const endBefore = tracer.begin("beforeHandle");
     for (const hook of lifecycle.beforeHandle) {
       const result = await hook.fn(ctx);
       if (result instanceof Response) {
         // Response 반환 시 체인 중단, afterHandle/mapResponse 건너뜀
         response = result;
+        endBefore();
         // afterResponse는 실행
-        scheduleAfterResponse(lifecycle.afterResponse, ctx);
+        scheduleAfterResponse(lifecycle.afterResponse, ctx, tracer);
         return response;
       }
     }
+    endBefore();
 
     // 4. 메인 핸들러 실행
+    const endHandle = tracer.begin("handle");
     response = await handler();
+    endHandle();
 
     // 5. afterHandle
+    const endAfter = tracer.begin("afterHandle");
     for (const hook of lifecycle.afterHandle) {
       response = await hook.fn(ctx, response);
     }
+    endAfter();
 
     // 6. mapResponse
+    const endMap = tracer.begin("mapResponse");
     for (const hook of lifecycle.mapResponse) {
       response = await hook.fn(ctx, response);
     }
+    endMap();
 
     // 7. afterResponse (비동기)
-    scheduleAfterResponse(lifecycle.afterResponse, ctx);
+    scheduleAfterResponse(lifecycle.afterResponse, ctx, tracer);
 
     return response;
   } catch (err) {
     // onError 처리
     const error = err instanceof Error ? err : new Error(String(err));
+    tracer.error("error", error);
 
     for (const hook of lifecycle.onError) {
       const result = await hook.fn(ctx, error);
       if (result instanceof Response) {
         // afterResponse는 에러 시에도 실행
-        scheduleAfterResponse(lifecycle.afterResponse, ctx);
+        scheduleAfterResponse(lifecycle.afterResponse, ctx, tracer);
         return result;
       }
     }
@@ -214,12 +232,14 @@ export async function executeLifecycle(
  */
 function scheduleAfterResponse(
   hooks: HookContainer<AfterResponseHandler>[],
-  ctx: ManduContext
+  ctx: ManduContext,
+  tracer?: ReturnType<typeof createTracer>
 ): void {
   if (hooks.length === 0) return;
 
   // queueMicrotask로 응답 후 실행
   queueMicrotask(async () => {
+    const endAfterResponse = tracer?.begin("afterResponse") ?? (() => {});
     for (const hook of hooks) {
       try {
         await hook.fn(ctx);
@@ -227,6 +247,7 @@ function scheduleAfterResponse(
         console.error("[Mandu] afterResponse hook error:", err);
       }
     }
+    endAfterResponse();
   });
 }
 

package/src/runtime/ssr.ts

@@ -1,313 +1,315 @@
-import { renderToString } from "react-dom/server";
-import type { ReactElement } from "react";
-import type { BundleManifest } from "../bundler/types";
-import type { HydrationConfig, HydrationPriority } from "../spec/schema";
-
-export interface SSROptions {
-  title?: string;
-  lang?: string;
-  /** 서버에서 로드한 데이터 (클라이언트로 전달) */
-  serverData?: Record<string, unknown>;
-  /** Hydration 설정 */
-  hydration?: HydrationConfig;
-  /** 번들 매니페스트 */
-  bundleManifest?: BundleManifest;
-  /** 라우트 ID (island 식별용) */
-  routeId?: string;
-  /** 추가 head 태그 */
-  headTags?: string;
-  /** 추가 body 끝 태그 */
-  bodyEndTags?: string;
-  /** 개발 모드 여부 */
-  isDev?: boolean;
-  /** HMR 포트 (개발 모드에서 사용) */
-  hmrPort?: number;
-  /** Client-side Routing 활성화 여부 */
-  enableClientRouter?: boolean;
-  /** 라우트 패턴 (Client-side Routing용) */
-  routePattern?: string;
-}
-
-/**
- * SSR 데이터를 안전하게 직렬화
- */
-function serializeServerData(data: Record<string, unknown>): string {
-  // XSS 방지를 위한 이스케이프
-  const json = JSON.stringify(data)
-    .replace(/</g, "\\u003c")
-    .replace(/>/g, "\\u003e")
-    .replace(/&/g, "\\u0026")
-    .replace(/'/g, "\\u0027");
-
-  return `<script id="__MANDU_DATA__" type="application/json">${json}</script>
-<script>window.__MANDU_DATA__ = JSON.parse(document.getElementById('__MANDU_DATA__').textContent);</script>`;
-}
-
-/**
- * Import map 생성 (bare specifier 해결용)
- */
-function generateImportMap(manifest: BundleManifest): string {
-  if (!manifest.importMap || Object.keys(manifest.importMap.imports).length === 0) {
-    return "";
-  }
-
-  const importMapJson = JSON.stringify(manifest.importMap, null, 2);
-  return `<script type="importmap">${importMapJson}</script>`;
-}
-
-/**
- * Hydration 스크립트 태그 생성
- */
-function generateHydrationScripts(
-  routeId: string,
-  manifest: BundleManifest
-): string {
-  const scripts: string[] = [];
-
-  // Import map 먼저 (반드시 module scripts 전에 위치해야 함)
-  const importMap = generateImportMap(manifest);
-  if (importMap) {
-    scripts.push(importMap);
-  }
-
-  // Runtime 로드
-  if (manifest.shared.runtime) {
-    scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
-  }
-
-  // Island 번들 로드
-  const bundle = manifest.bundles[routeId];
-  if (bundle) {
-    // Preload (선택적)
-    scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
-    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
-  }
-
-  return scripts.join("\n");
-}
-
-/**
- * Island 래퍼로 컨텐츠 감싸기
- */
-export function wrapWithIsland(
-  content: string,
-  routeId: string,
-  priority: HydrationPriority = "visible"
-): string {
-  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
-}
-
-export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const {
-    title = "Mandu App",
-    lang = "ko",
-    serverData,
-    hydration,
-    bundleManifest,
-    routeId,
-    headTags = "",
-    bodyEndTags = "",
-    isDev = false,
-    hmrPort,
-    enableClientRouter = false,
-    routePattern,
-  } = options;
-
-  let content = renderToString(element);
-
-  // Island 래퍼 적용 (hydration 필요 시)
-  const needsHydration =
-    hydration && hydration.strategy !== "none" && routeId && bundleManifest;
-
-  if (needsHydration) {
-    content = wrapWithIsland(content, routeId, hydration.priority);
-  }
-
-  // 서버 데이터 스크립트
-  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);
-  }
-
-  // HMR 스크립트 (개발 모드)
-  let hmrScript = "";
-  if (isDev && hmrPort) {
-    hmrScript = generateHMRScript(hmrPort);
-  }
-
-  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>
-  ${headTags}
-</head>
-<body>
-  <div id="root">${content}</div>
-  ${dataScript}
-  ${routeScript}
-  ${hydrationScripts}
-  ${routerScript}
-  ${hmrScript}
-  ${bodyEndTags}
-</body>
-</html>`;
-}
-
-/**
- * Client-side Routing: 현재 라우트 정보 스크립트 생성
- */
-function generateRouteScript(
-  routeId: string,
-  pattern: string,
-  serverData?: Record<string, unknown>
-): string {
-  const routeInfo = {
-    id: routeId,
-    pattern,
-    params: extractParamsFromUrl(pattern),
-  };
-
-  const json = JSON.stringify(routeInfo)
-    .replace(/</g, "\\u003c")
-    .replace(/>/g, "\\u003e");
-
-  return `<script>window.__MANDU_ROUTE__ = ${json};</script>`;
-}
-
-/**
- * URL 패턴에서 파라미터 추출 (클라이언트에서 사용)
- */
-function extractParamsFromUrl(pattern: string): Record<string, string> {
-  // 서버에서는 실제 params를 전달받으므로 빈 객체 반환
-  // 실제 params는 serverData나 별도 전달
-  return {};
-}
-
-/**
- * Client-side Router 스크립트 로드
- */
-function generateClientRouterScript(manifest: BundleManifest): string {
-  // Import map 먼저 (이미 hydration에서 추가되었을 수 있음)
-  const scripts: string[] = [];
-
-  // 라우터 번들이 있으면 로드
-  if (manifest.shared?.router) {
-    scripts.push(`<script type="module" src="${manifest.shared.router}"></script>`);
-  }
-
-  return scripts.join("\n");
-}
-
-/**
- * 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();
-          } else if (msg.type === 'error') {
-            console.error('[Mandu HMR] Build error:', msg.data?.message);
-          }
-        } catch(err) {}
-      };
-      ws.onclose = function() {
-        if (reconnectAttempts < maxReconnectAttempts) {
-          reconnectAttempts++;
-          setTimeout(connect, 1000 * reconnectAttempts);
-        }
-      };
-    } catch(err) {
-      setTimeout(connect, 1000);
-    }
-  }
-  connect();
-})();
-</script>`;
-}
-
-export function createHTMLResponse(html: string, status: number = 200): Response {
-  return new Response(html, {
-    status,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-    },
-  });
-}
-
-export function renderSSR(element: ReactElement, options: SSROptions = {}): Response {
-  const html = renderToHTML(element, options);
-  return createHTMLResponse(html);
-}
-
-/**
- * Hydration이 포함된 SSR 렌더링
- *
- * @example
- * ```typescript
- * const response = await renderWithHydration(
- *   <TodoList todos={todos} />,
- *   {
- *     title: "할일 목록",
- *     routeId: "todos",
- *     serverData: { todos },
- *     hydration: { strategy: "island", priority: "visible" },
- *     bundleManifest,
- *   }
- * );
- * ```
- */
-export async function renderWithHydration(
-  element: ReactElement,
-  options: SSROptions & {
-    routeId: string;
-    serverData: Record<string, unknown>;
-    hydration: HydrationConfig;
-    bundleManifest: BundleManifest;
-  }
-): Promise<Response> {
-  const html = renderToHTML(element, options);
-  return createHTMLResponse(html);
-}
+import { renderToString } from "react-dom/server";
+import { serializeProps } from "../client/serialize";
+import type { ReactElement } from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig, HydrationPriority } from "../spec/schema";
+
+export interface SSROptions {
+  title?: string;
+  lang?: string;
+  /** 서버에서 로드한 데이터 (클라이언트로 전달) */
+  serverData?: Record<string, unknown>;
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** 라우트 ID (island 식별용) */
+  routeId?: string;
+  /** 추가 head 태그 */
+  headTags?: string;
+  /** 추가 body 끝 태그 */
+  bodyEndTags?: string;
+  /** 개발 모드 여부 */
+  isDev?: boolean;
+  /** HMR 포트 (개발 모드에서 사용) */
+  hmrPort?: number;
+  /** Client-side Routing 활성화 여부 */
+  enableClientRouter?: boolean;
+  /** 라우트 패턴 (Client-side Routing용) */
+  routePattern?: string;
+}
+
+/**
+ * SSR 데이터를 안전하게 직렬화 (Fresh 스타일 고급 직렬화)
+ * Date, Map, Set, URL, RegExp, BigInt, 순환참조 지원
+ */
+function serializeServerData(data: Record<string, unknown>): string {
+  // serializeProps로 고급 직렬화 (Date, Map, Set 등 지원)
+  const json = serializeProps(data)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/'/g, "\\u0027");
+
+  return `<script id="__MANDU_DATA__" type="application/json">${json}</script>
+<script>window.__MANDU_DATA_RAW__ = document.getElementById('__MANDU_DATA__').textContent;</script>`;
+}
+
+/**
+ * Import map 생성 (bare specifier 해결용)
+ */
+function generateImportMap(manifest: BundleManifest): string {
+  if (!manifest.importMap || Object.keys(manifest.importMap.imports).length === 0) {
+    return "";
+  }
+
+  const importMapJson = JSON.stringify(manifest.importMap, null, 2);
+  return `<script type="importmap">${importMapJson}</script>`;
+}
+
+/**
+ * Hydration 스크립트 태그 생성
+ */
+function generateHydrationScripts(
+  routeId: string,
+  manifest: BundleManifest
+): string {
+  const scripts: string[] = [];
+
+  // Import map 먼저 (반드시 module scripts 전에 위치해야 함)
+  const importMap = generateImportMap(manifest);
+  if (importMap) {
+    scripts.push(importMap);
+  }
+
+  // Runtime 로드
+  if (manifest.shared.runtime) {
+    scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
+  }
+
+  // Island 번들 로드
+  const bundle = manifest.bundles[routeId];
+  if (bundle) {
+    // Preload (선택적)
+    scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
+    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
+  }
+
+  return scripts.join("\n");
+}
+
+/**
+ * Island 래퍼로 컨텐츠 감싸기
+ */
+export function wrapWithIsland(
+  content: string,
+  routeId: string,
+  priority: HydrationPriority = "visible"
+): string {
+  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
+}
+
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const {
+    title = "Mandu App",
+    lang = "ko",
+    serverData,
+    hydration,
+    bundleManifest,
+    routeId,
+    headTags = "",
+    bodyEndTags = "",
+    isDev = false,
+    hmrPort,
+    enableClientRouter = false,
+    routePattern,
+  } = options;
+
+  let content = renderToString(element);
+
+  // Island 래퍼 적용 (hydration 필요 시)
+  const needsHydration =
+    hydration && hydration.strategy !== "none" && routeId && bundleManifest;
+
+  if (needsHydration) {
+    content = wrapWithIsland(content, routeId, hydration.priority);
+  }
+
+  // 서버 데이터 스크립트
+  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);
+  }
+
+  // HMR 스크립트 (개발 모드)
+  let hmrScript = "";
+  if (isDev && hmrPort) {
+    hmrScript = generateHMRScript(hmrPort);
+  }
+
+  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>
+  ${headTags}
+</head>
+<body>
+  <div id="root">${content}</div>
+  ${dataScript}
+  ${routeScript}
+  ${hydrationScripts}
+  ${routerScript}
+  ${hmrScript}
+  ${bodyEndTags}
+</body>
+</html>`;
+}
+
+/**
+ * Client-side Routing: 현재 라우트 정보 스크립트 생성
+ */
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  serverData?: Record<string, unknown>
+): string {
+  const routeInfo = {
+    id: routeId,
+    pattern,
+    params: extractParamsFromUrl(pattern),
+  };
+
+  const json = JSON.stringify(routeInfo)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+
+  return `<script>window.__MANDU_ROUTE__ = ${json};</script>`;
+}
+
+/**
+ * URL 패턴에서 파라미터 추출 (클라이언트에서 사용)
+ */
+function extractParamsFromUrl(pattern: string): Record<string, string> {
+  // 서버에서는 실제 params를 전달받으므로 빈 객체 반환
+  // 실제 params는 serverData나 별도 전달
+  return {};
+}
+
+/**
+ * Client-side Router 스크립트 로드
+ */
+function generateClientRouterScript(manifest: BundleManifest): string {
+  // Import map 먼저 (이미 hydration에서 추가되었을 수 있음)
+  const scripts: string[] = [];
+
+  // 라우터 번들이 있으면 로드
+  if (manifest.shared?.router) {
+    scripts.push(`<script type="module" src="${manifest.shared.router}"></script>`);
+  }
+
+  return scripts.join("\n");
+}
+
+/**
+ * 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();
+          } else if (msg.type === 'error') {
+            console.error('[Mandu HMR] Build error:', msg.data?.message);
+          }
+        } catch(err) {}
+      };
+      ws.onclose = function() {
+        if (reconnectAttempts < maxReconnectAttempts) {
+          reconnectAttempts++;
+          setTimeout(connect, 1000 * reconnectAttempts);
+        }
+      };
+    } catch(err) {
+      setTimeout(connect, 1000);
+    }
+  }
+  connect();
+})();
+</script>`;
+}
+
+export function createHTMLResponse(html: string, status: number = 200): Response {
+  return new Response(html, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+    },
+  });
+}
+
+export function renderSSR(element: ReactElement, options: SSROptions = {}): Response {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}
+
+/**
+ * Hydration이 포함된 SSR 렌더링
+ *
+ * @example
+ * ```typescript
+ * const response = await renderWithHydration(
+ *   <TodoList todos={todos} />,
+ *   {
+ *     title: "할일 목록",
+ *     routeId: "todos",
+ *     serverData: { todos },
+ *     hydration: { strategy: "island", priority: "visible" },
+ *     bundleManifest,
+ *   }
+ * );
+ * ```
+ */
+export async function renderWithHydration(
+  element: ReactElement,
+  options: SSROptions & {
+    routeId: string;
+    serverData: Record<string, unknown>;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
+): Promise<Response> {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}

package/src/runtime/tmpclaude-1f31-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/runtime

package/src/runtime/tmpclaude-8527-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/runtime

package/src/runtime/tmpclaude-e62c-cwd

@@ -0,0 +1 @@
+/c/Users/LamySolution/workspace/mandu/packages/core/src/runtime

package/src/runtime/trace.ts

@@ -0,0 +1,85 @@
+/**
+ * Mandu Trace 🧭
+ * Lifecycle 단계별 추적 (옵션)
+ */
+
+import type { ManduContext } from "../filling/context";
+
+export type TraceEvent =
+  | "request"
+  | "parse"
+  | "transform"
+  | "beforeHandle"
+  | "handle"
+  | "afterHandle"
+  | "mapResponse"
+  | "afterResponse"
+  | "error";
+
+export type TracePhase = "begin" | "end" | "error";
+
+export interface TraceEntry {
+  event: TraceEvent;
+  phase: TracePhase;
+  time: number;
+  name?: string;
+  error?: string;
+}
+
+export interface TraceCollector {
+  records: TraceEntry[];
+}
+
+export const TRACE_KEY = "__mandu_trace";
+
+const now = (): number => {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+};
+
+export function enableTrace(ctx: ManduContext): TraceCollector {
+  const existing = ctx.get<TraceCollector>(TRACE_KEY);
+  if (existing) return existing;
+  const collector: TraceCollector = { records: [] };
+  ctx.set(TRACE_KEY, collector);
+  return collector;
+}
+
+export function getTrace(ctx: ManduContext): TraceCollector | undefined {
+  return ctx.get<TraceCollector>(TRACE_KEY);
+}
+
+export interface Tracer {
+  enabled: boolean;
+  begin: (event: TraceEvent, name?: string) => () => void;
+  error: (event: TraceEvent, err: unknown, name?: string) => void;
+}
+
+const NOOP_TRACER: Tracer = {
+  enabled: false,
+  begin: () => () => {},
+  error: () => {},
+};
+
+export function createTracer(ctx: ManduContext, enabled?: boolean): Tracer {
+  const shouldEnable = Boolean(enabled) || ctx.has(TRACE_KEY);
+  if (!shouldEnable) return NOOP_TRACER;
+
+  const collector = enableTrace(ctx);
+
+  return {
+    enabled: true,
+    begin: (event, name) => {
+      collector.records.push({ event, phase: "begin", time: now(), name });
+      return () => {
+        collector.records.push({ event, phase: "end", time: now(), name });
+      };
+    },
+    error: (event, err, name) => {
+      const message = err instanceof Error ? err.message : String(err);
+      collector.records.push({ event, phase: "error", time: now(), name, error: message });
+    },
+  };
+}