@mandujs/core 0.54.21 → 0.54.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.21",
+  "version": "0.54.23",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/router.ts

@@ -165,42 +165,42 @@ const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN
 // because `registerCacheSize` replaces any prior reporter under the same key.
 registerCacheSize("patternCache", () => patternCache.size);
 
-/**
- * 패턴을 정규식으로 컴파일
- */
-function compilePattern(pattern: string): CompiledPattern {
-  const cached = patternCache.get(pattern);
-  if (cached) return cached;
-
-  const paramNames: string[] = [];
-  const normalized = pattern === "/" ? "/" : pattern.replace(/\/+$/, "") || "/";
-  const segments = normalized.split("/").filter(Boolean);
-
-  const regexStr = segments.length === 0
-    ? "/"
-    : segments.map((segment) => {
-        if (segment === "*") {
-          return "/.+";
-        }
-
-        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\*(\?)?$/);
-        if (wildcardMatch) {
-          paramNames.push(wildcardMatch[1]);
-          return wildcardMatch[2] === "?" ? "(?:/(.*))?" : "/(.+)";
-        }
-
-        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
-        if (paramMatch) {
-          paramNames.push(paramMatch[1]);
-          return "/([^/]+)";
-        }
-
-        return `/${escapePatternSegment(segment)}`;
-      }).join("");
-
-  const compiled = {
-    regex: new RegExp(`^${regexStr}$`),
-    paramNames,
+/**
+ * 패턴을 정규식으로 컴파일
+ */
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  const paramNames: string[] = [];
+  const normalized = pattern === "/" ? "/" : pattern.replace(/\/+$/, "") || "/";
+  const segments = normalized.split("/").filter(Boolean);
+
+  const regexStr = segments.length === 0
+    ? "/"
+    : segments.map((segment) => {
+        if (segment === "*") {
+          return "/.+";
+        }
+
+        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\*(\?)?$/);
+        if (wildcardMatch) {
+          paramNames.push(wildcardMatch[1]);
+          return wildcardMatch[2] === "?" ? "(?:/(.*))?" : "/(.+)";
+        }
+
+        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
+        if (paramMatch) {
+          paramNames.push(paramMatch[1]);
+          return "/([^/]+)";
+        }
+
+        return `/${escapePatternSegment(segment)}`;
+      }).join("");
+
+  const compiled = {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
   };
 
   patternCache.set(pattern, compiled);
@@ -219,17 +219,17 @@ function extractParamsFromPath(
 
   if (!match) return {};
 
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    params[name] = match[index + 1] ?? "";
-  });
-
-  return params;
-}
-
-function escapePatternSegment(segment: string): string {
-  return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+  const params: Record<string, string> = {};
+  compiled.paramNames.forEach((name, index) => {
+    params[name] = match[index + 1] ?? "";
+  });
+
+  return params;
+}
+
+function escapePatternSegment(segment: string): string {
+  return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 // ========== Navigation ==========
 
@@ -324,6 +324,16 @@ export async function navigate(
     // json 파싱 사이에 새 네비게이션이 시작됐을 수 있음
     if (controller.signal.aborted) return;
 
+    // #316: server-only target (no client-renderable route component). A
+    // client-side state update would change the URL but not the content
+    // ("click does nothing / goes back"). Fall back to a full document
+    // navigation so the server SSRs the page. `=== false` is intentional:
+    // older servers omit the flag, and we must not regress those.
+    if (data.clientRenderable === false) {
+      window.location.href = url.href;
+      return;
+    }
+
     // 상태 + History + 스크롤을 한 번에 적용하는 함수
     const applyUpdate = () => {
       const historyState = { routeId: data.routeId, params: data.params };

package/src/error/result.ts

@@ -52,9 +52,55 @@ export function statusFromError(error: ManduError): number {
 
 /**
  * 에러를 Response로 변환
+ *
+ * Content negotiation: for the built-in 404 not-found response, inspect the
+ * request's `Accept` header. Browser navigation (Accept includes `text/html`)
+ * gets a minimal HTML 404 page instead of raw JSON; API/fetch clients keep
+ * the JSON error envelope. A custom `app/not-found.tsx` is handled upstream
+ * and never reaches this fallback. See GitHub issue #320.
  */
-export function errorToResponse(error: ManduError, isDev: boolean): Response {
+export function errorToResponse(error: ManduError, isDev: boolean, req?: Request): Response {
+  const status = statusFromError(error);
+
+  if (status === 404 && req && acceptsHtml(req)) {
+    return new Response(renderNotFoundHtml(error.message), {
+      status,
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  }
+
   return Response.json(formatErrorResponse(error, { isDev }), {
-    status: statusFromError(error),
+    status,
   });
 }
+
+/** Whether the request's `Accept` header opts into an HTML response. */
+function acceptsHtml(req: Request): boolean {
+  const accept = req.headers.get("accept") ?? "";
+  return accept.includes("text/html");
+}
+
+/** Escape a string for safe interpolation into HTML text content. */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** Minimal built-in 404 HTML document for browser navigation. */
+function renderNotFoundHtml(message: string): string {
+  const safe = escapeHtml(message);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>404 - Not Found</title>
+</head>
+<body>
+<h1>404 - Not Found</h1>
+<p>${safe}</p>
+</body>
+</html>`;
+}

package/src/filling/body-parse.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Regression tests for issue #318:
+ * ctx.body() must raise a 400 (Bad Request) for empty/malformed JSON bodies,
+ * never a 500 FRAMEWORK_BUG / MANDU_F999 (a bad body is the client's fault).
+ */
+
+import { describe, it, expect } from "bun:test";
+import { ManduFillingFactory } from "./filling";
+import { BadRequestError } from "./context";
+
+const Mandu = ManduFillingFactory;
+
+function jsonPost(body: string): Request {
+  return new Request("http://localhost/api/auth/login", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body,
+  });
+}
+
+describe("ctx.body() bad request handling (#318)", () => {
+  const filling = Mandu.filling().post(async (ctx) => {
+    const data = await ctx.body();
+    return ctx.ok(data);
+  });
+
+  it("returns 400 (not 500) for an empty JSON body", async () => {
+    const res = await filling.handle(jsonPost(""));
+    expect(res.status).toBe(400);
+
+    const payload = (await res.json()) as Record<string, unknown>;
+    expect(payload.errorType).not.toBe("FRAMEWORK_BUG");
+    expect(payload.code).not.toBe("MANDU_F999");
+    expect(payload.code).toBe("MANDU_C400");
+  });
+
+  it("returns 400 (not 500) for a malformed JSON body", async () => {
+    const res = await filling.handle(jsonPost("{bad,,"));
+    expect(res.status).toBe(400);
+
+    const payload = (await res.json()) as Record<string, unknown>;
+    expect(payload.errorType).not.toBe("FRAMEWORK_BUG");
+    expect(payload.errorType).not.toBe("LOGIC_ERROR");
+    expect(payload.code).toBe("MANDU_C400");
+    // Must not misdiagnose client input as a slot file problem.
+    expect(JSON.stringify(payload)).not.toContain("slot");
+  });
+
+  it("still parses a valid JSON body normally", async () => {
+    const res = await filling.handle(jsonPost(JSON.stringify({ email: "a@b.c" })));
+    expect(res.status).toBe(200);
+    const payload = (await res.json()) as Record<string, unknown>;
+    expect(payload.email).toBe("a@b.c");
+  });
+
+  it("ctx.body() throws BadRequestError directly on malformed JSON", async () => {
+    const ctx = Mandu.context(jsonPost("not json"));
+    await expect(ctx.body()).rejects.toBeInstanceOf(BadRequestError);
+  });
+});

package/src/filling/context.ts

@@ -549,7 +549,16 @@ export class ManduContext {
     let data: unknown;
 
     if (contentType.includes("application/json")) {
-      data = await this.request.json();
+      try {
+        data = await this.request.json();
+      } catch (cause) {
+        // Empty or malformed JSON body is a client error (400),
+        // not a framework bug (500). See issue #318.
+        throw new BadRequestError(
+          "Invalid or empty JSON request body",
+          cause
+        );
+      }
     } else if (contentType.includes("application/x-www-form-urlencoded")) {
       const formData = await this.request.formData();
       data = Object.fromEntries(formData.entries());
@@ -628,23 +637,23 @@ export class ManduContext {
     return this.withCookies(new Response(null, { status: 204 }));
   }
 
-  /** 400 Bad Request, or custom 4xx/5xx error with ctx.error(status, message). */
-  error(message: string, details?: unknown): Response;
-  error(status: number, message: string, details?: unknown): Response;
-  error(
-    statusOrMessage: number | string,
-    messageOrDetails?: string | unknown,
-    maybeDetails?: unknown
-  ): Response {
-    if (typeof statusOrMessage === "number") {
-      const status = Number.isInteger(statusOrMessage) && statusOrMessage >= 400 && statusOrMessage <= 599
-        ? statusOrMessage
-        : 400;
-      const message = typeof messageOrDetails === "string" ? messageOrDetails : "Error";
-      return this.json({ status: "error", message, details: maybeDetails }, status);
-    }
-    return this.json({ status: "error", message: statusOrMessage, details: messageOrDetails }, 400);
-  }
+  /** 400 Bad Request, or custom 4xx/5xx error with ctx.error(status, message). */
+  error(message: string, details?: unknown): Response;
+  error(status: number, message: string, details?: unknown): Response;
+  error(
+    statusOrMessage: number | string,
+    messageOrDetails?: string | unknown,
+    maybeDetails?: unknown
+  ): Response {
+    if (typeof statusOrMessage === "number") {
+      const status = Number.isInteger(statusOrMessage) && statusOrMessage >= 400 && statusOrMessage <= 599
+        ? statusOrMessage
+        : 400;
+      const message = typeof messageOrDetails === "string" ? messageOrDetails : "Error";
+      return this.json({ status: "error", message, details: maybeDetails }, status);
+    }
+    return this.json({ status: "error", message: statusOrMessage, details: messageOrDetails }, 400);
+  }
 
   /** 401 Unauthorized */
   unauthorized(message: string = "Unauthorized"): Response {
@@ -888,3 +897,19 @@ export class ValidationError extends Error {
     this.name = "ValidationError";
   }
 }
+
+/**
+ * Bad request error (400 Bad Request)
+ *
+ * Raised when client-supplied input cannot be processed, e.g. an empty or
+ * malformed JSON request body in {@link ManduContext.body}. This is the
+ * client's fault and must never be classified as a framework bug (500).
+ */
+export class BadRequestError extends Error {
+  readonly statusCode = 400;
+
+  constructor(message: string = "Bad request", cause?: unknown) {
+    super(message, { cause });
+    this.name = "BadRequestError";
+  }
+}

package/src/filling/filling.ts

@@ -5,7 +5,7 @@
  * DNA-002: 의존성 주입 패턴 지원
  */
 
-import { ManduContext, ValidationError } from "./context";
+import { ManduContext, ValidationError, BadRequestError } from "./context";
 import { AuthenticationError, AuthorizationError } from "./auth";
 import { type FillingDeps, globalDeps } from "./deps";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
@@ -595,9 +595,18 @@ export class ManduFilling<TLoaderData = unknown> {
       if (actionResult) return actionResult;
     }
 
-    const handler = this.config.handlers.get(method);
+    // RFC 7231 §4.3.2: HEAD is GET without a body. A route that only
+    // registers a GET handler must still serve HEAD — run GET, then strip
+    // the body while preserving status + headers. An explicit HEAD handler
+    // takes precedence when present.
+    const stripBody = method === "HEAD" && !this.config.handlers.has("HEAD");
+    const handler = this.config.handlers.get(method) ?? (stripBody ? this.config.handlers.get("GET") : undefined);
     if (!handler) {
-      return ctx.json({ status: "error", message: `Method ${method} not allowed`, allowed: Array.from(this.config.handlers.keys()) }, 405);
+      const allowed = Array.from(this.config.handlers.keys());
+      if (this.config.handlers.has("GET") && !allowed.includes("HEAD")) {
+        allowed.push("HEAD");
+      }
+      return ctx.json({ status: "error", message: `Method ${method} not allowed`, allowed }, 405);
     }
     const lifecycleWithDefaults = this.createLifecycleWithDefaults(routeContext);
     const runHandler = async () => {
@@ -615,7 +624,17 @@ export class ManduFilling<TLoaderData = unknown> {
       const composed = compose(chain);
       return composed(ctx);
     };
-    return executeLifecycle(lifecycleWithDefaults, ctx, runHandler, options);
+    const response = await executeLifecycle(lifecycleWithDefaults, ctx, runHandler, options);
+    if (stripBody) {
+      // Preserve status + headers (incl. Content-Type / Content-Length the
+      // GET handler set), drop the body. A null-body Response keeps headers.
+      return new Response(null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    }
+    return response;
   }
 
   /**
@@ -745,6 +764,9 @@ export class ManduFilling<TLoaderData = unknown> {
       if (error instanceof ValidationError) {
         return ctx.json({ errorType: "LOGIC_ERROR", code: ErrorCode.SLOT_VALIDATION_ERROR, message: "Validation failed", summary: "입력 검증 실패 - 요청 데이터 확인 필요", fix: { file: routeContext ? `spec/slots/${routeContext.routeId}.slot.ts` : "spec/slots/", suggestion: "요청 데이터가 스키마와 일치하는지 확인하세요" }, route: routeContext, errors: error.errors, timestamp: new Date().toISOString() }, 400);
       }
+      if (error instanceof BadRequestError) {
+        return ctx.json({ errorType: "CLIENT_ERROR", code: "MANDU_C400", message: error.message, summary: "잘못된 요청 본문 - 클라이언트 입력 확인 필요", route: routeContext, timestamp: new Date().toISOString() }, 400);
+      }
       const classifier = new ErrorClassifier(null, routeContext ? { id: routeContext.routeId, pattern: routeContext.pattern } : undefined);
       const manduError = classifier.classify(error);
       console.error(`[Mandu] ${manduError.errorType}:`, manduError.message);

package/src/filling/head-method.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Regression test for issue #319: a route that only registers a GET handler
+ * via `Mandu.filling().get(...)` must serve HEAD requests as a body-less GET
+ * (RFC 7231 §4.3.2) — returning the same status + headers with an empty body,
+ * not a 405 Method Not Allowed.
+ */
+import { describe, it, expect } from "bun:test";
+import { ManduFillingFactory } from "./filling";
+
+describe("Filling HEAD handling (#319)", () => {
+  it("serves HEAD via the GET handler with status + headers and an empty body", async () => {
+    const filling = ManduFillingFactory.filling().get((ctx) =>
+      ctx.json({ ok: true }),
+    );
+
+    const getRes = await filling.handle(
+      new Request("http://localhost/api/health", { method: "GET" }),
+    );
+    expect(getRes.status).toBe(200);
+
+    const headRes = await filling.handle(
+      new Request("http://localhost/api/health", { method: "HEAD" }),
+    );
+
+    expect(headRes.status).toBe(200);
+    expect(headRes.headers.get("content-type")).toBe(
+      getRes.headers.get("content-type"),
+    );
+    const headBody = await headRes.text();
+    expect(headBody).toBe("");
+  });
+
+  it("prefers an explicit HEAD handler when one is registered", async () => {
+    const filling = ManduFillingFactory.filling()
+      .get((ctx) => ctx.json({ ok: true }))
+      .head((ctx) => {
+        const res = ctx.json({ ignored: true });
+        res.headers.set("X-Explicit-Head", "1");
+        return res;
+      });
+
+    const headRes = await filling.handle(
+      new Request("http://localhost/api/health", { method: "HEAD" }),
+    );
+
+    expect(headRes.status).toBe(200);
+    expect(headRes.headers.get("X-Explicit-Head")).toBe("1");
+  });
+
+  it("still returns 405 for a method with no GET fallback", async () => {
+    const filling = ManduFillingFactory.filling().post((ctx) => ctx.json({ ok: true }));
+
+    const headRes = await filling.handle(
+      new Request("http://localhost/api/health", { method: "HEAD" }),
+    );
+
+    expect(headRes.status).toBe(405);
+  });
+
+  it("lists HEAD in the Allow set when GET is registered but the method is unsupported", async () => {
+    const filling = ManduFillingFactory.filling().get((ctx) => ctx.json({ ok: true }));
+
+    const putRes = await filling.handle(
+      new Request("http://localhost/api/health", { method: "PUT" }),
+    );
+
+    expect(putRes.status).toBe(405);
+    const body = (await putRes.json()) as { allowed: string[] };
+    expect(body.allowed).toContain("GET");
+    expect(body.allowed).toContain("HEAD");
+  });
+});

package/src/runtime/__tests__/not-found-content-negotiation.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Content negotiation for the built-in default 404 response (GitHub issue #320).
+ *
+ * The framework's fallback 404 (when no `app/not-found.tsx` is registered)
+ * must honor the request `Accept` header: browser navigation that accepts
+ * `text/html` gets a minimal HTML 404 page, while API/fetch clients keep the
+ * JSON error envelope. Both keep status 404.
+ *
+ * This exercises `errorToResponse(createNotFoundResponse(...))` — the single
+ * convergence point every built-in default 404 path routes through in
+ * runtime/server.ts.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { errorToResponse, createNotFoundResponse } from "../../error";
+
+function build404(accept?: string): Response {
+  const headers: Record<string, string> = {};
+  if (accept !== undefined) headers["Accept"] = accept;
+  const req = new Request("http://test/this-page-does-not-exist", { headers });
+  return errorToResponse(
+    createNotFoundResponse("/this-page-does-not-exist"),
+    false,
+    req,
+  );
+}
+
+describe("default 404 content negotiation (#320)", () => {
+  it("returns HTML 404 when Accept includes text/html (browser navigation)", async () => {
+    const res = build404("text/html,application/xhtml+xml");
+    expect(res.status).toBe(404);
+    expect(res.headers.get("Content-Type")).toContain("text/html");
+
+    const body = await res.text();
+    expect(body).toContain("<!DOCTYPE html>");
+    expect(body).toContain("404 - Not Found");
+    // Body must NOT be a JSON error envelope.
+    expect(body).not.toContain("MANDU_E105");
+  });
+
+  it("returns JSON 404 when Accept is application/json (API client)", async () => {
+    const res = build404("application/json");
+    expect(res.status).toBe(404);
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.code).toBe("MANDU_E105");
+    expect(body.message).toBe("Route not found: /this-page-does-not-exist");
+  });
+
+  it("returns JSON 404 when no Accept header is present (fetch default)", async () => {
+    const res = build404(undefined);
+    expect(res.status).toBe(404);
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.code).toBe("MANDU_E105");
+  });
+
+  it("falls back to JSON when no request is supplied (back-compat)", async () => {
+    const res = errorToResponse(createNotFoundResponse("/x"), false);
+    expect(res.status).toBe(404);
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+  });
+
+  it("escapes the message in the HTML body (no markup injection)", async () => {
+    const req = new Request("http://test/x", {
+      headers: { Accept: "text/html" },
+    });
+    const res = errorToResponse(
+      createNotFoundResponse("/<script>alert(1)</script>"),
+      false,
+      req,
+    );
+    const body = await res.text();
+    expect(body).not.toContain("<script>alert(1)</script>");
+    expect(body).toContain("&lt;script&gt;");
+  });
+});

package/src/runtime/handlers.ts

@@ -23,7 +23,7 @@ import {
   type PageRegistration,
 } from "./server";
 import { registerManifest } from "./registry";
-import { needsHydration, type RouteClientBoundary, type RoutesManifest } from "../spec/schema";
+import { needsHydration, type RouteClientBoundary, type RoutesManifest } from "../spec/schema";
 
 type RouteModule = Record<string, unknown>;
 
@@ -62,11 +62,20 @@ function hasHttpMethodHandlers(module: RouteModule): boolean {
 function createMethodDispatcher(module: RouteModule, routeId: string) {
   return async (req: Request, params: Record<string, string> = {}) => {
     const method = req.method.toUpperCase();
-    const handler = (isHttpMethod(method) ? module[method] : undefined) as
+    // RFC 7231 §4.3.2: HEAD is GET without a body. When no explicit HEAD
+    // export exists, dispatch to GET and strip the body — preserving the
+    // status + headers GET produced. An explicit HEAD export wins.
+    const stripBody = method === "HEAD" && typeof module.HEAD !== "function";
+    const lookup = stripBody ? "GET" : method;
+    const handler = (isHttpMethod(lookup) ? module[lookup] : undefined) as
       | ((request: Request, context?: { params: Record<string, string> }) => Response | Promise<Response>)
       | undefined;
 
     if (!handler) {
+      const allow = HTTP_METHODS.filter((m) => typeof module[m] === "function");
+      if (typeof module.GET === "function" && !allow.includes("HEAD")) {
+        allow.push("HEAD");
+      }
       return Response.json(
         {
           error: `Method ${method} not allowed for route ${routeId}`,
@@ -74,17 +83,25 @@ function createMethodDispatcher(module: RouteModule, routeId: string) {
         {
           status: 405,
           headers: {
-            Allow: HTTP_METHODS.filter((m) => typeof module[m] === "function").join(", "),
+            Allow: allow.join(", "),
           },
         }
       );
     }
 
-    return handler(req, { params });
+    const response = await handler(req, { params });
+    if (stripBody) {
+      return new Response(null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    }
+    return response;
   };
 }
 
-export interface RegisterHandlersOptions {
+export interface RegisterHandlersOptions {
   /**
    * Module import function (dev: importFresh, start: standard import).
    * The optional `opts.changedFile` is forwarded into Phase 7.0 B5's
@@ -92,17 +109,17 @@ export interface RegisterHandlersOptions {
    * module's import graph, `importFn` returns the cached bundle in ~0.1 ms
    * instead of re-running Bun.build.
    */
-  importFn: (
-    modulePath: string,
-    opts?: {
-      changedFile?: string;
-      clientBoundaryTransform?: {
-        routeId: string;
-        hydrate?: string;
-        boundaries?: RouteClientBoundary[];
-      };
-    },
-  ) => Promise<unknown>;
+  importFn: (
+    modulePath: string,
+    opts?: {
+      changedFile?: string;
+      clientBoundaryTransform?: {
+        routeId: string;
+        hydrate?: string;
+        boundaries?: RouteClientBoundary[];
+      };
+    },
+  ) => Promise<unknown>;
   /** Set for tracking already registered layout paths */
   registeredLayouts: Set<string>;
   /** Clear layout cache on reload */
@@ -125,23 +142,23 @@ export async function registerManifestHandlers(
   rootDir: string,
   options: RegisterHandlersOptions
 ): Promise<void> {
-  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
-  const baseImportOpts: { changedFile?: string } | undefined =
-    changedFile !== undefined ? { changedFile } : undefined;
-  const importOptsForRoute = (route?: RoutesManifest["routes"][number]) => {
-    const boundaryTransform = route?.kind === "page" && route.boundaries?.length
-        ? {
-            routeId: route.id,
-            hydrate: route.hydration?.priority ?? "visible",
-            boundaries: route.boundaries,
-          }
-      : undefined;
-    if (!baseImportOpts && !boundaryTransform) return undefined;
-    return {
-      ...baseImportOpts,
-      ...(boundaryTransform ? { clientBoundaryTransform: boundaryTransform } : {}),
-    };
-  };
+  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
+  const baseImportOpts: { changedFile?: string } | undefined =
+    changedFile !== undefined ? { changedFile } : undefined;
+  const importOptsForRoute = (route?: RoutesManifest["routes"][number]) => {
+    const boundaryTransform = route?.kind === "page" && route.boundaries?.length
+        ? {
+            routeId: route.id,
+            hydrate: route.hydration?.priority ?? "visible",
+            boundaries: route.boundaries,
+          }
+      : undefined;
+    if (!baseImportOpts && !boundaryTransform) return undefined;
+    return {
+      ...baseImportOpts,
+      ...(boundaryTransform ? { clientBoundaryTransform: boundaryTransform } : {}),
+    };
+  };
 
   if (isReload) {
     registeredLayouts.clear();
@@ -158,19 +175,19 @@ export async function registerManifestHandlers(
     // runtime dispatcher invokes the default export on each request
     // so HMR reloads pick up edits automatically (same pattern as
     // API routes below).
-    if (route.kind === "metadata") {
-      const modulePath = path.resolve(rootDir, route.module);
-      registerMetadataHandler(route.id, async () => {
-        return importFn(modulePath, importOptsForRoute(route));
-      });
-      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
-      continue;
+    if (route.kind === "metadata") {
+      const modulePath = path.resolve(rootDir, route.module);
+      registerMetadataHandler(route.id, async () => {
+        return importFn(modulePath, importOptsForRoute(route));
+      });
+      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
+      continue;
     }
 
-    if (route.kind === "api") {
-      const modulePath = path.resolve(rootDir, route.module);
-      try {
-        const module = (await importFn(modulePath, importOptsForRoute(route))) as RouteModule;
+    if (route.kind === "api") {
+      const modulePath = path.resolve(rootDir, route.module);
+      try {
+        const module = (await importFn(modulePath, importOptsForRoute(route))) as RouteModule;
         let handler: unknown = module.default ?? module.handler ?? module;
 
         // 1) ManduFilling instance
@@ -217,7 +234,7 @@ export async function registerManifestHandlers(
               // Layout modules must export a default component. Runtime
               // validation in `renderToHTML` / page-loader asserts this —
               // so casting the unknown `importFn` result is safe here.
-              return importFn(absLayoutPath, baseImportOpts);
+              return importFn(absLayoutPath, baseImportOpts);
             }) as Parameters<typeof registerLayoutLoader>[1]);
             registeredLayouts.add(layoutPath);
             console.log(`  🎨 Layout: ${layoutPath}`);
@@ -228,7 +245,7 @@ export async function registerManifestHandlers(
       // Use PageHandler if slotModule exists (filling.loader support)
       if (route.slotModule) {
         registerPageHandler(route.id, async () => {
-          const mod = (await importFn(componentPath, importOptsForRoute(route))) as Record<string, unknown>;
+          const mod = (await importFn(componentPath, importOptsForRoute(route))) as Record<string, unknown>;
           // Normalize the page module shape. Users write pages in two styles:
           //   (a) `export default function Page() {…}` + `export const filling = …`
           //   (b) `export default { component: …, filling: … }`
@@ -266,7 +283,7 @@ export async function registerManifestHandlers(
           `  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
       } else {
-        registerPageLoader(route.id, (() => importFn(componentPath, importOptsForRoute(route))) as Parameters<typeof registerPageLoader>[1]);
+        registerPageLoader(route.id, (() => importFn(componentPath, importOptsForRoute(route))) as Parameters<typeof registerPageLoader>[1]);
         console.log(
           `  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
@@ -276,7 +293,7 @@ export async function registerManifestHandlers(
 
   // Phase 6.3: register `app/not-found.tsx` if it exists. Global, one per
   // app — the server falls through to the built-in 404 if unregistered.
-  await registerAppNotFound(rootDir, importFn, baseImportOpts);
+  await registerAppNotFound(rootDir, importFn, baseImportOpts);
 }
 
 /**
@@ -284,11 +301,11 @@ export async function registerManifestHandlers(
  * project root and register it as the app-level 404 handler. Silent
  * no-op if no file exists — the server's built-in 404 covers that case.
  */
-async function registerAppNotFound(
-  rootDir: string,
-  importFn: RegisterHandlersOptions["importFn"],
-  importOpts?: { changedFile?: string },
-): Promise<void> {
+async function registerAppNotFound(
+  rootDir: string,
+  importFn: RegisterHandlersOptions["importFn"],
+  importOpts?: { changedFile?: string },
+): Promise<void> {
   const candidates = [
     "app/not-found.tsx",
     "app/not-found.ts",

package/src/runtime/server.ts

@@ -1328,7 +1328,7 @@ async function handleRequestObserved(
   const result = await handleRequestInternal(req, router, registry);
 
   if (!result.ok) {
-    const errorResponse = errorToResponse(result.error, registry.settings.isDev);
+    const errorResponse = errorToResponse(result.error, registry.settings.isDev, req);
     if (registry.settings.isDev) {
       // #177: dev 모드 에러 응답도 캐시 방지
       if (!errorResponse.headers.has("Cache-Control")) {
@@ -2394,14 +2394,14 @@ async function renderNotFoundPage(
   if (!registration) {
     const handler = registry.notFoundHandler;
     if (!handler) {
-      return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev);
+      return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev, req);
     }
     try {
       const globalReg = await handler();
       registration = { component: globalReg.component as React.ComponentType<Record<string, unknown>>, filling: globalReg.filling };
     } catch (handlerError) {
       console.error(`[Mandu] global notFoundHandler failed; falling back to built-in 404:`, handlerError);
-      return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev);
+      return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev, req);
     }
   }
 
@@ -2460,7 +2460,7 @@ async function renderNotFoundPage(
     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);
+    return errorToResponse(createNotFoundResponse(new URL(req.url).pathname), settings.isDev, req);
   }
 }
 
@@ -2638,11 +2638,22 @@ async function handlePageRoute(
     // 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";
+    // #316: tell the full SPA router whether it can render this route on the
+    // client. Server-only pages (no route-level client hydration bundle) have
+    // no client component, so a pushState + state update leaves the URL changed
+    // but the content stale. When false, the router must fall back to a full
+    // document navigation so the server re-renders the page.
+    const clientRenderable = !!(
+      route.hydration &&
+      route.hydration.strategy !== "none" &&
+      settings.bundleManifest?.bundles[route.id]?.js
+    );
     const jsonResponse = Response.json({
       routeId: route.id,
       pattern: route.pattern,
       params,
       loaderData: loaderData ?? null,
+      clientRenderable,
       timestamp: Date.now(),
     });
     if (isHDR) {
@@ -3383,7 +3394,7 @@ async function handleRequestInternal(
       // Surface error-path responses to the chain so logging / metrics
       // layers see the final status. The outer `handleRequest` still owns
       // dev-mode Cache-Control stamping + observability lifecycle emission.
-      return errorToResponse(result.error, settings.isDev);
+      return errorToResponse(result.error, settings.isDev, finalReq);
     },
   });
   if (middlewareResponse) {

package/src/runtime/ssr.ts

@@ -6,13 +6,13 @@ import type { BundleManifest } from "../bundler/types";
 import { isSafeManduUrl } from "../bundler/manifest-schema";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
-import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
+import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
-import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
+import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
 import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
-import { maybeInjectDevOverlay } from "../dev-error-overlay";
-import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
+import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
 
 /**
  * Issue #192 — `@view-transition` at-rule block.
@@ -47,7 +47,7 @@ export interface SSROptions {
   title?: string;
   lang?: string;
   /** 서버에서 로드한 데이터 (클라이언트로 전달) */
-  serverData?: unknown;
+  serverData?: unknown;
   /** Hydration 설정 */
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
@@ -256,36 +256,36 @@ function generateHydrationScripts(
     ? Object.values(manifest.islands).filter((ib) => ib.route === routeId)
     : [];
 
-  if (routeIslands.length > 0) {
-    for (const ib of routeIslands) {
-      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
+  if (routeIslands.length > 0) {
+    for (const ib of routeIslands) {
+      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
   } else {
     // Fallback: route-level bundle (backward compat)
     const bundle = manifest.bundles[routeId];
     if (bundle) {
       const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  if (manifest.partials) {
-    for (const partial of Object.values(manifest.partials)) {
-      const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  if (manifest.boundaries) {
-    for (const boundary of Object.values(manifest.boundaries)) {
-      if (boundary.route !== routeId) continue;
-      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  if (manifest.partials) {
+    for (const partial of Object.values(manifest.partials)) {
+      const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  if (manifest.boundaries) {
+    for (const boundary of Object.values(manifest.boundaries)) {
+      if (boundary.route !== routeId) continue;
+      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(manifest.shared.runtime)}"></script>`);
   }
@@ -628,9 +628,9 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   return React.cloneElement(element, undefined, resolvedChildren);
 }
 
-export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const hasExplicitTitle = options.title !== undefined;
-  const {
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const hasExplicitTitle = options.title !== undefined;
+  const {
     title = "Mandu App",
     lang = "ko",
     serverData,
@@ -712,9 +712,9 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   } catch { /* client 모듈 로드 실패 시 무시 */ }
 
   const renderToString = getRenderToString();
-  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
-    renderToString(element),
-  );
+  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
+    renderToString(element),
+  );
 
   // 렌더링 중 수집된 head 태그
   collectedHeadTags = headGet?.() ?? "";
@@ -724,14 +724,14 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   const needsHydration =
     hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
-  if (needsHydration && !islandPreWrapped) {
-    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
-    const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js;
-    if (bundleSrc) {
-      content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
-    }
-  }
+  if (needsHydration && !islandPreWrapped) {
+    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js;
+    if (bundleSrc) {
+      content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
+    }
+  }
 
   // Zero-JS 모드: island이 없는 페이지에서는 클라이언트 JS 번들을 전송하지 않음
   // HMR/DevTools는 dev 환경에서만 유지 (CSS 핫리로드 등)
@@ -742,10 +742,10 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 
   if (needsHydration) {
     // 서버 데이터 스크립트 (클라이언트 hydration에서 사용)
-    if (serverData !== undefined && routeId) {
-      const wrappedData = {
-        [routeId]: {
-          serverData,
+    if (serverData !== undefined && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData,
           timestamp: Date.now(),
         },
       };
@@ -814,28 +814,52 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? `<script>window.__MANDU_SPA__=false;</script>`
     : "";
 
-  // #179: body 내 <link> 태그를 <head>로 호이스팅
+  // #179: body 내 <link> 태그를 <head>로 호이스팅
   // React 컴포넌트(layout.tsx 등)에서 <link>를 렌더링하면 body 안에 위치하게 되는데,
   // 폰트/스타일시트는 <head>에 있어야 FOUT 없이 로드됨
   const linkTagPattern = /<link\s[^>]*(?:rel=["'](?:stylesheet|preconnect|preload|icon|dns-prefetch)["'][^>]*|href=["'][^"']+["'][^>]*)\/?\s*>/gi;
   const hoistedLinks: string[] = [];
-  const bodyContent = content.replace(linkTagPattern, (match) => {
+  const bodyAfterLinks = content.replace(linkTagPattern, (match) => {
     hoistedLinks.push(match);
     return "";
   });
-  const hoistedLinkTags = hoistedLinks.join("\n  ");
-
-  // #273 F15 — React 19 renders document metadata such as <title> from a
-  // page component into the body string in this SSR path. Hoist the first
-  // body title into <head> when no metadata/generateMetadata title was
-  // provided, and always strip body titles to avoid duplicate/invalid HTML.
-  let effectiveTitle = title;
-  const titleTagPattern = /<title(?:\s[^>]*)?>([\s\S]*?)<\/title>/i;
-  const bodyTitleMatch = bodyContent.match(titleTagPattern);
-  const bodyWithoutTitle = bodyContent.replace(/<title(?:\s[^>]*)?>[\s\S]*?<\/title>/gi, "");
-  if (!hasExplicitTitle && bodyTitleMatch) {
-    effectiveTitle = decodeHtmlText(bodyTitleMatch[1] ?? title);
-  }
+  const hoistedLinkTags = hoistedLinks.join("\n  ");
+
+  // #317: hoist body <meta> (og:*, twitter:*, description, …) and JSON-LD into
+  // <head>. The legacy renderToString path does not perform React 19's
+  // document-metadata hoisting, so without this og/twitter cards land in the
+  // body where crawlers ignore them. Mirrors React 19's rule: <meta> is
+  // hoistable document metadata EXCEPT microdata (`itemprop`), which is
+  // content and must stay where it was authored.
+  const metaTagPattern = /<meta\s[^>]*?\/?>/gi;
+  const hoistedMetas: string[] = [];
+  const bodyAfterMeta = bodyAfterLinks.replace(metaTagPattern, (match) => {
+    if (/\bitemprop[\s=]/i.test(match)) return match;
+    hoistedMetas.push(match);
+    return "";
+  });
+  const hoistedMetaTags = hoistedMetas.join("\n  ");
+
+  const ldJsonPattern =
+    /<script\s[^>]*type=["']application\/ld\+json["'][^>]*>[\s\S]*?<\/script>/gi;
+  const hoistedLdJson: string[] = [];
+  const bodyContent = bodyAfterMeta.replace(ldJsonPattern, (match) => {
+    hoistedLdJson.push(match);
+    return "";
+  });
+  const hoistedLdJsonTags = hoistedLdJson.join("\n  ");
+
+  // #273 F15 — React 19 renders document metadata such as <title> from a
+  // page component into the body string in this SSR path. Hoist the first
+  // body title into <head> when no metadata/generateMetadata title was
+  // provided, and always strip body titles to avoid duplicate/invalid HTML.
+  let effectiveTitle = title;
+  const titleTagPattern = /<title(?:\s[^>]*)?>([\s\S]*?)<\/title>/i;
+  const bodyTitleMatch = bodyContent.match(titleTagPattern);
+  const bodyWithoutTitle = bodyContent.replace(/<title(?:\s[^>]*)?>[\s\S]*?<\/title>/gi, "");
+  if (!hasExplicitTitle && bodyTitleMatch) {
+    effectiveTitle = decodeHtmlText(bodyTitleMatch[1] ?? title);
+  }
 
   // Phase 18.α — Dev Error Overlay injection.
   // Only emitted when `isDev` AND the user has not opted out (via
@@ -853,19 +877,21 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${escapeHtmlText(effectiveTitle)}</title>
+  <title>${escapeHtmlText(effectiveTitle)}</title>
   ${cssLinkTag}
   ${viewTransitionTag}
   ${prefetchScriptTag}
   ${spaNavHelperTag}
   ${hoistedLinkTags}
+  ${hoistedMetaTags}
+  ${hoistedLdJsonTags}
   ${headTags}
   ${collectedHeadTags}
   ${fastRefreshPreamble}
   ${devErrorOverlayTag}
 </head>
 <body>
-  <div id="root"${rootAttrs}>${bodyWithoutTitle}</div>
+  <div id="root"${rootAttrs}>${bodyWithoutTitle}</div>
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}
@@ -882,11 +908,11 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 /**
  * Client-side Routing: 현재 라우트 정보 스크립트 생성
  */
-function generateRouteScript(
-  routeId: string,
-  pattern: string,
-  _serverData?: unknown
-): string {
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  _serverData?: unknown
+): string {
   const routeInfo = {
     id: routeId,
     pattern,
@@ -1187,12 +1213,12 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
  */
 export async function renderWithHydration(
   element: ReactElement,
-  options: SSROptions & {
-    routeId: string;
-    serverData: unknown;
-    hydration: HydrationConfig;
-    bundleManifest: BundleManifest;
-  }
+  options: SSROptions & {
+    routeId: string;
+    serverData: unknown;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
 ): Promise<Response> {
   const html = renderToHTML(element, options);
   // Phase 7.2 R1 Agent C (H1) — same CSP header logic as renderSSR.