@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.98

package/dist/server/internal.js

@@ -1,7 +1,7 @@
 import { n as isDevMode, t as isDebug } from "../_chunks/debug-ECi_61pb.js";
 import { a as warnRedirectInSuspense, c as warnSuspenseWrappingChildren, i as warnRedirectInAccess, n as setViteServer, o as warnSlowSlotWithoutSuspense, r as warnDenyInSuspense, s as warnStaticRequestApi, t as WarningId } from "../_chunks/dev-warnings-DpGRGoDi.js";
-import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
-import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-DS3eKNmf.js";
+import { n as classifyUrlSegment } from "../_chunks/segment-classify-BjfuctV2.js";
+import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-BU684ls2.js";
 import { a as timingAls, r as requestContextAls, t as earlyHintsSenderAls } from "../_chunks/als-registry-HS0LGUl2.js";
 import { f as runWithRequestContext, l as getSetCookieHeaders, m as setSegmentParams, p as setMutableCookieContext, t as applyRequestHeaderOverlay, u as markResponseFlushed } from "../_chunks/request-context-CK5tZqIP.js";
 import { l as RenderError, n as executeAction, o as DenySignal, r as isRscActionRequest, s as RedirectSignal, t as buildNoJsResponse } from "../_chunks/actions-DLnUaR65.js";
@@ -10,120 +10,6 @@ import "../client/error-boundary.js";
 import "../_chunks/segment-context-fHFLF1PE.js";
 import { readFile } from "node:fs/promises";
 import { createElement } from "react";
-//#region src/server/canonicalize.ts
-/**
-* Encoded separators that produce a 400 rejection.
-* %2f (/) and %5c (\) cause path-confusion attacks.
-*/
-var ENCODED_SEPARATOR_RE = /%2f|%5c/i;
-/** Null byte — rejected. */
-var NULL_BYTE_RE = /%00/i;
-/**
-* Canonicalize a URL pathname.
-*
-* 1. Reject encoded separators (%2f, %5c) and null bytes (%00)
-* 2. Single percent-decode
-* 3. Collapse // → /
-* 4. Resolve .. segments (reject if escaping root)
-* 5. Strip trailing slash (except root "/")
-*
-* @param rawPathname - The raw pathname from the request URL (percent-encoded)
-* @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.
-*/
-function canonicalize(rawPathname, stripTrailingSlash = true) {
-	if (ENCODED_SEPARATOR_RE.test(rawPathname)) return {
-		ok: false,
-		status: 400
-	};
-	if (NULL_BYTE_RE.test(rawPathname)) return {
-		ok: false,
-		status: 400
-	};
-	let decoded;
-	try {
-		decoded = decodeURIComponent(rawPathname);
-	} catch {
-		return {
-			ok: false,
-			status: 400
-		};
-	}
-	if (decoded.includes("\0")) return {
-		ok: false,
-		status: 400
-	};
-	let pathname = decoded.replace(/\/\/+/g, "/");
-	const segments = pathname.split("/");
-	const resolved = [];
-	for (const seg of segments) if (seg === "..") {
-		if (resolved.length <= 1) return {
-			ok: false,
-			status: 400
-		};
-		resolved.pop();
-	} else if (seg !== ".") resolved.push(seg);
-	pathname = resolved.join("/") || "/";
-	if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith("/")) pathname = pathname.slice(0, -1);
-	return {
-		ok: true,
-		pathname
-	};
-}
-//#endregion
-//#region src/server/proxy.ts
-/**
-* Run the proxy pipeline.
-*
-* @param proxyExport - The default export from proxy.ts (function or array)
-* @param req - The incoming request
-* @param next - The continuation that proceeds to route matching and rendering
-* @returns The final response
-*/
-async function runProxy(proxyExport, req, next) {
-	const fns = Array.isArray(proxyExport) ? proxyExport : [proxyExport];
-	let i = fns.length;
-	let composed = next;
-	while (i--) {
-		const fn = fns[i];
-		const downstream = composed;
-		composed = () => Promise.resolve(fn(req, downstream));
-	}
-	return composed();
-}
-//#endregion
-//#region src/server/middleware-runner.ts
-/**
-* Run a route's middleware function.
-*
-* @param middlewareFn - The default export from the route's middleware.ts
-* @param ctx - The middleware context (req, params, headers, requestHeaders, searchParams)
-* @returns A Response if middleware short-circuited, or undefined to continue
-*/
-async function runMiddleware(middlewareFn, ctx) {
-	const result = await middlewareFn(ctx);
-	if (result instanceof Response) return result;
-}
-/**
-* Run all middleware functions in the segment chain, root to leaf.
-*
-* Execution is top-down: root middleware runs first, leaf middleware runs last.
-* All middleware share the same MiddlewareContext — a parent that sets
-* ctx.requestHeaders makes it visible to child middleware and downstream components.
-*
-* Short-circuits on the first middleware that returns a Response.
-* Remaining middleware in the chain do not execute.
-*
-* @param chain - Middleware functions ordered root-to-leaf
-* @param ctx - Shared middleware context
-* @returns A Response if any middleware short-circuited, or undefined to continue
-*/
-async function runMiddlewareChain(chain, ctx) {
-	for (const fn of chain) {
-		const result = await fn(ctx);
-		if (result instanceof Response) return result;
-	}
-}
-//#endregion
 //#region src/server/server-timing.ts
 /**
 * Server-Timing header — dev-mode timing breakdowns for Chrome DevTools.
@@ -532,6 +418,250 @@ function hasOnRequestError() {
 	return _onRequestError !== null;
 }
 //#endregion
+//#region src/server/pipeline-helpers.ts
+/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
+var DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Shallow merge that skips top-level prototype-polluting keys.
+*
+* This is intentionally NOT a deep sanitizer. It only blocks shallow
+* pollution via top-level `__proto__` / `constructor` / `prototype`
+* keys. The deeper guarantee for segment params comes from merging
+* codec output into a null-prototype target inside coerceSegmentParams().
+*
+* See TIM-655, TIM-855, design/13-security.md
+*/
+function safeMerge(target, source) {
+	for (const key of Object.keys(source)) if (!DANGEROUS_KEYS.has(key)) target[key] = source[key];
+}
+/**
+* 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.
+*
+* Returns `null` when the app has no proxy.ts — the hot path short-circuits
+* around `runProxyPhase` entirely in that case.
+*
+* Accepts the sugar form (a bare `ProxyExport` — function or function array)
+* and normalises it to the static variant. Functions and arrays are
+* structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
+* so discrimination is unambiguous.
+*/
+function makeProxyResolver(proxy) {
+	if (proxy === void 0) return null;
+	if (typeof proxy === "function" || Array.isArray(proxy)) {
+		const exp = proxy;
+		return () => exp;
+	}
+	if (proxy.kind === "static") {
+		const exp = proxy.export;
+		return () => exp;
+	}
+	const loader = proxy.loader;
+	return async () => (await loader()).default;
+}
+/**
+* Apply all Set-Cookie headers from the cookie jar to a Headers object.
+* Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
+*/
+function applyCookieJar(headers) {
+	for (const value of getSetCookieHeaders()) headers.append("Set-Cookie", value);
+}
+/**
+* Merge framework-managed response headers onto a terminal response without
+* overwriting headers the terminal response already set itself.
+*/
+function mergeMissingHeaders(target, source) {
+	const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));
+	for (const [key, value] of source.entries()) if (!existingKeys.has(key.toLowerCase())) target.append(key, value);
+}
+/**
+* Clone a Response into a fresh one whose header bag is guaranteed mutable.
+*
+* `Response.redirect()` and some platform-level passthrough responses (notably
+* on Cloudflare Workers) return objects with frozen header bags. Calling
+* `.set()` or `.append()` on them throws `TypeError: immutable`, which the
+* pipeline can hit when it appends Set-Cookie or Server-Timing entries.
+*
+* The pipeline calls this at the producer sites where user-controlled
+* responses enter the framework — `outcomeToResponse` for all phase outcomes,
+* and `handleRequest` for metadata-route and auto-sitemap user handlers — so
+* downstream code can write headers without runtime feature-detection.
+*
+* The clone is unconditional. This is a deliberate trade: we avoid a
+* try/catch + thrown `TypeError` on every request (the previous probe-based
+* approach paid that cost on the hot path) and accept one cheap Response
+* rewrap at the framework boundary instead.
+*/
+function cloneWithMutableHeaders(response) {
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: new Headers(response.headers)
+	});
+}
+/**
+* Build a redirect Response from a RedirectSignal.
+*
+* For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
+* so the client router can perform a soft SPA redirect. A raw 302 would be
+* turned into an opaque redirect by fetch({redirect:'manual'}), crashing
+* createFromFetch. See design/19-client-navigation.md.
+*/
+function buildRedirectResponse(signal, req, headers) {
+	if ((req.headers.get("Accept") ?? "").includes("text/x-component")) {
+		headers.set("X-Timber-Redirect", signal.location);
+		return new Response(null, {
+			status: 204,
+			headers
+		});
+	}
+	headers.set("Location", signal.location);
+	return new Response(null, {
+		status: signal.status,
+		headers
+	});
+}
+/**
+* Fire the user's onRequestError hook with request context.
+* Extracts request info from the Request object and calls the instrumentation hook.
+*/
+async function fireOnRequestError(error, req, phase) {
+	const url = new URL(req.url);
+	const headersObj = {};
+	req.headers.forEach((v, k) => {
+		headersObj[k] = v;
+	});
+	await callOnRequestError(error, {
+		method: req.method,
+		path: url.pathname,
+		headers: headersObj
+	}, {
+		phase,
+		routePath: url.pathname,
+		routeType: "page",
+		traceId: getTraceId()
+	});
+}
+//#endregion
+//#region src/server/canonicalize.ts
+/**
+* Encoded separators that produce a 400 rejection.
+* %2f (/) and %5c (\) cause path-confusion attacks.
+*/
+var ENCODED_SEPARATOR_RE = /%2f|%5c/i;
+/** Null byte — rejected. */
+var NULL_BYTE_RE = /%00/i;
+/**
+* Canonicalize a URL pathname.
+*
+* 1. Reject encoded separators (%2f, %5c) and null bytes (%00)
+* 2. Single percent-decode
+* 3. Collapse // → /
+* 4. Resolve .. segments (reject if escaping root)
+* 5. Strip trailing slash (except root "/")
+*
+* @param rawPathname - The raw pathname from the request URL (percent-encoded)
+* @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.
+*/
+function canonicalize(rawPathname, stripTrailingSlash = true) {
+	if (ENCODED_SEPARATOR_RE.test(rawPathname)) return {
+		ok: false,
+		status: 400
+	};
+	if (NULL_BYTE_RE.test(rawPathname)) return {
+		ok: false,
+		status: 400
+	};
+	let decoded;
+	try {
+		decoded = decodeURIComponent(rawPathname);
+	} catch {
+		return {
+			ok: false,
+			status: 400
+		};
+	}
+	if (decoded.includes("\0")) return {
+		ok: false,
+		status: 400
+	};
+	let pathname = decoded.replace(/\/\/+/g, "/");
+	const segments = pathname.split("/");
+	const resolved = [];
+	for (const seg of segments) if (seg === "..") {
+		if (resolved.length <= 1) return {
+			ok: false,
+			status: 400
+		};
+		resolved.pop();
+	} else if (seg !== ".") resolved.push(seg);
+	pathname = resolved.join("/") || "/";
+	if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith("/")) pathname = pathname.slice(0, -1);
+	return {
+		ok: true,
+		pathname
+	};
+}
+//#endregion
+//#region src/server/proxy.ts
+/**
+* Run the proxy pipeline.
+*
+* @param proxyExport - The default export from proxy.ts (function or array)
+* @param req - The incoming request
+* @param next - The continuation that proceeds to route matching and rendering
+* @returns The final response
+*/
+async function runProxy(proxyExport, req, next) {
+	const fns = Array.isArray(proxyExport) ? proxyExport : [proxyExport];
+	let i = fns.length;
+	let composed = next;
+	while (i--) {
+		const fn = fns[i];
+		const downstream = composed;
+		composed = () => Promise.resolve(fn(req, downstream));
+	}
+	return composed();
+}
+//#endregion
+//#region src/server/middleware-runner.ts
+/**
+* Run a route's middleware function.
+*
+* @param middlewareFn - The default export from the route's middleware.ts
+* @param ctx - The middleware context (req, params, headers, requestHeaders, searchParams)
+* @returns A Response if middleware short-circuited, or undefined to continue
+*/
+async function runMiddleware(middlewareFn, ctx) {
+	const result = await middlewareFn(ctx);
+	if (result instanceof Response) return result;
+}
+/**
+* Run all middleware functions in the segment chain, root to leaf.
+*
+* Execution is top-down: root middleware runs first, leaf middleware runs last.
+* All middleware share the same MiddlewareContext — a parent that sets
+* ctx.requestHeaders makes it visible to child middleware and downstream components.
+*
+* Short-circuits on the first middleware that returns a Response.
+* Remaining middleware in the chain do not execute.
+*
+* @param chain - Middleware functions ordered root-to-leaf
+* @param ctx - Shared middleware context
+* @returns A Response if any middleware short-circuited, or undefined to continue
+*/
+async function runMiddlewareChain(chain, ctx) {
+	for (const fn of chain) {
+		const result = await fn(ctx);
+		if (result instanceof Response) return result;
+	}
+}
+//#endregion
 //#region src/server/metadata-social.ts
 /**
 * Render Open Graph metadata into head element descriptors.
@@ -1616,78 +1746,383 @@ function pathnameMatchesPattern(pathname, pattern) {
 				continue;
 		}
 	}
-	return pi === pathParts.length;
-}
-//#endregion
-//#region src/server/pipeline.ts
-/**
-* Request pipeline — the central dispatch for all timber.js requests.
-*
-* Pipeline stages (in order):
-*   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
-*
-* Each stage is a pure function or returns a Response to short-circuit.
-* Each request gets a trace ID, structured logging, and OTEL spans.
-*
-* See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
-* and design/17-logging.md §"Production Logging"
-*/
-/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
-var DANGEROUS_KEYS = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-/**
-* Shallow merge that skips prototype-polluting keys.
-*
-* Used instead of Object.assign when the source object comes from
-* user-authored codec output (segmentParams.parse), which could
-* contain __proto__, constructor, or prototype keys.
-*
-* See TIM-655, design/13-security.md
-*/
-function safeMerge(target, source) {
-	for (const key of Object.keys(source)) if (!DANGEROUS_KEYS.has(key)) target[key] = source[key];
+	return pi === pathParts.length;
+}
+//#endregion
+//#region src/server/pipeline-phases.ts
+/**
+* Pipeline phase functions — module-level free functions that take their
+* dependencies as explicit parameters. Each phase returns a `PhaseOutcome`
+* (a discriminated union over response / redirect / deny / error). The
+* terminal `outcomeToResponse` translates outcomes into Responses.
+*
+* Lifted out of `createPipeline` so each phase can be unit-tested in
+* isolation. The lift is mechanical — these functions used to be closures
+* over `config`; they now take `config` as an explicit parameter.
+*
+* See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow".
+*/
+/**
+* Run segment param coercion on the matched route's segments.
+*
+* Loads params.ts modules from segments that have them, extracts the
+* segmentParams definition, and coerces raw string params through codecs.
+* 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"
+*/
+async function coerceSegmentParams(match) {
+	const segments = match.segments;
+	let mergeTarget = match.segmentParams;
+	let usesNullPrototypeTarget = Object.getPrototypeOf(mergeTarget) === null;
+	for (const segment of segments) {
+		if (!segment.params) continue;
+		let mod;
+		try {
+			mod = await loadModule(segment.params);
+		} catch (err) {
+			throw new ParamCoercionError(`Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`);
+		}
+		const segmentParamsDef = mod.segmentParams;
+		if (!segmentParamsDef || typeof segmentParamsDef.parse !== "function") continue;
+		try {
+			const coerced = segmentParamsDef.parse(match.segmentParams);
+			if (!usesNullPrototypeTarget) {
+				mergeTarget = Object.create(null);
+				safeMerge(mergeTarget, match.segmentParams);
+				match.segmentParams = mergeTarget;
+				usesNullPrototypeTarget = true;
+			}
+			safeMerge(mergeTarget, coerced);
+		} catch (err) {
+			throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+		}
+	}
+}
+/**
+* Run the proxy.ts phase. Calls user proxy code and uses `handleRequest` as
+* the inner `next()` continuation. The proxy resolver was picked at pipeline
+* construction time so the hot path sees no per-request branching on the
+* `ProxyConfig` discriminant.
+*/
+async function runProxyPhase(config, getProxy, req, method, path) {
+	const detailed = config.serverTiming === "detailed";
+	try {
+		const proxyExport = await getProxy();
+		const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(config, req, method, path));
+		return {
+			kind: "response",
+			phase: "proxy",
+			response: await withSpan("timber.proxy", {}, () => detailed ? withTiming("proxy", "proxy.ts", proxyFn) : proxyFn())
+		};
+	} catch (error) {
+		return {
+			kind: "error",
+			phase: "proxy",
+			error
+		};
+	}
+}
+/**
+* Run the middleware chain phase. If the chain short-circuits with a Response,
+* returns it as a 'response' outcome. Otherwise applies the request header
+* overlay and falls through to the render phase.
+*/
+async function runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, renderContext) {
+	const detailed = config.serverTiming === "detailed";
+	const ctx = {
+		req,
+		requestHeaders: requestHeaderOverlay,
+		headers: responseHeaders,
+		segmentParams: match.segmentParams,
+		earlyHints: (hints) => {
+			for (const hint of hints) {
+				let value;
+				if (hint.as !== void 0) value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
+				else value = `<${hint.href}>; rel=${hint.rel}`;
+				if (hint.crossOrigin !== void 0) value += `; crossorigin=${hint.crossOrigin}`;
+				if (hint.fetchPriority !== void 0) value += `; fetchpriority=${hint.fetchPriority}`;
+				responseHeaders.append("Link", value);
+			}
+		}
+	};
+	try {
+		const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
+		const middlewareResponse = await (async () => {
+			setMutableCookieContext(true);
+			try {
+				return await withSpan("timber.middleware", {}, () => detailed ? withTiming("mw", "middleware.ts", chainFn) : chainFn());
+			} finally {
+				setMutableCookieContext(false);
+			}
+		})();
+		if (middlewareResponse) return {
+			kind: "response",
+			phase: "middleware",
+			response: middlewareResponse
+		};
+		applyRequestHeaderOverlay(requestHeaderOverlay);
+		applyCookieJar(responseHeaders);
+		return runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, renderContext);
+	} catch (error) {
+		if (error instanceof RedirectSignal) return {
+			kind: "redirect",
+			phase: "middleware",
+			signal: error
+		};
+		if (error instanceof DenySignal) return {
+			kind: "deny",
+			phase: "middleware",
+			signal: error
+		};
+		return {
+			kind: "error",
+			phase: "middleware",
+			error
+		};
+	}
+}
+/**
+* Run the render phase. Wraps the configured renderer in a span and a
+* timing scope, and translates thrown signals into outcome variants.
+*/
+async function runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, { canonicalPathname, interception }) {
+	const detailed = config.serverTiming === "detailed";
+	try {
+		const renderFn = () => config.render(req, match, responseHeaders, requestHeaderOverlay, interception);
+		return {
+			kind: "response",
+			phase: "render",
+			response: await withSpan("timber.render", { "http.route": canonicalPathname }, () => detailed ? withTiming("render", "RSC + SSR render", renderFn) : renderFn())
+		};
+	} catch (error) {
+		if (error instanceof DenySignal) return {
+			kind: "deny",
+			phase: "render",
+			signal: error
+		};
+		if (error instanceof RedirectSignal) return {
+			kind: "redirect",
+			phase: "render",
+			signal: error
+		};
+		return {
+			kind: "error",
+			phase: "render",
+			error
+		};
+	}
+}
+/**
+* Process a single request from canonicalization through phase dispatch.
+*
+* Stages: canonicalize → metadata routes → auto-sitemap → version skew →
+* route match → interception → early hints → param coercion → middleware →
+* render → outcome translation. Pre-routing short-circuits return Responses
+* directly; post-match dispatch goes through `outcomeToResponse`.
+*
+* Used both as the top-level entry (when no proxy.ts is configured) and as
+* the `next()` continuation passed to `runProxy()`.
+*/
+async function handleRequest(config, req, method, path) {
+	const stripTrailingSlash = config.stripTrailingSlash ?? true;
+	const result = canonicalize(new URL(req.url).pathname, stripTrailingSlash);
+	if (!result.ok) return new Response(null, { status: result.status });
+	const canonicalPathname = result.pathname;
+	if (config.matchMetadataRoute) {
+		const metaMatch = config.matchMetadataRoute(canonicalPathname);
+		if (metaMatch) try {
+			if (metaMatch.isStatic) return await serveStaticMetadataFile(metaMatch);
+			const mod = await loadModule(metaMatch.file);
+			if (typeof mod.default !== "function") return new Response("Metadata route must export a default function", { status: 500 });
+			const handlerResult = await mod.default();
+			if (handlerResult instanceof Response) return cloneWithMutableHeaders(handlerResult);
+			const contentType = metaMatch.contentType;
+			let body;
+			if (typeof handlerResult === "string") body = handlerResult;
+			else if (contentType === "application/xml") body = serializeSitemap(handlerResult);
+			else if (contentType === "application/manifest+json") body = JSON.stringify(handlerResult, null, 2);
+			else body = typeof handlerResult === "string" ? handlerResult : String(handlerResult);
+			return new Response(body, {
+				status: 200,
+				headers: { "Content-Type": `${contentType}; charset=utf-8` }
+			});
+		} catch (error) {
+			logRenderError({
+				method,
+				path,
+				error
+			});
+			if (config.onPipelineError && error instanceof Error) config.onPipelineError(error, "metadata-route");
+			return new Response(null, { status: 500 });
+		}
+	}
+	if (config.autoSitemapHandler) try {
+		const sitemapResponse = await config.autoSitemapHandler(canonicalPathname);
+		if (sitemapResponse) return cloneWithMutableHeaders(sitemapResponse);
+	} catch (error) {
+		logRenderError({
+			method,
+			path,
+			error
+		});
+		if (config.onPipelineError && error instanceof Error) config.onPipelineError(error, "auto-sitemap");
+		return new Response(null, { status: 500 });
+	}
+	if ((req.headers.get("Accept") ?? "").includes("text/x-component")) {
+		if (!checkVersionSkew(req).ok) {
+			const reloadHeaders = new Headers();
+			applyReloadHeaders(reloadHeaders);
+			return new Response(null, {
+				status: 204,
+				headers: reloadHeaders
+			});
+		}
+	}
+	let match = config.matchRoute(canonicalPathname);
+	let interception;
+	const sourceUrl = req.headers.get("X-Timber-URL");
+	if (sourceUrl && config.interceptionRewrites?.length) {
+		const intercepted = findInterceptionMatch(canonicalPathname, sourceUrl, config.interceptionRewrites);
+		if (intercepted) {
+			const sourceMatch = config.matchRoute(intercepted.sourcePathname);
+			if (sourceMatch) {
+				match = sourceMatch;
+				interception = { targetPathname: canonicalPathname };
+			}
+		}
+	}
+	if (!match) {
+		if (config.renderNoMatch) {
+			const responseHeaders = new Headers();
+			return cloneWithMutableHeaders(await config.renderNoMatch(req, responseHeaders));
+		}
+		return new Response(null, { status: 404 });
+	}
+	const responseHeaders = new Headers();
+	const requestHeaderOverlay = new Headers();
+	responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
+	if (config.earlyHints) try {
+		await config.earlyHints(match, req, responseHeaders);
+	} catch {}
+	try {
+		await coerceSegmentParams(match);
+	} catch (error) {
+		if (error instanceof ParamCoercionError) {
+			const leafSegment = match.segments[match.segments.length - 1];
+			if (leafSegment.route && !leafSegment.page) return new Response(null, { status: 404 });
+			if (config.renderNoMatch) return cloneWithMutableHeaders(await config.renderNoMatch(req, responseHeaders));
+			return new Response(null, { status: 404 });
+		}
+		throw error;
+	}
+	setSegmentParams(match.segmentParams);
+	return outcomeToResponse(config, match.middlewareChain.length > 0 ? await runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+		canonicalPathname,
+		interception
+	}) : await runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+		canonicalPathname,
+		interception
+	}), {
+		req,
+		method,
+		path,
+		responseHeaders,
+		match
+	});
 }
 /**
-* Run segment param coercion on the matched route's segments.
-*
-* Loads params.ts modules from segments that have them, extracts the
-* segmentParams definition, and coerces raw string params through codecs.
-* 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"
-*/
-async function coerceSegmentParams(match) {
-	const segments = match.segments;
-	for (const segment of segments) {
-		if (!segment.params) continue;
-		let mod;
-		try {
-			mod = await loadModule(segment.params);
-		} catch (err) {
-			throw new ParamCoercionError(`Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`);
+* Terminal outcome handler — converts a `PhaseOutcome` into a final
+* `Response`, applying cookies, building redirects, rendering deny pages
+* and fallback error pages, and firing instrumentation hooks.
+*
+* This is the single source of truth for how phase outputs become wire
+* responses; the per-phase try/catch blocks now produce values, not
+* Responses, so the conversion logic lives in exactly one place.
+*/
+async function outcomeToResponse(config, outcome, ctx) {
+	switch (outcome.kind) {
+		case "response": {
+			const finalResponse = cloneWithMutableHeaders(outcome.response);
+			if (outcome.phase === "proxy") return finalResponse;
+			if (outcome.phase === "middleware" && ctx.responseHeaders) {
+				applyCookieJar(finalResponse.headers);
+				mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
+				logMiddlewareShortCircuit({
+					method: ctx.method,
+					path: ctx.path,
+					status: finalResponse.status
+				});
+			}
+			if (outcome.phase === "render") markResponseFlushed();
+			return finalResponse;
 		}
-		const segmentParamsDef = mod.segmentParams;
-		if (!segmentParamsDef || typeof segmentParamsDef.parse !== "function") continue;
-		try {
-			const coerced = segmentParamsDef.parse(match.segmentParams);
-			safeMerge(match.segmentParams, coerced);
-		} catch (err) {
-			throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+		case "redirect": {
+			const headers = ctx.responseHeaders ?? new Headers();
+			applyCookieJar(headers);
+			return buildRedirectResponse(outcome.signal, ctx.req, headers);
+		}
+		case "deny": {
+			const headers = ctx.responseHeaders ?? new Headers();
+			applyCookieJar(headers);
+			if (config.renderDenyFallback) try {
+				return cloneWithMutableHeaders(await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match));
+			} catch {}
+			return new Response(null, {
+				status: outcome.signal.status,
+				headers
+			});
+		}
+		case "error": {
+			if (outcome.phase === "proxy") {
+				logProxyError({ error: outcome.error });
+				await fireOnRequestError(outcome.error, ctx.req, "proxy");
+				if (config.onPipelineError && outcome.error instanceof Error) config.onPipelineError(outcome.error, "proxy");
+				return new Response(null, { status: 500 });
+			}
+			if (outcome.phase === "middleware") {
+				logMiddlewareError({
+					method: ctx.method,
+					path: ctx.path,
+					error: outcome.error
+				});
+				await fireOnRequestError(outcome.error, ctx.req, "handler");
+				if (config.onPipelineError && outcome.error instanceof Error) config.onPipelineError(outcome.error, "middleware");
+				return new Response(null, { status: 500 });
+			}
+			const headers = ctx.responseHeaders ?? new Headers();
+			applyCookieJar(headers);
+			logRenderError({
+				method: ctx.method,
+				path: ctx.path,
+				error: outcome.error
+			});
+			await fireOnRequestError(outcome.error, ctx.req, "render");
+			if (config.onPipelineError && outcome.error instanceof Error) config.onPipelineError(outcome.error, "render");
+			if (config.renderFallbackError) try {
+				return cloneWithMutableHeaders(await config.renderFallbackError(outcome.error, ctx.req, headers));
+			} catch {}
+			return new Response(null, { status: 500 });
 		}
 	}
 }
+//#endregion
+//#region src/server/pipeline.ts
 /**
 * Create the request handler from a pipeline configuration.
 *
-* Returns a function that processes an incoming Request through all pipeline stages
-* and produces a Response. This is the top-level entry point for the server.
+* Returns a function that processes an incoming Request through all pipeline
+* stages and produces a Response. This is the top-level entry point for the
+* server. The body is intentionally small — phase logic lives in
+* `pipeline-phases.ts`. This function only owns the per-request setup that
+* has to wrap the entire dispatch: trace ID, request context ALS, span
+* scope, Server-Timing header emission, and the active-request counter.
 */
 function createPipeline(config) {
-	const { proxy, matchRoute, render, earlyHints, stripTrailingSlash = true, slowRequestMs = 3e3, serverTiming = "total", onPipelineError } = config;
+	const proxyResolver = makeProxyResolver(config.proxy);
+	const slowRequestMs = config.slowRequestMs ?? 3e3;
+	const serverTiming = config.serverTiming ?? "total";
 	let activeRequests = 0;
 	return async (req) => {
 		const url = new URL(req.url);
@@ -1709,18 +2144,18 @@ function createPipeline(config) {
 						const otelIds = await getOtelTraceId();
 						if (otelIds) replaceTraceId(otelIds.traceId, otelIds.spanId);
 						let result;
-						if (proxy || config.proxyLoader) result = await runProxyPhase(req, method, path);
-						else result = await handleRequest(req, method, path);
+						if (proxyResolver) result = await outcomeToResponse(config, await runProxyPhase(config, proxyResolver, req, method, path), {
+							req,
+							method,
+							path
+						});
+						else result = await handleRequest(config, req, method, path);
 						await setSpanAttribute("http.response.status_code", result.status);
 						if (serverTiming === "detailed") {
 							const timingHeader = getServerTimingHeader();
-							if (timingHeader) {
-								result = ensureMutableResponse(result);
-								result.headers.set("Server-Timing", timingHeader);
-							}
+							if (timingHeader) result.headers.set("Server-Timing", timingHeader);
 						} else if (serverTiming === "total") {
 							const totalMs = Math.round(performance.now() - startTime);
-							result = ensureMutableResponse(result);
 							result.headers.set("Server-Timing", `total;dur=${totalMs}`);
 						}
 						return result;
@@ -1749,276 +2184,6 @@ function createPipeline(config) {
 			});
 		});
 	};
-	async function runProxyPhase(req, method, path) {
-		try {
-			let proxyExport;
-			if (config.proxyLoader) proxyExport = (await config.proxyLoader()).default;
-			else proxyExport = config.proxy;
-			const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
-			return await withSpan("timber.proxy", {}, () => serverTiming === "detailed" ? withTiming("proxy", "proxy.ts", proxyFn) : proxyFn());
-		} catch (error) {
-			logProxyError({ error });
-			await fireOnRequestError(error, req, "proxy");
-			if (onPipelineError && error instanceof Error) onPipelineError(error, "proxy");
-			return new Response(null, { status: 500 });
-		}
-	}
-	/**
-	* Build a redirect Response from a RedirectSignal.
-	*
-	* For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
-	* so the client router can perform a soft SPA redirect. A raw 302 would be
-	* turned into an opaque redirect by fetch({redirect:'manual'}), crashing
-	* createFromFetch. See design/19-client-navigation.md.
-	*/
-	function buildRedirectResponse(signal, req, headers) {
-		if ((req.headers.get("Accept") ?? "").includes("text/x-component")) {
-			headers.set("X-Timber-Redirect", signal.location);
-			return new Response(null, {
-				status: 204,
-				headers
-			});
-		}
-		headers.set("Location", signal.location);
-		return new Response(null, {
-			status: signal.status,
-			headers
-		});
-	}
-	async function handleRequest(req, method, path) {
-		const result = canonicalize(new URL(req.url).pathname, stripTrailingSlash);
-		if (!result.ok) return new Response(null, { status: result.status });
-		const canonicalPathname = result.pathname;
-		if (config.matchMetadataRoute) {
-			const metaMatch = config.matchMetadataRoute(canonicalPathname);
-			if (metaMatch) try {
-				if (metaMatch.isStatic) return await serveStaticMetadataFile(metaMatch);
-				const mod = await loadModule(metaMatch.file);
-				if (typeof mod.default !== "function") return new Response("Metadata route must export a default function", { status: 500 });
-				const handlerResult = await mod.default();
-				if (handlerResult instanceof Response) return handlerResult;
-				const contentType = metaMatch.contentType;
-				let body;
-				if (typeof handlerResult === "string") body = handlerResult;
-				else if (contentType === "application/xml") body = serializeSitemap(handlerResult);
-				else if (contentType === "application/manifest+json") body = JSON.stringify(handlerResult, null, 2);
-				else body = typeof handlerResult === "string" ? handlerResult : String(handlerResult);
-				return new Response(body, {
-					status: 200,
-					headers: { "Content-Type": `${contentType}; charset=utf-8` }
-				});
-			} catch (error) {
-				logRenderError({
-					method,
-					path,
-					error
-				});
-				if (onPipelineError && error instanceof Error) onPipelineError(error, "metadata-route");
-				return new Response(null, { status: 500 });
-			}
-		}
-		if (config.autoSitemapHandler) try {
-			const sitemapResponse = await config.autoSitemapHandler(canonicalPathname);
-			if (sitemapResponse) return sitemapResponse;
-		} catch (error) {
-			logRenderError({
-				method,
-				path,
-				error
-			});
-			if (onPipelineError && error instanceof Error) onPipelineError(error, "auto-sitemap");
-			return new Response(null, { status: 500 });
-		}
-		if ((req.headers.get("Accept") ?? "").includes("text/x-component")) {
-			if (!checkVersionSkew(req).ok) {
-				const reloadHeaders = new Headers();
-				applyReloadHeaders(reloadHeaders);
-				return new Response(null, {
-					status: 204,
-					headers: reloadHeaders
-				});
-			}
-		}
-		let match = matchRoute(canonicalPathname);
-		let interception;
-		const sourceUrl = req.headers.get("X-Timber-URL");
-		if (sourceUrl && config.interceptionRewrites?.length) {
-			const intercepted = findInterceptionMatch(canonicalPathname, sourceUrl, config.interceptionRewrites);
-			if (intercepted) {
-				const sourceMatch = matchRoute(intercepted.sourcePathname);
-				if (sourceMatch) {
-					match = sourceMatch;
-					interception = { targetPathname: canonicalPathname };
-				}
-			}
-		}
-		if (!match) {
-			if (config.renderNoMatch) {
-				const responseHeaders = new Headers();
-				return config.renderNoMatch(req, responseHeaders);
-			}
-			return new Response(null, { status: 404 });
-		}
-		const responseHeaders = new Headers();
-		const requestHeaderOverlay = new Headers();
-		responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
-		if (earlyHints) try {
-			await earlyHints(match, req, responseHeaders);
-		} catch {}
-		try {
-			await coerceSegmentParams(match);
-		} catch (error) {
-			if (error instanceof ParamCoercionError) {
-				const leafSegment = match.segments[match.segments.length - 1];
-				if (leafSegment.route && !leafSegment.page) return new Response(null, { status: 404 });
-				if (config.renderNoMatch) return config.renderNoMatch(req, responseHeaders);
-				return new Response(null, { status: 404 });
-			}
-			throw error;
-		}
-		setSegmentParams(match.segmentParams);
-		if (match.middlewareChain.length > 0) {
-			const ctx = {
-				req,
-				requestHeaders: requestHeaderOverlay,
-				headers: responseHeaders,
-				segmentParams: match.segmentParams,
-				earlyHints: (hints) => {
-					for (const hint of hints) {
-						let value;
-						if (hint.as !== void 0) value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
-						else value = `<${hint.href}>; rel=${hint.rel}`;
-						if (hint.crossOrigin !== void 0) value += `; crossorigin=${hint.crossOrigin}`;
-						if (hint.fetchPriority !== void 0) value += `; fetchpriority=${hint.fetchPriority}`;
-						responseHeaders.append("Link", value);
-					}
-				}
-			};
-			try {
-				setMutableCookieContext(true);
-				const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
-				const middlewareResponse = await withSpan("timber.middleware", {}, () => serverTiming === "detailed" ? withTiming("mw", "middleware.ts", chainFn) : chainFn());
-				setMutableCookieContext(false);
-				if (middlewareResponse) {
-					const finalResponse = ensureMutableResponse(middlewareResponse);
-					applyCookieJar(finalResponse.headers);
-					const existingKeys = new Set([...finalResponse.headers.keys()].map((k) => k.toLowerCase()));
-					for (const [key, value] of responseHeaders.entries()) if (!existingKeys.has(key.toLowerCase())) finalResponse.headers.append(key, value);
-					logMiddlewareShortCircuit({
-						method,
-						path,
-						status: finalResponse.status
-					});
-					return finalResponse;
-				}
-				applyRequestHeaderOverlay(requestHeaderOverlay);
-			} catch (error) {
-				setMutableCookieContext(false);
-				if (error instanceof RedirectSignal) {
-					applyCookieJar(responseHeaders);
-					return buildRedirectResponse(error, req, responseHeaders);
-				}
-				if (error instanceof DenySignal) {
-					applyCookieJar(responseHeaders);
-					if (config.renderDenyFallback) try {
-						return await config.renderDenyFallback(error, req, responseHeaders, match);
-					} catch {}
-					return new Response(null, {
-						status: error.status,
-						headers: responseHeaders
-					});
-				}
-				logMiddlewareError({
-					method,
-					path,
-					error
-				});
-				await fireOnRequestError(error, req, "handler");
-				if (onPipelineError && error instanceof Error) onPipelineError(error, "middleware");
-				return new Response(null, { status: 500 });
-			}
-		}
-		applyCookieJar(responseHeaders);
-		try {
-			const renderFn = () => render(req, match, responseHeaders, requestHeaderOverlay, interception);
-			const response = await withSpan("timber.render", { "http.route": canonicalPathname }, () => serverTiming === "detailed" ? withTiming("render", "RSC + SSR render", renderFn) : renderFn());
-			markResponseFlushed();
-			return response;
-		} catch (error) {
-			if (error instanceof DenySignal) {
-				if (config.renderDenyFallback) try {
-					return await config.renderDenyFallback(error, req, responseHeaders, match);
-				} catch {}
-				return new Response(null, {
-					status: error.status,
-					headers: responseHeaders
-				});
-			}
-			if (error instanceof RedirectSignal) return buildRedirectResponse(error, req, responseHeaders);
-			logRenderError({
-				method,
-				path,
-				error
-			});
-			await fireOnRequestError(error, req, "render");
-			if (onPipelineError && error instanceof Error) onPipelineError(error, "render");
-			if (config.renderFallbackError) try {
-				return await config.renderFallbackError(error, req, responseHeaders);
-			} catch {}
-			return new Response(null, { status: 500 });
-		}
-	}
-}
-/**
-* Fire the user's onRequestError hook with request context.
-* Extracts request info from the Request object and calls the instrumentation hook.
-*/
-async function fireOnRequestError(error, req, phase) {
-	const url = new URL(req.url);
-	const headersObj = {};
-	req.headers.forEach((v, k) => {
-		headersObj[k] = v;
-	});
-	await callOnRequestError(error, {
-		method: req.method,
-		path: url.pathname,
-		headers: headersObj
-	}, {
-		phase,
-		routePath: url.pathname,
-		routeType: "page",
-		traceId: getTraceId()
-	});
-}
-/**
-* Apply all Set-Cookie headers from the cookie jar to a Headers object.
-* Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
-*/
-function applyCookieJar(headers) {
-	for (const value of getSetCookieHeaders()) headers.append("Set-Cookie", value);
-}
-/**
-* Ensure a Response has mutable headers so the pipeline can safely append
-* Set-Cookie and Server-Timing entries.
-*
-* `Response.redirect()` and some platform-level responses return objects
-* with immutable headers. Calling `.set()` or `.append()` on them throws
-* `TypeError: immutable`. This helper detects the immutable case by
-* attempting a no-op write and, on failure, clones into a fresh Response
-* with mutable headers.
-*/
-function ensureMutableResponse(response) {
-	try {
-		response.headers.set("X-Timber-Probe", "1");
-		response.headers.delete("X-Timber-Probe");
-		return response;
-	} catch {
-		return new Response(response.body, {
-			status: response.status,
-			statusText: response.statusText,
-			headers: new Headers(response.headers)
-		});
-	}
 }
 //#endregion
 //#region src/server/build-manifest.ts
@@ -2263,7 +2428,11 @@ async function buildElementTree(config) {
 			const LayoutComponent = (await loadModule(segment.layout)).default;
 			if (LayoutComponent) {
 				const slotProps = {};
-				if (segment.slots.size > 0) for (const [slotName, slotNode] of segment.slots) slotProps[slotName] = await buildSlotElement(slotNode, loadModule, createElement, errorBoundaryComponent);
+				const slotNames = Object.keys(segment.slots);
+				if (slotNames.length > 0) for (const slotName of slotNames) {
+					const slotNode = segment.slots[slotName];
+					slotProps[slotName] = await buildSlotElement(slotNode, loadModule, createElement, errorBoundaryComponent);
+				}
 				element = createElement(LayoutComponent, {
 					...slotProps,
 					children: element
@@ -2332,7 +2501,7 @@ function isMdxFile(file) {
 */
 async function wrapWithErrorBoundaries(segment, element, loadModule, createElement, errorBoundaryComponent) {
 	if (segment.statusFiles) {
-		for (const [key, file] of segment.statusFiles) if (key !== "4xx" && key !== "5xx") {
+		for (const [key, file] of Object.entries(segment.statusFiles)) if (key !== "4xx" && key !== "5xx") {
 			const status = parseInt(key, 10);
 			if (!isNaN(status)) {
 				const Component = (await loadModule(file)).default;
@@ -2347,7 +2516,7 @@ async function wrapWithErrorBoundaries(segment, element, loadModule, createEleme
 				});
 			}
 		}
-		for (const [key, file] of segment.statusFiles) if (key === "4xx" || key === "5xx") {
+		for (const [key, file] of Object.entries(segment.statusFiles)) if (key === "4xx" || key === "5xx") {
 			const Component = (await loadModule(file)).default;
 			if (Component) {
 				const categoryStatus = key === "4xx" ? 400 : 500;
@@ -2377,15 +2546,54 @@ async function wrapWithErrorBoundaries(segment, element, loadModule, createEleme
 }
 //#endregion
 //#region src/server/status-code-resolver.ts
-/**
-* Maps legacy file convention names to their corresponding HTTP status codes.
-* Only used in the 4xx component fallback chain.
-*/
-var LEGACY_FILE_TO_STATUS = {
+/** Reverse index: status code → legacy file name. Built once at module load. */
+var STATUS_TO_LEGACY_FILE = Object.fromEntries(Object.entries({
 	"not-found": 404,
 	"forbidden": 403,
 	"unauthorized": 401
-};
+}).map(([name, status]) => [status, name]));
+/**
+* Look up `{statusStr}` then `{categoryKey}` (e.g. "4xx" / "5xx") in a
+* status-file group on a single segment. Shared by all three fallback
+* chains — the only structural difference between component 4xx,
+* component 5xx, and JSON resolution is *which* group is searched and
+* how the per-segment loop is layered around it.
+*/
+function lookupInGroup(group, statusStr, categoryKey, segmentIndex, status) {
+	if (!group) return null;
+	const exact = group[statusStr];
+	if (exact) return {
+		file: exact,
+		status,
+		kind: "exact",
+		segmentIndex
+	};
+	const category = group[categoryKey];
+	if (category) return {
+		file: category,
+		status,
+		kind: "category",
+		segmentIndex
+	};
+	return null;
+}
+/**
+* Look up the legacy convention file (`not-found.tsx` / `forbidden.tsx` /
+* `unauthorized.tsx`) for `status` on a single segment. Returns null if
+* `status` has no legacy mapping or the file isn't present.
+*/
+function lookupLegacy(group, status, segmentIndex) {
+	if (!group) return null;
+	const name = STATUS_TO_LEGACY_FILE[status];
+	if (!name) return null;
+	const file = group[name];
+	return file ? {
+		file,
+		status,
+		kind: "legacy",
+		segmentIndex
+	} : null;
+}
 /**
 * Resolve the status-code file to render for a given HTTP status code.
 *
@@ -2398,108 +2606,58 @@ var LEGACY_FILE_TO_STATUS = {
 * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
 */
 function resolveStatusFile(status, segments, format = "component") {
-	if (status >= 400 && status <= 499) return format === "json" ? resolve4xxJson(status, segments) : resolve4xx(status, segments);
-	if (status >= 500 && status <= 599) return format === "json" ? resolve5xxJson(status, segments) : resolve5xx(status, segments);
-	return null;
+	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);
 }
 /**
-* 4xx component fallback chain (three separate passes):
-*   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
-*   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
-*   Pass 3 — error.tsx (leaf → root)
+* 4xx component fallback chain — three separate full passes leaf→root.
+*
+* The passes must be separate (not interleaved per-segment) so that a
+* root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
+* inverts this and is per-segment: a leaf's `error.tsx` beats a root's
+* `5xx.tsx`. This asymmetry is the only reason these two functions exist
+* separately.
+*
+*   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
+*   Pass 2 — not-found / forbidden / unauthorized (legacyStatusFiles)
+*   Pass 3 — error.tsx                         (error)
 */
 function resolve4xx(status, segments) {
 	const statusStr = String(status);
 	for (let i = segments.length - 1; i >= 0; i--) {
-		const segment = segments[i];
-		if (!segment.statusFiles) continue;
-		const exact = segment.statusFiles.get(statusStr);
-		if (exact) return {
-			file: exact,
-			status,
-			kind: "exact",
-			segmentIndex: i
-		};
-		const category = segment.statusFiles.get("4xx");
-		if (category) return {
-			file: category,
-			status,
-			kind: "category",
-			segmentIndex: i
-		};
+		const r = lookupInGroup(segments[i].statusFiles, statusStr, "4xx", i, status);
+		if (r) return r;
 	}
 	for (let i = segments.length - 1; i >= 0; i--) {
-		const segment = segments[i];
-		if (!segment.legacyStatusFiles) continue;
-		for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) if (legacyStatus === status) {
-			const file = segment.legacyStatusFiles.get(name);
-			if (file) return {
-				file,
-				status,
-				kind: "legacy",
-				segmentIndex: i
-			};
-		}
+		const r = lookupLegacy(segments[i].legacyStatusFiles, status, i);
+		if (r) return r;
 	}
-	for (let i = segments.length - 1; i >= 0; i--) if (segments[i].error) return {
-		file: segments[i].error,
-		status,
-		kind: "error",
-		segmentIndex: i
-	};
-	return null;
-}
-/**
-* 4xx JSON fallback chain (single pass):
-*   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
-*   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
-*/
-function resolve4xxJson(status, segments) {
-	const statusStr = String(status);
 	for (let i = segments.length - 1; i >= 0; i--) {
-		const segment = segments[i];
-		if (!segment.jsonStatusFiles) continue;
-		const exact = segment.jsonStatusFiles.get(statusStr);
-		if (exact) return {
-			file: exact,
+		const errorFile = segments[i].error;
+		if (errorFile) return {
+			file: errorFile,
 			status,
-			kind: "exact",
-			segmentIndex: i
-		};
-		const category = segment.jsonStatusFiles.get("4xx");
-		if (category) return {
-			file: category,
-			status,
-			kind: "category",
+			kind: "error",
 			segmentIndex: i
 		};
 	}
 	return null;
 }
 /**
-* 5xx component fallback chain (single pass, per-segment):
-*   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+* 5xx component fallback chain — single pass, per-segment leaf→root.
+*
+* At each segment: {status}.tsx → 5xx.tsx → error.tsx. A leaf's
+* `error.tsx` therefore beats a root's `5xx.tsx`, which is the
+* intentional inverse of the 4xx chain.
 */
 function resolve5xx(status, segments) {
 	const statusStr = String(status);
 	for (let i = segments.length - 1; i >= 0; i--) {
 		const segment = segments[i];
-		if (segment.statusFiles) {
-			const exact = segment.statusFiles.get(statusStr);
-			if (exact) return {
-				file: exact,
-				status,
-				kind: "exact",
-				segmentIndex: i
-			};
-			const category = segment.statusFiles.get("5xx");
-			if (category) return {
-				file: category,
-				status,
-				kind: "category",
-				segmentIndex: i
-			};
-		}
+		const r = lookupInGroup(segment.statusFiles, statusStr, "5xx", i, status);
+		if (r) return r;
 		if (segment.error) return {
 			file: segment.error,
 			status,
@@ -2510,29 +2668,18 @@ function resolve5xx(status, segments) {
 	return null;
 }
 /**
-* 5xx JSON fallback chain (single pass):
-*   At each segment (leaf → root): {status}.json → 5xx.json
-*   No error.tsx equivalent — JSON chain terminates at category catch-all.
+* JSON fallback chain (for both 4xx and 5xx) — single pass leaf→root.
+*
+* At each segment: {status}.json → {category}.json. No legacy compat,
+* no error.tsx — the JSON chain terminates at the category catch-all
+* and the caller falls back to a bare-JSON framework default.
 */
-function resolve5xxJson(status, segments) {
+function resolveJson(status, segments) {
 	const statusStr = String(status);
+	const categoryKey = status >= 500 ? "5xx" : "4xx";
 	for (let i = segments.length - 1; i >= 0; i--) {
-		const segment = segments[i];
-		if (!segment.jsonStatusFiles) continue;
-		const exact = segment.jsonStatusFiles.get(statusStr);
-		if (exact) return {
-			file: exact,
-			status,
-			kind: "exact",
-			segmentIndex: i
-		};
-		const category = segment.jsonStatusFiles.get("5xx");
-		if (category) return {
-			file: category,
-			status,
-			kind: "category",
-			segmentIndex: i
-		};
+		const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
+		if (r) return r;
 	}
 	return null;
 }