@mandujs/core 0.9.25 → 0.9.27

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@mandujs/core",
-  "version": "0.9.25",
-  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client/index.ts",
-    "./*": "./src/*"
-  },
-  "files": [
-    "src/**/*"
-  ],
-  "scripts": {
-    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
-    "test:hydration": "bun test tests/hydration",
-    "test:streaming": "bun test tests/streaming-ssr",
-    "test:watch": "bun test --watch"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^15.0.0"
-  },
-  "keywords": [
-    "mandu",
-    "framework",
-    "agent",
-    "ai",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/konamgil/mandu.git",
-    "directory": "packages/core"
-  },
-  "author": "konamgil",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0",
-    "zod": ">=3.0.0"
-  },
-  "dependencies": {
-    "chokidar": "^5.0.0",
-    "ollama": "^0.6.3"
-  }
-}
+{
+  "name": "@mandujs/core",
+  "version": "0.9.27",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "scripts": {
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
+    "test:hydration": "bun test tests/hydration",
+    "test:streaming": "bun test tests/streaming-ssr",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0"
+  },
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "zod": ">=3.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "ollama": "^0.6.3"
+  }
+}

package/src/bundler/build.ts

@@ -58,20 +58,94 @@ function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
 function generateRuntimeSource(): string {
   return `
 /**
- * Mandu Hydration Runtime v0.8.0 (Generated)
+ * Mandu Hydration Runtime v0.9.0 (Generated)
  * Fresh-style dynamic import architecture
+ * + Error Boundary & Loading fallback support
  */
 
 // React 정적 import (Island와 같은 인스턴스 공유)
-import React from 'react';
+import React, { useState, useEffect, Component } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 
-// Hydrated roots 추적 (unmount용)
-const hydratedRoots = new Map();
+// Hydrated roots 추적 (unmount용) - 전역 초기화
+window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
+const hydratedRoots = window.__MANDU_ROOTS__;
 
 // 서버 데이터
 const getServerData = (id) => (window.__MANDU_DATA__ || {})[id]?.serverData || {};
 
+/**
+ * Error Boundary 컴포넌트 (Class Component)
+ * Island의 errorBoundary 옵션을 지원
+ */
+class IslandErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error, errorInfo) {
+    console.error('[Mandu] Island error:', this.props.islandId, error, errorInfo);
+  }
+
+  reset = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      // 커스텀 errorBoundary가 있으면 사용
+      if (this.props.errorBoundary) {
+        return this.props.errorBoundary(this.state.error, this.reset);
+      }
+      // 기본 에러 UI
+      return React.createElement('div', {
+        className: 'mandu-island-error',
+        style: {
+          padding: '16px',
+          background: '#fef2f2',
+          border: '1px solid #fecaca',
+          borderRadius: '8px',
+          color: '#dc2626',
+        }
+      }, [
+        React.createElement('strong', { key: 'title' }, '⚠️ 오류 발생'),
+        React.createElement('p', { key: 'msg', style: { margin: '8px 0', fontSize: '14px' } },
+          this.state.error?.message || '알 수 없는 오류'
+        ),
+        React.createElement('button', {
+          key: 'btn',
+          onClick: this.reset,
+          style: {
+            padding: '6px 12px',
+            background: '#dc2626',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: 'pointer',
+          }
+        }, '다시 시도')
+      ]);
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Loading Wrapper 컴포넌트
+ * Island의 loading 옵션을 지원
+ */
+function IslandLoadingWrapper({ children, loading, isReady }) {
+  if (!isReady && loading) {
+    return loading();
+  }
+  return children;
+}
+
 /**
  * Hydration 스케줄러
  */
@@ -121,6 +195,7 @@ function scheduleHydration(element, src, priority) {
 /**
  * Island 로드 및 hydrate (핵심 함수)
  * Dynamic import로 Island 모듈 로드 후 렌더링
+ * Error Boundary 및 Loading fallback 지원
  */
 async function loadAndHydrate(element, src) {
   const id = element.getAttribute('data-mandu-island');
@@ -138,10 +213,31 @@ async function loadAndHydrate(element, src) {
     const { definition } = island;
     const data = getServerData(id);
 
-    // Island 컴포넌트 (정적 import된 React 사용)
+    // Island 컴포넌트 (Error Boundary + Loading 지원)
     function IslandComponent() {
+      const [isReady, setIsReady] = useState(false);
+
+      useEffect(() => {
+        setIsReady(true);
+      }, []);
+
+      // setup 호출 및 render
       const setupResult = definition.setup(data);
-      return definition.render(setupResult);
+      const content = definition.render(setupResult);
+
+      // Loading wrapper 적용
+      const wrappedContent = definition.loading
+        ? React.createElement(IslandLoadingWrapper, {
+            loading: definition.loading,
+            isReady,
+          }, content)
+        : content;
+
+      // Error Boundary 적용
+      return React.createElement(IslandErrorBoundary, {
+        islandId: id,
+        errorBoundary: definition.errorBoundary,
+      }, wrappedContent);
     }
 
     // Hydrate (SSR DOM 재사용 + 이벤트 연결)
@@ -166,6 +262,12 @@ async function loadAndHydrate(element, src) {
   } catch (error) {
     console.error('[Mandu] Hydration failed for', id, error);
     element.setAttribute('data-mandu-error', 'true');
+
+    // 에러 이벤트 발송
+    element.dispatchEvent(new CustomEvent('mandu:hydration-error', {
+      bubbles: true,
+      detail: { id, error: error.message }
+    }));
   }
 }
 
@@ -174,6 +276,7 @@ async function loadAndHydrate(element, src) {
  */
 function hydrateIslands() {
   const islands = document.querySelectorAll('[data-mandu-island]');
+  const seenIds = new Set();
 
   for (const el of islands) {
     const id = el.getAttribute('data-mandu-island');
@@ -185,6 +288,13 @@ function hydrateIslands() {
       continue;
     }
 
+    // 중복 ID 경고
+    if (seenIds.has(id)) {
+      console.warn('[Mandu] Duplicate island id detected:', id, '- skipping');
+      continue;
+    }
+    seenIds.add(id);
+
     scheduleHydration(el, src, priority);
   }
 }
@@ -841,14 +951,15 @@ async function buildIsland(
     await Bun.write(entryPath, generateIslandEntry(route.id, clientModulePath));
 
     // 빌드
+    // splitting 옵션: true면 공통 코드를 별도 청크로 추출
     const result = await Bun.build({
       entrypoints: [entryPath],
       outdir: outDir,
-      naming: outputName,
+      naming: options.splitting ? "[name]-[hash].js" : outputName,
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
-      splitting: false, // Island 단위로 이미 분리됨
+      splitting: options.splitting ?? false,
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
@@ -864,15 +975,36 @@ async function buildIsland(
     }
 
     // 출력 파일 정보
-    const outputPath = path.join(outDir, outputName);
-    const outputFile = Bun.file(outputPath);
+    // splitting 활성화 시 Bun.build 결과에서 실제 출력 파일 찾기
+    let actualOutputPath: string;
+    let actualOutputName: string;
+
+    if (options.splitting && result.outputs.length > 0) {
+      // splitting 모드: 결과에서 엔트리 파일 찾기
+      const entryOutput = result.outputs.find(
+        (o) => o.kind === "entry-point" || o.path.includes(route.id)
+      );
+      if (entryOutput) {
+        actualOutputPath = entryOutput.path;
+        actualOutputName = path.basename(entryOutput.path);
+      } else {
+        actualOutputPath = result.outputs[0].path;
+        actualOutputName = path.basename(result.outputs[0].path);
+      }
+    } else {
+      // 일반 모드: 예상 경로 사용
+      actualOutputPath = path.join(outDir, outputName);
+      actualOutputName = outputName;
+    }
+
+    const outputFile = Bun.file(actualOutputPath);
     const content = await outputFile.text();
     const gzipped = Bun.gzipSync(Buffer.from(content));
 
     return {
       routeId: route.id,
       entrypoint: route.clientModule!,
-      outputPath: `/.mandu/client/${outputName}`,
+      outputPath: `/.mandu/client/${actualOutputName}`,
       size: outputFile.size,
       gzipSize: gzipped.length,
     };

package/src/bundler/dev.ts

@@ -89,12 +89,21 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     // clientModule 매핑에서 routeId 찾기
     let routeId = clientModuleToRoute.get(normalizedPath);
 
-    // .client.ts 파일인 경우 파일명에서 routeId 추출
-    if (!routeId && changedFile.endsWith(".client.ts")) {
-      const basename = path.basename(changedFile, ".client.ts");
-      const route = manifest.routes.find((r) => r.id === basename);
-      if (route) {
-        routeId = route.id;
+    // .client.ts 또는 .client.tsx 파일인 경우 파일명에서 routeId 추출
+    if (!routeId) {
+      let basename: string | null = null;
+
+      if (changedFile.endsWith(".client.ts")) {
+        basename = path.basename(changedFile, ".client.ts");
+      } else if (changedFile.endsWith(".client.tsx")) {
+        basename = path.basename(changedFile, ".client.tsx");
+      }
+
+      if (basename) {
+        const route = manifest.routes.find((r) => r.id === basename);
+        if (route) {
+          routeId = route.id;
+        }
       }
     }
 

package/src/bundler/types.ts

@@ -103,4 +103,12 @@ export interface BundlerOptions {
   external?: string[];
   /** 환경 변수 주입 */
   define?: Record<string, string>;
+  /**
+   * 코드 스플리팅 활성화
+   * - true: Island들 간 공통 코드를 별도 청크로 추출 (캐시 효율 향상)
+   * - false: 각 Island가 독립 번들로 생성 (기본값)
+   *
+   * 주의: splitting=true인 경우 청크 파일 관리가 필요합니다.
+   */
+  splitting?: boolean;
 }

package/src/client/index.ts

@@ -33,11 +33,23 @@ export {
   useHydrated,
   useIslandEvent,
   fetchApi,
+  // Partials/Slots API
+  partial,
+  slot,
+  createPartialGroup,
   type IslandDefinition,
   type IslandMetadata,
   type CompiledIsland,
   type FetchOptions,
   type WrapComponentOptions,
+  type IslandEventHandle,
+  // Partials/Slots Types
+  type PartialConfig,
+  type PartialDefinition,
+  type CompiledPartial,
+  type SlotDefinition,
+  type CompiledSlot,
+  type PartialGroup,
 } from "./island";
 
 // Runtime API
@@ -96,7 +108,7 @@ export {
 } from "./serialize";
 
 // Re-export as Mandu namespace for consistent API
-import { island, wrapComponent } from "./island";
+import { island, wrapComponent, partial, slot, createPartialGroup } from "./island";
 import { navigate, prefetch, initializeRouter } from "./router";
 import { Link, NavLink } from "./Link";
 
@@ -147,4 +159,22 @@ export const ManduClient = {
    * @see NavLink
    */
   NavLink,
+
+  /**
+   * Create a partial island for granular hydration
+   * @see partial
+   */
+  partial,
+
+  /**
+   * Create a slot for server-rendered content with client hydration
+   * @see slot
+   */
+  slot,
+
+  /**
+   * Create a group of partials for coordinated hydration
+   * @see createPartialGroup
+   */
+  createPartialGroup,
 };

package/src/client/island.ts

@@ -140,15 +140,46 @@ export function useHydrated(): boolean {
   return true;
 }
 
+/**
+ * Island 간 통신을 위한 이벤트 훅 반환 타입
+ */
+export interface IslandEventHandle<T> {
+  /** 이벤트 발송 함수 */
+  emit: (data: T) => void;
+  /** 이벤트 리스너 해제 함수 (cleanup) */
+  cleanup: () => void;
+}
+
 /**
  * Island 간 통신을 위한 이벤트 훅
+ *
+ * @example
+ * ```typescript
+ * // Island A
+ * const { emit, cleanup } = useIslandEvent<{ count: number }>(
+ *   'counter-update',
+ *   (data) => console.log('Received:', data.count)
+ * );
+ *
+ * // 이벤트 발송
+ * emit({ count: 42 });
+ *
+ * // 컴포넌트 언마운트 시 cleanup
+ * useEffect(() => cleanup, []);
+ * ```
+ *
+ * @deprecated 새로운 API는 { emit, cleanup } 객체를 반환합니다.
+ *   하위 호환성을 위해 emit 함수에 cleanup 속성도 추가됩니다.
  */
 export function useIslandEvent<T = unknown>(
   eventName: string,
   handler: (data: T) => void
-): (data: T) => void {
+): IslandEventHandle<T>["emit"] & IslandEventHandle<T> {
   if (typeof window === "undefined") {
-    return () => {};
+    const noop = (() => {}) as IslandEventHandle<T>["emit"] & IslandEventHandle<T>;
+    noop.emit = noop;
+    noop.cleanup = () => {};
+    return noop;
   }
 
   // 이벤트 리스너 등록
@@ -160,10 +191,22 @@ export function useIslandEvent<T = unknown>(
 
   window.addEventListener(customEventName, listener as EventListener);
 
-  // 이벤트 발송 함수 반환
-  return (data: T) => {
+  // cleanup 함수
+  const cleanup = () => {
+    window.removeEventListener(customEventName, listener as EventListener);
+  };
+
+  // 이벤트 발송 함수
+  const emit = (data: T) => {
     window.dispatchEvent(new CustomEvent(customEventName, { detail: data }));
   };
+
+  // 하위 호환성: emit 함수에 cleanup 속성 추가
+  const result = emit as IslandEventHandle<T>["emit"] & IslandEventHandle<T>;
+  result.emit = emit;
+  result.cleanup = cleanup;
+
+  return result;
 }
 
 /**
@@ -254,3 +297,218 @@ export async function fetchApi<T>(
 
   return response.json();
 }
+
+// ========== Client Partials/Slots API ==========
+
+/**
+ * Partial Island 설정
+ * 페이지 내 특정 부분만 하이드레이션할 때 사용
+ */
+export interface PartialConfig {
+  /** Partial 고유 ID */
+  id: string;
+  /** 하이드레이션 우선순위 */
+  priority?: "immediate" | "visible" | "idle" | "interaction";
+  /** 부모 Island ID (중첩 시) */
+  parentId?: string;
+}
+
+/**
+ * Partial Island 정의 타입
+ */
+export interface PartialDefinition<TProps> {
+  /** Partial 컴포넌트 */
+  component: React.ComponentType<TProps>;
+  /** 초기 props (SSR에서 전달) */
+  initialProps?: TProps;
+  /** 하이드레이션 우선순위 */
+  priority?: "immediate" | "visible" | "idle" | "interaction";
+}
+
+/**
+ * 컴파일된 Partial
+ */
+export interface CompiledPartial<TProps> {
+  /** Partial 정의 */
+  definition: PartialDefinition<TProps>;
+  /** Mandu Partial 마커 */
+  __mandu_partial: true;
+  /** Partial ID */
+  __mandu_partial_id?: string;
+}
+
+/**
+ * Partial Island 생성
+ * 페이지 내 특정 부분만 하이드레이션
+ *
+ * @example
+ * ```typescript
+ * // 검색 바만 별도 Island로 분리
+ * const SearchBarPartial = partial({
+ *   component: SearchBar,
+ *   priority: 'interaction', // 사용자 상호작용 시 하이드레이션
+ * });
+ *
+ * // 사용
+ * function Header() {
+ *   return (
+ *     <header>
+ *       <Logo />
+ *       <SearchBarPartial.Render query="" />
+ *     </header>
+ *   );
+ * }
+ * ```
+ */
+export function partial<TProps extends Record<string, any>>(
+  definition: PartialDefinition<TProps>
+): CompiledPartial<TProps> & {
+  Render: React.ComponentType<TProps>;
+} {
+  if (!definition.component) {
+    throw new Error("[Mandu Partial] component is required");
+  }
+
+  const compiled: CompiledPartial<TProps> = {
+    definition,
+    __mandu_partial: true,
+  };
+
+  // Render 컴포넌트 생성
+  const React = require("react");
+
+  const RenderComponent: React.FC<TProps> = (props) => {
+    return React.createElement(definition.component, props);
+  };
+
+  return Object.assign(compiled, { Render: RenderComponent });
+}
+
+/**
+ * Slot 정의 - 서버에서 렌더링되고 클라이언트에서 하이드레이션되는 영역
+ */
+export interface SlotDefinition<TData, TProps> {
+  /** 슬롯 ID */
+  id: string;
+  /** 데이터 로더 (서버에서 실행) */
+  loader?: () => Promise<TData>;
+  /** 데이터를 props로 변환 */
+  transform?: (data: TData) => TProps;
+  /** 렌더링 컴포넌트 */
+  component: React.ComponentType<TProps>;
+  /** 하이드레이션 우선순위 */
+  priority?: "immediate" | "visible" | "idle" | "interaction";
+  /** 로딩 UI */
+  loading?: () => ReactNode;
+  /** 에러 UI */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+}
+
+/**
+ * 컴파일된 Slot
+ */
+export interface CompiledSlot<TData, TProps> {
+  definition: SlotDefinition<TData, TProps>;
+  __mandu_slot: true;
+  __mandu_slot_id: string;
+}
+
+/**
+ * Client Slot 생성
+ * 서버 데이터를 받아 클라이언트에서 하이드레이션되는 컴포넌트
+ *
+ * @example
+ * ```typescript
+ * // 댓글 영역을 별도 슬롯으로 분리
+ * const CommentsSlot = slot({
+ *   id: 'comments',
+ *   loader: async () => fetchComments(postId),
+ *   transform: (data) => ({ comments: data.items }),
+ *   component: CommentList,
+ *   priority: 'visible',
+ *   loading: () => <CommentsSkeleton />,
+ * });
+ * ```
+ */
+export function slot<TData, TProps extends Record<string, any>>(
+  definition: SlotDefinition<TData, TProps>
+): CompiledSlot<TData, TProps> {
+  if (!definition.id) {
+    throw new Error("[Mandu Slot] id is required");
+  }
+  if (!definition.component) {
+    throw new Error("[Mandu Slot] component is required");
+  }
+
+  return {
+    definition,
+    __mandu_slot: true,
+    __mandu_slot_id: definition.id,
+  };
+}
+
+/**
+ * 여러 Partial을 그룹으로 관리
+ */
+export interface PartialGroup {
+  /** 그룹에 Partial 추가 */
+  add: <TProps>(id: string, partial: CompiledPartial<TProps>) => void;
+  /** Partial 조회 */
+  get: <TProps>(id: string) => CompiledPartial<TProps> | undefined;
+  /** 모든 Partial ID 목록 */
+  ids: () => string[];
+  /** 특정 Partial 하이드레이션 트리거 */
+  hydrate: (id: string) => Promise<void>;
+  /** 모든 Partial 하이드레이션 */
+  hydrateAll: () => Promise<void>;
+}
+
+/**
+ * Partial 그룹 생성
+ *
+ * @example
+ * ```typescript
+ * const dashboardPartials = createPartialGroup();
+ *
+ * dashboardPartials.add('chart', ChartPartial);
+ * dashboardPartials.add('table', TablePartial);
+ *
+ * // 특정 부분만 하이드레이션
+ * await dashboardPartials.hydrate('chart');
+ * ```
+ */
+export function createPartialGroup(): PartialGroup {
+  const partials = new Map<string, CompiledPartial<any>>();
+
+  return {
+    add: (id, partial) => {
+      partial.__mandu_partial_id = id;
+      partials.set(id, partial);
+    },
+    get: (id) => partials.get(id),
+    ids: () => Array.from(partials.keys()),
+    hydrate: async (id) => {
+      if (typeof window === "undefined") return;
+
+      const element = document.querySelector(`[data-mandu-partial="${id}"]`);
+      if (element) {
+        element.dispatchEvent(
+          new CustomEvent("mandu:hydrate-partial", { bubbles: true, detail: { id } })
+        );
+      }
+    },
+    hydrateAll: async () => {
+      if (typeof window === "undefined") return;
+
+      const elements = document.querySelectorAll("[data-mandu-partial]");
+      for (const el of elements) {
+        const id = el.getAttribute("data-mandu-partial");
+        if (id) {
+          el.dispatchEvent(
+            new CustomEvent("mandu:hydrate-partial", { bubbles: true, detail: { id } })
+          );
+        }
+      }
+    },
+  };
+}

package/src/runtime/server.ts

@@ -204,24 +204,49 @@ function defaultCreateApp(context: AppContext): React.ReactElement {
 
 // ========== Static File Serving ==========
 
+/**
+ * 경로가 허용된 디렉토리 내에 있는지 검증
+ * Path traversal 공격 방지
+ */
+function isPathSafe(filePath: string, allowedDir: string): boolean {
+  const resolvedPath = path.resolve(filePath);
+  const resolvedAllowedDir = path.resolve(allowedDir);
+  // 경로가 허용된 디렉토리로 시작하는지 확인 (디렉토리 구분자 포함)
+  return resolvedPath.startsWith(resolvedAllowedDir + path.sep) ||
+         resolvedPath === resolvedAllowedDir;
+}
+
 /**
  * 정적 파일 서빙
  * - /.mandu/client/* : 클라이언트 번들 (Island hydration)
  * - /public/* : 정적 에셋 (이미지, CSS 등)
  * - /favicon.ico : 파비콘
+ *
+ * 보안: Path traversal 공격 방지를 위해 모든 경로를 검증합니다.
  */
 async function serveStaticFile(pathname: string): Promise<Response | null> {
   let filePath: string | null = null;
   let isBundleFile = false;
+  let allowedBaseDir: string;
+
+  // Path traversal 시도 조기 차단 (정규화 전 raw 체크)
+  if (pathname.includes("..")) {
+    return null;
+  }
 
   // 1. 클라이언트 번들 파일 (/.mandu/client/*)
   if (pathname.startsWith("/.mandu/client/")) {
-    filePath = path.join(serverSettings.rootDir, pathname);
+    // pathname에서 prefix 제거 후 안전하게 조합
+    const relativePath = pathname.slice("/.mandu/client/".length);
+    allowedBaseDir = path.join(serverSettings.rootDir, ".mandu", "client");
+    filePath = path.join(allowedBaseDir, relativePath);
     isBundleFile = true;
   }
-  // 2. Public 폴더 파일 (/public/* 또는 직접 접근)
+  // 2. Public 폴더 파일 (/public/*)
   else if (pathname.startsWith("/public/")) {
-    filePath = path.join(serverSettings.rootDir, pathname);
+    const relativePath = pathname.slice("/public/".length);
+    allowedBaseDir = path.join(serverSettings.rootDir, "public");
+    filePath = path.join(allowedBaseDir, relativePath);
   }
   // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
   else if (
@@ -230,11 +255,18 @@ async function serveStaticFile(pathname: string): Promise<Response | null> {
     pathname === "/sitemap.xml" ||
     pathname === "/manifest.json"
   ) {
-    filePath = path.join(serverSettings.rootDir, serverSettings.publicDir, pathname);
+    // 고정된 파일명만 허용 (이미 위에서 정확히 매칭됨)
+    const filename = path.basename(pathname);
+    allowedBaseDir = path.join(serverSettings.rootDir, serverSettings.publicDir);
+    filePath = path.join(allowedBaseDir, filename);
+  } else {
+    return null; // 정적 파일이 아님
   }
 
-  if (!filePath) {
-    return null; // 정적 파일이 아님
+  // 최종 경로 검증: 허용된 디렉토리 내에 있는지 확인
+  if (!isPathSafe(filePath, allowedBaseDir!)) {
+    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
+    return null;
   }
 
   try {

package/src/runtime/ssr.ts

@@ -74,7 +74,7 @@ function generateImportMap(manifest: BundleManifest): string {
 
 /**
  * Hydration 스크립트 태그 생성
- * v0.8.0: Island 직접 로드 제거 - Runtime이 data-mandu-src에서 dynamic import
+ * v0.9.0: vendor, runtime 모두 modulepreload로 성능 최적화
  */
 function generateHydrationScripts(
   routeId: string,
@@ -88,8 +88,27 @@ function generateHydrationScripts(
     scripts.push(importMap);
   }
 
+  // Vendor modulepreload (React, ReactDOM 등 - 캐시 효율 극대화)
+  if (manifest.shared.vendor) {
+    scripts.push(`<link rel="modulepreload" href="${manifest.shared.vendor}">`);
+  }
+  if (manifest.importMap?.imports) {
+    const imports = manifest.importMap.imports;
+    // react-dom, react-dom/client 등 추가 preload
+    if (imports["react-dom"] && imports["react-dom"] !== manifest.shared.vendor) {
+      scripts.push(`<link rel="modulepreload" href="${imports["react-dom"]}">`);
+    }
+    if (imports["react-dom/client"]) {
+      scripts.push(`<link rel="modulepreload" href="${imports["react-dom/client"]}">`);
+    }
+  }
+
+  // Runtime modulepreload (hydration 실행 전 미리 로드)
+  if (manifest.shared.runtime) {
+    scripts.push(`<link rel="modulepreload" href="${manifest.shared.runtime}">`);
+  }
+
   // Island 번들 modulepreload (성능 최적화 - prefetch only)
-  // v0.8.0: <script> 태그 제거 - Runtime이 dynamic import로 로드
   const bundle = manifest.bundles[routeId];
   if (bundle) {
     scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);

package/src/runtime/streaming-ssr.ts

@@ -461,7 +461,26 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   // 3. Streaming 완료 마커 (클라이언트에서 감지용)
   scripts.push(`<script>window.__MANDU_STREAMING_SHELL_READY__ = true;</script>`);
 
-  // 4. Island modulepreload
+  // 4. Vendor modulepreload (React, ReactDOM 등 - 캐시 효율 극대화)
+  if (bundleManifest?.shared.vendor) {
+    scripts.push(`<link rel="modulepreload" href="${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="${imports["react-dom"]}">`);
+    }
+    if (imports["react-dom/client"]) {
+      scripts.push(`<link rel="modulepreload" href="${imports["react-dom/client"]}">`);
+    }
+  }
+
+  // 5. Runtime modulepreload (hydration 실행 전 미리 로드)
+  if (bundleManifest?.shared.runtime) {
+    scripts.push(`<link rel="modulepreload" href="${bundleManifest.shared.runtime}">`);
+  }
+
+  // 6. Island modulepreload
   if (bundleManifest && routeId) {
     const bundle = bundleManifest.bundles[routeId];
     if (bundle) {
@@ -469,17 +488,17 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     }
   }
 
-  // 5. Runtime 로드
+  // 7. Runtime 로드
   if (bundleManifest?.shared.runtime) {
     scripts.push(`<script type="module" src="${bundleManifest.shared.runtime}"></script>`);
   }
 
-  // 6. Router 스크립트
+  // 8. Router 스크립트
   if (enableClientRouter && bundleManifest?.shared?.router) {
     scripts.push(`<script type="module" src="${bundleManifest.shared.router}"></script>`);
   }
 
-  // 7. HMR 스크립트 (개발 모드)
+  // 9. HMR 스크립트 (개발 모드)
   if (isDev && hmrPort) {
     scripts.push(generateHMRScript(hmrPort));
   }
@@ -969,58 +988,72 @@ export async function renderWithDeferredData(
     },
   });
 
-  // 3. TransformStream: base stream 통과 + tail 이후 deferred 스크립트 주입
-  const transformStream = new TransformStream<Uint8Array, Uint8Array>({
-    transform(chunk, controller) {
-      // base stream chunk 그대로 전달
-      controller.enqueue(chunk);
-    },
-    async flush(controller) {
-      // base stream 완료 후, deferred가 아직 안 끝났으면 잠시 대기
-      // (단, deferredTimeout 내에서만)
-      if (!allDeferredSettled) {
-        const elapsed = Date.now() - startTime;
-        let remainingTime = deferredTimeout - elapsed;
-        if (streamTimeout && streamTimeout > 0) {
-          const remainingStream = streamTimeout - elapsed;
-          remainingTime = Math.min(remainingTime, remainingStream);
+  // 3. 수동 스트림 파이프라인 (Bun pipeThrough 호환성 문제 해결)
+  //    base stream을 읽고 → 변환 후 → 새 스트림으로 출력
+  const reader = baseStream.getReader();
+
+  const finalStream = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+
+        if (!done && value) {
+          // base stream chunk 그대로 전달
+          controller.enqueue(value);
+          return;
         }
-        remainingTime = Math.max(0, remainingTime);
-        if (remainingTime > 0) {
-          await Promise.race([
-            deferredSettledPromise,
-            new Promise(resolve => setTimeout(resolve, remainingTime)),
-          ]);
+
+        // base stream 완료 → flush 로직 실행
+        // deferred가 아직 안 끝났으면 잠시 대기 (단, deferredTimeout 내에서만)
+        if (!allDeferredSettled) {
+          const elapsed = Date.now() - startTime;
+          let remainingTime = deferredTimeout - elapsed;
+          if (streamTimeout && streamTimeout > 0) {
+            const remainingStream = streamTimeout - elapsed;
+            remainingTime = Math.min(remainingTime, remainingStream);
+          }
+          remainingTime = Math.max(0, remainingTime);
+          if (remainingTime > 0) {
+            await Promise.race([
+              deferredSettledPromise,
+              new Promise(resolve => setTimeout(resolve, remainingTime)),
+            ]);
+          }
         }
-      }
 
-      // 준비된 deferred 스크립트만 주입 (실제 enqueue 기준 카운트)
-      let injectedCount = 0;
-      for (const script of readyScripts) {
-        controller.enqueue(encoder.encode(script));
-        injectedCount++;
-      }
+        // 준비된 deferred 스크립트만 주입 (실제 enqueue 기준 카운트)
+        let injectedCount = 0;
+        for (const script of readyScripts) {
+          controller.enqueue(encoder.encode(script));
+          injectedCount++;
+        }
 
-      if (isDev && injectedCount > 0) {
-        console.log(`[Mandu Streaming] Injected ${injectedCount} deferred scripts`);
-      }
+        if (isDev && injectedCount > 0) {
+          console.log(`[Mandu Streaming] Injected ${injectedCount} deferred scripts`);
+        }
 
-      // HTML 닫기 태그 추가 (</body></html>)
-      controller.enqueue(encoder.encode(generateHTMLClose()));
+        // HTML 닫기 태그 추가 (</body></html>)
+        controller.enqueue(encoder.encode(generateHTMLClose()));
 
-      // 최종 메트릭 보고 (injectedCount가 실제 메트릭)
-      if (onMetrics && baseMetrics) {
-        onMetrics({
-          ...baseMetrics,
-          deferredChunkCount: injectedCount,
-          allReadyTime: Date.now() - startTime,
-        });
+        // 최종 메트릭 보고 (injectedCount가 실제 메트릭)
+        if (onMetrics && baseMetrics) {
+          onMetrics({
+            ...baseMetrics,
+            deferredChunkCount: injectedCount,
+            allReadyTime: Date.now() - startTime,
+          });
+        }
+
+        controller.close();
+      } catch (error) {
+        controller.error(error);
       }
     },
+    cancel() {
+      reader.cancel();
+    },
   });
 
-  const finalStream = baseStream.pipeThrough(transformStream);
-
   return new Response(finalStream, {
     status: 200,
     headers: {