@mandujs/core 0.3.4 → 0.4.1

package/src/client/island.ts

@@ -0,0 +1,197 @@
+/**
+ * Mandu Island - Client Slot API 🏝️
+ * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * Island 정의 타입
+ * @template TServerData - SSR에서 전달받는 서버 데이터 타입
+ * @template TSetupResult - setup 함수가 반환하는 결과 타입
+ */
+export interface IslandDefinition<TServerData, TSetupResult> {
+  /**
+   * Setup Phase
+   * - 서버 데이터를 받아 클라이언트 상태 초기화
+   * - React hooks 사용 가능
+   * - 반환값이 render 함수에 전달됨
+   */
+  setup: (serverData: TServerData) => TSetupResult;
+
+  /**
+   * Render Phase
+   * - setup에서 반환된 값을 props로 받음
+   * - 순수 렌더링 로직만 포함
+   */
+  render: (props: TSetupResult) => ReactNode;
+
+  /**
+   * Optional: 에러 발생 시 표시할 fallback UI
+   */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+
+  /**
+   * Optional: 로딩 중 표시할 UI (progressive hydration용)
+   */
+  loading?: () => ReactNode;
+}
+
+/**
+ * Island 컴포넌트의 메타데이터
+ */
+export interface IslandMetadata {
+  /** Island 고유 식별자 */
+  id: string;
+  /** SSR 데이터 키 */
+  dataKey: string;
+  /** Hydration 우선순위 */
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
+
+/**
+ * 컴파일된 Island 컴포넌트 타입
+ */
+export interface CompiledIsland<TServerData, TSetupResult> {
+  /** Island 정의 */
+  definition: IslandDefinition<TServerData, TSetupResult>;
+  /** Island 메타데이터 (빌드 시 주입) */
+  __mandu_island: true;
+  /** Island ID (빌드 시 주입) */
+  __mandu_island_id?: string;
+}
+
+/**
+ * Island 컴포넌트 생성
+ *
+ * @example
+ * ```typescript
+ * // spec/slots/todos.client.ts
+ * import { Mandu } from "@mandujs/core/client";
+ * import { useState, useCallback } from "react";
+ *
+ * interface TodosData {
+ *   todos: Todo[];
+ *   user: User | null;
+ * }
+ *
+ * export default Mandu.island<TodosData>({
+ *   setup: (serverData) => {
+ *     const [todos, setTodos] = useState(serverData.todos);
+ *     const addTodo = useCallback(async (text: string) => {
+ *       // ...
+ *     }, []);
+ *     return { todos, addTodo, user: serverData.user };
+ *   },
+ *   render: ({ todos, addTodo, user }) => (
+ *     <div>
+ *       {user && <span>Hello, {user.name}!</span>}
+ *       <TodoList todos={todos} onAdd={addTodo} />
+ *     </div>
+ *   )
+ * });
+ * ```
+ */
+export function island<TServerData, TSetupResult = TServerData>(
+  definition: IslandDefinition<TServerData, TSetupResult>
+): CompiledIsland<TServerData, TSetupResult> {
+  // Validate definition
+  if (typeof definition.setup !== "function") {
+    throw new Error("[Mandu Island] setup must be a function");
+  }
+  if (typeof definition.render !== "function") {
+    throw new Error("[Mandu Island] render must be a function");
+  }
+
+  return {
+    definition,
+    __mandu_island: true,
+  };
+}
+
+/**
+ * Island에서 사용할 수 있는 헬퍼 훅들
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Hydration 상태를 추적하는 훅
+ */
+export function useHydrated(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Island 간 통신을 위한 이벤트 훅
+ */
+export function useIslandEvent<T = unknown>(
+  eventName: string,
+  handler: (data: T) => void
+): (data: T) => void {
+  if (typeof window === "undefined") {
+    return () => {};
+  }
+
+  // 이벤트 리스너 등록
+  const customEventName = `mandu:island:${eventName}`;
+
+  const listener = (event: CustomEvent<T>) => {
+    handler(event.detail);
+  };
+
+  window.addEventListener(customEventName, listener as EventListener);
+
+  // 이벤트 발송 함수 반환
+  return (data: T) => {
+    window.dispatchEvent(new CustomEvent(customEventName, { detail: data }));
+  };
+}
+
+/**
+ * API 호출 헬퍼
+ */
+export interface FetchOptions extends Omit<RequestInit, "body"> {
+  body?: unknown;
+}
+
+export async function fetchApi<T>(
+  url: string,
+  options: FetchOptions = {}
+): Promise<T> {
+  const { body, headers = {}, ...rest } = options;
+
+  const response = await fetch(url, {
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    ...rest,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ message: response.statusText }));
+    throw new Error(error.message || `API Error: ${response.status}`);
+  }
+
+  return response.json();
+}

package/src/client/runtime.ts

@@ -0,0 +1,335 @@
+/**
+ * Mandu Hydration Runtime 🌊
+ * 브라우저에서 Island를 hydrate하는 런타임
+ */
+
+import { hydrateRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import type { CompiledIsland } from "./island";
+import type { ReactNode } from "react";
+import React from "react";
+
+/**
+ * Island 로더 타입
+ */
+export type IslandLoader = () => Promise<CompiledIsland<any, any>> | CompiledIsland<any, any>;
+
+/**
+ * Island 레지스트리
+ */
+const islandRegistry = new Map<string, IslandLoader>();
+
+/**
+ * Hydrated roots 추적
+ */
+const hydratedRoots = new Map<string, Root>();
+
+/**
+ * Hydration 상태 추적
+ */
+interface HydrationState {
+  total: number;
+  hydrated: number;
+  failed: number;
+  pending: Set<string>;
+}
+
+const hydrationState: HydrationState = {
+  total: 0,
+  hydrated: 0,
+  failed: 0,
+  pending: new Set(),
+};
+
+/**
+ * Island 등록
+ */
+export function registerIsland(id: string, loader: IslandLoader): void {
+  islandRegistry.set(id, loader);
+}
+
+/**
+ * 등록된 모든 Island 가져오기
+ */
+export function getRegisteredIslands(): string[] {
+  return Array.from(islandRegistry.keys());
+}
+
+/**
+ * 서버 데이터 가져오기
+ */
+export function getServerData<T = unknown>(islandId: string): T | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+
+  const manduData = (window as any).__MANDU_DATA__;
+  if (!manduData) {
+    return undefined;
+  }
+
+  return manduData[islandId]?.serverData as T;
+}
+
+/**
+ * Priority-based hydration 스케줄러
+ */
+type HydrationPriority = "immediate" | "visible" | "idle" | "interaction";
+
+function scheduleHydration(
+  element: HTMLElement,
+  id: string,
+  priority: HydrationPriority,
+  serverData: unknown
+): void {
+  switch (priority) {
+    case "immediate":
+      hydrateIsland(element, id, serverData);
+      break;
+
+    case "visible":
+      if ("IntersectionObserver" in window) {
+        const observer = new IntersectionObserver(
+          (entries) => {
+            if (entries[0].isIntersecting) {
+              observer.disconnect();
+              hydrateIsland(element, id, serverData);
+            }
+          },
+          { rootMargin: "50px" }
+        );
+        observer.observe(element);
+      } else {
+        // Fallback for older browsers
+        hydrateIsland(element, id, serverData);
+      }
+      break;
+
+    case "idle":
+      if ("requestIdleCallback" in window) {
+        (window as any).requestIdleCallback(() => {
+          hydrateIsland(element, id, serverData);
+        });
+      } else {
+        // Fallback
+        setTimeout(() => hydrateIsland(element, id, serverData), 200);
+      }
+      break;
+
+    case "interaction": {
+      const hydrate = () => {
+        element.removeEventListener("mouseenter", hydrate);
+        element.removeEventListener("focusin", hydrate);
+        element.removeEventListener("touchstart", hydrate);
+        hydrateIsland(element, id, serverData);
+      };
+      element.addEventListener("mouseenter", hydrate, { once: true, passive: true });
+      element.addEventListener("focusin", hydrate, { once: true });
+      element.addEventListener("touchstart", hydrate, { once: true, passive: true });
+      break;
+    }
+  }
+}
+
+/**
+ * 단일 Island hydrate
+ */
+async function hydrateIsland(
+  element: HTMLElement,
+  id: string,
+  serverData: unknown
+): Promise<void> {
+  const loader = islandRegistry.get(id);
+  if (!loader) {
+    console.warn(`[Mandu] Island not registered: ${id}`);
+    hydrationState.failed++;
+    hydrationState.pending.delete(id);
+    return;
+  }
+
+  try {
+    // 로더 실행 (dynamic import 또는 직접 참조)
+    const island = await Promise.resolve(loader());
+
+    if (!island.__mandu_island) {
+      throw new Error(`[Mandu] Invalid island: ${id}`);
+    }
+
+    const { definition } = island;
+
+    // Island 컴포넌트 생성
+    function IslandComponent(): ReactNode {
+      const setupResult = definition.setup(serverData);
+      return definition.render(setupResult);
+    }
+
+    // ErrorBoundary가 있으면 감싸기
+    let content: ReactNode;
+    if (definition.errorBoundary) {
+      content = React.createElement(
+        ManduErrorBoundary,
+        {
+          fallback: (error: Error, reset: () => void) => definition.errorBoundary!(error, reset),
+        },
+        React.createElement(IslandComponent)
+      );
+    } else {
+      content = React.createElement(IslandComponent);
+    }
+
+    // Hydrate
+    const root = hydrateRoot(element, content);
+    hydratedRoots.set(id, root);
+
+    // 상태 업데이트
+    element.setAttribute("data-mandu-hydrated", "true");
+    hydrationState.hydrated++;
+    hydrationState.pending.delete(id);
+
+    // 성능 마커
+    if (typeof performance !== "undefined" && performance.mark) {
+      performance.mark(`mandu-hydrated-${id}`);
+    }
+
+    // Hydration 완료 이벤트
+    element.dispatchEvent(
+      new CustomEvent("mandu:hydrated", {
+        bubbles: true,
+        detail: { id, serverData },
+      })
+    );
+  } catch (error) {
+    console.error(`[Mandu] Hydration failed for island ${id}:`, error);
+    hydrationState.failed++;
+    hydrationState.pending.delete(id);
+
+    // 에러 상태 표시
+    element.setAttribute("data-mandu-error", "true");
+
+    // 에러 이벤트
+    element.dispatchEvent(
+      new CustomEvent("mandu:hydration-error", {
+        bubbles: true,
+        detail: { id, error },
+      })
+    );
+  }
+}
+
+/**
+ * 모든 Island hydrate 시작
+ */
+export async function hydrateIslands(): Promise<void> {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const islands = document.querySelectorAll<HTMLElement>("[data-mandu-island]");
+  const manduData = (window as any).__MANDU_DATA__ || {};
+
+  hydrationState.total = islands.length;
+
+  for (const element of islands) {
+    const id = element.getAttribute("data-mandu-island");
+    if (!id) continue;
+
+    const priority = (element.getAttribute("data-mandu-priority") || "visible") as HydrationPriority;
+    const data = manduData[id]?.serverData || {};
+
+    hydrationState.pending.add(id);
+    scheduleHydration(element, id, priority, data);
+  }
+}
+
+/**
+ * Hydration 상태 조회
+ */
+export function getHydrationState(): Readonly<HydrationState> {
+  return { ...hydrationState };
+}
+
+/**
+ * 특정 Island unmount
+ */
+export function unmountIsland(id: string): boolean {
+  const root = hydratedRoots.get(id);
+  if (!root) {
+    return false;
+  }
+
+  root.unmount();
+  hydratedRoots.delete(id);
+  return true;
+}
+
+/**
+ * 모든 Island unmount
+ */
+export function unmountAllIslands(): void {
+  for (const [id, root] of hydratedRoots) {
+    root.unmount();
+    hydratedRoots.delete(id);
+  }
+}
+
+/**
+ * 간단한 ErrorBoundary 컴포넌트
+ */
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback: (error: Error, reset: () => void) => ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+class ManduErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    console.error("[Mandu] Island error:", error, errorInfo);
+  }
+
+  reset = (): void => {
+    this.setState({ error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.error) {
+      return this.props.fallback(this.state.error, this.reset);
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * 자동 초기화 (스크립트 로드 시)
+ */
+export function initializeRuntime(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  // DOM이 준비되면 hydration 시작
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => {
+      hydrateIslands();
+    });
+  } else {
+    // 이미 DOM이 준비된 경우
+    hydrateIslands();
+  }
+}
+
+// 자동 초기화 여부 (번들 시 설정)
+if (typeof window !== "undefined" && (window as any).__MANDU_AUTO_INIT__ !== false) {
+  initializeRuntime();
+}

package/src/filling/filling.ts

@@ -15,10 +15,14 @@ export type Guard = (ctx: ManduContext) => symbol | Response | Promise<symbol |
 /** HTTP methods */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
-interface FillingConfig {
+/** Loader function type - SSR 데이터 로딩 */
+export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
+
+interface FillingConfig<TLoaderData = unknown> {
   handlers: Map<HttpMethod, Handler>;
   guards: Guard[];
   methodGuards: Map<HttpMethod, Guard[]>;
+  loader?: Loader<TLoaderData>;
 }
 
 /**
@@ -30,14 +34,64 @@ interface FillingConfig {
  *   .get(ctx => ctx.ok({ message: 'Hello!' }))
  *   .post(ctx => ctx.created({ id: 1 }))
  * ```
+ *
+ * @example with loader
+ * ```typescript
+ * export default Mandu.filling<{ todos: Todo[] }>()
+ *   .loader(async (ctx) => {
+ *     const todos = await db.todos.findMany();
+ *     return { todos };
+ *   })
+ *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+ * ```
  */
-export class ManduFilling {
-  private config: FillingConfig = {
+export class ManduFilling<TLoaderData = unknown> {
+  private config: FillingConfig<TLoaderData> = {
     handlers: new Map(),
     guards: [],
     methodGuards: new Map(),
   };
 
+  // ============================================
+  // 🥟 SSR Loader
+  // ============================================
+
+  /**
+   * Define SSR data loader
+   * 페이지 렌더링 전 서버에서 데이터를 로드합니다.
+   * 로드된 데이터는 클라이언트로 전달되어 hydration에 사용됩니다.
+   *
+   * @example
+   * ```typescript
+   * .loader(async (ctx) => {
+   *   const todos = await db.todos.findMany();
+   *   return { todos, user: ctx.get('user') };
+   * })
+   * ```
+   */
+  loader(loaderFn: Loader<TLoaderData>): this {
+    this.config.loader = loaderFn;
+    return this;
+  }
+
+  /**
+   * Execute loader and return data
+   * @internal Used by SSR runtime
+   */
+  async executeLoader(ctx: ManduContext): Promise<TLoaderData | undefined> {
+    if (!this.config.loader) {
+      return undefined;
+    }
+    return await this.config.loader(ctx);
+  }
+
+  /**
+   * Check if loader is defined
+   */
+  hasLoader(): boolean {
+    return !!this.config.loader;
+  }
+
   // ============================================
   // 🥟 HTTP Method Handlers
   // ============================================
@@ -242,9 +296,26 @@ export const Mandu = {
    * export default Mandu.filling()
    *   .get(ctx => ctx.ok({ message: 'Hello!' }))
    * ```
+   *
+   * @example with loader data type
+   * ```typescript
+   * import { Mandu } from '@mandujs/core'
+   *
+   * interface LoaderData {
+   *   todos: Todo[];
+   *   user: User | null;
+   * }
+   *
+   * export default Mandu.filling<LoaderData>()
+   *   .loader(async (ctx) => {
+   *     const todos = await db.todos.findMany();
+   *     return { todos, user: null };
+   *   })
+   *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+   * ```
    */
-  filling(): ManduFilling {
-    return new ManduFilling();
+  filling<TLoaderData = unknown>(): ManduFilling<TLoaderData> {
+    return new ManduFilling<TLoaderData>();
   },
 
   /**

package/src/index.ts

@@ -7,3 +7,4 @@ export * from "./filling";
 export * from "./change";
 export * from "./error";
 export * from "./slot";
+export * from "./bundler";

package/src/runtime/server.ts

@@ -14,6 +14,10 @@ import {
 export interface ServerOptions {
   port?: number;
   hostname?: string;
+  /** 개발 모드 여부 */
+  isDev?: boolean;
+  /** HMR 포트 (개발 모드에서 사용) */
+  hmrPort?: number;
 }
 
 export interface ManduServer {
@@ -40,6 +44,9 @@ const pageLoaders: Map<string, PageLoader> = new Map();
 const routeComponents: Map<string, RouteComponent> = new Map();
 let createAppFn: CreateAppFn | null = null;
 
+// Dev mode settings (module-level for handleRequest access)
+let devModeSettings: { isDev: boolean; hmrPort?: number } = { isDev: false };
+
 export function registerApiHandler(routeId: string, handler: ApiHandler): void {
   apiHandlers.set(routeId, handler);
 }
@@ -126,7 +133,11 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         params,
       });
 
-      return renderSSR(app, { title: `${route.id} - Mandu` });
+      return renderSSR(app, {
+        title: `${route.id} - Mandu`,
+        isDev: devModeSettings.isDev,
+        hmrPort: devModeSettings.hmrPort,
+      });
     } catch (err) {
       const ssrError = createSSRErrorResponse(
         route.id,
@@ -159,7 +170,10 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
 }
 
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
-  const { port = 3000, hostname = "localhost" } = options;
+  const { port = 3000, hostname = "localhost", isDev = false, hmrPort } = options;
+
+  // Dev mode settings 저장
+  devModeSettings = { isDev, hmrPort };
 
   const router = new Router(manifest.routes);
 
@@ -169,7 +183,14 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     fetch: (req) => handleRequest(req, router),
   });
 
-  console.log(`🥟 Mandu server running at http://${hostname}:${port}`);
+  if (isDev) {
+    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${port}`);
+    if (hmrPort) {
+      console.log(`🔥 HMR enabled on port ${hmrPort + 1}`);
+    }
+  } else {
+    console.log(`🥟 Mandu server running at http://${hostname}:${port}`);
+  }
 
   return {
     server,