@mandujs/core 0.32.0 → 0.33.0

package/src/plugins/runner.ts

@@ -0,0 +1,361 @@
+/**
+ * Canonical Plugin Hook Runner — Phase 18.τ.
+ *
+ * This module is the only place where plugin hook dispatch + merge
+ * semantics are implemented. Every integration point (bundler, prerender,
+ * router scanner, runtime server) imports from here so the rules are
+ * consistent and easy to audit.
+ *
+ * Dispatch order, common to every hook:
+ *   1. Config-level hooks (from `ManduConfig.hooks`) run FIRST.
+ *   2. Plugin hooks (from `ManduConfig.plugins[].hooks`) run in
+ *      declaration order.
+ *   3. Each invocation is isolated in try/catch — one failure does not
+ *      block subsequent hooks. Errors are collected in the returned
+ *      {@link HookRunReport} so callers can surface a single rollup.
+ *
+ * Merge semantics (per hook type):
+ *
+ *   | Hook                    | Return type            | Merge rule          |
+ *   | ----------------------- | ---------------------- | ------------------- |
+ *   | `onRouteRegistered`     | void                   | —                   |
+ *   | `onBundleComplete`      | void                   | —                   |
+ *   | `definePrerenderHook`   | PrerenderOverride|void | Object spread       |
+ *   | `onManifestBuilt`       | RoutesManifest|void    | Pipe (last wins)    |
+ *   | `defineBundlerPlugin`   | BunPlugin|BunPlugin[]  | Concat              |
+ *   | `defineMiddlewareChain` | Middleware[]           | Concat              |
+ *   | `defineTestTransform`   | string                 | Pipe (each sees prev)|
+ *
+ * @see `docs/architect/plugin-api.md`
+ * @see `./hooks.ts` for the typed surface
+ */
+
+import type { BunPlugin } from "bun";
+import type { Middleware } from "../middleware/define";
+import type { BundleStats } from "../bundler/types";
+import type { RouteSpec, RoutesManifest } from "../spec/schema";
+import type {
+  ManduPlugin,
+  ManduHooks,
+  PluginContext,
+  PrerenderContext,
+  PrerenderOverride,
+  TestTransformContext,
+} from "./hooks";
+
+// ═══════════════════════════════════════════════════════════════════════
+// Shared types
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Per-hook-invocation error record. Attached to the returned report so
+ * callers can log "plugin X failed on hook Y" without swallowing the
+ * stack trace.
+ */
+export interface HookError {
+  /** Hook name that failed. */
+  hook: keyof ManduHooks;
+  /** Plugin label — either `"config"` or `plugin.name`. */
+  source: string;
+  /** Captured error. */
+  error: Error;
+}
+
+export interface HookRunReport<T = unknown> {
+  /** Merged result (shape varies by hook — see merge table above). */
+  result: T;
+  /** Errors swallowed per hook invocation. Empty when all plugins succeeded. */
+  errors: HookError[];
+}
+
+/**
+ * Args common to every runner call.
+ */
+export interface RunnerArgs {
+  plugins: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Yield every `(source, fn)` pair for a given hook name, in the canonical
+ * dispatch order: config hook first, then plugin hooks by declaration.
+ */
+function* iterateHook<K extends keyof ManduHooks>(
+  hookName: K,
+  args: RunnerArgs,
+): Generator<{ source: string; fn: NonNullable<ManduHooks[K]> }> {
+  const configFn = args.configHooks?.[hookName];
+  if (configFn) {
+    yield { source: "config", fn: configFn as NonNullable<ManduHooks[K]> };
+  }
+  for (const plugin of args.plugins) {
+    const pluginFn = plugin.hooks?.[hookName];
+    if (pluginFn) {
+      yield {
+        source: plugin.name,
+        fn: pluginFn as NonNullable<ManduHooks[K]>,
+      };
+    }
+  }
+}
+
+/**
+ * Invoke a hook function and surface any thrown error as a HookError so
+ * the caller can carry on with the next plugin. Returns the function's
+ * return value (or `undefined` on error).
+ */
+async function invokeSafely<R>(
+  hookName: keyof ManduHooks,
+  source: string,
+  thunk: () => R | Promise<R>,
+  errors: HookError[],
+): Promise<R | undefined> {
+  try {
+    return await thunk();
+  } catch (raw) {
+    const error = raw instanceof Error ? raw : new Error(String(raw));
+    errors.push({ hook: hookName, source, error });
+    // Surface to stderr too — matches the legacy `runHook` behaviour so
+    // users see the failure even if the caller ignores the report.
+    console.error(`[plugin] ${hookName} failed in ${source}: ${error.message}`);
+    return undefined;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Observer runners (void return — "fire and forget")
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Fire `onRouteRegistered` for each scanned route. Errors in one plugin
+ * don't stop the scan, or even other plugins for the same route.
+ */
+export async function runOnRouteRegistered(
+  route: RouteSpec,
+  args: RunnerArgs,
+): Promise<HookRunReport<void>> {
+  const errors: HookError[] = [];
+  for (const { source, fn } of iterateHook("onRouteRegistered", args)) {
+    await invokeSafely("onRouteRegistered", source, () => fn(route), errors);
+  }
+  return { result: undefined, errors };
+}
+
+/**
+ * Fire `onBundleComplete` with the final BundleStats.
+ */
+export async function runOnBundleComplete(
+  stats: BundleStats,
+  args: RunnerArgs,
+): Promise<HookRunReport<void>> {
+  const errors: HookError[] = [];
+  for (const { source, fn } of iterateHook("onBundleComplete", args)) {
+    await invokeSafely("onBundleComplete", source, () => fn(stats), errors);
+  }
+  return { result: undefined, errors };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Transformer runners (return-value pipe / spread)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Merge strategy for `definePrerenderHook`:
+ *
+ *   - Each plugin's non-undefined return spreads onto the accumulator so
+ *     later plugins can override earlier fields (`{ skip: true }` wins
+ *     unless a later plugin sets `{ skip: false }` explicitly).
+ *   - An undefined / void return is treated as "no change".
+ */
+export async function runDefinePrerenderHook(
+  ctx: PrerenderContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<PrerenderOverride>> {
+  const errors: HookError[] = [];
+  let merged: PrerenderOverride = {};
+  for (const { source, fn } of iterateHook("definePrerenderHook", args)) {
+    const out = await invokeSafely(
+      "definePrerenderHook",
+      source,
+      () => fn(ctx),
+      errors,
+    );
+    if (out && typeof out === "object") {
+      merged = { ...merged, ...out };
+    }
+  }
+  return { result: merged, errors };
+}
+
+/**
+ * Pipe `onManifestBuilt` across plugins. Each plugin receives the
+ * manifest the previous plugin returned. A `void` / `undefined` return
+ * means "no change, pass through".
+ */
+export async function runOnManifestBuilt(
+  manifest: RoutesManifest,
+  args: RunnerArgs,
+): Promise<HookRunReport<RoutesManifest>> {
+  const errors: HookError[] = [];
+  let current: RoutesManifest = manifest;
+  for (const { source, fn } of iterateHook("onManifestBuilt", args)) {
+    const out = await invokeSafely(
+      "onManifestBuilt",
+      source,
+      () => fn(current),
+      errors,
+    );
+    if (out && typeof out === "object") {
+      current = out;
+    }
+  }
+  return { result: current, errors };
+}
+
+/**
+ * Collect BunPlugin contributions across every plugin. Scalar returns are
+ * wrapped into a single-element array; array returns are concatenated.
+ * `undefined` is skipped.
+ */
+export async function runDefineBundlerPlugin(
+  args: RunnerArgs,
+): Promise<HookRunReport<BunPlugin[]>> {
+  const errors: HookError[] = [];
+  const collected: BunPlugin[] = [];
+  for (const { source, fn } of iterateHook("defineBundlerPlugin", args)) {
+    const out = await invokeSafely(
+      "defineBundlerPlugin",
+      source,
+      () => fn(),
+      errors,
+    );
+    if (!out) continue;
+    if (Array.isArray(out)) {
+      collected.push(...out);
+    } else {
+      collected.push(out);
+    }
+  }
+  return { result: collected, errors };
+}
+
+/**
+ * Concatenate Middleware arrays from every plugin that provides a
+ * `defineMiddlewareChain`. The returned array is prepended to the
+ * user-declared `ManduConfig.middleware` at server boot time (see
+ * `runtime/server.ts`).
+ */
+export async function runDefineMiddlewareChain(
+  ctx: PluginContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<Middleware[]>> {
+  const errors: HookError[] = [];
+  const collected: Middleware[] = [];
+  for (const { source, fn } of iterateHook("defineMiddlewareChain", args)) {
+    const out = await invokeSafely(
+      "defineMiddlewareChain",
+      source,
+      () => fn(ctx),
+      errors,
+    );
+    if (Array.isArray(out)) {
+      collected.push(...out);
+    }
+  }
+  return { result: collected, errors };
+}
+
+/**
+ * Pipe test-file source through every plugin's `defineTestTransform`.
+ * Each plugin sees the output of the previous plugin. A thrown error
+ * leaves the source unchanged for that step.
+ */
+export async function runDefineTestTransform(
+  ctx: TestTransformContext,
+  args: RunnerArgs,
+): Promise<HookRunReport<string>> {
+  const errors: HookError[] = [];
+  let current = ctx.source;
+  for (const { source, fn } of iterateHook("defineTestTransform", args)) {
+    const out = await invokeSafely(
+      "defineTestTransform",
+      source,
+      () => fn({ testFile: ctx.testFile, source: current }),
+      errors,
+    );
+    if (typeof out === "string") {
+      current = out;
+    }
+  }
+  return { result: current, errors };
+}
+
+/**
+ * Driver-friendly wrapper for `runDefineMiddlewareChain` that returns
+ * the merged Middleware[] directly (errors are logged to stderr via
+ * the same path as the inner runner). Use when a sync caller like
+ * `startServer()` needs the array pre-resolved — wrap the call in
+ * `await` from your driver (the CLI), then pass the result in as a
+ * PREFIX to `options.middleware`.
+ *
+ * @example
+ * ```ts
+ * const pluginMiddleware = await resolvePluginMiddleware({
+ *   plugins: config.plugins ?? [],
+ *   configHooks: config.hooks,
+ *   rootDir: process.cwd(),
+ *   mode: isDev ? "development" : "production",
+ * });
+ * startServer(manifest, {
+ *   ...serverOptions,
+ *   middleware: [...pluginMiddleware, ...(config.middleware ?? [])],
+ *   plugins: config.plugins,
+ *   configHooks: config.hooks,
+ * });
+ * ```
+ */
+export async function resolvePluginMiddleware(input: {
+  plugins: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
+  rootDir: string;
+  mode: "development" | "production";
+}): Promise<Middleware[]> {
+  const ctx: PluginContext = {
+    rootDir: input.rootDir,
+    mode: input.mode,
+    logger: {
+      debug: (m, d) => console.debug(`[plugin] ${m}`, d ?? ""),
+      info: (m, d) => console.info(`[plugin] ${m}`, d ?? ""),
+      warn: (m, d) => console.warn(`[plugin] ${m}`, d ?? ""),
+      error: (m, d) => console.error(`[plugin] ${m}`, d ?? ""),
+    },
+  };
+  const report = await runDefineMiddlewareChain(ctx, {
+    plugins: input.plugins,
+    configHooks: input.configHooks,
+  });
+  return report.result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Convenience: summarize errors for CLI output
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Render an error rollup the CLI can print. Returns `null` when the
+ * report is clean — callers should treat `null` as "nothing to log".
+ */
+export function formatHookErrors(
+  report: HookRunReport<unknown>,
+): string | null {
+  if (report.errors.length === 0) return null;
+  const lines = [`[plugin] ${report.errors.length} hook failure(s):`];
+  for (const e of report.errors) {
+    lines.push(`  - ${e.hook} in ${e.source}: ${e.error.message}`);
+  }
+  return lines.join("\n");
+}

package/src/router/fs-routes.ts

@@ -13,6 +13,11 @@ import type { FSRouteConfig, FSScannerConfig, ScanResult } from "./fs-types";
 import { DEFAULT_SCANNER_CONFIG } from "./fs-types";
 import { scanRoutes } from "./fs-scanner";
 import { loadManduConfig } from "../config";
+import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -41,6 +46,20 @@ export interface GenerateOptions {
 
   /** 출력 파일 경로 (지정 시 파일로 저장) */
   outputPath?: string;
+
+  /**
+   * Phase 18.τ — optional plugins + config-level hooks bundle.
+   *
+   * When provided, `generateManifest()` fires two plugin hooks:
+   *   - `onRouteRegistered(route)` — once per scanned route.
+   *   - `onManifestBuilt(manifest)` — after assembly, BEFORE the
+   *     manifest is written to disk. A plugin may return a mutated
+   *     manifest (pipe semantics across plugins).
+   *
+   * Omitted → zero overhead, identical to pre-τ behaviour.
+   */
+  plugins?: readonly ManduPlugin[];
+  configHooks?: Partial<ManduHooks>;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -244,12 +263,36 @@ export async function generateManifest(
   }
 
   // FS Routes 매니페스트 생성
-  const manifest = scanResultToManifest(scanResult);
+  let manifest = scanResultToManifest(scanResult);
   const warnings: string[] = [];
 
   // Auto-linking: spec/slots/, spec/contracts/ 자동 연결
   await resolveAutoLinks(manifest, rootDir);
 
+  // Phase 18.τ — fire plugin hooks AFTER auto-linking so plugins see the
+  // final RouteSpec (including slot/contract/client modules). Both hooks
+  // are opt-in; zero-overhead when `options.plugins` / `options.configHooks`
+  // are omitted.
+  const pluginArgs = {
+    plugins: options.plugins ?? [],
+    configHooks: options.configHooks,
+  };
+  if (pluginArgs.plugins.length > 0 || pluginArgs.configHooks) {
+    for (const route of manifest.routes) {
+      const { errors } = await runOnRouteRegistered(route, pluginArgs);
+      for (const e of errors) {
+        warnings.push(
+          `onRouteRegistered[${e.source}] ${route.id}: ${e.error.message}`
+        );
+      }
+    }
+    const manifestReport = await runOnManifestBuilt(manifest, pluginArgs);
+    manifest = manifestReport.result;
+    for (const e of manifestReport.errors) {
+      warnings.push(`onManifestBuilt[${e.source}]: ${e.error.message}`);
+    }
+  }
+
   // 기존 매니페스트에서 사용자 설정 필드 보존 (clientModule, hydration 등)
   const outputPath = options.outputPath ?? ".mandu/routes.manifest.json";
   const outputFullPath = join(rootDir, outputPath);
@@ -272,6 +315,26 @@ export async function generateManifest(
         if (prev.hydration && !route.hydration) {
           route.hydration = prev.hydration;
         }
+        // Issue #214 — preserve prerender-time fields (`dynamicParams`,
+        // `staticParams`) across manifest rescans. `mandu build`'s prerender
+        // phase stamps these onto the manifest; a subsequent `mandu dev`
+        // rescan must not wipe them out.
+        if (route.kind === "page" && prev.kind === "page") {
+          const prevPage = prev as typeof prev & {
+            dynamicParams?: boolean;
+            staticParams?: unknown[];
+          };
+          const routePage = route as typeof route & {
+            dynamicParams?: boolean;
+            staticParams?: unknown[];
+          };
+          if (prevPage.dynamicParams !== undefined && routePage.dynamicParams === undefined) {
+            routePage.dynamicParams = prevPage.dynamicParams;
+          }
+          if (prevPage.staticParams !== undefined && routePage.staticParams === undefined) {
+            routePage.staticParams = prevPage.staticParams;
+          }
+        }
       }
     }
   } catch {

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";
@@ -531,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.
    *
@@ -3404,6 +3412,57 @@ function stripLocaleForRedirectCheck(
 }
 // ─── 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,
@@ -3707,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;
@@ -3860,6 +3977,8 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     scheduler: schedulerOption,
     i18n: i18nOption,
     messages: messagesOption,
+    plugins: pluginsOption,
+    configHooks: configHooksOption,
   } = options;
 
   // Phase 18.μ — validate i18n + messages shape. Both are branded via
@@ -3881,6 +4000,18 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   // 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)

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,