@mandujs/core 0.54.2 → 0.54.4

package/src/bundler/build.ts

@@ -10,18 +10,20 @@ import type {
   BundleResult,
   BundleOutput,
   BundleManifest,
-  BundleStats,
-  BundlerOptions,
-  IslandFileEntry,
-} from "./types";
+  BundleStats,
+  BundlerOptions,
+  IslandFileEntry,
+  PartialFileEntry,
+} from "./types";
 import { HYDRATION } from "../constants";
 import { safeBuild } from "./safe-build";
 import { fastRefreshPlugin } from "./fast-refresh-plugin";
 import { defaultBundlerPlugins } from "./plugins";
 import type { BunPlugin } from "bun";
-import { mark, measure } from "../perf";
-import { HMR_PERF } from "../perf/hmr-markers";
-import { runOnBundleComplete } from "../plugins/runner";
+import { mark, measure } from "../perf";
+import { HMR_PERF } from "../perf/hmr-markers";
+import { runOnBundleComplete } from "../plugins/runner";
+import { validateClientModuleForBrowserBundle } from "../router/client-entry";
 import {
   readVendorCache,
   writeVendorCache,
@@ -186,7 +188,46 @@ async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<Is
  *
  * @internal
  */
-export const _testOnly_scanIslandFiles = scanIslandFiles;
+export const _testOnly_scanIslandFiles = scanIslandFiles;
+
+function normalizeClientEntryName(name: string): string {
+  return name
+    .trim()
+    .replace(/[^A-Za-z0-9_-]/g, "-")
+    .replace(/^-+|-+$/g, "") || "partial";
+}
+
+async function scanPartialFiles(rootDir: string): Promise<PartialFileEntry[]> {
+  const entries: PartialFileEntry[] = [];
+  const seen = new Set<string>();
+
+  try {
+    const glob = new Bun.Glob("**/*.partial.{ts,tsx}");
+    for await (const rel of glob.scan({ cwd: rootDir, absolute: true })) {
+      if (rel.includes(`${path.sep}node_modules${path.sep}`)) continue;
+      if (rel.includes(`${path.sep}.mandu${path.sep}`)) continue;
+
+      const filePath = path.resolve(rel);
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+
+      const base = path.basename(filePath).replace(/\.partial\.tsx?$/, "");
+      entries.push({
+        name: normalizeClientEntryName(base),
+        filePath,
+        priority: HYDRATION.DEFAULT_PRIORITY,
+      });
+    }
+  } catch {
+    // Bun.Glob unavailable or scan failed — a missing partial bundle should
+    // not prevent route-level islands from building.
+  }
+
+  return entries.sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+
+/** @internal test helper */
+export const _testOnly_scanPartialFiles = scanPartialFiles;
 
 /**
  * Test-only accessor for the hydrated-routes filter. Mirrors the rationale
@@ -214,49 +255,42 @@ export const _testOnly_getHydratedRoutes = getHydratedRoutes;
  * Paths are absolute and deduplicated. Returns `[]` when the manifest
  * has no hydrated routes.
  */
-export async function collectCompilerLintTargets(
-  manifest: RoutesManifest,
-  rootDir: string,
-): Promise<string[]> {
-  const hydratedRoutes = getHydratedRoutes(manifest);
-  if (hydratedRoutes.length === 0) return [];
-
-  const out = new Set<string>();
-
-  // 1) Islands (reuses the bundler's canonical scanner).
-  const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
-  for (const entry of islandFiles) {
-    out.add(path.resolve(entry.filePath));
-  }
-
-  // 2) `"use client"` page modules — the hydrated-route filter
-  //    already asserted `clientModule` exists.
-  for (const route of hydratedRoutes) {
-    const rel = route.clientModule ?? route.module;
-    if (rel) out.add(path.resolve(rootDir, rel));
-  }
-
-  // 3) Partials — glob the whole project once. Partials live anywhere
-  //    the user chooses, they're not sibling-scoped like islands.
-  try {
-    const glob = new Bun.Glob("**/*.partial.{ts,tsx}");
-    for await (const rel of glob.scan({ cwd: rootDir, absolute: true })) {
-      if (rel.includes(`${path.sep}node_modules${path.sep}`)) continue;
-      if (rel.includes(`${path.sep}.mandu${path.sep}`)) continue;
-      out.add(path.resolve(rel));
-    }
-  } catch {
-    // Bun.Glob unavailable or scan failed — skip partials rather than
-    // aborting the whole diagnostic run.
-  }
-
-  return Array.from(out).sort();
-}
+export async function collectCompilerLintTargets(
+  manifest: RoutesManifest,
+  rootDir: string,
+): Promise<string[]> {
+  const hydratedRoutes = getHydratedRoutes(manifest);
+
+  const out = new Set<string>();
+
+  // 1) Islands (reuses the bundler's canonical scanner).
+  if (hydratedRoutes.length > 0) {
+    const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
+    for (const entry of islandFiles) {
+      out.add(path.resolve(entry.filePath));
+    }
+
+    // 2) `"use client"` page modules — the hydrated-route filter
+    //    already asserted `clientModule` exists.
+    for (const route of hydratedRoutes) {
+      const rel = route.clientModule ?? route.module;
+      if (rel) out.add(path.resolve(rootDir, rel));
+    }
+  }
+
+  // 3) Partials — glob the whole project once. Partials live anywhere
+  //    the user chooses, they're not sibling-scoped like islands.
+  for (const entry of await scanPartialFiles(rootDir)) {
+    out.add(path.resolve(entry.filePath));
+  }
+
+  return Array.from(out).sort();
+}
 
 /** Build a single per-island bundle. */
-async function buildPerIslandBundle(
-  entry: IslandFileEntry, outDir: string, options: BundlerOptions
-): Promise<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> {
+async function buildPerIslandBundle(
+  entry: IslandFileEntry, outDir: string, options: BundlerOptions
+): Promise<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> {
   const entryPath = path.join(outDir, `_entry_island_${entry.name}.js`);
   const outputName = `${entry.name}.island.js`;
   // Phase 7.1 B-1/B-4: wire Bun's native React Fast Refresh transform +
@@ -285,9 +319,66 @@ async function buildPerIslandBundle(
     return { name: entry.name, js: `/.mandu/client/${outputName}`, route: entry.routeId, priority: entry.priority };
   } catch (error) {
     await fs.unlink(entryPath).catch(() => {});
-    throw error;
-  }
-}
+    throw error;
+  }
+}
+
+interface PartialBundleBuild {
+  name: string;
+  js: string;
+  priority: PartialFileEntry["priority"];
+  size: number;
+  gzipSize: number;
+}
+
+/** Build a single inline partial bundle. */
+async function buildPartialBundle(
+  entry: PartialFileEntry,
+  outDir: string,
+  options: BundlerOptions,
+): Promise<PartialBundleBuild> {
+  const entryPath = path.join(outDir, `_entry_partial_${entry.name}.js`);
+  const outputName = `${entry.name}.partial.js`;
+  const isDev = isDevelopmentBuild(options);
+
+  try {
+    await Bun.write(entryPath, generatePartialEntry(entry.name, entry.filePath));
+    const result = await safeBuild({
+      entrypoints: [entryPath],
+      outdir: outDir,
+      naming: outputName,
+      minify: shouldMinify(options),
+      sourcemap: options.sourcemap ? "external" : "none",
+      target: "browser",
+      ...(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(`Partial build failed for '${entry.name}' (source: ${entry.filePath}):\n${grouped}\n  Hint: Export a Mandu partial from this file with \`partial({ component })\`.`);
+    }
+
+    const outputPath = path.join(outDir, outputName);
+    const outputFile = Bun.file(outputPath);
+    const content = await outputFile.text();
+    const gzipped = Bun.gzipSync(Buffer.from(content));
+
+    return {
+      name: entry.name,
+      js: `/.mandu/client/${outputName}`,
+      priority: entry.priority,
+      size: outputFile.size,
+      gzipSize: gzipped.length,
+    };
+  } catch (error) {
+    await fs.unlink(entryPath).catch(() => {});
+    throw error;
+  }
+}
 
 /**
  * 빈 매니페스트 생성
@@ -413,12 +504,31 @@ function generateRuntimeSource(): string {
 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 getServerData = (id) => (window.__MANDU_DATA__ || {})[id]?.serverData || {};
+// Hydrated roots 추적 (unmount용) - 전역 초기화
+window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
+const hydratedRoots = window.__MANDU_ROOTS__;
+
+// 서버 데이터
+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__ = JSON.parse(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 || {};
 
 /**
  * Error Boundary 컴포넌트 (Class Component)
@@ -632,12 +742,16 @@ async function loadAndHydrate(element, src) {
     const island = module.default;
     let data = getServerData(id);
 
-    // Fallback: read data-props from child element if __MANDU_DATA__ is empty
-    if (!data || Object.keys(data).length === 0) {
-      const propsEl = element.querySelector('[data-props]');
-      if (propsEl) {
-        try {
-          data = JSON.parse(propsEl.getAttribute('data-props'));
+    // Fallback: read data-props from the island root or a child element if
+    // __MANDU_DATA__ is empty. Inline partials put their serialized props on
+    // the root marker itself.
+    if (!data || Object.keys(data).length === 0) {
+      const propsEl = element.hasAttribute('data-props')
+        ? element
+        : element.querySelector('[data-props]');
+      if (propsEl) {
+        try {
+          data = JSON.parse(propsEl.getAttribute('data-props'));
         } catch (e) {
           console.warn('[Mandu] Failed to parse data-props fallback:', e);
         }
@@ -1311,22 +1425,63 @@ async function buildRouterRuntime(
  * - Runtime이 dynamic import로 로드
  * - 등록/초기화 코드 없음
  */
-function generateIslandEntry(routeId: string, clientModulePath: string): string {
-  // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
-  const normalizedPath = clientModulePath.replace(/\\/g, "/");
-  return `
+function generateIslandEntry(routeId: string, clientModulePath: string): string {
+  // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
+  const normalizedPath = clientModulePath.replace(/\\/g, "/");
+  return `
 /**
  * Mandu Island: ${routeId} (Generated)
  * Pure export - no side effects
  */
 import island from "${normalizedPath}";
-export default island;
-`;
-}
-
-/**
- * Runtime 번들 빌드
- */
+export default island;
+`;
+}
+
+function generatePartialEntry(partialId: string, partialModulePath: string): string {
+  const normalizedPath = partialModulePath.replace(/\\/g, "/");
+  return `
+/**
+ * Mandu Partial: ${partialId} (Generated)
+ * Exports a runtime-compatible island wrapper around a compiled partial.
+ */
+import React from "react";
+import * as partialModule from "${normalizedPath}";
+
+function findPartial(mod) {
+  if (mod.default && mod.default.__mandu_partial === true) return mod.default;
+  for (const value of Object.values(mod)) {
+    if (value && value.__mandu_partial === true) return value;
+  }
+  throw new Error("[Mandu Partial] ${partialId} must export a value returned by partial({ component })");
+}
+
+const partial = findPartial(partialModule);
+const definition = partial.definition;
+const component = definition.component;
+
+export default {
+  __mandu_island: true,
+  definition: {
+    setup(serverData) {
+      if (serverData && typeof serverData === "object" && Object.keys(serverData).length > 0) {
+        return serverData;
+      }
+      return definition.initialProps || {};
+    },
+    render(props) {
+      return React.createElement(component, props);
+    },
+    errorBoundary: definition.errorBoundary,
+    loading: definition.loading,
+  },
+};
+`;
+}
+
+/**
+ * Runtime 번들 빌드
+ */
 async function buildRuntime(
   outDir: string,
   options: BundlerOptions
@@ -1810,15 +1965,16 @@ async function buildIsland(
 /**
  * 번들 매니페스트 생성
  */
-function createBundleManifest(
-  outputs: BundleOutput[],
-  routes: RouteSpec[],
-  runtimePath: string,
-  vendorResult: VendorBuildResult,
-  routerPath: string,
-  env: "development" | "production",
-  islandBundles?: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }>
-): BundleManifest {
+function createBundleManifest(
+  outputs: BundleOutput[],
+  routes: RouteSpec[],
+  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 {
   const bundles: BundleManifest["bundles"] = {};
 
   for (const output of outputs) {
@@ -1834,16 +1990,27 @@ function createBundleManifest(
 
   // Per-island bundles (code splitting)
   let islands: BundleManifest["islands"];
-  if (islandBundles && islandBundles.length > 0) {
-    islands = {};
-    for (const ib of islandBundles) {
-      islands[ib.name] = {
-        js: ib.js,
+  if (islandBundles && islandBundles.length > 0) {
+    islands = {};
+    for (const ib of islandBundles) {
+      islands[ib.name] = {
+        js: ib.js,
         route: ib.route,
         priority: ib.priority,
-      };
-    }
-  }
+      };
+    }
+  }
+
+  let partials: BundleManifest["partials"];
+  if (partialBundles && partialBundles.length > 0) {
+    partials = {};
+    for (const partial of partialBundles) {
+      partials[partial.name] = {
+        js: partial.js,
+        priority: partial.priority,
+      };
+    }
+  }
 
   // Phase 7.1 B-2: expose Fast Refresh dev bundles so the HTML
   // preamble can inject a dynamic import pointing at them. Only
@@ -1859,10 +2026,11 @@ function createBundleManifest(
   return {
     version: 1,
     buildTime: new Date().toISOString(),
-    env,
-    bundles,
-    ...(islands ? { islands } : {}),
-    shared: {
+    env,
+    bundles,
+    ...(islands ? { islands } : {}),
+    ...(partials ? { partials } : {}),
+    shared: {
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
       router: routerPath, // Client-side Router
@@ -1883,28 +2051,32 @@ function createBundleManifest(
 /**
  * 번들 통계 계산
  */
-function calculateStats(outputs: BundleOutput[], startTime: number): BundleStats {
-  let totalSize = 0;
-  let totalGzipSize = 0;
-  let largestBundle = { routeId: "", size: 0 };
-
-  for (const output of outputs) {
-    totalSize += output.size;
-    totalGzipSize += output.gzipSize;
-
-    if (output.size > largestBundle.size) {
-      largestBundle = { routeId: output.routeId, size: output.size };
+function calculateStats(
+  outputs: BundleOutput[],
+  startTime: number,
+  extraOutputs: Array<{ routeId: string; size: number; gzipSize: number }> = [],
+): BundleStats {
+  let totalSize = 0;
+  let totalGzipSize = 0;
+  let largestBundle = { routeId: "", size: 0 };
+
+  for (const output of [...outputs, ...extraOutputs]) {
+    totalSize += output.size;
+    totalGzipSize += output.gzipSize;
+
+    if (output.size > largestBundle.size) {
+      largestBundle = { routeId: output.routeId, size: output.size };
     }
   }
 
   return {
     totalSize,
-    totalGzipSize,
-    largestBundle,
-    buildTime: performance.now() - startTime,
-    bundleCount: outputs.length,
-  };
-}
+    totalGzipSize,
+    largestBundle,
+    buildTime: performance.now() - startTime,
+    bundleCount: outputs.length + extraOutputs.length,
+  };
+}
 
 /**
  * 클라이언트 번들 빌드
@@ -1950,8 +2122,24 @@ export async function buildClientBundles(
   };
   const env = resolveBundlerMode(options);
 
-  // 1. Hydration이 필요한 라우트 필터링
-  const hydratedRoutes = getHydratedRoutes(manifest);
+  // 1. Hydration이 필요한 라우트 필터링
+  const invalidClientRouteIds = new Set<string>();
+  let hydratedRoutes = getHydratedRoutes(manifest);
+  if (hydratedRoutes.length > 0) {
+    const validRoutes: RouteSpec[] = [];
+    for (const route of hydratedRoutes) {
+      const validationError = await validateClientModuleForBrowserBundle(route, rootDir);
+      if (validationError) {
+        invalidClientRouteIds.add(route.id);
+        errors.push(validationError);
+        continue;
+      }
+      validRoutes.push(route);
+    }
+    hydratedRoutes = validRoutes;
+  }
+  const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
+  const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
 
   // 2. 출력 디렉토리 생성 (항상 필요 - 매니페스트 저장용)
   const outDir = resolveClientOutDir(rootDir, options.outDir);
@@ -1959,9 +2147,9 @@ export async function buildClientBundles(
 
   // Hydration 라우트가 없어도 빈 매니페스트를 저장해야 함
   // (이전 빌드의 stale 매니페스트 참조 방지)
-  if (hydratedRoutes.length === 0) {
+  if (hydratedRoutes.length === 0 && partialFiles.length === 0) {
     // #185: skipFrameworkBundles 모드에서는 기존 manifest를 그대로 유지 (devtools 재빌드도 스킵)
-    if (options.skipFrameworkBundles) {
+    if (options.skipFrameworkBundles && errors.length === 0) {
       const manifestPath = path.join(rootDir, ".mandu/manifest.json");
       try {
         const manifestRaw = await fs.readFile(manifestPath, "utf-8");
@@ -2012,11 +2200,11 @@ export async function buildClientBundles(
       path.join(rootDir, ".mandu/manifest.json"),
       JSON.stringify(emptyManifest, null, 2)
     );
-    return {
-      success: true,
-      outputs: [],
-      errors: [],
-      manifest: emptyManifest,
+    return {
+      success: errors.length === 0,
+      outputs: [],
+      errors,
+      manifest: emptyManifest,
       stats: {
         totalSize: 0,
         totalGzipSize: 0,
@@ -2055,11 +2243,14 @@ export async function buildClientBundles(
       return buildClientBundles(manifest, rootDir, { ...options, targetRouteIds: undefined });
     }
 
-    // Only update manifest with successfully built outputs (#10: preserve previous good manifest on failure)
-    if (outputs.length > 0) {
-      for (const output of outputs) {
-        if (existingManifest.bundles[output.routeId]) {
-          existingManifest.bundles[output.routeId].js = output.outputPath;
+    // Only update manifest with successfully built outputs (#10: preserve previous good manifest on failure)
+    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;
@@ -2071,11 +2262,11 @@ export async function buildClientBundles(
         }
       }
 
-      await fs.writeFile(
-        path.join(rootDir, ".mandu/manifest.json"),
-        JSON.stringify(existingManifest, null, 2)
-      );
-    }
+      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);
@@ -2111,9 +2302,13 @@ export async function buildClientBundles(
         "[Mandu] Existing manifest missing required fields (shared/bundles), falling back to full build",
       );
       return buildClientBundles(manifest, rootDir, { ...options, skipFrameworkBundles: false });
-    }
-
-    // Pre-build validation + 병렬 island 빌드 (framework 번들은 스킵)
+    }
+
+    for (const routeId of invalidClientRouteIds) {
+      delete existingManifest.bundles[routeId];
+    }
+
+    // Pre-build validation + 병렬 island 빌드 (framework 번들은 스킵)
     for (const route of hydratedRoutes) {
       if (!route.clientModule) continue;
       const clientModulePath = path.join(rootDir, route.clientModule);
@@ -2178,25 +2373,62 @@ export async function buildClientBundles(
         };
       }
     }
-    if (perIslandBundles.length > 0) {
-      existingManifest.islands = existingManifest.islands || {};
-      for (const ib of perIslandBundles) {
-        existingManifest.islands[ib.name] = {
-          js: ib.js,
+    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,
-        };
-      }
-    }
-
-    await fs.writeFile(
-      path.join(rootDir, ".mandu/manifest.json"),
-      JSON.stringify(existingManifest, null, 2),
-    );
-
-    const stats = calculateStats(outputs, startTime);
-    return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
-  }
+        };
+      }
+    }
+
+    const partialBundles: PartialBundleBuild[] = [];
+    if (partialFiles.length > 0) {
+      const partialResults = await Promise.all(
+        partialFiles.map(async (entry) => {
+          try {
+            return await buildPartialBundle(entry, outDir, options);
+          } catch (error) {
+            errors.push(`[partial:${entry.name}] ${String(error)}`);
+            return null;
+          }
+        }),
+      );
+      for (const result of partialResults) {
+        if (result) partialBundles.push(result);
+      }
+    }
+    if (partialFiles.length > 0 || existingManifest.partials) {
+      existingManifest.partials = {};
+      for (const partial of partialBundles) {
+        existingManifest.partials[partial.name] = {
+          js: partial.js,
+          priority: partial.priority,
+        };
+      }
+      if (Object.keys(existingManifest.partials).length === 0) {
+        delete existingManifest.partials;
+      }
+    }
+
+    await fs.writeFile(
+      path.join(rootDir, ".mandu/manifest.json"),
+      JSON.stringify(existingManifest, null, 2),
+    );
+
+    const stats = calculateStats(
+      outputs,
+      startTime,
+      partialBundles.map((partial) => ({
+        routeId: `partial:${partial.name}`,
+        size: partial.size,
+        gzipSize: partial.gzipSize,
+      })),
+    );
+    return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
+  }
 
   // 3-4. Runtime, Router, Vendor, DevTools 번들 병렬 빌드 (서로 독립적)
   const isDev = env === "development";
@@ -2282,11 +2514,11 @@ export async function buildClientBundles(
   const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
   const islandBundles: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> = [];
 
-  if (islandFiles.length > 0) {
-    const islandResults = await Promise.all(
-      islandFiles.map(async (entry) => {
-        try {
-          return await buildPerIslandBundle(entry, outDir, options);
+  if (islandFiles.length > 0) {
+    const islandResults = await Promise.all(
+      islandFiles.map(async (entry) => {
+        try {
+          return await buildPerIslandBundle(entry, outDir, options);
         } catch (error) {
           errors.push(`[island:${entry.name}] ${String(error)}`);
           return null;
@@ -2294,20 +2526,38 @@ export async function buildClientBundles(
       })
     );
     for (const result of islandResults) {
-      if (result) islandBundles.push(result);
-    }
-  }
-
-  // 6. 번들 매니페스트 생성
-  const bundleManifest = createBundleManifest(
-    outputs,
-    hydratedRoutes,
-    runtimeResult.outputPath,
-    vendorResult,
-    routerResult.outputPath,
-    env,
-    islandBundles
-  );
+      if (result) islandBundles.push(result);
+    }
+  }
+
+  const partialBundles: PartialBundleBuild[] = [];
+  if (partialFiles.length > 0) {
+    const partialResults = await Promise.all(
+      partialFiles.map(async (entry) => {
+        try {
+          return await buildPartialBundle(entry, outDir, options);
+        } catch (error) {
+          errors.push(`[partial:${entry.name}] ${String(error)}`);
+          return null;
+        }
+      }),
+    );
+    for (const result of partialResults) {
+      if (result) partialBundles.push(result);
+    }
+  }
+
+  // 6. 번들 매니페스트 생성
+  const bundleManifest = createBundleManifest(
+    outputs,
+    hydratedRoutes,
+    runtimeResult.outputPath,
+    vendorResult,
+    routerResult.outputPath,
+    env,
+    islandBundles,
+    partialBundles,
+  );
 
   await fs.writeFile(
     path.join(rootDir, ".mandu/manifest.json"),
@@ -2315,7 +2565,15 @@ export async function buildClientBundles(
   );
 
   // 7. 통계 계산
-  const stats = calculateStats(outputs, startTime);
+  const stats = calculateStats(
+    outputs,
+    startTime,
+    partialBundles.map((partial) => ({
+      routeId: `partial:${partial.name}`,
+      size: partial.size,
+      gzipSize: partial.gzipSize,
+    })),
+  );
 
   // Phase 18.τ — fire onBundleComplete(stats) before return.
   await fireOnBundleComplete(stats);
@@ -2343,13 +2601,14 @@ export function formatSize(bytes: number): string {
  * 번들 결과 요약 출력
  */
 export function printBundleStats(result: BundleResult): void {
-  console.log("\n📦 Mandu Client Bundles");
-  console.log("=".repeat(50));
-
-  if (result.outputs.length === 0) {
-    console.log("No islands to bundle (hydration: none or no clientModule)");
-    return;
-  }
+  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)");
+    return;
+  }
 
   console.log(`Environment: ${result.manifest.env}`);
   console.log(`Bundles: ${result.stats.bundleCount}`);
@@ -2358,12 +2617,15 @@ export function printBundleStats(result: BundleResult): void {
   console.log(`Build Time: ${result.stats.buildTime.toFixed(0)}ms`);
   console.log("");
 
-  // 각 번들 정보
-  for (const output of result.outputs) {
-    console.log(
-      `  ${output.routeId}: ${formatSize(output.size)} (gzip: ${formatSize(output.gzipSize)})`
-    );
-  }
+  // 각 번들 정보
+  for (const output of result.outputs) {
+    console.log(
+      `  ${output.routeId}: ${formatSize(output.size)} (gzip: ${formatSize(output.gzipSize)})`
+    );
+  }
+  if (partialCount > 0) {
+    console.log(`  Partials: ${partialCount}`);
+  }
 
   if (result.errors.length > 0) {
     console.log("\n⚠️ Errors:");