@mandujs/core 0.31.0 → 0.33.0

package/src/runtime/server.ts

@@ -1,5 +1,5 @@
 import type { Server } from "bun";
-import type { RoutesManifest, RouteSpec, HydrationConfig } from "../spec/schema";
+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";
@@ -117,6 +117,20 @@ import {
   buildPayloadFromError,
   shouldInjectOverlay,
 } from "../dev-error-overlay";
+// Phase 18.μ — i18n dispatch. `resolveLocale()` is pure (no side effects),
+// `createTranslator()` binds a per-request `t()` to the registry.
+import {
+  resolveLocale,
+  createTranslator,
+  isI18nDefinition,
+  isMessageRegistry,
+} from "../i18n";
+import type {
+  I18nDefinition,
+  ResolvedLocale,
+  Translator,
+} from "../i18n/types";
+import type { MessageRegistry } from "../i18n/message-registry";
 
 export interface RateLimitOptions {
   windowMs?: number;
@@ -517,6 +531,14 @@ export interface ServerOptions {
    * `secureMiddleware`, `rateLimitMiddleware`).
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.τ — plugins contributing `defineMiddlewareChain()` +
+   * lifecycle observers. Plugin middleware are PREPENDED to
+   * `options.middleware` so they run BEFORE user-declared layers. Both
+   * fields are optional; omission is a zero-overhead passthrough.
+   */
+  plugins?: readonly import("../plugins/hooks").ManduPlugin[];
+  configHooks?: Partial<import("../plugins/hooks").ManduHooks>;
   /**
    * Phase 18.κ — tRPC-like typed RPC endpoints.
    *
@@ -548,6 +570,33 @@ export interface ServerOptions {
     jobs?: import("../scheduler").CronDef[];
     disabled?: boolean;
   };
+  /**
+   * Phase 18.μ — first-class i18n. Threaded from `ManduConfig.i18n`.
+   *
+   * When populated, the runtime dispatcher:
+   *   1. resolves the active locale BEFORE route dispatch (via
+   *      {@link resolveLocale}) using the configured strategy;
+   *   2. attaches `ctx.locale` (ResolvedLocale) + `ctx.t` (typed
+   *      translator) to every loader / handler invocation;
+   *   3. stamps `Vary: Accept-Language` + `Content-Language` on all
+   *      page responses so upstream caches key on locale;
+   *   4. when `strategy === "path-prefix"` and the incoming URL
+   *      carries no locale prefix AND no override cookie, redirects
+   *      `/` → `/<defaultLocale>` so browsers reach a locale-scoped
+   *      URL (Next.js parity).
+   *
+   * Omitting this block keeps the runtime branch-free — the hot path
+   * incurs zero overhead when i18n is disabled.
+   */
+  i18n?: I18nDefinition;
+  /**
+   * Phase 18.μ — optional message registry bound to `ctx.t`. Created via
+   * `defineMessages({ en: {...}, ko: {...} })`. When omitted but `i18n`
+   * is set, `ctx.locale` is populated but `ctx.t` stays `undefined` —
+   * projects that manage their own translation layer (e.g. react-intl)
+   * use `ctx.locale.code` and ignore `ctx.t`.
+   */
+  messages?: MessageRegistry;
 }
 
 export interface ManduServer {
@@ -736,6 +785,19 @@ export interface ServerRegistrySettings {
    * `ServerOptions.middleware` at {@link startServer} time.
    */
   middlewareChain?: ComposedHandler;
+  /**
+   * Phase 18.μ — resolved i18n definition. `undefined` means "no i18n
+   * configured at boot" (hot path is branch-free). Wired from
+   * `ServerOptions.i18n`.
+   */
+  i18n?: I18nDefinition;
+  /**
+   * Phase 18.μ — message registry bound to {@link i18n}. When both are
+   * set, the runtime builds a per-request `ctx.t` via
+   * `createTranslator()`. When only `i18n` is set, `ctx.t` stays
+   * `undefined` and user code is responsible for its own translations.
+   */
+  messages?: MessageRegistry;
 }
 
 export class ServerRegistry {
@@ -1609,6 +1671,15 @@ async function handleRequestWithTracing(
         });
       }
     }
+    // Phase 18.μ — stamp locale hint on error responses too.
+    const errI18nState = i18nRequestState.get(req);
+    if (errI18nState && !errorResponse.headers.has("Content-Language")) {
+      try {
+        errorResponse.headers.set("Content-Language", errI18nState.locale.code);
+      } catch {
+        // Some adapters freeze headers on error responses — ignore.
+      }
+    }
     return errorResponse;
   }
 
@@ -1642,6 +1713,28 @@ async function handleRequestWithTracing(
     }
   }
 
+  // Phase 18.μ — stamp locale-sensitive caching hints onto the final
+  // response. `Vary: Accept-Language, Cookie` ensures upstream caches
+  // key correctly per locale signal; `Content-Language` surfaces the
+  // resolved locale for SEO / screen-reader parity. Only stamped when
+  // i18n is configured AND the request was actually resolved — the hot
+  // path is branch-free when `i18n` is absent.
+  const i18nState = i18nRequestState.get(req);
+  if (i18nState) {
+    const existingVary = result.value.headers.get("Vary");
+    const varyParts = new Set(
+      (existingVary ? existingVary.split(",") : [])
+        .map((s) => s.trim())
+        .filter(Boolean)
+    );
+    varyParts.add("Accept-Language");
+    varyParts.add("Cookie");
+    result.value.headers.set("Vary", [...varyParts].join(", "));
+    if (!result.value.headers.has("Content-Language")) {
+      result.value.headers.set("Content-Language", i18nState.locale.code);
+    }
+  }
+
   return result.value;
 }
 
@@ -1908,6 +2001,7 @@ async function loadPageData(
       // Filling의 loader 실행
       if (registration.filling?.hasLoader()) {
         const ctx = new ManduContext(req, params);
+        attachI18nToContext(ctx, req);
         // 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.
@@ -2028,6 +2122,7 @@ async function loadPageData(
       }
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
+        attachI18nToContext(ctx, req);
         // DX-3 / Phase 6.3: same redirect + notFound handling as the
         // PageHandler path above. notFound is checked first so both
         // short-circuits remain symmetric.
@@ -2197,6 +2292,7 @@ async function loadLayoutData(
           const filling = exported as ManduFilling;
           if (filling.hasLoader()) {
             const ctx = new ManduContext(req, params);
+            attachI18nToContext(ctx, req);
             const data = await filling.executeLoader(ctx);
             // DX-3: layout loaders are NOT allowed to redirect. They share
             // the pipeline with a page loader and we can only honor one
@@ -2430,15 +2526,27 @@ async function renderPageSSR(
       ? route.streaming
       : settings.streaming;
 
-    // Issue #198 — Pre-resolve async server components before handing off
-    // to React's SSR engines. `renderToString` (non-streaming path) does
-    // not support async components; `renderToReadableStream` does, but
-    // the shell-gen step in streaming-ssr also falls through
-    // `collectStreamingHeadTags` → `renderToString`. Resolving up-front
-    // gives consistent, synchronous trees to both paths and keeps the
-    // user-visible contract (`export default async function Page() {...}`
-    // and `export default async function Layout() {...}`) working end to end.
-    app = (await resolveAsyncElement(app)) as React.ReactElement;
+    // Issue #198 / Phase 18.ξ — Async server component resolution policy.
+    //
+    // Non-streaming path (`renderToString`) cannot handle async components,
+    // so we MUST pre-resolve the tree up-front.
+    //
+    // Streaming path (`renderToReadableStream`, React 19) supports async
+    // components natively and is designed around progressive flushing. If
+    // we pre-resolve here, the caller blocks until every async component
+    // settles before the shell can be emitted — defeating the entire point
+    // of streaming (`TTFB` regresses from shell-ready to slowest-component).
+    // So in streaming mode we hand React the raw async tree. Head tags
+    // pushed from async components are captured by `renderToStream`'s
+    // `buildHtmlTail` (late-head injection) via `use-head`. The streaming
+    // shell-gen's `collectStreamingHeadTags` pre-pass uses `renderToString`
+    // internally and will throw on async trees — its try/catch already
+    // handles that case and returns an empty string, so the early shell
+    // emission is still correct; the late-head script fills in any
+    // metadata emitted during the async render.
+    if (!useStreaming) {
+      app = (await resolveAsyncElement(app)) as React.ReactElement;
+    }
 
     if (useStreaming) {
       const streamingResponse = await renderStreamingResponse(app, {
@@ -2667,6 +2775,7 @@ async function renderNotFoundPage(
     let loaderData: unknown = { message };
     if (registration.filling?.hasLoader()) {
       const ctx = new ManduContext(req, params);
+      attachI18nToContext(ctx, req);
       try {
         const returned = await registration.filling.executeLoader(ctx);
         loaderData = returned !== undefined ? returned : { message };
@@ -3243,6 +3352,117 @@ async function tryServePrerendered(
   return new Response(body, { status: 200, headers });
 }
 
+// ─── Phase 18.μ — request-scoped i18n state ──────────────────────────────
+/**
+ * Per-request locale state keyed by the `Request` object. The runtime
+ * dispatcher populates this right before `handleRequestInternal` returns
+ * to route-specific paths; `handlePageRoute` / `handleApiRoute` read it
+ * when creating `ManduContext` and attach via `ctx._setI18n(...)`.
+ *
+ * A WeakMap is used so completed requests release their entries
+ * automatically — no explicit cleanup needed on the hot path.
+ *
+ * @internal
+ */
+const i18nRequestState = new WeakMap<
+  Request,
+  { locale: ResolvedLocale; translator?: Translator }
+>();
+
+/**
+ * Phase 18.μ — expose the stashed locale state for `filling` /
+ * `handlePageRoute` / `handleApiRoute`. Returns `undefined` when i18n
+ * is disabled OR the request predates dispatch (internal callers).
+ *
+ * @internal
+ */
+export function getRequestI18n(
+  req: Request
+): { locale: ResolvedLocale; translator?: Translator } | undefined {
+  return i18nRequestState.get(req);
+}
+
+/**
+ * Phase 18.μ — attach i18n state to a freshly-constructed `ManduContext`.
+ * No-op when i18n is disabled. Called by every callsite that instantiates
+ * `new ManduContext(req, …)` so `ctx.locale` + `ctx.t` are populated
+ * before loader / handler execution.
+ *
+ * @internal
+ */
+function attachI18nToContext(ctx: ManduContext, req: Request): void {
+  const state = i18nRequestState.get(req);
+  if (state) {
+    ctx._setI18n(state.locale, state.translator);
+  }
+}
+
+/**
+ * Helper: returns the URL's first segment if it matches a known locale.
+ * Extracted so the inline μ dispatch block stays readable.
+ */
+function stripLocaleForRedirectCheck(
+  pathname: string,
+  locales: readonly string[]
+): string | undefined {
+  if (pathname.length < 2) return undefined;
+  const slashIdx = pathname.indexOf("/", 1);
+  const first = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
+  return locales.includes(first) ? first : undefined;
+}
+// ─── End Phase 18.μ ──────────────────────────────────────────────────────
+
+// ─── Issue #214 — dynamicParams guard helper ────────────────────────────────
+/**
+ * True when the incoming `params` from the router matches one of the
+ * enumerated sets in `staticParams` (populated at build time from
+ * `generateStaticParams`). Used by the runtime #214 guard to decide
+ * whether a `dynamicParams: false` page must 404.
+ *
+ * Matching rules mirror `bundler/generate-static-params.ts`:
+ *   - Scalar segments compare as exact strings.
+ *   - Catch-all segments compare as slash-joined strings (the router
+ *     always materializes wildcards as a single string, whereas
+ *     `generateStaticParams` emits `string[]` — we normalize both
+ *     sides to the joined form for equality).
+ *
+ * When `staticParams` is undefined or empty, no URL can match — the
+ * route effectively becomes "no dynamic URLs at all", which is the
+ * documented behavior of `dynamicParams: false` + `generateStaticParams: []`.
+ */
+function paramsInStaticSet(
+  params: Record<string, string>,
+  staticParams: StaticParamSetSchema[] | undefined
+): boolean {
+  if (!staticParams || staticParams.length === 0) return false;
+  const paramKeys = Object.keys(params);
+  for (const entry of staticParams) {
+    if (!entry) continue;
+    let allMatch = true;
+    for (const key of paramKeys) {
+      const requestValue = params[key];
+      const declared = (entry as Record<string, string | string[] | undefined>)[key];
+      if (declared === undefined) {
+        // Optional catch-all that wasn't declared — router gives empty
+        // string in that case; anything else is a miss.
+        if (requestValue !== "") {
+          allMatch = false;
+          break;
+        }
+        continue;
+      }
+      const declaredJoined = Array.isArray(declared) ? declared.join("/") : declared;
+      if (declaredJoined !== requestValue) {
+        allMatch = false;
+        break;
+      }
+    }
+    if (allMatch) return true;
+  }
+  return false;
+}
+// ─── End Issue #214 ─────────────────────────────────────────────────────────
+
 async function handleRequestInternal(
   req: Request,
   router: Router,
@@ -3272,6 +3492,92 @@ async function handleRequestInternal(
     return ok(prerendered);
   }
 
+  // ─── Phase 18.μ — i18n dispatch ─────────────────────────────────────────
+  // Runs AFTER γ's prerendered check (static HTML per-locale is already
+  // handled by path-prefix synthesis at build time) and BEFORE ζ's cache
+  // lookup (cache keys include the resolved locale via `Vary:
+  // Accept-Language`).
+  //
+  //   1. Resolve the active locale via `resolveLocale()` — the strategy
+  //      switches determines URL / cookie / header precedence.
+  //   2. For `strategy: 'path-prefix'`: when the incoming URL carries no
+  //      locale prefix (root or locale-less path) AND the resolution
+  //      came from `default` / `fallback`, we emit a 307 redirect to
+  //      `/<locale><rest>` so the user lands on a locale-scoped URL.
+  //      Cookie / header signals "win" over the default — no redirect
+  //      when the user explicitly preferred a non-default locale.
+  //   3. Stash the resolved locale on the `registry.__perRequest` map
+  //      indexed by the request so downstream `handlePageRoute` /
+  //      `handleApiRoute` can mount it onto `ctx` via `_setI18n()`.
+  //
+  // Zero overhead when `settings.i18n` is undefined — the `if` falls
+  // through and the hot path runs exactly as Phase 18.λ's baseline.
+  let resolvedLocaleForRequest: ResolvedLocale | undefined;
+  let translatorForRequest: Translator | undefined;
+  if (settings.i18n) {
+    resolvedLocaleForRequest = resolveLocale(req, settings.i18n);
+
+    // Path-prefix strategy: URL has no locale prefix AND resolver picked
+    // a non-default locale from cookie/header → redirect to prefixed URL
+    // so the user lands on a locale-scoped URL (Next.js parity).
+    //
+    // Excluded paths (never redirected, always locale-neutral):
+    //   - `/api/*`  — API routes use `Accept-Language` header; JSON
+    //     clients rarely want an HTML redirect.
+    //   - `/_mandu/*`, `/.mandu/*` — framework internals.
+    //   - `/sitemap.xml`, `/robots.txt`, etc. — metadata routes live
+    //     at site root across all locales.
+    if (
+      settings.i18n.strategy === "path-prefix" &&
+      (req.method === "GET" || req.method === "HEAD") &&
+      !pathname.startsWith("/api/") &&
+      !pathname.startsWith("/_mandu/") &&
+      !pathname.startsWith("/.mandu/") &&
+      !pathname.startsWith("/__kitchen") &&
+      !pathname.startsWith("/__mandu/") &&
+      pathname !== "/sitemap.xml" &&
+      pathname !== "/robots.txt" &&
+      pathname !== "/llms.txt" &&
+      pathname !== "/manifest.webmanifest"
+    ) {
+      const urlLocale = stripLocaleForRedirectCheck(pathname, settings.i18n.locales);
+      if (!urlLocale && resolvedLocaleForRequest.code !== settings.i18n.defaultLocale) {
+        const targetPath = `/${resolvedLocaleForRequest.code}${pathname === "/" ? "" : pathname}`;
+        const targetUrl = new URL(targetPath + url.search, req.url);
+        const redirectRes = new Response(null, {
+          status: 307,
+          headers: {
+            Location: targetUrl.toString(),
+            Vary: "Accept-Language, Cookie",
+            "Content-Language": resolvedLocaleForRequest.code,
+          },
+        });
+        return ok(redirectRes);
+      }
+    }
+
+    // Build translator if a registry is wired up.
+    if (settings.messages) {
+      translatorForRequest = createTranslator(settings.messages, {
+        activeLocale: resolvedLocaleForRequest.code,
+        defaultLocale: settings.i18n.defaultLocale,
+        fallbackLocale: settings.i18n.fallback,
+      });
+    }
+
+    // Stash on request-scoped map so downstream context creation (inside
+    // `handlePageRoute` / `handleApiRoute`) can pick them up without
+    // threading extra args through every call site. `i18nRequestState`
+    // is a WeakMap — no memory retention after the request completes.
+    if (resolvedLocaleForRequest) {
+      i18nRequestState.set(req, {
+        locale: resolvedLocaleForRequest,
+        translator: translatorForRequest,
+      });
+    }
+  }
+  // ─── End Phase 18.μ ─────────────────────────────────────────────────────
+
   // 1. 정적 파일 서빙 시도 (최우선)
   // Edge runtimes (Cloudflare Workers, etc.) have no filesystem — skip and
   // let the platform's asset pipeline (Wrangler [assets], Vercel _static, …)
@@ -3425,6 +3731,7 @@ async function handleRequestInternal(
         let loaderData: unknown = { message: "Not Found" };
         if (registration.filling?.hasLoader()) {
           const ctx = new ManduContext(req, {});
+          attachI18nToContext(ctx, req);
           try {
             const returned = await registration.filling.executeLoader(ctx);
             loaderData = returned !== undefined ? returned : { message: "Not Found" };
@@ -3459,6 +3766,64 @@ async function handleRequestInternal(
 
   const { route, params } = match;
 
+  // ─── Issue #214 — dynamicParams guard ─────────────────────────────────────
+  // Runs AFTER γ's prerendered pass-through (step 0.5) and BEFORE ζ's
+  // per-route ISR cache dispatch (which lives inside `handlePageRoute`).
+  //
+  // Contract (Next.js parity):
+  //   - Page route opted into `dynamicParams: false` AND has `staticParams`
+  //     populated from `generateStaticParams` at build time → the incoming
+  //     params MUST match one of the known sets. Otherwise: 404.
+  //   - `dynamicParams: true` (or undefined) → default behavior unchanged.
+  //     Any dynamic URL falls through to SSR just like before.
+  //   - API + metadata routes are never gated — `dynamicParams` is
+  //     page-only.
+  //
+  // The guard short-circuits with `renderNotFoundPage` so per-route
+  // `not-found.tsx` / global `notFoundHandler` / built-in JSON 404 all
+  // render correctly without recursing through SSR. Cookies are not
+  // applied because no page loader has run yet — this check precedes
+  // loader dispatch by design.
+  if (
+    route.kind === "page" &&
+    (route as { dynamicParams?: boolean }).dynamicParams === false
+  ) {
+    const staticParams = (route as { staticParams?: StaticParamSetSchema[] })
+      .staticParams;
+    if (!paramsInStaticSet(params, staticParams)) {
+      const pageRouteForNF = route as {
+        id: string;
+        pattern: string;
+        layoutChain?: string[];
+        hydration?: HydrationConfig;
+        streaming?: boolean;
+        notFoundModule?: string;
+      };
+      const nfResponse = await renderNotFoundPage(
+        req,
+        pageRouteForNF,
+        params,
+        registry,
+        /* pageCookies */ undefined,
+        /* layoutCookies */ undefined,
+        /* layoutData */ undefined,
+        new Response(
+          JSON.stringify({
+            message: `No static param match for ${pathname}`,
+          }),
+          { status: 404, headers: { "Content-Type": "application/json" } }
+        )
+      );
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions =
+          typeof settings.cors === "object" ? settings.cors : {};
+        return ok(applyCorsToResponse(nfResponse, req, corsOptions));
+      }
+      return ok(nfResponse);
+    }
+  }
+  // ─── End Issue #214 ───────────────────────────────────────────────────────
+
   // 3. 라우트 종류별 처리
   if (route.kind === "api") {
     const rateLimitOptions = settings.rateLimit;
@@ -3610,11 +3975,43 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     middleware: middlewareOption,
     rpc: rpcOption,
     scheduler: schedulerOption,
+    i18n: i18nOption,
+    messages: messagesOption,
+    plugins: pluginsOption,
+    configHooks: configHooksOption,
   } = options;
 
+  // Phase 18.μ — validate i18n + messages shape. Both are branded via
+  // `defineI18n()` / `defineMessages()`; reject any raw object so user
+  // typos fail fast at boot instead of on first request.
+  if (i18nOption !== undefined && !isI18nDefinition(i18nOption)) {
+    throw new Error(
+      "[mandu] ServerOptions.i18n must be the return value of defineI18n(). " +
+        "Import { defineI18n } from '@mandujs/core/i18n'."
+    );
+  }
+  if (messagesOption !== undefined && !isMessageRegistry(messagesOption)) {
+    throw new Error(
+      "[mandu] ServerOptions.messages must be the return value of defineMessages(). " +
+        "Import { defineMessages } from '@mandujs/core/i18n'."
+    );
+  }
+
   // Phase 18.ε — build the request-level middleware chain once at boot.
   // `compose()` returns a passthrough when the list is empty; storing
   // `undefined` for "no middleware" keeps the hot path branch-free.
+  //
+  // Phase 18.τ — plugin-contributed middleware via `defineMiddlewareChain()`
+  // is resolved asynchronously OUTSIDE `startServer()` (which is sync).
+  // Drivers call `resolvePluginMiddleware({ plugins, configHooks, rootDir,
+  // mode })` and pass the resulting `Middleware[]` as a PREFIX of
+  // `options.middleware` before calling `startServer()`.
+  //
+  // `pluginsOption` / `configHooksOption` are still carried here so that
+  // lifecycle observers fired by drivers can reuse the same bundle; they
+  // are NOT consulted for the middleware chain itself.
+  void pluginsOption;
+  void configHooksOption;
   const middlewareChain: ComposedHandler | undefined =
     middlewareOption && middlewareOption.length > 0
       ? composeMiddleware(...middlewareOption)
@@ -3692,6 +4089,8 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     tracer: tracerInstance.enabled ? tracerInstance : undefined,
     prerender: prerenderSettings,
     middlewareChain,
+    i18n: i18nOption,
+    messages: messagesOption,
   };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;

package/src/runtime/ssr.ts

@@ -590,6 +590,15 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   // Clone with the resolved children. React.cloneElement preserves the
   // element's key, ref, and internal `$$typeof` markers — a plain spread
   // does not.
+  //
+  // #212 — when resolvedChildren is an array of siblings, spread it back
+  // to the variadic form so React's variadic-children heuristic kicks in
+  // and does NOT demand keys (the original JSX was variadic too — no key
+  // was required). Passing a single array argument would trigger spurious
+  // "missing key" warnings for every sibling.
+  if (Array.isArray(resolvedChildren)) {
+    return React.cloneElement(element, undefined, ...resolvedChildren);
+  }
   return React.cloneElement(element, undefined, resolvedChildren);
 }
 

package/src/spec/schema.ts

@@ -80,6 +80,13 @@ const RouteSpecBase = {
   streaming: z.boolean().optional(),
 };
 
+// ---- Static params (Issue #214) ----
+// StaticParamSet values mirror `bundler/generate-static-params.ts` —
+// scalar params are strings, catch-all params are `string[]`.
+const StaticParamValue = z.union([z.string(), z.array(z.string())]);
+const StaticParamSet = z.record(StaticParamValue);
+export type StaticParamSetSchema = z.infer<typeof StaticParamSet>;
+
 // ---- Page 라우트 ----
 export const PageRouteSpec = z
   .object({
@@ -93,6 +100,20 @@ export const PageRouteSpec = z
     loadingModule: z.string().optional(),
     errorModule: z.string().optional(),
     notFoundModule: z.string().optional(),
+    /**
+     * Issue #214 — when `false`, the runtime rejects dynamic URLs
+     * whose params aren't in `staticParams` with a 404 instead of
+     * falling through to SSR. Undefined or `true` preserves the
+     * default "SSR on miss" behavior (Next.js parity).
+     */
+    dynamicParams: z.boolean().optional(),
+    /**
+     * Issue #214 — populated at build time from `generateStaticParams`.
+     * Consulted by the runtime #214 guard together with `dynamicParams`
+     * to decide whether an incoming param set is allowed. Scalar values
+     * are strings; catch-all values are string arrays.
+     */
+    staticParams: z.array(StaticParamSet).optional(),
   })
   .refine(
     (route) => {
@@ -159,6 +180,10 @@ export const RouteSpec = z.discriminatedUnion("kind", [
     loadingModule: z.string().optional(),
     errorModule: z.string().optional(),
     notFoundModule: z.string().optional(),
+    // Issue #214 — see PageRouteSpec for contract. Kept optional so
+    // existing manifests load unchanged (default behavior: dynamic SSR).
+    dynamicParams: z.boolean().optional(),
+    staticParams: z.array(StaticParamSet).optional(),
   }),
   z.object({
     ...RouteSpecBase,