@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/server/pipeline-interception.ts

@@ -9,33 +9,102 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
-/** Result of a successful interception match. */
-export interface InterceptionMatchResult {
-  /** The pathname to re-match (the source/intercepting route's parent). */
-  sourcePathname: string;
-}
+import { classifyUrlSegment } from '../routing/segment-classify.ts';
+import type { InterceptionRewrite } from '../routing/interception.ts';
+import { computeSegmentTreePaths } from '../routing/segment-keys.ts';
+import { isRscRequest } from '../shared/rsc-media-type.ts';
+import { canonicalize } from './canonicalize.ts';
+import { parseClientStateTree } from './state-tree-diff.ts';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.ts';
 
 /**
  * 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).
+ * 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.
  *
- * Returns the source pathname to re-match if interception applies, or null.
+ * 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".
  */
 export function findInterceptionMatch(
   targetPathname: string,
-  sourceUrl: string,
-  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
-): InterceptionMatchResult | null {
-  for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix
-    if (!sourceUrl.startsWith(rewrite.interceptingPrefix)) continue;
+  resolveSourceScopes: () => ReadonlySet<string>[] | null,
+  rewrites: InterceptionRewrite[]
+): InterceptionRewrite | null {
+  // Dynamic segments in the pattern match any single URL segment. Collected up
+  // front rather than inside the channel loop so a pattern is matched once
+  // however many channels are tried — and the common case, no rewrite matching
+  // at all, costs exactly the same scan it always did and resolves no scope.
+  const candidates = rewrites.filter((rewrite) =>
+    pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)
+  );
+  if (candidates.length === 0) return null;
+
+  // Nothing at all is known about the source tree — no scope can contain
+  // anything, so no rewrite can apply.
+  const scopes = resolveSourceScopes();
+  if (!scopes) return null;
 
-    // Check if the target URL matches the intercepted pattern.
-    // Dynamic segments in the pattern match any single URL segment.
-    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
-      return { sourcePathname: rewrite.interceptingPrefix };
+  // `candidates` is deepest scope first (`collectInterceptionRewrites`), so
+  // within one channel the first hit is the innermost owner that channel
+  // reports. Channels are tried in order, so a scope the client says it has
+  // mounted always beats one only the address bar implies.
+  for (const scope of scopes) {
+    for (const rewrite of candidates) {
+      if (scope.has(rewrite.interceptingScope)) return rewrite;
     }
   }
   return null;
@@ -53,24 +122,164 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   let pi = 0;
   for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
+    const seg = classifyUrlSegment(patternParts[i]);
 
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
+    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;
     }
+  }
 
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) return false;
-      pi++;
-      continue;
-    }
+  return pi === pathParts.length;
+}
 
-    // Static — must match exactly
-    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
-    pi++;
+// ─── Pipeline Resolution ──────────────────────────────────────────────────
+
+/**
+ * Resolve which route renders a soft navigation that an intercepting route
+ * may claim. Returns the canonical match unchanged when no rewrite applies.
+ *
+ * Runs during route setup, so anything it throws is a `'setup'` outcome.
+ */
+export function resolveInterceptedRoute(
+  config: PipelineConfig,
+  req: Request,
+  canonicalPathname: string,
+  canonicalMatch: RouteMatch | null
+): { match: RouteMatch | null; interception?: InterceptionContext } {
+  const stripTrailingSlash = config.stripTrailingSlash ?? true;
+  let match = canonicalMatch;
+  let interception: InterceptionContext | undefined;
+
+  // Stage 2a: Intercepting route resolution (modal pattern).
+  // Only honored on RSC client-navigation requests (Accept: text/x-component)
+  // to prevent spoofing from plain HTML navigations or raw HTTP clients.
+  // The header value must be a valid relative pathname — reject schemes,
+  // authority, and control characters. Canonicalize before matching.
+  if (isRscRequest(req) && config.interceptionRewrites?.length) {
+    const rawSourceUrl = req.headers.get('X-Timber-URL');
+    const validatedSourceUrl = rawSourceUrl
+      ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
+      : null;
+    if (validatedSourceUrl) {
+      // The scope of an interception is the segment that owns the intercepting
+      // slot, so the guard asks whether the route the user is LEAVING renders
+      // that segment. Two independent answers to "what is on screen?", tried in
+      // order — deferred behind a thunk so neither runs unless a rewrite's
+      // target pattern matches.
+      //
+      // 1. What the client says it has mounted (X-Timber-State-Tree
+      //    `treePaths`). Authoritative about tree shape and nothing else.
+      // 2. What re-matching X-Timber-URL implies. Correct while the address bar
+      //    still holds the source page, which stops being true the moment a
+      //    modal is open — the address is then the *intercepted* URL and
+      //    re-matching it resolves through whichever group owns the canonical
+      //    page (TIM-1282).
+      //
+      // Neither is trusted: both are client-supplied, and satisfying the scope
+      // only selects which build-time rewrite applies. The rendered pathname is
+      // always the rewrite's own `interceptingPrefix`, the server re-derives the
+      // rendered chain from it below, and every access.ts runs regardless.
+      //
+      // They are handed over as two sets in that order rather than one union:
+      // each describes a single rendered chain, and only within one chain does
+      // "the deepest scope" name the innermost owner (TIM-1318). Unioned, a
+      // deeper scope from the address-implied canonical branch — which after
+      // (2) may be a route group the client never mounted — would outrank the
+      // owner actually on screen.
+      const resolveSourceScopes = () => {
+        const mounted = new Set(parseClientStateTree(req)?.treePaths ?? []);
+        const sourceRoute = config.matchRoute(validatedSourceUrl);
+        const addressed = new Set(sourceRoute ? computeSegmentTreePaths(sourceRoute.segments) : []);
+        const scopes = [mounted, addressed].filter((scope) => scope.size > 0);
+        // Neither channel produced a tree — no scope can contain anything, and
+        // an origin that matches no route is not a legitimate soft navigation.
+        return scopes.length > 0 ? scopes : null;
+      };
+      const rewrite = findInterceptionMatch(
+        canonicalPathname,
+        resolveSourceScopes,
+        config.interceptionRewrites
+      );
+      if (rewrite?.mode === 'children') {
+        // Sibling layout swap (TIM-1280). Nothing is re-matched: the resolver
+        // addresses the owner directory by tree path and returns the chain
+        // `[…owner ancestors, interceptingNode, …descendants]`, which renders
+        // as an ordinary route. `interception` stays unset — there is no slot
+        // to intercept into, and setting it would additionally arm the modal
+        // path for every slot in the tree we are about to render.
+        //
+        // A null here means the scope named nothing in this manifest, or no
+        // intercepting child matched the target. Both fall through to the
+        // canonical route, which is what a hard navigation renders.
+        const interceptedMatch = config.matchInterceptedRoute?.(
+          canonicalPathname,
+          rewrite.interceptingScope
+        );
+        if (interceptedMatch) match = interceptedMatch;
+      } else if (rewrite) {
+        const sourceMatch = config.matchRoute(rewrite.interceptingPrefix);
+        // The scope test above was about the route the user is LEAVING. The
+        // route we are about to render is a different one —
+        // `interceptingPrefix` is URL-derived, and route groups are
+        // URL-invisible, so `/` can resolve into a sibling group that does not
+        // own the slot. Rendering that would reproduce the TIM-1278 failure on
+        // a valid tree: the rewrite hijacks the navigation and no slot exists
+        // to render the intercepting page. Fall through to the canonical
+        // target route instead.
+        const rendersTheSlot =
+          sourceMatch !== null &&
+          computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope);
+        if (rendersTheSlot) {
+          match = sourceMatch;
+          interception = { targetPathname: canonicalPathname };
+        }
+      }
+    }
   }
 
-  return pi === pathParts.length;
+  return { match, interception };
+}
+
+/**
+ * Validate and canonicalize the X-Timber-URL header value.
+ *
+ * Returns the canonical pathname if valid, or null if rejected:
+ * - Must start with '/' (relative pathname, no scheme/authority)
+ * - Must not contain control characters
+ * - Must pass canonicalization (no encoded separators, null bytes, etc.)
+ */
+function validateInterceptionHeader(raw: string, stripTrailingSlash: boolean): string | null {
+  if (!raw.startsWith('/')) return null;
+  if (raw.startsWith('//')) return null;
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) return null;
+  }
+  const result = canonicalize(raw, stripTrailingSlash);
+  if (!result.ok) return null;
+  return result.pathname;
 }

package/src/server/pipeline-metadata.ts

@@ -31,7 +31,7 @@ const TEXT_CONTENT_TYPES = new Set([
  * See design/16-metadata.md §"Metadata Routes"
  */
 export async function serveStaticMetadataFile(
-  metaMatch: import('./route-matcher.js').MetadataRouteMatch
+  metaMatch: import('./route-matcher.ts').MetadataRouteMatch
 ): Promise<Response> {
   const { contentType, file } = metaMatch;
   const isText = TEXT_CONTENT_TYPES.has(contentType);
@@ -41,6 +41,7 @@ export async function serveStaticMetadataFile(
   const headers: Record<string, string> = {
     'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
     'Content-Length': String(body.byteLength),
+    'Cache-Control': 'public, max-age=14400, must-revalidate',
   };
 
   return new Response(body, { status: 200, headers });
@@ -79,6 +80,19 @@ export function serializeSitemap(
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
 }
 
+/**
+ * Serialize a sitemap index (list of sub-sitemap URLs) to XML.
+ * Used for pagination when the total URL count exceeds 50,000.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export function serializeSitemapIndex(sitemapUrls: string[]): string {
+  const sitemaps = sitemapUrls
+    .map((url) => `  <sitemap>\n    <loc>${escapeXml(url)}</loc>\n  </sitemap>`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemaps}\n</sitemapindex>`;
+}
+
 /** Escape special XML characters. */
 export function escapeXml(str: string): string {
   return str

package/src/server/pipeline-outcome.ts

@@ -0,0 +1,290 @@
+/**
+ * Pipeline outcome translator — converts a `PhaseOutcome` (the value
+ * each phase function returns) into a final `Response`.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the per-phase try /
+ * catch logic and the terminal Response-building logic each live in
+ * their own file. The phases produce values; this module is the single
+ * source of truth for how those values become wire responses.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import {
+  applyCookieJar,
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  dynamicResponseHeaders,
+  fireOnRequestError,
+  mergeMissingHeaders,
+} from './pipeline-helpers.ts';
+import {
+  logProxyError,
+  logMiddlewareError,
+  logMiddlewareShortCircuit,
+  logRenderError,
+  logRouteError,
+  logRouteSetupError,
+} from './logger.ts';
+import { markResponseFlushed } from './request-context.ts';
+import { RedirectSignal, DenySignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
+import { isApiRouteChain } from './route-matcher.ts';
+import { isDebug } from './debug.ts';
+import { errorResponseHeaders } from './error-response-headers.ts';
+import { rscErrorEnvelope } from './rsc-error-envelope.ts';
+import { isRscRequest } from '../shared/rsc-media-type.ts';
+import type { PipelineConfig, RouteMatch } from './pipeline.ts';
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function rscErrorResponse(isRsc: boolean, status: number, headers: Headers): Response {
+  if (isRsc) return rscErrorEnvelope(status, headers);
+  return new Response(null, { status, headers: errorResponseHeaders(headers) });
+}
+
+/**
+ * Resolve the header bag a signal/error outcome is written onto, with the
+ * cookie jar applied exactly once.
+ *
+ * Ownership rule (design/49 §P0b): the phase that owns `responseHeaders`
+ * applies the jar to it once; the translator applies it only for outcomes
+ * that arrive without it. Render-phase outcomes already carry the jar —
+ * `runRenderPhase()` applies it on entry, with or without a middleware
+ * chain — so re-applying here emitted every middleware `Set-Cookie` twice
+ * (TIM-1491).
+ *
+ * The guard is "not render", not "only middleware": proxy-phase signals
+ * reach the translator with no `responseHeaders` at all, and for a
+ * `proxy.ts` that awaits `next()` and then throws, this is the only place
+ * the cookies downstream middleware set can reach the wire
+ * (design/29-cookies.md §"proxy.ts Cookie Access"). Middleware-phase
+ * signals throw before that phase's own application, so they need it too,
+ * and so do setup-phase outcomes, which come before any phase applied it.
+ *
+ * `fresh` creates the bag for an outcome that arrives without one.
+ */
+function outcomeHeaders(
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext,
+  fresh: () => Headers = () => new Headers()
+): Headers {
+  const headers = ctx.responseHeaders ?? fresh();
+  if (outcome.phase !== 'render') applyCookieJar(headers);
+  return headers;
+}
+
+/** Whether the outcome is for a route.ts match, which answers in its own format. */
+function isApiRouteMatch(ctx: OutcomeContext): boolean {
+  return ctx.match !== undefined && isApiRouteChain(ctx.match.segments);
+}
+
+/**
+ * Report an error outcome once: log it under its phase, fire
+ * `onRequestError`, and hand it to the dev overlay. An error from a
+ * route.ts handler — or anything else in its render phase — logs as a route
+ * error and reports as phase `'route'`.
+ */
+async function reportError(
+  config: PipelineConfig,
+  error: unknown,
+  phase: PhaseName,
+  ctx: OutcomeContext
+): Promise<void> {
+  const { method, path } = ctx;
+  switch (phase) {
+    case 'proxy':
+      logProxyError({ error });
+      break;
+    case 'setup':
+      logRouteSetupError({ method, path, error });
+      break;
+    case 'middleware':
+      logMiddlewareError({ method, path, error });
+      break;
+    case 'render':
+      if (isApiRouteMatch(ctx)) {
+        logRouteError({ method, path, error });
+      } else {
+        logRenderError({ method, path, error });
+      }
+      break;
+  }
+  await fireOnRequestError(error, ctx.req, phase, ctx.match?.segments);
+  if (config.onPipelineError && error instanceof Error) config.onPipelineError(error, phase);
+}
+
+// ─── Phase Outcome ─────────────────────────────────────────────────────────
+
+/**
+ * The pipeline phase an outcome came from.
+ *
+ * `'setup'` is route setup between `proxy.ts` and `middleware.ts`: route
+ * matching, interception, and segment-param coercion. It has its own name
+ * rather than borrowing `'middleware'` because both the cookie-jar guard
+ * and `onRequestError` key on the phase (TIM-1537).
+ */
+export type PhaseName = 'proxy' | 'setup' | 'middleware' | 'render';
+
+export type PhaseOutcome =
+  | { kind: 'response'; phase: PhaseName; response: Response }
+  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
+  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
+  | { kind: 'error'; phase: PhaseName; error: unknown };
+
+/** The outcome for a value a phase threw: a signal, or an error. */
+export function thrownOutcome(phase: PhaseName, thrown: unknown): PhaseOutcome {
+  if (isRedirectSignal(thrown)) return { kind: 'redirect', phase, signal: thrown };
+  if (isDenySignal(thrown)) return { kind: 'deny', phase, signal: thrown };
+  return { kind: 'error', phase, error: thrown };
+}
+
+export interface OutcomeContext {
+  req: Request;
+  method: string;
+  path: string;
+  responseHeaders?: Headers;
+  match?: RouteMatch;
+}
+
+// ─── Translator ────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export async function outcomeToResponse(
+  config: PipelineConfig,
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext
+): Promise<Response> {
+  switch (outcome.kind) {
+    case 'response': {
+      // Clone unconditionally so downstream code (cookie/header merge,
+      // Server-Timing in createPipeline) can write headers without paying
+      // for a try/catch immutability probe per request. User middleware,
+      // proxy, and route code may all return `Response.redirect()` or
+      // platform-level responses with frozen header bags. See TIM-866.
+      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;
+    }
+
+    case 'redirect': {
+      const headers = outcomeHeaders(outcome, ctx);
+      // A route.ts match redirects with a real 3xx whatever it accepts; only
+      // a page navigation gets the client router's soft redirect.
+      const navigation = isRscRequest(ctx.req) && !isApiRouteMatch(ctx);
+      return buildRedirectResponse(outcome.signal, headers, navigation);
+    }
+
+    case 'deny': {
+      // A deny with no bag of its own (a proxy-phase deny) gets the
+      // dynamic-page cache policy every other rendered page starts with.
+      // Only the deny: a redirect proxy.ts chose keeps HTTP's own caching
+      // semantics (a 308 is heuristically cacheable).
+      const headers = outcomeHeaders(outcome, ctx, dynamicResponseHeaders);
+      if (config.renderDenyFallback) {
+        try {
+          // Clone user-supplied deny-page responses so downstream
+          // Server-Timing writes are safe against frozen header bags
+          // (e.g. user returned Response.redirect from the hook).
+          return cloneWithMutableHeaders(
+            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
+          );
+        } catch (denyRenderError) {
+          // Deny page rendering failed — log before falling through to bare response.
+          // Without this, a crashing deny page produces a blank response with zero
+          // server-side signal. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: denyRenderError });
+          await fireOnRequestError(denyRenderError, ctx.req, 'render', ctx.match?.segments);
+          if (config.onPipelineError && denyRenderError instanceof Error)
+            config.onPipelineError(denyRenderError, 'render');
+          // A client navigation cannot decode an empty body: send the
+          // hard-navigate envelope so the document request renders the deny.
+          if (isRscRequest(ctx.req)) return rscErrorEnvelope(outcome.signal.status, headers);
+        }
+      }
+      if (isDebug()) {
+        console.warn(
+          `[timber] DenySignal(${outcome.signal.status}) from ${outcome.phase} phase — ` +
+            `no renderDenyFallback configured, returning bare ${outcome.signal.status} response\n` +
+            `  Request: ${ctx.method} ${ctx.path}\n` +
+            `  Add a status-code file (e.g. 404.tsx) or error.tsx to render a custom deny page.`
+        );
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      // RSC payload requests (client navigation) expect Flight data, not HTML.
+      // Signal the error via X-Timber-Error so the client hard-navigates
+      // to the server-rendered error page instead of feeding HTML to the
+      // Flight decoder (which crashes with "enqueueModel is not a function").
+      const isRsc = isRscRequest(ctx.req);
+      const headers = outcomeHeaders(outcome, ctx);
+      await reportError(config, outcome.error, outcome.phase, ctx);
+
+      // proxy.ts and middleware.ts errors answer with a bare 500 — no page.
+      if (outcome.phase === 'proxy' || outcome.phase === 'middleware') {
+        return rscErrorResponse(isRsc, 500, headers);
+      }
+
+      // A route.ts match answers in its JSON format whatever the Accept
+      // header says, so it skips the navigation envelope and goes to the
+      // fallback renderer with the match.
+      if (isRsc && !isApiRouteMatch(ctx)) {
+        return rscErrorResponse(true, 500, headers);
+      }
+
+      if (config.renderFallbackError) {
+        try {
+          // Clone user-supplied fallback error responses so downstream
+          // Server-Timing writes are safe against frozen header bags.
+          return cloneWithMutableHeaders(
+            // Sanitized: the replacement body must not inherit the success
+            // response's encoding, length, validators, or cache lifetime
+            // that middleware may already have set on the bag.
+            await config.renderFallbackError(
+              outcome.error,
+              ctx.req,
+              errorResponseHeaders(headers),
+              ctx.match
+            )
+          );
+        } catch (fallbackRenderError) {
+          // Fallback rendering itself failed — log the secondary error before
+          // falling through to bare 500. The original render error was already
+          // logged above; this captures the fallback renderer's own crash so it
+          // doesn't vanish silently. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: fallbackRenderError });
+          await fireOnRequestError(fallbackRenderError, ctx.req, 'render', ctx.match?.segments);
+          if (config.onPipelineError && fallbackRenderError instanceof Error)
+            config.onPipelineError(fallbackRenderError, 'render');
+        }
+      }
+      return rscErrorResponse(false, 500, headers);
+    }
+  }
+}