@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/dist/server/internal.js

@@ -1,11 +1,17 @@
-import { a as classifyMetadataRoute, i as METADATA_ROUTE_CONVENTIONS, o as getMetadataRouteAutoLink, r as canonicalize, s as getMetadataRouteServePath } from "../_chunks/canonicalize-DQHyFClh.js";
-import { n as classifyUrlSegment } from "../_chunks/segment-classify-Byy425ng.js";
-import { $ as timingAls, A as setMatchedSegmentPath, C as applyRequestHeaderOverlay, D as getSegmentParams, E as getSearchParams, F as getSetCookieHeaders, G as replaceTraceId, H as getOtelTraceId, I as getWaitUntil, J as withSpan, K as runWithTraceId, L as isDebug, M as setSegmentParams, N as getCookie, O as markResponseFlushed, V as generateTraceId, W as getTraceId, Y as earlyHintsSenderAls, Z as requestContextAls, _ as RedirectSignal, a as logProxyError, c as logRequestReceived, d as logSwrRefetchFailed, f as logWaitUntilRejected, g as DenySignal, h as swallow, i as logMiddlewareShortCircuit, j as setMutableCookieContext, k as runWithRequestContext, l as logRouteError, m as setLogger, n as logCacheMiss, o as logRenderError, p as logWaitUntilUnsupported, q as setSpanAttribute, r as logMiddlewareError, s as logRequestCompleted, t as getLogger, u as logSlowRequest, v as RenderError, w as getHeader } from "../_chunks/logger-AWfuX-KJ.js";
-import { i as coerce, t as executeAction } from "../_chunks/actions-O_LsyCE4.js";
-import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as createSingleflight, y as lastInvalidationEpochFor } from "../_chunks/cache-api-B-lhk9p4.js";
-import "../client/error-boundary.js";
-import { n as toBracketKey } from "../_chunks/resolve-schema-Dz3fcFUo.js";
-import "../_chunks/segment-context-ZDnXDkbz.js";
+import { n as isRscRequest } from "../_chunks/rsc-media-type-DRqE_lD_.js";
+import { a as canonicalize, c as getMetadataRouteAutoLink, l as getMetadataRouteServePath, o as METADATA_ROUTE_CONVENTIONS, s as classifyMetadataRoute, t as computeSegmentTreePaths } from "../_chunks/segment-keys-BawYuNFO.js";
+import { n as classifyUrlSegment, r as effectiveUrlSegment } from "../_chunks/segment-classify-C539Pa2O.js";
+import { a as timingAls, r as requestContextAls, t as earlyHintsSenderAls } from "../_chunks/als-registry-C6kcfprT.js";
+import { A as setMatchedSegmentPath, C as applyRequestHeaderOverlay, D as getSegmentParams, E as getSearchParams, F as getSetCookieHeaders, G as replaceTraceId, H as getOtelTraceId, I as getWaitUntil, J as withSpan, K as runWithTraceId, L as isDebug, M as setSegmentParams, N as getCookie, O as markResponseFlushed, V as generateTraceId, W as getTraceId, _ as RedirectSignal, a as logProxyError, c as logRequestReceived, d as logSwrRefetchFailed, f as logWaitUntilRejected, g as DenySignal, h as swallow, i as logMiddlewareShortCircuit, j as setMutableCookieContext, k as runWithRequestContext, l as logRouteError, m as setLogger, n as logCacheMiss, o as logRenderError, p as logWaitUntilUnsupported, q as setSpanAttribute, r as logMiddlewareError, s as logRequestCompleted, t as getLogger, u as logSlowRequest, v as RenderError, w as getHeader } from "../_chunks/logger-D8xJZXIN.js";
+import { i as isRscCacheKeyShape, n as RSC_KEY_PARAM, s as rscCacheKey, t as RSC_KEY_HEADERS } from "../_chunks/rsc-cache-key-DD0fl_-s.js";
+import { t as isMdxFilePath } from "../_chunks/mdx-file-C005ay-P.js";
+import { i as collectRouteModulepreloads, n as collectRouteCss, r as collectRouteFonts } from "../_chunks/build-manifest-DWppEdLB.js";
+import { i as coerce, t as executeAction } from "../_chunks/actions-35jnMdeJ.js";
+import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as createSingleflight, y as lastInvalidationEpochFor } from "../_chunks/cache-api-DjNrIWRR.js";
+import "../_chunks/error-boundary-D-ODYX41.js";
+import { n as toBracketKey } from "../_chunks/resolve-schema-5ma5pp1b.js";
+import { r as normalizeParamValue } from "../_chunks/segment-context-CjOlyB8Y.js";
+import { n as rscErrorEnvelope } from "../_chunks/rsc-error-envelope-tT5PJs4q.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import React, { createElement, useContext } from "react";
@@ -209,38 +215,6 @@ function hasOnRequestError() {
 //#endregion
 //#region src/server/pipeline-helpers.ts
 /**
-* 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.
-*/
-var DANGEROUS_KEYS = /* @__PURE__ */ 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
-*/
-function sanitizeParamValue(value) {
-	if (value === null || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(sanitizeParamValue);
-	const proto = Object.getPrototypeOf(value);
-	if (proto !== Object.prototype && proto !== null) return value;
-	const out = Object.create(null);
-	for (const key of Object.keys(value)) if (!DANGEROUS_KEYS.has(key)) out[key] = sanitizeParamValue(value[key]);
-	return out;
-}
-/**
 * Build a proxy resolver closure from the declared source. Called exactly
 * once at `createPipeline` setup time, so the hot path sees only the branch
 * that corresponds to this pipeline's configured variant.
@@ -315,7 +289,7 @@ function cloneWithMutableHeaders(response) {
 * createFromFetch. See design/19-client-navigation.md.
 */
 function buildRedirectResponse(signal, req, headers) {
-	if ((req.headers.get("Accept") ?? "").includes("text/x-component")) {
+	if (isRscRequest(req)) {
 		headers.set("X-Timber-Redirect", signal.location);
 		return new Response(null, {
 			status: 204,
@@ -1164,6 +1138,42 @@ async function loadModule(loader) {
 	}
 }
 //#endregion
+//#region src/server/utils/element-type.ts
+var REACT_COMPONENT_TYPE_MARKERS = /* @__PURE__ */ new Set([
+	Symbol.for("react.forward_ref"),
+	Symbol.for("react.memo"),
+	Symbol.for("react.lazy"),
+	Symbol.for("react.provider"),
+	Symbol.for("react.context"),
+	Symbol.for("react.suspense"),
+	Symbol.for("react.suspense_list"),
+	Symbol.for("react.client.reference")
+]);
+/**
+* Validate that a loaded module's `default` export is something React
+* accepts as the first argument to `createElement` — i.e. a valid component
+* type. React doesn't export `isValidElementType` (only `isValidElement`,
+* which checks for *elements*, not *component types*), so this mirrors
+* React's internal check:
+*
+*   - functions  → function or class components
+*   - objects with a `$$typeof` matching one of React's known component
+*     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+*     suspense, client references via `@vitejs/plugin-rsc`)
+*
+* Strings (HTML tag names) are valid for `createElement` but never appear
+* as a route module's default export, so they're not recognized here.
+*
+* Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+* the boundary wrapper is skipped rather than crashing inside React.
+*/
+function isValidElementType(value) {
+	if (typeof value === "function") return true;
+	if (typeof value !== "object" || value === null) return false;
+	const marker = value.$$typeof;
+	return typeof marker === "symbol" && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}
+//#endregion
 //#region src/server/deny-boundary.ts
 /**
 * Deny boundary subsystem — the in-tree DenySignal flow.
@@ -1175,10 +1185,14 @@ async function loadModule(loader) {
 *    `DenyPageEntry` records ordered by specificity (specific status →
 *    category catch-all → `error.tsx`).
 *
-* 2. **Runtime matching** (`renderMatchingDenyPage`) — picks the first
-*    chain entry whose status filter matches the thrown DenySignal and
-*    returns a React element for the matching component. Used by
-*    `AccessGate` and `PageDenyBoundary` when they catch a deny.
+* 2. **Runtime matching and placement** (`matchDenyEntry`, `placeDenyPage`,
+*    `handleCaughtDeny`) — picks the first chain entry whose status filter
+*    matches the thrown DenySignal, then decides whether the catch site may
+*    render it where it stands. A chain spans the catcher outward to root,
+*    so a match may belong to an ancestor segment; rendering it in place
+*    would wrap it in every layout in between. Ancestor-owned matches are
+*    re-thrown with `ownerKey` stamped on the signal so the error boundary
+*    at the owning segment renders it. See TIM-1356.
 *
 * 3. **The page boundary itself** (`PageDenyBoundary`) — the async server
 *    component that wraps a server-component page, calls it, and catches
@@ -1196,19 +1210,86 @@ async function loadModule(loader) {
 * See design/04-authorization.md, design/10-error-handling.md, TIM-666.
 */
 /**
-* Find the first deny page in the chain that matches the given status code.
-* Returns a React element for the matching component, or null if no match.
+* Find the first deny page in the chain whose status filter matches.
+* Returns null when nothing in the chain accepts this status.
+*
+* For 4xx statuses, the chain's stored order is correct: every status file
+* across all segments (inner→outer) before any error.tsx — so a root
+* `404.tsx` beats a leaf `error.tsx`. This matches `resolve4xx`.
+*
+* For 5xx statuses, the match walks per-segment (inner→outer): at each
+* segment, status files (`503.tsx` → `5xx.tsx`) then `error.tsx`, before
+* moving to the next segment outward. A leaf `error.tsx` therefore beats a
+* root `5xx.tsx` — the intentional inverse of the 4xx chain, matching
+* `resolve5xx`. See TIM-1360.
 */
-function renderMatchingDenyPage(chain, status, data) {
+function matchDenyEntry(chain, status) {
+	if (status >= 500) return matchDenyEntry5xx(chain, status);
 	for (const entry of chain) {
-		if (entry.status === status) return renderDenyEntry(entry, status, data);
-		if (entry.status === 400 && status >= 400 && status <= 499) return renderDenyEntry(entry, status, data);
-		if (entry.status === 500 && status >= 500 && status <= 599) return renderDenyEntry(entry, status, data);
-		if (entry.status === null) return renderDenyEntry(entry, status, data);
+		if (entry.status === status) return entry;
+		if (entry.status === 400 && status >= 400 && status <= 499) return entry;
+		if (entry.status === null) return entry;
 	}
 	return null;
 }
 /**
+* 5xx per-segment walk: at each segment (inner→outer), check status files
+* then error.tsx before moving outward. Mirrors `resolve5xx`.
+*/
+function matchDenyEntry5xx(chain, status) {
+	const segmentIndices = [];
+	for (const entry of chain) if (!segmentIndices.includes(entry.segmentIndex)) segmentIndices.push(entry.segmentIndex);
+	segmentIndices.sort((a, b) => b - a);
+	for (const seg of segmentIndices) {
+		for (const entry of chain) {
+			if (entry.segmentIndex !== seg || entry.kind === "error") continue;
+			if (entry.status === status) return entry;
+			if (entry.status === 500 && status >= 500 && status <= 599) return entry;
+		}
+		for (const entry of chain) {
+			if (entry.segmentIndex !== seg || entry.kind !== "error") continue;
+			return entry;
+		}
+	}
+	return null;
+}
+/**
+* Decide where the deny page for `status` renders, from the perspective of
+* the catch site at `selfKey`.
+*
+* The match itself is unchanged — first entry in fallback order wins, so
+* every path picks the same file. What this adds is the position: a chain
+* built at segment i spans i outward to root, so a matched entry is owned
+* either by the catcher or by one of its ancestors.
+*
+* - Owned by the catcher → `render`. The catcher already sits at the
+*   owning segment's position.
+* - Owned by an ancestor → `hoist`. Rendering here would wrap the deny page
+*   in every layout between the owner and the catcher. The caller re-throws
+*   with `ownerKey` stamped on the signal so the boundary at that segment
+*   renders it instead — inside the owner's layout, outside the rest.
+*
+* Returns null when no entry matches; the caller re-throws unannotated and
+* the re-render fallback resolves it.
+*
+* See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+*/
+function placeDenyPage(chain, status, data, selfKey) {
+	const entry = matchDenyEntry(chain, status);
+	if (!entry) return null;
+	if (entry.ownerKey !== selfKey) {
+		if (entry.isMdx) return null;
+		return {
+			kind: "hoist",
+			ownerKey: entry.ownerKey
+		};
+	}
+	return {
+		kind: "render",
+		element: renderDenyEntry(entry, status, data)
+	};
+}
+/**
 * Build the element for a matched deny chain entry with the props contract
 * the file's convention documents:
 *
@@ -1239,6 +1320,37 @@ function renderDenyEntry(entry, status, data) {
 	});
 }
 /**
+* The whole of what an in-tree catch site does with a `DenySignal`, shared
+* by all three of them (`PageDenyBoundary`, `TracedLayout`, `AccessGate`).
+*
+* Returns the deny page element when this catch site owns the matched file.
+* Otherwise it throws — annotated with `ownerKey` when an ancestor owns the
+* file, bare when nothing matched at all.
+*
+* `setDenyStatus` runs on the hoist path too, and must run *before* the
+* throw: on the RSC payload path no boundary executes server-side, so the
+* ALS status is the only thing standing between the response and a 200
+* (`rsc-payload.ts` reads it after the stream settles).
+*
+* Either branch leaves part of the matched chain unmounted — hoisting sends
+* the render to a boundary that discards everything below it, and a layout
+* that denies returns the deny page instead of its own child outlet. What the
+* response then says about the tree is decided from the deny status alone in
+* `rsc-payload.ts`, not tracked here; see the note there for why.
+*/
+function handleCaughtDeny(chain, error, selfKey) {
+	const placement = chain ? placeDenyPage(chain, error.status, error.data, selfKey) : null;
+	if (placement?.kind === "render") {
+		setDenyStatus(error.status);
+		return placement.element;
+	}
+	if (placement?.kind === "hoist") {
+		setDenyStatus(error.status);
+		error.ownerKey = placement.ownerKey;
+	}
+	throw error;
+}
+/**
 * Set the deny status in the request context ALS.
 * Called from AccessGate / PageDenyBoundary when a DenySignal is caught.
 * The pipeline reads this after render to set the HTTP status code.
@@ -1250,6 +1362,17 @@ function setDenyStatus(status) {
 		store.onDenyStatus?.();
 	}
 }
+/**
+* Record the first denied segment index in the request context ALS.
+* Called from AccessGate when a DenySignal is caught during render.
+* Only the first (shallowest) denial is recorded — deeper denials are
+* unreachable because the gate short-circuits the subtree.
+* See TIM-1363.
+*/
+function setFirstDeniedSegmentIndex(index) {
+	const store = requestContextAls.getStore();
+	if (store && store._firstDeniedSegmentIndex === void 0) store._firstDeniedSegmentIndex = index;
+}
 //#endregion
 //#region src/server/access-gate.tsx
 /**
@@ -1269,37 +1392,37 @@ function setDenyStatus(status) {
 /**
 * Framework-injected access gate for segments.
 *
-* When a pre-computed `verdict` prop is provided (from the pre-render pass
-* in route-element-builder.ts), AccessGate replays it synchronously — no
-* async, no re-execution of access.ts, immune to Suspense timing. The OTEL
-* span was already emitted during the pre-render pass.
-*
-* When no verdict is provided (backward compat with tree-builder.ts),
-* AccessGate calls accessFn directly with OTEL instrumentation.
+* Calls accessFn during render — inside `renderToReadableStream`, sharing
+* the same `React.cache` scope as layouts and pages. A `requireUser()`
+* call in access.ts populates the cache; the same call in any layout is
+* a free hit. Access executes exactly once per request. See TIM-1363.
 *
 * access.ts is a pure gate — return values are discarded. The layout below
 * gets the same data by calling the same cached functions (React.cache dedup).
+*
+* On denial the gate renders the matching deny page only when this segment
+* owns it. Because the gate is wrapped OUTSIDE its own layout, that render
+* omits the denying segment's layout — deliberate, and the one place the
+* in-tree path diverges from `renderDenyPage`'s inclusive slice: a layout
+* whose access.ts denied must never run and serialize protected data into
+* the Flight stream (TIM-1074). An ancestor-owned page is hoisted instead,
+* because the gate also sits inside every layout above it and rendering
+* here would wrap the deny page in all of them (TIM-1356).
+*
+* For skipped segments (skippedSegment=true), deny pages are NOT rendered
+* in-tree — the client's cached layout chrome would wrap them incorrectly.
+* Instead, the deny is recorded in ALS and rethrown so the response path
+* can return rscErrorEnvelope for a client hard-navigate.
 */
 function AccessGate(props) {
-	const { accessFn, segmentName, verdict, denyPages, children } = props;
-	if (verdict !== void 0) {
-		if (verdict === "pass") return children;
-		if (verdict instanceof DenySignal && denyPages) {
-			const denyElement = renderMatchingDenyPage(denyPages, verdict.status, verdict.data);
-			if (denyElement) {
-				setDenyStatus(verdict.status);
-				return denyElement;
-			}
-		}
-		throw verdict;
-	}
-	return accessGateFallback(accessFn, segmentName, denyPages, children);
+	const { accessFn, segmentName, segmentKey, segmentIndex, denyPages, skippedSegment, onSettled, children } = props;
+	return accessGateFallback(accessFn, segmentName, segmentKey, segmentIndex, skippedSegment ? void 0 : denyPages, skippedSegment, onSettled, children);
 }
 /**
-* Async fallback for AccessGate when no pre-computed verdict is available.
-* Calls accessFn with OTEL instrumentation.
+* Calls accessFn during render with OTEL instrumentation.
+* Records the first denied segment index in ALS for post-render consumers.
 */
-async function accessGateFallback(accessFn, segmentName, denyPages, children) {
+async function accessGateFallback(accessFn, segmentName, segmentKey, segmentIndex, denyPages, skippedSegment, onSettled, children) {
 	try {
 		await withSpan("timber.access", { "timber.segment": segmentName ?? "unknown" }, async () => {
 			try {
@@ -1315,14 +1438,17 @@ async function accessGateFallback(accessFn, segmentName, denyPages, children) {
 			}
 		});
 	} catch (error) {
-		if (error instanceof DenySignal && denyPages) {
-			const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
-			if (denyElement) {
-				setDenyStatus(error.status);
-				return denyElement;
+		if (error instanceof DenySignal) {
+			if (segmentIndex !== void 0) setFirstDeniedSegmentIndex(segmentIndex);
+			if (skippedSegment) {
+				error._hardNavigate = true;
+				throw error;
 			}
+			if (denyPages) return handleCaughtDeny(denyPages, error, segmentKey);
 		}
 		throw error;
+	} finally {
+		onSettled?.();
 	}
 	return children;
 }
@@ -1744,69 +1870,248 @@ function wrapInSlotsProvider(shell, slotValues) {
 	});
 }
 //#endregion
+//#region src/server/error-boundary-wrapper.ts
+/**
+* Load a status/error file's component, or `null` if the boundary should be skipped.
+*
+* Two ways to get `null`, both deliberate:
+*   - the module fails to load (syntax error in the error page) — building an
+*     error boundary must not itself throw, so the boundary is skipped (TIM-584);
+*   - the default export is not a valid React component type, which would
+*     otherwise crash inside `createElement`.
+*/
+async function loadBoundaryComponent(file, loadModule) {
+	let mod;
+	try {
+		mod = await loadModule(file);
+	} catch {
+		return null;
+	}
+	return isValidElementType(mod?.default) ? mod.default : null;
+}
+/**
+* Wrap `element` in one error boundary rendering `Component` on failure.
+*
+* MDX status files are server components and cannot be passed as function
+* props to `TimberErrorBoundary` (a 'use client' component). They are
+* pre-rendered as elements and passed as `fallbackElement` instead. See TIM-503.
+*
+* @param status      boundary status filter — omitted entirely for `error.tsx`
+* @param fallbackProps props handed to an MDX fallback when it is pre-rendered
+*/
+function wrapInBoundary(element, Component, file, status, fallbackProps, config) {
+	const props = isMdxFilePath(file.filePath) ? {
+		fallbackElement: config.createElement(Component, fallbackProps),
+		children: element
+	} : {
+		fallbackComponent: Component,
+		children: element
+	};
+	if (status !== void 0) props.status = status;
+	if (config.segmentKey !== void 0) props.segmentKey = config.segmentKey;
+	return config.createElement(config.errorBoundaryComponent, props);
+}
+/**
+* Wrap an element in the error boundaries declared by a route segment.
+*
+* Wrapping is applied inside-out — the last wrap produces the outermost
+* boundary — so the processing order below is innermost to outermost:
+*
+* 1. Specific status files (e.g. `404.tsx`, `503.tsx`) — highest priority at runtime
+* 2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+* 3. `error.tsx` — catches anything not matched by a status file
+*
+* The order is load-bearing: it decides which boundary catches a given throw.
+*
+* See design/10-error-handling.md §"Format-Aware Fallback Chains".
+*/
+async function wrapSegmentWithErrorBoundaries(segment, element, config) {
+	const { loadModule, skipDenyBoundaries = false } = config;
+	if (segment.statusFiles) {
+		for (const [key, file] of Object.entries(segment.statusFiles)) {
+			if (key === "4xx" || key === "5xx") continue;
+			const status = parseInt(key, 10);
+			if (isNaN(status)) continue;
+			if (skipDenyBoundaries && status >= 400 && status <= 499) continue;
+			const Component = await loadBoundaryComponent(file, loadModule);
+			if (Component) element = wrapInBoundary(element, Component, file, status, { status }, config);
+		}
+		for (const [key, file] of Object.entries(segment.statusFiles)) {
+			if (key !== "4xx" && key !== "5xx") continue;
+			if (skipDenyBoundaries && key === "4xx") continue;
+			const Component = await loadBoundaryComponent(file, loadModule);
+			if (Component) element = wrapInBoundary(element, Component, file, key === "4xx" ? 400 : 500, {}, config);
+		}
+	}
+	if (segment.error) {
+		const Component = await loadBoundaryComponent(segment.error, loadModule);
+		if (Component) element = wrapInBoundary(element, Component, segment.error, void 0, {}, config);
+	}
+	return element;
+}
+//#endregion
 //#region src/server/param-coercion.ts
 /** Global schema codecs, set once at startup from virtual:timber-schema. */
 var _globalCodecs = null;
 /**
 * Run segment param coercion on the matched route's segments.
 *
-* When `globalCodecs` is provided (from app/schema.ts), uses the global
-* codec map keyed by bare param name. Otherwise falls back to loading
-* per-segment params.ts modules.
+* Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
+* design/41-global-params.md migration step 9). A route with no schema, or
+* a param the schema does not declare, keeps its raw string — which is the
+* honest type for an uninterpreted URL segment.
 *
 * Throws ParamCoercionError if any codec fails (→ 404).
 *
 * This runs BEFORE middleware, so ctx.segmentParams is already typed.
 * See design/07-routing.md §"Where Coercion Runs"
 * See design/41-global-params.md §"Pipeline Integration"
+*
+* Stays `async` with nothing to await: it is injected as a
+* `CoerceSegmentParamsFn` into the revalidation renderer and the action
+* middleware runner, both of which await it. Narrowing the return type to
+* `void` would break those contracts and remove a microtask boundary the
+* pipeline's ordering has always had, for no gain.
 */
 async function coerceSegmentParams(match) {
 	const globalCodecs = _globalCodecs;
 	const mergeTarget = Object.create(null);
 	for (const key of Object.keys(match.segmentParams)) if (key !== "__proto__") mergeTarget[key] = match.segmentParams[key];
 	match.segmentParams = mergeTarget;
-	if (globalCodecs) {
-		for (const segment of match.segments) {
-			if (!segment.paramName) continue;
-			const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
-			const codec = globalCodecs[bracketKey];
-			if (!codec) continue;
-			const key = segment.paramName;
-			if (!(key in mergeTarget)) continue;
-			try {
-				mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key]));
-			} catch (err) {
-				const message = err instanceof Error ? err.message : String(err);
-				if (isDebug()) console.warn(`[timber] Global schema codec rejected value for param "${key}"\n  Error: ${message}\n  Raw value: ${JSON.stringify(mergeTarget[key])}\n  Hint: check the codec in app/schema.ts for key '${bracketKey}'.`);
-				throw new ParamCoercionError(message);
-			}
-		}
-		return;
-	}
-	for (const segment of match.segments) {
-		if (!segment.params) continue;
-		let mod;
+	if (globalCodecs) for (const node of match.segments) {
+		const segment = effectiveUrlSegment(node);
+		if (!segment.paramName) continue;
+		const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+		const codec = globalCodecs[bracketKey];
+		if (!codec) continue;
+		const key = segment.paramName;
+		if (!(key in mergeTarget)) continue;
+		let parsed;
 		try {
-			mod = await loadModule(segment.params);
+			parsed = codec.parse(mergeTarget[key]);
 		} catch (err) {
-			const message = `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`;
-			if (isDebug()) console.warn(`[timber] Param coercion error: ${message}\n  Segment: ${segment.segmentName}\n  Params file: ${segment.params}`);
+			const message = err instanceof Error ? err.message : String(err);
+			if (isDebug()) console.warn(`[timber] Global schema codec rejected value for param "${key}"\n  Error: ${message}\n  Raw value: ${JSON.stringify(mergeTarget[key])}\n  Hint: check the codec in app/schema.ts for key '${bracketKey}'.`);
 			throw new ParamCoercionError(message);
 		}
-		const segmentParamsDef = mod.segmentParams;
-		if (!segmentParamsDef || typeof segmentParamsDef.parse !== "function") continue;
-		try {
-			const coerced = segmentParamsDef.parse(match.segmentParams);
-			for (const key of Object.keys(coerced)) if (key !== "__proto__") mergeTarget[key] = sanitizeParamValue(coerced[key]);
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			if (isDebug()) {
-				const rawKeys = Object.keys(match.segmentParams).join(", ");
-				console.warn(`[timber] Param codec rejected values for segment "${segment.segmentName}"\n  Error: ${message}\n  Available raw params: { ${rawKeys} }\n  Params file: ${segment.params}\n  Hint: this usually means a codec threw for the raw URL value.\n  Check that the regex/schema accepts the actual path segment string.`);
+		mergeTarget[key] = normalizeParamValue(parsed, key);
+	}
+}
+//#endregion
+//#region src/server/pipeline-interception.ts
+/**
+* Interception route matching for the request pipeline.
+*
+* Matches target URLs against interception rewrites to support the
+* modal route pattern (soft navigation intercepts).
+*
+* Extracted from pipeline.ts to keep files under 500 lines.
+*
+* See design/07-routing.md §"Intercepting Routes"
+*/
+/**
+* Check if an intercepting route applies for this soft navigation.
+*
+* Two conditions must hold:
+*
+* 1. The **target** pathname matches the rewrite's intercepted pattern.
+* 2. The **source** route — the page the user is navigating FROM, per the
+*    validated X-Timber-URL header — renders the segment that owns the slot
+*    holding the intercepting page (`interceptingScope`). Only then does that
+*    slot exist in the rendered tree, so only then can the intercepting page
+*    render.
+*
+* Condition 2 replaced a URL-prefix check (TIM-1279). A prefix cannot
+* distinguish a route-group-scoped interception from a genuinely root-level
+* one — route groups are invisible in `urlPath`, so both collapse to "/" and
+* the guard degenerates to always-true. Tree paths carry group identity.
+* The scope check also subsumes the old segment-boundary rule: a source route
+* under /feed-private has no "/feed" in its chain.
+*
+* A third condition lives with the caller, which owns route matching, and it
+* applies to the `'slot'` shape only: the route produced by re-matching
+* `interceptingPrefix` must pass through the scope too. Conditions 1–2 are
+* about the route the user is leaving; the slot has to exist in the tree that
+* actually renders. The `'children'` shape resolves its owner from the scope
+* directly rather than from a pathname, so it satisfies that by construction.
+*
+* `resolveSourceScopes` is a thunk so its inputs are only resolved when some
+* rewrite's pattern actually matches the target — the common case is no match
+* at all. It returns the two client-supplied answers to "what is on screen?"
+* as **separate sets, most authoritative first**: the tree paths the client
+* says it has mounted, then those of the route the departing URL matches. It
+* returns null only when neither yields anything, which is not a soft
+* navigation this can reason about.
+*
+* They are two sets rather than one union because ranking needs a chain
+* (TIM-1318). Each channel describes a single rendered chain, so within one the
+* scopes are strictly nested and the deepest is the innermost owner. Unioned
+* they are not: once a modal is open the address bar holds the *intercepted*
+* URL, so the second channel describes the canonical branch — possibly an
+* exclusive route group the client never mounted — and a deeper scope from
+* there would outrank the owner actually on screen. Trying the mounted channel
+* to exhaustion first keeps the fallback the union was there to provide while
+* ranking only within one chain.
+*
+* Returns the winning build-time rewrite, or null. Only build-time values ever
+* reach the renderer: the client-supplied header selects a rewrite but never
+* becomes a rendered route or pathname.
+*
+* The **first** matching rewrite wins, and the caller does not fall back to the
+* next one when the winner fails to resolve. That is deliberate and pre-dates
+* the two shapes: a rewrite that matched the target and the scope described the
+* author's intent, and quietly rendering some other author's interception
+* instead would be harder to explain than rendering the canonical route.
+*
+* "First" is meaningful because the list arrives **deepest scope first** —
+* `collectInterceptionRewrites` sorts it at build time, so the deepest owner a
+* single chain passes through wins and nothing here has to score (TIM-1318).
+* Tree-walk order used to decide it, which meant renaming a route group flipped
+* which modal opened. The precondition is a property of the manifest this reads
+* rather than something it can re-derive, so it is asserted at its source:
+* `tests/interception.test.ts` §"rewrite order is decided by scope depth".
+*/
+function findInterceptionMatch(targetPathname, resolveSourceScopes, rewrites) {
+	const candidates = rewrites.filter((rewrite) => pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern));
+	if (candidates.length === 0) return null;
+	const scopes = resolveSourceScopes();
+	if (!scopes) return null;
+	for (const scope of scopes) for (const rewrite of candidates) if (scope.has(rewrite.interceptingScope)) return rewrite;
+	return null;
+}
+/**
+* Check if a pathname matches a URL pattern with dynamic segments.
+*
+* Supports [param] (single segment) and [...param] (one or more segments).
+* Static segments must match exactly.
+*/
+function pathnameMatchesPattern(pathname, pattern) {
+	const pathParts = pathname === "/" ? [] : pathname.slice(1).split("/");
+	const patternParts = pattern === "/" ? [] : pattern.slice(1).split("/");
+	let pi = 0;
+	for (let i = 0; i < patternParts.length; i++) {
+		const seg = classifyUrlSegment(patternParts[i]);
+		switch (seg.kind) {
+			case "catch-all": return pi < pathParts.length;
+			case "optional-catch-all": return true;
+			case "dynamic": {
+				if (pi >= pathParts.length) return false;
+				const prefix = seg.prefix ?? "";
+				const suffix = seg.suffix ?? "";
+				const pathPart = pathParts[pi];
+				if (prefix || suffix) {
+					if (pathPart.length <= prefix.length + suffix.length || prefix && !pathPart.startsWith(prefix) || suffix && !pathPart.endsWith(suffix)) return false;
+				}
+				pi++;
+				continue;
 			}
-			throw new ParamCoercionError(message);
+			case "static":
+				if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
+				pi++;
+				continue;
 		}
 	}
+	return pi === pathParts.length;
 }
 //#endregion
 //#region src/client/segment-update-context.ts
@@ -1865,9 +2170,54 @@ getOrCreateContext();
 * See design/13-security.md §"State tree manipulation".
 */
 //#endregion
+//#region src/server/state-tree-diff.ts
+/**
+* State Tree Diffing — Server-side parsing and diffing of X-Timber-State-Tree.
+*
+* The client sends X-Timber-State-Tree on navigation requests, listing
+* the sync segments it has cached. The server diffs this against the
+* target route's segments to skip re-rendering unchanged sync layouts.
+*
+* This is a performance optimization only — NOT a security boundary.
+* All access.ts files run regardless of the state tree content.
+* A fabricated state tree can only cause extra rendering work or stale
+* layouts — never auth bypass.
+*
+* See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+* See design/13-security.md §"State tree manipulation"
+*/
+/**
+* Parse the X-Timber-State-Tree header from a request.
+*
+* Returns a Set of segment paths the client has cached (with an
+* additional `slots` property for cached slot paths), or null if
+* the header is missing, malformed, or empty. Parsing happens before
+* renderToReadableStream — not inside the React render pass.
+*
+* @returns ClientStateTree with segments and slots, or null if no valid state tree
+*/
+function parseClientStateTree(req) {
+	const header = req.headers.get("X-Timber-State-Tree");
+	if (!header) return null;
+	try {
+		const parsed = JSON.parse(header);
+		const hasSegments = Array.isArray(parsed.segments) && parsed.segments.length > 0;
+		const hasSlots = Array.isArray(parsed.slots) && parsed.slots.length > 0;
+		const hasTreePaths = Array.isArray(parsed.treePaths) && parsed.treePaths.length > 0;
+		if (!hasSegments && !hasSlots && !hasTreePaths) return null;
+		const result = new Set(hasSegments ? parsed.segments : []);
+		result.slots = hasSlots ? new Set(parsed.slots) : null;
+		result.treePaths = hasTreePaths ? new Set(parsed.treePaths) : null;
+		return result;
+	} catch (err) {
+		swallow(err, "malformed X-Timber-State-Tree header");
+		return null;
+	}
+}
+//#endregion
 //#region src/server/route-element-builder.ts
 /**
-* Thrown when a defineSegmentParams codec's parse() fails.
+* Thrown when an app/schema.ts segment-param codec's parse() fails.
 * The pipeline catches this and responds with 404.
 */
 var ParamCoercionError = class extends Error {
@@ -1942,78 +2292,6 @@ function escapeXml(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 //#endregion
-//#region src/server/pipeline-interception.ts
-/**
-* Interception route matching for the request pipeline.
-*
-* Matches target URLs against interception rewrites to support the
-* modal route pattern (soft navigation intercepts).
-*
-* Extracted from pipeline.ts to keep files under 500 lines.
-*
-* See design/07-routing.md §"Intercepting Routes"
-*/
-/**
-* Check if a pathname starts with a prefix on a segment boundary.
-*
-* Prevents /feed from matching /feed-private — the prefix must be
-* followed by '/' or be an exact match.
-*/
-function hasSegmentPrefix(pathname, prefix) {
-	if (prefix === "/") return true;
-	if (!pathname.startsWith(prefix)) return false;
-	return pathname.length === prefix.length || pathname[prefix.length] === "/";
-}
-/**
-* Check if an intercepting route applies for this soft navigation.
-*
-* Matches the target pathname against interception rewrites, constrained
-* by the source URL (X-Timber-URL header — where the user navigates FROM).
-*
-* Returns the source pathname to re-match if interception applies, or null.
-*/
-function findInterceptionMatch(targetPathname, sourceUrl, rewrites) {
-	for (const rewrite of rewrites) {
-		if (!hasSegmentPrefix(sourceUrl, rewrite.interceptingPrefix)) continue;
-		if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) return { sourcePathname: rewrite.interceptingPrefix };
-	}
-	return null;
-}
-/**
-* Check if a pathname matches a URL pattern with dynamic segments.
-*
-* Supports [param] (single segment) and [...param] (one or more segments).
-* Static segments must match exactly.
-*/
-function pathnameMatchesPattern(pathname, pattern) {
-	const pathParts = pathname === "/" ? [] : pathname.slice(1).split("/");
-	const patternParts = pattern === "/" ? [] : pattern.slice(1).split("/");
-	let pi = 0;
-	for (let i = 0; i < patternParts.length; i++) {
-		const seg = classifyUrlSegment(patternParts[i]);
-		switch (seg.kind) {
-			case "catch-all": return pi < pathParts.length;
-			case "optional-catch-all": return true;
-			case "dynamic": {
-				if (pi >= pathParts.length) return false;
-				const prefix = seg.prefix ?? "";
-				const suffix = seg.suffix ?? "";
-				const pathPart = pathParts[pi];
-				if (prefix || suffix) {
-					if (pathPart.length <= prefix.length + suffix.length || prefix && !pathPart.startsWith(prefix) || suffix && !pathPart.endsWith(suffix)) return false;
-				}
-				pi++;
-				continue;
-			}
-			case "static":
-				if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
-				pi++;
-				continue;
-		}
-	}
-	return pi === pathParts.length;
-}
-//#endregion
 //#region src/server/pipeline-outcome.ts
 /**
 * Pipeline outcome translator — converts a `PhaseOutcome` (the value
@@ -2028,16 +2306,7 @@ function pathnameMatchesPattern(pathname, pattern) {
 */
 function rscErrorResponse(isRsc, status, headers) {
 	if (!isRsc) return new Response(null, { status });
-	const h = headers ?? new Headers();
-	h.set("X-Timber-Error", "1");
-	h.set("content-type", "application/json; charset=utf-8");
-	return new Response(JSON.stringify({
-		error: true,
-		status
-	}), {
-		status,
-		headers: h
-	});
+	return rscErrorEnvelope(status, headers);
 }
 /**
 * Terminal outcome handler — converts a `PhaseOutcome` into a final
@@ -2091,7 +2360,7 @@ async function outcomeToResponse(config, outcome, ctx) {
 			});
 		}
 		case "error": {
-			const isRsc = (ctx.req.headers.get("Accept") ?? "").includes("text/x-component");
+			const isRsc = isRscRequest(ctx.req);
 			if (outcome.phase === "proxy") {
 				logProxyError({ error: outcome.error });
 				await fireOnRequestError(outcome.error, ctx.req, "proxy");
@@ -2334,15 +2603,6 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 			}
 			const handlerResult = await mod.default();
 			if (handlerResult instanceof Response) {
-				if (method === "HEAD") {
-					const headHeaders = new Headers(handlerResult.headers);
-					if (handlerResult.ok && !headHeaders.has("Cache-Control")) headHeaders.set("Cache-Control", "public, max-age=14400, must-revalidate");
-					return new Response(null, {
-						status: handlerResult.status,
-						statusText: handlerResult.statusText,
-						headers: headHeaders
-					});
-				}
 				const res = cloneWithMutableHeaders(handlerResult);
 				if (res.ok && !res.headers.has("Cache-Control")) res.headers.set("Cache-Control", "public, max-age=14400, must-revalidate");
 				return res;
@@ -2387,8 +2647,8 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 		if (config.onPipelineError && error instanceof Error) config.onPipelineError(error, "auto-sitemap");
 		return new Response(null, { status: 500 });
 	}
-	const isRscRequest = (req.headers.get("Accept") ?? "").includes("text/x-component");
-	if (isRscRequest) {
+	const isRsc = isRscRequest(req);
+	if (isRsc) {
 		if (!checkVersionSkew(req).ok) {
 			const reloadHeaders = new Headers();
 			applyReloadHeaders(reloadHeaders);
@@ -2400,14 +2660,23 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 	}
 	let match = config.matchRoute(canonicalPathname);
 	let interception;
-	if (isRscRequest && config.interceptionRewrites?.length) {
+	if (isRsc && config.interceptionRewrites?.length) {
 		const rawSourceUrl = req.headers.get("X-Timber-URL");
 		const validatedSourceUrl = rawSourceUrl ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash) : null;
 		if (validatedSourceUrl) {
-			const intercepted = findInterceptionMatch(canonicalPathname, validatedSourceUrl, config.interceptionRewrites);
-			if (intercepted) {
-				const sourceMatch = config.matchRoute(intercepted.sourcePathname);
-				if (sourceMatch) {
+			const resolveSourceScopes = () => {
+				const mounted = new Set(parseClientStateTree(req)?.treePaths ?? []);
+				const sourceRoute = config.matchRoute(validatedSourceUrl);
+				const scopes = [mounted, new Set(sourceRoute ? computeSegmentTreePaths(sourceRoute.segments) : [])].filter((scope) => scope.size > 0);
+				return scopes.length > 0 ? scopes : null;
+			};
+			const rewrite = findInterceptionMatch(canonicalPathname, resolveSourceScopes, config.interceptionRewrites);
+			if (rewrite?.mode === "children") {
+				const interceptedMatch = config.matchInterceptedRoute?.(canonicalPathname, rewrite.interceptingScope);
+				if (interceptedMatch) match = interceptedMatch;
+			} else if (rewrite) {
+				const sourceMatch = config.matchRoute(rewrite.interceptingPrefix);
+				if (sourceMatch !== null && computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope)) {
 					match = sourceMatch;
 					interception = { targetPathname: canonicalPathname };
 				}
@@ -2427,7 +2696,7 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 	responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
 	const leafSegment = match.segments[match.segments.length - 1];
 	const isApiRoute = leafSegment?.route && !leafSegment?.page;
-	if (config.earlyHints && !isRscRequest && !isApiRoute) try {
+	if (config.earlyHints && !isRsc && !isApiRoute) try {
 		await config.earlyHints(match, req, responseHeaders);
 	} catch (err) {
 		swallow(err, "early hints hook threw");
@@ -2439,7 +2708,7 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 		if (error instanceof ParamCoercionError) {
 			if (isDebug()) {
 				const segmentChain = match.segments.map((s) => s.segmentName || "/").join(" → ");
-				console.warn(`[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n  Matched segments: ${segmentChain}\n  Error: ${error.message}\n  This usually means a params.ts codec rejected the URL params.\n  Check that all fields in defineSegmentParams() are optional for params\n  that don't appear at every route depth (e.g. year, month, day).`);
+				console.warn(`[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n  Matched segments: ${segmentChain}\n  Error: ${error.message}\n  This usually means a codec in app/schema.ts rejected the URL value.\n  Check the codec for the bracket key of the segment named above.`);
 			}
 			const leafSegment = match.segments[match.segments.length - 1];
 			if (leafSegment.route && !leafSegment.page) return new Response(null, { status: 404 });
@@ -2466,6 +2735,188 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 	});
 }
 //#endregion
+//#region src/server/rsc-cache-key-guard.ts
+/**
+* Origin-side binding of the `_rsc` cache key to the request that produced
+* the response (TIM-1268).
+*
+* The key is deterministic, and deliberately so — that is what makes RSC
+* payloads cacheable. But deterministic also means *predictable*: anyone can
+* compute the key another client will request. Without this guard, a caller
+* could request `/about?_rsc=<victim's key>` while sending its own
+* `X-Timber-State-Tree`, and a shared cache that keys by URL — the exact
+* environment this feature targets — would store that variant under the
+* victim's key. Every subsequent legitimate navigation would then be served
+* a payload rendered for someone else's segment tree or deployment.
+*
+* The guard is a *storability* rule, not a rejection: if the claimed key
+* does not match the key derived from the received headers, the response
+* loses its shared-cache directives. Mismatched requests are still served
+* normally, they just cannot be stored for anyone else.
+*
+* Why not Next.js's 307 self-correction: a redirect is cacheable in its own
+* right, costs a round trip on every legitimate miss, and would make the
+* server's behaviour depend on a parameter it otherwise never reads. This
+* rule closes the same hole by making the poisoned entry unstorable at the
+* source, in the response the developer already has to opt into sharing.
+*
+* See design/19-client-navigation.md §"The `_rsc` cache key".
+*/
+/**
+* Legacy shared-cache control fields that predate RFC 9213 and so do not
+* follow the `<target>-Cache-Control` naming pattern — the one part of this
+* rule that cannot be matched by shape. `X-Accel-Expires` is nginx
+* `proxy_cache`, which gives it precedence over `Cache-Control`.
+*
+* A closed historical set, unlike the vendor `*-Cache-Control` names, which
+* keep being minted and are handled by pattern below.
+*/
+var LEGACY_CDN_CACHE_HEADERS = [
+	"Surrogate-Control",
+	"Edge-Control",
+	"X-Accel-Expires"
+];
+/**
+* Whether a response header overrides `Cache-Control` at a shared cache.
+*
+* Matched by *shape*, not by vendor name. RFC 9213 defines targeted fields
+* as `<target>-Cache-Control`, and every CDN spells its own: `CDN-`,
+* `Cloudflare-CDN-`, `Netlify-CDN-`, `Vercel-CDN-`, and whichever ships
+* next. A vendor list here is a denylist with an unbounded tail — it was
+* extended twice during review, each time by one name, which is the signal
+* that enumeration is the wrong shape. The suffix rule is total.
+*
+* `Cache-Control` itself does not match (no `-` prefix) and is replaced
+* separately.
+*/
+function isSharedCacheOverride(name) {
+	const lowered = name.toLowerCase();
+	return lowered.endsWith("-cache-control") || LEGACY_CDN_CACHE_HEADERS.some((legacy) => legacy.toLowerCase() === lowered);
+}
+/**
+* Whether the request's `_rsc` parameter matches the key derived from its
+* own headers.
+*
+* Requests without the parameter are not claiming a key at all, so they are
+* left alone — the bare document URL is the developer's declared territory
+* (see design/32-response-caching.md, TIM-1264). Neither is a parameter
+* whose value could not be one of our digests: `_rsc` is not reserved, and
+* an application that already uses it for its own search state
+* (`/search?_rsc=foo`) must not have its cache policy silently revoked by a
+* guard that mistook that for a forgery.
+*/
+async function hasValidRscCacheKey(req) {
+	if (!req.url.includes("?")) return true;
+	let values;
+	try {
+		values = new URL(req.url).searchParams.getAll(RSC_KEY_PARAM);
+	} catch {
+		return false;
+	}
+	const claims = values.filter(isRscCacheKeyShape);
+	if (claims.length === 0) return true;
+	const expected = await rscCacheKey((name) => req.headers.get(name));
+	if (expected === null) return false;
+	return claims.every((claim) => claim === expected);
+}
+/**
+* Ensure a Flight payload can never be interpreted as a document.
+*
+* Applied here, at the pipeline's single exit, rather than where each
+* payload response is built. Six places build one — the success path, three
+* in `deny-renderer.ts`, the action paths — and hardening them one at a time
+* is how you end up hardening five of six. The response is Flight if it says
+* it is; that is the only test that covers every producer, including ones
+* added later.
+*
+* Matters because the payload URL is observable and, on a shared-cache hit,
+* the origin is never consulted — so a top-level navigation can be handed
+* these bytes with no request-time check available. See design/13-security.md
+* #36c.
+*/
+function hardenRscPayloadResponse(response) {
+	const contentType = response.headers.get("content-type");
+	if (!contentType) return;
+	if (contentType.split(";")[0].trim().toLowerCase() !== "text/x-component") return;
+	response.headers.set("X-Content-Type-Options", "nosniff");
+}
+/**
+* Make a response unstorable by any shared cache when its request claimed an
+* `_rsc` key that does not match its own headers.
+*
+* The end state is unconditional and therefore statable: **a mismatched
+* response is never stored by any cache.** Every targeted cache-control
+* field is removed and `Cache-Control` is replaced outright, rather than
+* downgrading only when a shared directive is spotted. Conditional variants
+* of this were tried and were wrong twice over — they missed the CDN-
+* specific headers, and leaving `Cache-Control` alone when it looked
+* harmless lets a CDN apply heuristic caching to a response that has none.
+*
+* The cost is that a mismatched request loses developer-chosen *browser*
+* caching too. That is a request no timber client ever makes.
+*
+* Purge tags (`Surrogate-Key`, `Cache-Tag`) are deliberately left alone:
+* they address stored entries, and this response is not stored.
+*
+* Mutates `response.headers` in place; the pipeline guarantees mutable
+* headers at this point (see TIM-866).
+*/
+async function enforceRscCacheKey(req, response) {
+	if (await hasValidRscCacheKey(req)) return;
+	const overrides = [];
+	for (const name of response.headers.keys()) if (isSharedCacheOverride(name)) overrides.push(name);
+	for (const name of overrides) response.headers.delete(name);
+	response.headers.set("Cache-Control", "private, no-store");
+}
+//#endregion
+//#region src/server/head-response.ts
+/**
+* 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).
+*/
+function stripHeadBody(response, method) {
+	if (method.toUpperCase() !== "HEAD") return response;
+	const body = response.body;
+	if (body === null) return response;
+	try {
+		body.cancel().catch(() => {});
+	} catch {}
+	return new Response(null, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
+//#endregion
 //#region src/server/pipeline.ts
 /**
 * Create the request handler from a pipeline configuration.
@@ -2529,12 +2980,14 @@ function createPipeline(config) {
 						});
 						else result = await innerHandler();
 						await setSpanAttribute("http.response.status_code", result.status);
-						const varyTokens = ["Accept"];
-						if (config.interceptionRewrites?.length) varyTokens.push("X-Timber-URL");
+						const varyTokens = [...RSC_KEY_HEADERS];
 						const existingVary = result.headers.get("Vary");
 						const existingTokens = existingVary ? existingVary.toLowerCase().split(",").map((t) => t.trim()) : [];
 						const newTokens = varyTokens.filter((t) => !existingTokens.includes(t.toLowerCase()));
 						if (newTokens.length > 0) result.headers.set("Vary", existingVary ? `${existingVary}, ${newTokens.join(", ")}` : newTokens.join(", "));
+						await enforceRscCacheKey(canonicalReq, result);
+						hardenRscPayloadResponse(result);
+						result = stripHeadBody(result, method);
 						if (serverTiming === "detailed") {
 							const timingHeader = getServerTimingHeader();
 							if (timingHeader) result.headers.set("Server-Timing", timingHeader);
@@ -2576,68 +3029,6 @@ function createPipeline(config) {
 	return pipelineFn;
 }
 //#endregion
-//#region src/server/build-manifest.ts
-/**
-* Collect all CSS files needed for a matched route's segment chain.
-*
-* Walks segments root → leaf, collecting CSS for each layout and page.
-* Deduplicates while preserving order (root layout CSS first).
-*/
-function collectRouteCss(segments, manifest) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const segment of segments) for (const file of [segment.layout, segment.page]) {
-		if (!file) continue;
-		const cssFiles = manifest.css[file.filePath];
-		if (!cssFiles) continue;
-		for (const url of cssFiles) if (!seen.has(url)) {
-			seen.add(url);
-			result.push(url);
-		}
-	}
-	return result;
-}
-/**
-* Collect all font entries needed for a matched route's segment chain.
-*
-* Walks segments root → leaf, collecting fonts for each layout and page.
-* Deduplicates by href while preserving order.
-*/
-function collectRouteFonts(segments, manifest) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const segment of segments) for (const file of [segment.layout, segment.page]) {
-		if (!file) continue;
-		const fonts = manifest.fonts[file.filePath];
-		if (!fonts) continue;
-		for (const entry of fonts) if (!seen.has(entry.href)) {
-			seen.add(entry.href);
-			result.push(entry);
-		}
-	}
-	return result;
-}
-/**
-* Collect modulepreload URLs for a matched route's segment chain.
-*
-* Walks segments root → leaf, collecting transitive JS dependencies
-* for each layout and page. Deduplicates across segments.
-*/
-function collectRouteModulepreloads(segments, manifest) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const segment of segments) for (const file of [segment.layout, segment.page]) {
-		if (!file) continue;
-		const preloads = manifest.modulepreload[file.filePath];
-		if (!preloads) continue;
-		for (const url of preloads) if (!seen.has(url)) {
-			seen.add(url);
-			result.push(url);
-		}
-	}
-	return result;
-}
-//#endregion
 //#region src/server/early-hints.ts
 /**
 * 103 Early Hints utilities.
@@ -2771,40 +3162,6 @@ function sendEarlyHints103(links) {
 }
 //#endregion
 //#region src/server/tree-builder.ts
-var REACT_COMPONENT_TYPE_MARKERS = /* @__PURE__ */ new Set([
-	Symbol.for("react.forward_ref"),
-	Symbol.for("react.memo"),
-	Symbol.for("react.lazy"),
-	Symbol.for("react.provider"),
-	Symbol.for("react.context"),
-	Symbol.for("react.suspense"),
-	Symbol.for("react.suspense_list"),
-	Symbol.for("react.client.reference")
-]);
-/**
-* Validate that a loaded module's `default` export is something React
-* accepts as the first argument to `createElement` — i.e. a valid component
-* type. React doesn't export `isValidElementType` (only `isValidElement`,
-* which checks for *elements*, not *component types*), so this mirrors
-* React's internal check:
-*
-*   - functions  → function or class components
-*   - objects with a `$$typeof` matching one of React's known component
-*     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
-*     suspense, client references via `@vitejs/plugin-rsc`)
-*
-* Strings (HTML tag names) are valid for `createElement` but never appear
-* as a route module's default export, so they're not recognized here.
-*
-* Anything else (numbers, plain config objects, JSON, etc.) is rejected so
-* the boundary wrapper is skipped rather than crashing inside React.
-*/
-function isValidElementType(value) {
-	if (typeof value === "function") return true;
-	if (typeof value !== "object" || value === null) return false;
-	const marker = value.$$typeof;
-	return typeof marker === "symbol" && REACT_COMPONENT_TYPE_MARKERS.has(marker);
-}
 /**
 * Build the unified element tree from a matched segment chain.
 *
@@ -2830,7 +3187,11 @@ async function buildElementTree(config) {
 	let element = createElement(PageComponent, {});
 	for (let i = segments.length - 1; i >= 0; i--) {
 		const segment = segments[i];
-		element = await wrapWithErrorBoundaries(segment, element, loadModule, createElement, errorBoundaryComponent);
+		element = await wrapSegmentWithErrorBoundaries(segment, element, {
+			loadModule,
+			createElement,
+			errorBoundaryComponent
+		});
 		if (segment.access) {
 			const accessFn = (await loadModule(segment.access)).default;
 			element = createElement("timber:access-gate", {
@@ -2871,7 +3232,11 @@ async function buildSlotElement(slotNode, loadModule, createElement, errorBounda
 	const DefaultComponent = (slotNode.default ? await loadModule(slotNode.default) : null)?.default;
 	if (!PageComponent) return DefaultComponent ? createElement(DefaultComponent, {}) : null;
 	let element = createElement(PageComponent, {});
-	element = await wrapWithErrorBoundaries(slotNode, element, loadModule, createElement, errorBoundaryComponent);
+	element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
+		loadModule,
+		createElement,
+		errorBoundaryComponent
+	});
 	if (slotNode.access) {
 		const accessFn = (await loadModule(slotNode.access)).default;
 		const DeniedComponent = (slotNode.denied ? await loadModule(slotNode.denied) : null)?.default ?? null;
@@ -2887,81 +3252,6 @@ async function buildSlotElement(slotNode, loadModule, createElement, errorBounda
 	}
 	return element;
 }
-/** MDX/markdown extensions — these are server components that cannot be passed as function props. */
-var MDX_EXTENSIONS = /* @__PURE__ */ new Set(["mdx", "md"]);
-/**
-* Check if a route file is an MDX/markdown file based on its extension.
-* MDX components are server components by default and cannot cross the
-* RSC→client boundary as function props. They must be pre-rendered as
-* elements and passed as fallbackElement instead of fallbackComponent.
-*/
-function isMdxFile(file) {
-	return MDX_EXTENSIONS.has(file.extension);
-}
-/**
-* Wrap an element with error boundaries from a segment's status-code files.
-*
-* Wrapping order (innermost to outermost):
-*   1. Specific status files (503.tsx, 429.tsx, etc.)
-*   2. Category catch-alls (4xx.tsx, 5xx.tsx)
-*   3. error.tsx (general error boundary)
-*
-* This creates the fallback chain described in design/10-error-handling.md.
-*
-* MDX status files are server components and cannot be passed as function
-* props to TimberErrorBoundary (a 'use client' component). Instead, they
-* are pre-rendered as elements and passed as fallbackElement. The error
-* boundary renders the element directly when an error is caught.
-* See TIM-503.
-*/
-async function wrapWithErrorBoundaries(segment, element, loadModule, createElement, errorBoundaryComponent) {
-	if (segment.statusFiles) {
-		for (const [key, file] of Object.entries(segment.statusFiles)) if (key !== "4xx" && key !== "5xx") {
-			const status = parseInt(key, 10);
-			if (!isNaN(status)) {
-				const mod = await loadModule(file);
-				const Component = isValidElementType(mod.default) ? mod.default : null;
-				if (Component) element = createElement(errorBoundaryComponent, isMdxFile(file) ? {
-					fallbackElement: createElement(Component, { status }),
-					status,
-					children: element
-				} : {
-					fallbackComponent: Component,
-					status,
-					children: element
-				});
-			}
-		}
-		for (const [key, file] of Object.entries(segment.statusFiles)) if (key === "4xx" || key === "5xx") {
-			const mod = await loadModule(file);
-			const Component = isValidElementType(mod.default) ? mod.default : null;
-			if (Component) {
-				const categoryStatus = key === "4xx" ? 400 : 500;
-				element = createElement(errorBoundaryComponent, isMdxFile(file) ? {
-					fallbackElement: createElement(Component, {}),
-					status: categoryStatus,
-					children: element
-				} : {
-					fallbackComponent: Component,
-					status: categoryStatus,
-					children: element
-				});
-			}
-		}
-	}
-	if (segment.error) {
-		const errorModule = await loadModule(segment.error);
-		const ErrorComponent = isValidElementType(errorModule.default) ? errorModule.default : null;
-		if (ErrorComponent) element = createElement(errorBoundaryComponent, isMdxFile(segment.error) ? {
-			fallbackElement: createElement(ErrorComponent, {}),
-			children: element
-		} : {
-			fallbackComponent: ErrorComponent,
-			children: element
-		});
-	}
-	return element;
-}
 //#endregion
 //#region src/server/status-code-resolver.ts
 /**
@@ -2999,12 +3289,19 @@ function lookupInGroup(group, statusStr, categoryKey, segmentIndex, status) {
 * @param status - The HTTP status code (4xx or 5xx).
 * @param segments - The matched segment chain from root (index 0) to leaf (last).
 * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
-*/
-function resolveStatusFile(status, segments, format = "component") {
+* @param maxIndex - Optional upper bound on the segment index to search.
+*   When set, the resolver only considers segments `0..maxIndex` (inclusive),
+*   skipping any segments deeper in the tree. Used by the deny renderers to
+*   prevent resolving a status file below a denied segment — matching
+*   `buildDenyPageChain`'s start-at-i semantics. The error renderers omit
+*   this parameter, so the full chain is searched — a 500 from a leaf page
+*   should use the leaf's own `5xx.tsx`. See TIM-1358.
+*/
+function resolveStatusFile(status, segments, format = "component", maxIndex) {
 	if (status < 400 || status > 599) return null;
-	if (format === "json") return resolveJson(status, segments);
-	if (status <= 499) return resolve4xx(status, segments);
-	return resolve5xx(status, segments);
+	if (format === "json") return resolveJson(status, segments, maxIndex);
+	if (status <= 499) return resolve4xx(status, segments, maxIndex);
+	return resolve5xx(status, segments, maxIndex);
 }
 /**
 * 4xx component fallback chain — two separate full passes leaf→root.
@@ -3018,13 +3315,14 @@ function resolveStatusFile(status, segments, format = "component") {
 *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
 *   Pass 2 — error.tsx                         (error)
 */
-function resolve4xx(status, segments) {
+function resolve4xx(status, segments, maxIndex) {
 	const statusStr = String(status);
-	for (let i = segments.length - 1; i >= 0; i--) {
+	const start = maxIndex !== void 0 ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
+	for (let i = start; i >= 0; i--) {
 		const r = lookupInGroup(segments[i].statusFiles, statusStr, "4xx", i, status);
 		if (r) return r;
 	}
-	for (let i = segments.length - 1; i >= 0; i--) {
+	for (let i = start; i >= 0; i--) {
 		const errorFile = segments[i].error;
 		if (errorFile) return {
 			file: errorFile,
@@ -3042,9 +3340,10 @@ function resolve4xx(status, segments) {
 * `error.tsx` therefore beats a root's `5xx.tsx`, which is the
 * intentional inverse of the 4xx chain.
 */
-function resolve5xx(status, segments) {
+function resolve5xx(status, segments, maxIndex) {
 	const statusStr = String(status);
-	for (let i = segments.length - 1; i >= 0; i--) {
+	const start = maxIndex !== void 0 ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
+	for (let i = start; i >= 0; i--) {
 		const segment = segments[i];
 		const r = lookupInGroup(segment.statusFiles, statusStr, "5xx", i, status);
 		if (r) return r;
@@ -3064,10 +3363,11 @@ function resolve5xx(status, segments) {
 * no error.tsx — the JSON chain terminates at the category catch-all
 * and the caller falls back to a bare-JSON framework default.
 */
-function resolveJson(status, segments) {
+function resolveJson(status, segments, maxIndex) {
 	const statusStr = String(status);
 	const categoryKey = status >= 500 ? "5xx" : "4xx";
-	for (let i = segments.length - 1; i >= 0; i--) {
+	const start = maxIndex !== void 0 ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
+	for (let i = start; i >= 0; i--) {
 		const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
 		if (r) return r;
 	}
@@ -3277,14 +3577,8 @@ async function handleRouteRequest(mod, ctx) {
 		});
 	}
 	if (method === "HEAD") {
-		if (mod.HEAD) return runHandler(mod.HEAD, ctx);
-		if (mod.GET) {
-			const res = await runHandler(mod.GET, ctx);
-			return new Response(null, {
-				status: res.status,
-				headers: res.headers
-			});
-		}
+		if (mod.HEAD) return stripHeadBody(await runHandler(mod.HEAD, ctx), method);
+		if (mod.GET) return stripHeadBody(await runHandler(mod.GET, ctx), method);
 	}
 	const handler = mod[method];
 	if (!handler) return new Response(null, {
@@ -3511,11 +3805,11 @@ var registry = /* @__PURE__ */ new Map();
 */
 function resolveKeyParams(store) {
 	const main = store.segmentParams ?? {};
-	const map = store.slotParamsMap;
-	if (!map || map.size === 0) return main;
+	const slots = store.slotParams;
+	if (!slots || Object.keys(slots).length === 0) return main;
 	const mainCanonical = tryCanonicalize({ ...main });
 	if (mainCanonical === null) return null;
-	for (const slotParams of map.values()) {
+	for (const slotParams of Object.values(slots)) {
 		const merged = tryCanonicalize({
 			...main,
 			...slotParams