@mandujs/core 0.54.10 → 0.54.12

package/src/bundler/build.ts

@@ -10,23 +10,23 @@ import type {
   BundleResult,
   BundleOutput,
   BundleManifest,
-  BundleStats,
-  BundlerOptions,
-  IslandFileEntry,
-  PartialFileEntry,
-} 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 {
-  describeMissingHydrationClientModule,
-  validateClientModuleForBrowserBundle,
-} from "../router/client-entry";
+import { mark, measure } from "../perf";
+import { HMR_PERF } from "../perf/hmr-markers";
+import { runOnBundleComplete } from "../plugins/runner";
+import {
+  describeMissingHydrationClientModule,
+  validateClientModuleForBrowserBundle,
+} from "../router/client-entry";
 import {
   readVendorCache,
   writeVendorCache,
@@ -100,13 +100,16 @@ function shouldSplitChunks(options: BundlerOptions): boolean {
   return options.splitting ?? (resolveBundlerMode(options) === "production");
 }
 
-function nodeEnvDefine(options: BundlerOptions): string {
-  return JSON.stringify(resolveBundlerMode(options));
-}
-
-function resolveClientOutDir(rootDir: string, outDir?: string): string {
-  const defaultOutDir = path.join(rootDir, ".mandu/client");
-  if (!outDir) return defaultOutDir;
+function nodeEnvDefine(options: BundlerOptions): string {
+  return JSON.stringify(resolveBundlerMode(options));
+}
+
+const FAST_REFRESH_SELF_ALIAS_PATTERN =
+  /^var\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*\1;\s*\r?\n(?=\$RefreshReg\$\(\1,\s*["'][^"']*:default["']\);)/gm;
+
+function resolveClientOutDir(rootDir: string, outDir?: string): string {
+  const defaultOutDir = path.join(rootDir, ".mandu/client");
+  if (!outDir) return defaultOutDir;
 
   const resolvedOutDir = path.isAbsolute(outDir) ? outDir : path.resolve(rootDir, outDir);
   if (path.normalize(resolvedOutDir) === path.normalize(path.join(rootDir, ".mandu"))) {
@@ -191,46 +194,46 @@ async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<Is
  *
  * @internal
  */
-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;
+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
@@ -239,9 +242,9 @@ export const _testOnly_scanPartialFiles = scanPartialFiles;
  *
  * @internal
  */
-export const _testOnly_getHydratedRoutes = getHydratedRoutes;
-export const _testOnly_getHydrationRoutesMissingClientModule =
-  getHydrationRoutesMissingClientModule;
+export const _testOnly_getHydratedRoutes = getHydratedRoutes;
+export const _testOnly_getHydrationRoutesMissingClientModule =
+  getHydrationRoutesMissingClientModule;
 
 /**
  * Issue #240 Phase 2 — collect every file the React Compiler plugin
@@ -260,37 +263,37 @@ export const _testOnly_getHydrationRoutesMissingClientModule =
  * 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);
-
-  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();
-}
+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(
@@ -317,73 +320,74 @@ async function buildPerIslandBundle(
       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(`Island build failed for '${entry.name}' (source: ${entry.filePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this island file.`);
-    }
-    return { name: entry.name, js: `/.mandu/client/${outputName}`, route: entry.routeId, priority: entry.priority };
-  } catch (error) {
-    await fs.unlink(entryPath).catch(() => {});
-    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 })\`.`);
+      throw new Error(`Island build failed for '${entry.name}' (source: ${entry.filePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this island file.`);
     }
+    await sanitizeGeneratedClientBundle(path.join(outDir, outputName), isDev);
+    return { name: entry.name, js: `/.mandu/client/${outputName}`, route: entry.routeId, priority: entry.priority };
+  } catch (error) {
+    await fs.unlink(entryPath).catch(() => {});
+    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 sanitizedContent = await sanitizeGeneratedClientBundle(outputPath, isDev);
     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;
-  }
-}
+    const gzipped = Bun.gzipSync(Buffer.from(sanitizedContent));
+
+    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;
+  }
+}
 
 /**
  * 빈 매니페스트 생성
@@ -407,23 +411,23 @@ 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 getHydrationRoutesMissingClientModule(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 &&
+      needsHydration(route)
+  );
+}
+
+function getHydrationRoutesMissingClientModule(manifest: RoutesManifest): RouteSpec[] {
+  return manifest.routes.filter(
+    (route) =>
+      route.kind === "page" &&
+      !route.clientModule &&
+      needsHydration(route)
+  );
+}
 
 const REACT_SHIM_EXPORTS = [
   "Activity",
@@ -518,31 +522,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__;
-
-// 서버 데이터
-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 || {};
+// 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)
@@ -756,16 +760,16 @@ async function loadAndHydrate(element, src) {
     const island = module.default;
     let data = getServerData(id);
 
-    // 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'));
+    // 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);
         }
@@ -1439,63 +1443,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;
-`;
-}
-
-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 번들 빌드
- */
+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
@@ -1776,9 +1780,9 @@ async function buildVendorShims(
     }
   }
 
-  const buildShim = async (
-    shim: { name: string; source: string; key: VendorShimKey; cacheId: string }
-  ): Promise<{ key: VendorShimKey; cacheId: string; outputName?: string; outputPath?: string; error?: string }> => {
+  const buildShim = async (
+    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`;
 
@@ -1814,14 +1818,14 @@ async function buildVendorShims(
 
       await fs.unlink(srcPath).catch(() => {});
 
-      if (!result.success) {
-        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  ${vendorShimFailureHint(shim.name)}`,
-        };
-      }
+      if (!result.success) {
+        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  ${vendorShimFailureHint(shim.name)}`,
+        };
+      }
 
       return {
         key: shim.key,
@@ -1831,13 +1835,13 @@ async function buildVendorShims(
       };
     } catch (error) {
       await fs.unlink(srcPath).catch(() => {});
-      return {
-        key: shim.key,
-        cacheId: shim.cacheId,
-        error: `[${shim.name}] ${String(error)}\n  ${vendorShimFailureHint(shim.name)}`,
-      };
-    }
-  };
+      return {
+        key: shim.key,
+        cacheId: shim.cacheId,
+        error: `[${shim.name}] ${String(error)}\n  ${vendorShimFailureHint(shim.name)}`,
+      };
+    }
+  };
 
   const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
   const writeEntries: VendorCacheWriteEntry[] = [];
@@ -1880,14 +1884,14 @@ async function buildVendorShims(
     fastRefreshRuntime: results.fastRefreshRuntime,
     errors,
   };
-}
-
-function vendorShimFailureHint(shimName: string): string {
-  if (shimName.includes("react-refresh")) {
-    return "Hint: install the optional dev peer dependency with `bun add -d react-refresh`.";
-  }
-  return "Hint: check the import paths and ensure the vendor package is installed.";
-}
+}
+
+function vendorShimFailureHint(shimName: string): string {
+  if (shimName.includes("react-refresh")) {
+    return "Hint: install the optional dev peer dependency with `bun add -d react-refresh`.";
+  }
+  return "Hint: check the import paths and ensure the vendor package is installed.";
+}
 
 /**
  * 단일 Island 번들 빌드
@@ -1959,9 +1963,9 @@ async function buildIsland(
       actualOutputName = outputName;
     }
 
-    const outputFile = Bun.file(actualOutputPath);
-    const content = await outputFile.text();
-    const gzipped = Bun.gzipSync(Buffer.from(content));
+    const outputFile = Bun.file(actualOutputPath);
+    const content = await sanitizeGeneratedClientBundle(actualOutputPath, isDev);
+    const gzipped = Bun.gzipSync(Buffer.from(content));
 
     return {
       routeId: route.id,
@@ -1973,22 +1977,64 @@ async function buildIsland(
   } catch (error) {
     await fs.unlink(entryPath).catch(() => {});
     throw error;
-  }
-}
-
-/**
- * 번들 매니페스트 생성
+  }
+}
+
+async function sanitizeGeneratedClientBundle(outputPath: string, isDev: boolean): Promise<string> {
+  const source = await Bun.file(outputPath).text();
+  if (!isDev) return source;
+
+  const sanitized = removeFastRefreshSelfAliases(source);
+  if (sanitized === source) return source;
+
+  await Bun.write(outputPath, sanitized);
+  await validateGeneratedClientBundle(outputPath);
+  return sanitized;
+}
+
+function removeFastRefreshSelfAliases(source: string): string {
+  return source.replace(FAST_REFRESH_SELF_ALIAS_PATTERN, (line, localName: string, offset: number) => {
+    const priorSource = source.slice(0, offset);
+    const declarationPattern = new RegExp(`(?:const|let|class|function)\\s+${escapeRegExp(localName)}\\b`);
+    return declarationPattern.test(priorSource) ? "" : line;
+  });
+}
+
+async function validateGeneratedClientBundle(outputPath: string): Promise<void> {
+  const tempOutDir = await fs.mkdtemp(path.join(path.dirname(outputPath), ".validate-"));
+  try {
+    const result = await safeBuild({
+      entrypoints: [outputPath],
+      outdir: tempOutDir,
+      target: "browser",
+      external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"],
+    });
+    if (result.success) return;
+
+    const grouped = result.logs.map((log) => `  - ${log.message}`).join("\n");
+    throw new Error(`Generated client bundle failed syntax validation (source: ${outputPath}):\n${grouped}`);
+  } finally {
+    await fs.rm(tempOutDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * 번들 매니페스트 생성
  */
-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 {
+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) {
@@ -2004,27 +2050,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,
-      };
-    }
-  }
+      };
+    }
+  }
+
+  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
@@ -2040,11 +2086,11 @@ function createBundleManifest(
   return {
     version: 1,
     buildTime: new Date().toISOString(),
-    env,
-    bundles,
-    ...(islands ? { islands } : {}),
-    ...(partials ? { partials } : {}),
-    shared: {
+    env,
+    bundles,
+    ...(islands ? { islands } : {}),
+    ...(partials ? { partials } : {}),
+    shared: {
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
       router: routerPath, // Client-side Router
@@ -2065,32 +2111,32 @@ function createBundleManifest(
 /**
  * 번들 통계 계산
  */
-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 };
+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 + extraOutputs.length,
-  };
-}
+    totalGzipSize,
+    largestBundle,
+    buildTime: performance.now() - startTime,
+    bundleCount: outputs.length + extraOutputs.length,
+  };
+}
 
 /**
  * 클라이언트 번들 빌드
@@ -2134,47 +2180,47 @@ export async function buildClientBundles(
       errors.push(`onBundleComplete[${e.source}]: ${e.error.message}`);
     }
   };
-  const env = resolveBundlerMode(options);
-
-  // 1. Hydration이 필요한 라우트 필터링
-  const invalidClientRouteIds = new Set<string>();
-  const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
-  const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
-  const routesMissingClientModule = getHydrationRoutesMissingClientModule(manifest);
-  if (routesMissingClientModule.length > 0) {
-    const missingClientErrors = await Promise.all(
-      routesMissingClientModule.map((route) =>
-        describeMissingHydrationClientModule(route, rootDir, {
-          allowPartialOnly: partialFiles.length > 0,
-        })
-      )
-    );
-    errors.push(...missingClientErrors.filter((error): error is string => error !== null));
-  }
-
-  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;
-  }
-  // 2. 출력 디렉토리 생성 (항상 필요 - 매니페스트 저장용)
+  const env = resolveBundlerMode(options);
+
+  // 1. Hydration이 필요한 라우트 필터링
+  const invalidClientRouteIds = new Set<string>();
+  const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
+  const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
+  const routesMissingClientModule = getHydrationRoutesMissingClientModule(manifest);
+  if (routesMissingClientModule.length > 0) {
+    const missingClientErrors = await Promise.all(
+      routesMissingClientModule.map((route) =>
+        describeMissingHydrationClientModule(route, rootDir, {
+          allowPartialOnly: partialFiles.length > 0,
+        })
+      )
+    );
+    errors.push(...missingClientErrors.filter((error): error is string => error !== null));
+  }
+
+  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;
+  }
+  // 2. 출력 디렉토리 생성 (항상 필요 - 매니페스트 저장용)
   const outDir = resolveClientOutDir(rootDir, options.outDir);
   await fs.mkdir(outDir, { recursive: true });
 
   // Hydration 라우트가 없어도 빈 매니페스트를 저장해야 함
   // (이전 빌드의 stale 매니페스트 참조 방지)
-  if (hydratedRoutes.length === 0 && partialFiles.length === 0) {
+  if (hydratedRoutes.length === 0 && partialFiles.length === 0) {
     // #185: skipFrameworkBundles 모드에서는 기존 manifest를 그대로 유지 (devtools 재빌드도 스킵)
-    if (options.skipFrameworkBundles && errors.length === 0) {
+    if (options.skipFrameworkBundles && errors.length === 0) {
       const manifestPath = path.join(rootDir, ".mandu/manifest.json");
       try {
         const manifestRaw = await fs.readFile(manifestPath, "utf-8");
@@ -2225,11 +2271,11 @@ export async function buildClientBundles(
       path.join(rootDir, ".mandu/manifest.json"),
       JSON.stringify(emptyManifest, null, 2)
     );
-    return {
-      success: errors.length === 0,
-      outputs: [],
-      errors,
-      manifest: emptyManifest,
+    return {
+      success: errors.length === 0,
+      outputs: [],
+      errors,
+      manifest: emptyManifest,
       stats: {
         totalSize: 0,
         totalGzipSize: 0,
@@ -2268,14 +2314,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)
-    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;
+    // 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;
@@ -2287,11 +2333,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);
@@ -2327,13 +2373,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 });
-    }
-
-    for (const routeId of invalidClientRouteIds) {
-      delete existingManifest.bundles[routeId];
-    }
-
-    // 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);
@@ -2398,62 +2444,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,
-        };
-      }
-    }
-
-    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 };
-  }
+        };
+      }
+    }
+
+    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";
@@ -2539,11 +2585,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;
@@ -2551,38 +2597,38 @@ export async function buildClientBundles(
       })
     );
     for (const result of islandResults) {
-      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,
-  );
+      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"),
@@ -2590,15 +2636,15 @@ 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,
+    })),
+  );
 
   // Phase 18.τ — fire onBundleComplete(stats) before return.
   await fireOnBundleComplete(stats);
@@ -2626,14 +2672,14 @@ 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)");
-    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}`);
@@ -2642,15 +2688,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)})`
-    );
-  }
-  if (partialCount > 0) {
-    console.log(`  Partials: ${partialCount}`);
-  }
+  // 각 번들 정보
+  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:");