@mandujs/core 0.7.6 → 0.8.0

package/package.json

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

package/src/bundler/build.ts

@@ -47,44 +47,34 @@ function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
 }
 
 /**
- * Runtime 번들 소스 생성
+ * Runtime 번들 소스 생성 (v0.8.0 재설계)
+ *
+ * 설계 원칙:
+ * - 글로벌 레지스트리 없음 (Island가 스스로 등록 안함)
+ * - Runtime이 Island를 dynamic import()로 로드
+ * - HTML의 data-mandu-src 속성에서 번들 URL 읽기
+ * - 실행 순서 문제 완전 해결
  */
 function generateRuntimeSource(): string {
   return `
 /**
- * Mandu Hydration Runtime (Generated)
+ * Mandu Hydration Runtime v0.8.0 (Generated)
+ * Fresh-style dynamic import architecture
  */
 
-// 글로벌 레지스트리 사용 (Island 번들과 공유)
-// 주의: 변수로 캐싱하면 번들러가 인라인 시 new Map()으로 대체함
-// 항상 window.__MANDU_ISLANDS__를 직접 참조해야 함
-window.__MANDU_ISLANDS__ = window.__MANDU_ISLANDS__ || new Map();
-window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
+// Hydrated roots 추적 (unmount용)
+const hydratedRoots = new Map();
 
 // 서버 데이터
-const serverData = window.__MANDU_DATA__ || {};
-
-/**
- * Island 등록
- */
-export function registerIsland(id, loader) {
-  window.__MANDU_ISLANDS__.set(id, loader);
-}
-
-/**
- * 서버 데이터 가져오기
- */
-export function getServerData(id) {
-  return serverData[id]?.serverData;
-}
+const getServerData = (id) => (window.__MANDU_DATA__ || {})[id]?.serverData || {};
 
 /**
  * Hydration 스케줄러
  */
-function scheduleHydration(element, id, priority, data) {
+function scheduleHydration(element, src, priority) {
   switch (priority) {
     case 'immediate':
-      hydrateIsland(element, id, data);
+      loadAndHydrate(element, src);
       break;
 
     case 'visible':
@@ -92,20 +82,20 @@ function scheduleHydration(element, id, priority, data) {
         const observer = new IntersectionObserver((entries) => {
           if (entries[0].isIntersecting) {
             observer.disconnect();
-            hydrateIsland(element, id, data);
+            loadAndHydrate(element, src);
           }
         }, { rootMargin: '50px' });
         observer.observe(element);
       } else {
-        hydrateIsland(element, id, data);
+        loadAndHydrate(element, src);
       }
       break;
 
     case 'idle':
       if ('requestIdleCallback' in window) {
-        requestIdleCallback(() => hydrateIsland(element, id, data));
+        requestIdleCallback(() => loadAndHydrate(element, src));
       } else {
-        setTimeout(() => hydrateIsland(element, id, data), 200);
+        setTimeout(() => loadAndHydrate(element, src), 200);
       }
       break;
 
@@ -114,7 +104,7 @@ function scheduleHydration(element, id, priority, data) {
         element.removeEventListener('mouseenter', hydrate);
         element.removeEventListener('focusin', hydrate);
         element.removeEventListener('touchstart', hydrate);
-        hydrateIsland(element, id, data);
+        loadAndHydrate(element, src);
       };
       element.addEventListener('mouseenter', hydrate, { once: true, passive: true });
       element.addEventListener('focusin', hydrate, { once: true });
@@ -125,26 +115,26 @@ function scheduleHydration(element, id, priority, data) {
 }
 
 /**
- * 단일 Island hydrate (또는 mount)
- * SSR 플레이스홀더를 Island 컴포넌트로 교체
+ * Island 로드 및 hydrate (핵심 함수)
+ * Dynamic import로 Island 모듈 로드 후 렌더링
  */
-async function hydrateIsland(element, id, data) {
-  const loader = window.__MANDU_ISLANDS__.get(id);
-  if (!loader) {
-    console.warn('[Mandu] Island not found:', id);
-    return;
-  }
+async function loadAndHydrate(element, src) {
+  const id = element.getAttribute('data-mandu-island');
 
   try {
-    const island = await Promise.resolve(loader());
+    // Dynamic import - 이 시점에 Island 모듈 로드
+    const module = await import(src);
+    const island = module.default;
 
-    // Island 컴포넌트 가져오기
-    const islandDef = island.default || island;
-    if (!islandDef.__mandu_island) {
-      throw new Error('[Mandu] Invalid island: ' + id);
+    // Island 유효성 검사
+    if (!island || !island.__mandu_island) {
+      throw new Error('[Mandu] Invalid island module: ' + id);
     }
 
-    const { definition } = islandDef;
+    const { definition } = island;
+    const data = getServerData(id);
+
+    // React 동적 로드
     const { createRoot } = await import('react-dom/client');
     const React = await import('react');
 
@@ -154,11 +144,10 @@ async function hydrateIsland(element, id, data) {
       return definition.render(setupResult);
     }
 
-    // Mount (createRoot 사용 - SSR 플레이스홀더 교체)
-    // hydrateRoot 대신 createRoot 사용: Island는 SSR과 다른 컨텐츠를 렌더링할 수 있음
+    // Mount
     const root = createRoot(element);
     root.render(React.createElement(IslandComponent));
-    window.__MANDU_ROOTS__.set(id, root);
+    hydratedRoots.set(id, root);
 
     // 완료 표시
     element.setAttribute('data-mandu-hydrated', 'true');
@@ -173,6 +162,8 @@ async function hydrateIsland(element, id, data) {
       bubbles: true,
       detail: { id, data }
     }));
+
+    console.log('[Mandu] Hydrated:', id);
   } catch (error) {
     console.error('[Mandu] Hydration failed for', id, error);
     element.setAttribute('data-mandu-error', 'true');
@@ -180,34 +171,47 @@ async function hydrateIsland(element, id, data) {
 }
 
 /**
- * 모든 Island hydrate
+ * 모든 Island hydrate 시작
  */
-export async function hydrateIslands() {
+function hydrateIslands() {
   const islands = document.querySelectorAll('[data-mandu-island]');
 
   for (const el of islands) {
     const id = el.getAttribute('data-mandu-island');
-    if (!id) continue;
-
+    const src = el.getAttribute('data-mandu-src');
     const priority = el.getAttribute('data-mandu-priority') || 'visible';
-    const data = serverData[id]?.serverData || {};
 
-    scheduleHydration(el, id, priority, data);
+    if (!id || !src) {
+      console.warn('[Mandu] Island missing id or src:', el);
+      continue;
+    }
+
+    scheduleHydration(el, src, priority);
   }
 }
 
 /**
- * 자동 초기화
+ * Island unmount
  */
+function unmountIsland(id) {
+  const root = hydratedRoots.get(id);
+  if (root) {
+    root.unmount();
+    hydratedRoots.delete(id);
+    return true;
+  }
+  return false;
+}
+
+// 자동 초기화
 if (document.readyState === 'loading') {
   document.addEventListener('DOMContentLoaded', hydrateIslands);
 } else {
   hydrateIslands();
 }
 
-// 글로벌 레지스트리 접근용 getter
-export const getIslandRegistry = () => window.__MANDU_ISLANDS__;
-export const getHydratedRoots = () => window.__MANDU_ROOTS__;
+// Export for external use
+export { hydrateIslands, unmountIsland, hydratedRoots };
 `;
 }
 
@@ -609,23 +613,22 @@ async function buildRouterRuntime(
 }
 
 /**
- * Island 엔트리 래퍼 생성
- * 주의: 글로벌 레지스트리 직접 사용 (번들러 인라인 문제 방지)
+ * Island 엔트리 래퍼 생성 (v0.8.0 재설계)
+ *
+ * 설계 원칙:
+ * - 순수 export만 (부작용 없음)
+ * - Runtime이 dynamic import로 로드
+ * - 등록/초기화 코드 없음
  */
 function generateIslandEntry(routeId: string, clientModulePath: string): string {
   // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
   const normalizedPath = clientModulePath.replace(/\\/g, "/");
   return `
 /**
- * Mandu Island Entry: ${routeId} (Generated)
+ * Mandu Island: ${routeId} (Generated)
+ * Pure export - no side effects
  */
-
 import island from "${normalizedPath}";
-
-// 글로벌 레지스트리에 직접 등록 (런타임과 공유)
-window.__MANDU_ISLANDS__ = window.__MANDU_ISLANDS__ || new Map();
-window.__MANDU_ISLANDS__.set("${routeId}", () => island);
-
 export default island;
 `;
 }

package/src/client/index.ts

@@ -42,15 +42,12 @@ export {
 
 // Runtime API
 export {
-  registerIsland,
-  getRegisteredIslands,
   getServerData,
-  hydrateIslands,
   getHydrationState,
   unmountIsland,
   unmountAllIslands,
-  initializeRuntime,
-  type IslandLoader,
+  type HydrationState,
+  type HydrationPriority,
 } from "./runtime";
 
 // Client-side Router API
@@ -100,12 +97,12 @@ export {
 
 // Re-export as Mandu namespace for consistent API
 import { island, wrapComponent } from "./island";
-import { hydrateIslands, initializeRuntime } from "./runtime";
 import { navigate, prefetch, initializeRouter } from "./router";
 import { Link, NavLink } from "./Link";
 
 /**
  * Mandu Client namespace
+ * v0.8.0: Hydration은 자동으로 처리됨 (generateRuntimeSource에서 생성)
  */
 export const Mandu = {
   /**
@@ -120,18 +117,6 @@ export const Mandu = {
    */
   wrapComponent,
 
-  /**
-   * Hydrate all islands on the page
-   * @see hydrateIslands
-   */
-  hydrate: hydrateIslands,
-
-  /**
-   * Initialize the hydration runtime
-   * @see initializeRuntime
-   */
-  init: initializeRuntime,
-
   /**
    * Navigate to a URL (client-side)
    * @see navigate

package/src/client/runtime.ts

@@ -1,67 +1,41 @@
 /**
  * Mandu Hydration Runtime 🌊
- * 브라우저에서 Island를 hydrate하는 런타임
+ * v0.8.0: Dynamic Import 기반 아키텍처
+ *
+ * 이 파일은 타입 정의와 유틸리티 함수를 제공합니다.
+ * 실제 Hydration Runtime은 bundler/build.ts의 generateRuntimeSource()에서 생성됩니다.
  */
 
-import { hydrateRoot } from "react-dom/client";
 import type { Root } from "react-dom/client";
-import type { CompiledIsland } from "./island";
-import type { ReactNode } from "react";
-import React from "react";
 
 /**
- * Island 로더 타입
- */
-export type IslandLoader = () => Promise<CompiledIsland<any, any>> | CompiledIsland<any, any>;
-
-/**
- * Island 레지스트리 (글로벌)
- * 주의: 로컬 Map 사용 시 번들러 인라인 문제로 별도 인스턴스 생성됨
- * 항상 window.__MANDU_ISLANDS__를 직접 참조해야 함
+ * Window 전역 타입 확장
  */
 declare global {
   interface Window {
-    __MANDU_ISLANDS__: Map<string, IslandLoader>;
+    /** Hydrated React roots (unmount용) */
     __MANDU_ROOTS__: Map<string, Root>;
+    /** 서버 데이터 */
+    __MANDU_DATA__?: Record<string, { serverData: unknown; timestamp: number }>;
+    /** 직렬화된 서버 데이터 (raw JSON) */
+    __MANDU_DATA_RAW__?: string;
   }
 }
 
-// 글로벌 레지스트리 초기화
-if (typeof window !== "undefined") {
-  window.__MANDU_ISLANDS__ = window.__MANDU_ISLANDS__ || new Map<string, IslandLoader>();
-  window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map<string, Root>();
-}
-
 /**
  * Hydration 상태 추적
  */
-interface HydrationState {
+export interface HydrationState {
   total: number;
   hydrated: number;
   failed: number;
   pending: Set<string>;
 }
 
-const hydrationState: HydrationState = {
-  total: 0,
-  hydrated: 0,
-  failed: 0,
-  pending: new Set(),
-};
-
-/**
- * Island 등록
- */
-export function registerIsland(id: string, loader: IslandLoader): void {
-  window.__MANDU_ISLANDS__.set(id, loader);
-}
-
 /**
- * 등록된 모든 Island 가져오기
+ * Hydration 우선순위
  */
-export function getRegisteredIslands(): string[] {
-  return Array.from(window.__MANDU_ISLANDS__.keys());
-}
+export type HydrationPriority = "immediate" | "visible" | "idle" | "interaction";
 
 /**
  * 서버 데이터 가져오기
@@ -71,7 +45,7 @@ export function getServerData<T = unknown>(islandId: string): T | undefined {
     return undefined;
   }
 
-  const manduData = (window as any).__MANDU_DATA__;
+  const manduData = window.__MANDU_DATA__;
   if (!manduData) {
     return undefined;
   }
@@ -80,186 +54,41 @@ export function getServerData<T = unknown>(islandId: string): T | undefined {
 }
 
 /**
- * Priority-based hydration 스케줄러
- */
-type HydrationPriority = "immediate" | "visible" | "idle" | "interaction";
-
-function scheduleHydration(
-  element: HTMLElement,
-  id: string,
-  priority: HydrationPriority,
-  serverData: unknown
-): void {
-  switch (priority) {
-    case "immediate":
-      hydrateIsland(element, id, serverData);
-      break;
-
-    case "visible":
-      if ("IntersectionObserver" in window) {
-        const observer = new IntersectionObserver(
-          (entries) => {
-            if (entries[0].isIntersecting) {
-              observer.disconnect();
-              hydrateIsland(element, id, serverData);
-            }
-          },
-          { rootMargin: "50px" }
-        );
-        observer.observe(element);
-      } else {
-        // Fallback for older browsers
-        hydrateIsland(element, id, serverData);
-      }
-      break;
-
-    case "idle":
-      if ("requestIdleCallback" in window) {
-        (window as any).requestIdleCallback(() => {
-          hydrateIsland(element, id, serverData);
-        });
-      } else {
-        // Fallback
-        setTimeout(() => hydrateIsland(element, id, serverData), 200);
-      }
-      break;
-
-    case "interaction": {
-      const hydrate = () => {
-        element.removeEventListener("mouseenter", hydrate);
-        element.removeEventListener("focusin", hydrate);
-        element.removeEventListener("touchstart", hydrate);
-        hydrateIsland(element, id, serverData);
-      };
-      element.addEventListener("mouseenter", hydrate, { once: true, passive: true });
-      element.addEventListener("focusin", hydrate, { once: true });
-      element.addEventListener("touchstart", hydrate, { once: true, passive: true });
-      break;
-    }
-  }
-}
-
-/**
- * 단일 Island hydrate
- */
-async function hydrateIsland(
-  element: HTMLElement,
-  id: string,
-  serverData: unknown
-): Promise<void> {
-  const loader = window.__MANDU_ISLANDS__.get(id);
-  if (!loader) {
-    console.warn(`[Mandu] Island not registered: ${id}`);
-    hydrationState.failed++;
-    hydrationState.pending.delete(id);
-    return;
-  }
-
-  try {
-    // 로더 실행 (dynamic import 또는 직접 참조)
-    const island = await Promise.resolve(loader());
-
-    if (!island.__mandu_island) {
-      throw new Error(`[Mandu] Invalid island: ${id}`);
-    }
-
-    const { definition } = island;
-
-    // Island 컴포넌트 생성
-    function IslandComponent(): ReactNode {
-      const setupResult = definition.setup(serverData);
-      return definition.render(setupResult);
-    }
-
-    // ErrorBoundary가 있으면 감싸기
-    let content: ReactNode;
-    if (definition.errorBoundary) {
-      content = React.createElement(
-        ManduErrorBoundary,
-        {
-          fallback: (error: Error, reset: () => void) => definition.errorBoundary!(error, reset),
-        },
-        React.createElement(IslandComponent)
-      );
-    } else {
-      content = React.createElement(IslandComponent);
-    }
-
-    // Hydrate
-    const root = hydrateRoot(element, content);
-    window.__MANDU_ROOTS__.set(id, root);
-
-    // 상태 업데이트
-    element.setAttribute("data-mandu-hydrated", "true");
-    hydrationState.hydrated++;
-    hydrationState.pending.delete(id);
-
-    // 성능 마커
-    if (typeof performance !== "undefined" && performance.mark) {
-      performance.mark(`mandu-hydrated-${id}`);
-    }
-
-    // Hydration 완료 이벤트
-    element.dispatchEvent(
-      new CustomEvent("mandu:hydrated", {
-        bubbles: true,
-        detail: { id, serverData },
-      })
-    );
-  } catch (error) {
-    console.error(`[Mandu] Hydration failed for island ${id}:`, error);
-    hydrationState.failed++;
-    hydrationState.pending.delete(id);
-
-    // 에러 상태 표시
-    element.setAttribute("data-mandu-error", "true");
-
-    // 에러 이벤트
-    element.dispatchEvent(
-      new CustomEvent("mandu:hydration-error", {
-        bubbles: true,
-        detail: { id, error },
-      })
-    );
-  }
-}
-
-/**
- * 모든 Island hydrate 시작
+ * Hydration 상태 조회 (DOM 기반)
  */
-export async function hydrateIslands(): Promise<void> {
+export function getHydrationState(): Readonly<HydrationState> {
   if (typeof document === "undefined") {
-    return;
+    return { total: 0, hydrated: 0, failed: 0, pending: new Set() };
   }
 
   const islands = document.querySelectorAll<HTMLElement>("[data-mandu-island]");
-  const manduData = (window as any).__MANDU_DATA__ || {};
-
-  hydrationState.total = islands.length;
-
-  for (const element of islands) {
-    const id = element.getAttribute("data-mandu-island");
-    if (!id) continue;
-
-    const priority = (element.getAttribute("data-mandu-priority") || "visible") as HydrationPriority;
-    const data = manduData[id]?.serverData || {};
-
-    hydrationState.pending.add(id);
-    scheduleHydration(element, id, priority, data);
-  }
-}
+  const hydrated = document.querySelectorAll<HTMLElement>("[data-mandu-hydrated]");
+  const failed = document.querySelectorAll<HTMLElement>("[data-mandu-error]");
+
+  const pending = new Set<string>();
+  islands.forEach((el) => {
+    const id = el.getAttribute("data-mandu-island");
+    if (id && !el.hasAttribute("data-mandu-hydrated") && !el.hasAttribute("data-mandu-error")) {
+      pending.add(id);
+    }
+  });
 
-/**
- * Hydration 상태 조회
- */
-export function getHydrationState(): Readonly<HydrationState> {
-  return { ...hydrationState };
+  return {
+    total: islands.length,
+    hydrated: hydrated.length,
+    failed: failed.length,
+    pending,
+  };
 }
 
 /**
  * 특정 Island unmount
  */
 export function unmountIsland(id: string): boolean {
+  if (typeof window === "undefined" || !window.__MANDU_ROOTS__) {
+    return false;
+  }
+
   const root = window.__MANDU_ROOTS__.get(id);
   if (!root) {
     return false;
@@ -274,70 +103,12 @@ export function unmountIsland(id: string): boolean {
  * 모든 Island unmount
  */
 export function unmountAllIslands(): void {
-  for (const [id, root] of window.__MANDU_ROOTS__) {
-    root.unmount();
-    window.__MANDU_ROOTS__.delete(id);
-  }
-}
-
-/**
- * 간단한 ErrorBoundary 컴포넌트
- */
-interface ErrorBoundaryProps {
-  children: ReactNode;
-  fallback: (error: Error, reset: () => void) => ReactNode;
-}
-
-interface ErrorBoundaryState {
-  error: Error | null;
-}
-
-class ManduErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
-  constructor(props: ErrorBoundaryProps) {
-    super(props);
-    this.state = { error: null };
-  }
-
-  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
-    return { error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
-    console.error("[Mandu] Island error:", error, errorInfo);
-  }
-
-  reset = (): void => {
-    this.setState({ error: null });
-  };
-
-  render(): ReactNode {
-    if (this.state.error) {
-      return this.props.fallback(this.state.error, this.reset);
-    }
-    return this.props.children;
-  }
-}
-
-/**
- * 자동 초기화 (스크립트 로드 시)
- */
-export function initializeRuntime(): void {
-  if (typeof document === "undefined") {
+  if (typeof window === "undefined" || !window.__MANDU_ROOTS__) {
     return;
   }
 
-  // DOM이 준비되면 hydration 시작
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", () => {
-      hydrateIslands();
-    });
-  } else {
-    // 이미 DOM이 준비된 경우
-    hydrateIslands();
+  for (const [id, root] of window.__MANDU_ROOTS__) {
+    root.unmount();
+    window.__MANDU_ROOTS__.delete(id);
   }
 }
-
-// 자동 초기화 여부 (번들 시 설정)
-if (typeof window !== "undefined" && (window as any).__MANDU_AUTO_INIT__ !== false) {
-  initializeRuntime();
-}

package/src/filling/filling.ts

@@ -141,6 +141,9 @@ export class ManduFilling<TLoaderData = unknown> {
     return this;
   }
 
+  /**
+   * 요청 시작 훅
+   */
   onRequest(fn: OnRequestHandler): this {
     this.config.lifecycle.onRequest.push({ fn, scope: "local" });
     return this;
@@ -159,6 +162,10 @@ export class ManduFilling<TLoaderData = unknown> {
     return this;
   }
 
+  /**
+   * 바디 파싱 훅
+   * body를 읽을 때는 req.clone() 사용 권장
+   */
   onParse(fn: OnParseHandler): this {
     this.config.lifecycle.onParse.push({ fn, scope: "local" });
     return this;
@@ -184,21 +191,33 @@ export class ManduFilling<TLoaderData = unknown> {
     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;
   }
 
+  /**
+   * 응답 후 훅 (비동기)
+   */
   afterResponse(fn: AfterResponseHandler): this {
     this.config.lifecycle.afterResponse.push({ fn, scope: "local" });
     return this;

package/src/runtime/ssr.ts

@@ -59,6 +59,7 @@ function generateImportMap(manifest: BundleManifest): string {
 
 /**
  * Hydration 스크립트 태그 생성
+ * v0.8.0: Island 직접 로드 제거 - Runtime이 data-mandu-src에서 dynamic import
  */
 function generateHydrationScripts(
   routeId: string,
@@ -72,15 +73,14 @@ function generateHydrationScripts(
     scripts.push(importMap);
   }
 
-  // Island 번들 먼저 로드 (등록)
-  // 주의: ES Module 병렬 로드로 인해 Island가 먼저 등록되어야 함
+  // 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}">`);
-    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
   }
 
-  // Runtime 나중에 로드 (hydrateIslands 실행)
+  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
   }
@@ -90,13 +90,16 @@ function generateHydrationScripts(
 
 /**
  * Island 래퍼로 컨텐츠 감싸기
+ * v0.8.0: data-mandu-src 속성 추가 (Runtime이 dynamic import로 로드)
  */
 export function wrapWithIsland(
   content: string,
   routeId: string,
-  priority: HydrationPriority = "visible"
+  priority: HydrationPriority = "visible",
+  bundleSrc?: string
 ): string {
-  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
+  const srcAttr = bundleSrc ? ` data-mandu-src="${bundleSrc}"` : "";
+  return `<div data-mandu-island="${routeId}"${srcAttr} data-mandu-priority="${priority}">${content}</div>`;
 }
 
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
@@ -122,7 +125,10 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
   if (needsHydration) {
-    content = wrapWithIsland(content, routeId, hydration.priority);
+    // 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);
   }
 
   // 서버 데이터 스크립트