@mandujs/core 0.9.30 → 0.9.37

package/src/runtime/router.ts

@@ -78,13 +78,25 @@ export class RouterError extends Error {
 // TrieNode Class
 // ═══════════════════════════════════════════════════════════════════════════
 
+/**
+ * Wildcard 설정
+ */
+interface WildcardConfig {
+  /** 파라미터 이름 (예: "path" for :path*) */
+  name: string;
+  /** optional 여부 (예: :path*? 는 optional) */
+  optional: boolean;
+  /** 라우트 정보 */
+  route: RouteSpec;
+}
+
 /**
  * Trie node for dynamic route matching
  *
  * Structure:
  * - children: Map for static segments
  * - paramChild: Single param child with name tracking (P0-4)
- * - wildcardRoute: Route for wildcard (*) matching
+ * - wildcardConfig: Wildcard with param name and optional flag
  * - route: Route that terminates at this node
  */
 class TrieNode {
@@ -94,11 +106,16 @@ class TrieNode {
   /** Parameter child with name for conflict detection */
   paramChild: { name: string; node: TrieNode } | null = null;
 
-  /** Wildcard route (only valid at leaf) */
-  wildcardRoute: RouteSpec | null = null;
+  /** Wildcard config with param name (only valid at leaf) */
+  wildcardConfig: WildcardConfig | null = null;
 
   /** Route terminating at this node */
   route: RouteSpec | null = null;
+
+  /** @deprecated Use wildcardConfig instead */
+  get wildcardRoute(): RouteSpec | null {
+    return this.wildcardConfig?.route ?? null;
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -116,7 +133,7 @@ class TrieNode {
  *
  * @returns Decoded string or null if security violation
  */
-function safeDecodeURIComponent(str: string): string | null {
+function safeDecodeURIComponent(str: string): string | null {
   // 1. Pre-decode %2F check
   if (ENCODED_SLASH_PATTERN.test(str)) {
     return null;
@@ -141,8 +158,26 @@ function safeDecodeURIComponent(str: string): string | null {
     return null;
   }
 
-  return decoded;
-}
+  return decoded;
+}
+
+/**
+ * Decode wildcard segments safely (per-segment)
+ */
+function decodeWildcardSegments(segments: string[]): string | null {
+  if (segments.length === 0) return "";
+
+  const decodedSegments: string[] = [];
+  for (const segment of segments) {
+    const decoded = safeDecodeURIComponent(segment);
+    if (decoded === null) {
+      return null;
+    }
+    decodedSegments.push(decoded);
+  }
+
+  return decodedSegments.join("/");
+}
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Router Class
@@ -305,7 +340,8 @@ export class Router {
     }
 
     // P0-2: Segment-based wildcard validation
-    const wildcardIdx = segments.findIndex((s) => s === "*");
+    // Wildcard formats: * (legacy), :param*, :param*? (optional)
+    const wildcardIdx = segments.findIndex((s) => s === "*" || s.includes("*"));
     if (wildcardIdx !== -1 && wildcardIdx !== segments.length - 1) {
       throw new RouterError(
         `Wildcard must be the last segment in pattern "${pattern}"`,
@@ -335,17 +371,58 @@ export class Router {
   private insertTrie(pattern: string, segments: string[], route: RouteSpec): void {
     let node = this.trie;
 
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i];
-
-      // Wildcard handling
-      if (seg === "*") {
-        node.wildcardRoute = route;
-        return;
-      }
-
-      // Parameter handling
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+
+      // Legacy wildcard: *
+      if (seg === "*") {
+        if (node.wildcardConfig) {
+          throw new RouterError(
+            `Wildcard conflict in pattern "${pattern}"`,
+            "ROUTE_CONFLICT",
+            route.id,
+            node.wildcardConfig.route.id
+          );
+        }
+        node.wildcardConfig = {
+          name: WILDCARD_PARAM_KEY,
+          optional: false,
+          route,
+        };
+        return;
+      }
+
+      // Parameter handling (including wildcards)
       if (seg.startsWith(":")) {
+        // Check for wildcard pattern: :param* or :param*?
+        const wildcardMatch = seg.match(/^:([^*?]+)\*(\?)?$/);
+        if (wildcardMatch) {
+          const paramName = wildcardMatch[1];
+          const isOptional = wildcardMatch[2] === "?";
+
+          if (node.wildcardConfig) {
+            throw new RouterError(
+              `Wildcard conflict in pattern "${pattern}"`,
+              "ROUTE_CONFLICT",
+              route.id,
+              node.wildcardConfig.route.id
+            );
+          }
+
+          node.wildcardConfig = {
+            name: paramName,
+            optional: isOptional,
+            route,
+          };
+
+          // Optional wildcard: 현재 노드도 매칭 가능하게 route 설정
+          if (isOptional && !node.route) {
+            node.route = route;
+          }
+          return;
+        }
+
+        // Regular parameter: :param
         const paramName = seg.slice(1);
 
         // P0-3: Param name conflict detection
@@ -385,14 +462,14 @@ export class Router {
     let node = this.trie;
 
     // Track wildcard candidate for backtracking
-    let wildcardMatch: { route: RouteSpec; consumed: number } | null = null;
+    let wildcardMatch: { config: WildcardConfig; consumed: number } | null = null;
 
     for (let i = 0; i < segments.length; i++) {
       const seg = segments[i];
 
       // Save wildcard candidate before advancing
-      if (node.wildcardRoute) {
-        wildcardMatch = { route: node.wildcardRoute, consumed: i };
+      if (node.wildcardConfig) {
+        wildcardMatch = { config: node.wildcardConfig, consumed: i };
       }
 
       // 1. Try static child first (higher priority)
@@ -417,15 +494,19 @@ export class Router {
         continue;
       }
 
-      // 3. No match - try wildcard fallback
-      if (wildcardMatch) {
-        const remaining = segments.slice(wildcardMatch.consumed).join("/");
-        if (this.debug) {
-          console.log(`[Router] Wildcard match: ${wildcardMatch.route.id} with ${remaining}`);
-        }
-        return {
-          route: wildcardMatch.route,
-          params: { [WILDCARD_PARAM_KEY]: remaining },
+      // 3. No match - try wildcard fallback
+      if (wildcardMatch) {
+        const remainingSegments = segments.slice(wildcardMatch.consumed);
+        const remaining = decodeWildcardSegments(remainingSegments);
+        if (remaining === null) {
+          return null;
+        }
+        if (this.debug) {
+          console.log(`[Router] Wildcard match: ${wildcardMatch.config.route.id} with ${remaining}`);
+        }
+        return {
+          route: wildcardMatch.config.route,
+          params: { ...params, [wildcardMatch.config.name]: remaining },
         };
       }
 
@@ -441,23 +522,36 @@ export class Router {
       return { route: node.route, params };
     }
 
-    // Check for wildcard at current node (but with no remaining segments)
-    // Policy A: /files/* does NOT match /files
-    if (node.wildcardRoute) {
-      // Don't match - wildcard requires at least one segment
-      if (this.debug) {
-        console.log(`[Router] Wildcard policy A: ${pathname} does not match wildcard`);
-      }
+    // Check for wildcard at current node (but with no remaining segments)
+    if (node.wildcardConfig) {
+      // Optional wildcard: /files/:path*? matches /files (with empty path param)
+      if (node.wildcardConfig.optional) {
+        if (this.debug) {
+          console.log(`[Router] Optional wildcard match: ${node.wildcardConfig.route.id} with empty path`);
+        }
+        return {
+          route: node.wildcardConfig.route,
+          params,
+        };
+      }
+      // Non-optional wildcard: /files/:path* does NOT match /files
+      if (this.debug) {
+        console.log(`[Router] Wildcard policy: ${pathname} does not match non-optional wildcard`);
+      }
     }
 
-    // Try wildcard fallback from earlier in the path
-    if (wildcardMatch) {
-      const remaining = segments.slice(wildcardMatch.consumed).join("/");
-      return {
-        route: wildcardMatch.route,
-        params: { [WILDCARD_PARAM_KEY]: remaining },
-      };
-    }
+    // Try wildcard fallback from earlier in the path
+    if (wildcardMatch) {
+      const remainingSegments = segments.slice(wildcardMatch.consumed);
+      const remaining = decodeWildcardSegments(remainingSegments);
+      if (remaining === null) {
+        return null;
+      }
+      return {
+        route: wildcardMatch.config.route,
+        params: { ...params, [wildcardMatch.config.name]: remaining },
+      };
+    }
 
     return null;
   }
@@ -470,8 +564,11 @@ export class Router {
       routes.push(node.route);
     }
 
-    if (node.wildcardRoute) {
-      routes.push(node.wildcardRoute);
+    if (node.wildcardConfig) {
+      // Optional wildcard의 경우 route가 이미 추가되었을 수 있음
+      if (!node.route || node.wildcardConfig.route !== node.route) {
+        routes.push(node.wildcardConfig.route);
+      }
     }
 
     for (const child of node.children.values()) {

package/src/runtime/server.ts

@@ -5,7 +5,8 @@ import type { ManduFilling } from "../filling/filling";
 import { ManduContext } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR, renderStreamingResponse } from "./ssr";
-import React from "react";
+import { PageBoundary, DefaultLoading, DefaultError, type ErrorFallbackProps } from "./boundary";
+import React, { type ReactNode } from "react";
 import path from "path";
 import {
   formatErrorResponse,
@@ -119,6 +120,36 @@ export interface ManduServer {
 export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
 export type PageLoader = () => Promise<{ default: React.ComponentType<{ params: Record<string, string> }> }>;
 
+/**
+ * Layout 컴포넌트 타입
+ * children을 받아서 감싸는 구조
+ */
+export type LayoutComponent = React.ComponentType<{
+  children: React.ReactNode;
+  params?: Record<string, string>;
+}>;
+
+/**
+ * Layout 로더 타입
+ */
+export type LayoutLoader = () => Promise<{ default: LayoutComponent }>;
+
+/**
+ * Loading 컴포넌트 타입
+ */
+export type LoadingComponent = React.ComponentType<Record<string, never>>;
+
+/**
+ * Error 컴포넌트 타입
+ */
+export type ErrorComponent = React.ComponentType<ErrorFallbackProps>;
+
+/**
+ * Loading/Error 로더 타입
+ */
+export type LoadingLoader = () => Promise<{ default: LoadingComponent }>;
+export type ErrorLoader = () => Promise<{ default: ErrorComponent }>;
+
 /**
  * Page 등록 정보
  * - component: React 컴포넌트
@@ -166,6 +197,18 @@ export class ServerRegistry {
   readonly pageLoaders: Map<string, PageLoader> = new Map();
   readonly pageHandlers: Map<string, PageHandler> = new Map();
   readonly routeComponents: Map<string, RouteComponent> = new Map();
+  /** Layout 컴포넌트 캐시 (모듈 경로 → 컴포넌트) */
+  readonly layoutComponents: Map<string, LayoutComponent> = new Map();
+  /** Layout 로더 (모듈 경로 → 로더 함수) */
+  readonly layoutLoaders: Map<string, LayoutLoader> = new Map();
+  /** Loading 컴포넌트 캐시 (모듈 경로 → 컴포넌트) */
+  readonly loadingComponents: Map<string, LoadingComponent> = new Map();
+  /** Loading 로더 (모듈 경로 → 로더 함수) */
+  readonly loadingLoaders: Map<string, LoadingLoader> = new Map();
+  /** Error 컴포넌트 캐시 (모듈 경로 → 컴포넌트) */
+  readonly errorComponents: Map<string, ErrorComponent> = new Map();
+  /** Error 로더 (모듈 경로 → 로더 함수) */
+  readonly errorLoaders: Map<string, ErrorLoader> = new Map();
   createAppFn: CreateAppFn | null = null;
   settings: ServerRegistrySettings = {
     isDev: false,
@@ -191,10 +234,130 @@ export class ServerRegistry {
     this.routeComponents.set(routeId, component);
   }
 
+  /**
+   * Layout 로더 등록
+   */
+  registerLayoutLoader(modulePath: string, loader: LayoutLoader): void {
+    this.layoutLoaders.set(modulePath, loader);
+  }
+
+  /**
+   * Layout 컴포넌트 가져오기 (캐시 또는 로드)
+   */
+  async getLayoutComponent(modulePath: string): Promise<LayoutComponent | null> {
+    // 캐시 확인
+    const cached = this.layoutComponents.get(modulePath);
+    if (cached) {
+      return cached;
+    }
+
+    // 로더로 로드
+    const loader = this.layoutLoaders.get(modulePath);
+    if (loader) {
+      try {
+        const module = await loader();
+        const component = module.default;
+        this.layoutComponents.set(modulePath, component);
+        return component;
+      } catch (error) {
+        console.error(`[Mandu] Failed to load layout: ${modulePath}`, error);
+        return null;
+      }
+    }
+
+    // 동적 import 시도
+    try {
+      const fullPath = path.join(this.settings.rootDir, modulePath);
+      const module = await import(fullPath);
+      const component = module.default;
+      this.layoutComponents.set(modulePath, component);
+      return component;
+    } catch (error) {
+      console.error(`[Mandu] Failed to load layout: ${modulePath}`, error);
+      return null;
+    }
+  }
+
   setCreateApp(fn: CreateAppFn): void {
     this.createAppFn = fn;
   }
 
+  /**
+   * Loading 로더 등록
+   */
+  registerLoadingLoader(modulePath: string, loader: LoadingLoader): void {
+    this.loadingLoaders.set(modulePath, loader);
+  }
+
+  /**
+   * Error 로더 등록
+   */
+  registerErrorLoader(modulePath: string, loader: ErrorLoader): void {
+    this.errorLoaders.set(modulePath, loader);
+  }
+
+  /**
+   * Loading 컴포넌트 가져오기 (캐시 또는 로드)
+   */
+  async getLoadingComponent(modulePath: string): Promise<LoadingComponent | null> {
+    const cached = this.loadingComponents.get(modulePath);
+    if (cached) return cached;
+
+    const loader = this.loadingLoaders.get(modulePath);
+    if (loader) {
+      try {
+        const module = await loader();
+        const component = module.default;
+        this.loadingComponents.set(modulePath, component);
+        return component;
+      } catch (error) {
+        console.error(`[Mandu] Failed to load loading component: ${modulePath}`, error);
+        return null;
+      }
+    }
+
+    try {
+      const fullPath = path.join(this.settings.rootDir, modulePath);
+      const module = await import(fullPath);
+      const component = module.default;
+      this.loadingComponents.set(modulePath, component);
+      return component;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Error 컴포넌트 가져오기 (캐시 또는 로드)
+   */
+  async getErrorComponent(modulePath: string): Promise<ErrorComponent | null> {
+    const cached = this.errorComponents.get(modulePath);
+    if (cached) return cached;
+
+    const loader = this.errorLoaders.get(modulePath);
+    if (loader) {
+      try {
+        const module = await loader();
+        const component = module.default;
+        this.errorComponents.set(modulePath, component);
+        return component;
+      } catch (error) {
+        console.error(`[Mandu] Failed to load error component: ${modulePath}`, error);
+        return null;
+      }
+    }
+
+    try {
+      const fullPath = path.join(this.settings.rootDir, modulePath);
+      const module = await import(fullPath);
+      const component = module.default;
+      this.errorComponents.set(modulePath, component);
+      return component;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 모든 핸들러/컴포넌트 초기화 (테스트용)
    */
@@ -203,6 +366,12 @@ export class ServerRegistry {
     this.pageLoaders.clear();
     this.pageHandlers.clear();
     this.routeComponents.clear();
+    this.layoutComponents.clear();
+    this.layoutLoaders.clear();
+    this.loadingComponents.clear();
+    this.loadingLoaders.clear();
+    this.errorComponents.clear();
+    this.errorLoaders.clear();
     this.createAppFn = null;
   }
 }
@@ -253,6 +422,63 @@ export function setCreateApp(fn: CreateAppFn): void {
   defaultRegistry.setCreateApp(fn);
 }
 
+/**
+ * Layout 로더 등록 (전역)
+ */
+export function registerLayoutLoader(modulePath: string, loader: LayoutLoader): void {
+  defaultRegistry.registerLayoutLoader(modulePath, loader);
+}
+
+/**
+ * Loading 로더 등록 (전역)
+ */
+export function registerLoadingLoader(modulePath: string, loader: LoadingLoader): void {
+  defaultRegistry.registerLoadingLoader(modulePath, loader);
+}
+
+/**
+ * Error 로더 등록 (전역)
+ */
+export function registerErrorLoader(modulePath: string, loader: ErrorLoader): void {
+  defaultRegistry.registerErrorLoader(modulePath, loader);
+}
+
+/**
+ * 레이아웃 체인으로 컨텐츠 래핑
+ *
+ * @param content 페이지 컴포넌트로 렌더된 React Element
+ * @param layoutChain 레이아웃 모듈 경로 배열 (외부 → 내부)
+ * @param registry ServerRegistry 인스턴스
+ * @param params URL 파라미터
+ * @returns 래핑된 React Element
+ */
+async function wrapWithLayouts(
+  content: React.ReactElement,
+  layoutChain: string[],
+  registry: ServerRegistry,
+  params: Record<string, string>
+): Promise<React.ReactElement> {
+  if (!layoutChain || layoutChain.length === 0) {
+    return content;
+  }
+
+  // 레이아웃 로드 (병렬)
+  const layouts = await Promise.all(
+    layoutChain.map((modulePath) => registry.getLayoutComponent(modulePath))
+  );
+
+  // 내부 → 외부 순서로 래핑 (역순)
+  let wrapped = content;
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    const Layout = layouts[i];
+    if (Layout) {
+      wrapped = React.createElement(Layout, { params }, wrapped);
+    }
+  }
+
+  return wrapped;
+}
+
 // Default createApp implementation (registry 기반)
 function createDefaultAppFactory(registry: ServerRegistry) {
   return function defaultCreateApp(context: AppContext): React.ReactElement {
@@ -504,13 +730,18 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
     const defaultAppCreator = createDefaultAppFactory(registry);
     const appCreator = registry.createAppFn || defaultAppCreator;
     try {
-      const app = appCreator({
+      let app = appCreator({
         routeId: route.id,
         url: req.url,
         params,
         loaderData,
       });
 
+      // 레이아웃 체인 적용 (layoutChain이 있는 경우)
+      if (route.layoutChain && route.layoutChain.length > 0) {
+        app = await wrapWithLayouts(app, route.layoutChain, registry, params);
+      }
+
       // serverData 구조: { [routeId]: { serverData: loaderData } }
       const serverData = loaderData
         ? { [route.id]: { serverData: loaderData } }

package/src/spec/schema.ts

@@ -94,6 +94,17 @@ export const RouteSpec = z
     // - false: 이 라우트에 전통적 SSR 적용
     // - undefined: 서버 설정 따름
     streaming: z.boolean().optional(),
+
+    // Layout 체인 [NEW v0.9.33]
+    // - 페이지에 적용할 레이아웃 모듈 경로 배열
+    // - 배열 순서: 외부 → 내부 (Root → Parent → Child)
+    layoutChain: z.array(z.string()).optional(),
+
+    // Loading UI 모듈 경로 [NEW v0.9.33]
+    loadingModule: z.string().optional(),
+
+    // Error UI 모듈 경로 [NEW v0.9.33]
+    errorModule: z.string().optional(),
   })
   .refine(
     (route) => {

package/src/watcher/rules.ts

@@ -21,10 +21,10 @@ import fs from "fs/promises";
  */
 export const MVP_RULES: ArchRule[] = [
   {
-    id: "GENERATED_DIRECT_EDIT",
+    id: "GENERATED_DIRECT_EDIT",
     name: "Generated Direct Edit",
     description: "Generated 파일은 직접 수정하면 안 됩니다",
-    pattern: "generated/**",
+    pattern: "**/generated/**",
     action: "warn",
     message: "Generated 파일이 직접 수정되었습니다. 이 파일은 `mandu generate`로 재생성됩니다.",
     agentAction: "regenerate",
@@ -64,10 +64,10 @@ export const MVP_RULES: ArchRule[] = [
     agentCommand: "mandu_check_location",
   },
   {
-    id: "FORBIDDEN_IMPORT",
+    id: "FORBIDDEN_IMPORT",
     name: "Forbidden Import in Generated",
     description: "Generated 파일에서 금지된 모듈 import",
-    pattern: "generated/**",
+    pattern: "**/generated/**",
     action: "warn",
     message: "Generated 파일에서 금지된 모듈이 import되었습니다.",
     forbiddenImports: ["fs", "child_process", "cluster", "worker_threads"],