@mandujs/core 0.9.22 → 0.9.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -14,7 +14,7 @@
     "src/**/*"
   ],
   "scripts": {
-    "test": "bun test",
+    "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
     "test:hydration": "bun test tests/hydration",
     "test:streaming": "bun test tests/streaming-ssr",
     "test:watch": "bun test --watch"

package/src/runtime/router.test.ts

@@ -0,0 +1,423 @@
+/**
+ * Router v5 Tests
+ *
+ * Test cases:
+ * 1. Static vs Dynamic Priority
+ * 2. Parameter Matching
+ * 3. Wildcard Matching
+ * 4. Security (URI encoding)
+ * 5. Validation Errors
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  Router,
+  RouterError,
+  createRouter,
+  WILDCARD_PARAM_KEY,
+} from "./router";
+import type { RouteSpec } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test Fixtures
+// ═══════════════════════════════════════════════════════════════════════════
+
+function makeRoute(id: string, pattern: string, kind: "page" | "api" = "api"): RouteSpec {
+  return {
+    id,
+    pattern,
+    kind,
+    module: `generated/${id}.route.ts`,
+    ...(kind === "page" ? { componentModule: `generated/${id}.route.tsx` } : {}),
+  } as RouteSpec;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. Static vs Dynamic Priority
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Static vs Dynamic Priority", () => {
+  test("static route takes precedence over param route", () => {
+    const router = createRouter([
+      makeRoute("todos-item", "/api/todos/:id"),
+      makeRoute("todos-stats", "/api/todos/stats"),
+    ]);
+
+    const result = router.match("/api/todos/stats");
+
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("todos-stats");
+    expect(result!.params).toEqual({});
+  });
+
+  test("static route precedence regardless of registration order", () => {
+    // Register static AFTER dynamic
+    const router = createRouter([
+      makeRoute("users-item", "/users/:id"),
+      makeRoute("users-me", "/users/me"),
+    ]);
+
+    expect(router.match("/users/me")!.route.id).toBe("users-me");
+    expect(router.match("/users/123")!.route.id).toBe("users-item");
+  });
+
+  test("root path matching", () => {
+    const router = createRouter([
+      makeRoute("home", "/", "page"),
+      makeRoute("api", "/api"),
+    ]);
+
+    expect(router.match("/")!.route.id).toBe("home");
+    expect(router.match("/api")!.route.id).toBe("api");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. Parameter Matching
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Parameter Matching", () => {
+  test("extracts single param correctly", () => {
+    const router = createRouter([
+      makeRoute("todos-item", "/api/todos/:id"),
+    ]);
+
+    const result = router.match("/api/todos/123");
+
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("todos-item");
+    expect(result!.params).toEqual({ id: "123" });
+  });
+
+  test("extracts multiple params correctly", () => {
+    const router = createRouter([
+      makeRoute("user-post", "/users/:userId/posts/:postId"),
+    ]);
+
+    const result = router.match("/users/42/posts/99");
+
+    expect(result).not.toBeNull();
+    expect(result!.params).toEqual({ userId: "42", postId: "99" });
+  });
+
+  test("decodes UTF-8 encoded params", () => {
+    const router = createRouter([
+      makeRoute("user", "/user/:name"),
+    ]);
+
+    // café encoded as caf%C3%A9
+    const result = router.match("/user/caf%C3%A9");
+
+    expect(result).not.toBeNull();
+    expect(result!.params).toEqual({ name: "café" });
+  });
+
+  test("handles non-ASCII static routes", () => {
+    const router = createRouter([
+      makeRoute("cafe", "/café", "page"),
+    ]);
+
+    expect(router.match("/café")!.route.id).toBe("cafe");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. Wildcard Matching
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Wildcard Matching", () => {
+  test("matches wildcard with remaining path", () => {
+    const router = createRouter([
+      makeRoute("files", "/files/*"),
+    ]);
+
+    const result = router.match("/files/a/b/c");
+
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("files");
+    expect(result!.params).toEqual({ [WILDCARD_PARAM_KEY]: "a/b/c" });
+  });
+
+  test("wildcard with single segment", () => {
+    const router = createRouter([
+      makeRoute("docs", "/docs/*"),
+    ]);
+
+    const result = router.match("/docs/readme");
+
+    expect(result!.params).toEqual({ [WILDCARD_PARAM_KEY]: "readme" });
+  });
+
+  test("Policy A: wildcard does NOT match base path", () => {
+    const router = createRouter([
+      makeRoute("files", "/files/*"),
+    ]);
+
+    // /files/* should NOT match /files
+    expect(router.match("/files")).toBeNull();
+    expect(router.match("/files/")).toBeNull(); // normalized to /files
+  });
+
+  test("static route takes precedence over wildcard", () => {
+    const router = createRouter([
+      makeRoute("files-wildcard", "/files/*"),
+      makeRoute("files-readme", "/files/readme"),
+    ]);
+
+    expect(router.match("/files/readme")!.route.id).toBe("files-readme");
+    expect(router.match("/files/other")!.route.id).toBe("files-wildcard");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. Security (URI Encoding)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Security", () => {
+  test("blocks %2F (encoded slash) in path segments", () => {
+    const router = createRouter([
+      makeRoute("user", "/user/:name"),
+    ]);
+
+    // a%2Fb = a/b encoded
+    const result = router.match("/user/a%2Fb");
+
+    expect(result).toBeNull();
+  });
+
+  test("blocks double-encoded slash (%252F)", () => {
+    const router = createRouter([
+      makeRoute("user", "/user/:name"),
+    ]);
+
+    // %252F decodes to %2F
+    const result = router.match("/user/%252F");
+
+    expect(result).toBeNull();
+  });
+
+  test("blocks malformed UTF-8 encoding", () => {
+    const router = createRouter([
+      makeRoute("user", "/user/:name"),
+    ]);
+
+    // Invalid UTF-8 sequence
+    const result = router.match("/user/%C0%AE");
+
+    expect(result).toBeNull();
+  });
+
+  test("allows valid percent-encoded characters", () => {
+    const router = createRouter([
+      makeRoute("search", "/search/:query"),
+    ]);
+
+    // hello%20world = "hello world"
+    const result = router.match("/search/hello%20world");
+
+    expect(result).not.toBeNull();
+    expect(result!.params).toEqual({ query: "hello world" });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. Validation Errors
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Validation Errors", () => {
+  test("throws DUPLICATE_PATTERN for same pattern", () => {
+    expect(() => {
+      createRouter([
+        makeRoute("route1", "/api/users"),
+        makeRoute("route2", "/api/users"),
+      ]);
+    }).toThrow(RouterError);
+
+    try {
+      createRouter([
+        makeRoute("route1", "/api/users"),
+        makeRoute("route2", "/api/users"),
+      ]);
+    } catch (e) {
+      expect(e).toBeInstanceOf(RouterError);
+      expect((e as RouterError).code).toBe("DUPLICATE_PATTERN");
+      expect((e as RouterError).routeId).toBe("route2");
+      expect((e as RouterError).conflictsWith).toBe("route1");
+    }
+  });
+
+  test("throws DUPLICATE_PATTERN for normalized duplicates (trailing slash)", () => {
+    expect(() => {
+      createRouter([
+        makeRoute("route1", "/api/users"),
+        makeRoute("route2", "/api/users/"),
+      ]);
+    }).toThrow(RouterError);
+
+    try {
+      createRouter([
+        makeRoute("route1", "/api/users"),
+        makeRoute("route2", "/api/users/"),
+      ]);
+    } catch (e) {
+      expect((e as RouterError).code).toBe("DUPLICATE_PATTERN");
+    }
+  });
+
+  test("throws PARAM_NAME_CONFLICT for same-depth param mismatch", () => {
+    expect(() => {
+      createRouter([
+        makeRoute("users", "/users/:id"),
+        makeRoute("users-by-name", "/users/:name"),
+      ]);
+    }).toThrow(RouterError);
+
+    try {
+      createRouter([
+        makeRoute("users", "/users/:id"),
+        makeRoute("users-by-name", "/users/:name"),
+      ]);
+    } catch (e) {
+      expect((e as RouterError).code).toBe("PARAM_NAME_CONFLICT");
+    }
+  });
+
+  test("allows same param name across different paths", () => {
+    // These should NOT conflict - different parent paths
+    const router = createRouter([
+      makeRoute("users", "/users/:id"),
+      makeRoute("posts", "/posts/:id"),
+    ]);
+
+    expect(router.match("/users/1")!.params).toEqual({ id: "1" });
+    expect(router.match("/posts/2")!.params).toEqual({ id: "2" });
+  });
+
+  test("throws WILDCARD_NOT_LAST for non-terminal wildcard", () => {
+    expect(() => {
+      createRouter([
+        makeRoute("invalid", "/files/*/more"),
+      ]);
+    }).toThrow(RouterError);
+
+    try {
+      createRouter([
+        makeRoute("invalid", "/files/*/more"),
+      ]);
+    } catch (e) {
+      expect((e as RouterError).code).toBe("WILDCARD_NOT_LAST");
+    }
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. Router API
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Router API", () => {
+  test("getStats returns correct counts", () => {
+    const router = createRouter([
+      makeRoute("home", "/"),
+      makeRoute("health", "/api/health"),
+      makeRoute("todos-item", "/api/todos/:id"),
+      makeRoute("files", "/files/*"),
+    ]);
+
+    const stats = router.getStats();
+
+    expect(stats.staticCount).toBe(2); // / and /api/health
+    expect(stats.dynamicCount).toBe(2); // /api/todos/:id and /files/*
+    expect(stats.totalRoutes).toBe(4);
+  });
+
+  test("getRoutes returns all registered routes", () => {
+    const routes = [
+      makeRoute("home", "/"),
+      makeRoute("users", "/users/:id"),
+    ];
+    const router = createRouter(routes);
+
+    const retrieved = router.getRoutes();
+
+    expect(retrieved.length).toBe(2);
+    expect(retrieved.map((r) => r.id).sort()).toEqual(["home", "users"]);
+  });
+
+  test("addRoute adds route to existing router", () => {
+    const router = createRouter([
+      makeRoute("home", "/"),
+    ]);
+
+    router.addRoute(makeRoute("about", "/about"));
+
+    expect(router.match("/about")).not.toBeNull();
+    expect(router.getStats().totalRoutes).toBe(2);
+  });
+
+  test("addRoute validates against existing routes", () => {
+    const router = createRouter([
+      makeRoute("home", "/"),
+    ]);
+
+    expect(() => {
+      router.addRoute(makeRoute("home2", "/"));
+    }).toThrow(RouterError);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. Edge Cases
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Edge Cases", () => {
+  test("empty routes", () => {
+    const router = createRouter([]);
+
+    expect(router.match("/")).toBeNull();
+    expect(router.getStats().totalRoutes).toBe(0);
+  });
+
+  test("deep nested paths", () => {
+    const router = createRouter([
+      makeRoute("deep", "/a/b/c/d/e/:id"),
+    ]);
+
+    const result = router.match("/a/b/c/d/e/123");
+
+    expect(result!.params).toEqual({ id: "123" });
+  });
+
+  test("consecutive params", () => {
+    const router = createRouter([
+      makeRoute("date", "/calendar/:year/:month/:day"),
+    ]);
+
+    const result = router.match("/calendar/2025/01/30");
+
+    expect(result!.params).toEqual({
+      year: "2025",
+      month: "01",
+      day: "30",
+    });
+  });
+
+  test("param followed by static", () => {
+    const router = createRouter([
+      makeRoute("user-posts", "/users/:id/posts"),
+    ]);
+
+    const result = router.match("/users/42/posts");
+
+    expect(result!.route.id).toBe("user-posts");
+    expect(result!.params).toEqual({ id: "42" });
+  });
+
+  test("trailing slash normalization", () => {
+    const router = createRouter([
+      makeRoute("api", "/api"),
+    ]);
+
+    expect(router.match("/api")).not.toBeNull();
+    expect(router.match("/api/")).not.toBeNull(); // normalized to /api
+  });
+});

package/src/runtime/router.ts

@@ -1,83 +1,502 @@
+/**
+ * Mandu Router v5 - Hybrid Trie Architecture
+ *
+ * @version 5.0.0
+ * @see docs/architecture/06_mandu_router_v5_hybrid_trie.md
+ *
+ * Features:
+ * - Static routes: Map O(1) lookup
+ * - Dynamic routes: Trie O(k) lookup (k = segments)
+ * - Security: %2F blocking, double-encoding protection
+ * - Validation: Duplicate detection, param name conflicts
+ */
+
 import type { RouteSpec } from "../spec/schema";
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Encoded slash pattern for security checks */
+const ENCODED_SLASH_PATTERN = /%2f/i;
+
+/** Fixed key for wildcard params */
+const WILDCARD_PARAM_KEY = "$wildcard";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types & Interfaces
+// ═══════════════════════════════════════════════════════════════════════════
+
 export interface MatchResult {
   route: RouteSpec;
   params: Record<string, string>;
 }
 
+export interface RouterOptions {
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+export interface RouterStats {
+  staticCount: number;
+  dynamicCount: number;
+  totalRoutes: number;
+}
+
+export type RouterErrorCode =
+  | "DUPLICATE_PATTERN"
+  | "PARAM_NAME_CONFLICT"
+  | "WILDCARD_NOT_LAST"
+  | "ROUTE_CONFLICT";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RouterError Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Router-specific error with error code for programmatic handling
+ */
+export class RouterError extends Error {
+  public readonly name = "RouterError";
+
+  constructor(
+    message: string,
+    public readonly code: RouterErrorCode,
+    public readonly routeId: string,
+    public readonly conflictsWith?: string
+  ) {
+    super(message);
+
+    // V8 stack trace capture
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, RouterError);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TrieNode Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 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
+ * - route: Route that terminates at this node
+ */
+class TrieNode {
+  /** Static segment children */
+  children: Map<string, TrieNode> = new Map();
+
+  /** Parameter child with name for conflict detection */
+  paramChild: { name: string; node: TrieNode } | null = null;
+
+  /** Wildcard route (only valid at leaf) */
+  wildcardRoute: RouteSpec | null = null;
+
+  /** Route terminating at this node */
+  route: RouteSpec | null = null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Security Functions
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Safe URI component decoding with 4-layer security
+ *
+ * Security checks:
+ * 1. Pre-decode %2F check (encoded slash)
+ * 2. decodeURIComponent execution
+ * 3. Post-decode slash check
+ * 4. Double-encoding check (%252F -> %2F)
+ *
+ * @returns Decoded string or null if security violation
+ */
+function safeDecodeURIComponent(str: string): string | null {
+  // 1. Pre-decode %2F check
+  if (ENCODED_SLASH_PATTERN.test(str)) {
+    return null;
+  }
+
+  // 2. Decode
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(str);
+  } catch {
+    // Malformed UTF-8
+    return null;
+  }
+
+  // 3. Post-decode slash check
+  if (decoded.includes("/")) {
+    return null;
+  }
+
+  // 4. Double-encoding check
+  if (ENCODED_SLASH_PATTERN.test(decoded)) {
+    return null;
+  }
+
+  return decoded;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Router Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Hybrid Trie Router
+ *
+ * Matching order:
+ * 1. Static routes (Map) - O(1)
+ * 2. Dynamic routes (Trie) - O(k)
+ *
+ * Static routes always take precedence over dynamic routes.
+ */
 export class Router {
-  private routes: RouteSpec[] = [];
-  private compiledPatterns: Map<string, { regex: RegExp; paramNames: string[] }> = new Map();
+  /** Static routes for O(1) lookup */
+  private statics: Map<string, RouteSpec> = new Map();
+
+  /** Trie root for dynamic routes */
+  private trie: TrieNode = new TrieNode();
 
-  constructor(routes: RouteSpec[] = []) {
+  /** Registered patterns for duplicate detection (normalized -> routeId) */
+  private registeredPatterns: Map<string, string> = new Map();
+
+  /** Debug mode */
+  private debug: boolean;
+
+  constructor(routes: RouteSpec[] = [], options: RouterOptions = {}) {
+    this.debug = options.debug ?? false;
     this.setRoutes(routes);
   }
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Public API
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Set routes (replaces existing routes)
+   * @throws {RouterError} On validation failure
+   */
   setRoutes(routes: RouteSpec[]): void {
-    this.routes = routes;
-    this.compiledPatterns.clear();
+    // Clear existing state
+    this.statics.clear();
+    this.trie = new TrieNode();
+    this.registeredPatterns.clear();
 
+    // Register each route with validation
     for (const route of routes) {
-      this.compiledPatterns.set(route.id, this.compilePattern(route.pattern));
+      this.validateAndRegister(route);
+    }
+
+    if (this.debug) {
+      console.log(`[Router] Registered ${routes.length} routes`);
+      console.log(`[Router] Static: ${this.statics.size}, Dynamic: ${this.registeredPatterns.size - this.statics.size}`);
+    }
+  }
+
+  /**
+   * Add a single route
+   * @throws {RouterError} On validation failure
+   */
+  addRoute(route: RouteSpec): void {
+    this.validateAndRegister(route);
+  }
+
+  /**
+   * Match pathname to route
+   *
+   * @returns MatchResult or null (including security violations)
+   */
+  match(pathname: string): MatchResult | null {
+    const normalized = this.normalize(pathname);
+
+    // 1. Static lookup O(1)
+    const staticRoute = this.statics.get(normalized);
+    if (staticRoute) {
+      if (this.debug) {
+        console.log(`[Router] Static match: ${normalized} -> ${staticRoute.id}`);
+      }
+      return { route: staticRoute, params: {} };
+    }
+
+    // 2. Trie lookup O(k)
+    return this.matchTrie(normalized);
+  }
+
+  /**
+   * Get all registered routes
+   */
+  getRoutes(): RouteSpec[] {
+    const routes: RouteSpec[] = [];
+
+    // Collect from statics
+    for (const route of this.statics.values()) {
+      routes.push(route);
     }
+
+    // Collect from trie (DFS)
+    this.collectTrieRoutes(this.trie, routes);
+
+    return routes;
   }
 
-  private compilePattern(pattern: string): { regex: RegExp; paramNames: string[] } {
-    const paramNames: string[] = [];
+  /**
+   * Get router statistics
+   */
+  getStats(): RouterStats {
+    const staticCount = this.statics.size;
+    const totalRoutes = this.registeredPatterns.size;
+    return {
+      staticCount,
+      dynamicCount: totalRoutes - staticCount,
+      totalRoutes,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Normalization
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Normalize path (P0-1)
+   * - "/" stays as is
+   * - Remove trailing slash for others
+   */
+  private normalize(path: string): string {
+    if (path === "/") return "/";
+    return path.replace(/\/+$/, "");
+  }
 
-    // 파라미터 플레이스홀더를 임시 토큰으로 대체
-    const PARAM_PLACEHOLDER = "\x00PARAM\x00";
-    const paramMatches: string[] = [];
+  /**
+   * Check if pattern is static (no params or wildcards)
+   */
+  private isStatic(pattern: string): boolean {
+    return !pattern.includes(":") && !pattern.includes("*");
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Validation & Registration
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Validate and register a route
+   * @throws {RouterError} On validation failure
+   */
+  private validateAndRegister(route: RouteSpec): void {
+    const { id, pattern } = route;
+    const normalized = this.normalize(pattern);
+    const segments = normalized.split("/").filter(Boolean);
+
+    // P0-1: Duplicate check on normalized pattern
+    const existing = this.registeredPatterns.get(normalized);
+    if (existing) {
+      throw new RouterError(
+        `Pattern "${pattern}" duplicates existing pattern from route "${existing}"`,
+        "DUPLICATE_PATTERN",
+        id,
+        existing
+      );
+    }
+
+    // P0-2: Segment-based wildcard validation
+    const wildcardIdx = segments.findIndex((s) => s === "*");
+    if (wildcardIdx !== -1 && wildcardIdx !== segments.length - 1) {
+      throw new RouterError(
+        `Wildcard must be the last segment in pattern "${pattern}"`,
+        "WILDCARD_NOT_LAST",
+        id
+      );
+    }
 
-    const withPlaceholders = pattern.replace(
-      /:([a-zA-Z_][a-zA-Z0-9_]*)/g,
-      (_, paramName) => {
-        paramMatches.push(paramName);
-        return PARAM_PLACEHOLDER;
+    // Register based on type
+    if (this.isStatic(normalized)) {
+      this.statics.set(normalized, route);
+    } else {
+      this.insertTrie(normalized, segments, route);
+    }
+
+    this.registeredPatterns.set(normalized, id);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Private: Trie Operations
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Insert route into trie
+   * @throws {RouterError} On param name conflict
+   */
+  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;
       }
-    );
-
-    // regex 특수문자 이스케이프 (/ 포함)
-    const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
-
-    // 플레이스홀더를 캡처 그룹으로 복원하고 paramNames 채우기
-    let paramIndex = 0;
-    const regexStr = escaped.replace(
-      new RegExp(PARAM_PLACEHOLDER.replace(/\x00/g, "\\x00"), "g"),
-      () => {
-        paramNames.push(paramMatches[paramIndex++]);
-        return "([^/]+)";
+
+      // Parameter handling
+      if (seg.startsWith(":")) {
+        const paramName = seg.slice(1);
+
+        // P0-3: Param name conflict detection
+        if (node.paramChild) {
+          if (node.paramChild.name !== paramName) {
+            throw new RouterError(
+              `Parameter name conflict at depth ${i}: ":${paramName}" vs existing ":${node.paramChild.name}" in pattern "${pattern}"`,
+              "PARAM_NAME_CONFLICT",
+              route.id
+            );
+          }
+          node = node.paramChild.node;
+        } else {
+          const newNode = new TrieNode();
+          node.paramChild = { name: paramName, node: newNode };
+          node = newNode;
+        }
+        continue;
       }
-    );
 
-    const regex = new RegExp(`^${regexStr}$`);
-    return { regex, paramNames };
+      // Static segment handling
+      if (!node.children.has(seg)) {
+        node.children.set(seg, new TrieNode());
+      }
+      node = node.children.get(seg)!;
+    }
+
+    node.route = route;
   }
 
-  match(pathname: string): MatchResult | null {
-    for (const route of this.routes) {
-      const compiled = this.compiledPatterns.get(route.id);
-      if (!compiled) continue;
-
-      const match = pathname.match(compiled.regex);
-      if (match) {
-        const params: Record<string, string> = {};
-        compiled.paramNames.forEach((name, index) => {
-          params[name] = match[index + 1];
-        });
-
-        return { route, params };
+  /**
+   * Match pathname against trie
+   */
+  private matchTrie(pathname: string): MatchResult | null {
+    const segments = pathname.split("/").filter(Boolean);
+    const params: Record<string, string> = {};
+    let node = this.trie;
+
+    // Track wildcard candidate for backtracking
+    let wildcardMatch: { route: RouteSpec; 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 };
+      }
+
+      // 1. Try static child first (higher priority)
+      const staticChild = node.children.get(seg);
+      if (staticChild) {
+        node = staticChild;
+        continue;
+      }
+
+      // 2. Try param child
+      if (node.paramChild) {
+        const decoded = safeDecodeURIComponent(seg);
+        if (decoded === null) {
+          // Security violation
+          if (this.debug) {
+            console.log(`[Router] Security block: ${seg}`);
+          }
+          return null;
+        }
+        params[node.paramChild.name] = decoded;
+        node = node.paramChild.node;
+        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 },
+        };
+      }
+
+      // No match at all
+      return null;
+    }
+
+    // End of path - check for route at current node
+    if (node.route) {
+      if (this.debug) {
+        console.log(`[Router] Trie match: ${node.route.id}`);
+      }
+      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`);
       }
     }
 
+    // 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 },
+      };
+    }
+
     return null;
   }
 
-  getRoutes(): RouteSpec[] {
-    return [...this.routes];
+  /**
+   * Collect routes from trie (for getRoutes)
+   */
+  private collectTrieRoutes(node: TrieNode, routes: RouteSpec[]): void {
+    if (node.route && !this.statics.has(this.normalize(node.route.pattern))) {
+      routes.push(node.route);
+    }
+
+    if (node.wildcardRoute) {
+      routes.push(node.wildcardRoute);
+    }
+
+    for (const child of node.children.values()) {
+      this.collectTrieRoutes(child, routes);
+    }
+
+    if (node.paramChild) {
+      this.collectTrieRoutes(node.paramChild.node, routes);
+    }
   }
 }
 
-export function createRouter(routes: RouteSpec[] = []): Router {
-  return new Router(routes);
+// ═══════════════════════════════════════════════════════════════════════════
+// Factory Function
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a new router instance
+ */
+export function createRouter(routes: RouteSpec[] = [], options: RouterOptions = {}): Router {
+  return new Router(routes, options);
 }
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Exports
+// ═══════════════════════════════════════════════════════════════════════════
+
+export { WILDCARD_PARAM_KEY };

package/src/runtime/streaming-ssr.ts

@@ -83,8 +83,7 @@ export interface StreamingSSROptions {
   routePattern?: string;
   /** Critical 데이터 (Shell과 함께 즉시 전송) - JSON-serializable object만 허용 */
   criticalData?: Record<string, unknown>;
-  /** Deferred 데이터 (Suspense 후 스트리밍) */
-  deferredData?: Record<string, unknown>;
+  // Note: deferredData는 renderWithDeferredData의 deferredPromises로 대체됨
   /** Hydration 설정 */
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
@@ -121,6 +120,11 @@ export interface StreamingSSROptions {
   onError?: (error: Error) => void;
   /** 메트릭 콜백 (observability) */
   onMetrics?: (metrics: StreamingMetrics) => void;
+  /**
+   * HTML 닫기 태그 생략 여부 (내부용)
+   * true이면 </body></html>을 생략하여 deferred 스크립트 삽입 지점 확보
+   */
+  _skipHtmlClose?: boolean;
 }
 
 export interface StreamingLoaderResult<T = unknown> {
@@ -239,7 +243,10 @@ function warnStreamingCaveats(isDev: boolean): void {
  */
 function generateErrorScript(error: Error, routeId: string): string {
   const safeMessage = error.message
-    .replace(/</g, "\\u003c")
+    .replace(/\\/g, "\\\\")      // 백슬래시 먼저 (다른 이스케이프에 영향)
+    .replace(/\n/g, "\\n")       // 줄바꿈
+    .replace(/\r/g, "\\r")       // 캐리지 리턴
+    .replace(/</g, "\\u003c")    // XSS 방지
     .replace(/>/g, "\\u003e")
     .replace(/"/g, "\\u0022");
 
@@ -387,6 +394,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     islandOpenTag = `<div data-mandu-island="${routeId}" data-mandu-src="${bundleSrc}" data-mandu-priority="${priority}">`;
   }
 
+  // Import map은 module 스크립트보다 먼저 정의되어야 bare specifier 해석 가능
   return `<!DOCTYPE html>
 <html lang="${lang}">
 <head>
@@ -394,22 +402,22 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
   ${loadingStyles}
-  ${headTags}
   ${importMapScript}
+  ${headTags}
 </head>
 <body>
   <div id="root">${islandOpenTag}`;
 }
 
 /**
- * Streaming용 HTML Tail 생성 (</div id="root"> ~ </html>)
+ * Streaming용 HTML Tail 스크립트 생성 (</div id="root"> ~ 스크립트들)
+ * `</body></html>`은 포함하지 않음 - deferred 스크립트 삽입 지점 확보
  */
-function generateHTMLTail(options: StreamingSSROptions): string {
+function generateHTMLTailContent(options: StreamingSSROptions): string {
   const {
     routeId,
     routePattern,
     criticalData,
-    deferredData,
     bundleManifest,
     isDev = false,
     hmrPort,
@@ -481,11 +489,27 @@ function generateHTMLTail(options: StreamingSSROptions): string {
   const islandCloseTag = needsHydration ? "</div>" : "";
 
   return `${islandCloseTag}</div>
-  ${scripts.join("\n  ")}
+  ${scripts.join("\n  ")}`;
+}
+
+/**
+ * HTML 문서 닫기 태그
+ * Deferred 스크립트 삽입 후 호출
+ */
+function generateHTMLClose(): string {
+  return `
 </body>
 </html>`;
 }
 
+/**
+ * Streaming용 HTML Tail 생성 (</div id="root"> ~ </html>)
+ * 하위 호환성 유지 - 내부적으로 generateHTMLTailContent + generateHTMLClose 사용
+ */
+function generateHTMLTail(options: StreamingSSROptions): string {
+  return generateHTMLTailContent(options) + generateHTMLClose();
+}
+
 /**
  * Deferred 데이터 인라인 스크립트 생성
  * Streaming 중에 데이터 도착 시 DOM에 주입
@@ -573,6 +597,7 @@ export async function renderToStream(
     isDev = false,
     routeId = "unknown",
     criticalData,
+    streamTimeout,
   } = options;
 
   // 메트릭 수집
@@ -595,7 +620,10 @@ export async function renderToStream(
 
   const encoder = new TextEncoder();
   const htmlShell = generateHTMLShell(options);
-  const htmlTail = generateHTMLTail(options);
+  // _skipHtmlClose가 true이면 </body></html> 생략 (deferred 스크립트 삽입용)
+  const htmlTail = options._skipHtmlClose
+    ? generateHTMLTailContent(options)
+    : generateHTMLTail(options);
 
   let shellSent = false;
 
@@ -637,8 +665,20 @@ export async function renderToStream(
 
   // Custom stream으로 래핑 (Shell + React Content + Tail)
   let tailSent = false;
+  let streamTimedOut = false;
   const reader = reactStream.getReader();
 
+  // 스트림 타임아웃 타이머 (옵션이 있을 때만)
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  if (streamTimeout && streamTimeout > 0) {
+    timeoutId = setTimeout(() => {
+      streamTimedOut = true;
+      if (isDev) {
+        console.warn(`[Mandu Streaming] Stream timeout after ${streamTimeout}ms`);
+      }
+    }, streamTimeout);
+  }
+
   return new ReadableStream<Uint8Array>({
     async start(controller) {
       // Shell 즉시 전송 (TTFB 최소화의 핵심!)
@@ -650,9 +690,38 @@ export async function renderToStream(
 
     async pull(controller) {
       try {
+        // 타임아웃 체크
+        if (streamTimedOut) {
+          const timeoutError = new Error(`Stream timeout: exceeded ${streamTimeout}ms`);
+          metrics.hasError = true;
+
+          const streamingError: StreamingError = {
+            error: timeoutError,
+            isShellError: false,
+            recoverable: true,
+            timestamp: Date.now(),
+          };
+          onStreamError?.(streamingError);
+
+          controller.enqueue(encoder.encode(generateErrorScript(timeoutError, routeId)));
+
+          if (!tailSent) {
+            controller.enqueue(encoder.encode(htmlTail));
+            tailSent = true;
+            metrics.allReadyTime = Date.now() - metrics.startTime;
+            onMetrics?.(metrics);
+          }
+          controller.close();
+          reader.cancel();
+          return;
+        }
+
         const { done, value } = await reader.read();
 
         if (done) {
+          // 타이머 정리
+          if (timeoutId) clearTimeout(timeoutId);
+
           if (!tailSent) {
             controller.enqueue(encoder.encode(htmlTail));
             tailSent = true;
@@ -670,6 +739,9 @@ export async function renderToStream(
         // React 컨텐츠를 그대로 스트리밍
         controller.enqueue(value);
       } catch (error) {
+        // 타이머 정리
+        if (timeoutId) clearTimeout(timeoutId);
+
         const err = error instanceof Error ? error : new Error(String(error));
         metrics.hasError = true;
 
@@ -697,6 +769,7 @@ export async function renderToStream(
     },
 
     cancel() {
+      if (timeoutId) clearTimeout(timeoutId);
       reader.cancel();
     },
   });
@@ -845,11 +918,13 @@ export async function renderWithDeferredData(
     : Promise.resolve().then(() => { allDeferredSettled = true; });
 
   // 2. Base stream 즉시 시작 (TTFB 최소화의 핵심!)
+  //    _skipHtmlClose: true로 </body></html> 생략 → deferred 스크립트 삽입 지점 확보
   let baseMetrics: StreamingMetrics | null = null;
   const baseStream = await renderToStream(element, {
     ...restOptions,
     routeId,
     isDev,
+    _skipHtmlClose: true, // deferred 스크립트를 </body> 전에 삽입하기 위해
     onMetrics: (metrics) => {
       baseMetrics = metrics;
     },
@@ -885,6 +960,9 @@ export async function renderWithDeferredData(
         console.log(`[Mandu Streaming] Injected ${injectedCount} deferred scripts`);
       }
 
+      // HTML 닫기 태그 추가 (</body></html>)
+      controller.enqueue(encoder.encode(generateHTMLClose()));
+
       // 최종 메트릭 보고 (injectedCount가 실제 메트릭)
       if (onMetrics && baseMetrics) {
         onMetrics({