@mandujs/core 0.54.17 → 0.54.19

package/src/bundler/build.ts

@@ -4,7 +4,7 @@ import type * as __ManduPluginsReactCompilerTypes0 from "./plugins/react-compile
  * Bun.build 기반 클라이언트 번들 빌드
  */
 
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import type { RouteClientBoundary, RoutesManifest, RouteSpec } from "../spec/schema";
 import { needsHydration, getRouteHydration } from "../spec/schema";
 import type {
   BundleResult,
@@ -36,7 +36,19 @@ import {
   type VendorCacheWriteEntry,
 } from "./vendor-cache";
 import path from "path";
-import fs from "fs/promises";
+import fs from "fs/promises";
+
+interface BoundaryBundleBuild {
+  id: string;
+  route: string;
+  js: string;
+  module: string;
+  exportName: string;
+  priority: "immediate" | "visible" | "idle" | "interaction";
+  hydrate: string;
+  size: number;
+  gzipSize: number;
+}
 
 /**
  * Resolve Mandu's default bundler plugin set from a `BundlerOptions`
@@ -411,23 +423,24 @@ function createEmptyManifest(env: "development" | "production"): BundleManifest
 /**
  * Hydration이 필요한 라우트 필터링
  */
-function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
-  return manifest.routes.filter(
-    (route) =>
-      route.kind === "page" &&
-      route.clientModule &&
-      needsHydration(route)
-  );
-}
+function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
+  return manifest.routes.filter(
+    (route) =>
+      route.kind === "page" &&
+      (!!route.clientModule || !!route.boundaries?.length) &&
+      needsHydration(route)
+  );
+}
 
 function getHydrationRoutesMissingClientModule(manifest: RoutesManifest): RouteSpec[] {
   return manifest.routes.filter(
-    (route) =>
-      route.kind === "page" &&
-      !route.clientModule &&
-      needsHydration(route)
-  );
-}
+    (route) =>
+      route.kind === "page" &&
+      !route.clientModule &&
+      !route.boundaries?.length &&
+      needsHydration(route)
+  );
+}
 
 const REACT_SHIM_EXPORTS = [
   "Activity",
@@ -501,603 +514,15 @@ function formatShimBindings(names: readonly string[], indent = "  "): string {
   return names.map((name) => `${indent}${name},`).join("\n");
 }
 
-/**
- * Runtime 번들 소스 생성 (v0.8.0 재설계)
- *
- * 설계 원칙:
- * - 글로벌 레지스트리 없음 (Island가 스스로 등록 안함)
- * - Runtime이 Island를 dynamic import()로 로드
- * - HTML의 data-mandu-src 속성에서 번들 URL 읽기
- * - 실행 순서 문제 완전 해결
- */
-function generateRuntimeSource(): string {
-  return `
-/**
- * Mandu Hydration Runtime v0.9.0 (Generated)
- * Fresh-style dynamic import architecture
- * + Error Boundary & Loading fallback support
- */
-
-// React 정적 import (Island와 같은 인스턴스 공유)
-import React, { useState, useEffect, Component } from 'react';
-import { hydrateRoot, createRoot } from 'react-dom/client';
-
-// Hydrated roots 추적 (unmount용) - 전역 초기화
-window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
-const hydratedRoots = window.__MANDU_ROOTS__;
-
-const TYPE_MARKERS = {
-  UNDEFINED: "\\u0000_",
-  DATE: "\\u0000D",
-  URL: "\\u0000U",
-  REGEXP: "\\u0000R",
-  MAP: "\\u0000M",
-  SET: "\\u0000S",
-  REF: "\\u0000$",
-  BIGINT: "\\u0000B",
-  SYMBOL: "\\u0000Y",
-  ERROR: "\\u0000E",
-};
-
-function deserializeManduProps(json) {
-  const ctx = { refs: [] };
-  return deserializeManduValue(JSON.parse(json), ctx);
-}
-
-function deserializeManduValue(value, ctx) {
-  if (value === null) return null;
-  if (typeof value === 'string') {
-    if (value === TYPE_MARKERS.UNDEFINED) return undefined;
-    if (value.startsWith("\\u0000\\u0000")) return value.slice(2);
-    if (value.startsWith(TYPE_MARKERS.DATE)) return new Date(value.slice(2));
-    if (value.startsWith(TYPE_MARKERS.URL)) return new URL(value.slice(2));
-    if (value.startsWith(TYPE_MARKERS.REGEXP)) {
-      const str = value.slice(2);
-      const match = str.match(/^\\/(.*)\\/([gimsuy]*)$/);
-      return match ? new RegExp(match[1], match[2]) : str;
-    }
-    if (value.startsWith(TYPE_MARKERS.BIGINT)) return BigInt(value.slice(2));
-    if (value.startsWith(TYPE_MARKERS.SYMBOL)) return Symbol(value.slice(2));
-    if (value.startsWith(TYPE_MARKERS.REF)) return ctx.refs[parseInt(value.slice(2), 10)];
-    return value;
-  }
-  if (typeof value === 'boolean' || typeof value === 'number') return value;
-  if (Array.isArray(value)) {
-    const marker = value[0];
-    if (marker === TYPE_MARKERS.ERROR) {
-      const error = new Error(value[2]);
-      error.name = value[1];
-      if (value[3]) error.stack = value[3];
-      ctx.refs.push(error);
-      return error;
-    }
-    if (marker === TYPE_MARKERS.MAP) {
-      const map = new Map();
-      ctx.refs.push(map);
-      for (let i = 1; i < value.length; i++) {
-        const entry = value[i];
-        map.set(deserializeManduValue(entry[0], ctx), deserializeManduValue(entry[1], ctx));
-      }
-      return map;
-    }
-    if (marker === TYPE_MARKERS.SET) {
-      const set = new Set();
-      ctx.refs.push(set);
-      for (let i = 1; i < value.length; i++) {
-        set.add(deserializeManduValue(value[i], ctx));
-      }
-      return set;
-    }
-    const arr = [];
-    ctx.refs.push(arr);
-    for (const item of value) arr.push(deserializeManduValue(item, ctx));
-    return arr;
-  }
-  if (typeof value === 'object') {
-    const obj = {};
-    ctx.refs.push(obj);
-    for (const [key, nested] of Object.entries(value)) {
-      obj[key] = deserializeManduValue(nested, ctx);
-    }
-    return obj;
-  }
-  return value;
-}
-
-// 서버 데이터
-function readManduData() {
-  if (window.__MANDU_DATA__) return window.__MANDU_DATA__;
-
-  const raw = window.__MANDU_DATA_RAW__ || document.getElementById('__MANDU_DATA__')?.textContent;
-  if (!raw) {
-    window.__MANDU_DATA__ = {};
-    return window.__MANDU_DATA__;
-  }
-
-  try {
-    window.__MANDU_DATA__ = deserializeManduProps(raw);
-  } catch (error) {
-    console.warn('[Mandu] Failed to parse server data:', error);
-    window.__MANDU_DATA__ = {};
-  }
-
-  return window.__MANDU_DATA__;
-}
-
-const getServerData = (id) => readManduData()[id]?.serverData || {};
-
-function findPropsScript(id) {
-  const scripts = document.querySelectorAll('script[data-mandu-props]');
-  for (const script of scripts) {
-    if (script.getAttribute('data-mandu-props') === id) {
-      return script;
-    }
-  }
-  return null;
-}
-
-function parsePropsScript(id) {
-  const script = findPropsScript(id);
-  if (!script || !script.textContent) return null;
-  try {
-    return deserializeManduProps(script.textContent);
-  } catch (error) {
-    console.warn('[Mandu] Failed to parse data-mandu-props for island ' + id + ':', error);
-    return null;
-  }
-}
-
-function readDataProps(element) {
-  const propsEl = element.hasAttribute('data-props')
-    ? element
-    : element.querySelector('[data-props]');
-  if (!propsEl) return null;
-  try {
-    return deserializeManduProps(propsEl.getAttribute('data-props') || '{}');
-  } catch (error) {
-    console.warn('[Mandu] Failed to parse data-props fallback:', error);
-    return null;
-  }
-}
-
-function getIslandProps(id, element) {
-  return parsePropsScript(id) || readDataProps(element) || getServerData(id);
-}
-
 /**
- * Error Boundary 컴포넌트 (Class Component)
- * Island의 errorBoundary 옵션을 지원
+ * Runtime bundle entry point.
+ *
+ * The browser runtime lives in client/runtime-entry.ts so it is typechecked
+ * with the rest of core and imports the shared props deserializer directly.
  */
-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;
-  }
+function getRuntimeEntryPath(): string {
+  return path.resolve(import.meta.dir, "..", "client", "runtime-entry.ts");
 }
-
-/**
- * Loading Wrapper 컴포넌트
- * Island의 loading 옵션을 지원
- */
-function IslandLoadingWrapper({ children, loading, isReady }) {
-  if (!isReady && loading) {
-    return loading();
-  }
-  return children;
-}
-
-function resolveHydrationTarget(element) {
-  if (!(element instanceof HTMLElement)) {
-    return element;
-  }
-
-  if (getComputedStyle(element).display !== 'contents') {
-    return element;
-  }
-
-  const queue = Array.from(element.children);
-  while (queue.length > 0) {
-    const candidate = queue.shift();
-    if (candidate instanceof HTMLElement) {
-      return candidate;
-    }
-    if (candidate) {
-      queue.push(...candidate.children);
-    }
-  }
-
-  return element.parentElement || element;
-}
-
-function hasHydratableMarkup(element) {
-  for (const node of element.childNodes) {
-    if (node.nodeType === Node.ELEMENT_NODE) {
-      return true;
-    }
-
-    if (node.nodeType === Node.TEXT_NODE && node.textContent && node.textContent.trim() !== '') {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-function shouldHydrateCompiledIsland(element) {
-  return (
-    element.getAttribute('data-mandu-loading') !== 'true' &&
-    hasHydratableMarkup(element)
-  );
-}
-
-function createHydrationOptions(element, id, mode) {
-  return {
-    onRecoverableError(error) {
-      element.setAttribute('data-mandu-recoverable-error', 'true');
-      console.warn('[Mandu] Recoverable hydration error:', id, mode, error);
-      element.dispatchEvent(new CustomEvent('mandu:recoverable-hydration-error', {
-        bubbles: true,
-        detail: {
-          id,
-          mode,
-          error: error instanceof Error ? error.message : String(error),
-        },
-      }));
-    },
-  };
-}
-
-/**
- * Hydration 스케줄러
- */
-function priorityToHydrateStrategy(priority) {
-  return priority === 'immediate' ? 'load' : priority;
-}
-
-function scheduleHydration(element, src, strategy) {
-  if (!strategy) strategy = 'load';
-  if (strategy === 'immediate') strategy = 'load';
-
-  if (strategy.startsWith('media(') && strategy.endsWith(')')) {
-    const query = strategy.slice('media('.length, -1).trim();
-    if (!query || !window.matchMedia) {
-      loadAndHydrate(element, src);
-      return;
-    }
-    const mql = window.matchMedia(query);
-    if (mql.matches) {
-      loadAndHydrate(element, src);
-      return;
-    }
-    const onChange = (event) => {
-      if (!event.matches) return;
-      if (mql.removeEventListener) {
-        mql.removeEventListener('change', onChange);
-      } else if (mql.removeListener) {
-        mql.removeListener(onChange);
-      }
-      loadAndHydrate(element, src);
-    };
-    if (mql.addEventListener) {
-      mql.addEventListener('change', onChange);
-    } else if (mql.addListener) {
-      mql.addListener(onChange);
-    }
-    return;
-  }
-
-  switch (strategy) {
-    case 'load':
-    case 'immediate':
-      loadAndHydrate(element, src);
-      break;
-
-    case 'visible':
-      if ('IntersectionObserver' in window) {
-        const observer = new IntersectionObserver((entries) => {
-          if (entries[0].isIntersecting) {
-            observer.disconnect();
-            loadAndHydrate(element, src);
-          }
-        }, { rootMargin: '200px' });
-        const target = resolveHydrationTarget(element);
-        observer.observe(target);
-      } else {
-        loadAndHydrate(element, src);
-      }
-      break;
-
-    case 'idle':
-      if ('requestIdleCallback' in window) {
-        requestIdleCallback(() => loadAndHydrate(element, src));
-      } else {
-        setTimeout(() => loadAndHydrate(element, src), 200);
-      }
-      break;
-
-    case 'interaction': {
-      const target = resolveHydrationTarget(element);
-      const hydrate = () => {
-        target.removeEventListener('touchstart', hydrate);
-        target.removeEventListener('click', hydrate);
-        target.removeEventListener('keydown', hydrate);
-        loadAndHydrate(element, src);
-      };
-      target.addEventListener('touchstart', hydrate, { once: true, passive: true });
-      target.addEventListener('click', hydrate, { once: true });
-      target.addEventListener('keydown', hydrate, { once: true });
-      break;
-    }
-
-    default:
-      console.warn('[Mandu] Unknown hydrate strategy "' + strategy + '", falling back to load.');
-      loadAndHydrate(element, src);
-  }
-}
-
-/**
- * Island 로드 및 hydrate (핵심 함수)
- * Dynamic import로 Island 모듈 로드 후 렌더링
- * Error Boundary 및 Loading fallback 지원
- */
-async function loadAndHydrate(element, src) {
-  const id = element.getAttribute('data-mandu-island');
-  if (!id) {
-    return;
-  }
-
-  if (
-    hydratedRoots.has(id) ||
-    element.hasAttribute('data-mandu-hydrated') ||
-    element.getAttribute('data-mandu-hydrating') === 'true'
-  ) {
-    return;
-  }
-
-  element.setAttribute('data-mandu-hydrating', 'true');
-
-  try {
-    // Dynamic import - 이 시점에 Island 모듈 로드
-    const module = await import(src);
-    const island = module.default;
-    const data = getIslandProps(id, element);
-
-    // Mandu Island (preferred)
-    if (island && island.__mandu_island === true) {
-      const { definition } = island;
-      const shouldHydrate = shouldHydrateCompiledIsland(element);
-      const renderMode = shouldHydrate ? 'hydrate' : 'mount';
-
-      // Island 컴포넌트 (Error Boundary + Loading 지원)
-      function IslandComponent({ initialReady }) {
-        const [isReady, setIsReady] = useState(initialReady);
-
-        useEffect(() => {
-          setIsReady(true);
-        }, []);
-
-        // setup 호출 및 render
-        const setupResult = definition.setup(data);
-        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);
-      }
-
-      const root = shouldHydrate
-        ? hydrateRoot(
-            element,
-            React.createElement(IslandComponent, { initialReady: true }),
-            createHydrationOptions(element, id, renderMode)
-          )
-        : createRoot(element);
-
-      if (!shouldHydrate) {
-        root.render(React.createElement(IslandComponent, { initialReady: false }));
-      }
-
-      hydratedRoots.set(id, root);
-
-      // 완료 표시
-      element.setAttribute('data-mandu-render-mode', renderMode);
-      element.setAttribute('data-mandu-hydrated', 'true');
-
-      // 성능 마커
-      if (performance.mark) {
-        performance.mark('mandu-hydrated-' + id);
-      }
-
-      // 이벤트 발송
-      element.dispatchEvent(new CustomEvent('mandu:hydrated', {
-        bubbles: true,
-        detail: { id, data, mode: renderMode }
-      }));
-
-      // Kitchen DevTools에 island 등록
-      if (window.__MANDU_DEVTOOLS_HOOK__) {
-        const hydrateTime = performance.now ? performance.now() : Date.now();
-        window.__MANDU_DEVTOOLS_HOOK__.emit({
-          type: 'island:register',
-          timestamp: Date.now(),
-          data: {
-            id,
-            name: id,
-            strategy: element.getAttribute('data-mandu-priority') || 'visible',
-            status: 'hydrated',
-            renderMode,
-            hydrateStartTime: hydrateTime - 10,
-            hydrateEndTime: hydrateTime,
-            propsSize: JSON.stringify(data).length,
-          },
-        });
-      }
-
-      console.log('[Mandu] Hydrated:', id, '(' + renderMode + ')');
-    }
-    // Plain React component fallback (e.g. "use client" pages)
-    else if (typeof island === 'function' || React.isValidElement(island)) {
-      console.warn('[Mandu] Plain component hydration:', id);
-      const renderMode = 'hydrate';
-
-      const root = typeof island === 'function'
-        ? hydrateRoot(
-            element,
-            React.createElement(island, data),
-            createHydrationOptions(element, id, renderMode)
-          )
-        : hydrateRoot(element, island, createHydrationOptions(element, id, renderMode));
-
-      hydratedRoots.set(id, root);
-
-      // 완료 표시
-      element.setAttribute('data-mandu-render-mode', renderMode);
-      element.setAttribute('data-mandu-hydrated', 'true');
-
-      // 성능 마커
-      if (performance.mark) {
-        performance.mark('mandu-hydrated-' + id);
-      }
-
-      // 이벤트 발송
-      element.dispatchEvent(new CustomEvent('mandu:hydrated', {
-        bubbles: true,
-        detail: { id, data, mode: renderMode }
-      }));
-
-      console.log('[Mandu] Plain component hydrated:', id, '(' + renderMode + ')');
-    }
-    else {
-      throw new Error('[Mandu] Invalid module: expected Mandu island or React component: ' + id);
-    }
-  } 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 }
-    }));
-  } finally {
-    element.removeAttribute('data-mandu-hydrating');
-  }
-}
-
-/**
- * 모든 Island hydrate 시작
- */
-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');
-    const src = el.getAttribute('data-mandu-src');
-    const priority = el.getAttribute('data-mandu-priority') || '${HYDRATION.DEFAULT_PRIORITY}';
-    const hydrateStrategy = el.getAttribute('data-hydrate') || priorityToHydrateStrategy(priority);
-
-    if (!id || !src) {
-      console.warn('[Mandu] Island missing id or src:', el);
-      continue;
-    }
-
-    // 중복 ID 경고
-    if (seenIds.has(id)) {
-      console.warn('[Mandu] Duplicate island id detected:', id, '- skipping');
-      continue;
-    }
-    seenIds.add(id);
-
-    scheduleHydration(el, src, hydrateStrategy);
-  }
-}
-
-/**
- * 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();
-}
-
-// Export for external use
-export { hydrateIslands, unmountIsland, hydratedRoots };
-`;
-}
-
 /**
  * React shim 소스 생성 (import map용)
  * 주의: export *는 Bun bundler에서 제대로 작동하지 않으므로 명시적 export 필요
@@ -1589,6 +1014,9 @@ function generateIslandEntry(routeId: string, clientModulePath: string, exportNa
   // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
   const normalizedPath = clientModulePath.replace(/\\/g, "/");
   const normalizedExportName = exportName && exportName !== "default" ? exportName : undefined;
+  const namedExport = normalizedExportName && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(normalizedExportName)
+    ? `export const ${normalizedExportName} = exportedIsland;`
+    : "";
   const candidates = [
     normalizedExportName,
     inferClientExportNameFromPath(clientModulePath),
@@ -1608,8 +1036,10 @@ import React from "react";
 import * as islandModule from ${importSpecifier};
 
 const candidateExportNames = ${JSON.stringify(candidates)};
+const explicitExportName = ${JSON.stringify(normalizedExportName ?? null)};
 
 function resolveIslandExport(mod) {
+  if (explicitExportName && mod[explicitExportName]) return mod[explicitExportName];
   if (mod.default) return mod.default;
   for (const name of candidateExportNames) {
     if (mod[name]) return mod[name];
@@ -1630,6 +1060,7 @@ const exportedIsland = island && island.__mandu_island === true
     };
 
 export default exportedIsland;
+${namedExport}
 `;
 }
 
@@ -1692,21 +1123,17 @@ export default {
 /**
  * Runtime 번들 빌드
  */
-async function buildRuntime(
-  outDir: string,
-  options: BundlerOptions
-): Promise<{ success: boolean; outputPath: string; errors: string[] }> {
-  const runtimePath = path.join(outDir, "_runtime.src.js");
-  const outputName = "_runtime.js";
-
-  try {
-    // 런타임 소스 작성
-    await Bun.write(runtimePath, generateRuntimeSource());
-
-    // 빌드
-    const result = await safeBuild({
-      entrypoints: [runtimePath],
-      outdir: outDir,
+async function buildRuntime(
+  outDir: string,
+  options: BundlerOptions
+): Promise<{ success: boolean; outputPath: string; errors: string[] }> {
+  const runtimePath = getRuntimeEntryPath();
+  const outputName = "_runtime.js";
+
+  try {
+    const result = await safeBuild({
+      entrypoints: [runtimePath],
+      outdir: outDir,
       naming: outputName,
       minify: shouldMinify(options),
       sourcemap: options.sourcemap ? "external" : "none",
@@ -1717,29 +1144,24 @@ async function buildRuntime(
         "process.env.NODE_ENV": nodeEnvDefine(options),
         ...options.define,
       },
-    });
-
-    if (!result.success) {
-      // 실패 시 디버깅을 위해 소스 파일을 남겨둠 (_runtime.src.js)
-      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
-      return {
-        success: false,
-        outputPath: "",
-        errors: [`Runtime bundle build failed (source: ${runtimePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types. The source file has been kept for debugging.`],
-      };
-    }
-
-    // 성공 시에만 소스 파일 정리
-    await fs.unlink(runtimePath).catch(() => {});
-
-    return {
-      success: true,
-      outputPath: `/.mandu/client/${outputName}`,
-      errors: [],
-    };
-  } catch (error: unknown) {
-    // 예외 발생 시에도 디버깅을 위해 소스 파일을 남겨둠
-    const extra: string[] = [];
+    });
+
+    if (!result.success) {
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
+      return {
+        success: false,
+        outputPath: "",
+        errors: [`Runtime bundle build failed (source: ${runtimePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types.`],
+      };
+    }
+
+    return {
+      success: true,
+      outputPath: `/.mandu/client/${outputName}`,
+      errors: [],
+    };
+  } catch (error: unknown) {
+    const extra: string[] = [];
     const errObj = error as Record<string, unknown> | null;
     if (errObj && Array.isArray(errObj.errors)) {
       extra.push(...errObj.errors.map((e: unknown) => String((e as Record<string, unknown>)?.message || e)));
@@ -2095,7 +1517,7 @@ function routeIdToAssetStem(routeId: string): string {
 /**
  * 단일 Island 번들 빌드
  */
-async function buildIsland(
+async function buildIsland(
   route: RouteSpec,
   rootDir: string,
   outDir: string,
@@ -2178,8 +1600,171 @@ async function buildIsland(
   } catch (error) {
     await fs.unlink(entryPath).catch(() => {});
     throw error;
-  }
-}
+  }
+}
+
+async function buildBoundaryBundle(
+  boundary: RouteClientBoundary,
+  rootDir: string,
+  outDir: string,
+  options: BundlerOptions,
+): Promise<BoundaryBundleBuild> {
+  const clientModulePath = path.join(rootDir, boundary.module);
+  const assetStem = routeIdToAssetStem(boundary.id);
+  const entryStem = `_entry_boundary_${assetStem}`;
+  const entryPath = path.join(outDir, `${entryStem}.js`);
+  const outputName = `${assetStem}.boundary.js`;
+  const isDev = isDevelopmentBuild(options);
+
+  try {
+    await Bun.write(entryPath, generateIslandEntry(boundary.id, clientModulePath, boundary.exportName));
+
+    const result = await safeBuild({
+      entrypoints: [entryPath],
+      outdir: outDir,
+      naming: options.splitting ? "[name]-[hash].js" : outputName,
+      minify: shouldMinify(options),
+      sourcemap: options.sourcemap ? "external" : "none",
+      target: "browser",
+      splitting: shouldSplitChunks(options),
+      ...(isDev ? { reactFastRefresh: true } : {}),
+      plugins: [...manduClientPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
+      external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
+      define: {
+        "process.env.NODE_ENV": nodeEnvDefine(options),
+        ...options.define,
+      },
+    });
+
+    await fs.unlink(entryPath).catch(() => {});
+
+    if (!result.success) {
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
+      throw new Error(`Boundary build failed for '${boundary.id}' (source: ${clientModulePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this client boundary file.`);
+    }
+
+    let actualOutputPath: string;
+    let actualOutputName: string;
+    if (options.splitting && result.outputs.length > 0) {
+      const entryOutput = result.outputs.find(
+        (o) => o.kind === "entry-point" || o.path.includes(entryStem) || o.path.includes(assetStem),
+      );
+      actualOutputPath = entryOutput?.path ?? result.outputs[0].path;
+      actualOutputName = path.basename(actualOutputPath);
+    } else {
+      actualOutputPath = path.join(outDir, outputName);
+      actualOutputName = outputName;
+    }
+
+    const outputFile = Bun.file(actualOutputPath);
+    const content = await sanitizeGeneratedClientBundle(actualOutputPath, isDev);
+    const gzipped = Bun.gzipSync(Buffer.from(content));
+    const priority = boundaryPriorityToLegacyPriority(boundary.hydrate);
+
+    return {
+      id: boundary.id,
+      route: boundary.routeId,
+      js: `/.mandu/client/${actualOutputName}`,
+      module: boundary.module,
+      exportName: boundary.exportName,
+      priority,
+      hydrate: boundary.hydrate,
+      size: outputFile.size,
+      gzipSize: gzipped.length,
+    };
+  } finally {
+    await fs.unlink(entryPath).catch(() => {});
+  }
+}
+
+async function buildBoundaryBundlesForRecords(
+  boundaries: RouteClientBoundary[],
+  rootDir: string,
+  outDir: string,
+  options: BundlerOptions,
+  errors: string[],
+): Promise<BoundaryBundleBuild[]> {
+  if (boundaries.length === 0) return [];
+  if (pushDuplicateBoundaryIdErrors(boundaries, errors)) return [];
+
+  const results = await Promise.all(
+    boundaries.map(async (boundary) => {
+      try {
+        return await buildBoundaryBundle(boundary, rootDir, outDir, options);
+      } catch (error) {
+        errors.push(`[boundary:${boundary.id}] ${String(error)}`);
+        return null;
+      }
+    }),
+  );
+
+  return results.filter((result): result is BoundaryBundleBuild => result !== null);
+}
+
+function pushDuplicateBoundaryIdErrors(boundaries: RouteClientBoundary[], errors: string[]): boolean {
+  const firstById = new Map<string, RouteClientBoundary>();
+  let hasDuplicate = false;
+
+  for (const boundary of boundaries) {
+    const first = firstById.get(boundary.id);
+    if (!first) {
+      firstById.set(boundary.id, boundary);
+      continue;
+    }
+
+    hasDuplicate = true;
+    errors.push(
+      `[boundary:${boundary.id}] MANDU_BOUNDARY_DUPLICATE_ID Duplicate client boundary id. ` +
+      `First route="${first.routeId}" source="${first.source.file}", duplicate route="${boundary.routeId}" source="${boundary.source.file}". ` +
+      "Boundary ids must be unique before bundle manifest generation.",
+    );
+  }
+
+  return hasDuplicate;
+}
+
+function mergeBoundaryBundlesIntoManifest(
+  manifest: BundleManifest,
+  routeIds: Iterable<string>,
+  boundaryBundles: BoundaryBundleBuild[],
+): void {
+  const rebuiltRouteIds = new Set(routeIds);
+  if (rebuiltRouteIds.size === 0 && boundaryBundles.length === 0) return;
+
+  if (manifest.boundaries) {
+    for (const [id, boundary] of Object.entries(manifest.boundaries)) {
+      if (rebuiltRouteIds.has(boundary.route)) {
+        delete manifest.boundaries[id];
+      }
+    }
+  }
+
+  if (boundaryBundles.length > 0) {
+    manifest.boundaries = manifest.boundaries || {};
+    for (const boundary of boundaryBundles) {
+      manifest.boundaries[boundary.id] = {
+        route: boundary.route,
+        js: boundary.js,
+        module: boundary.module,
+        exportName: boundary.exportName,
+        priority: boundary.priority,
+        hydrate: boundary.hydrate,
+      };
+    }
+  }
+
+  if (manifest.boundaries && Object.keys(manifest.boundaries).length === 0) {
+    delete manifest.boundaries;
+  }
+}
+
+function boundaryPriorityToLegacyPriority(value: string): BoundaryBundleBuild["priority"] {
+  if (value === "load") return "immediate";
+  if (value === "immediate" || value === "visible" || value === "idle" || value === "interaction") {
+    return value;
+  }
+  return "visible";
+}
 
 async function sanitizeGeneratedClientBundle(outputPath: string, isDev: boolean): Promise<string> {
   const source = await Bun.file(outputPath).text();
@@ -2232,10 +1817,11 @@ function createBundleManifest(
   runtimePath: string,
   vendorResult: VendorBuildResult,
   routerPath: string,
-  env: "development" | "production",
-  islandBundles?: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }>,
-  partialBundles?: Array<{ name: string; js: string; priority: PartialFileEntry["priority"] }>,
-): BundleManifest {
+  env: "development" | "production",
+  islandBundles?: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }>,
+  partialBundles?: Array<{ name: string; js: string; priority: PartialFileEntry["priority"] }>,
+  boundaryBundles?: BoundaryBundleBuild[],
+): BundleManifest {
   const bundles: BundleManifest["bundles"] = {};
 
   for (const output of outputs) {
@@ -2262,7 +1848,7 @@ function createBundleManifest(
     }
   }
 
-  let partials: BundleManifest["partials"];
+  let partials: BundleManifest["partials"];
   if (partialBundles && partialBundles.length > 0) {
     partials = {};
     for (const partial of partialBundles) {
@@ -2271,7 +1857,22 @@ function createBundleManifest(
         priority: partial.priority,
       };
     }
-  }
+  }
+
+  let boundaries: BundleManifest["boundaries"];
+  if (boundaryBundles && boundaryBundles.length > 0) {
+    boundaries = {};
+    for (const boundary of boundaryBundles) {
+      boundaries[boundary.id] = {
+        route: boundary.route,
+        js: boundary.js,
+        module: boundary.module,
+        exportName: boundary.exportName,
+        priority: boundary.priority,
+        hydrate: boundary.hydrate,
+      };
+    }
+  }
 
   // Phase 7.1 B-2: expose Fast Refresh dev bundles so the HTML
   // preamble can inject a dynamic import pointing at them. Only
@@ -2288,10 +1889,11 @@ function createBundleManifest(
     version: 1,
     buildTime: new Date().toISOString(),
     env,
-    bundles,
-    ...(islands ? { islands } : {}),
-    ...(partials ? { partials } : {}),
-    shared: {
+    bundles,
+    ...(islands ? { islands } : {}),
+    ...(partials ? { partials } : {}),
+    ...(boundaries ? { boundaries } : {}),
+    shared: {
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
       router: routerPath, // Client-side Router
@@ -2487,26 +2089,37 @@ export async function buildClientBundles(
     };
   }
 
-  // 부분 빌드 모드: targetRouteIds가 지정되면 해당 Island만 재빌드 (#122)
-  if (options.targetRouteIds && options.targetRouteIds.length > 0) {
-    const targetRoutes = hydratedRoutes.filter((r) => options.targetRouteIds!.includes(r.id));
-
-    const targetResults = await Promise.all(
-      targetRoutes.map(async (route) => {
-        try {
-          return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
-        } catch (error) {
+  // 부분 빌드 모드: targetRouteIds가 지정되면 해당 Island만 재빌드 (#122)
+  if (options.targetRouteIds && options.targetRouteIds.length > 0) {
+    const targetRouteIds = new Set(options.targetRouteIds);
+    const targetRoutes = hydratedRoutes.filter((r) => targetRouteIds.has(r.id));
+    const targetIslandRoutes = targetRoutes.filter((route) => !!route.clientModule);
+
+    const targetResults = await Promise.all(
+      targetIslandRoutes.map(async (route) => {
+        try {
+          return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
+        } catch (error) {
           return { ok: false as const, routeId: route.id, error: String(error) };
         }
       }),
     );
     for (const r of targetResults) {
       if (r.ok) outputs.push(r.result);
-      else errors.push(`[${r.routeId}] ${r.error}`);
-    }
-
-    // 기존 매니페스트를 읽어 변경된 Island만 갱신
-    let existingManifest: BundleManifest;
+      else errors.push(`[${r.routeId}] ${r.error}`);
+    }
+
+    const boundaryRecords = targetRoutes.flatMap((route) => route.boundaries ?? []);
+    const boundaryBundles = await buildBoundaryBundlesForRecords(
+      boundaryRecords,
+      rootDir,
+      outDir,
+      options,
+      errors,
+    );
+
+    // 기존 매니페스트를 읽어 변경된 Island만 갱신
+    let existingManifest: BundleManifest;
     try {
       const manifestData = await fs.readFile(path.join(rootDir, ".mandu/manifest.json"), "utf-8");
       existingManifest = JSON.parse(manifestData) as BundleManifest;
@@ -2519,31 +2132,45 @@ export async function buildClientBundles(
     for (const routeId of invalidClientRouteIds) {
       delete existingManifest.bundles[routeId];
     }
-    if (outputs.length > 0 || invalidClientRouteIds.size > 0) {
-      for (const output of outputs) {
-        if (existingManifest.bundles[output.routeId]) {
-          existingManifest.bundles[output.routeId].js = output.outputPath;
-        } else {
-          const route = targetRoutes.find((r) => r.id === output.routeId);
-          const hydration = route ? getRouteHydration(route) : null;
-          existingManifest.bundles[output.routeId] = {
-            js: output.outputPath,
+    if (outputs.length > 0 || invalidClientRouteIds.size > 0 || boundaryRecords.length > 0) {
+      for (const output of outputs) {
+        if (existingManifest.bundles[output.routeId]) {
+          existingManifest.bundles[output.routeId].js = output.outputPath;
+        } else {
+          const route = targetIslandRoutes.find((r) => r.id === output.routeId);
+          const hydration = route ? getRouteHydration(route) : null;
+          existingManifest.bundles[output.routeId] = {
+            js: output.outputPath,
             dependencies: ["_runtime", "_react"],
             priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
-          };
-        }
-      }
-
-      await fs.writeFile(
-        path.join(rootDir, ".mandu/manifest.json"),
+          };
+        }
+      }
+
+      mergeBoundaryBundlesIntoManifest(
+        existingManifest,
+        targetRoutes.map((route) => route.id),
+        boundaryBundles,
+      );
+
+      await fs.writeFile(
+        path.join(rootDir, ".mandu/manifest.json"),
         JSON.stringify(existingManifest, null, 2)
       );
     }
-    // When all builds failed, do NOT overwrite manifest — keep previous good state
-
-    const stats = calculateStats(outputs, startTime);
-    return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
-  }
+    // When all builds failed, do NOT overwrite manifest — keep previous good state
+
+    const stats = calculateStats(
+      outputs,
+      startTime,
+      boundaryBundles.map((boundary) => ({
+        routeId: `boundary:${boundary.id}`,
+        size: boundary.size,
+        gzipSize: boundary.gzipSize,
+      })),
+    );
+    return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
+  }
 
   // #185: Framework-internal 번들 스킵 모드
   // 사용자 코드(src/shared 등) 변경 시 runtime/router/vendor/devtools 재빌드는 낭비.
@@ -2599,7 +2226,7 @@ export async function buildClientBundles(
     }
 
     const islandResults = await Promise.all(
-      hydratedRoutes.map(async (route) => {
+      hydratedRoutes.filter((route) => !!route.clientModule).map(async (route) => {
         try {
           return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
         } catch (error) {
@@ -2645,18 +2272,32 @@ export async function buildClientBundles(
         };
       }
     }
-    if (perIslandBundles.length > 0) {
-      existingManifest.islands = existingManifest.islands || {};
-      for (const ib of perIslandBundles) {
-        existingManifest.islands[ib.name] = {
+    if (perIslandBundles.length > 0) {
+      existingManifest.islands = existingManifest.islands || {};
+      for (const ib of perIslandBundles) {
+        existingManifest.islands[ib.name] = {
           js: ib.js,
           route: ib.route,
           priority: ib.priority,
-        };
-      }
-    }
-
-    const partialBundles: PartialBundleBuild[] = [];
+        };
+      }
+    }
+
+    const boundaryRecords = hydratedRoutes.flatMap((route) => route.boundaries ?? []);
+    const boundaryBundles = await buildBoundaryBundlesForRecords(
+      boundaryRecords,
+      rootDir,
+      outDir,
+      options,
+      errors,
+    );
+    mergeBoundaryBundlesIntoManifest(
+      existingManifest,
+      hydratedRoutes.map((route) => route.id),
+      boundaryBundles,
+    );
+
+    const partialBundles: PartialBundleBuild[] = [];
     if (partialFiles.length > 0) {
       const partialResults = await Promise.all(
         partialFiles.map(async (entry) => {
@@ -2690,15 +2331,22 @@ export async function buildClientBundles(
       JSON.stringify(existingManifest, null, 2),
     );
 
-    const stats = calculateStats(
-      outputs,
-      startTime,
-      partialBundles.map((partial) => ({
-        routeId: `partial:${partial.name}`,
-        size: partial.size,
-        gzipSize: partial.gzipSize,
-      })),
-    );
+    const stats = calculateStats(
+      outputs,
+      startTime,
+      [
+        ...partialBundles.map((partial) => ({
+          routeId: `partial:${partial.name}`,
+          size: partial.size,
+          gzipSize: partial.gzipSize,
+        })),
+        ...boundaryBundles.map((boundary) => ({
+          routeId: `boundary:${boundary.id}`,
+          size: boundary.size,
+          gzipSize: boundary.gzipSize,
+        })),
+      ],
+    );
     return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
   }
 
@@ -2756,7 +2404,7 @@ export async function buildClientBundles(
 
   // 5. 각 Island 번들 병렬 빌드 (#185: L1631의 per-island와 일관성 확보)
   const fullIslandResults = await Promise.all(
-    hydratedRoutes.map(async (route) => {
+    hydratedRoutes.filter((route) => !!route.clientModule).map(async (route) => {
       try {
         return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
       } catch (error) {
@@ -2783,9 +2431,9 @@ export async function buildClientBundles(
 
   // 5.5. Per-island code splitting: scan and build individual island bundles
   const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
-  const islandBundles: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> = [];
+  const islandBundles: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> = [];
 
-  if (islandFiles.length > 0) {
+  if (islandFiles.length > 0) {
     const islandResults = await Promise.all(
       islandFiles.map(async (entry) => {
         try {
@@ -2799,9 +2447,27 @@ export async function buildClientBundles(
     for (const result of islandResults) {
       if (result) islandBundles.push(result);
     }
-  }
-
-  const partialBundles: PartialBundleBuild[] = [];
+  }
+
+  const boundaryRecords = hydratedRoutes.flatMap((route) => route.boundaries ?? []);
+  const boundaryBundles: BoundaryBundleBuild[] = [];
+  if (boundaryRecords.length > 0 && !pushDuplicateBoundaryIdErrors(boundaryRecords, errors)) {
+    const boundaryResults = await Promise.all(
+      boundaryRecords.map(async (boundary) => {
+        try {
+          return await buildBoundaryBundle(boundary, rootDir, outDir, options);
+        } catch (error) {
+          errors.push(`[boundary:${boundary.id}] ${String(error)}`);
+          return null;
+        }
+      }),
+    );
+    for (const result of boundaryResults) {
+      if (result) boundaryBundles.push(result);
+    }
+  }
+
+  const partialBundles: PartialBundleBuild[] = [];
   if (partialFiles.length > 0) {
     const partialResults = await Promise.all(
       partialFiles.map(async (entry) => {
@@ -2825,10 +2491,11 @@ export async function buildClientBundles(
     runtimeResult.outputPath,
     vendorResult,
     routerResult.outputPath,
-    env,
-    islandBundles,
-    partialBundles,
-  );
+    env,
+    islandBundles,
+    partialBundles,
+    boundaryBundles,
+  );
 
   await fs.writeFile(
     path.join(rootDir, ".mandu/manifest.json"),
@@ -2836,15 +2503,22 @@ export async function buildClientBundles(
   );
 
   // 7. 통계 계산
-  const stats = calculateStats(
-    outputs,
-    startTime,
-    partialBundles.map((partial) => ({
-      routeId: `partial:${partial.name}`,
-      size: partial.size,
-      gzipSize: partial.gzipSize,
-    })),
-  );
+  const stats = calculateStats(
+    outputs,
+    startTime,
+    [
+      ...partialBundles.map((partial) => ({
+        routeId: `partial:${partial.name}`,
+        size: partial.size,
+        gzipSize: partial.gzipSize,
+      })),
+      ...boundaryBundles.map((boundary) => ({
+        routeId: `boundary:${boundary.id}`,
+        size: boundary.size,
+        gzipSize: boundary.gzipSize,
+      })),
+    ],
+  );
 
   // Phase 18.τ — fire onBundleComplete(stats) before return.
   await fireOnBundleComplete(stats);
@@ -2873,14 +2547,15 @@ export function formatSize(bytes: number): string {
  */
 export function printBundleStats(result: BundleResult): void {
   console.log("\n📦 Mandu Client Bundles");
-  console.log("=".repeat(50));
-
-  const partialCount = Object.keys(result.manifest.partials ?? {}).length;
-  if (result.outputs.length === 0 && partialCount === 0) {
-    console.log("No islands or partials to bundle (hydration: none or no client entry)");
-    if (result.errors.length > 0) {
-      console.log("\n⚠️ Errors:");
-      for (const error of result.errors) {
+  console.log("=".repeat(50));
+
+  const partialCount = Object.keys(result.manifest.partials ?? {}).length;
+  const boundaryCount = Object.keys(result.manifest.boundaries ?? {}).length;
+  if (result.outputs.length === 0 && partialCount === 0 && boundaryCount === 0) {
+    console.log("No islands, partials, or boundaries to bundle (hydration: none or no client entry)");
+    if (result.errors.length > 0) {
+      console.log("\n⚠️ Errors:");
+      for (const error of result.errors) {
         console.log(`  ${error}`);
       }
     }
@@ -2900,11 +2575,14 @@ export function printBundleStats(result: BundleResult): void {
       `  ${output.routeId}: ${formatSize(output.size)} (gzip: ${formatSize(output.gzipSize)})`
     );
   }
-  if (partialCount > 0) {
-    console.log(`  Partials: ${partialCount}`);
-  }
-
-  if (result.errors.length > 0) {
+  if (partialCount > 0) {
+    console.log(`  Partials: ${partialCount}`);
+  }
+  if (boundaryCount > 0) {
+    console.log(`  Boundaries: ${boundaryCount}`);
+  }
+
+  if (result.errors.length > 0) {
     console.log("\n⚠️ Errors:");
     for (const error of result.errors) {
       console.log(`  ${error}`);