@mandujs/core 0.9.42 → 0.9.44

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.42",
+  "version": "0.9.44",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/css.ts

@@ -0,0 +1,302 @@
+/**
+ * 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);
+
+  try {
+    // 출력 디렉토리 생성
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  } catch (error) {
+    const err = new Error(`CSS 출력 디렉토리 생성 실패: ${error instanceof Error ? error.message : error}`);
+    console.error(`❌ ${err.message}`);
+    onError?.(err);
+    throw err;
+  }
+
+  // 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 실행
+  let proc;
+  try {
+    proc = spawn(["bunx", ...args], {
+      cwd: rootDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch (error) {
+    const err = new Error(
+      `Tailwind CLI 실행 실패. @tailwindcss/cli가 설치되어 있는지 확인하세요.\n` +
+      `설치: bun add -d @tailwindcss/cli tailwindcss\n` +
+      `원인: ${error instanceof Error ? error.message : error}`
+    );
+    console.error(`❌ ${err.message}`);
+    onError?.(err);
+    throw err;
+  }
+
+  // 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

@@ -3,12 +3,12 @@
  * 개발 모드 번들링 + HMR (Hot Module Replacement)
  */
 
-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";
+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 {
   /** 프로젝트 루트 */
@@ -274,7 +274,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           clearTimeout(debounceTimer);
         }
 
-        debounceTimer = setTimeout(() => handleFileChange(fullPath), TIMEOUTS.WATCHER_DEBOUNCE);
+        debounceTimer = setTimeout(() => handleFileChange(fullPath), TIMEOUTS.WATCHER_DEBOUNCE);
       });
 
       watchers.push(watcher);
@@ -319,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 }>;
   };
 }
 
@@ -333,7 +336,7 @@ export interface HMRMessage {
  */
 export function createHMRServer(port: number): HMRServer {
   const clients = new Set<any>();
-  const hmrPort = port + PORTS.HMR_OFFSET;
+  const hmrPort = port + PORTS.HMR_OFFSET;
 
   const server = Bun.serve({
     port: hmrPort,
@@ -416,16 +419,16 @@ export function createHMRServer(port: number): HMRServer {
  * HMR 클라이언트 스크립트 생성
  * 브라우저에서 실행되어 HMR 서버와 연결
  */
-export function generateHMRClientScript(port: number): string {
-  const hmrPort = port + PORTS.HMR_OFFSET;
+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 = ${TIMEOUTS.HMR_MAX_RECONNECT};
-  const reconnectDelay = ${TIMEOUTS.HMR_RECONNECT_DELAY};
+  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 {
@@ -497,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/runtime/server.ts

@@ -1,25 +1,25 @@
 import type { Server } from "bun";
-import type { RoutesManifest } from "../spec/schema";
-import type { BundleManifest } from "../bundler/types";
-import type { ManduFilling } from "../filling/filling";
-import { ManduContext } from "../filling/context";
-import { Router } from "./router";
-import { renderSSR, renderStreamingResponse } from "./ssr";
-import { PageBoundary, DefaultLoading, DefaultError, type ErrorFallbackProps } from "./boundary";
-import React, { type ReactNode } from "react";
-import path from "path";
-import fs from "fs/promises";
-import { PORTS } from "../constants";
-import {
-  createNotFoundResponse,
-  createHandlerNotFoundResponse,
-  createPageLoadErrorResponse,
-  createSSRErrorResponse,
-  errorToResponse,
-  err,
-  ok,
-  type Result,
-} from "../error";
+import type { RoutesManifest } from "../spec/schema";
+import type { BundleManifest } from "../bundler/types";
+import type { ManduFilling } from "../filling/filling";
+import { ManduContext } from "../filling/context";
+import { Router } from "./router";
+import { renderSSR, renderStreamingResponse } from "./ssr";
+import { PageBoundary, DefaultLoading, DefaultError, type ErrorFallbackProps } from "./boundary";
+import React, { type ReactNode } from "react";
+import path from "path";
+import fs from "fs/promises";
+import { PORTS } from "../constants";
+import {
+  createNotFoundResponse,
+  createHandlerNotFoundResponse,
+  createPageLoadErrorResponse,
+  createSSRErrorResponse,
+  errorToResponse,
+  err,
+  ok,
+  type Result,
+} from "../error";
 import {
   type CorsOptions,
   isPreflightRequest,
@@ -106,6 +106,13 @@ export interface ServerOptions {
    * - false: 기존 renderToString 사용 (기본값)
    */
   streaming?: boolean;
+  /**
+   * CSS 파일 경로 (SSR 링크 주입용)
+   * - string: 해당 경로로 <link> 주입 (예: "/.mandu/client/globals.css")
+   * - false: CSS 링크 주입 비활성화 (Tailwind 미사용 시)
+   * - undefined: 자동 감지 (.mandu/client/globals.css 존재 시 주입)
+   */
+  cssPath?: string | false;
   /**
    * 커스텀 레지스트리 (핸들러/설정 분리)
    * - 제공하지 않으면 기본 전역 레지스트리 사용
@@ -195,6 +202,13 @@ export interface ServerRegistrySettings {
   publicDir: string;
   cors?: CorsOptions | false;
   streaming: boolean;
+  /**
+   * CSS 파일 경로 (SSR 링크 주입용)
+   * - string: 해당 경로로 <link> 주입
+   * - false: CSS 링크 주입 비활성화
+   * - undefined: 자동 감지 (.mandu/client/globals.css 존재 시 주입)
+   */
+  cssPath?: string | false;
 }
 
 export class ServerRegistry {
@@ -509,34 +523,34 @@ function createDefaultAppFactory(registry: ServerRegistry) {
  * 경로가 허용된 디렉토리 내에 있는지 검증
  * Path traversal 공격 방지
  */
-async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean> {
-  try {
-    const resolvedPath = path.resolve(filePath);
-    const resolvedAllowedDir = path.resolve(allowedDir);
-
-    if (!resolvedPath.startsWith(resolvedAllowedDir + path.sep) &&
-        resolvedPath !== resolvedAllowedDir) {
-      return false;
-    }
-
-    // 파일이 없으면 안전 (존재하지 않는 경로)
-    try {
-      await fs.access(resolvedPath);
-    } catch {
-      return true;
-    }
-
-    // Symlink 해결 후 재검증
-    const realPath = await fs.realpath(resolvedPath);
-    const realAllowedDir = await fs.realpath(resolvedAllowedDir);
-
-    return realPath.startsWith(realAllowedDir + path.sep) ||
-           realPath === realAllowedDir;
-  } catch (error) {
-    console.warn(`[Mandu Security] Path validation failed: ${filePath}`, error);
-    return false;
-  }
-}
+async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean> {
+  try {
+    const resolvedPath = path.resolve(filePath);
+    const resolvedAllowedDir = path.resolve(allowedDir);
+
+    if (!resolvedPath.startsWith(resolvedAllowedDir + path.sep) &&
+        resolvedPath !== resolvedAllowedDir) {
+      return false;
+    }
+
+    // 파일이 없으면 안전 (존재하지 않는 경로)
+    try {
+      await fs.access(resolvedPath);
+    } catch {
+      return true;
+    }
+
+    // Symlink 해결 후 재검증
+    const realPath = await fs.realpath(resolvedPath);
+    const realAllowedDir = await fs.realpath(resolvedAllowedDir);
+
+    return realPath.startsWith(realAllowedDir + path.sep) ||
+           realPath === realAllowedDir;
+  } catch (error) {
+    console.warn(`[Mandu Security] Path validation failed: ${filePath}`, error);
+    return false;
+  }
+}
 
 /**
  * 정적 파일 서빙
@@ -546,73 +560,73 @@ async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean
  *
  * 보안: Path traversal 공격 방지를 위해 모든 경로를 검증합니다.
  */
-async function serveStaticFile(pathname: string, settings: ServerRegistrySettings): Promise<Response | null> {
-  let filePath: string | null = null;
-  let isBundleFile = false;
-  let allowedBaseDir: string;
-  let relativePath: string;
-
-  // Path traversal 시도 조기 차단 (정규화 전 raw 체크)
-  if (pathname.includes("..")) {
-    return null;
-  }
+async function serveStaticFile(pathname: string, settings: ServerRegistrySettings): Promise<Response | null> {
+  let filePath: string | null = null;
+  let isBundleFile = false;
+  let allowedBaseDir: string;
+  let relativePath: string;
+
+  // Path traversal 시도 조기 차단 (정규화 전 raw 체크)
+  if (pathname.includes("..")) {
+    return null;
+  }
 
   // 1. 클라이언트 번들 파일 (/.mandu/client/*)
   if (pathname.startsWith("/.mandu/client/")) {
     // pathname에서 prefix 제거 후 안전하게 조합
-    relativePath = pathname.slice("/.mandu/client/".length);
-    allowedBaseDir = path.join(settings.rootDir, ".mandu", "client");
-    isBundleFile = true;
-  }
-  // 2. Public 폴더 파일 (/public/*)
-  else if (pathname.startsWith("/public/")) {
-    relativePath = pathname.slice("/public/".length);
-    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
-  }
-  // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
-  else if (
-    pathname === "/favicon.ico" ||
-    pathname === "/robots.txt" ||
+    relativePath = pathname.slice("/.mandu/client/".length);
+    allowedBaseDir = path.join(settings.rootDir, ".mandu", "client");
+    isBundleFile = true;
+  }
+  // 2. Public 폴더 파일 (/public/*)
+  else if (pathname.startsWith("/public/")) {
+    relativePath = pathname.slice("/public/".length);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  }
+  // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
+  else if (
+    pathname === "/favicon.ico" ||
+    pathname === "/robots.txt" ||
     pathname === "/sitemap.xml" ||
     pathname === "/manifest.json"
-  ) {
-    // 고정된 파일명만 허용 (이미 위에서 정확히 매칭됨)
-    relativePath = path.basename(pathname);
-    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
-  } else {
-    return null; // 정적 파일이 아님
-  }
-
-  // URL 디코딩 (실패 시 차단)
-  let decodedPath: string;
-  try {
-    decodedPath = decodeURIComponent(relativePath);
-  } catch {
-    return null;
-  }
-
-  // 정규화 + Null byte 방지
-  const normalizedPath = path.posix.normalize(decodedPath);
-  if (normalizedPath.includes("\0")) {
-    console.warn(`[Mandu Security] Null byte attack detected: ${pathname}`);
-    return null;
-  }
-
-  // 선행 슬래시 제거 → path.join이 base를 무시하지 않도록 보장
-  const safeRelativePath = normalizedPath.replace(/^\/+/, "");
-
-  // 상대 경로 탈출 차단
-  if (safeRelativePath.startsWith("..")) {
-    return null;
-  }
-
-  filePath = path.join(allowedBaseDir, safeRelativePath);
-
-  // 최종 경로 검증: 허용된 디렉토리 내에 있는지 확인
-  if (!(await isPathSafe(filePath, allowedBaseDir!))) {
-    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
-    return null;
-  }
+  ) {
+    // 고정된 파일명만 허용 (이미 위에서 정확히 매칭됨)
+    relativePath = path.basename(pathname);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  } else {
+    return null; // 정적 파일이 아님
+  }
+
+  // URL 디코딩 (실패 시 차단)
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(relativePath);
+  } catch {
+    return null;
+  }
+
+  // 정규화 + Null byte 방지
+  const normalizedPath = path.posix.normalize(decodedPath);
+  if (normalizedPath.includes("\0")) {
+    console.warn(`[Mandu Security] Null byte attack detected: ${pathname}`);
+    return null;
+  }
+
+  // 선행 슬래시 제거 → path.join이 base를 무시하지 않도록 보장
+  const safeRelativePath = normalizedPath.replace(/^\/+/, "");
+
+  // 상대 경로 탈출 차단
+  if (safeRelativePath.startsWith("..")) {
+    return null;
+  }
+
+  filePath = path.join(allowedBaseDir, safeRelativePath);
+
+  // 최종 경로 검증: 허용된 디렉토리 내에 있는지 확인
+  if (!(await isPathSafe(filePath, allowedBaseDir!))) {
+    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
+    return null;
+  }
 
   try {
     const file = Bun.file(filePath);
@@ -650,64 +664,64 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
 
 // ========== Request Handler ==========
 
-async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
-  const result = await handleRequestInternal(req, router, registry);
-
-  if (!result.ok) {
-    return errorToResponse(result.error, registry.settings.isDev);
-  }
-
-  return result.value;
-}
-
-async function handleRequestInternal(
-  req: Request,
-  router: Router,
-  registry: ServerRegistry
-): Promise<Result<Response>> {
-  const url = new URL(req.url);
-  const pathname = url.pathname;
-  const settings = registry.settings;
-
-  // 0. CORS Preflight 요청 처리
-  if (settings.cors && isPreflightRequest(req)) {
-    const corsOptions = settings.cors === true ? {} : settings.cors;
-    return ok(handlePreflightRequest(req, corsOptions));
-  }
+async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
+  const result = await handleRequestInternal(req, router, registry);
+
+  if (!result.ok) {
+    return errorToResponse(result.error, registry.settings.isDev);
+  }
+
+  return result.value;
+}
+
+async function handleRequestInternal(
+  req: Request,
+  router: Router,
+  registry: ServerRegistry
+): Promise<Result<Response>> {
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+  const settings = registry.settings;
+
+  // 0. CORS Preflight 요청 처리
+  if (settings.cors && isPreflightRequest(req)) {
+    const corsOptions = settings.cors === true ? {} : settings.cors;
+    return ok(handlePreflightRequest(req, corsOptions));
+  }
 
   // 1. 정적 파일 서빙 시도 (최우선)
-  const staticResponse = await serveStaticFile(pathname, settings);
-  if (staticResponse) {
-    // 정적 파일에도 CORS 헤더 적용
-    if (settings.cors && isCorsRequest(req)) {
-      const corsOptions = settings.cors === true ? {} : settings.cors;
-      return ok(applyCorsToResponse(staticResponse, req, corsOptions));
-    }
-    return ok(staticResponse);
-  }
+  const staticResponse = await serveStaticFile(pathname, settings);
+  if (staticResponse) {
+    // 정적 파일에도 CORS 헤더 적용
+    if (settings.cors && isCorsRequest(req)) {
+      const corsOptions = settings.cors === true ? {} : settings.cors;
+      return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+    }
+    return ok(staticResponse);
+  }
 
   // 2. 라우트 매칭
   const match = router.match(pathname);
 
-  if (!match) {
-    return err(createNotFoundResponse(pathname));
-  }
+  if (!match) {
+    return err(createNotFoundResponse(pathname));
+  }
 
   const { route, params } = match;
 
-  if (route.kind === "api") {
-    const handler = registry.apiHandlers.get(route.id);
-    if (!handler) {
-      return err(createHandlerNotFoundResponse(route.id, route.pattern));
-    }
-    try {
-      const response = await handler(req, params);
-      return ok(response);
-    } catch (errValue) {
-      const error = errValue instanceof Error ? errValue : new Error(String(errValue));
-      return err(createSSRErrorResponse(route.id, route.pattern, error));
-    }
-  }
+  if (route.kind === "api") {
+    const handler = registry.apiHandlers.get(route.id);
+    if (!handler) {
+      return err(createHandlerNotFoundResponse(route.id, route.pattern));
+    }
+    try {
+      const response = await handler(req, params);
+      return ok(response);
+    } catch (errValue) {
+      const error = errValue instanceof Error ? errValue : new Error(String(errValue));
+      return err(createSSRErrorResponse(route.id, route.pattern, error));
+    }
+  }
 
   if (route.kind === "page") {
     let loaderData: unknown;
@@ -718,27 +732,27 @@ async function handleRequestInternal(
 
     // 1. PageHandler 방식 (신규 - filling 포함)
     const pageHandler = registry.pageHandlers.get(route.id);
-    if (pageHandler) {
-      try {
-        const registration = await pageHandler();
-        component = registration.component as RouteComponent;
-        registry.registerRouteComponent(route.id, component);
+    if (pageHandler) {
+      try {
+        const registration = await pageHandler();
+        component = registration.component as RouteComponent;
+        registry.registerRouteComponent(route.id, component);
 
         // Filling의 loader 실행
         if (registration.filling?.hasLoader()) {
           const ctx = new ManduContext(req, params);
           loaderData = await registration.filling.executeLoader(ctx);
         }
-      } catch (error) {
-        const pageError = createPageLoadErrorResponse(
-          route.id,
-          route.pattern,
-          error instanceof Error ? error : new Error(String(error))
-        );
-        console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
-        return err(pageError);
-      }
-    }
+      } catch (error) {
+        const pageError = createPageLoadErrorResponse(
+          route.id,
+          route.pattern,
+          error instanceof Error ? error : new Error(String(error))
+        );
+        console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+        return err(pageError);
+      }
+    }
     // 2. PageLoader 방식 (레거시 호환)
     else {
       const loader = registry.pageLoaders.get(route.id);
@@ -758,28 +772,28 @@ async function handleRequestInternal(
             const ctx = new ManduContext(req, params);
             loaderData = await filling.executeLoader(ctx);
           }
-        } catch (error) {
-          const pageError = createPageLoadErrorResponse(
-            route.id,
-            route.pattern,
-            error instanceof Error ? error : new Error(String(error))
-          );
-          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
-          return err(pageError);
-        }
-      }
-    }
+        } catch (error) {
+          const pageError = createPageLoadErrorResponse(
+            route.id,
+            route.pattern,
+            error instanceof Error ? error : new Error(String(error))
+          );
+          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+          return err(pageError);
+        }
+      }
+    }
 
     // Client-side Routing: 데이터만 반환 (JSON)
-    if (isDataRequest) {
-      return ok(Response.json({
-        routeId: route.id,
-        pattern: route.pattern,
-        params,
-        loaderData: loaderData ?? null,
-        timestamp: Date.now(),
-      }));
-    }
+    if (isDataRequest) {
+      return ok(Response.json({
+        routeId: route.id,
+        pattern: route.pattern,
+        params,
+        loaderData: loaderData ?? null,
+        timestamp: Date.now(),
+      }));
+    }
 
     // SSR 렌더링
     const defaultAppCreator = createDefaultAppFactory(registry);
@@ -808,17 +822,18 @@ async function handleRequestInternal(
         ? route.streaming
         : settings.streaming;
 
-      if (useStreaming) {
-        return ok(await renderStreamingResponse(app, {
-          title: `${route.id} - Mandu`,
-          isDev: settings.isDev,
-          hmrPort: settings.hmrPort,
-          routeId: route.id,
+      if (useStreaming) {
+        return ok(await renderStreamingResponse(app, {
+          title: `${route.id} - Mandu`,
+          isDev: settings.isDev,
+          hmrPort: settings.hmrPort,
+          routeId: route.id,
           routePattern: route.pattern,
           hydration: route.hydration,
           bundleManifest: settings.bundleManifest,
           criticalData: loaderData as Record<string, unknown> | undefined,
           enableClientRouter: true,
+          cssPath: settings.cssPath,
           onShellReady: () => {
             if (settings.isDev) {
               console.log(`[Mandu Streaming] Shell ready: ${route.id}`);
@@ -831,80 +846,134 @@ async function handleRequestInternal(
                 allReadyTime: `${metrics.allReadyTime}ms`,
                 hasError: metrics.hasError,
               });
-            }
-          },
-        }));
-      }
-
-      // 기존 renderToString 방식
-      return ok(renderSSR(app, {
-        title: `${route.id} - Mandu`,
-        isDev: settings.isDev,
-        hmrPort: settings.hmrPort,
-        routeId: route.id,
+            }
+          },
+        }));
+      }
+
+      // 기존 renderToString 방식
+      return ok(renderSSR(app, {
+        title: `${route.id} - Mandu`,
+        isDev: settings.isDev,
+        hmrPort: settings.hmrPort,
+        routeId: route.id,
         hydration: route.hydration,
         bundleManifest: settings.bundleManifest,
         serverData,
-        // Client-side Routing 활성화 정보 전달
-        enableClientRouter: true,
-        routePattern: route.pattern,
-      }));
-    } catch (error) {
-      const ssrError = createSSRErrorResponse(
-        route.id,
-        route.pattern,
-        error instanceof Error ? error : new Error(String(error))
-      );
-      console.error(`[Mandu] ${ssrError.errorType}:`, ssrError.message);
-      return err(ssrError);
-    }
-  }
-
-  return err({
-    errorType: "FRAMEWORK_BUG",
-    code: "MANDU_F003",
-    httpStatus: 500,
-    message: `Unknown route kind: ${route.kind}`,
-    summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
-    fix: {
-      file: "spec/routes.manifest.json",
-      suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
-    },
-    route: {
-      id: route.id,
-      pattern: route.pattern,
-    },
-    timestamp: new Date().toISOString(),
-  });
-}
+        // Client-side Routing 활성화 정보 전달
+        enableClientRouter: true,
+        routePattern: route.pattern,
+        cssPath: settings.cssPath,
+      }));
+    } catch (error) {
+      const ssrError = createSSRErrorResponse(
+        route.id,
+        route.pattern,
+        error instanceof Error ? error : new Error(String(error))
+      );
+      console.error(`[Mandu] ${ssrError.errorType}:`, ssrError.message);
+      return err(ssrError);
+    }
+  }
+
+  return err({
+    errorType: "FRAMEWORK_BUG",
+    code: "MANDU_F003",
+    httpStatus: 500,
+    message: `Unknown route kind: ${route.kind}`,
+    summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
+    fix: {
+      file: "spec/routes.manifest.json",
+      suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
+    },
+    route: {
+      id: route.id,
+      pattern: route.pattern,
+    },
+    timestamp: new Date().toISOString(),
+  });
+}
+
+// ========== Port Selection ==========
+
+const MAX_PORT_ATTEMPTS = 10;
+
+function isPortInUseError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as { code?: string }).code;
+  const message = (error as { message?: string }).message ?? "";
+  return code === "EADDRINUSE" || message.includes("EADDRINUSE") || message.includes("address already in use");
+}
+
+function startBunServerWithFallback(options: {
+  port: number;
+  hostname?: string;
+  fetch: (req: Request) => Promise<Response>;
+}): { server: Server; port: number; attempts: number } {
+  const { port: startPort, hostname, fetch } = options;
+  let lastError: unknown = null;
+
+  for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+    const candidate = startPort + attempt;
+    if (candidate < 1 || candidate > 65535) {
+      continue;
+    }
+    try {
+      const server = Bun.serve({
+        port: candidate,
+        hostname,
+        fetch,
+      });
+      return { server, port: server.port ?? candidate, attempts: attempt };
+    } catch (error) {
+      if (!isPortInUseError(error)) {
+        throw error;
+      }
+      lastError = error;
+    }
+  }
+
+  throw lastError ?? new Error(`No available port found starting at ${startPort}`);
+}
 
 // ========== Server Startup ==========
 
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
-  const {
-    port = 3000,
-    hostname = "localhost",
-    rootDir = process.cwd(),
-    isDev = false,
+  const {
+    port = 3000,
+    hostname = "localhost",
+    rootDir = process.cwd(),
+    isDev = false,
     hmrPort,
     bundleManifest,
     publicDir = "public",
     cors = false,
     streaming = false,
+    cssPath: cssPathOption,
     registry = defaultRegistry,
   } = options;
 
-  // CORS 옵션 파싱
-  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
-
-  if (!isDev && cors === true) {
-    console.warn("⚠️  [Security Warning] CORS is set to allow all origins.");
-    console.warn("   This is not recommended for production environments.");
-    console.warn("   Consider specifying allowed origins explicitly:");
-    console.warn("   cors: { origin: ['https://yourdomain.com'] }");
-  }
-
-  // Registry settings 저장
+  // cssPath 처리:
+  // - string: 해당 경로로 <link> 주입
+  // - false: CSS 링크 주입 비활성화
+  // - undefined: false로 처리 (기본적으로 링크 미삽입 - 404 방지)
+  //
+  // dev/build에서 Tailwind 감지 시 명시적으로 cssPath 전달 필요:
+  // - dev.ts: cssPath: hasTailwind ? cssWatcher?.serverPath : false
+  // - 프로덕션: 빌드 후 .mandu/client/globals.css 존재 시 경로 전달
+  const cssPath: string | false = cssPathOption ?? false;
+
+  // CORS 옵션 파싱
+  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
+
+  if (!isDev && cors === true) {
+    console.warn("⚠️  [Security Warning] CORS is set to allow all origins.");
+    console.warn("   This is not recommended for production environments.");
+    console.warn("   Consider specifying allowed origins explicitly:");
+    console.warn("   cors: { origin: ['https://yourdomain.com'] }");
+  }
+
+  // Registry settings 저장 (초기값)
   registry.settings = {
     isDev,
     hmrPort,
@@ -913,6 +982,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     publicDir,
     cors: corsOptions,
     streaming,
+    cssPath,
   };
 
   const router = new Router(manifest.routes);
@@ -929,17 +999,25 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     return response;
   };
 
-  const server = Bun.serve({
+  const { server, port: actualPort, attempts } = startBunServerWithFallback({
     port,
     hostname,
     fetch: fetchHandler,
   });
 
+  if (attempts > 0) {
+    console.warn(`⚠️  Port ${port} is in use. Using ${actualPort} instead.`);
+  }
+
+  if (hmrPort !== undefined && hmrPort === port && actualPort !== port) {
+    registry.settings = { ...registry.settings, hmrPort: actualPort };
+  }
+
   if (isDev) {
-    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${port}`);
-    if (hmrPort) {
-      console.log(`🔥 HMR enabled on port ${hmrPort + PORTS.HMR_OFFSET}`);
-    }
+    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${actualPort}`);
+    if (registry.settings.hmrPort) {
+      console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
+    }
     console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
     if (corsOptions) {
       console.log(`🌐 CORS enabled`);
@@ -948,7 +1026,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
       console.log(`🌊 Streaming SSR enabled`);
     }
   } else {
-    console.log(`🥟 Mandu server running at http://${hostname}:${port}`);
+    console.log(`🥟 Mandu server running at http://${hostname}:${actualPort}`);
     if (streaming) {
       console.log(`🌊 Streaming SSR enabled`);
     }

package/src/runtime/ssr.ts

@@ -43,6 +43,8 @@ export interface SSROptions {
   enableClientRouter?: boolean;
   /** 라우트 패턴 (Client-side Routing용) */
   routePattern?: string;
+  /** CSS 파일 경로 (자동 주입, 기본: /.mandu/client/globals.css) */
+  cssPath?: string | false;
 }
 
 /**
@@ -151,8 +153,16 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     hmrPort,
     enableClientRouter = false,
     routePattern,
+    cssPath,
   } = options;
 
+  // CSS 링크 태그 생성
+  // - cssPath가 string이면 해당 경로 사용
+  // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
+  const cssLinkTag = cssPath && cssPath !== false
+    ? `<link rel="stylesheet" href="${cssPath}${isDev ? `?t=${Date.now()}` : ""}">`
+    : "";
+
   let content = renderToString(element);
 
   // Island 래퍼 적용 (hydration 필요 시)
@@ -208,6 +218,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${cssLinkTag}
   ${headTags}
 </head>
 <body>

package/src/runtime/streaming-ssr.ts

@@ -138,6 +138,8 @@ export interface StreamingSSROptions {
    * true이면 </body></html>을 생략하여 deferred 스크립트 삽입 지점 확보
    */
   _skipHtmlClose?: boolean;
+  /** CSS 파일 경로 (자동 주입, 기본: /.mandu/client/globals.css) */
+  cssPath?: string | false;
 }
 
 export interface StreamingLoaderResult<T = unknown> {
@@ -367,8 +369,17 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     bundleManifest,
     routeId,
     hydration,
+    cssPath,
+    isDev = false,
   } = options;
 
+  // CSS 링크 태그 생성
+  // - cssPath가 string이면 해당 경로 사용
+  // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
+  const cssLinkTag = cssPath && cssPath !== false
+    ? `<link rel="stylesheet" href="${cssPath}${isDev ? `?t=${Date.now()}` : ""}">`
+    : "";
+
   // Import map (module scripts 전에 위치해야 함)
   let importMapScript = "";
   if (bundleManifest?.importMap && Object.keys(bundleManifest.importMap.imports).length > 0) {
@@ -414,6 +425,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${cssLinkTag}
   ${loadingStyles}
   ${importMapScript}
   ${headTags}