@mandujs/core 0.20.9 → 0.21.0

package/README.md

@@ -162,7 +162,7 @@ watcher.start();
 listPresets().forEach(p => console.log(p.name, p.description));
 ```
 
-### Presets
+### Presets (6)
 
 | Preset | Layers | Use Case |
 |--------|--------|----------|
@@ -171,6 +171,7 @@ listPresets().forEach(p => console.log(p.name, p.description));
 | `clean` | api, application, domain, infra, shared | Backend |
 | `hexagonal` | adapters, ports, application, domain | DDD |
 | `atomic` | pages, templates, organisms, molecules, atoms | UI |
+| `cqrs` | commands, queries, events, dto, application, domain | Event-sourced apps |
 
 ### AST-based Analysis
 

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@mandujs/core",
-  "version": "0.20.9",
-  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client/index.ts",
-    "./middleware": "./src/middleware/index.ts",
-    "./testing": "./src/testing/index.ts",
-    "./plugins": "./src/plugins/index.ts",
-    "./error": "./src/error/index.ts",
-    "./observability": "./src/observability/index.ts",
-    "./bundler/prerender": "./src/bundler/prerender.ts",
-    "./*": "./src/*"
-  },
-  "files": [
-    "src/**/*"
-  ],
-  "scripts": {
-    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
-    "test:hydration": "bun test tests/hydration",
-    "test:streaming": "bun test tests/streaming-ssr",
-    "test:watch": "bun test --watch"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^15.0.0"
-  },
-  "keywords": [
-    "mandu",
-    "framework",
-    "agent",
-    "ai",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/konamgil/mandu.git",
-    "directory": "packages/core"
-  },
-  "author": "konamgil",
-  "license": "MPL-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
-  "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "@tailwindcss/cli": ">=4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@tailwindcss/cli": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "chokidar": "^5.0.0",
-    "fast-glob": "^3.3.2",
-    "glob": "^13.0.0",
-    "minimatch": "^10.1.1",
-    "ollama": "^0.6.3",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "@mandujs/core",
+  "version": "0.21.0",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./middleware": "./src/middleware/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./plugins": "./src/plugins/index.ts",
+    "./error": "./src/error/index.ts",
+    "./observability": "./src/observability/index.ts",
+    "./bundler/prerender": "./src/bundler/prerender.ts",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "scripts": {
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
+    "test:hydration": "bun test tests/hydration",
+    "test:streaming": "bun test tests/streaming-ssr",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0"
+  },
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MPL-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@tailwindcss/cli": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/cli": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.2",
+    "glob": "^13.0.0",
+    "minimatch": "^10.1.1",
+    "ollama": "^0.6.3",
+    "zod": "^3.23.8"
+  }
+}

package/src/bundler/build.ts

@@ -1473,6 +1473,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 +1544,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,6 +1595,122 @@ 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);
@@ -1602,23 +1761,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}`);
       }
     }
   }

package/src/bundler/dev.ts

@@ -10,6 +10,12 @@ import { PORTS, TIMEOUTS } from "../constants";
 import path from "path";
 import fs from "fs";
 
+/**
+ * #184: 공통 디렉토리 변경 시 사용하는 sentinel.
+ * `onSSRChange`에 특정 파일 경로 대신 이 상수를 전달하면 "전체 SSR 레지스트리 invalidate" 의미.
+ */
+export const SSR_CHANGE_WILDCARD = "*";
+
 export interface DevBundlerOptions {
   /** 프로젝트 루트 */
   rootDir: string;
@@ -21,14 +27,16 @@ export interface DevBundlerOptions {
   onError?: (error: Error, routeId?: string) => void;
   /**
    * SSR 파일 변경 콜백 (page.tsx, layout.tsx 등)
-   * 클라이언트 번들 리빌드 없이 서버 핸들러 재등록이 필요한 경우 호출
+   * 클라이언트 번들 리빌드 없이 서버 핸들러 재등록이 필요한 경우 호출.
+   * `SSR_CHANGE_WILDCARD` ("*")를 받으면 전체 레지스트리 invalidate 의미 (#184).
+   * Promise 반환 시 await 되므로 레지스트리 clear가 완료된 후 HMR reload broadcast 가능.
    */
-  onSSRChange?: (filePath: string) => void;
+  onSSRChange?: (filePath: string) => void | Promise<void>;
   /**
    * API route 파일 변경 콜백 (route.ts 등)
    * API 핸들러 재등록이 필요한 경우 호출
    */
-  onAPIChange?: (filePath: string) => void;
+  onAPIChange?: (filePath: string) => void | Promise<void>;
   /**
    * 추가 watch 디렉토리 (공통 컴포넌트 등)
    * 상대 경로 또는 절대 경로 모두 지원
@@ -56,6 +64,21 @@ export interface DevBundler {
   close: () => void;
 }
 
+/**
+ * #180: 파일 경로 비교를 위한 정규화.
+ * - 절대 경로로 변환 (path.resolve)
+ * - 백슬래시 → 포워드슬래시
+ * - Windows에서는 case-insensitive 매칭 (소문자화)
+ *
+ * 동적 라우트 폴더(`[lang]` 등) 변경 감지가 누락되던 문제는 watcher가 보고하는
+ * `path.join(dir, filename)`과 `serverModuleSet` 등록 시의 `path.resolve(rootDir, ...)`
+ * 가 드라이브 문자 대소문자/슬래시 표기 차이로 어긋나서 발생했음.
+ */
+function normalizeFsPath(p: string): string {
+  const resolved = path.resolve(p).replace(/\\/g, "/");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
 // 기본 공통 컴포넌트 디렉토리 목록
 const DEFAULT_COMMON_DIRS = [
   "src/components",
@@ -114,7 +137,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   for (const route of manifest.routes) {
     if (route.clientModule) {
       const absPath = path.resolve(rootDir, route.clientModule);
-      const normalizedPath = absPath.replace(/\\/g, "/");
+      const normalizedPath = normalizeFsPath(absPath);
       clientModuleToRoute.set(normalizedPath, route.id);
 
       // Also register *.client.tsx/ts files in the same directory (#140)
@@ -122,7 +145,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       const dir = path.dirname(absPath);
       const baseStem = path.basename(absPath).replace(/\.(island|client)\.(tsx?|jsx?)$/, "");
       for (const ext of [".client.tsx", ".client.ts", ".client.jsx", ".client.js"]) {
-        const clientPath = path.join(dir, baseStem + ext).replace(/\\/g, "/");
+        const clientPath = normalizeFsPath(path.join(dir, baseStem + ext));
         if (clientPath !== normalizedPath) {
           clientModuleToRoute.set(clientPath, route.id);
         }
@@ -134,23 +157,23 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
     // SSR 모듈 등록 (page.tsx, layout.tsx) — #151
     if (route.componentModule) {
-      const absPath = path.resolve(rootDir, route.componentModule).replace(/\\/g, "/");
-      serverModuleSet.add(absPath);
-      watchDirs.add(path.dirname(path.resolve(rootDir, route.componentModule)));
+      const absPath = path.resolve(rootDir, route.componentModule);
+      serverModuleSet.add(normalizeFsPath(absPath));
+      watchDirs.add(path.dirname(absPath));
     }
     if (route.layoutChain) {
       for (const layoutPath of route.layoutChain) {
-        const absPath = path.resolve(rootDir, layoutPath).replace(/\\/g, "/");
-        serverModuleSet.add(absPath);
-        watchDirs.add(path.dirname(path.resolve(rootDir, layoutPath)));
+        const absPath = path.resolve(rootDir, layoutPath);
+        serverModuleSet.add(normalizeFsPath(absPath));
+        watchDirs.add(path.dirname(absPath));
       }
     }
 
     // Track API route modules for hot-reload
     if (route.kind === "api" && route.module) {
-      const absPath = path.resolve(rootDir, route.module).replace(/\\/g, "/");
-      apiModuleSet.add(absPath);
-      watchDirs.add(path.dirname(path.resolve(rootDir, route.module)));
+      const absPath = path.resolve(rootDir, route.module);
+      apiModuleSet.add(normalizeFsPath(absPath));
+      watchDirs.add(path.dirname(absPath));
     }
   }
 
@@ -194,9 +217,9 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
   // 파일이 공통 디렉토리에 있는지 확인
   const isInCommonDir = (filePath: string): boolean => {
-    const normalizedFile = path.resolve(filePath).replace(/\\/g, "/");
+    const normalizedFile = normalizeFsPath(filePath);
     for (const commonDir of commonWatchDirs) {
-      const normalizedCommon = path.resolve(commonDir).replace(/\\/g, "/");
+      const normalizedCommon = normalizeFsPath(commonDir);
       if (normalizedFile.startsWith(normalizedCommon + "/")) {
         return true;
       }
@@ -232,23 +255,38 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   };
 
   const _doBuild = async (changedFile: string) => {
-    const normalizedPath = changedFile.replace(/\\/g, "/");
+    const normalizedPath = normalizeFsPath(changedFile);
 
-    // 공통 컴포넌트 디렉토리 변경 → 전체 재빌드 (targetRouteIds 없이)
+    // 공통 컴포넌트 디렉토리 변경 → Island만 재빌드 + SSR 레지스트리 invalidate (#184, #185)
     if (isInCommonDir(changedFile)) {
       console.log(`\n🔄 Common file changed: ${path.basename(changedFile)}`);
-      console.log(`   Rebuilding all islands...`);
+      console.log(`   Rebuilding islands (framework bundles skipped)...`);
       const startTime = performance.now();
 
       try {
+        // #185: framework 번들 (runtime/router/vendor/devtools) 스킵 — 사용자 코드 변경 시 불필요
         const result = await buildClientBundles(manifest, rootDir, {
           minify: false,
           sourcemap: true,
+          skipFrameworkBundles: true,
         });
 
         const buildTime = performance.now() - startTime;
 
         if (result.success) {
+          // #184: common dir 변경은 SSR 모듈 캐시 invalidation이 필요 — wildcard 시그널
+          // 빌드 성공한 경우에만 SSR 레지스트리를 clear (실패 시 마지막 good state 유지)
+          // 주의: Bun의 transitive ESM 캐시는 프로세스 레벨이라 이 시그널만으로는
+          //      `src/shared/**`을 transitive하게 import하는 SSR 모듈까지 완전히 갱신되지 않음.
+          //      진짜 해결은 subprocess/worker 기반 SSR eval이 필요 (follow-up 이슈).
+          if (onSSRChange) {
+            try {
+              await Promise.resolve(onSSRChange(SSR_CHANGE_WILDCARD));
+            } catch (ssrError) {
+              console.warn(`⚠️  SSR invalidation failed:`, ssrError instanceof Error ? ssrError.message : ssrError);
+            }
+          }
+
           console.log(`✅ Rebuilt ${result.stats.bundleCount} islands in ${buildTime.toFixed(0)}ms`);
           onRebuild?.({
             routeId: "*", // 전체 재빌드 표시
@@ -257,6 +295,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           });
         } else {
           console.error(`❌ Build failed:`, result.errors);
+          console.log(`   ⏳ SSR registry not invalidated (keeping last good state)`);
           onRebuild?.({
             routeId: "*",
             success: false,
@@ -279,10 +318,10 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     // Fallback for *.client.tsx/ts: find route whose clientModule is in the same directory (#140)
     // basename matching (e.g. "page" !== "index") is unreliable — use directory-based matching instead
     if (!routeId && (changedFile.endsWith(".client.ts") || changedFile.endsWith(".client.tsx"))) {
-      const changedDir = path.dirname(path.resolve(rootDir, changedFile)).replace(/\\/g, "/");
+      const changedDir = normalizeFsPath(path.dirname(path.resolve(rootDir, changedFile)));
       const matchedRoute = manifest.routes.find((r) => {
         if (!r.clientModule) return false;
-        const routeDir = path.dirname(path.resolve(rootDir, r.clientModule)).replace(/\\/g, "/");
+        const routeDir = normalizeFsPath(path.dirname(path.resolve(rootDir, r.clientModule)));
         return routeDir === changedDir;
       });
       if (matchedRoute) {

package/src/bundler/types.ts

@@ -137,4 +137,12 @@ export interface BundlerOptions {
    * - 미지정 시 전체 빌드 (기본값)
    */
   targetRouteIds?: string[];
+  /**
+   * Framework-internal 번들 (runtime/router/vendor/devtools) 스킵 (#185)
+   * - true: 사용자 island만 재빌드, runtime/router/vendor/devtools 출력은 기존 매니페스트에서 재사용
+   * - 주 용도: 공통 디렉토리(src/shared 등) 파일 변경 시 dev watcher가 수행하는 rebuild.
+   *   사용자 코드 변경은 framework 번들 출력에 영향을 주지 않으므로 재빌드 불필요.
+   * - 안전성: 기존 `.mandu/manifest.json` 이 없으면 자동으로 full build로 fallback.
+   */
+  skipFrameworkBundles?: boolean;
 }

package/src/config/validate.ts

@@ -100,6 +100,7 @@ const DevConfigSchema = z
   .object({
     hmr: z.boolean().default(true),
     watchDirs: z.array(z.string()).default([]),
+    observability: z.boolean().default(true),
   })
   .strict();
 

package/src/devtools/ai/mcp-connector.ts

@@ -85,22 +85,13 @@ export type MCPConnectionStatus =
 // ============================================================================
 
 /**
- * #176: 런타임에 현재 페이지 호스트/포트에서 MCP WebSocket URL을 유추한다.
- * Bun 번들러가 `typeof window`를 컴파일 시 dead-code 제거하므로
- * 함수로 감싸서 런타임 평가를 보장한다.
+ * #181: 이전에는 `ws://{host}:{port}/mcp` 형태로 자동 유추했으나, dev 서버는
+ * 해당 엔드포인트를 제공하지 않아 브라우저가 reconnect 루프에 빠져 멈추는 문제가 있었음.
+ * 이제는 명시적인 `serverUrl`을 받지 못하면 connect() 자체가 실패하도록 한다.
+ * 호출자가 의도적으로 MCP 엔드포인트 URL을 넘겨야만 WebSocket을 시도한다.
  */
-function resolveDefaultServerUrl(): string {
-  try {
-    // eslint-disable-next-line no-restricted-globals
-    if (globalThis.document && globalThis.location) {
-      return `ws://${globalThis.location.hostname}:${globalThis.location.port}/mcp`;
-    }
-  } catch { /* SSR / Node / Bun 환경 */ }
-  return 'ws://localhost:3333/mcp';
-}
-
 const DEFAULT_OPTIONS: Required<MCPConnectorOptions> = {
-  serverUrl: '',  // connect() 시 resolveDefaultServerUrl()로 대체
+  serverUrl: '',
   connectionTimeout: 5000,
   requestTimeout: 30000,
   // #175: MCP 서버가 없을 수 있으므로 기본 비활성화
@@ -150,6 +141,19 @@ export class MCPConnector {
         return;
       }
 
+      // #181: 명시적 serverUrl이 없으면 즉시 실패. 자동 URL 유추는
+      // 존재하지 않는 /mcp 엔드포인트로 향해 브라우저를 멈추게 했음.
+      const url = this.options.serverUrl;
+      if (!url) {
+        const err = new Error(
+          '[Mandu Kitchen] MCPConnector.connect() requires an explicit serverUrl. ' +
+            'No MCP WebSocket endpoint is started by the dev server.',
+        );
+        this.handleConnectionError(err);
+        reject(err);
+        return;
+      }
+
       this.setStatus('connecting');
 
       const timeout = setTimeout(() => {
@@ -158,8 +162,6 @@ export class MCPConnector {
       }, this.options.connectionTimeout);
 
       try {
-        // #176: 빈 serverUrl이면 런타임에서 현재 페이지 기준으로 유추
-        const url = this.options.serverUrl || resolveDefaultServerUrl();
         this.ws = new WebSocket(url);
 
         this.ws.onopen = () => {

package/src/devtools/client/components/mandu-character.tsx

@@ -35,7 +35,10 @@ const styles = {
     userSelect: 'none' as const,
     fontFamily: typography.fontFamily.mono,
     textTransform: 'uppercase' as const,
-    border: `1px solid ${colors.background.light}`,
+    // #183: borderColor longhand override 충돌을 피하기 위해 shorthand를 분리
+    borderWidth: '1px',
+    borderStyle: 'solid',
+    borderColor: colors.background.light,
   },
   content: {
     display: 'flex',