@mandujs/core 0.9.40 → 0.9.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.40",
+  "version": "0.9.42",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/build.ts

@@ -3,17 +3,18 @@
  * Bun.build 기반 클라이언트 번들 빌드
  */
 
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
-import { needsHydration, getRouteHydration } from "../spec/schema";
-import type {
-  BundleResult,
-  BundleOutput,
-  BundleManifest,
-  BundleStats,
-  BundlerOptions,
-} from "./types";
-import path from "path";
-import fs from "fs/promises";
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import { needsHydration, getRouteHydration } from "../spec/schema";
+import type {
+  BundleResult,
+  BundleOutput,
+  BundleManifest,
+  BundleStats,
+  BundlerOptions,
+} from "./types";
+import { HYDRATION } from "../constants";
+import path from "path";
+import fs from "fs/promises";
 
 /**
  * 빈 매니페스트 생성
@@ -281,7 +282,7 @@ function hydrateIslands() {
   for (const el of islands) {
     const id = el.getAttribute('data-mandu-island');
     const src = el.getAttribute('data-mandu-src');
-    const priority = el.getAttribute('data-mandu-priority') || 'visible';
+    const priority = el.getAttribute('data-mandu-priority') || '${HYDRATION.DEFAULT_PRIORITY}';
 
     if (!id || !src) {
       console.warn('[Mandu] Island missing id or src:', el);
@@ -854,20 +855,21 @@ interface VendorBuildResult {
  * Vendor shim 번들 빌드
  * React, ReactDOM, ReactDOMClient를 각각의 shim으로 빌드
  */
-async function buildVendorShims(
-  outDir: string,
-  options: BundlerOptions
-): Promise<VendorBuildResult> {
-  const errors: string[] = [];
-  const results: Record<string, string> = {
-    react: "",
-    reactDom: "",
-    reactDomClient: "",
-    jsxRuntime: "",
-    jsxDevRuntime: "",
-  };
-
-  const shims = [
+async function buildVendorShims(
+  outDir: string,
+  options: BundlerOptions
+): Promise<VendorBuildResult> {
+  const errors: string[] = [];
+  type VendorShimKey = "react" | "reactDom" | "reactDomClient" | "jsxRuntime" | "jsxDevRuntime";
+  const results: Record<VendorShimKey, string> = {
+    react: "",
+    reactDom: "",
+    reactDomClient: "",
+    jsxRuntime: "",
+    jsxDevRuntime: "",
+  };
+
+  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" },
@@ -875,52 +877,68 @@ async function buildVendorShims(
     { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime" },
   ];
 
-  for (const shim of shims) {
-    const srcPath = path.join(outDir, `${shim.name}.src.js`);
-    const outputName = `${shim.name}.js`;
-
-    try {
-      await Bun.write(srcPath, shim.source);
-
-      // _react.js와 jsx-runtime들은 완전히 번들링 (external 없음)
-      // _react-dom*, jsx-runtime은 react를 external로 처리하여 동일한 React 인스턴스 공유
-      // jsx-runtime은 Fragment를 react에서 가져오므로 react만 external
-      let shimExternal: string[] = [];
-      if (shim.name === "_react-dom" || shim.name === "_react-dom-client") {
-        shimExternal = ["react"];
-      } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
-        // jsx-runtime은 react를 external로 (Fragment 때문에),
-        // 하지만 react/jsx-runtime은 번들링되어야 함
-        shimExternal = ["react"];
-      }
-      // _react.js는 external 없이 React 전체를 번들링
-
-      const result = await Bun.build({
-        entrypoints: [srcPath],
-        outdir: outDir,
-        naming: outputName,
-        minify: options.minify ?? process.env.NODE_ENV === "production",
-        sourcemap: options.sourcemap ? "external" : "none",
-        target: "browser",
-        external: shimExternal,
-        define: {
-          "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
-          ...options.define,
-        },
-      });
-
-      await fs.unlink(srcPath).catch(() => {});
-
-      if (!result.success) {
-        errors.push(`[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`);
-      } else {
-        results[shim.key] = `/.mandu/client/${outputName}`;
-      }
-    } catch (error) {
-      await fs.unlink(srcPath).catch(() => {});
-      errors.push(`[${shim.name}] ${String(error)}`);
-    }
-  }
+  const buildShim = async (
+    shim: { name: string; source: string; key: VendorShimKey }
+  ): Promise<{ key: VendorShimKey; outputPath?: string; error?: string }> => {
+    const srcPath = path.join(outDir, `${shim.name}.src.js`);
+    const outputName = `${shim.name}.js`;
+
+    try {
+      await Bun.write(srcPath, shim.source);
+
+      // _react.js는 external 없이 React 전체를 번들링
+      // _react-dom*, jsx-runtime은 react를 external로 처리하여 동일한 React 인스턴스 공유
+      let shimExternal: string[] = [];
+      if (shim.name === "_react-dom" || shim.name === "_react-dom-client") {
+        shimExternal = ["react"];
+      } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
+        shimExternal = ["react"];
+      }
+
+      const result = await Bun.build({
+        entrypoints: [srcPath],
+        outdir: outDir,
+        naming: outputName,
+        minify: options.minify ?? process.env.NODE_ENV === "production",
+        sourcemap: options.sourcemap ? "external" : "none",
+        target: "browser",
+        external: shimExternal,
+        define: {
+          "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
+          ...options.define,
+        },
+      });
+
+      await fs.unlink(srcPath).catch(() => {});
+
+      if (!result.success) {
+        return {
+          key: shim.key,
+          error: `[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`,
+        };
+      }
+
+      return {
+        key: shim.key,
+        outputPath: `/.mandu/client/${outputName}`,
+      };
+    } catch (error) {
+      await fs.unlink(srcPath).catch(() => {});
+      return {
+        key: shim.key,
+        error: `[${shim.name}] ${String(error)}`,
+      };
+    }
+  };
+
+  const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
+  for (const result of buildResults) {
+    if (result.error) {
+      errors.push(result.error);
+    } else if (result.outputPath) {
+      results[result.key] = result.outputPath;
+    }
+  }
 
   return {
     success: errors.length === 0,
@@ -1034,7 +1052,7 @@ function createBundleManifest(
     bundles[output.routeId] = {
       js: output.outputPath,
       dependencies: ["_runtime", "_react"],
-      priority: hydration?.priority || "visible",
+      priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
     };
   }
 

package/src/bundler/dev.ts

@@ -3,11 +3,12 @@
  * 개발 모드 번들링 + HMR (Hot Module Replacement)
  */
 
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
-import { buildClientBundles } from "./build";
-import type { BundleResult } from "./types";
-import path from "path";
-import fs from "fs";
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import { buildClientBundles } from "./build";
+import type { BundleResult } from "./types";
+import { PORTS, TIMEOUTS } from "../constants";
+import path from "path";
+import fs from "fs";
 
 export interface DevBundlerOptions {
   /** 프로젝트 루트 */
@@ -57,6 +58,12 @@ const DEFAULT_COMMON_DIRS = [
   "hooks",
   "src/utils",
   "utils",
+  // Islands & Client 디렉토리
+  "src/client",
+  "client",
+  "src/islands",
+  "islands",
+  "apps/web",
 ];
 
 /**
@@ -267,7 +274,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           clearTimeout(debounceTimer);
         }
 
-        debounceTimer = setTimeout(() => handleFileChange(fullPath), 100);
+        debounceTimer = setTimeout(() => handleFileChange(fullPath), TIMEOUTS.WATCHER_DEBOUNCE);
       });
 
       watchers.push(watcher);
@@ -326,7 +333,7 @@ export interface HMRMessage {
  */
 export function createHMRServer(port: number): HMRServer {
   const clients = new Set<any>();
-  const hmrPort = port + 1;
+  const hmrPort = port + PORTS.HMR_OFFSET;
 
   const server = Bun.serve({
     port: hmrPort,
@@ -409,16 +416,16 @@ export function createHMRServer(port: number): HMRServer {
  * HMR 클라이언트 스크립트 생성
  * 브라우저에서 실행되어 HMR 서버와 연결
  */
-export function generateHMRClientScript(port: number): string {
-  const hmrPort = port + 1;
+export function generateHMRClientScript(port: number): string {
+  const hmrPort = port + PORTS.HMR_OFFSET;
 
   return `
 (function() {
-  const HMR_PORT = ${hmrPort};
-  let ws = null;
-  let reconnectAttempts = 0;
-  const maxReconnectAttempts = 10;
-  const reconnectDelay = 1000;
+  const HMR_PORT = ${hmrPort};
+  let ws = null;
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = ${TIMEOUTS.HMR_MAX_RECONNECT};
+  const reconnectDelay = ${TIMEOUTS.HMR_RECONNECT_DELAY};
 
   function connect() {
     try {

package/src/client/globals.ts

@@ -0,0 +1,44 @@
+/**
+ * Mandu 전역 타입 선언
+ * 클라이언트 측 전역 상태의 타입 정의
+ */
+import type { Root } from "react-dom/client";
+import type { RouterState } from "./router";
+
+interface ManduRouteInfo {
+  id: string;
+  pattern: string;
+  params: Record<string, string>;
+}
+
+interface ManduDataEntry {
+  serverData: unknown;
+  timestamp?: number;
+}
+
+declare global {
+  interface Window {
+    /** 서버에서 전달된 데이터 (routeId → data) */
+    __MANDU_DATA__?: Record<string, ManduDataEntry>;
+
+    /** 직렬화된 서버 데이터 (raw JSON) */
+    __MANDU_DATA_RAW__?: string;
+
+    /** 현재 라우트 정보 */
+    __MANDU_ROUTE__?: ManduRouteInfo;
+
+    /** 클라이언트 라우터 상태 */
+    __MANDU_ROUTER_STATE__?: RouterState;
+
+    /** 라우터 상태 변경 리스너 */
+    __MANDU_ROUTER_LISTENERS__?: Set<(state: RouterState) => void>;
+
+    /** Hydrated roots 추적 (unmount용) */
+    __MANDU_ROOTS__?: Map<string, Root>;
+
+    /** React 인스턴스 공유 */
+    __MANDU_REACT__?: typeof import("react");
+  }
+}
+
+export {};

package/src/client/index.ts

@@ -1,6 +1,6 @@
-/**
- * Mandu Client Module 🏝️
- * 클라이언트 사이드 hydration 및 라우팅을 위한 API
+/**
+ * Mandu Client Module 🏝️
+ * 클라이언트 사이드 hydration 및 라우팅을 위한 API
  *
  * @example
  * ```typescript
@@ -23,7 +23,8 @@
  *   return <Link href="/about">About</Link>;
  * }
  * ```
- */
+ */
+import "./globals";
 
 // Island API
 export {

package/src/client/island.ts

@@ -3,7 +3,8 @@
  * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
  */
 
-import type { ReactNode } from "react";
+import type { ReactNode } from "react";
+import { getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Island 정의 타입
@@ -117,18 +118,12 @@ export function island<TServerData, TSetupResult = TServerData>(
  * SSR 데이터에 안전하게 접근하는 훅
  * 서버 데이터가 없는 경우 fallback 반환
  */
-export function useServerData<T>(key: string, fallback: T): T {
-  if (typeof window === "undefined") {
-    return fallback;
-  }
-
-  const manduData = (window as any).__MANDU_DATA__;
-  if (!manduData || !(key in manduData)) {
-    return fallback;
-  }
-
-  return manduData[key] as T;
-}
+export function useServerData<T>(key: string, fallback: T): T {
+  if (typeof window === "undefined") return fallback;
+
+  const data = getGlobalServerData<T>(key);
+  return data === undefined ? fallback : data;
+}
 
 /**
  * Hydration 상태를 추적하는 훅

package/src/client/router.ts

@@ -4,6 +4,16 @@
  */
 
 import type { ReactNode } from "react";
+import {
+  getManduData,
+  getManduRoute,
+  getRouterListeners,
+  getRouterState as getWindowRouterState,
+  setRouterState as setWindowRouterState,
+  setServerData,
+} from "./window-state";
+import { LRUCache } from "../utils/lru-cache";
+import { LIMITS } from "../constants";
 
 // ========== Types ==========
 
@@ -33,51 +43,38 @@ export interface NavigateOptions {
 
 type RouterListener = (state: RouterState) => void;
 
-// ========== Global Router State (모든 모듈에서 동일 인스턴스 공유) ==========
-
-declare global {
-  interface Window {
-    __MANDU_ROUTER_STATE__?: RouterState;
-    __MANDU_ROUTER_LISTENERS__?: Set<RouterListener>;
-  }
-}
-
 function getGlobalRouterState(): RouterState {
   if (typeof window === "undefined") {
     return { currentRoute: null, loaderData: undefined, navigation: { state: "idle" } };
   }
-  if (!window.__MANDU_ROUTER_STATE__) {
+  if (!getWindowRouterState()) {
     // SSR에서 주입된 __MANDU_ROUTE__에서 초기화
-    const route = (window as any).__MANDU_ROUTE__;
-    const data = (window as any).__MANDU_DATA__;
-
-    window.__MANDU_ROUTER_STATE__ = {
-      currentRoute: route ? {
-        id: route.id,
-        pattern: route.pattern,
-        params: route.params || {},
-      } : null,
+    const route = getManduRoute();
+    const data = getManduData();
+
+    setWindowRouterState({
+      currentRoute: route
+        ? {
+            id: route.id,
+            pattern: route.pattern,
+            params: route.params || {},
+          }
+        : null,
       loaderData: route && data?.[route.id]?.serverData,
       navigation: { state: "idle" },
-    };
+    });
   }
-  return window.__MANDU_ROUTER_STATE__;
+  return getWindowRouterState()!;
 }
 
 function setGlobalRouterState(state: RouterState): void {
   if (typeof window !== "undefined") {
-    window.__MANDU_ROUTER_STATE__ = state;
+    setWindowRouterState(state);
   }
 }
 
 function getGlobalListeners(): Set<RouterListener> {
-  if (typeof window === "undefined") {
-    return new Set();
-  }
-  if (!window.__MANDU_ROUTER_LISTENERS__) {
-    window.__MANDU_ROUTER_LISTENERS__ = new Set();
-  }
-  return window.__MANDU_ROUTER_LISTENERS__;
+  return getRouterListeners();
 }
 
 // Getter for routerState (전역 상태 참조)
@@ -91,8 +88,8 @@ const listeners = { get current() { return getGlobalListeners(); } };
 function initializeFromServer(): void {
   if (typeof window === "undefined") return;
 
-  const route = (window as any).__MANDU_ROUTE__;
-  const data = (window as any).__MANDU_DATA__;
+  const route = getManduRoute();
+  const data = getManduData();
 
   if (route) {
     // URL에서 실제 params 추출
@@ -117,7 +114,7 @@ interface CompiledPattern {
   paramNames: string[];
 }
 
-const patternCache = new Map<string, CompiledPattern>();
+const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN_CACHE);
 
 /**
  * 패턴을 정규식으로 컴파일
@@ -237,12 +234,7 @@ export async function navigate(
     });
 
     // __MANDU_DATA__ 업데이트
-    if (typeof window !== "undefined") {
-      (window as any).__MANDU_DATA__ = {
-        ...(window as any).__MANDU_DATA__,
-        [data.routeId]: { serverData: data.loaderData },
-      };
-    }
+    setServerData(data.routeId, data.loaderData);
 
     notifyListeners();
 
@@ -271,7 +263,7 @@ function handlePopState(event: PopStateEvent): void {
     });
   } else {
     // 직접 URL 입력 등으로 방문한 페이지 - 상태만 업데이트
-    const route = (window as any).__MANDU_ROUTE__;
+    const route = getManduRoute();
     setGlobalRouterState({
       currentRoute: route ? {
         id: route.id,
@@ -380,7 +372,7 @@ function handleLinkClick(event: MouseEvent): void {
 
 // ========== Prefetch ==========
 
-const prefetchedUrls = new Set<string>();
+const prefetchedUrls = new LRUCache<string, true>(LIMITS.ROUTER_PREFETCH_CACHE);
 
 /**
  * 페이지 데이터 미리 로드
@@ -391,7 +383,7 @@ export async function prefetch(url: string): Promise<void> {
   try {
     const dataUrl = `${url}${url.includes("?") ? "&" : "?"}_data=1`;
     await fetch(dataUrl, { priority: "low" } as RequestInit);
-    prefetchedUrls.add(url);
+    prefetchedUrls.set(url, true);
   } catch {
     // Prefetch 실패는 무시
   }

package/src/client/runtime.ts

@@ -6,21 +6,7 @@
  * 실제 Hydration Runtime은 bundler/build.ts의 generateRuntimeSource()에서 생성됩니다.
  */
 
-import type { Root } from "react-dom/client";
-
-/**
- * Window 전역 타입 확장
- */
-declare global {
-  interface Window {
-    /** Hydrated React roots (unmount용) */
-    __MANDU_ROOTS__: Map<string, Root>;
-    /** 서버 데이터 */
-    __MANDU_DATA__?: Record<string, { serverData: unknown; timestamp: number }>;
-    /** 직렬화된 서버 데이터 (raw JSON) */
-    __MANDU_DATA_RAW__?: string;
-  }
-}
+import { getHydratedRoots, getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Hydration 상태 추적
@@ -40,18 +26,10 @@ export type HydrationPriority = "immediate" | "visible" | "idle" | "interaction"
 /**
  * 서버 데이터 가져오기
  */
-export function getServerData<T = unknown>(islandId: string): T | undefined {
-  if (typeof window === "undefined") {
-    return undefined;
-  }
-
-  const manduData = window.__MANDU_DATA__;
-  if (!manduData) {
-    return undefined;
-  }
-
-  return manduData[islandId]?.serverData as T;
-}
+export function getServerData<T = unknown>(islandId: string): T | undefined {
+  if (typeof window === "undefined") return undefined;
+  return getGlobalServerData<T>(islandId);
+}
 
 /**
  * Hydration 상태 조회 (DOM 기반)
@@ -84,31 +62,25 @@ export function getHydrationState(): Readonly<HydrationState> {
 /**
  * 특정 Island unmount
  */
-export function unmountIsland(id: string): boolean {
-  if (typeof window === "undefined" || !window.__MANDU_ROOTS__) {
-    return false;
-  }
-
-  const root = window.__MANDU_ROOTS__.get(id);
-  if (!root) {
-    return false;
-  }
-
-  root.unmount();
-  window.__MANDU_ROOTS__.delete(id);
-  return true;
-}
+export function unmountIsland(id: string): boolean {
+  const roots = getHydratedRoots();
+  const root = roots.get(id);
+  if (!root) {
+    return false;
+  }
+
+  root.unmount();
+  roots.delete(id);
+  return true;
+}
 
 /**
  * 모든 Island unmount
  */
-export function unmountAllIslands(): void {
-  if (typeof window === "undefined" || !window.__MANDU_ROOTS__) {
-    return;
-  }
-
-  for (const [id, root] of window.__MANDU_ROOTS__) {
-    root.unmount();
-    window.__MANDU_ROOTS__.delete(id);
-  }
-}
+export function unmountAllIslands(): void {
+  const roots = getHydratedRoots();
+  for (const [id, root] of roots) {
+    root.unmount();
+    roots.delete(id);
+  }
+}