@mandujs/core 0.9.41 → 0.9.43

package/README.ko.md

@@ -215,7 +215,7 @@ import type {
 ## 요구 사항
 
 - Bun >= 1.0.0
-- React >= 18.0.0
+- React >= 19.0.0
 - Zod >= 3.0.0
 
 ## 관련 패키지

package/README.md

@@ -490,7 +490,7 @@ import type {
 ## Requirements
 
 - Bun >= 1.0.0
-- React >= 18.0.0
+- React >= 19.0.0
 - Zod >= 3.0.0
 
 ## Related Packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.41",
+  "version": "0.9.43",
   "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/css.ts

@@ -0,0 +1,283 @@
+/**
+ * Mandu CSS Builder
+ * Tailwind CSS v4 CLI 기반 CSS 빌드 및 감시
+ *
+ * 특징:
+ * - Tailwind v4 Oxide Engine (Rust) 사용
+ * - Zero Config: @import "tailwindcss" 자동 감지
+ * - 출력: .mandu/client/globals.css
+ */
+
+import { spawn, type Subprocess } from "bun";
+import path from "path";
+import fs from "fs/promises";
+
+// ========== Types ==========
+
+export interface CSSBuildOptions {
+  /** 프로젝트 루트 디렉토리 */
+  rootDir: string;
+  /** CSS 입력 파일 (기본: "app/globals.css") */
+  input?: string;
+  /** CSS 출력 파일 (기본: ".mandu/client/globals.css") */
+  output?: string;
+  /** Watch 모드 활성화 */
+  watch?: boolean;
+  /** Minify 활성화 (production) */
+  minify?: boolean;
+  /** 빌드 완료 콜백 */
+  onBuild?: (result: CSSBuildResult) => void;
+  /** 에러 콜백 */
+  onError?: (error: Error) => void;
+}
+
+export interface CSSBuildResult {
+  success: boolean;
+  outputPath: string;
+  buildTime?: number;
+  error?: string;
+}
+
+export interface CSSWatcher {
+  /** Tailwind CLI 프로세스 */
+  process: Subprocess;
+  /** 출력 파일 경로 (절대 경로) */
+  outputPath: string;
+  /** 서버 경로 (/.mandu/client/globals.css) */
+  serverPath: string;
+  /** 프로세스 종료 */
+  close: () => void;
+}
+
+// ========== Constants ==========
+
+const DEFAULT_INPUT = "app/globals.css";
+const DEFAULT_OUTPUT = ".mandu/client/globals.css";
+const SERVER_CSS_PATH = "/.mandu/client/globals.css";
+
+// ========== Detection ==========
+
+/**
+ * Tailwind v4 프로젝트인지 감지
+ * app/globals.css에 @import "tailwindcss" 포함 여부 확인
+ */
+export async function isTailwindProject(rootDir: string): Promise<boolean> {
+  const cssPath = path.join(rootDir, DEFAULT_INPUT);
+
+  try {
+    const content = await fs.readFile(cssPath, "utf-8");
+    // Tailwind v4: @import "tailwindcss"
+    // Tailwind v3: @tailwind base; @tailwind components; @tailwind utilities;
+    return (
+      content.includes('@import "tailwindcss"') ||
+      content.includes("@import 'tailwindcss'") ||
+      content.includes("@tailwind base")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CSS 입력 파일 존재 여부 확인
+ */
+export async function hasCSSEntry(rootDir: string, input?: string): Promise<boolean> {
+  const cssPath = path.join(rootDir, input || DEFAULT_INPUT);
+  try {
+    await fs.access(cssPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ========== Build ==========
+
+/**
+ * CSS 일회성 빌드 (production용)
+ */
+export async function buildCSS(options: CSSBuildOptions): Promise<CSSBuildResult> {
+  const {
+    rootDir,
+    input = DEFAULT_INPUT,
+    output = DEFAULT_OUTPUT,
+    minify = true,
+  } = options;
+
+  const inputPath = path.join(rootDir, input);
+  const outputPath = path.join(rootDir, output);
+  const startTime = performance.now();
+
+  // 출력 디렉토리 생성
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+  // Tailwind CLI 실행
+  const args = [
+    "@tailwindcss/cli",
+    "-i", inputPath,
+    "-o", outputPath,
+  ];
+
+  if (minify) {
+    args.push("--minify");
+  }
+
+  try {
+    const proc = spawn(["bunx", ...args], {
+      cwd: rootDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    // 프로세스 완료 대기
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      return {
+        success: false,
+        outputPath,
+        error: stderr || `Tailwind CLI exited with code ${exitCode}`,
+      };
+    }
+
+    const buildTime = performance.now() - startTime;
+
+    return {
+      success: true,
+      outputPath,
+      buildTime,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      outputPath,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// ========== Watch ==========
+
+/**
+ * CSS 감시 모드 시작 (development용)
+ * Tailwind CLI --watch 모드로 실행
+ */
+export async function startCSSWatch(options: CSSBuildOptions): Promise<CSSWatcher> {
+  const {
+    rootDir,
+    input = DEFAULT_INPUT,
+    output = DEFAULT_OUTPUT,
+    minify = false,
+    onBuild,
+    onError,
+  } = options;
+
+  const inputPath = path.join(rootDir, input);
+  const outputPath = path.join(rootDir, output);
+
+  // 출력 디렉토리 생성
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+  // Tailwind CLI 인자 구성
+  const args = [
+    "@tailwindcss/cli",
+    "-i", inputPath,
+    "-o", outputPath,
+    "--watch",
+  ];
+
+  if (minify) {
+    args.push("--minify");
+  }
+
+  console.log(`🎨 Tailwind CSS v4 빌드 시작...`);
+  console.log(`   입력: ${input}`);
+  console.log(`   출력: ${output}`);
+
+  // Bun subprocess로 Tailwind CLI 실행
+  const proc = spawn(["bunx", ...args], {
+    cwd: rootDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // stdout 모니터링 (빌드 완료 감지)
+  (async () => {
+    const reader = proc.stdout.getReader();
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const text = decoder.decode(value);
+      const lines = text.split("\n").filter((l) => l.trim());
+
+      for (const line of lines) {
+        // Tailwind v4 출력 패턴: "Done in Xms" 또는 빌드 완료 메시지
+        if (line.includes("Done in") || line.includes("Rebuilt in")) {
+          console.log(`   ✅ CSS ${line.trim()}`);
+          onBuild?.({
+            success: true,
+            outputPath,
+          });
+        } else if (line.includes("warn") || line.includes("Warning")) {
+          console.log(`   ⚠️  CSS ${line.trim()}`);
+        }
+      }
+    }
+  })();
+
+  // stderr 모니터링 (에러 감지)
+  (async () => {
+    const reader = proc.stderr.getReader();
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const text = decoder.decode(value).trim();
+      if (text) {
+        // bash_profile 경고는 무시
+        if (text.includes(".bash_profile") || text.includes("$'\\377")) {
+          continue;
+        }
+        console.error(`   ❌ CSS Error: ${text}`);
+        onError?.(new Error(text));
+      }
+    }
+  })();
+
+  // 프로세스 종료 감지
+  proc.exited.then((code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`   ❌ Tailwind CLI exited with code ${code}`);
+    }
+  });
+
+  return {
+    process: proc,
+    outputPath,
+    serverPath: SERVER_CSS_PATH,
+    close: () => {
+      proc.kill();
+    },
+  };
+}
+
+/**
+ * CSS 서버 경로 반환
+ */
+export function getCSSServerPath(): string {
+  return SERVER_CSS_PATH;
+}
+
+/**
+ * CSS 링크 태그 생성
+ */
+export function generateCSSLinkTag(isDev: boolean = false): string {
+  const cacheBust = isDev ? `?t=${Date.now()}` : "";
+  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
+}

package/src/bundler/dev.ts

@@ -6,6 +6,7 @@
 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";
 
@@ -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);
@@ -312,12 +319,15 @@ export interface HMRServer {
 }
 
 export interface HMRMessage {
-  type: "connected" | "reload" | "island-update" | "layout-update" | "error" | "ping";
+  type: "connected" | "reload" | "island-update" | "layout-update" | "css-update" | "error" | "ping" | "guard-violation";
   data?: {
     routeId?: string;
     layoutPath?: string;
+    cssPath?: string;
     message?: string;
     timestamp?: number;
+    file?: string;
+    violations?: Array<{ line: number; message: string }>;
   };
 }
 
@@ -326,7 +336,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,
@@ -410,15 +420,15 @@ export function createHMRServer(port: number): HMRServer {
  * 브라우저에서 실행되어 HMR 서버와 연결
  */
 export function generateHMRClientScript(port: number): string {
-  const hmrPort = port + 1;
+  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 maxReconnectAttempts = ${TIMEOUTS.HMR_MAX_RECONNECT};
+  const reconnectDelay = ${TIMEOUTS.HMR_RECONNECT_DELAY};
 
   function connect() {
     try {
@@ -490,6 +500,21 @@ export function generateHMRClientScript(port: number): string {
         location.reload();
         break;
 
+      case 'css-update':
+        console.log('[Mandu HMR] CSS updated');
+        // CSS 핫 리로드 (페이지 새로고침 없이 스타일시트만 교체)
+        var targetCssPath = message.data?.cssPath || '/.mandu/client/globals.css';
+        var links = document.querySelectorAll('link[rel="stylesheet"]');
+        links.forEach(function(link) {
+          var href = link.getAttribute('href') || '';
+          var baseHref = href.split('?')[0];
+          // 정확한 경로 매칭 우선, fallback으로 기존 패턴 매칭
+          if (baseHref === targetCssPath || href.includes('globals.css') || href.includes('.mandu/client')) {
+            link.setAttribute('href', baseHref + '?t=' + Date.now());
+          }
+        });
+        break;
+
       case 'error':
         console.error('[Mandu HMR] Build error:', message.data?.message);
         showErrorOverlay(message.data?.message);

package/src/bundler/index.ts

@@ -6,3 +6,4 @@
 export * from "./types";
 export * from "./build";
 export * from "./dev";
+export * from "./css";

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 {