@mandujs/core 0.20.10 → 0.22.0

package/src/runtime/server.ts

@@ -2,9 +2,17 @@ import type { Server } from "bun";
 import type { RoutesManifest, RouteSpec, HydrationConfig } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling, RenderMode } from "../filling/filling";
-import { ManduContext, type CookieManager } from "../filling/context";
+import { ManduContext, CookieManager } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR, renderStreamingResponse } from "./ssr";
+import {
+  resolveMetadata,
+  renderMetadata,
+  renderTitle,
+  type Metadata,
+  type MetadataItem,
+  type GenerateMetadata,
+} from "../seo";
 import { type ErrorFallbackProps } from "./boundary";
 import React, { type ReactNode } from "react";
 import path from "path";
@@ -50,6 +58,9 @@ import { createFetchHandler } from "./handler";
 import { wrapBunWebSocket, type WSUpgradeData } from "../filling/ws";
 import { handleImageRequest } from "./image-handler";
 import { extractShellHtml, createPPRResponse } from "./ppr";
+import { isRedirectResponse } from "./redirect";
+import { isNotFoundResponse } from "./not-found";
+import { newId } from "../id";
 
 export interface RateLimitOptions {
   windowMs?: number;
@@ -390,6 +401,10 @@ export type ErrorLoader = () => Promise<{ default: ErrorComponent }>;
 export interface PageRegistration {
   component: React.ComponentType<{ params: Record<string, string>; loaderData?: unknown }>;
   filling?: ManduFilling<unknown>;
+  /** #186: page 모듈의 static `metadata` export (선택) */
+  metadata?: Metadata;
+  /** #186: page 모듈의 `generateMetadata` 함수 export (선택) */
+  generateMetadata?: GenerateMetadata;
 }
 
 /**
@@ -456,6 +471,13 @@ export class ServerRegistry {
   readonly errorLoaders: Map<string, ErrorLoader> = new Map();
   createAppFn: CreateAppFn | null = null;
   rateLimiter: MemoryRateLimiter | null = null;
+  /**
+   * Phase 6.3: app-level `not-found.tsx` handler. Returns the React
+   * component used for 404 rendering. Set via {@link registerNotFoundHandler}.
+   * Global — one per app, registered at startup. Unresolved → fall back
+   * to the framework's built-in 404 JSON error.
+   */
+  notFoundHandler: PageHandler | null = null;
   /** Kitchen dev dashboard handler (dev mode only) */
   kitchen: KitchenHandler | null = null;
   /** 라우트별 캐시 옵션 (filling.loader()의 cacheOptions에서 등록) */
@@ -466,6 +488,17 @@ export class ServerRegistry {
   readonly layoutSlotPaths: Map<string, string | null> = new Map();
   /** WebSocket 핸들러 (라우트 ID → WSHandlers) */
   readonly wsHandlers: Map<string, import("../filling/ws").WSHandlers> = new Map();
+  /**
+   * Metadata API 캐시 (#186)
+   * - pageMetadata: routeId → page 모듈의 static `metadata` export
+   * - pageGenerateMetadata: routeId → `generateMetadata` 함수
+   * - layoutMetadata: layout 모듈 경로 → static `metadata` export (null = 시도했지만 없음)
+   * - layoutGenerateMetadata: layout 모듈 경로 → `generateMetadata` 함수
+   */
+  readonly pageMetadata: Map<string, import("../seo").Metadata> = new Map();
+  readonly pageGenerateMetadata: Map<string, import("../seo").GenerateMetadata> = new Map();
+  readonly layoutMetadata: Map<string, import("../seo").Metadata | null> = new Map();
+  readonly layoutGenerateMetadata: Map<string, import("../seo").GenerateMetadata> = new Map();
   settings: ServerRegistrySettings = {
     isDev: false,
     rootDir: process.cwd(),
@@ -512,6 +545,16 @@ export class ServerRegistry {
     this.errorLoaders.set(modulePath, loader);
   }
 
+  /**
+   * Phase 6.3: register the app-level not-found handler. Follows the
+   * same factory shape as `registerPageHandler` (async component loader)
+   * so users can lazy-import their `app/not-found.tsx`. Only one handler
+   * is retained — later calls overwrite earlier ones.
+   */
+  registerNotFoundHandler(handler: PageHandler): void {
+    this.notFoundHandler = handler;
+  }
+
   /**
    * 제네릭 컴포넌트 로더 (DRY)
    * 캐시 → 로더 → 동적 import 순서로 시도
@@ -537,6 +580,22 @@ export class ServerRegistry {
     const cached = cacheMap.get(modulePath);
     if (cached) return cached;
 
+    // #186: layout인 경우 metadata / generateMetadata export를 함께 캐싱
+    const cacheLayoutMetadata = (mod: unknown) => {
+      if (type !== "layout") return;
+      if (this.layoutMetadata.has(modulePath)) return;
+      const modObj = (mod && typeof mod === "object" ? (mod as Record<string, unknown>) : null);
+      const staticMeta = modObj?.metadata;
+      const generateFn = modObj?.generateMetadata;
+      this.layoutMetadata.set(
+        modulePath,
+        staticMeta && typeof staticMeta === "object" ? (staticMeta as Metadata) : null,
+      );
+      if (typeof generateFn === "function") {
+        this.layoutGenerateMetadata.set(modulePath, generateFn as GenerateMetadata);
+      }
+    };
+
     // 2. 등록된 로더 시도
     const loader = loaderMap.get(modulePath);
     if (loader) {
@@ -544,6 +603,7 @@ export class ServerRegistry {
         const module = await loader();
         const component = module.default;
         cacheMap.set(modulePath, component);
+        cacheLayoutMetadata(module);
         return component;
       } catch (error) {
         console.error(`[Mandu] Failed to load ${type}: ${modulePath}`, error);
@@ -562,6 +622,7 @@ export class ServerRegistry {
       const module = await import(validation.value);
       const component = module.default;
       cacheMap.set(modulePath, component);
+      cacheLayoutMetadata(module);
       return component;
     } catch (error) {
       // layout은 에러 로깅, loading/error는 조용히 실패
@@ -611,8 +672,13 @@ export class ServerRegistry {
     this.loadingLoaders.clear();
     this.errorComponents.clear();
     this.errorLoaders.clear();
+    this.pageMetadata.clear();
+    this.pageGenerateMetadata.clear();
+    this.layoutMetadata.clear();
+    this.layoutGenerateMetadata.clear();
     this.createAppFn = null;
     this.rateLimiter = null;
+    this.notFoundHandler = null;
   }
 }
 
@@ -683,6 +749,15 @@ export function registerErrorLoader(modulePath: string, loader: ErrorLoader): vo
   defaultRegistry.registerErrorLoader(modulePath, loader);
 }
 
+/**
+ * Phase 6.3: register the app-level not-found handler on the default
+ * registry. Called once at app init (either by codegen or manually)
+ * with a PageHandler that resolves to the `not-found.tsx` component.
+ */
+export function registerNotFoundHandler(handler: PageHandler): void {
+  defaultRegistry.registerNotFoundHandler(handler);
+}
+
 export function registerWSHandler(routeId: string, handlers: import("../filling/ws").WSHandlers): void {
   defaultRegistry.wsHandlers.set(routeId, handlers);
 }
@@ -1120,7 +1195,7 @@ async function handleInternalCacheControlRequest(
 async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
   const requestStart = Date.now();
   // Phase 1-4: Correlation ID — 한 요청에서 발생하는 모든 이벤트를 추적
-  const correlationId = req.headers.get("x-mandu-request-id") ?? crypto.randomUUID();
+  const correlationId = req.headers.get("x-mandu-request-id") ?? newId();
   const result = await handleRequestInternal(req, router, registry);
 
   if (!result.ok) {
@@ -1212,11 +1287,99 @@ async function handleApiRoute(
 
 // ---------- Page Data Loader ----------
 
+/**
+ * Merge any pending Set-Cookie headers from ctx.cookies into the given
+ * Response. Used when a loader short-circuits via `redirect(...)` — session
+ * mutations made before the redirect call must still be emitted.
+ *
+ * CookieManager.applyToResponse already handles the no-op case (empty
+ * cookie set); we guard first anyway to avoid cloning the Response body
+ * unnecessarily (Response.redirect's body is always null, but keeping
+ * this cheap).
+ */
+function mergeCookiesIntoResponse(response: Response, cookies: CookieManager): Response {
+  if (!cookies.hasPendingCookies()) return response;
+  return cookies.applyToResponse(response);
+}
+
+/**
+ * Phase 6.3: derive a short opaque digest for an Error so dev and prod
+ * renders can both reference the same log entry. Not a security token —
+ * just a correlation aid. We hash `message + top stack frame` for a
+ * stable-ish 8-char hex that survives the same error thrown twice.
+ *
+ * Exported for unit testing. Not part of the public API.
+ */
+export function computeErrorDigest(error: Error): string {
+  const source = `${error.message ?? ""}::${(error.stack ?? "").split("\n")[1] ?? ""}`;
+  // FNV-1a 32-bit — cheap, no deps, deterministic. Avoids pulling crypto.
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < source.length; i++) {
+    hash ^= source.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Phase 6.3: redact an Error for the rendered error-boundary surface.
+ *
+ * In dev: pass-through — `error.tsx` sees the original Error unchanged.
+ * In prod: produce a clone with
+ *   - `.message` kept (users want a hint)
+ *   - `.stack` trimmed to the error header + the top 3 frames (enough
+ *     to tell "it's my code" vs "it's node_modules" without leaking the
+ *     whole call tree to the browser)
+ *   - the original `.name` preserved
+ *
+ * The returned value is always an Error (or subclass), so React rendering
+ * can treat it uniformly. A matching digest is computed and returned so
+ * the caller can pass it to the `digest` prop.
+ *
+ * Exported for unit testing. Not part of the public API.
+ */
+export function redactErrorForBoundary(error: Error, isDev: boolean): { error: Error; digest: string } {
+  const digest = computeErrorDigest(error);
+  if (isDev) {
+    return { error, digest };
+  }
+  const redacted = new Error(error.message);
+  redacted.name = error.name;
+  if (typeof error.stack === "string") {
+    const lines = error.stack.split("\n");
+    // Keep the header line (`Error: msg`) + up to 3 frames.
+    redacted.stack = lines.slice(0, 4).join("\n");
+  } else {
+    redacted.stack = undefined;
+  }
+  return { error: redacted, digest };
+}
+
 interface PageLoadResult {
   loaderData: unknown;
   cookies?: CookieManager;
   /** Layout별 loader 데이터 (모듈 경로 → 데이터) */
   layoutData?: Map<string, unknown>;
+  /**
+   * If the page's loader returned or threw a redirect Response, it surfaces
+   * here. Callers short-circuit SSR and emit this Response to the browser
+   * with any pending ctx.cookies merged in (session/CSRF must survive).
+   *
+   * NOTE: a bare `throw new Error(...)` does NOT set this — only Response
+   * instances with a redirect-range status + Location header. See
+   * `isRedirectResponse()` in runtime/redirect.ts.
+   */
+  redirect?: Response;
+  /**
+   * Phase 6.3: page loader returned/threw `notFound()`. When set, the
+   * caller renders `app/not-found.tsx` (if registered) or falls through
+   * to the built-in 404. The original Response carries the message body
+   * as plain text so it can be surfaced on the 404 page.
+   *
+   * NOTE: a bare `new Response(null, { status: 404 })` does NOT set this
+   * — only `notFound()` from `runtime/not-found.ts` (checked via brand).
+   */
+  notFound?: Response;
 }
 
 /**
@@ -1240,7 +1403,40 @@ async function loadPageData(
       // Filling의 loader 실행
       if (registration.filling?.hasLoader()) {
         const ctx = new ManduContext(req, params);
-        loaderData = await registration.filling.executeLoader(ctx);
+        // DX-3: loader may return OR throw a redirect Response. Both are
+        // short-circuits — if we detect one, skip SSR and hand the Response
+        // to the caller with pending cookies merged in.
+        // Phase 6.3: same semantics for notFound() — checked BEFORE redirect
+        // so a loader that does `throw notFound()` surfaces through the
+        // dedicated path rather than hitting the isRedirectResponse false
+        // positive (it won't — notFound has no Location — but being explicit
+        // prevents future regressions).
+        let returned: unknown;
+        try {
+          returned = await registration.filling.executeLoader(ctx);
+        } catch (thrown) {
+          if (isNotFoundResponse(thrown)) {
+            // Carry the pending cookies on the result so the renderer can
+            // merge them onto the rendered not-found page (which is a
+            // fresh Response — the nfResponse body isn't reused).
+            const nfCookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+            return ok({ loaderData: undefined, notFound: thrown, cookies: nfCookies });
+          }
+          if (isRedirectResponse(thrown)) {
+            const redirectResponse = mergeCookiesIntoResponse(thrown, ctx.cookies);
+            return ok({ loaderData: undefined, redirect: redirectResponse });
+          }
+          throw thrown;
+        }
+        if (isNotFoundResponse(returned)) {
+          const nfCookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+          return ok({ loaderData: undefined, notFound: returned, cookies: nfCookies });
+        }
+        if (isRedirectResponse(returned)) {
+          const redirectResponse = mergeCookiesIntoResponse(returned, ctx.cookies);
+          return ok({ loaderData: undefined, redirect: redirectResponse });
+        }
+        loaderData = returned;
         if (ctx.cookies.hasPendingCookies()) {
           cookies = ctx.cookies;
         }
@@ -1270,15 +1466,63 @@ async function loadPageData(
         : (exportedObj?.component ?? exported);
       registry.registerRouteComponent(route.id, component as RouteComponent);
 
+      // #186: page 모듈에서 metadata / generateMetadata export 캐싱
+      const modObj = module as Record<string, unknown>;
+      if (modObj.metadata && typeof modObj.metadata === "object") {
+        registry.pageMetadata.set(route.id, modObj.metadata as Metadata);
+      }
+      if (typeof modObj.generateMetadata === "function") {
+        registry.pageGenerateMetadata.set(
+          route.id,
+          modObj.generateMetadata as GenerateMetadata,
+        );
+      }
+
       // filling이 있으면 캐시 옵션 등록 + loader 실행
+      // Support both page-module shapes:
+      //   (a) `export default { component, filling }` — object default
+      //   (b) `export default function Page()` + `export const filling = …`
+      //       — function default with named filling export
+      // (b) is the more natural TS/React shape; without this fallback, filling
+      // silently does nothing and pages render without loader data.
       let cookies: CookieManager | undefined;
-      const filling = typeof exported === "object" && exported !== null ? (exportedObj as Record<string, unknown>)?.filling as ManduFilling | null : null;
+      const fillingFromDefault =
+        typeof exported === "object" && exported !== null
+          ? ((exportedObj as Record<string, unknown>)?.filling as ManduFilling | null | undefined)
+          : null;
+      const fillingFromNamed = modObj.filling as ManduFilling | null | undefined;
+      const filling: ManduFilling | null = fillingFromDefault ?? fillingFromNamed ?? null;
       if (filling?.getCacheOptions?.()) {
         registry.cacheOptions.set(route.id, filling.getCacheOptions()!);
       }
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
-        loaderData = await filling.executeLoader(ctx);
+        // DX-3 / Phase 6.3: same redirect + notFound handling as the
+        // PageHandler path above. notFound is checked first so both
+        // short-circuits remain symmetric.
+        let returned: unknown;
+        try {
+          returned = await filling.executeLoader(ctx);
+        } catch (thrown) {
+          if (isNotFoundResponse(thrown)) {
+            const nfCookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+            return ok({ loaderData: undefined, notFound: thrown, cookies: nfCookies });
+          }
+          if (isRedirectResponse(thrown)) {
+            const redirectResponse = mergeCookiesIntoResponse(thrown, ctx.cookies);
+            return ok({ loaderData: undefined, redirect: redirectResponse });
+          }
+          throw thrown;
+        }
+        if (isNotFoundResponse(returned)) {
+          const nfCookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+          return ok({ loaderData: undefined, notFound: returned, cookies: nfCookies });
+        }
+        if (isRedirectResponse(returned)) {
+          const redirectResponse = mergeCookiesIntoResponse(returned, ctx.cookies);
+          return ok({ loaderData: undefined, redirect: redirectResponse });
+        }
+        loaderData = returned;
         if (ctx.cookies.hasPendingCookies()) {
           cookies = ctx.cookies;
         }
@@ -1299,18 +1543,71 @@ async function loadPageData(
   return ok({ loaderData });
 }
 
+interface LayoutLoadResult {
+  /** Layout별 loader 데이터 (모듈 경로 → 데이터) */
+  data: Map<string, unknown>;
+  /**
+   * Layout chain이 ctx.cookies.set(...) 으로 쌓은 pending 쿠키들.
+   * loader 여러 개가 쿠키를 쓰면 chain 순서대로 병합되어 단일 CookieManager가 됨
+   * (부모 layout → 자식 layout 방향으로 later-wins).
+   * 쓴 쿠키가 없으면 undefined.
+   *
+   * DX-2: 예전엔 layout slot의 ctx.cookies가 drop 됐음 — 이제 여기서 response로 전파된다.
+   */
+  cookies: CookieManager | undefined;
+}
+
+/**
+ * Layout + Page CookieManager 병합.
+ *
+ * 규칙 (DX-2):
+ * - layout 이 쓴 Set-Cookie 는 먼저, page 가 쓴 Set-Cookie 는 나중에 오도록 순서 고정.
+ * - HTTP 상 같은 이름의 Set-Cookie 가 여러 번 붙으면 브라우저는 뒤에 온 것(= page)을 최종 값으로 채택.
+ * - 이렇게 하면 middleware → handler 와 동일한 "뒤에 온 것이 이긴다" 관례를 유지.
+ *
+ * 구현은 raw-append 만 사용해서 한쪽 CookieManager 를 mutate 하지 않는다.
+ * (page 의 응답 API [ctx.json 등] 가 내부적으로 page 의 CookieManager 를 다시 쓸 수 있으므로
+ *  page CookieManager 를 mutate 해버리면 double-emit 위험이 생긴다.)
+ */
+function mergeCookieManagers(
+  req: Request,
+  layout: CookieManager | undefined,
+  page: CookieManager | undefined,
+): CookieManager | undefined {
+  if (!layout && !page) return undefined;
+  if (!layout) return page;
+  if (!page) return layout;
+
+  // 둘 다 있으면 빈 CookieManager 에 raw 로 layout → page 순서로 쌓는다.
+  const merged = new CookieManager(req);
+  for (const header of layout.getSetCookieHeaders()) {
+    merged.appendRawSetCookie(header);
+  }
+  for (const header of page.getSetCookieHeaders()) {
+    merged.appendRawSetCookie(header);
+  }
+  return merged;
+}
+
 /**
  * Layout chain의 모든 loader를 병렬 실행
  * 각 layout.slot.ts가 있으면 해당 데이터를 layout props로 전달
+ *
+ * Cookie 처리 (DX-2):
+ * - 각 layout slot은 개별 ManduContext 에서 실행되므로 각자의 CookieManager 를 가짐
+ * - 함수 리턴 전에 chain 순서대로 하나의 CookieManager 로 병합해 반환
+ * - 같은 이름의 쿠키를 여러 layout 이 set 하면 layout chain 후반부(= children 에 가까운 쪽)가 이김
  */
 async function loadLayoutData(
   req: Request,
   layoutChain: string[] | undefined,
   params: Record<string, string>,
   registry: ServerRegistry
-): Promise<Map<string, unknown>> {
+): Promise<LayoutLoadResult> {
   const layoutData = new Map<string, unknown>();
-  if (!layoutChain || layoutChain.length === 0) return layoutData;
+  if (!layoutChain || layoutChain.length === 0) {
+    return { data: layoutData, cookies: undefined };
+  }
 
   // layout.slot.ts 파일 검색: layout 모듈 경로에서 .slot.ts 파일 경로 유도
   // 예: app/layout.tsx → spec/slots/layout.slot.ts (auto-link 규칙)
@@ -1351,7 +1648,7 @@ async function loadLayoutData(
     }
   }
 
-  if (loaderEntries.length === 0) return layoutData;
+  if (loaderEntries.length === 0) return { data: layoutData, cookies: undefined };
 
   const results = await Promise.all(
     loaderEntries.map(async ({ modulePath, slotPath }) => {
@@ -1364,27 +1661,154 @@ async function loadLayoutData(
           if (filling.hasLoader()) {
             const ctx = new ManduContext(req, params);
             const data = await filling.executeLoader(ctx);
-            return { modulePath, data };
+            // DX-3: layout loaders are NOT allowed to redirect. They share
+            // the pipeline with a page loader and we can only honor one
+            // redirect — the page's wins (authoritative). If a layout
+            // returned a Response we log + discard it (keeping cookies
+            // the layout may have set). Users who want layout-level auth
+            // should put the redirect in the page's loader.
+            if (isRedirectResponse(data)) {
+              console.warn(
+                `[Mandu] Layout loader for ${modulePath} returned a redirect Response; ignoring. ` +
+                  `Put redirect() in a page loader instead — layout loaders cannot short-circuit rendering.`
+              );
+              const cookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+              return { modulePath, data: undefined, cookies };
+            }
+            const cookies = ctx.cookies.hasPendingCookies() ? ctx.cookies : undefined;
+            return { modulePath, data, cookies };
           }
         }
       } catch (error) {
-        console.warn(`[Mandu] Layout loader failed for ${modulePath}:`, error);
+        // A thrown redirect Response from a layout would land here —
+        // same rule: ignore, it's not the layout's decision to make.
+        if (isRedirectResponse(error)) {
+          console.warn(
+            `[Mandu] Layout loader for ${modulePath} threw a redirect Response; ignoring. ` +
+              `Put redirect() in a page loader instead.`
+          );
+        } else {
+          console.warn(`[Mandu] Layout loader failed for ${modulePath}:`, error);
+        }
       }
-      return { modulePath, data: undefined };
+      return { modulePath, data: undefined, cookies: undefined };
     })
   );
 
-  for (const { modulePath, data } of results) {
+  // chain 순서 유지: loaderEntries 순으로 결과를 순회
+  // (Promise.all 은 입력 순서대로 배열을 보존하므로 results 의 index 가 chain 순서와 일치)
+  //
+  // Layout chain 단일 쿠키 병합 전략 (DX-2):
+  // - 쿠키를 쓴 layout 이 하나라도 있으면 빈 CookieManager 를 만들고 chain 순서대로 raw-append
+  // - 같은 이름의 쿠키를 여러 layout 이 set 하면 chain 후반부(= children 에 가까운 쪽)가 뒤에 나오므로
+  //   브라우저 semantics 상 이김 (HTTP 상 마지막 Set-Cookie 가 최종 값)
+  // - 개별 loader 의 CookieManager 를 mutate 하지 않음 (test assertion 안전성 확보)
+  let mergedCookies: CookieManager | undefined;
+  for (const { modulePath, data, cookies } of results) {
     if (data !== undefined) {
       layoutData.set(modulePath, data);
     }
+    if (cookies) {
+      if (!mergedCookies) {
+        mergedCookies = new CookieManager(req);
+      }
+      for (const rawSetCookie of cookies.getSetCookieHeaders()) {
+        mergedCookies.appendRawSetCookie(rawSetCookie);
+      }
+    }
   }
 
-  return layoutData;
+  return { data: layoutData, cookies: mergedCookies };
 }
 
 // ---------- SSR Renderer ----------
 
+/**
+ * #186: URL에서 searchParams를 Record<string, string>로 추출 (SEO 모듈 시그니처)
+ */
+function extractSearchParams(url: string): Record<string, string> {
+  try {
+    const u = new URL(url);
+    const result: Record<string, string> = {};
+    for (const [key, value] of u.searchParams.entries()) {
+      if (!(key in result)) result[key] = value;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * #186: layout chain + page metadata를 순서대로 수집해 MetadataItem[] 구성
+ * - 각 layout의 generateMetadata 우선, 없으면 static metadata
+ * - page 모듈의 generateMetadata 우선, 없으면 static metadata
+ * - 결과 배열을 SEO 모듈의 resolveMetadata에 전달
+ */
+async function collectMetadataItems(
+  route: { id: string; layoutChain?: string[] },
+  registry: ServerRegistry,
+): Promise<MetadataItem[]> {
+  const items: MetadataItem[] = [];
+
+  if (route.layoutChain) {
+    for (const layoutPath of route.layoutChain) {
+      // Layout 모듈 로드 → metadata / generateMetadata 캐시 채움
+      await registry.getLayoutComponent(layoutPath);
+      const dyn = registry.layoutGenerateMetadata.get(layoutPath);
+      if (dyn) {
+        items.push(dyn);
+        continue;
+      }
+      const staticMeta = registry.layoutMetadata.get(layoutPath);
+      if (staticMeta) items.push(staticMeta);
+    }
+  }
+
+  const pageDyn = registry.pageGenerateMetadata.get(route.id);
+  if (pageDyn) {
+    items.push(pageDyn);
+  } else {
+    const pageStatic = registry.pageMetadata.get(route.id);
+    if (pageStatic) items.push(pageStatic);
+  }
+
+  return items;
+}
+
+/**
+ * #186: 해석된 Metadata를 SSR 옵션(title + headTags)으로 변환
+ */
+async function buildSSRMetadata(
+  route: { id: string; layoutChain?: string[] },
+  params: Record<string, string>,
+  url: string,
+  registry: ServerRegistry,
+): Promise<{ title: string; headTags: string }> {
+  try {
+    const items = await collectMetadataItems(route, registry);
+    if (items.length === 0) {
+      return { title: "Mandu App", headTags: "" };
+    }
+    const resolved = await resolveMetadata(items, params, extractSearchParams(url));
+    const titleHtml = renderTitle(resolved);
+    const headTags = renderMetadata(resolved);
+    // resolveMetadata는 <title>을 headTags 안에 이미 포함시키므로,
+    // 중복 방지를 위해 title은 문자열만 뽑고 headTags에서 <title>을 제거
+    const title = extractTitleText(titleHtml) ?? "Mandu App";
+    const headWithoutTitle = headTags.replace(/<title>[^<]*<\/title>\n?/i, "");
+    return { title, headTags: headWithoutTitle };
+  } catch (error) {
+    console.warn("[Mandu] metadata resolution failed:", error);
+    return { title: "Mandu App", headTags: "" };
+  }
+}
+
+function extractTitleText(titleHtml: string): string | null {
+  const match = /<title>([^<]*)<\/title>/i.exec(titleHtml);
+  return match ? match[1] : null;
+}
+
 /**
  * SSR 렌더링 (Streaming/Non-streaming)
  */
@@ -1437,6 +1861,9 @@ async function renderPageSSR(
       ? { [route.id]: { serverData: loaderData } }
       : undefined;
 
+    // #186: layout chain + page metadata 병합
+    const builtMeta = await buildSSRMetadata(route, params, url, registry);
+
     // Streaming SSR 모드 결정
     const useStreaming = route.streaming !== undefined
       ? route.streaming
@@ -1444,7 +1871,8 @@ async function renderPageSSR(
 
     if (useStreaming) {
       const streamingResponse = await renderStreamingResponse(app, {
-        title: `${route.id} - Mandu`,
+        title: builtMeta.title,
+        headTags: builtMeta.headTags,
         isDev: settings.isDev,
         hmrPort: settings.hmrPort,
         routeId: route.id,
@@ -1477,7 +1905,8 @@ async function renderPageSSR(
     // renderToHTML에서 중복 래핑하지 않도록 hydration을 전달하되 strategy를 "none"으로 설정
     // 단, hydration 스크립트(importmap, runtime 등)는 여전히 필요하므로 bundleManifest는 유지
     const ssrResponse = renderSSR(app, {
-      title: `${route.id} - Mandu`,
+      title: builtMeta.title,
+      headTags: builtMeta.headTags,
       isDev: settings.isDev,
       hmrPort: settings.hmrPort,
       routeId: route.id,
@@ -1499,10 +1928,18 @@ async function renderPageSSR(
         const errorMod = await import(path.join(settings.rootDir, route.errorModule));
         const ErrorComponent = errorMod.default as React.ComponentType<ErrorFallbackProps>;
         if (ErrorComponent) {
+          // Phase 6.3: redact stack in prod, keep full fidelity in dev.
+          // Full error is always logged below; only the client-visible
+          // `error` prop is trimmed.
+          const { error: boundaryError, digest } = redactErrorForBoundary(
+            renderError,
+            settings.isDev,
+          );
           const errorElement = React.createElement(ErrorComponent, {
-            error: renderError,
+            error: boundaryError,
             errorInfo: undefined,
             resetError: () => {}, // SSR에서는 noop — 클라이언트 hydration 시 실제 동작
+            digest,
           });
 
           // 레이아웃은 유지하면서 에러 컴포넌트만 교체
@@ -1512,7 +1949,8 @@ async function renderPageSSR(
           }
 
           const errorHtml = renderSSR(errorApp, {
-            title: `Error - ${route.id}`,
+            // 에러 상태에서는 resolveMetadata 결과를 신뢰할 수 없을 수 있으므로 리터럴 사용
+            title: "Mandu App — Error",
             isDev: settings.isDev,
             cssPath: settings.cssPath,
           });
@@ -1533,6 +1971,102 @@ async function renderPageSSR(
   }
 }
 
+// ---------- Not Found Renderer (Phase 6.3) ----------
+
+/**
+ * Read the plain-text message body out of a notFound() Response without
+ * consuming it. Returns a short default if the body is empty or reading
+ * fails (e.g. body already read — shouldn't happen but defensive).
+ */
+async function readNotFoundMessage(response: Response): Promise<string> {
+  try {
+    const clone = response.clone();
+    const body = await clone.text();
+    return body.length > 0 ? body : "Not Found";
+  } catch {
+    return "Not Found";
+  }
+}
+
+/**
+ * Render `app/not-found.tsx` (if registered) as a status-404 page, or
+ * fall back to the framework's JSON 404 error. Cookies set by the page
+ * loader and any layout loaders are preserved on the final Response.
+ *
+ * Infinite-loop guard: if rendering the not-found component itself
+ * throws (bad user code), we don't recurse back into this function —
+ * we emit the built-in 404 instead. That way a broken not-found.tsx
+ * never causes a stack overflow or tarpit loop.
+ */
+async function renderNotFoundPage(
+  req: Request,
+  route: { id: string; pattern: string; layoutChain?: string[]; hydration?: HydrationConfig; streaming?: boolean },
+  params: Record<string, string>,
+  registry: ServerRegistry,
+  pageCookies: CookieManager | undefined,
+  layoutCookies: CookieManager | undefined,
+  layoutData: Map<string, unknown> | undefined,
+  notFoundResponse: Response,
+): Promise<Response> {
+  const settings = registry.settings;
+  const mergedCookies = mergeCookieManagers(req, layoutCookies, pageCookies);
+  const message = await readNotFoundMessage(notFoundResponse);
+
+  const handler = registry.notFoundHandler;
+  if (!handler) {
+    // No app/not-found.tsx registered — return the existing 404 path.
+    return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev);
+  }
+
+  try {
+    const registration = await handler();
+    const NotFoundComponent = registration.component;
+
+    // Let the not-found page's own loader contribute data (e.g. nav links,
+    // locale strings). The page loader has already run — this is the 2nd
+    // loader invocation, scoped to the 404 surface only.
+    let loaderData: unknown = { message };
+    if (registration.filling?.hasLoader()) {
+      const ctx = new ManduContext(req, params);
+      try {
+        const returned = await registration.filling.executeLoader(ctx);
+        loaderData = returned !== undefined ? returned : { message };
+      } catch (loaderError) {
+        console.warn(`[Mandu] not-found.tsx loader threw, falling back to { message }:`, loaderError);
+        loaderData = { message };
+      }
+    }
+
+    // Render the component. Reuse renderSSR directly (no cache, no
+    // streaming, no island bundling — a 404 page is plain).
+    let app: React.ReactElement = React.createElement(NotFoundComponent, {
+      params,
+      loaderData,
+    });
+    if (route.layoutChain && route.layoutChain.length > 0) {
+      app = await wrapWithLayouts(app, route.layoutChain, registry, params, layoutData);
+    }
+
+    const html = renderSSR(app, {
+      title: "Not Found",
+      isDev: settings.isDev,
+      cssPath: settings.cssPath,
+    });
+
+    // renderSSR returns a 200; override to 404 without losing headers.
+    const headers = new Headers(html.headers);
+    const body = await html.text();
+    let response = new Response(body, { status: 404, headers });
+    if (mergedCookies) {
+      response = mergedCookies.applyToResponse(response);
+    }
+    return response;
+  } catch (renderError) {
+    console.error(`[Mandu] app/not-found.tsx render failed; falling back to built-in 404:`, renderError);
+    return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev);
+  }
+}
+
 // ---------- Page Route Handler ----------
 
 /** SWR 백그라운드 재생성 중복 방지 */
@@ -1569,6 +2103,12 @@ async function handlePageRoute(
       // Shell HIT: load only the dynamic data (cheap), skip full SSR render
       const loadResult = await loadPageData(req, route, params, registry);
       if (!loadResult.ok) return loadResult;
+      // DX-3: loader-level redirect wins over the PPR shell — never emit
+      // cached HTML to a user the loader wants to redirect away. Cookies
+      // were already merged into the redirect Response inside loadPageData.
+      if (loadResult.value.redirect) {
+        return ok(loadResult.value.redirect);
+      }
       const { loaderData, cookies } = loadResult.value;
       const pprResponse = createPPRResponse(cachedShell.html, route.id, loaderData);
       return ok(cookies ? cookies.applyToResponse(pprResponse) : pprResponse);
@@ -1606,7 +2146,7 @@ async function handlePageRoute(
   }
 
   // 1. 페이지 + 레이아웃 데이터 병렬 로딩
-  const [loadResult, layoutData] = await Promise.all([
+  const [loadResult, layoutLoad] = await Promise.all([
     loadPageData(req, route, params, registry),
     loadLayoutData(req, route.layoutChain, params, registry),
   ]);
@@ -1614,11 +2154,66 @@ async function handlePageRoute(
     return loadResult;
   }
 
-  const { loaderData, cookies } = loadResult.value;
+  const { loaderData, cookies: pageCookies } = loadResult.value;
+  const { data: layoutData, cookies: layoutCookies } = layoutLoad;
+
+  // DX-3: page loader redirect short-circuit. Applied BEFORE cookie merging
+  // and BEFORE the SPA _data branch so the redirect is authoritative — a
+  // client-side fetch('/page?_data=1') from the router must still see the
+  // redirect so it follows the server's decision instead of rendering the
+  // page shell. Layout loaders never redirect in this release (nested:
+  // test #7) — only the page's decision wins.
+  //
+  // Cookies already merged in loadPageData include page-level cookies set
+  // before the redirect call. Layout-level cookies also merge in so a
+  // layout that started a session survives the page's redirect.
+  if (loadResult.value.redirect) {
+    let redirectResponse = loadResult.value.redirect;
+    if (layoutCookies) {
+      redirectResponse = layoutCookies.applyToResponse(redirectResponse);
+    }
+    return ok(redirectResponse);
+  }
+
+  // Phase 6.3: notFound short-circuit. Same ordering rationale as redirect —
+  // never serve cached HTML to a user whose loader emitted notFound(), never
+  // leak loader JSON via the ?_data=1 path. If `app/not-found.tsx` is
+  // registered we render it here (status 404) with cookies preserved;
+  // otherwise we fall back to the built-in 404.
+  if (loadResult.value.notFound) {
+    const nfResponse = await renderNotFoundPage(
+      req,
+      route,
+      params,
+      registry,
+      pageCookies,
+      layoutCookies,
+      layoutData,
+      loadResult.value.notFound,
+    );
+    return ok(nfResponse);
+  }
+
+  // DX-2: layout slot 의 쿠키를 response 로 전파.
+  // 병합 순서: layout 먼저, page 가 뒤 — 같은 이름이면 page 가 이긴다 (middleware→handler 관례).
+  const mergedCookies = mergeCookieManagers(req, layoutCookies, pageCookies);
 
   // 2. Client-side Routing: 데이터만 반환 (JSON)
   // 참고: layoutData는 SSR 시에만 사용 — SPA 네비게이션은 전체 페이지 SSR을 받지 않으므로 제외
   if (isDataRequest) {
+    // Phase 7.2 — HDR (Hot Data Revalidation) signal. When the client
+    // sends `X-Mandu-HDR: 1` it is a slot-refetch in dev mode. We echo
+    // the header back so observability tooling can distinguish HDR
+    // refetches from normal SPA navigations. The JSON body is
+    // identical — HDR reuses the existing `_data=1` contract — so
+    // this header is purely advisory.
+    //
+    // Phase 7.3 L-04: only echo the header in dev. HDR is a dev-time
+    // feature (slot file watching + client HMR script) so no legitimate
+    // production client should ever send `X-Mandu-HDR: 1`. Echoing it
+    // in prod is zero-value attack surface (request-triggered response
+    // header reflection). Silently ignore the request header instead.
+    const isHDR = settings.isDev && req.headers.get("x-mandu-hdr") === "1";
     const jsonResponse = Response.json({
       routeId: route.id,
       pattern: route.pattern,
@@ -1626,11 +2221,22 @@ async function handlePageRoute(
       loaderData: loaderData ?? null,
       timestamp: Date.now(),
     });
-    return ok(cookies ? cookies.applyToResponse(jsonResponse) : jsonResponse);
+    if (isHDR) {
+      // Set headers on the response. Response.json() returns an
+      // immutable Response; we wrap with a new Headers object.
+      const headers = new Headers(jsonResponse.headers);
+      headers.set("X-Mandu-HDR", "1");
+      const taggedResponse = new Response(jsonResponse.body, {
+        status: jsonResponse.status,
+        headers,
+      });
+      return ok(mergedCookies ? mergedCookies.applyToResponse(taggedResponse) : taggedResponse);
+    }
+    return ok(mergedCookies ? mergedCookies.applyToResponse(jsonResponse) : jsonResponse);
   }
 
   // 3. SSR 렌더링 (layoutData 전달)
-  const ssrResult = await renderPageSSR(route, params, loaderData, req.url, registry, cookies, layoutData);
+  const ssrResult = await renderPageSSR(route, params, loaderData, req.url, registry, mergedCookies, layoutData);
 
   // 4a. PPR: cache only the shell (HTML structure minus loader data), not the full page
   if (cache && ssrResult.ok && renderMode === "ppr") {
@@ -1678,13 +2284,19 @@ async function regenerateCache(
   cache: CacheStore,
   cacheKey: string
 ): Promise<void> {
-  const [loadResult, layoutData] = await Promise.all([
+  const [loadResult, layoutLoad] = await Promise.all([
     loadPageData(req, route, params, registry),
     loadLayoutData(req, route.layoutChain, params, registry),
   ]);
   if (!loadResult.ok) return;
+  // DX-3: never cache a redirect under a page-html cache key. A redirect
+  // is per-request (auth state dependent) — caching it would poison every
+  // subsequent visitor. Bail out and let the next request re-evaluate.
+  if (loadResult.value.redirect) return;
 
   const { loaderData } = loadResult.value;
+  const { data: layoutData } = layoutLoad;
+  // 캐시 재생성 경로는 per-request 쿠키를 캐시해선 안 됨 → cookies undefined 로 유지.
   const ssrResult = await renderPageSSR(route, params, loaderData, req.url, registry, undefined, layoutData);
   if (!ssrResult.ok) return;
 
@@ -1752,6 +2364,15 @@ async function ensurePageRouteMetadata(
     registry.renderModes.set(routeId, registration.filling.getRenderMode());
   }
 
+  // #186: pageHandlers 경로에서도 metadata / generateMetadata 캐싱
+  // (pageLoaders 경로는 loadPageData에서 이미 처리됨)
+  if (registration.metadata && typeof registration.metadata === "object") {
+    registry.pageMetadata.set(routeId, registration.metadata);
+  }
+  if (typeof registration.generateMetadata === "function") {
+    registry.pageGenerateMetadata.set(routeId, registration.generateMetadata);
+  }
+
   return registration;
 }
 
@@ -1825,6 +2446,41 @@ async function handleRequestInternal(
   // 3. 라우트 매칭
   const match = router.match(pathname);
   if (!match) {
+    // Phase 6.3: unmatched URL → try `app/not-found.tsx` first. We
+    // can't reuse renderNotFoundPage directly (no route/params/layoutChain
+    // context here), so inline a minimal render path. The component and
+    // its loader are invoked with empty params + a pseudo route id so
+    // layouts that rely on routeId don't crash. If rendering fails OR no
+    // handler is registered, fall through to the built-in error path.
+    if (registry.notFoundHandler) {
+      try {
+        const registration = await registry.notFoundHandler();
+        let loaderData: unknown = { message: "Not Found" };
+        if (registration.filling?.hasLoader()) {
+          const ctx = new ManduContext(req, {});
+          try {
+            const returned = await registration.filling.executeLoader(ctx);
+            loaderData = returned !== undefined ? returned : { message: "Not Found" };
+          } catch (loaderError) {
+            console.warn(`[Mandu] not-found.tsx loader threw (unmatched URL):`, loaderError);
+          }
+        }
+        const app = React.createElement(registration.component, {
+          params: {},
+          loaderData,
+        });
+        const html = renderSSR(app, {
+          title: "Not Found",
+          isDev: settings.isDev,
+          cssPath: settings.cssPath,
+        });
+        const headers = new Headers(html.headers);
+        const body = await html.text();
+        return ok(new Response(body, { status: 404, headers }));
+      } catch (renderError) {
+        console.error(`[Mandu] app/not-found.tsx render failed for unmatched URL; falling back to built-in 404:`, renderError);
+      }
+    }
     return err(createNotFoundResponse(pathname));
   }
 
@@ -2045,7 +2701,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
           const match = router.match(url.pathname);
           if (match && registry.wsHandlers.has(match.route.id)) {
             const upgraded = (bunServer as any).upgrade(req, {
-              data: { routeId: match.route.id, params: match.params, id: crypto.randomUUID() },
+              data: { routeId: match.route.id, params: match.params, id: newId() },
             });
             return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
           }