@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/pipeline.ts

@@ -4,24 +4,23 @@
  * 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.
+ * The phase functions live in `pipeline-phases.ts` so each phase can be
+ * tested in isolation. The terminal `outcomeToResponse` translator and
+ * stateless helpers live in `pipeline-phases.ts` and `pipeline-helpers.ts`
+ * respectively. This file owns only the public type surface and the
+ * `createPipeline` entry point: trace ID setup, request-context ALS,
+ * Server-Timing wrapping, and the activeRequests counter.
  *
  * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
  * and design/17-logging.md §"Production Logging"
  */
 
-import { canonicalize } from './canonicalize.js';
-import { runProxy, type ProxyExport } from './proxy.js';
-import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
-import { runWithTimingCollector, withTiming, getServerTimingHeader } from './server-timing.js';
-import {
-  runWithRequestContext,
-  applyRequestHeaderOverlay,
-  setMutableCookieContext,
-  getSetCookieHeaders,
-  markResponseFlushed,
-} from './request-context.js';
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { ProxyExport } from './proxy.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import { runWithTimingCollector, getServerTimingHeader } from './server-timing.ts';
+import { wrapResponseWithStreamTiming } from './stream-utils.ts';
+import { runWithRequestContext } from './request-context.ts';
 import {
   generateTraceId,
   runWithTraceId,
@@ -29,34 +28,44 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  traceId,
-} from './tracing.js';
-import {
-  logRequestReceived,
-  logRequestCompleted,
-  logSlowRequest,
-  logProxyError,
-  logMiddlewareError,
-  logMiddlewareShortCircuit,
-  logRenderError,
-} from './logger.js';
-import { callOnRequestError } from './instrumentation.js';
-import { RedirectSignal, DenySignal } from './primitives.js';
-import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
-import { findInterceptionMatch } from './pipeline-interception.js';
-import type { MiddlewareContext } from './types.js';
-import type { SegmentNode } from '#/routing/types.js';
+} from './tracing.ts';
+import { logRequestReceived, logRequestCompleted, logSlowRequest } from './logger.ts';
+import { DenySignal } from './primitives.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { makeProxyResolver } from './pipeline-helpers.ts';
+import { handleRequest, runProxyPhase } from './pipeline-phases.ts';
+import { outcomeToResponse } from './pipeline-outcome.ts';
+import { canonicalize } from './canonicalize.ts';
+import { enforceRscCacheKey, hardenRscPayloadResponse } from './rsc-cache-key-guard.ts';
+import { stripHeadBody } from './head-response.ts';
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.ts';
+import { isDebug } from './debug.ts';
 
 // ─── Route Match Result ────────────────────────────────────────────────────
 
-/** Result of matching a canonical pathname against the route tree. */
+/**
+ * Result of matching a canonical pathname against the route tree.
+ *
+ * `segments` is the runtime (`ManifestFile`-specialized) shape — the same
+ * nodes carried in the virtual route manifest. TIM-863 unified this: the
+ * matcher produces `ManifestSegmentNode[]` directly and every consumer
+ * (render, slots, params coercion, early hints, deny fallback) sees the
+ * same structural type with no `as unknown as` laundering.
+ */
 export interface RouteMatch {
   /** The matched segment chain from root to leaf. */
-  segments: SegmentNode[];
-  /** Extracted route params (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** The leaf segment's middleware.ts export, if any. */
-  middleware?: MiddlewareFn;
+  segments: ManifestSegmentNode[];
+  /** Extracted segment params (catch-all segments produce string[]). Post-coercion, values may be non-string (TIM-1347). */
+  segmentParams: CoercedParams;
+  /**
+   * Raw segment params before codec coercion. Always string or string[].
+   * Used by slot resolution to reconstruct URL parts — coerced params may
+   * have been transformed by codecs and are unsuitable for URL matching.
+   * Set by the pipeline before coercion runs.
+   */
+  rawSegmentParams?: Record<string, string | string[]>;
+  /** Middleware chain from the segment tree, ordered root-to-leaf. */
+  middlewareChain: MiddlewareFn[];
 }
 
 /** Function that matches a canonical pathname to a route. */
@@ -65,7 +74,7 @@ export type RouteMatcher = (pathname: string) => RouteMatch | null;
 /** Function that matches a canonical pathname to a metadata route. */
 export type MetadataRouteMatcher = (
   pathname: string
-) => import('./route-matcher.js').MetadataRouteMatch | null;
+) => import('./route-matcher.ts').MetadataRouteMatch | null;
 
 /** Context for intercepting route resolution (modal pattern). */
 export interface InterceptionContext {
@@ -91,11 +100,32 @@ export type EarlyHintsEmitter = (
 
 // ─── Pipeline Configuration ────────────────────────────────────────────────
 
+/**
+ * Proxy source — a tagged union so the choice between "already-resolved
+ * export" and "lazy HMR-friendly loader" is encoded in the type, not
+ * inferred per-request.
+ *
+ * - `static` — the proxy export is already resolved (production, tests).
+ * - `lazy`   — a loader is called per-request for HMR freshness (dev).
+ *
+ * `PipelineConfig.proxy` also accepts a bare `ProxyExport` (a function or
+ * function array) as shorthand for the static variant — convenient for tests
+ * that construct a `createPipeline` config inline. Omit the field entirely
+ * when the app has no `proxy.ts`.
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware".
+ */
+export type ProxyConfig =
+  | { kind: 'static'; export: ProxyExport }
+  | { kind: 'lazy'; loader: () => Promise<{ default: ProxyExport }> };
+
 export interface PipelineConfig {
-  /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
-  proxy?: ProxyExport;
-  /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
-  proxyLoader?: () => Promise<{ default: ProxyExport }>;
+  /**
+   * proxy.ts source. Undefined if the app has no proxy.ts. Accepts either a
+   * tagged `ProxyConfig` (canonical) or a bare `ProxyExport` as sugar for the
+   * static variant.
+   */
+  proxy?: ProxyConfig | ProxyExport;
   /** Route matcher — resolves a canonical pathname to a RouteMatch. */
   matchRoute: RouteMatcher;
   /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
@@ -115,14 +145,36 @@ export interface PipelineConfig {
    * Generated at build time from intercepting route directories.
    * See design/07-routing.md §"Intercepting Routes"
    */
-  interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
+  interceptionRewrites?: import('../routing/interception.ts').InterceptionRewrite[];
+  /**
+   * Resolver for children-path interceptions — the sibling layout swap.
+   *
+   * Separate from `matchRoute` because it addresses the owner directory by
+   * tree path rather than by pathname, which needs the manifest tree itself.
+   * Omitting it disables the `'children'` interception shape and leaves the
+   * canonical route rendering, which is the fail-safe outcome.
+   *
+   * See design/07-routing.md §"Intercepting Routes"
+   */
+  matchInterceptedRoute?: import('./children-interception.ts').InterceptedRouteMatcher;
+  /**
+   * Control Server-Timing header output.
+   *
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render).
+   * - `'total'` — single `total;dur=N` entry (production-safe).
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'total'`.
+   */
+  serverTiming?: 'detailed' | 'total' | false;
   /**
-   * Emit Server-Timing header on responses for Chrome DevTools visibility.
-   * Only enable in dev mode — exposes internal timing data.
+   * Auto-generated sitemap handler. When provided, the pipeline intercepts
+   * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
+   * function. Returns a Response or null (pass-through to regular routing).
    *
-   * Default: false (production-safe).
+   * See design/16-metadata.md §"Auto-generated Sitemap"
    */
-  enableServerTiming?: boolean;
+  autoSitemapHandler?: (pathname: string) => Promise<Response | null>;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -131,6 +183,38 @@ export interface PipelineConfig {
    * Undefined in production — zero overhead.
    */
   onPipelineError?: (error: Error, phase: string) => void;
+
+  /**
+   * Dev error handler with RSC debug context — set by the dev server after
+   * the RSC entry module is imported. `onPipelineError` resolves debug
+   * components from ALS and delegates to this handler.
+   *
+   * This is a mutable property (not a constructor argument) because the dev
+   * server imports the RSC entry module first (which constructs the config),
+   * then wires in the overlay handler. Moving the state here (from a
+   * module-level `let`) keeps it co-located with the config it belongs to
+   * and makes it visible in tests without module-level mutation.
+   *
+   * Undefined in production — zero overhead.
+   */
+  devPipelineErrorHandler?: (
+    error: Error,
+    phase: string,
+    debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
+  ) => void;
+
+  /**
+   * HMR connection options for dev-only HTML pages (dev 404 page, fallback
+   * error page) — set by the dev server after the RSC entry module is
+   * imported, like `devPipelineErrorHandler`. The RSC environment can't
+   * read the Vite server config (separate module graph), so the dev server
+   * plumbs the resolved HMR endpoint (protocol/host/port/path/token) here
+   * for the pages' auto-reload WebSocket. See TIM-1067.
+   *
+   * Undefined in production — zero overhead.
+   */
+  devHmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions;
+
   /**
    * Fallback error renderer — called when a catastrophic error escapes the
    * render phase. Produces an HTML Response instead of a bare empty 500.
@@ -147,6 +231,51 @@ export interface PipelineConfig {
     req: Request,
     responseHeaders: Headers
   ) => Response | Promise<Response>;
+  /**
+   * Fallback deny page renderer — called when a DenySignal escapes from
+   * middleware or the render phase. Renders the appropriate status-code
+   * page (403.tsx, 404.tsx, etc.) instead of returning a bare empty response.
+   *
+   * If this function throws, the pipeline falls back to a bare
+   * `new Response(null, { status: denyStatus })`.
+   */
+  renderDenyFallback?: (
+    deny: DenySignal,
+    req: Request,
+    responseHeaders: Headers,
+    /**
+     * The matched route, if available. Provided by both the middleware-stage
+     * and render-stage catch blocks (matching runs before middleware). When
+     * present, the renderer should resolve the deny status file against the
+     * matched chain so colocated `403.tsx`/`4xx.tsx`/`401.json` files are
+     * picked up. Falls back to the root-only chain when omitted (e.g. for
+     * deny()s thrown before route matching could complete). See TIM-822.
+     */
+    match?: RouteMatch
+  ) => Response | Promise<Response>;
+
+  /**
+   * Server action dispatch — called after proxy.ts runs for POST requests
+   * that look like server actions. Returns a Response if the request was
+   * handled as an action, or null to fall through to normal routing.
+   *
+   * `canonicalPath` is the already-decoded canonical pathname — the same
+   * value that `handleRequest` and `matchRoute` use. Do NOT re-derive it
+   * from `req.url` (which re-encodes).
+   *
+   * The `reenter` parameter is the full pipeline function (including proxy,
+   * ALS, tracing) for the no-JS validation rerender path — the synthetic
+   * GET flows through the complete pipeline.
+   *
+   * Moved into the pipeline (TIM-1213) so proxy.ts runs on action POSTs,
+   * matching the design doc contract: "proxy.ts runs on every request,
+   * no exclusions."
+   */
+  dispatchAction?: (
+    req: Request,
+    canonicalPath: string,
+    reenter: (req: Request) => Promise<Response>
+  ) => Promise<Response | null>;
 }
 
 // ─── Pipeline ──────────────────────────────────────────────────────────────
@@ -154,26 +283,31 @@ export interface PipelineConfig {
 /**
  * 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.
  */
 export function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response> {
-  const {
-    proxy,
-    matchRoute,
-    render,
-    earlyHints,
-    stripTrailingSlash = true,
-    slowRequestMs = 3000,
-    enableServerTiming = false,
-    onPipelineError,
-  } = config;
+  // Resolve the proxy source once. The request hot path calls this closure
+  // directly with no discriminant check — the branch is taken here during
+  // setup. For the lazy variant, `loader()` still runs per-request so HMR
+  // continues to re-import the user's proxy.ts.
+  const proxyResolver = makeProxyResolver(config.proxy);
+  const slowRequestMs = config.slowRequestMs ?? 3000;
+  const serverTiming = config.serverTiming ?? 'total';
 
   // Concurrent request counter — tracks how many requests are in-flight.
   // Logged with each request for diagnosing resource contention.
   let activeRequests = 0;
 
-  return async (req: Request): Promise<Response> => {
+  // Self-reference for re-entry — the no-JS validation rerender path
+  // passes a synthetic GET back through the full pipeline (including
+  // proxy, ALS, tracing). The inner closure captures `pipelineFn` by
+  // name; by the time it's invoked, the const binding is initialized.
+  const pipelineFn = async (req: Request): Promise<Response> => {
     const url = new URL(req.url);
     const method = req.method;
     const path = url.pathname;
@@ -186,7 +320,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     const traceIdValue = generateTraceId();
 
     return runWithTraceId(traceIdValue, async () => {
-      // Establish request context ALS scope so headers() and cookies() work
+      // Establish request context ALS scope so getHeaders() and getCookies() work
       // throughout the entire request lifecycle (proxy, middleware, render).
       return runWithRequestContext(req, async () => {
         // In dev mode, wrap with timing collector for Server-Timing header.
@@ -205,36 +339,165 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
                 replaceTraceId(otelIds.traceId, otelIds.spanId);
               }
 
+              // Stage 0: Canonicalize URL at the outer boundary — before
+              // proxy.ts sees the request. Every layer (proxy, middleware,
+              // access, render) must see the same canonical path.
+              // See design/07-routing.md §"URL Canonicalization & Security".
+              const stripTrailingSlash = config.stripTrailingSlash ?? true;
+              const canonResult = canonicalize(url.pathname, stripTrailingSlash);
+              if (!canonResult.ok) {
+                if (isDebug()) {
+                  console.warn(
+                    `[timber] URL canonicalization rejected ${method} ${url.pathname} — responding with ${canonResult.status}\n` +
+                      `  This usually means the URL contains encoded separators (%2f, %5c),\n` +
+                      `  null bytes (%00), path traversal (..), or malformed percent-encoding.`
+                  );
+                }
+                return new Response(null, { status: canonResult.status });
+              }
+              const canonicalPath = canonResult.pathname;
+
+              // Construct a Request with the canonical URL so proxy.ts sees
+              // the same path that route matching will use. This prevents
+              // auth bypass via /admin/, /%61dmin, etc.
+              let canonicalReq = req;
+              if (url.pathname !== canonicalPath) {
+                const canonicalUrl = new URL(req.url);
+                canonicalUrl.pathname = canonicalPath;
+                canonicalReq = new Request(canonicalUrl.toString(), req);
+              }
+
+              // Build the inner handler — runs after proxy, before route
+              // matching. Checks for server action POSTs and dispatches them
+              // without entering the route match → middleware → render chain.
+              // Falls through to handleRequest for normal route handling.
+              // TIM-1213: action dispatch is now INSIDE the pipeline so
+              // proxy.ts runs on every request, including action POSTs.
+              const innerHandler = async (): Promise<Response> => {
+                if (config.dispatchAction) {
+                  const actionResult = await config.dispatchAction(
+                    canonicalReq,
+                    canonicalPath,
+                    pipelineFn
+                  );
+                  if (actionResult) return actionResult;
+                }
+                return handleRequest(config, canonicalReq, method, canonicalPath, true);
+              };
+
               let result: Response;
-              if (proxy || config.proxyLoader) {
-                result = await runProxyPhase(req, method, path);
+              if (proxyResolver) {
+                const outcome = await runProxyPhase(
+                  config,
+                  proxyResolver,
+                  canonicalReq,
+                  method,
+                  canonicalPath,
+                  innerHandler
+                );
+                result = await outcomeToResponse(config, outcome, {
+                  req: canonicalReq,
+                  method,
+                  path: canonicalPath,
+                });
               } else {
-                result = await handleRequest(req, method, path);
+                result = await innerHandler();
               }
 
               // Set response status on the root span before it ends —
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Append Server-Timing header.
-              // In dev mode: detailed per-phase breakdown (proxy, middleware, render).
-              // In production: single total duration — safe to expose, no phase names.
-              // Response.redirect() creates immutable headers, so we must
-              // ensure mutability before writing Server-Timing.
-              if (enableServerTiming) {
-                const serverTiming = getServerTimingHeader();
-                if (serverTiming) {
-                  result = ensureMutableResponse(result);
-                  result.headers.set('Server-Timing', serverTiming);
+              // Vary on exactly the headers the `_rsc` cache key hashes.
+              //
+              // Those two mechanisms answer the same question — which request
+              // headers change this response — so they are the same list, not
+              // two lists that happen to agree. A separate hand-written list
+              // here drifted from `RSC_KEY_HEADERS` the moment the key set
+              // grew, and the drift is invisible: `Vary` is the *fallback*
+              // layer, used only when a cache omits the query from its key,
+              // which is precisely when nobody is watching (TIM-1268).
+              //
+              // Why any of it: without `Vary: Accept` a shared cache may serve
+              // an RSC Flight payload to a browser expecting HTML, or the
+              // reverse (GHSA-wfc6-r584-vfw7, design/13-security.md). The
+              // `_rsc` param puts that distinction in the URL, so correctness
+              // no longer *depends* on `Vary` — which is opt-in configuration
+              // on Cloudflare and CloudFront. `Vary` covers the requests that
+              // arrive without the param: a stripped query, a hand-rolled
+              // client.
+              //
+              // It costs no hit rate. Document requests send no `X-Timber-*`
+              // header at all, so they collapse to a single cache key; payload
+              // requests are already fragmented by these same values via the
+              // 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(', ')
+                );
+              }
+
+              // A request may only claim an `_rsc` cache key that matches its
+              // own headers. The key is predictable by design, so without this
+              // a caller could render its own variant under another client's
+              // key and have a shared cache store it there (TIM-1268).
+              await enforceRscCacheKey(canonicalReq, result);
+
+              // Flight payloads must never be sniffable into a renderable
+              // type — applied at this single exit so every producer is
+              // covered, not just the success path (TIM-1268).
+              hardenRscPayloadResponse(result);
+
+              // A HEAD response carries the headers its GET would produce and
+              // no content (RFC 9110 §9.3.2). Applied at this single exit so
+              // every response shape is covered — page render, API route,
+              // metadata route, deny page, error page, proxy short-circuit —
+              // rather than per-renderer, where it was missing for page
+              // renders entirely (TIM-1324). The render still runs: the
+              // headers have to be the ones a GET would have sent.
+              result = stripHeadBody(result, method);
+
+              // Append Server-Timing header based on configured mode.
+              // Header mutability is guaranteed by the producer-side clone
+              // in `outcomeToResponse` and the metadata-route / auto-sitemap
+              // user-handler clones in `handleRequest`, so we can write
+              // directly without a runtime probe. See TIM-866.
+              if (serverTiming === 'detailed') {
+                // Detailed: per-phase breakdown (proxy, middleware, render).
+                const timingHeader = getServerTimingHeader();
+                if (timingHeader) {
+                  result.headers.set('Server-Timing', timingHeader);
                 }
-              } else {
-                // Production: emit total request duration only.
-                // No phase breakdown — prevents information disclosure
-                // while giving browser DevTools useful timing data.
+              } else if (serverTiming === 'total') {
+                // Total only: single `total;dur=N` — no phase names.
+                // Prevents information disclosure while giving browser
+                // DevTools useful timing data.
                 const totalMs = Math.round(performance.now() - startTime);
-                result = ensureMutableResponse(result);
                 result.headers.set('Server-Timing', `total;dur=${totalMs}`);
               }
+              // serverTiming === false: no header at all
+
+              // Wrap the response body with stream-lifecycle timing when
+              // detailed mode is on. Logs firstChunk/lastChunk/maxGap/close
+              // on stream close — measures the post-flush stream tail that
+              // the Server-Timing header can't capture (TIM-1106).
+              if (serverTiming === 'detailed' && result.body) {
+                result = new Response(wrapResponseWithStreamTiming(result.body, startTime), {
+                  status: result.status,
+                  statusText: result.statusText,
+                  headers: result.headers,
+                });
+              }
 
               return result;
             }
@@ -254,319 +517,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           return response;
         };
 
-        return enableServerTiming ? runWithTimingCollector(runRequest) : runRequest();
+        return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
       });
     });
   };
 
-  async function runProxyPhase(req: Request, method: string, path: string): Promise<Response> {
-    try {
-      // Resolve the proxy export. When a proxyLoader is provided (lazy import),
-      // it is called per-request so HMR updates in dev take effect immediately.
-      let proxyExport: ProxyExport;
-      if (config.proxyLoader) {
-        const mod = await config.proxyLoader();
-        proxyExport = mod.default;
-      } else {
-        proxyExport = config.proxy!;
-      }
-      const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
-      return await withSpan('timber.proxy', {}, () =>
-        enableServerTiming ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
-      );
-    } catch (error) {
-      // Uncaught proxy.ts error → bare HTTP 500
-      logProxyError({ error });
-      await fireOnRequestError(error, req, 'proxy');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'proxy');
-      return new Response(null, { status: 500 });
-    }
-  }
-
-  async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
-    // Stage 1: URL canonicalization
-    const url = new URL(req.url);
-    const result = canonicalize(url.pathname, stripTrailingSlash);
-    if (!result.ok) {
-      return new Response(null, { status: result.status });
-    }
-    const canonicalPathname = result.pathname;
-
-    // Stage 1b: Metadata route matching — runs before regular route matching.
-    // Metadata routes skip middleware.ts and access.ts (public endpoints for crawlers).
-    // See design/16-metadata.md §"Pipeline Integration"
-    if (config.matchMetadataRoute) {
-      const metaMatch = config.matchMetadataRoute(canonicalPathname);
-      if (metaMatch) {
-        try {
-          // Static metadata files (.xml, .txt, .png, .ico, etc.) are served
-          // directly from disk. Dynamic metadata routes (.ts, .tsx) export a
-          // handler function that generates the response.
-          if (metaMatch.isStatic) {
-            return await serveStaticMetadataFile(metaMatch);
-          }
-
-          const mod = (await metaMatch.file.load()) as { default?: Function };
-          if (typeof mod.default !== 'function') {
-            return new Response('Metadata route must export a default function', { status: 500 });
-          }
-          const handlerResult = await mod.default();
-          // If the handler returns a Response, use it directly
-          if (handlerResult instanceof Response) {
-            return handlerResult;
-          }
-          // Otherwise, serialize based on content type
-          const contentType = metaMatch.contentType;
-          let body: string;
-          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 });
-        }
-      }
-    }
-
-    // Stage 2: Route matching
-    let match = matchRoute(canonicalPathname);
-    let interception: InterceptionContext | undefined;
-
-    // Stage 2a: Intercepting route resolution (modal pattern).
-    // On soft navigation, check if an intercepting route should render instead.
-    // The client sends X-Timber-URL with the current pathname (where they're
-    // navigating FROM). If a rewrite matches, re-route to the source URL so
-    // the source layout renders with the intercepted content in the slot.
-    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) {
-      // No route matched — render 404.tsx in root layout if available,
-      // otherwise fall back to a bare 404 Response.
-      if (config.renderNoMatch) {
-        const responseHeaders = new Headers();
-        return config.renderNoMatch(req, responseHeaders);
-      }
-      return new Response(null, { status: 404 });
-    }
-
-    // Response and request header containers — created before early hints so
-    // the emitter can append Link headers (e.g. for Cloudflare CDN → 103).
-    const responseHeaders = new Headers();
-    const requestHeaderOverlay = new Headers();
-
-    // Set Cache-Control for dynamic HTML responses. Without this header,
-    // CDNs (particularly Cloudflare) may attempt to buffer/process the
-    // response differently, causing intermittent multi-second delays.
-    // This matches Next.js's default behavior.
-    responseHeaders.set('Cache-Control', 'private, no-cache, no-store, max-age=0, must-revalidate');
-
-    // Stage 2b: 103 Early Hints (before middleware, after match)
-    // Fires before middleware so the browser can begin fetching critical
-    // assets while middleware runs. Non-fatal — a failing emitter never
-    // blocks the request.
-    if (earlyHints) {
-      try {
-        await earlyHints(match, req, responseHeaders);
-      } catch {
-        // Early hints failure is non-fatal
-      }
-    }
-
-    // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
-    if (match.middleware) {
-      const ctx: MiddlewareContext = {
-        req,
-        requestHeaders: requestHeaderOverlay,
-        headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
-        earlyHints: (hints) => {
-          for (const hint of hints) {
-            let value = `<${hint.href}>; rel=${hint.rel}`;
-            if (hint.as !== undefined) value += `; as=${hint.as}`;
-            if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
-            if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
-            responseHeaders.append('Link', value);
-          }
-        },
-      };
-
-      try {
-        // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
-        setMutableCookieContext(true);
-        const middlewareFn = () => runMiddleware(match.middleware!, ctx);
-        const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          enableServerTiming ? withTiming('mw', 'middleware.ts', middlewareFn) : middlewareFn()
-        );
-        setMutableCookieContext(false);
-        if (middlewareResponse) {
-          // Apply cookie jar to short-circuit response.
-          // Response.redirect() creates immutable headers, so ensure
-          // mutability before appending Set-Cookie entries.
-          const finalResponse = ensureMutableResponse(middlewareResponse);
-          applyCookieJar(finalResponse.headers);
-          logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
-          return finalResponse;
-        }
-        // Middleware succeeded without short-circuiting — apply any
-        // injected request headers so headers() returns them downstream.
-        applyRequestHeaderOverlay(requestHeaderOverlay);
-      } catch (error) {
-        setMutableCookieContext(false);
-        // RedirectSignal from middleware → HTTP redirect (not an error).
-        // For RSC payload requests (client navigation), return 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.
-        if (error instanceof RedirectSignal) {
-          applyCookieJar(responseHeaders);
-          const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-          if (isRsc) {
-            responseHeaders.set('X-Timber-Redirect', error.location);
-            return new Response(null, { status: 204, headers: responseHeaders });
-          }
-          responseHeaders.set('Location', error.location);
-          return new Response(null, { status: error.status, headers: responseHeaders });
-        }
-        // DenySignal from middleware → HTTP deny status
-        if (error instanceof DenySignal) {
-          return new Response(null, { status: error.status });
-        }
-        // Middleware throw → HTTP 500 (middleware runs before rendering,
-        // no error boundary to catch it)
-        logMiddlewareError({ method, path, error });
-        await fireOnRequestError(error, req, 'handler');
-        if (onPipelineError && error instanceof Error) onPipelineError(error, 'middleware');
-        return new Response(null, { status: 500 });
-      }
-    }
-
-    // Apply cookie jar to response headers before render commits them.
-    // Middleware may have set cookies; they need to be on responseHeaders
-    // before flushResponse creates the Response object.
-    applyCookieJar(responseHeaders);
-
-    // Stage 4: Render (access gates + element tree + renderToReadableStream)
-    try {
-      const renderFn = () =>
-        render(req, match, responseHeaders, requestHeaderOverlay, interception);
-      const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        enableServerTiming ? withTiming('render', 'RSC + SSR render', renderFn) : renderFn()
-      );
-      markResponseFlushed();
-      return response;
-    } catch (error) {
-      // DenySignal leaked from render (e.g. notFound() in metadata()).
-      // Return the deny status code instead of 500.
-      if (error instanceof DenySignal) {
-        return new Response(null, { status: error.status });
-      }
-      // RedirectSignal leaked from render — honour the redirect.
-      if (error instanceof RedirectSignal) {
-        responseHeaders.set('Location', error.location);
-        return new Response(null, { status: error.status, headers: responseHeaders });
-      }
-      logRenderError({ method, path, error });
-      await fireOnRequestError(error, req, 'render');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'render');
-      // Try fallback error page before bare 500
-      if (config.renderFallbackError) {
-        try {
-          return await config.renderFallbackError(error, req, responseHeaders);
-        } catch {
-          // Fallback rendering itself failed — fall through to bare 500
-        }
-      }
-      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: unknown,
-  req: Request,
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
-): Promise<void> {
-  const url = new URL(req.url);
-  const headersObj: Record<string, string> = {};
-  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: traceId() }
-  );
-}
-
-// ─── Cookie Helpers ──────────────────────────────────────────────────────
-
-/**
- * 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: Headers): void {
-  for (const value of getSetCookieHeaders()) {
-    headers.append('Set-Cookie', value);
-  }
-}
-
-// ─── Immutable Response Helpers ──────────────────────────────────────────
-
-/**
- * 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: Response): Response {
-  try {
-    // Probe mutability with a benign operation that we immediately undo.
-    // We pick a header name that is extremely unlikely to collide with
-    // anything meaningful and delete it right away.
-    response.headers.set('X-Timber-Probe', '1');
-    response.headers.delete('X-Timber-Probe');
-    return response;
-  } catch {
-    // Headers are immutable — rebuild with mutable headers.
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers: new Headers(response.headers),
-    });
-  }
+  return pipelineFn;
 }