@mandujs/core 0.5.7 → 0.6.0

package/package.json

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

package/src/bundler/build.ts

@@ -279,6 +279,223 @@ export default jsxDevRuntime;
 `;
 }
 
+/**
+ * Client-side Router 런타임 소스 생성
+ */
+function generateRouterRuntimeSource(): string {
+  return `
+/**
+ * Mandu Client Router Runtime (Generated)
+ * Client-side Routing을 위한 런타임
+ */
+
+// 라우트 정보
+let currentRoute = window.__MANDU_ROUTE__ || null;
+let currentLoaderData = window.__MANDU_DATA__?.[currentRoute?.id]?.serverData;
+let navigationState = { state: 'idle' };
+const listeners = new Set();
+
+// 패턴 매칭 캐시
+const patternCache = new Map();
+
+function compilePattern(pattern) {
+  if (patternCache.has(pattern)) return patternCache.get(pattern);
+
+  const paramNames = [];
+  let paramIndex = 0;
+  const paramMatches = [];
+
+  const withPlaceholders = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+    paramMatches.push(name);
+    return '%%PARAM%%';
+  });
+
+  const escaped = withPlaceholders.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&');
+  const regexStr = escaped.replace(/%%PARAM%%/g, () => {
+    paramNames.push(paramMatches[paramIndex++]);
+    return '([^/]+)';
+  });
+
+  const compiled = { regex: new RegExp('^' + regexStr + '$'), paramNames };
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+
+function extractParams(pattern, pathname) {
+  const compiled = compilePattern(pattern);
+  const match = pathname.match(compiled.regex);
+  if (!match) return {};
+
+  const params = {};
+  compiled.paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
+  return params;
+}
+
+function notifyListeners() {
+  const state = {
+    currentRoute,
+    loaderData: currentLoaderData,
+    navigation: navigationState
+  };
+  listeners.forEach(fn => { try { fn(state); } catch(e) {} });
+}
+
+export function subscribe(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getRouterState() {
+  return {
+    currentRoute,
+    loaderData: currentLoaderData,
+    navigation: navigationState
+  };
+}
+
+export async function navigate(to, options = {}) {
+  const { replace = false, scroll = true } = options;
+
+  try {
+    const url = new URL(to, location.origin);
+    if (url.origin !== location.origin) {
+      location.href = to;
+      return;
+    }
+
+    navigationState = { state: 'loading', location: to };
+    notifyListeners();
+
+    const dataUrl = url.pathname + (url.search ? url.search + '&' : '?') + '_data=1';
+    const res = await fetch(dataUrl);
+
+    if (!res.ok) {
+      location.href = to;
+      return;
+    }
+
+    const data = await res.json();
+
+    if (replace) {
+      history.replaceState({ routeId: data.routeId }, '', to);
+    } else {
+      history.pushState({ routeId: data.routeId }, '', to);
+    }
+
+    currentRoute = { id: data.routeId, pattern: data.pattern, params: data.params };
+    currentLoaderData = data.loaderData;
+    navigationState = { state: 'idle' };
+
+    window.__MANDU_DATA__ = window.__MANDU_DATA__ || {};
+    window.__MANDU_DATA__[data.routeId] = { serverData: data.loaderData };
+
+    notifyListeners();
+
+    if (scroll) window.scrollTo(0, 0);
+  } catch (err) {
+    console.error('[Mandu Router] Error:', err);
+    location.href = to;
+  }
+}
+
+// Link 클릭 핸들러
+function handleClick(e) {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+
+  const anchor = e.target.closest('a[data-mandu-link]');
+  if (!anchor) return;
+
+  const href = anchor.getAttribute('href');
+  if (!href) return;
+
+  try {
+    const url = new URL(href, location.origin);
+    if (url.origin !== location.origin) return;
+  } catch { return; }
+
+  e.preventDefault();
+  navigate(href);
+}
+
+// Popstate 핸들러
+function handlePopState(e) {
+  if (e.state?.routeId) {
+    navigate(location.pathname + location.search, { replace: true, scroll: false });
+  }
+}
+
+// 초기화
+function init() {
+  if (currentRoute) {
+    currentRoute.params = extractParams(currentRoute.pattern, location.pathname);
+  }
+
+  window.addEventListener('popstate', handlePopState);
+  document.addEventListener('click', handleClick);
+  console.log('[Mandu Router] Initialized');
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', init);
+} else {
+  init();
+}
+
+export { currentRoute, currentLoaderData, navigationState };
+`;
+}
+
+/**
+ * Router 런타임 번들 빌드
+ */
+async function buildRouterRuntime(
+  outDir: string,
+  options: BundlerOptions
+): Promise<{ success: boolean; outputPath: string; errors: string[] }> {
+  const routerPath = path.join(outDir, "_router.src.js");
+  const outputName = "_router.js";
+
+  try {
+    await Bun.write(routerPath, generateRouterRuntimeSource());
+
+    const result = await Bun.build({
+      entrypoints: [routerPath],
+      outdir: outDir,
+      naming: outputName,
+      minify: options.minify ?? process.env.NODE_ENV === "production",
+      sourcemap: options.sourcemap ? "external" : "none",
+      target: "browser",
+      define: {
+        "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
+        ...options.define,
+      },
+    });
+
+    await fs.unlink(routerPath).catch(() => {});
+
+    if (!result.success) {
+      return {
+        success: false,
+        outputPath: "",
+        errors: result.logs.map((l) => l.message),
+      };
+    }
+
+    return {
+      success: true,
+      outputPath: `/.mandu/client/${outputName}`,
+      errors: [],
+    };
+  } catch (error) {
+    await fs.unlink(routerPath).catch(() => {});
+    return {
+      success: false,
+      outputPath: "",
+      errors: [String(error)],
+    };
+  }
+}
+
 /**
  * Island 엔트리 래퍼 생성
  */
@@ -503,6 +720,7 @@ function createBundleManifest(
   routes: RouteSpec[],
   runtimePath: string,
   vendorResult: VendorBuildResult,
+  routerPath: string,
   env: "development" | "production"
 ): BundleManifest {
   const bundles: BundleManifest["bundles"] = {};
@@ -526,6 +744,7 @@ function createBundleManifest(
     shared: {
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
+      router: routerPath, // Client-side Router
     },
     importMap: {
       imports: {
@@ -623,6 +842,12 @@ export async function buildClientBundles(
     errors.push(...runtimeResult.errors.map((e) => `[Runtime] ${e}`));
   }
 
+  // 3.5. Client-side Router 런타임 빌드
+  const routerResult = await buildRouterRuntime(outDir, options);
+  if (!routerResult.success) {
+    errors.push(...routerResult.errors.map((e) => `[Router] ${e}`));
+  }
+
   // 4. Vendor shim 번들 빌드 (React, ReactDOM, ReactDOMClient)
   const vendorResult = await buildVendorShims(outDir, options);
   if (!vendorResult.success) {
@@ -645,6 +870,7 @@ export async function buildClientBundles(
     hydratedRoutes,
     runtimeResult.outputPath,
     vendorResult,
+    routerResult.outputPath,
     env
   );
 

package/src/bundler/types.ts

@@ -59,6 +59,8 @@ export interface BundleManifest {
     runtime: string;
     /** React 번들 경로 */
     vendor: string;
+    /** Client-side Router 런타임 */
+    router?: string;
   };
   /** Import map for bare specifiers (react, react-dom, etc.) */
   importMap?: {

package/src/client/Link.tsx

@@ -0,0 +1,209 @@
+/**
+ * Mandu Link Component 🔗
+ * Client-side 네비게이션을 위한 Link 컴포넌트
+ */
+
+import React, {
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { navigate, prefetch } from "./router";
+
+export interface LinkProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** 이동할 URL */
+  href: string;
+  /** history.replaceState 사용 여부 */
+  replace?: boolean;
+  /** 마우스 hover 시 prefetch 여부 */
+  prefetch?: boolean;
+  /** 스크롤 위치 복원 여부 (기본: true) */
+  scroll?: boolean;
+  /** 자식 요소 */
+  children?: ReactNode;
+}
+
+/**
+ * Client-side 네비게이션 Link 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { Link } from "@mandujs/core/client";
+ *
+ * // 기본 사용
+ * <Link href="/about">About</Link>
+ *
+ * // Prefetch 활성화
+ * <Link href="/users" prefetch>Users</Link>
+ *
+ * // Replace 모드 (뒤로가기 히스토리 없음)
+ * <Link href="/login" replace>Login</Link>
+ * ```
+ */
+export function Link({
+  href,
+  replace = false,
+  prefetch: shouldPrefetch = false,
+  scroll = true,
+  children,
+  onClick,
+  onMouseEnter,
+  onFocus,
+  ...rest
+}: LinkProps): React.ReactElement {
+  const prefetchedRef = useRef(false);
+
+  // 클릭 핸들러
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      // 사용자 정의 onClick 먼저 실행
+      onClick?.(event);
+
+      // 기본 동작 방지 조건
+      if (
+        event.defaultPrevented ||
+        event.button !== 0 ||
+        event.metaKey ||
+        event.altKey ||
+        event.ctrlKey ||
+        event.shiftKey
+      ) {
+        return;
+      }
+
+      // 외부 링크 체크
+      try {
+        const url = new URL(href, window.location.origin);
+        if (url.origin !== window.location.origin) {
+          return; // 외부 링크는 기본 동작
+        }
+      } catch {
+        return;
+      }
+
+      // Client-side 네비게이션
+      event.preventDefault();
+      navigate(href, { replace, scroll });
+    },
+    [href, replace, scroll, onClick]
+  );
+
+  // Prefetch 실행
+  const doPrefetch = useCallback(() => {
+    if (!shouldPrefetch || prefetchedRef.current) return;
+
+    try {
+      const url = new URL(href, window.location.origin);
+      if (url.origin === window.location.origin) {
+        prefetch(href);
+        prefetchedRef.current = true;
+      }
+    } catch {
+      // 무시
+    }
+  }, [href, shouldPrefetch]);
+
+  // 마우스 hover 핸들러
+  const handleMouseEnter = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(event);
+      doPrefetch();
+    },
+    [onMouseEnter, doPrefetch]
+  );
+
+  // 포커스 핸들러 (키보드 네비게이션)
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(event);
+      doPrefetch();
+    },
+    [onFocus, doPrefetch]
+  );
+
+  // Viewport 진입 시 prefetch (IntersectionObserver)
+  useEffect(() => {
+    if (!shouldPrefetch || typeof IntersectionObserver === "undefined") {
+      return;
+    }
+
+    // ref가 없으면 무시 (SSR)
+    return;
+  }, [shouldPrefetch]);
+
+  return (
+    <a
+      href={href}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      onFocus={handleFocus}
+      data-mandu-link=""
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+/**
+ * NavLink - 현재 경로와 일치할 때 활성 스타일 적용
+ *
+ * @example
+ * ```tsx
+ * import { NavLink } from "@mandujs/core/client";
+ *
+ * <NavLink
+ *   href="/about"
+ *   className={({ isActive }) => isActive ? "active" : ""}
+ * >
+ *   About
+ * </NavLink>
+ * ```
+ */
+export interface NavLinkProps extends Omit<LinkProps, "className" | "style"> {
+  /** 활성 상태에 따른 className */
+  className?: string | ((props: { isActive: boolean }) => string);
+  /** 활성 상태에 따른 style */
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+  /** 정확히 일치해야 활성화 (기본: false) */
+  exact?: boolean;
+}
+
+export function NavLink({
+  href,
+  className,
+  style,
+  exact = false,
+  ...rest
+}: NavLinkProps): React.ReactElement {
+  // 현재 경로와 비교
+  const isActive =
+    typeof window !== "undefined"
+      ? exact
+        ? window.location.pathname === href
+        : window.location.pathname.startsWith(href)
+      : false;
+
+  const resolvedClassName =
+    typeof className === "function" ? className({ isActive }) : className;
+
+  const resolvedStyle =
+    typeof style === "function" ? style({ isActive }) : style;
+
+  return (
+    <Link
+      href={href}
+      className={resolvedClassName}
+      style={resolvedStyle}
+      {...rest}
+    />
+  );
+}
+
+export default Link;

package/src/client/hooks.ts

@@ -0,0 +1,267 @@
+/**
+ * Mandu Router Hooks 🪝
+ * React hooks for client-side routing
+ */
+
+import { useState, useEffect, useCallback, useSyncExternalStore } from "react";
+import {
+  subscribe,
+  getRouterState,
+  getCurrentRoute,
+  getLoaderData,
+  getNavigationState,
+  navigate,
+  type RouteInfo,
+  type NavigationState,
+  type NavigateOptions,
+} from "./router";
+
+/**
+ * 라우터 상태 전체 접근
+ *
+ * @example
+ * ```tsx
+ * const { currentRoute, loaderData, navigation } = useRouterState();
+ * ```
+ */
+export function useRouterState() {
+  return useSyncExternalStore(
+    subscribe,
+    getRouterState,
+    getRouterState // SSR에서도 동일
+  );
+}
+
+/**
+ * 현재 라우트 정보
+ *
+ * @example
+ * ```tsx
+ * const route = useRoute();
+ * console.log(route?.id, route?.params);
+ * ```
+ */
+export function useRoute(): RouteInfo | null {
+  const state = useRouterState();
+  return state.currentRoute;
+}
+
+/**
+ * URL 파라미터 접근
+ *
+ * @example
+ * ```tsx
+ * // URL: /users/123
+ * const { id } = useParams<{ id: string }>();
+ * console.log(id); // "123"
+ * ```
+ */
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+  const route = useRoute();
+  return (route?.params ?? {}) as T;
+}
+
+/**
+ * 현재 경로명
+ *
+ * @example
+ * ```tsx
+ * const pathname = usePathname();
+ * console.log(pathname); // "/users/123"
+ * ```
+ */
+export function usePathname(): string {
+  const [pathname, setPathname] = useState(() =>
+    typeof window !== "undefined" ? window.location.pathname : "/"
+  );
+
+  useEffect(() => {
+    const handleChange = () => {
+      setPathname(window.location.pathname);
+    };
+
+    window.addEventListener("popstate", handleChange);
+
+    // 라우터 상태 변경 구독
+    const unsubscribe = subscribe(() => {
+      setPathname(window.location.pathname);
+    });
+
+    return () => {
+      window.removeEventListener("popstate", handleChange);
+      unsubscribe();
+    };
+  }, []);
+
+  return pathname;
+}
+
+/**
+ * 현재 검색 파라미터 (쿼리 스트링)
+ *
+ * @example
+ * ```tsx
+ * // URL: /search?q=hello&page=2
+ * const searchParams = useSearchParams();
+ * console.log(searchParams.get("q")); // "hello"
+ * ```
+ */
+export function useSearchParams(): URLSearchParams {
+  const [searchParams, setSearchParams] = useState(() =>
+    typeof window !== "undefined"
+      ? new URLSearchParams(window.location.search)
+      : new URLSearchParams()
+  );
+
+  useEffect(() => {
+    const handleChange = () => {
+      setSearchParams(new URLSearchParams(window.location.search));
+    };
+
+    window.addEventListener("popstate", handleChange);
+
+    const unsubscribe = subscribe(() => {
+      setSearchParams(new URLSearchParams(window.location.search));
+    });
+
+    return () => {
+      window.removeEventListener("popstate", handleChange);
+      unsubscribe();
+    };
+  }, []);
+
+  return searchParams;
+}
+
+/**
+ * Loader 데이터 접근
+ *
+ * @example
+ * ```tsx
+ * interface UserData { name: string; email: string; }
+ * const data = useLoaderData<UserData>();
+ * ```
+ */
+export function useLoaderData<T = unknown>(): T | undefined {
+  const state = useRouterState();
+  return state.loaderData as T | undefined;
+}
+
+/**
+ * 네비게이션 상태 (로딩 여부)
+ *
+ * @example
+ * ```tsx
+ * const { state, location } = useNavigation();
+ *
+ * if (state === "loading") {
+ *   return <Spinner />;
+ * }
+ * ```
+ */
+export function useNavigation(): NavigationState {
+  const state = useRouterState();
+  return state.navigation;
+}
+
+/**
+ * 프로그래매틱 네비게이션
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate();
+ *
+ * const handleClick = () => {
+ *   navigate("/dashboard");
+ * };
+ *
+ * const handleSubmit = () => {
+ *   navigate("/success", { replace: true });
+ * };
+ * ```
+ */
+export function useNavigate(): (to: string, options?: NavigateOptions) => Promise<void> {
+  return useCallback((to: string, options?: NavigateOptions) => {
+    return navigate(to, options);
+  }, []);
+}
+
+/**
+ * 라우터 통합 훅 (편의용)
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   pathname,
+ *   params,
+ *   searchParams,
+ *   navigate,
+ *   isNavigating
+ * } = useRouter();
+ * ```
+ */
+export function useRouter() {
+  const pathname = usePathname();
+  const params = useParams();
+  const searchParams = useSearchParams();
+  const navigation = useNavigation();
+  const navigateFn = useNavigate();
+
+  return {
+    /** 현재 경로명 */
+    pathname,
+    /** URL 파라미터 */
+    params,
+    /** 검색 파라미터 (쿼리 스트링) */
+    searchParams,
+    /** 네비게이션 함수 */
+    navigate: navigateFn,
+    /** 네비게이션 중 여부 */
+    isNavigating: navigation.state === "loading",
+    /** 네비게이션 상태 상세 */
+    navigation,
+  };
+}
+
+/**
+ * 특정 경로와 현재 경로 일치 여부
+ *
+ * @example
+ * ```tsx
+ * const isActive = useMatch("/about");
+ * const isUsersPage = useMatch("/users/:id");
+ * ```
+ */
+export function useMatch(pattern: string): boolean {
+  const pathname = usePathname();
+
+  // 간단한 패턴 매칭 (파라미터 고려)
+  const regexStr = pattern
+    .replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, "[^/]+")
+    .replace(/\//g, "\\/");
+
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(pathname);
+}
+
+/**
+ * 뒤로 가기
+ */
+export function useGoBack(): () => void {
+  return useCallback(() => {
+    if (typeof window !== "undefined") {
+      window.history.back();
+    }
+  }, []);
+}
+
+/**
+ * 앞으로 가기
+ */
+export function useGoForward(): () => void {
+  return useCallback(() => {
+    if (typeof window !== "undefined") {
+      window.history.forward();
+    }
+  }, []);
+}

package/src/client/index.ts

@@ -1,10 +1,10 @@
 /**
  * Mandu Client Module 🏝️
- * 클라이언트 사이드 hydration을 위한 API
+ * 클라이언트 사이드 hydration 및 라우팅을 위한 API
  *
  * @example
  * ```typescript
- * // spec/slots/todos.client.ts
+ * // Island 컴포넌트
  * import { Mandu } from "@mandujs/core/client";
  *
  * export default Mandu.island<TodosData>({
@@ -12,6 +12,17 @@
  *   render: (props) => <TodoList {...props} />
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Client-side 라우팅
+ * import { Link, useRouter } from "@mandujs/core/client";
+ *
+ * function Nav() {
+ *   const { pathname, navigate } = useRouter();
+ *   return <Link href="/about">About</Link>;
+ * }
+ * ```
  */
 
 // Island API
@@ -42,9 +53,47 @@ export {
   type IslandLoader,
 } from "./runtime";
 
+// Client-side Router API
+export {
+  navigate,
+  prefetch,
+  subscribe,
+  getRouterState,
+  getCurrentRoute,
+  getLoaderData,
+  getNavigationState,
+  initializeRouter,
+  cleanupRouter,
+  type RouteInfo,
+  type NavigationState,
+  type RouterState,
+  type NavigateOptions,
+} from "./router";
+
+// Link Components
+export { Link, NavLink, type LinkProps, type NavLinkProps } from "./Link";
+
+// Router Hooks
+export {
+  useRouter,
+  useRoute,
+  useParams,
+  usePathname,
+  useSearchParams,
+  useLoaderData,
+  useNavigation,
+  useNavigate,
+  useMatch,
+  useGoBack,
+  useGoForward,
+  useRouterState,
+} from "./hooks";
+
 // Re-export as Mandu namespace for consistent API
 import { island, wrapComponent } from "./island";
 import { hydrateIslands, initializeRuntime } from "./runtime";
+import { navigate, prefetch, initializeRouter } from "./router";
+import { Link, NavLink } from "./Link";
 
 /**
  * Mandu Client namespace
@@ -73,4 +122,34 @@ export const Mandu = {
    * @see initializeRuntime
    */
   init: initializeRuntime,
+
+  /**
+   * Navigate to a URL (client-side)
+   * @see navigate
+   */
+  navigate,
+
+  /**
+   * Prefetch a URL for faster navigation
+   * @see prefetch
+   */
+  prefetch,
+
+  /**
+   * Initialize the client-side router
+   * @see initializeRouter
+   */
+  initRouter: initializeRouter,
+
+  /**
+   * Link component for client-side navigation
+   * @see Link
+   */
+  Link,
+
+  /**
+   * NavLink component with active state
+   * @see NavLink
+   */
+  NavLink,
 };

package/src/client/router.ts

@@ -0,0 +1,387 @@
+/**
+ * Mandu Client-side Router 🧭
+ * SPA 스타일 네비게이션을 위한 클라이언트 라우터
+ */
+
+import type { ReactNode } from "react";
+
+// ========== Types ==========
+
+export interface RouteInfo {
+  id: string;
+  pattern: string;
+  params: Record<string, string>;
+}
+
+export interface NavigationState {
+  state: "idle" | "loading";
+  location?: string;
+}
+
+export interface RouterState {
+  currentRoute: RouteInfo | null;
+  loaderData: unknown;
+  navigation: NavigationState;
+}
+
+export interface NavigateOptions {
+  /** history.replaceState 사용 여부 */
+  replace?: boolean;
+  /** 스크롤 위치 복원 여부 */
+  scroll?: boolean;
+}
+
+type RouterListener = (state: RouterState) => void;
+
+// ========== Router State ==========
+
+let routerState: RouterState = {
+  currentRoute: null,
+  loaderData: undefined,
+  navigation: { state: "idle" },
+};
+
+const listeners = new Set<RouterListener>();
+
+/**
+ * 초기화: 서버에서 전달된 라우트 정보로 상태 설정
+ */
+function initializeFromServer(): void {
+  if (typeof window === "undefined") return;
+
+  const route = (window as any).__MANDU_ROUTE__;
+  const data = (window as any).__MANDU_DATA__;
+
+  if (route) {
+    // URL에서 실제 params 추출
+    const params = extractParamsFromPath(route.pattern, window.location.pathname);
+
+    routerState = {
+      currentRoute: {
+        id: route.id,
+        pattern: route.pattern,
+        params,
+      },
+      loaderData: data?.[route.id]?.serverData,
+      navigation: { state: "idle" },
+    };
+  }
+}
+
+// ========== Pattern Matching ==========
+
+interface CompiledPattern {
+  regex: RegExp;
+  paramNames: string[];
+}
+
+const patternCache = new Map<string, CompiledPattern>();
+
+/**
+ * 패턴을 정규식으로 컴파일
+ */
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  const paramNames: string[] = [];
+  const PARAM_PLACEHOLDER = "\x00PARAM\x00";
+  const paramMatches: string[] = [];
+
+  const withPlaceholders = pattern.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)/g,
+    (_, paramName) => {
+      paramMatches.push(paramName);
+      return PARAM_PLACEHOLDER;
+    }
+  );
+
+  const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+
+  let paramIndex = 0;
+  const regexStr = escaped.replace(
+    new RegExp(PARAM_PLACEHOLDER.replace(/\x00/g, "\\x00"), "g"),
+    () => {
+      paramNames.push(paramMatches[paramIndex++]);
+      return "([^/]+)";
+    }
+  );
+
+  const compiled = {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
+  };
+
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * 패턴에서 파라미터 추출
+ */
+function extractParamsFromPath(
+  pattern: string,
+  pathname: string
+): Record<string, string> {
+  const compiled = compilePattern(pattern);
+  const match = pathname.match(compiled.regex);
+
+  if (!match) return {};
+
+  const params: Record<string, string> = {};
+  compiled.paramNames.forEach((name, index) => {
+    params[name] = match[index + 1];
+  });
+
+  return params;
+}
+
+// ========== Navigation ==========
+
+/**
+ * 페이지 네비게이션
+ */
+export async function navigate(
+  to: string,
+  options: NavigateOptions = {}
+): Promise<void> {
+  const { replace = false, scroll = true } = options;
+
+  try {
+    const url = new URL(to, window.location.origin);
+
+    // 외부 URL은 일반 네비게이션
+    if (url.origin !== window.location.origin) {
+      window.location.href = to;
+      return;
+    }
+
+    // 로딩 상태 시작
+    routerState = {
+      ...routerState,
+      navigation: { state: "loading", location: to },
+    };
+    notifyListeners();
+
+    // 데이터 fetch
+    const dataUrl = `${url.pathname}${url.search ? url.search + "&" : "?"}_data=1`;
+    const response = await fetch(dataUrl);
+
+    if (!response.ok) {
+      // 에러 시 full navigation fallback
+      window.location.href = to;
+      return;
+    }
+
+    const data = await response.json();
+
+    // History 업데이트
+    const historyState = { routeId: data.routeId, params: data.params };
+    if (replace) {
+      history.replaceState(historyState, "", to);
+    } else {
+      history.pushState(historyState, "", to);
+    }
+
+    // 상태 업데이트
+    routerState = {
+      currentRoute: {
+        id: data.routeId,
+        pattern: data.pattern,
+        params: data.params,
+      },
+      loaderData: data.loaderData,
+      navigation: { state: "idle" },
+    };
+
+    // __MANDU_DATA__ 업데이트
+    if (typeof window !== "undefined") {
+      (window as any).__MANDU_DATA__ = {
+        ...(window as any).__MANDU_DATA__,
+        [data.routeId]: { serverData: data.loaderData },
+      };
+    }
+
+    notifyListeners();
+
+    // 스크롤 복원
+    if (scroll) {
+      window.scrollTo(0, 0);
+    }
+  } catch (error) {
+    console.error("[Mandu Router] Navigation failed:", error);
+    // 에러 시 full navigation fallback
+    window.location.href = to;
+  }
+}
+
+/**
+ * 뒤로가기/앞으로가기 처리
+ */
+function handlePopState(event: PopStateEvent): void {
+  const state = event.state;
+
+  if (state?.routeId) {
+    // 이미 방문한 페이지 - 데이터 다시 fetch
+    navigate(window.location.pathname + window.location.search, {
+      replace: true,
+      scroll: false,
+    });
+  }
+}
+
+// ========== State Management ==========
+
+/**
+ * 리스너에게 상태 변경 알림
+ */
+function notifyListeners(): void {
+  for (const listener of listeners) {
+    try {
+      listener(routerState);
+    } catch (error) {
+      console.error("[Mandu Router] Listener error:", error);
+    }
+  }
+}
+
+/**
+ * 상태 변경 구독
+ */
+export function subscribe(listener: RouterListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * 현재 라우터 상태 가져오기
+ */
+export function getRouterState(): RouterState {
+  return routerState;
+}
+
+/**
+ * 현재 라우트 정보 가져오기
+ */
+export function getCurrentRoute(): RouteInfo | null {
+  return routerState.currentRoute;
+}
+
+/**
+ * 현재 loader 데이터 가져오기
+ */
+export function getLoaderData<T = unknown>(): T | undefined {
+  return routerState.loaderData as T | undefined;
+}
+
+/**
+ * 네비게이션 상태 가져오기
+ */
+export function getNavigationState(): NavigationState {
+  return routerState.navigation;
+}
+
+// ========== Link Click Handler ==========
+
+/**
+ * 링크 클릭 이벤트 핸들러 (이벤트 위임용)
+ */
+function handleLinkClick(event: MouseEvent): void {
+  // 기본 동작 조건 체크
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.shiftKey
+  ) {
+    return;
+  }
+
+  // 가장 가까운 앵커 태그 찾기
+  const anchor = (event.target as HTMLElement).closest("a");
+  if (!anchor) return;
+
+  // data-mandu-link 속성이 있는 링크만 처리
+  if (!anchor.hasAttribute("data-mandu-link")) return;
+
+  const href = anchor.getAttribute("href");
+  if (!href) return;
+
+  // 외부 링크 체크
+  try {
+    const url = new URL(href, window.location.origin);
+    if (url.origin !== window.location.origin) return;
+  } catch {
+    return;
+  }
+
+  // 기본 동작 방지 및 Client-side 네비게이션
+  event.preventDefault();
+  navigate(href);
+}
+
+// ========== Prefetch ==========
+
+const prefetchedUrls = new Set<string>();
+
+/**
+ * 페이지 데이터 미리 로드
+ */
+export async function prefetch(url: string): Promise<void> {
+  if (prefetchedUrls.has(url)) return;
+
+  try {
+    const dataUrl = `${url}${url.includes("?") ? "&" : "?"}_data=1`;
+    await fetch(dataUrl, { priority: "low" } as RequestInit);
+    prefetchedUrls.add(url);
+  } catch {
+    // Prefetch 실패는 무시
+  }
+}
+
+// ========== Initialization ==========
+
+let initialized = false;
+
+/**
+ * 라우터 초기화
+ */
+export function initializeRouter(): void {
+  if (typeof window === "undefined" || initialized) return;
+
+  initialized = true;
+
+  // 서버 데이터로 초기화
+  initializeFromServer();
+
+  // popstate 이벤트 리스너
+  window.addEventListener("popstate", handlePopState);
+
+  // 링크 클릭 이벤트 위임
+  document.addEventListener("click", handleLinkClick);
+
+  console.log("[Mandu Router] Initialized");
+}
+
+/**
+ * 라우터 정리
+ */
+export function cleanupRouter(): void {
+  if (typeof window === "undefined" || !initialized) return;
+
+  window.removeEventListener("popstate", handlePopState);
+  document.removeEventListener("click", handleLinkClick);
+  listeners.clear();
+  initialized = false;
+}
+
+// 자동 초기화 (DOM 준비 시)
+if (typeof window !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initializeRouter);
+  } else {
+    initializeRouter();
+  }
+}

package/src/runtime/server.ts

@@ -315,6 +315,9 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
     let loaderData: unknown;
     let component: RouteComponent | undefined;
 
+    // Client-side Routing: 데이터 요청 감지
+    const isDataRequest = url.searchParams.has("_data");
+
     // 1. PageHandler 방식 (신규 - filling 포함)
     const pageHandler = pageHandlers.get(route.id);
     if (pageHandler) {
@@ -363,6 +366,18 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
       }
     }
 
+    // Client-side Routing: 데이터만 반환 (JSON)
+    if (isDataRequest) {
+      return Response.json({
+        routeId: route.id,
+        pattern: route.pattern,
+        params,
+        loaderData: loaderData ?? null,
+        timestamp: Date.now(),
+      });
+    }
+
+    // SSR 렌더링 (기존 로직)
     const appCreator = createAppFn || defaultCreateApp;
     try {
       const app = appCreator({
@@ -385,6 +400,9 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         hydration: route.hydration,
         bundleManifest: serverSettings.bundleManifest,
         serverData,
+        // Client-side Routing 활성화 정보 전달
+        enableClientRouter: true,
+        routePattern: route.pattern,
       });
     } catch (err) {
       const ssrError = createSSRErrorResponse(

package/src/runtime/ssr.ts

@@ -22,6 +22,10 @@ export interface SSROptions {
   isDev?: boolean;
   /** HMR 포트 (개발 모드에서 사용) */
   hmrPort?: number;
+  /** Client-side Routing 활성화 여부 */
+  enableClientRouter?: boolean;
+  /** 라우트 패턴 (Client-side Routing용) */
+  routePattern?: string;
 }
 
 /**
@@ -105,6 +109,8 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     bodyEndTags = "",
     isDev = false,
     hmrPort,
+    enableClientRouter = false,
+    routePattern,
   } = options;
 
   let content = renderToString(element);
@@ -129,12 +135,24 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     dataScript = serializeServerData(wrappedData);
   }
 
+  // Client-side Routing: 라우트 정보 주입
+  let routeScript = "";
+  if (enableClientRouter && routeId) {
+    routeScript = generateRouteScript(routeId, routePattern || "", serverData);
+  }
+
   // Hydration 스크립트
   let hydrationScripts = "";
   if (needsHydration && bundleManifest) {
     hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
   }
 
+  // Client-side Router 스크립트
+  let routerScript = "";
+  if (enableClientRouter && bundleManifest) {
+    routerScript = generateClientRouterScript(bundleManifest);
+  }
+
   // HMR 스크립트 (개발 모드)
   let hmrScript = "";
   if (isDev && hmrPort) {
@@ -152,13 +170,60 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 <body>
   <div id="root">${content}</div>
   ${dataScript}
+  ${routeScript}
   ${hydrationScripts}
+  ${routerScript}
   ${hmrScript}
   ${bodyEndTags}
 </body>
 </html>`;
 }
 
+/**
+ * Client-side Routing: 현재 라우트 정보 스크립트 생성
+ */
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  serverData?: Record<string, unknown>
+): string {
+  const routeInfo = {
+    id: routeId,
+    pattern,
+    params: extractParamsFromUrl(pattern),
+  };
+
+  const json = JSON.stringify(routeInfo)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+
+  return `<script>window.__MANDU_ROUTE__ = ${json};</script>`;
+}
+
+/**
+ * URL 패턴에서 파라미터 추출 (클라이언트에서 사용)
+ */
+function extractParamsFromUrl(pattern: string): Record<string, string> {
+  // 서버에서는 실제 params를 전달받으므로 빈 객체 반환
+  // 실제 params는 serverData나 별도 전달
+  return {};
+}
+
+/**
+ * Client-side Router 스크립트 로드
+ */
+function generateClientRouterScript(manifest: BundleManifest): string {
+  // Import map 먼저 (이미 hydration에서 추가되었을 수 있음)
+  const scripts: string[] = [];
+
+  // 라우터 번들이 있으면 로드
+  if (manifest.shared?.router) {
+    scripts.push(`<script type="module" src="${manifest.shared.router}"></script>`);
+  }
+
+  return scripts.join("\n");
+}
+
 /**
  * HMR 스크립트 생성
  */