@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/src/server/default-status-page.ts

@@ -0,0 +1,127 @@
+/**
+ * Framework default status page — the terminal fallback of the deny chain.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every 4xx/5xx chain in a
+ * "framework default page". Before TIM-1258 that terminal did not exist: an app
+ * with no `404.tsx` / `4xx.tsx` / `error.tsx` got `Response(null, { status })` —
+ * a correct status code with an empty body. Browsers render that as a blank
+ * page, and static generation had nothing to write to `404.html`.
+ *
+ * This page is a plain HTML string rather than a React component on purpose:
+ * it is the *last* fallback, so it must not depend on the RSC → SSR pipeline
+ * (the machinery that may already have failed by the time we get here), and it
+ * must be renderable from the static build where no render environment exists.
+ * One builder is the single source of truth for both surfaces.
+ *
+ * Security: the page interpolates nothing but the status code, and the code is
+ * clamped to a plain integer before it reaches the markup. No request URL, no
+ * error message, no stack — see design/13-security.md principle 4.
+ */
+
+/**
+ * Canonical reason phrases (RFC 9110 §15) for the statuses an app is likely to
+ * `deny()` with. Anything else falls back to a generic category phrase — the
+ * phrase is decoration, never a place to echo caller-supplied text.
+ */
+const REASON_PHRASES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  413: 'Content Too Large',
+  415: 'Unsupported Media Type',
+  418: "I'm a Teapot",
+  422: 'Unprocessable Content',
+  429: 'Too Many Requests',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/** HTML content type used for every framework default page response. */
+export const DEFAULT_STATUS_PAGE_CONTENT_TYPE = 'text/html; charset=utf-8';
+
+/**
+ * Coerce a status into something safe to put in markup.
+ *
+ * `DenySignal.status` is typed `number` but nothing validates it at
+ * construction, and JS callers can hand us anything. Rather than escaping a
+ * value that should never have been a string, collapse non-integers to 500 —
+ * the page is decoration for a status already on the wire.
+ */
+function displayStatus(status: number): number {
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+}
+
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export function statusReasonPhrase(status: number): string {
+  const code = displayStatus(status);
+  if (REASON_PHRASES[code]) return REASON_PHRASES[code];
+  return code >= 500 ? 'Server Error' : 'Request Error';
+}
+
+/**
+ * Build the framework default page for a status code as a full HTML document.
+ *
+ * The document is self-contained: no scripts, no external resources, no client
+ * JavaScript. It renders identically in `server` mode, in `static` mode's
+ * generated `404.html`, and with `clientJavascript: false`.
+ */
+export function defaultStatusPageHtml(status: number): string {
+  const code = displayStatus(status);
+  const phrase = statusReasonPhrase(code);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${code} ${phrase}</title>
+<style>
+:root { color-scheme: light dark; --fg: #1a1a1a; --muted: #6b6b76; --bg: #ffffff; }
+@media (prefers-color-scheme: dark) { :root { --fg: #ededf1; --muted: #9b9baa; --bg: #111114; } }
+html, body { height: 100%; margin: 0; }
+body {
+  display: flex; align-items: center; justify-content: center;
+  background: var(--bg); color: var(--fg);
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  text-align: center; padding: 2rem;
+}
+h1 { font-size: 3rem; font-weight: 600; margin: 0; letter-spacing: -0.02em; }
+p { margin: 0.5rem 0 0; color: var(--muted); font-size: 1rem; }
+</style>
+</head>
+<body>
+<main>
+<h1>${code}</h1>
+<p>${phrase}</p>
+</main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Build the framework default page as an HTTP `Response`.
+ *
+ * `responseHeaders` carries whatever middleware/proxy already set (cookies,
+ * cache directives); the content type is overwritten because the body is
+ * always HTML regardless of what the route would have produced.
+ *
+ * The body is unconditional. HEAD is not this function's problem: the pipeline
+ * strips HEAD bodies at its single exit for every response shape, so a
+ * `method` parameter here would be one renderer's private copy of a rule that
+ * now holds framework-wide (TIM-1324).
+ */
+export function defaultStatusPageResponse(status: number, responseHeaders: Headers): Response {
+  responseHeaders.set('content-type', DEFAULT_STATUS_PAGE_CONTENT_TYPE);
+  return new Response(defaultStatusPageHtml(status), { status, headers: responseHeaders });
+}

package/src/server/deny-boundary.ts

@@ -36,7 +36,6 @@ import type { SerializableError } from '../client/error-reconstituter.js';
 import { requestContextAls } from './als-registry.js';
 import { DenySignal } from './primitives.js';
 import { loadModule } from './safe-load.js';
-import { LEGACY_FILE_TO_STATUS } from './status-code-resolver.js';
 import { withSpan } from './tracing.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
@@ -50,12 +49,11 @@ export interface DenyPageEntry {
   /** The component to render (server or client — both work). */
   component: (...args: unknown[]) => unknown;
   /**
-   * How the entry matched: a status-code file (404.tsx/4xx.tsx), a legacy
-   * compat file (not-found.tsx/forbidden.tsx/unauthorized.tsx), or the
+   * How the entry matched: a status-code file (404.tsx/4xx.tsx) or the
    * error.tsx catch-all. error.tsx entries render with their documented
    * { error, digest, reset } contract, not bare deny props. See TIM-1081.
    */
-  kind: 'status' | 'legacy' | 'error';
+  kind: 'status' | 'error';
   /** MDX files are server components — rendered with plain props, never ErrorReconstituter. */
   isMdx: boolean;
 }
@@ -69,9 +67,7 @@ export interface DenyPageEntry {
  * status-code file components in fallback order:
  * 1. Specific status files (403.tsx, 404.tsx) — exact match
  * 2. Category catch-alls (4xx.tsx) — matches any 4xx
- * 3. Legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
- *    unauthorized.tsx → 401) — exact match
- * 4. error.tsx — catches everything
+ * 3. error.tsx — catches everything
  *
  * Each segment is checked in this order. The chain is ordered so the
  * FIRST match wins at catch time. This mirrors resolveStatusFile's 4xx
@@ -127,29 +123,7 @@ export async function buildDenyPageChain(
     }
   }
 
-  // Pass 2: legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
-  // unauthorized.tsx → 401). Lower priority than status files (a root
-  // 4xx.tsx beats a leaf not-found.tsx) but higher than error.tsx — the
-  // same ordering as resolveStatusFile's resolve4xx. See TIM-1081.
-  for (let i = startIndex; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-    for (const [name, status] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      const file = segment.legacyStatusFiles[name];
-      if (!file) continue;
-      const mod = await loadModule(file).catch(() => null);
-      if (mod?.default) {
-        chain.push({
-          status,
-          component: mod.default as (...args: unknown[]) => unknown,
-          kind: 'legacy',
-          isMdx: isMdxFilePath(file.filePath),
-        });
-      }
-    }
-  }
-
-  // Pass 3: error.tsx files — lowest priority catch-all.
+  // Pass 2: error.tsx files — lowest priority catch-all.
   // Only added AFTER all status and legacy files so they never shadow a
   // more specific file from an ancestor segment.
   for (let i = startIndex; i >= 0; i--) {
@@ -202,7 +176,7 @@ export function renderMatchingDenyPage(
  * Build the element for a matched deny chain entry with the props contract
  * the file's convention documents:
  *
- * - Status-code and legacy files: { status, dangerouslyPassData }
+ * - Status-code files: { status, dangerouslyPassData }
  * - error.tsx (TSX): { error, digest, reset } via ErrorReconstituter, plus
  *   { status, dangerouslyPassData } for dual-shape implementations. Without
  *   the Error prop, any error.tsx written per the docs (reading

package/src/server/deny-renderer.ts

@@ -19,6 +19,9 @@ import { createElement, Fragment } from 'react';
 import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
+import { appVisibleSearch } from '../shared/rsc-cache-key.js';
+import { getSlotParamsForClient } from './request-context.js';
+import { withPublishedParams } from './publish-params.js';
 import { renderDenyEntry, type DenyPageEntry } from './deny-boundary.js';
 import { getCookiesForSsr } from './cookie-context.js';
 import { logRenderError } from './logger.js';
@@ -28,6 +31,8 @@ import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import { headElementsToReact } from './metadata.js';
 import { resolveStatusFile } from './status-code-resolver.js';
+import { defaultStatusPageResponse } from './default-status-page.js';
+import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import type { NavContext } from './ssr-bridge-types.js';
@@ -76,24 +81,36 @@ function isApiRoute(segments: ReadonlyArray<ManifestSegmentNode>): boolean {
 function buildDenyElement(
   deny: DenySignal,
   component: (...args: unknown[]) => unknown,
-  resolutionKind: 'exact' | 'category' | 'legacy' | 'error',
+  resolutionKind: 'exact' | 'category' | 'error',
   filePath: string
 ): React.ReactElement {
   const entry: DenyPageEntry = {
     status: deny.status,
     component,
-    kind: resolutionKind === 'error' ? 'error' : resolutionKind === 'legacy' ? 'legacy' : 'status',
+    kind: resolutionKind === 'error' ? 'error' : 'status',
     isMdx: isMdxFilePath(filePath),
   };
   return renderDenyEntry(entry, deny.status, deny.data);
 }
 
+/**
+ * Supplies a replacement for the framework default page at the end of the
+ * chain. Returning `null` keeps the framework default.
+ *
+ * The dev server uses this to substitute its route-listing 404 page. It is a
+ * parameter rather than a check on the produced Response because "the app
+ * authored no status page" is a fact about the *chain*, and inspecting the
+ * result for it (e.g. an empty body) stops being true the moment the chain
+ * grows a real terminal — which is exactly what TIM-1258 did.
+ */
+export type DefaultPageRenderer = (status: number, responseHeaders: Headers) => Response | null;
+
 /**
  * Render a status-code error page for a DenySignal.
  *
  * Resolves the appropriate status-code file from the segment chain based
- * on format preference. Returns an HTML Response (component), JSON Response,
- * or bare fallback Response.
+ * on format preference. Returns an HTML Response (component), a JSON Response,
+ * or the framework default status page.
  */
 export async function renderDenyPage(
   deny: DenySignal,
@@ -104,7 +121,8 @@ export async function renderDenyPage(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   createDebugChannelSink: DebugChannelFactory,
-  callSsr: CallSsrFn
+  callSsr: CallSsrFn,
+  defaultPage?: DefaultPageRenderer
 ): Promise<Response> {
   // API routes (route.ts) → JSON only, never render components
   if (isApiRoute(segments)) {
@@ -116,11 +134,14 @@ export async function renderDenyPage(
   // Page routes → component chain first, JSON fallback only if no component found.
   const resolution = resolveStatusFile(deny.status, segments, 'component');
 
-  // No component status file — try JSON chain before bare fallback
+  // No component status file — try JSON chain, then the framework default page.
   if (!resolution) {
     const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
     if (jsonResponse) return jsonResponse;
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   // Dev warning: JSON status file exists but is shadowed by the component chain.
@@ -137,10 +158,20 @@ export async function renderDenyPage(
     }
   }
 
-  // Load the status-code page component
-  const mod = await loadModule(resolution.file);
-  if (!mod.default) {
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  // Load the status-code page component. A file that resolved but exports no
+  // default — or whose module fails to import or evaluate — is not a usable
+  // component match: continue down the documented chain (JSON, then framework
+  // default) rather than returning an empty body or letting the loader's
+  // rejection escape request handling. Mirrors buildDenyPageChain and the
+  // error-file resolver, which both swallow the load failure.
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
+    if (jsonResponse) return jsonResponse;
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
@@ -176,7 +207,7 @@ export async function renderDenyPage(
   }
 
   // Render the error page to a fresh RSC Flight stream.
-  const rscStream = renderToReadableStream(element, {
+  const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
       logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
@@ -186,10 +217,13 @@ export async function renderDenyPage(
 
   const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
+  const slotParams = getSlotParamsForClient();
+
   const navContext: NavContext = {
     pathname: new URL(req.url).pathname,
     segmentParams: match.segmentParams,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    searchParams: Object.fromEntries(appVisibleSearch(new URL(req.url)).params),
+    slotParams,
     statusCode: deny.status,
     responseHeaders,
     headHtml: flightInitScript(),
@@ -199,7 +233,32 @@ export async function renderDenyPage(
     cookies: getCookiesForSsr(),
   };
 
-  return callSsr(ssrStream, navContext);
+  try {
+    // `await` inside the try on purpose — see the same note in
+    // rsc-entry/error-renderer.ts. A status page that crashes during SSR
+    // ends in the framework default page, not a blank body: the pipeline's
+    // own deny fallback catches this and can only produce an empty response,
+    // and a crashing 404.tsx is exactly when the reader has nothing else to
+    // go on (TIM-1258).
+    return await callSsr(ssrStream, navContext);
+  } catch (renderError) {
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: renderError });
+    return defaultStatusPageResponse(deny.status, responseHeaders);
+  }
+}
+
+/**
+ * Terminal fallback for a client-navigation deny with no status-code file.
+ *
+ * The HTML path answers this case with the framework default page, but a
+ * client-navigation response cannot carry HTML — the Flight decoder would
+ * choke on it. Emit the hard-navigate envelope instead: the client abandons
+ * SPA navigation and the resulting document request renders that same default
+ * page. Before TIM-1258 this returned an empty Flight body, which the decoder
+ * hit as a malformed stream.
+ */
+function denyHardNavigateResponse(status: number, responseHeaders: Headers): Response {
+  return rscErrorEnvelope(status, responseHeaders);
 }
 
 /**
@@ -219,14 +278,12 @@ export async function renderDenyPageAsRsc(
   const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   if (!resolution) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
-  const mod = await loadModule(resolution.file);
-  if (!mod.default) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
@@ -247,7 +304,7 @@ export async function renderDenyPageAsRsc(
     element = h(component, null, element);
   }
 
-  const rscStream = renderToReadableStream(element, {
+  const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
       console.error('[timber] Error page RSC render error:', error);
@@ -286,7 +343,11 @@ async function renderDenyPageJson(
   // JSON status files are loaded as modules that export the JSON content.
   // The manifest's load() imports the .json file, which Vite handles as a
   // default export of the parsed JSON object.
-  const mod = await loadModule(resolution.file);
+  // A .json status file that fails to load is not a usable match — return
+  // null so the caller continues to the framework default rather than
+  // rejecting out of the chain.
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod) return null;
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');

package/src/server/head-response.ts

@@ -0,0 +1,54 @@
+/**
+ * HEAD body stripping — RFC 9110 §9.3.2.
+ *
+ * "The HEAD method is identical to GET except that the server MUST NOT send
+ * content in the response." The headers, however, must be the ones the
+ * corresponding GET would have produced — which is why timber renders the
+ * route in full and discards the body here rather than short-circuiting the
+ * render. Content-Type, Content-Length, Set-Cookie, cache directives and
+ * everything else ride through untouched.
+ *
+ * Node's `ServerResponse` happens to discard writes for HEAD, so the wire is
+ * usually correct even without this. That is a property of one adapter, not of
+ * the `Response` object: static generation, the Cloudflare and Nitro adapters,
+ * tests, and anything calling the pipeline handler as a function all observe
+ * the `Response` directly and saw the full body before TIM-1324.
+ *
+ * The pipeline applies this at its single exit so every response shape is
+ * covered — page render, API route, metadata route, deny page, error page,
+ * proxy short-circuit. The two unit-level producers that are also reachable as
+ * standalone functions (`handleRouteRequest`, `handleApiRoute`) call it too, so
+ * each honours HEAD on its own; they share this implementation rather than
+ * repeating it, and applying it twice is a no-op.
+ */
+
+/**
+ * Return a bodyless copy of `response` when `method` is HEAD.
+ *
+ * A no-op for every other method and for responses that already carry no body
+ * (204, 304, redirects), so callers do not need to pre-check either.
+ *
+ * The discarded stream is cancelled: an SSR render that reached this point has
+ * a live producer attached, and dropping the reference without cancelling
+ * leaks it for the lifetime of the render (design/13-security.md A4).
+ */
+export function stripHeadBody(response: Response, method: string): Response {
+  if (method.toUpperCase() !== 'HEAD') return response;
+  const body = response.body;
+  if (body === null) return response;
+
+  // `cancel()` rejects if the stream is already errored and throws
+  // synchronously if it is locked — neither is actionable here, the body is
+  // being discarded either way.
+  try {
+    body.cancel().catch(() => {});
+  } catch {
+    /* stream already locked or disturbed */
+  }
+
+  return new Response(null, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/src/server/param-coercion.ts

@@ -13,9 +13,11 @@
  */
 
 import type { Codec } from '../codec.js';
+import type { SegmentType } from '../routing/types.js';
+import { effectiveUrlSegment } from '../routing/segment-classify.js';
 import { toBracketKey } from '../params/resolve-schema.js';
 import type { RouteMatch } from './pipeline.js';
-import { sanitizeParamValue } from './pipeline-helpers.js';
+import { normalizeParamValue } from '../shared/param-value.js';
 import { loadModule } from './safe-load.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { isDebug } from './debug.js';
@@ -44,6 +46,12 @@ export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | n
  * exists, the raw value is parsed through it. If no codec exists or no
  * global codecs are registered, the raw value passes through unchanged.
  *
+ * Segments are read through `effectiveUrlSegment` because an intercepting
+ * node's own `segmentType` is `'intercepting'` and its `paramName` is unset
+ * — the param it binds lives in the intercepted name (`(.)[id]` → `[id]`).
+ * The slot resolver matches through the same helper, so the key a param is
+ * coerced under is always the key it was matched under (TIM-1281).
+ *
  * Unlike main route coercion, this does NOT throw ParamCoercionError on
  * failure — slots degrade gracefully. A failed coercion logs a warning
  * in dev mode and keeps the raw value.
@@ -51,7 +59,12 @@ export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | n
  * @internal — framework use only
  */
 export function coerceSlotParams(
-  slotChain: Array<{ segmentType: string; paramName?: string }>,
+  slotChain: Array<{
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    interceptedSegmentName?: string;
+  }>,
   rawParams: Record<string, string | string[]>
 ): Record<string, string | string[]> {
   const globalCodecs = _globalCodecs;
@@ -62,7 +75,8 @@ export function coerceSlotParams(
     result[key] = rawParams[key];
   }
 
-  for (const segment of slotChain) {
+  for (const node of slotChain) {
+    const segment = effectiveUrlSegment(node);
     if (!segment.paramName) continue;
     const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
     const codec = globalCodecs[bracketKey];
@@ -71,10 +85,9 @@ export function coerceSlotParams(
     const key = segment.paramName;
     if (!(key in result)) continue;
 
+    let parsed: unknown;
     try {
-      result[key] = sanitizeParamValue(codec.parse(result[key] as string | string[])) as
-        | string
-        | string[];
+      parsed = codec.parse(result[key] as string | string[]);
     } catch (err) {
       // Slot param coercion failures are non-fatal — keep the raw value.
       // The main route already validated the URL; the slot just interprets
@@ -88,7 +101,9 @@ export function coerceSlotParams(
             `  Keeping raw value.`
         );
       }
+      continue;
     }
+    result[key] = normalizeParamValue(parsed, key) as string | string[];
   }
 
   return result as Record<string, string | string[]>;
@@ -125,7 +140,17 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   // by bracket name (e.g. '[id]', '[...slug]') to avoid collisions between
   // distinct segment types that share a param name.
   if (globalCodecs) {
-    for (const segment of match.segments) {
+    for (const node of match.segments) {
+      // Read through `effectiveUrlSegment` for the same reason
+      // `coerceSlotParams` does: an intercepting node's own `segmentType` is
+      // 'intercepting' and its `paramName` is unset — the param it binds lives
+      // in the intercepted name (`(.)[id]` → `[id]`). Until TIM-1280 an
+      // intercepting node could only appear in a *slot* chain, so only that
+      // path needed it; a children-path interception puts one in the main
+      // chain, and reading the node directly would silently skip coercion for
+      // exactly the param the intercepting directory declares — so the swapped
+      // route and the canonical one would disagree about the param's type.
+      const segment = effectiveUrlSegment(node);
       if (!segment.paramName) continue;
       const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
       const codec = globalCodecs[bracketKey];
@@ -133,8 +158,9 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
 
       const key = segment.paramName;
       if (!(key in mergeTarget)) continue;
+      let parsed: unknown;
       try {
-        mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key] as string | string[]));
+        parsed = codec.parse(mergeTarget[key] as string | string[]);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (isDebug()) {
@@ -147,6 +173,10 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
         }
         throw new ParamCoercionError(message);
       }
+      // Outside the catch: a codec that rejects a URL value is a 404, a codec
+      // that returns an unrepresentable one is a bug in the app. Normalizing
+      // inside would report the second as the first.
+      mergeTarget[key] = normalizeParamValue(parsed, key);
     }
     return;
   }
@@ -177,17 +207,9 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
 
     if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
 
+    let coerced: Record<string, unknown>;
     try {
-      const coerced = segmentParamsDef.parse(match.segmentParams);
-
-      // Deep-sanitize codec output: every nested plain object becomes
-      // null-prototype with dangerous keys stripped at every depth.
-      // See TIM-873, design/13-security.md
-      for (const key of Object.keys(coerced as Record<string, unknown>)) {
-        if (key !== '__proto__') {
-          mergeTarget[key] = sanitizeParamValue((coerced as Record<string, unknown>)[key]);
-        }
-      }
+      coerced = segmentParamsDef.parse(match.segmentParams) as Record<string, unknown>;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       if (isDebug()) {
@@ -203,5 +225,13 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
       }
       throw new ParamCoercionError(message);
     }
+
+    // Normalize outside the catch, for the same reason as above. `__proto__`
+    // is skipped here as well as inside `normalizeParamValue`, because this
+    // loop assigns into `mergeTarget` directly.
+    for (const key of Object.keys(coerced)) {
+      if (key === '__proto__') continue;
+      mergeTarget[key] = normalizeParamValue(coerced[key], key);
+    }
   }
 }

package/src/server/pipeline-helpers.ts

@@ -18,51 +18,6 @@ import type { ProxyConfig } from './pipeline.js';
 
 // ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
 
-/**
- * Only __proto__ needs stripping — it has a language-level setter that
- * changes the prototype chain of spread copies. constructor and prototype
- * are harmless own properties on null-prototype objects.
- */
-const DANGEROUS_KEYS = new Set(['__proto__']);
-
-/**
- * Deep-walk a value returned by a segment param codec, producing a
- * sanitized copy where every plain object is null-prototype and
- * dangerous keys (__proto__, constructor, prototype) are stripped at
- * every depth.
- *
- * Non-plain objects (Date, Map, class instances, etc.) are returned
- * as-is — they cannot be poisoned by `{...x}` spread and may carry
- * author-intended prototype methods.
- *
- * Arrays are walked element-wise.
- *
- * Performance: URL params are bounded by URL length (~8 KB). Realistic
- * trees are <1 KB. The recursive walk is sub-microsecond.
- *
- * See TIM-655, TIM-855, TIM-873, design/13-security.md
- */
-export function sanitizeParamValue(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-
-  if (Array.isArray(value)) {
-    return value.map(sanitizeParamValue);
-  }
-
-  // Only walk plain objects — anything with a custom prototype (Date, Map,
-  // class instances) is left untouched.
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== Object.prototype && proto !== null) return value;
-
-  const out: Record<string, unknown> = Object.create(null);
-  for (const key of Object.keys(value as Record<string, unknown>)) {
-    if (!DANGEROUS_KEYS.has(key)) {
-      out[key] = sanitizeParamValue((value as Record<string, unknown>)[key]);
-    }
-  }
-  return out;
-}
-
 // ─── Proxy Resolver ────────────────────────────────────────────────────────
 
 /**