@mandujs/core 0.20.10 → 0.22.0

package/src/bundler/build.ts

@@ -14,15 +14,52 @@ import type {
   IslandFileEntry,
 } from "./types";
 import { HYDRATION } from "../constants";
+import { safeBuild } from "./safe-build";
+import { fastRefreshPlugin } from "./fast-refresh-plugin";
+import { mark, measure } from "../perf";
+import { HMR_PERF } from "../perf/hmr-markers";
+import {
+  readVendorCache,
+  writeVendorCache,
+  restoreVendorCache,
+  resolveVendorCacheKeys,
+  type VendorCacheKeyInput,
+  type VendorCacheWriteEntry,
+} from "./vendor-cache";
 import path from "path";
 import fs from "fs/promises";
 
-/** Scan for *.island.tsx / *.island.ts files across hydrated route directories. */
+/**
+ * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
+ *
+ * Phase 7.1 R1 Agent C — per-island conditional skip defence.
+ *
+ * Callers (the two `buildClientBundles` paths at L1643 and L1817) feed us
+ * `hydratedRoutes` (from `getHydratedRoutes`), which already filters for
+ * `route.kind === "page" && route.clientModule && needsHydration(route)`.
+ * We re-assert the `needsHydration` predicate here for two reasons:
+ *
+ *   1. Defence-in-depth — if a future caller forgets the filter, we still
+ *      skip routes with `hydration.strategy === "none"`. Each skipped route
+ *      saves one `fs.readdir` + O(files) regex matches (~1-2 ms on Windows
+ *      NTFS per skipped dir, per diagnostic R0.3).
+ *
+ *   2. Cold-start regression guard — the R0 → R3 F breakdown attributes
+ *      +40-80 ms of cold start to per-island splitting (commit b503c36).
+ *      The unit test `per-island-scan-skips-non-hydrated` pins this so a
+ *      refactor cannot silently re-introduce the scan overhead for routes
+ *      that opt out of hydration.
+ */
 async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<IslandFileEntry[]> {
   const entries: IslandFileEntry[] = [];
   const seenDirs = new Set<string>();
 
   for (const route of routes) {
+    // Defensive guard — see the block comment above for rationale. Without
+    // this, a hypothetical caller passing `manifest.routes` directly would
+    // readdir every page route, including pure-SSR ones.
+    if (!needsHydration(route)) continue;
+
     const dir = path.dirname(path.join(rootDir, route.componentModule ?? route.module));
     if (seenDirs.has(dir)) continue;
     seenDirs.add(dir);
@@ -45,21 +82,46 @@ async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<Is
   return entries;
 }
 
+/**
+ * Test-only accessor for the island-file scanner. Allows the cold-start
+ * test suite (`__tests__/cold-start.test.ts`) to assert the per-island
+ * conditional skip without having to spin up a full `buildClientBundles`
+ * invocation (which would also run `safeBuild`).
+ *
+ * @internal
+ */
+export const _testOnly_scanIslandFiles = scanIslandFiles;
+
+/**
+ * Test-only accessor for the hydrated-routes filter. Mirrors the rationale
+ * above — lets tests verify that `getHydratedRoutes` really does drop
+ * `hydration.strategy: "none"` routes without rebuilding its logic.
+ *
+ * @internal
+ */
+export const _testOnly_getHydratedRoutes = getHydratedRoutes;
+
 /** 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"] }> {
   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 +
+  // Mandu's boundary injection plugin — but only in dev. Production
+  // bundles stay clean of `$RefreshReg$` / `$RefreshSig$` stubs.
+  const isDev = (options.minify ?? process.env.NODE_ENV === "production") === false;
   try {
     await Bun.write(entryPath, generateIslandEntry(entry.name, entry.filePath));
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [entryPath],
       outdir: outDir,
       naming: outputName,
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      ...(isDev ? { reactFastRefresh: true } : {}),
+      plugins: isDev ? [fastRefreshPlugin()] : [],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
@@ -971,7 +1033,7 @@ if (typeof window !== 'undefined') {
   try {
     await Bun.write(srcPath, source);
 
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [srcPath],
       outdir: outDir,
       naming: outputName,
@@ -1025,7 +1087,7 @@ async function buildRouterRuntime(
   try {
     await Bun.write(routerPath, generateRouterRuntimeSource());
 
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [routerPath],
       outdir: outDir,
       naming: outputName,
@@ -1100,7 +1162,7 @@ async function buildRuntime(
     await Bun.write(runtimePath, generateRuntimeSource());
 
     // 빌드
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [runtimePath],
       outdir: outDir,
       naming: outputName,
@@ -1161,38 +1223,216 @@ interface VendorBuildResult {
   reactDomClient: string;
   jsxRuntime: string;
   jsxDevRuntime: string;
+  /**
+   * Phase 7.1 B-2: bundled `react-refresh/runtime` — emitted ONLY in
+   * dev mode. Empty string in production. Consumed by the HTML
+   * preamble (`bundler/dev.ts`) via a dynamic import.
+   */
+  reactRefreshRuntime: string;
+  /**
+   * Phase 7.1 B-2: Mandu's `__MANDU_HMR__` glue module — also dev-only.
+   * Imported once by the HTML preamble which then calls `installGlobal`
+   * with the already-loaded refresh runtime.
+   */
+  fastRefreshRuntime: string;
   errors: string[];
 }
 
+/**
+ * Phase 7.1 B-2 — source generator for the `react-refresh/runtime` shim.
+ *
+ * The shim simply re-exports the upstream module under a default export
+ * that `fast-refresh-runtime.ts`'s `installGlobal({ runtimeImport })`
+ * can consume. Mirrors the pattern Vite uses for its `/@react-refresh`
+ * endpoint.
+ */
+function generateReactRefreshRuntimeShimSource(): string {
+  return `
+/**
+ * Mandu React Refresh Runtime Shim (Generated, dev-only)
+ * Re-exports the upstream react-refresh/runtime so the bundler can
+ * pre-bundle it without leaking the CommonJS entry into the app graph.
+ */
+import * as Runtime from 'react-refresh/runtime';
+export const injectIntoGlobalHook = Runtime.injectIntoGlobalHook;
+export const register = Runtime.register;
+export const createSignatureFunctionForTransform = Runtime.createSignatureFunctionForTransform;
+export const performReactRefresh = Runtime.performReactRefresh;
+export default {
+  injectIntoGlobalHook,
+  register,
+  createSignatureFunctionForTransform,
+  performReactRefresh,
+};
+`;
+}
+
+/**
+ * Phase 7.1 B-2 — source generator for the Mandu Fast Refresh glue.
+ *
+ * This re-exports `installGlobal` / `manduHMR` / helpers from
+ * `runtime/fast-refresh-runtime.ts`. By routing through a generated
+ * shim we keep the absolute path to core resolved once at build time
+ * (same pattern as `_devtools.js`).
+ */
+function generateFastRefreshRuntimeShimSource(): string {
+  const runtimePath = path
+    .resolve(import.meta.dir, "..", "runtime", "fast-refresh-runtime.ts")
+    .replace(/\\/g, "/");
+  return `
+/**
+ * Mandu Fast Refresh Runtime Shim (Generated, dev-only)
+ * Wires the react-refresh runtime to window.__MANDU_HMR__.
+ */
+export * from "${runtimePath}";
+import { installGlobal } from "${runtimePath}";
+export { installGlobal };
+`;
+}
+
 /**
  * Vendor shim 번들 빌드
  * React, ReactDOM, ReactDOMClient를 각각의 shim으로 빌드
+ *
+ * Phase 7.2.S2: caches the built shim outputs on disk under
+ * `.mandu/vendor-cache/` keyed by Bun + React + ReactDOM + react-refresh +
+ * @mandujs/core versions. Warm boots reuse the cached files instead of
+ * re-running Bun.build, eliminating ~80-120 ms from cold start.
  */
 async function buildVendorShims(
+  rootDir: string,
   outDir: string,
   options: BundlerOptions
 ): Promise<VendorBuildResult> {
   const errors: string[] = [];
-  type VendorShimKey = "react" | "reactDom" | "reactDomClient" | "jsxRuntime" | "jsxDevRuntime";
+  type VendorShimKey =
+    | "react"
+    | "reactDom"
+    | "reactDomClient"
+    | "jsxRuntime"
+    | "jsxDevRuntime"
+    | "reactRefreshRuntime"
+    | "fastRefreshRuntime";
   const results: Record<VendorShimKey, string> = {
     react: "",
     reactDom: "",
     reactDomClient: "",
     jsxRuntime: "",
     jsxDevRuntime: "",
+    reactRefreshRuntime: "",
+    fastRefreshRuntime: "",
   };
 
-  const shims: Array<{ name: string; source: string; key: VendorShimKey }> = [
-    { name: "_react", source: generateReactShimSource(), key: "react" },
-    { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom" },
-    { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient" },
-    { name: "_jsx-runtime", source: generateJsxRuntimeShimSource(), key: "jsxRuntime" },
-    { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime" },
+  // Phase 7.1 B-2: dev-only Fast Refresh shims. In production we skip
+  // them entirely so `react-refresh/runtime` is never bundled and the
+  // attack surface / bundle size regressions stay zero for deploys.
+  const isDev =
+    (options.minify ?? process.env.NODE_ENV === "production") === false;
+
+  const shims: Array<{ name: string; source: string; key: VendorShimKey; cacheId: string }> = [
+    { name: "_react", source: generateReactShimSource(), key: "react", cacheId: "react" },
+    { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom", cacheId: "react-dom" },
+    { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient", cacheId: "react-dom-client" },
+    { name: "_jsx-runtime", source: generateJsxRuntimeShimSource(), key: "jsxRuntime", cacheId: "jsx-runtime" },
+    { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime", cacheId: "jsx-dev-runtime" },
   ];
+  if (isDev) {
+    shims.push(
+      {
+        name: "_vendor-react-refresh",
+        source: generateReactRefreshRuntimeShimSource(),
+        key: "reactRefreshRuntime",
+        cacheId: "react-refresh-runtime",
+      },
+      {
+        name: "_fast-refresh-runtime",
+        source: generateFastRefreshRuntimeShimSource(),
+        key: "fastRefreshRuntime",
+        cacheId: "fast-refresh-glue",
+      },
+    );
+  }
+
+  // Phase 7.2.S2 — Tier 2 disk cache consultation. Production builds
+  // (non-dev, minified) still rebuild fresh because (a) the shim set is
+  // smaller (no fast-refresh) and (b) production is one-shot — there's no
+  // warm workflow to amortize the cache cost against. Dev warm restarts
+  // are where the cache pays off.
+  //
+  // `MANDU_VENDOR_CACHE=0` disables the cache (escape hatch for debugging
+  // cache-invalidation bugs without touching code).
+  const cacheEnabled = isDev && process.env.MANDU_VENDOR_CACHE !== "0";
+  let cacheKeys: VendorCacheKeyInput | null = null;
+
+  if (cacheEnabled) {
+    try {
+      cacheKeys = await resolveVendorCacheKeys(rootDir);
+      const hitOrMiss = await readVendorCache(rootDir, cacheKeys);
+
+      if (hitOrMiss.kind === "hit") {
+        // Attempt to restore every shim file to outDir.
+        const restored = await restoreVendorCache(
+          rootDir,
+          hitOrMiss.manifest,
+          outDir,
+        );
+        if (restored !== null) {
+          // Map the restored files into the result shape. If a shim is
+          // not in the manifest (eg. an older cache from before we added
+          // fast-refresh) we rebuild just that one — but the simpler
+          // policy is to require the manifest to cover every entry the
+          // current shim list wants, so we only accept hits that include
+          // everything. Otherwise fall through to rebuild.
+          const expected = new Set(shims.map((s) => s.cacheId));
+          const present = new Set(restored.keys());
+          let allPresent = true;
+          for (const id of expected) {
+            if (!present.has(id)) {
+              allPresent = false;
+              break;
+            }
+          }
+          if (allPresent) {
+            // Populate result + return. Every shim's outputPath references
+            // the freshly-restored file in `outDir`.
+            for (const shim of shims) {
+              const dst = restored.get(shim.cacheId);
+              if (dst) {
+                const fileName = path.basename(dst);
+                results[shim.key] = `/.mandu/client/${fileName}`;
+              }
+            }
+            mark(HMR_PERF.VENDOR_CACHE_HIT);
+            measure(HMR_PERF.VENDOR_CACHE_HIT, HMR_PERF.VENDOR_CACHE_HIT);
+            return {
+              success: true,
+              react: results.react,
+              reactDom: results.reactDom,
+              reactDomClient: results.reactDomClient,
+              jsxRuntime: results.jsxRuntime,
+              jsxDevRuntime: results.jsxDevRuntime,
+              reactRefreshRuntime: results.reactRefreshRuntime,
+              fastRefreshRuntime: results.fastRefreshRuntime,
+              errors,
+            };
+          }
+          // Restored but missing one of the expected shims — fall through.
+        }
+        // Restore failed — fall through to rebuild.
+      }
+
+      // Miss / failed restore: record the miss marker for perf logs.
+      mark(HMR_PERF.VENDOR_CACHE_MISS);
+      measure(HMR_PERF.VENDOR_CACHE_MISS, HMR_PERF.VENDOR_CACHE_MISS);
+    } catch {
+      // Any cache failure falls through to the full rebuild path — cache
+      // is strictly an optimisation.
+    }
+  }
 
   const buildShim = async (
-    shim: { name: string; source: string; key: VendorShimKey }
-  ): Promise<{ key: VendorShimKey; outputPath?: string; error?: string }> => {
+    shim: { name: string; source: string; key: VendorShimKey; cacheId: string }
+  ): Promise<{ key: VendorShimKey; cacheId: string; outputName?: string; outputPath?: string; error?: string }> => {
     const srcPath = path.join(outDir, `${shim.name}.src.js`);
     const outputName = `${shim.name}.js`;
 
@@ -1207,8 +1447,11 @@ async function buildVendorShims(
       } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
         shimExternal = ["react"];
       }
+      // `_vendor-react-refresh` and `_fast-refresh-runtime` are
+      // self-contained: we WANT react-refresh bundled in so the
+      // preamble's single dynamic import pulls the whole graph.
 
-      const result = await Bun.build({
+      const result = await safeBuild({
         entrypoints: [srcPath],
         outdir: outDir,
         naming: outputName,
@@ -1228,32 +1471,57 @@ async function buildVendorShims(
         const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
         return {
           key: shim.key,
+          cacheId: shim.cacheId,
           error: `Vendor shim '${shim.name}' build failed (source: ${srcPath}):\n${grouped}\n  Hint: Check the import paths and ensure the vendor package is installed.`,
         };
       }
 
       return {
         key: shim.key,
+        cacheId: shim.cacheId,
+        outputName,
         outputPath: `/.mandu/client/${outputName}`,
       };
     } catch (error) {
       await fs.unlink(srcPath).catch(() => {});
       return {
         key: shim.key,
+        cacheId: shim.cacheId,
         error: `[${shim.name}] ${String(error)}`,
       };
     }
   };
 
   const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
+  const writeEntries: VendorCacheWriteEntry[] = [];
   for (const result of buildResults) {
     if (result.error) {
       errors.push(result.error);
-    } else if (result.outputPath) {
+    } else if (result.outputPath && result.outputName) {
       results[result.key] = result.outputPath;
+      writeEntries.push({
+        logicalId: result.cacheId,
+        absPath: path.join(outDir, result.outputName),
+      });
     }
   }
 
+  // Phase 7.2.S2 — persist freshly-built shims for next boot. Best-effort;
+  // a write failure is logged via perf markers (opt-in) but never breaks
+  // the build. Only write when every shim succeeded — partial manifests
+  // would still satisfy the expected-set check on next boot but we
+  // prefer writing only complete manifests.
+  if (cacheEnabled && cacheKeys && errors.length === 0 && writeEntries.length > 0) {
+    // Fire-and-forget so the fast path isn't blocked on disk. The
+    // returned VendorBuildResult does not depend on the write outcome.
+    mark(HMR_PERF.VENDOR_CACHE_WRITE);
+    void writeVendorCache(rootDir, cacheKeys, writeEntries)
+      .then(() => {
+        measure(HMR_PERF.VENDOR_CACHE_WRITE, HMR_PERF.VENDOR_CACHE_WRITE);
+      })
+      .catch(() => {});
+  }
+
   return {
     success: errors.length === 0,
     react: results.react,
@@ -1261,6 +1529,8 @@ async function buildVendorShims(
     reactDomClient: results.reactDomClient,
     jsxRuntime: results.jsxRuntime,
     jsxDevRuntime: results.jsxDevRuntime,
+    reactRefreshRuntime: results.reactRefreshRuntime,
+    fastRefreshRuntime: results.fastRefreshRuntime,
     errors,
   };
 }
@@ -1278,13 +1548,17 @@ async function buildIsland(
   const entryPath = path.join(outDir, `_entry_${route.id}.js`);
   const outputName = `${route.id}.island.js`;
 
+  // Phase 7.1 B-1/B-4: wire native Fast Refresh transform + Mandu's
+  // boundary injection plugin. Dev-only; prod bundles remain clean.
+  const isDev =
+    (options.minify ?? process.env.NODE_ENV === "production") === false;
   try {
     // 엔트리 래퍼 생성
     await Bun.write(entryPath, generateIslandEntry(route.id, clientModulePath));
 
     // 빌드
     // splitting 옵션: true면 공통 코드를 별도 청크로 추출
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [entryPath],
       outdir: outDir,
       naming: options.splitting ? "[name]-[hash].js" : outputName,
@@ -1292,6 +1566,8 @@ async function buildIsland(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
+      ...(isDev ? { reactFastRefresh: true } : {}),
+      plugins: isDev ? [fastRefreshPlugin()] : [],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
@@ -1385,6 +1661,17 @@ function createBundleManifest(
     }
   }
 
+  // Phase 7.1 B-2: expose Fast Refresh dev bundles so the HTML
+  // preamble can inject a dynamic import pointing at them. Only
+  // populated when buildVendorShims ran in dev mode.
+  const fastRefresh =
+    vendorResult.reactRefreshRuntime && vendorResult.fastRefreshRuntime
+      ? {
+          runtime: vendorResult.reactRefreshRuntime,
+          glue: vendorResult.fastRefreshRuntime,
+        }
+      : undefined;
+
   return {
     version: 1,
     buildTime: new Date().toISOString(),
@@ -1395,6 +1682,7 @@ function createBundleManifest(
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
       router: routerPath, // Client-side Router
+      ...(fastRefresh ? { fastRefresh } : {}),
     },
     importMap: {
       imports: {
@@ -1456,6 +1744,7 @@ export async function buildClientBundles(
   rootDir: string,
   options: BundlerOptions = {}
 ): Promise<BundleResult> {
+  mark("bundler:full");
   const startTime = performance.now();
   const outputs: BundleOutput[] = [];
   const errors: string[] = [];
@@ -1473,6 +1762,44 @@ export async function buildClientBundles(
   // Hydration 라우트가 없어도 빈 매니페스트를 저장해야 함
   // (이전 빌드의 stale 매니페스트 참조 방지)
   if (hydratedRoutes.length === 0) {
+    // #185: skipFrameworkBundles 모드에서는 기존 manifest를 그대로 유지 (devtools 재빌드도 스킵)
+    if (options.skipFrameworkBundles) {
+      const manifestPath = path.join(rootDir, ".mandu/manifest.json");
+      try {
+        const manifestRaw = await fs.readFile(manifestPath, "utf-8");
+        let existing: BundleManifest;
+        try {
+          existing = JSON.parse(manifestRaw) as BundleManifest;
+        } catch (parseError) {
+          // #186 hardening: corrupt JSON이면 silent overwrite 대신 경고 + full build로 fallback
+          console.warn(
+            `[Mandu] Existing manifest is corrupt, falling back to full build: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+          );
+          throw parseError;
+        }
+        // #186 hardening: 필수 필드 검증 (shared / bundles 누락 시 fallback)
+        if (!existing || typeof existing !== "object" || !existing.shared || !existing.bundles) {
+          console.warn("[Mandu] Existing manifest missing required fields, falling back to full build");
+          throw new Error("invalid manifest shape");
+        }
+        return {
+          success: true,
+          outputs: [],
+          errors: [],
+          manifest: existing,
+          stats: {
+            totalSize: 0,
+            totalGzipSize: 0,
+            largestBundle: { routeId: "", size: 0 },
+            buildTime: 0,
+            bundleCount: 0,
+          },
+        };
+      } catch {
+        // 기존 manifest 없음/corrupt/invalid → full path로 fallback
+      }
+    }
+
     // Dev 모드에서는 DevTools 번들 빌드 (island 없어도 동작해야 함)
     const isDev = env === "development";
     if (isDev) {
@@ -1506,13 +1833,18 @@ export async function buildClientBundles(
   if (options.targetRouteIds && options.targetRouteIds.length > 0) {
     const targetRoutes = hydratedRoutes.filter((r) => options.targetRouteIds!.includes(r.id));
 
-    for (const route of targetRoutes) {
-      try {
-        const result = await buildIsland(route, rootDir, outDir, options);
-        outputs.push(result);
-      } catch (error) {
-        errors.push(`[${route.id}] ${String(error)}`);
-      }
+    const targetResults = await Promise.all(
+      targetRoutes.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만 갱신
@@ -1552,11 +1884,129 @@ export async function buildClientBundles(
     return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
   }
 
+  // #185: Framework-internal 번들 스킵 모드
+  // 사용자 코드(src/shared 등) 변경 시 runtime/router/vendor/devtools 재빌드는 낭비.
+  // 기존 매니페스트를 로드해 framework 출력 경로만 재사용하고 사용자 island만 재빌드.
+  if (options.skipFrameworkBundles) {
+    let existingManifest: BundleManifest;
+    try {
+      const manifestData = await fs.readFile(path.join(rootDir, ".mandu/manifest.json"), "utf-8");
+      existingManifest = JSON.parse(manifestData) as BundleManifest;
+    } catch (parseError) {
+      // 기존 매니페스트 없음/corrupt → 경고 후 full build로 fallback
+      if (parseError instanceof SyntaxError) {
+        console.warn(
+          `[Mandu] Existing manifest is corrupt, falling back to full build: ${parseError.message}`,
+        );
+      }
+      return buildClientBundles(manifest, rootDir, { ...options, skipFrameworkBundles: false });
+    }
+
+    // #186 hardening: 필수 필드 검증 — 누락 시 full build로 fallback
+    if (
+      !existingManifest ||
+      typeof existingManifest !== "object" ||
+      !existingManifest.shared ||
+      !existingManifest.bundles
+    ) {
+      console.warn(
+        "[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 route of hydratedRoutes) {
+      if (!route.clientModule) continue;
+      const clientModulePath = path.join(rootDir, route.clientModule);
+      try {
+        const source = await fs.readFile(clientModulePath, "utf-8");
+        const wrongImportPattern = /(?:import|from)\s+['"]@mandujs\/core['"]|require\s*\(\s*['"]@mandujs\/core['"]\s*\)/;
+        if (wrongImportPattern.test(source)) {
+          errors.push(
+            `[${route.id}] Island file "${route.clientModule}" imports from "@mandujs/core" which is a server-side module.\n` +
+            `  Fix: Change the import to "@mandujs/core/client".`,
+          );
+        }
+      } catch {
+        // 파일 읽기 실패는 나중 빌드에서 catch됨
+      }
+    }
+
+    const islandResults = await Promise.all(
+      hydratedRoutes.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 islandResults) {
+      if (r.ok) outputs.push(r.result);
+      else errors.push(`[${r.routeId}] ${r.error}`);
+    }
+
+    // Per-island bundle 재빌드 (이미 병렬)
+    const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
+    const perIslandBundles: Array<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> = [];
+    if (islandFiles.length > 0) {
+      const perIslandResults = 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;
+          }
+        }),
+      );
+      for (const result of perIslandResults) {
+        if (result) perIslandBundles.push(result);
+      }
+    }
+
+    // 기존 manifest를 기반으로 bundles / islands 엔트리만 교체 (framework 경로는 유지)
+    for (const output of outputs) {
+      if (existingManifest.bundles[output.routeId]) {
+        existingManifest.bundles[output.routeId].js = output.outputPath;
+      } else {
+        const route = hydratedRoutes.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,
+        };
+      }
+    }
+    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 };
+  }
+
   // 3-4. Runtime, Router, Vendor, DevTools 번들 병렬 빌드 (서로 독립적)
   const isDev = env === "development";
   const runtimePromise = buildRuntime(outDir, options);
   const routerPromise = buildRouterRuntime(outDir, options);
-  const vendorPromise = buildVendorShims(outDir, options);
+  // Phase 7.2.S2 — `rootDir` is now threaded through so buildVendorShims can
+  // consult `.mandu/vendor-cache/` for warm-boot shim reuse.
+  const vendorPromise = buildVendorShims(rootDir, outDir, options);
   const devtoolsPromise = isDev ? buildDevtoolsBundle(outDir, options) : null;
 
   const [runtimeResult, routerResult, vendorResult, devtoolsResult] = await Promise.all([
@@ -1602,23 +2052,30 @@ export async function buildClientBundles(
     }
   }
 
-  // 5. 각 Island 번들 빌드
-  for (const route of hydratedRoutes) {
-    try {
-      const result = await buildIsland(route, rootDir, outDir, options);
-      outputs.push(result);
-    } catch (error) {
-      const errorStr = String(error);
-      // Detect common mistake: importing @mandujs/core (server module) in client island
+  // 5. 각 Island 번들 병렬 빌드 (#185: L1631의 per-island와 일관성 확보)
+  const fullIslandResults = await Promise.all(
+    hydratedRoutes.map(async (route) => {
+      try {
+        return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
+      } catch (error) {
+        return { ok: false as const, route, error: String(error) };
+      }
+    }),
+  );
+  for (const r of fullIslandResults) {
+    if (r.ok) {
+      outputs.push(r.result);
+    } else {
+      const errorStr = r.error;
       if (errorStr.includes("AggregateError") || errorStr.includes("Could not resolve")) {
-        const clientModule = route.clientModule || "";
+        const clientModule = r.route.clientModule || "";
         errors.push(
-          `[${route.id}] ${errorStr}\n` +
+          `[${r.route.id}] ${errorStr}\n` +
           `  💡 Hint: If your island imports from "@mandujs/core", change it to "@mandujs/core/client".\n` +
-          `     Client islands cannot use server-side modules. File: ${clientModule}`
+          `     Client islands cannot use server-side modules. File: ${clientModule}`,
         );
       } else {
-        errors.push(`[${route.id}] ${errorStr}`);
+        errors.push(`[${r.route.id}] ${errorStr}`);
       }
     }
   }
@@ -1662,6 +2119,7 @@ export async function buildClientBundles(
   // 7. 통계 계산
   const stats = calculateStats(outputs, startTime);
 
+  measure("bundler:full", "bundler:full");
   return {
     success: errors.length === 0,
     outputs,