@mandujs/core 0.53.2 → 0.54.0

package/src/runtime/router.ts

@@ -81,14 +81,14 @@ export class RouterError extends Error {
 /**
  * Wildcard 설정
  */
-interface WildcardConfig {
-  /** 파라미터 이름 (예: "path" for :path*) */
-  name: string;
-  /** optional 여부 (예: :path*? 는 optional) */
-  optional: boolean;
-  /** 라우트 정보 */
-  route: RouteSpec;
-}
+interface WildcardConfig {
+  /** 파라미터 이름 (예: "path" for :path*) */
+  name: string;
+  /** optional 여부 (예: :path*? 는 optional) */
+  optional: boolean;
+  /** 라우트 정보 */
+  route: RouteSpec;
+}
 
 /**
  * Trie node for dynamic route matching
@@ -133,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;
@@ -158,26 +158,26 @@ function safeDecodeURIComponent(str: string): string | null {
     return null;
   }
 
-  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("/");
-}
+  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
@@ -371,47 +371,47 @@ 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];
-
-      // 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;
-      }
+    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,
+        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,
           };
 
@@ -494,18 +494,18 @@ export class Router {
         continue;
       }
 
-      // 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,
+      // 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 },
         };
       }
@@ -522,36 +522,36 @@ export class Router {
       return { route: node.route, params };
     }
 
-    // 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`);
-      }
+    // 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 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 },
-      };
-    }
+    // 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;
   }

package/src/runtime/server.ts

@@ -1,28 +1,28 @@
-import type { BunFile, Server, ServerWebSocket } from "bun";
+import type { BunFile, Server, ServerWebSocket } from "bun";
 import type { RoutesManifest, RouteSpec, HydrationConfig, StaticParamSetSchema } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling, RenderMode } from "../filling/filling";
 import { ManduContext, CookieManager } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR, renderStreamingResponse, resolveAsyncElement } from "./ssr";
-import {
-  resolveMetadata,
-  renderMetadata,
-  renderTitle,
-  type Metadata,
+import {
+  resolveMetadata,
+  renderMetadata,
+  renderTitle,
+  type Metadata,
   type MetadataItem,
-  type GenerateMetadata,
-} from "../seo";
-import { type ErrorFallbackProps } from "./boundary";
-import React from "react";
+  type GenerateMetadata,
+} from "../seo";
+import { type ErrorFallbackProps } from "./boundary";
+import React from "react";
 import path from "path";
 import fs from "fs/promises";
 import { PORTS } from "../constants";
 import {
-  type CacheStore,
-  type CacheStoreStats,
-  type CacheConfig,
-  lookupCache,
+  type CacheStore,
+  type CacheStoreStats,
+  type CacheConfig,
+  lookupCache,
   createCacheEntry,
   createCachedResponse,
   computeCacheControl,
@@ -51,12 +51,12 @@ import {
 } from "./cors";
 import { validateImportPath } from "./security";
 import { KITCHEN_PREFIX, KitchenHandler, recordRequest } from "../kitchen/kitchen-handler";
-import {
-  eventBus,
-  type EventType,
-  type ObservabilityEvent,
-  type ObservabilitySeverity,
-} from "../observability/event-bus";
+import {
+  eventBus,
+  type EventType,
+  type ObservabilityEvent,
+  type ObservabilitySeverity,
+} from "../observability/event-bus";
 import {
   HEAP_ENDPOINT,
   METRICS_ENDPOINT,
@@ -65,12 +65,12 @@ import {
   isObservabilityExposed,
   recordHttpRequest,
 } from "../observability/metrics";
-import {
-  handleOpenAPIRequest,
-  isOpenAPIEndpointEnabled,
-  resolveOpenAPIEndpointSettings,
-  type OpenAPIEndpointSettings,
-} from "./openapi-endpoint";
+import {
+  handleOpenAPIRequest,
+  isOpenAPIEndpointEnabled,
+  resolveOpenAPIEndpointSettings,
+  type OpenAPIEndpointSettings,
+} from "./openapi-endpoint";
 // Phase 18.ψ — user-facing perf marks dashboard append. We include a
 // `perf` block on the `/_mandu/heap` payload when the feature is active
 // so operators see a unified view (heap + caches + perf histogram).
@@ -81,7 +81,7 @@ import { collectPerfSnapshot } from "../perf/user-marks";
 // `startServer()`; `runWithSpan` is used at the absolute TOP of the
 // request handler so every downstream await (middleware, filling
 // loader, SSR render) inherits the active span via AsyncLocalStorage.
-import type { Tracer } from "../observability/tracing";
+import type { Tracer } from "../observability/tracing";
 import {
   createTracerFromConfig,
   runWithSpan,
@@ -102,10 +102,10 @@ import type { Middleware } from "../middleware/define";
 // Phase 18.λ — scheduler wiring (statically imported so `startServer` stays
 // synchronous; the cost of unused code is trivial — `defineCron` is a thin
 // wrapper around `Bun.cron`).
-import { defineCron as schedulerDefineCron, type CronDef, type CronRegistration } from "../scheduler";
+import { defineCron as schedulerDefineCron, type CronDef, type CronRegistration } from "../scheduler";
 import { setActiveSchedulerRegistration } from "../middleware/scheduler-cron";
 import { createFetchHandler } from "./handler";
-import { wrapBunWebSocket, type WSHandlers, type WSUpgradeData } from "../filling/ws";
+import { wrapBunWebSocket, type WSHandlers, type WSUpgradeData } from "../filling/ws";
 import { handleImageRequest } from "./image-handler";
 import { extractShellHtml, createPPRResponse } from "./ppr";
 import { isRedirectResponse } from "./redirect";
@@ -113,16 +113,16 @@ import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
 // Phase 18.κ — typed RPC dispatch (tRPC-like). See
 // `packages/core/src/contract/rpc.ts` + `docs/architect/typed-rpc.md`.
-import {
-  matchRpcPath,
-  dispatchRpc,
-  registerRpc,
-  clearRpcRegistry,
-  type RpcDefinition,
-  type RpcProcedureRecord,
-} from "../contract/rpc";
-import type { GuardConfig } from "../guard/types";
-import type { ManduHooks, ManduPlugin } from "../plugins/hooks";
+import {
+  matchRpcPath,
+  dispatchRpc,
+  registerRpc,
+  clearRpcRegistry,
+  type RpcDefinition,
+  type RpcProcedureRecord,
+} from "../contract/rpc";
+import type { GuardConfig } from "../guard/types";
+import type { ManduHooks, ManduPlugin } from "../plugins/hooks";
 import { handleMetadataRoute as dispatchMetadataRoute } from "../routes/metadata-routes";
 import {
   DEFAULT_PRERENDER_DIR,
@@ -426,7 +426,7 @@ export interface ServerOptions {
   /**
    * Guard config for Kitchen dev dashboard (dev mode only)
    */
-  guardConfig?: GuardConfig | null;
+  guardConfig?: GuardConfig | null;
   /**
    * SSR 캐시 설정 (ISR/SWR 용).
    *
@@ -582,8 +582,8 @@ export interface ServerOptions {
    * `options.middleware` so they run BEFORE user-declared layers. Both
    * fields are optional; omission is a zero-overhead passthrough.
    */
-  plugins?: readonly ManduPlugin[];
-  configHooks?: Partial<ManduHooks>;
+  plugins?: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
   /**
    * Phase 18.κ — tRPC-like typed RPC endpoints.
    *
@@ -596,7 +596,7 @@ export interface ServerOptions {
    * Typically threaded from `ManduConfig.rpc.endpoints`.
    */
   rpc?: {
-    endpoints?: Record<string, RpcDefinition<RpcProcedureRecord>>;
+    endpoints?: Record<string, RpcDefinition<RpcProcedureRecord>>;
   };
   /**
    * Phase 18.λ — declarative cron scheduler.
@@ -612,7 +612,7 @@ export interface ServerOptions {
    * Typically threaded from `ManduConfig.scheduler`.
    */
   scheduler?: {
-    jobs?: CronDef[];
+    jobs?: CronDef[];
     disabled?: boolean;
   };
   /**
@@ -823,7 +823,7 @@ export interface ServerRegistrySettings {
    * tracing is disabled (the hot path is branch-free). When set, every
    * request opens a root span via `tracer.startSpanFromRequest()`.
    */
-  tracer?: Tracer;
+  tracer?: Tracer;
   /**
    * Production OpenAPI endpoint — resolved from `ServerOptions.openapi`.
    * `undefined` means the endpoint is disabled (hot path branch-free).
@@ -831,7 +831,7 @@ export interface ServerRegistrySettings {
    * `<basePath>.json` / `<basePath>.yaml` short-circuits before route
    * dispatch to serve the cached spec body.
    */
-  openapi?: OpenAPIEndpointSettings;
+  openapi?: OpenAPIEndpointSettings;
   /**
    * Phase 18 — resolved prerender pass-through state. `undefined`
    * means the feature is disabled for this server instance.
@@ -917,7 +917,7 @@ export class ServerRegistry {
   /** Layout slot 파일 경로 캐시 (모듈 경로 → slot 경로 | null) */
   readonly layoutSlotPaths: Map<string, string | null> = new Map();
   /** WebSocket 핸들러 (라우트 ID → WSHandlers) */
-  readonly wsHandlers: Map<string, WSHandlers> = new Map();
+  readonly wsHandlers: Map<string, WSHandlers> = new Map();
   /**
    * Metadata API 캐시 (#186)
    * - pageMetadata: routeId → page 모듈의 static `metadata` export
@@ -925,10 +925,10 @@ export class ServerRegistry {
    * - layoutMetadata: layout 모듈 경로 → static `metadata` export (null = 시도했지만 없음)
    * - layoutGenerateMetadata: layout 모듈 경로 → `generateMetadata` 함수
    */
-  readonly pageMetadata: Map<string, Metadata> = new Map();
-  readonly pageGenerateMetadata: Map<string, GenerateMetadata> = new Map();
-  readonly layoutMetadata: Map<string, Metadata | null> = new Map();
-  readonly layoutGenerateMetadata: Map<string, GenerateMetadata> = new Map();
+  readonly pageMetadata: Map<string, Metadata> = new Map();
+  readonly pageGenerateMetadata: Map<string, GenerateMetadata> = new Map();
+  readonly layoutMetadata: Map<string, Metadata | null> = new Map();
+  readonly layoutGenerateMetadata: Map<string, GenerateMetadata> = new Map();
   settings: ServerRegistrySettings = {
     isDev: false,
     rootDir: process.cwd(),
@@ -1277,7 +1277,7 @@ export function registerNotFoundHandler(handler: PageHandler): void {
   defaultRegistry.registerNotFoundHandler(handler);
 }
 
-export function registerWSHandler(routeId: string, handlers: WSHandlers): void {
+export function registerWSHandler(routeId: string, handlers: WSHandlers): void {
   defaultRegistry.wsHandlers.set(routeId, handlers);
 }
 
@@ -1363,7 +1363,7 @@ function handleEventsStreamRequest(req: Request): Response {
   const filterSource = url.searchParams.get("source") || undefined;
   const filterTrace = url.searchParams.get("trace") || undefined;
 
-  const matches = (e: ObservabilityEvent): boolean => {
+  const matches = (e: ObservabilityEvent): boolean => {
     if (filterType && e.type !== filterType) return false;
     if (filterSeverity && e.severity !== filterSeverity) return false;
     if (filterSource && e.source !== filterSource) return false;
@@ -1444,8 +1444,8 @@ function handleEventsRecentRequest(req: Request): Response {
   const events = eventBus.getRecent(
     count ? Number(count) : undefined,
     {
-      type: type as EventType | undefined,
-      severity: severity as ObservabilitySeverity | undefined,
+      type: type as EventType | undefined,
+      severity: severity as ObservabilitySeverity | undefined,
     },
   );
   const stats = eventBus.getStats(windowMs);
@@ -1551,7 +1551,7 @@ function evictEtagCacheIfNeeded(): void {
  */
 async function computeStrongEtag(
   filePath: string,
-  file: BunFile,
+  file: BunFile,
 ): Promise<string> {
   const size = file.size;
   const mtime = file.lastModified;
@@ -4682,12 +4682,12 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   }
   // ─── End Phase 18.ζ ────────────────────────────────────────────────────
 
-  // Kitchen dev dashboard (dev mode only)
-  if (isDev) {
-    const kitchen = new KitchenHandler({ rootDir, manifest, guardConfig });
-    void kitchen.start();
-    registry.kitchen = kitchen;
-  }
+  // Kitchen dev dashboard (dev mode only)
+  if (isDev) {
+    const kitchen = new KitchenHandler({ rootDir, manifest, guardConfig });
+    void kitchen.start();
+    registry.kitchen = kitchen;
+  }
 
   const router = new Router(manifest.routes);
 
@@ -4869,7 +4869,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   // other boot errors rather than aborting the server. `startServer` is
   // synchronous by contract, so we use the already-imported scheduler
   // module rather than `await import`.
-  let schedulerRegistration: CronRegistration | null = null;
+  let schedulerRegistration: CronRegistration | null = null;
   const jobDefs = schedulerOption?.jobs ?? [];
   const schedulerDisabled = schedulerOption?.disabled === true;
   if (jobDefs.length > 0 && !schedulerDisabled) {
@@ -4921,10 +4921,10 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
             console.error("[scheduler] shutdown error:", err);
           });
       }
-      void server.stop();
-    },
-  };
-}
+      void server.stop();
+    },
+  };
+}
 
 // Clear registries (useful for testing) - deprecated, use clearDefaultRegistry()
 export function clearRegistry(): void {

package/src/runtime/shims.ts

@@ -1,48 +1,48 @@
-/**
- * Runtime Shims for React Compatibility
- *
- * React 19+ 호환성을 위한 런타임 shim 스크립트들을 제공합니다.
- *
- * @module runtime/shims
- */
-
-/**
- * React 19 Client Internals Shim Script
- *
- * React 19에서 react-dom/client가 실행되기 전에 ReactSharedInternals.S가
- * 존재하는지 확인하고 필요시 초기화하는 inline 스크립트입니다.
- *
- * **사용 목적**:
- * - Playwright headless 환경에서 hydration 실패 방지
- * - React 19의 __CLIENT_INTERNALS.S가 null일 수 있는 문제 해결
- * - SSR HTML에 삽입하여 번들 로드 전에 실행
- *
- * **안전성**:
- * - try-catch로 감싸져 있어 오류 발생 시에도 안전
- * - 기존 값이 있으면 덮어쓰지 않음
- * - React가 없거나 internals가 없어도 실패하지 않음
- *
- * @example
- * ```typescript
- * // SSR HTML에 삽입
- * const html = `
- *   ${hydrationScripts}
- *   ${REACT_INTERNALS_SHIM_SCRIPT}
- *   ${routerScript}
- * `;
- * ```
- */
-export const REACT_INTERNALS_SHIM_SCRIPT = `<script>
-// React 19 internals shim: ensure ReactSharedInternals.S exists before react-dom/client runs.
-// Some builds expect React.__CLIENT_INTERNALS... .S to be a function, but it may be null.
-// This shim is safe: it only fills the slot if missing.
-(function(){
-  try {
-    var React = window.React;
-    var i = React && React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
-    if (i && i.S == null) {
-      i.S = function(){};
-    }
-  } catch(e) {}
-})();
-</script>`;
+/**
+ * Runtime Shims for React Compatibility
+ *
+ * React 19+ 호환성을 위한 런타임 shim 스크립트들을 제공합니다.
+ *
+ * @module runtime/shims
+ */
+
+/**
+ * React 19 Client Internals Shim Script
+ *
+ * React 19에서 react-dom/client가 실행되기 전에 ReactSharedInternals.S가
+ * 존재하는지 확인하고 필요시 초기화하는 inline 스크립트입니다.
+ *
+ * **사용 목적**:
+ * - Playwright headless 환경에서 hydration 실패 방지
+ * - React 19의 __CLIENT_INTERNALS.S가 null일 수 있는 문제 해결
+ * - SSR HTML에 삽입하여 번들 로드 전에 실행
+ *
+ * **안전성**:
+ * - try-catch로 감싸져 있어 오류 발생 시에도 안전
+ * - 기존 값이 있으면 덮어쓰지 않음
+ * - React가 없거나 internals가 없어도 실패하지 않음
+ *
+ * @example
+ * ```typescript
+ * // SSR HTML에 삽입
+ * const html = `
+ *   ${hydrationScripts}
+ *   ${REACT_INTERNALS_SHIM_SCRIPT}
+ *   ${routerScript}
+ * `;
+ * ```
+ */
+export const REACT_INTERNALS_SHIM_SCRIPT = `<script>
+// React 19 internals shim: ensure ReactSharedInternals.S exists before react-dom/client runs.
+// Some builds expect React.__CLIENT_INTERNALS... .S to be a function, but it may be null.
+// This shim is safe: it only fills the slot if missing.
+(function(){
+  try {
+    var React = window.React;
+    var i = React && React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+    if (i && i.S == null) {
+      i.S = function(){};
+    }
+  } catch(e) {}
+})();
+</script>`;