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

package/src/server/rsc-entry/ssr-renderer.ts

@@ -12,25 +12,83 @@
  *              05-streaming.md §"deferSuspenseFor and the Hold Window"
  */
 
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPage } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import { SsrStreamError } from '#/server/primitives.js';
-import type { LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { NavContext } from '#/server/ssr-entry.js';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { flightInitScript } from '../flight-scripts.ts';
+import { getCspNonce, nonceAttr } from '../csp-nonce.ts';
+import { appVisibleSearch } from '../../shared/rsc-cache-key.ts';
+import { getSlotParamsForClient } from '../request-context.ts';
+import type { LayoutEntry } from '../deny-renderer.ts';
+import { renderDenyPage } from '../deny-renderer.ts';
+import type { RouteMatch } from '../pipeline.ts';
+import { isSsrStreamError } from '../primitives.ts';
+import type { LayoutComponentEntry } from '../route-element-builder.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import type { SlotSkipEntry } from '../slot-resolver.ts';
+import type { NavContext } from '../ssr-bridge-types.ts';
 
+import { htmlEscapeJsonString } from '../flight-scripts.ts';
 import {
   buildRedirectResponse,
   buildSegmentInfo,
   createDebugChannelSink,
   isAbortError,
-  parseCookiesFromHeader,
-} from './helpers.js';
-import { renderErrorPage } from './error-renderer.js';
-import { callSsr } from './ssr-bridge.js';
-import type { RenderSignals } from './rsc-stream.js';
+} from './helpers.ts';
+import { getCookiesForSsr } from '../cookie-context.ts';
+import { getDenyStatus, getFirstDeniedSegmentIndex } from '../deny-boundary.ts';
+import { renderErrorPage, type GlobalErrorFile } from './error-renderer.ts';
+import { callSsr } from './ssr-bridge.ts';
+import type { RenderSignals } from './rsc-stream.ts';
+import { recordTiming } from '../server-timing.ts';
+import { teeWithErrorPropagation } from '../stream-utils.ts';
+import { addSpanEventSync } from '../tracing.ts';
+import { isDevMode } from '../debug.ts';
+
+/**
+ * Maximum number of queueMicrotask yields during signal promotion.
+ * The known rejection chain depth for a withSpan-wrapped component is 3+
+ * microtasks. We use 5 to tolerate additional async wrappers or React
+ * Flight internals adding extra microtask hops. Do not increase beyond 8 —
+ * a deeper chain indicates a structural problem.
+ */
+const SIGNAL_PROMOTION_MAX_YIELDS = 5;
+
+/**
+ * Number of additional microtask yields used by the cap-reached detection
+ * phase (TIM-970). After the promotion loop burns its full cap without
+ * capturing a signal, we yield a few more times to distinguish "no signal
+ * was ever coming" (state 2) from "signal arrived one microtask past the
+ * cap" (state 3 — the silent-miss path). These yields are telemetry-only:
+ * if a late signal is observed it triggers a warn/span-event but is NOT
+ * promoted, because raising the effective promotion cap is deferred to
+ * the E.2 investigation. Without this phase, every default `deferSuspenseFor=0`
+ * render would emit a cap-reached warning even though nothing was missed.
+ */
+const SIGNAL_PROMOTION_DETECTION_EXTRA_YIELDS = 3;
+
+/**
+ * Test-only observable: records how many microtask yields were consumed
+ * during the last signal promotion check. Import this in tests to assert
+ * the actual rejection chain depth and detect regressions if wrappers
+ * add more async hops.
+ *
+ * Only populated when the object is imported and exists — production
+ * bundles that don't import it pay zero cost (the typeof check is free).
+ */
+export const __test_only_signalPromotionDepth: { value: number } = { value: 0 };
+
+/**
+ * Test-only observable: true when the promotion loop hit the cap without
+ * capturing a signal (the silent-miss path — state 3 in TIM-970). False
+ * when the loop captured a signal at any depth, when it was skipped via
+ * `_fizzAllReadyResolved`, or when no signal was ever expected at a depth
+ * shallower than the cap.
+ *
+ * Pairs with `__test_only_signalPromotionDepth`: depth alone cannot
+ * distinguish "cap hit with signal captured on yield 5" from "cap hit with
+ * signal arriving on yield 6+" — both read `.value === 5`. This flag closes
+ * that gap. See TIM-970, design/05-streaming.md §"Signal Promotion".
+ */
+export const __test_only_signalPromotionCapHit: { value: boolean } = { value: false };
 
 interface SsrRenderOptions {
   req: Request;
@@ -44,6 +102,9 @@ interface SsrRenderOptions {
   clientJsDisabled: boolean;
   headHtml: string;
   deferSuspenseFor: number;
+  /** Tier 2 global-error.tsx file, if present in app/. */
+  globalError?: GlobalErrorFile;
+  slotSkipInfo?: SlotSkipEntry[];
 }
 
 /**
@@ -77,40 +138,78 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     clientJsDisabled,
     headHtml,
     deferSuspenseFor,
+    globalError,
   } = opts;
 
   // Tee the RSC stream — one copy goes to SSR for HTML rendering,
   // the other is inlined in the HTML for client-side hydration.
-  const [ssrStream, inlineStream] = rscStream.tee();
-
-  // Embed segment metadata in HTML for initial hydration.
-  // The client reads this to populate its segment cache before the
-  // first navigation, enabling state tree diffing from the start.
-  // Skipped when client JS is disabled — no client JS to consume it.
-  const segmentScript = clientJsDisabled
-    ? ''
-    : `<script>self.__timber_segments=${JSON.stringify(buildSegmentInfo(segments, layoutComponents))}</script>`;
-
-  // Embed route params in HTML so useParams() works on initial hydration.
-  // Without this, useParams() returns {} until the first client navigation.
-  const paramsScript =
-    clientJsDisabled || Object.keys(match.params).length === 0
-      ? ''
-      : `<script>self.__timber_params=${JSON.stringify(match.params)}</script>`;
+  // Uses teeWithErrorPropagation to ensure errors on either branch
+  // cancel the other (preventing hung responses) and to monitor
+  // buffer divergence between SSR and inline consumers.
+  //
+  // When client JS is disabled, skip the tee — the inline stream would
+  // never be consumed, causing monotonic buffer divergence that eventually
+  // triggers the 5MB guard and cancels the SSR stream.
+  let ssrStream: ReadableStream<Uint8Array>;
+  let inlineStream: ReadableStream<Uint8Array> | undefined;
+  if (clientJsDisabled) {
+    ssrStream = rscStream;
+    inlineStream = undefined;
+  } else {
+    [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
+  }
+
+  // Wire an AbortController so the Flight injector stops writing <script>
+  // tags when an unhandled RSC error is detected. Without this, React's
+  // Flight encoder may write model data for a chunk that already received
+  // an error row, causing the client's Flight decoder to crash with
+  // "enqueueModel is not a function". See TIM-938.
+  const errorAbort = new AbortController();
+  signals.onUnhandledError = () => errorAbort.abort();
 
+  // Segment metadata for initial hydration: deferred to shell-flush time.
+  // The SSR entry invokes this thunk AFTER renderSsrNodeStream /
+  // renderSsrStream returns (shell ready ⇒ AccessGates settled), so
+  // getFirstDeniedSegmentIndex() returns the authoritative ALS value
+  // rather than the pre-render Infinity. See TIM-1365, TIM-1359.
+
+  // Params reach the browser inside the payload — a field on the root row of
+  // the same Flight stream that is inlined for hydration. SSR itself renders
+  // only the tree, and the client components it renders read params from the
+  // ALS context seeded below, which is also where server components answer
+  // `getSegmentParams(slotPath)` from.
+  const slotParams = getSlotParamsForClient();
+
+  // Middleware has already run; if it read `ctx.nonce` for its CSP header,
+  // that is the value every inline script must wear.
+  const nonce = getCspNonce();
+
+  const reqUrl = new URL(req.url);
   const navContext: NavContext = {
-    pathname: new URL(req.url).pathname,
-    params: match.params,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    pathname: reqUrl.pathname,
+    search: appVisibleSearch(reqUrl).search,
+    segmentParams: match.segmentParams,
+    slotParams,
     statusCode: 200,
     responseHeaders,
-    headHtml: headHtml + clientBootstrap.preloadLinks + segmentScript + paramsScript,
+    headHtml:
+      headHtml +
+      clientBootstrap.preloadLinks +
+      // Initialize __timber_f in <head> so it exists before any streaming
+      // chunk scripts arrive in <body>. See flight-scripts.ts, LOCAL-415.
+      (clientJsDisabled ? '' : flightInitScript(nonce)),
+    getHeadSegmentScript: clientJsDisabled
+      ? undefined
+      : () =>
+          `<script${nonceAttr(nonce)}>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents, opts.slotSkipInfo, undefined, getFirstDeniedSegmentIndex())))}</script>`,
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    nonce,
     // Skip RSC inline stream when client JS is disabled — no client to hydrate.
     rscStream: clientJsDisabled ? undefined : inlineStream,
     deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
     signal: req.signal,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
+    _errorSignal: errorAbort.signal,
   };
 
   // Helper: check if render-phase signals were captured and return the
@@ -118,14 +217,25 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   // promotion from Suspense) and failed SSR (signal outside Suspense).
   //
   // When `skipHandledDeny` is true (SSR success path), skip DenySignal
-  // promotion if the denial was already handled by a TimberErrorBoundary
-  // (e.g., slot error boundary). The boundary sets navContext._denyHandledByBoundary
-  // during SSR rendering. See LOCAL-298.
+  // re-render if the denial was already handled by a TimberErrorBoundary.
+  // The boundary renders the deny page as its fallback AND sets the correct
+  // HTTP status code on navContext — no redundant renderDenyPage() needed.
+  // See TIM-664, LOCAL-298.
+  // Read the denied segment index from ALS — set by AccessGate during render
+  // (setFirstDeniedSegmentIndex). See TIM-1358, TIM-1365.
+  function resolvedDeniedIndex(): number {
+    return getFirstDeniedSegmentIndex();
+  }
+
   function checkCapturedSignals(skipHandledDeny = false): Response | Promise<Response> | null {
     if (signals.redirectSignal) {
-      return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+      return buildRedirectResponse(signals.redirectSignal, req, responseHeaders);
     }
     if (signals.denySignal && !(skipHandledDeny && navContext._denyHandledByBoundary)) {
+      // Deny was not handled by an in-tree error boundary.
+      // Fall back to renderDenyPage (separate React.cache scope).
+      // For single-render behavior, add a 'use client' status-code file
+      // (e.g., 4xx.tsx) — the error boundary handles it in-tree.
       return renderDenyPage(
         signals.denySignal,
         segments,
@@ -135,7 +245,9 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
         responseHeaders,
         clientBootstrap,
         createDebugChannelSink,
-        callSsr
+        callSsr,
+        undefined,
+        resolvedDeniedIndex()
       );
     }
     if (signals.renderError) {
@@ -147,7 +259,9 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
         req,
         match,
         responseHeaders,
-        clientBootstrap
+        clientBootstrap,
+        globalError,
+        resolvedDeniedIndex()
       );
     }
     return null;
@@ -156,63 +270,207 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   try {
     const ssrResponse = await callSsr(ssrStream, navContext);
 
-    // Signal promotion: yield one tick so async component rejections
-    // propagate to the RSC onError callback, then check if any signals
-    // were captured during rendering inside Suspense boundaries.
-    // The Response hasn't been sent yet — it's an unconsumed stream.
+    // Record SSR sub-phase timings for Server-Timing header (detailed mode).
+    // These are populated by handleSsr() in the SSR environment and passed
+    // back via navContext._ssrTimings across the RSC→SSR boundary.
+    if (navContext._ssrTimings) {
+      const t = navContext._ssrTimings;
+      recordTiming({ name: 'ssr-decode', dur: t.decodeMs, desc: 'RSC Flight decode' });
+      recordTiming({ name: 'ssr-shell', dur: t.shellMs, desc: 'Fizz onShellReady' });
+      recordTiming({ name: 'ssr-pipeline', dur: t.pipelineMs, desc: 'stream transforms' });
+      recordTiming({
+        name: 'ssr-total',
+        dur: t.totalMs,
+        desc: t.nodeStreams ? 'SSR (Node streams)' : 'SSR (Web Streams)',
+      });
+    }
+
+    // Signal promotion: check if any signals were captured during rendering
+    // inside Suspense boundaries. If no signals are present yet, we may
+    // need to yield microtasks so async component rejections propagate
+    // through the full rejection chain to the RSC onError callback before
+    // we commit the response.
+    //
+    // Option 1 short-circuit: when Fizz's `stream.allReady` settled before
+    // the `deferSuspenseFor` hold ended (navContext._fizzAllReadyResolved),
+    // Flight has closed its stream, every `onError` already fired, and the
+    // signals object is fully populated. The retry loop would be a no-op.
+    // See design/spike-signal-promotion-protocol.md §"Option 1".
+    //
+    // Fallback path (hold timed out, no hold window, or shell-only return):
+    // the known rejection chain depth for a withSpan-wrapped page is 3+
+    // microtasks —
+    //   1. PageComponent throws DenySignal/RedirectSignal
+    //   2. withSpan catches and re-throws (microtask 1)
+    //   3. TracedPage promise rejects (microtask 2)
+    //   4. React Flight rejection handler → onError (microtask 3+)
+    // so a bounded retry loop (max 5) is required to catch signals whose
+    // propagation is still in-flight when callSsr returns. The loop exits
+    // early as soon as a signal is detected. Uses queueMicrotask instead
+    // of setTimeout(0) to avoid yielding to the full event loop.
     // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
-    await new Promise<void>((r) => setTimeout(r, 0));
+    if (!signals.redirectSignal && !signals.denySignal && !signals.renderError) {
+      let yieldsConsumed = 0;
+      let detectionConfirmedLateSignal = false;
+      if (!navContext._fizzAllReadyResolved) {
+        // Promotion phase: bounded cap of SIGNAL_PROMOTION_MAX_YIELDS.
+        // Signals captured here are honored by checkCapturedSignals and
+        // become the response (redirect/deny/error page).
+        for (let i = 0; i < SIGNAL_PROMOTION_MAX_YIELDS; i++) {
+          await new Promise<void>((r) => queueMicrotask(r));
+          yieldsConsumed++;
+          if (signals.redirectSignal || signals.denySignal || signals.renderError) break;
+        }
+
+        // Detection phase (TIM-970): if the promotion cap was hit without
+        // capturing a signal, yield a few more times to disambiguate state 2
+        // ("no signal was ever coming" — the common legitimate-200 case) from
+        // state 3 ("signal arrived one microtask past the cap" — the silent
+        // miss). Telemetry-only: if a late signal is observed it triggers
+        // the warning and span event but is NOT promoted. Promoting it would
+        // effectively raise the cap to MAX_YIELDS + DETECTION_EXTRA_YIELDS,
+        // which the ticket defers to the E.2 investigation. The signals are
+        // cleared so checkCapturedSignals does not pick them up.
+        if (
+          yieldsConsumed === SIGNAL_PROMOTION_MAX_YIELDS &&
+          !signals.redirectSignal &&
+          !signals.denySignal &&
+          !signals.renderError
+        ) {
+          for (let i = 0; i < SIGNAL_PROMOTION_DETECTION_EXTRA_YIELDS; i++) {
+            await new Promise<void>((r) => queueMicrotask(r));
+            if (signals.redirectSignal || signals.denySignal || signals.renderError) {
+              detectionConfirmedLateSignal = true;
+              signals.redirectSignal = null;
+              signals.denySignal = null;
+              signals.renderError = null;
+              break;
+            }
+          }
+        }
+      }
+      __test_only_signalPromotionDepth.value = yieldsConsumed;
+      __test_only_signalPromotionCapHit.value = detectionConfirmedLateSignal;
+
+      if (detectionConfirmedLateSignal) {
+        if (isDevMode()) {
+          console.warn(
+            `[timber] Signal promotion cap reached (${SIGNAL_PROMOTION_MAX_YIELDS} microtask yields) — a deny()/redirect()/renderError signal arrived just past the cap and was discarded. ` +
+              `Likely cause: a page using deny()/redirect() inside a deeply-wrapped async component (custom withSpan, decorators, etc.). ` +
+              `Simplify the async chain or reduce withSpan/wrapper depth. ` +
+              `See design/05-streaming.md §"Signal Promotion".`
+          );
+        }
+        addSpanEventSync('timber.ssr.signal_promotion_cap_reached', {
+          depth: SIGNAL_PROMOTION_MAX_YIELDS,
+          signal_types_checked: 'redirect,deny,renderError',
+        });
+      }
+    }
 
     const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
     if (promoted) {
       ssrResponse.body?.cancel();
       return promoted;
     }
+
+    // Check if a DenySignal was caught in-tree by AccessGate or
+    // PageDenyBoundary. The deny page was rendered as a normal element
+    // (no error in the Flight stream), so SSR succeeded with status 200.
+    // Override the status code from the ALS-stored deny status. See TIM-666.
+    const denyStatus = getDenyStatus();
+    if (denyStatus) {
+      return new Response(ssrResponse.body, {
+        status: denyStatus,
+        headers: ssrResponse.headers,
+      });
+    }
+
     return ssrResponse;
   } catch (ssrError) {
     // Connection abort — the client disconnected (page refresh, navigation
     // away). No response needed; return empty 499 (client closed request).
     if (isAbortError(ssrError) || req.signal?.aborted) {
+      inlineStream?.cancel().catch(() => {});
       return new Response(null, { status: 499 });
     }
 
     // SsrStreamError: SSR's renderToReadableStream failed because the RSC
     // stream contained an uncontained error (e.g., slot without error boundary).
-    // Render the deny/error page WITHOUT layout wrapping to avoid re-executing
-    // server components (which call headers()/cookies() and fail in SSR's
-    // separate ALS scope). See LOCAL-293.
-    if (ssrError instanceof SsrStreamError) {
+    //
+    // Error pages now use SSR-only rendering (Fizz directly, no RSC Flight),
+    // which imports layouts in the SSR environment where ALS is active. This
+    // means we CAN include layouts — they'll call getHeaders()/getCookies() correctly.
+    //
+    // Deny pages still go through RSC → SSR (plain props), so they pass empty
+    // layouts to avoid re-executing server components in the RSC environment's
+    // stale ALS scope. See LOCAL-293.
+    // SsrStreamError is thrown in the SSR environment but caught here in
+    // RSC — separate Vite module graphs, so `instanceof` can never match.
+    // isSsrStreamError() checks the Symbol.for brand instead. See
+    // design/18-build-system.md §"Dev Mode: Signal Identity Across Program Reloads".
+    if (isSsrStreamError(ssrError)) {
+      // Cancel the teed inline stream — SSR failed so this response will
+      // be replaced by renderErrorPage which creates its own clean streams.
+      // Without explicit cancellation the orphaned tee branch keeps the
+      // RSC source stream alive, preventing garbage collection.
+      inlineStream?.cancel().catch(() => {});
+
       if (signals.redirectSignal) {
-        return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+        return buildRedirectResponse(signals.redirectSignal, req, responseHeaders);
       }
       if (signals.denySignal) {
-        // Render deny page without layouts — pass empty layout list
+        // SSR failed (SsrStreamError) — the deny was in the shell and
+        // the error boundary didn't catch it during Fizz rendering.
+        // Fall back to renderDenyPage (separate render). See TIM-664.
         return renderDenyPage(
           signals.denySignal,
           segments,
-          [] as LayoutEntry[],
+          layoutComponents as LayoutEntry[],
           req,
           match,
           responseHeaders,
           clientBootstrap,
           createDebugChannelSink,
-          callSsr
+          callSsr,
+          undefined,
+          resolvedDeniedIndex()
         );
       }
       if (signals.renderError) {
+        // RenderError: TSX error pages use SSR-only path (layouts OK),
+        // MDX error pages use RSC path (plain props, no Error object).
         return renderErrorPage(
           signals.renderError.error,
           signals.renderError.status,
           segments,
-          [] as LayoutEntry[],
+          layoutComponents as LayoutEntry[],
           req,
           match,
           responseHeaders,
-          clientBootstrap
+          clientBootstrap,
+          globalError,
+          resolvedDeniedIndex()
         );
       }
-      // No captured signal — return bare 500
-      return new Response(null, { status: 500, headers: responseHeaders });
+      // No captured signal — unhandled error in the RSC stream.
+      // Use the lastUnhandledError from RSC onError if available (more
+      // reliable than extracting SsrStreamError.cause). Falls back to
+      // cause extraction for backward compatibility.
+      const originalError =
+        signals.lastUnhandledError ?? (ssrError as { cause?: unknown }).cause ?? ssrError;
+      return renderErrorPage(
+        originalError,
+        500,
+        segments,
+        layoutComponents as LayoutEntry[],
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        globalError,
+        resolvedDeniedIndex()
+      );
     }
 
     // SSR shell rendering failed — the error was outside Suspense.

package/src/server/rsc-entry/wrap-action-dispatch.ts

@@ -0,0 +1,186 @@
+/**
+ * Action-dispatch wrapper around the route pipeline.
+ *
+ * Extracted from rsc-entry/index.ts so the wiring can be unit-tested in
+ * isolation from Vite's virtual modules.
+ *
+ * ## Architecture (TIM-1213)
+ *
+ * The wrapper is responsible for ONE thing:
+ *
+ *   **Pipeline-boundary CSRF validation** — runs on EVERY unsafe-method
+ *   request, before any dispatch decision. This is the only line of
+ *   defense for `route.ts` API handlers and server actions. See LOCAL-773.
+ *
+ * Server action dispatch has moved INTO the pipeline (`PipelineConfig.
+ * dispatchAction`) so that `proxy.ts` runs on action POSTs — matching the
+ * design doc contract: "proxy.ts runs on every request, no exclusions."
+ *
+ * The `buildActionDispatcher` function constructs the `dispatchAction`
+ * callback that `createPipeline` calls after proxy.ts runs. It
+ * encapsulates action detection, route-type check, action handler
+ * dispatch, and the no-JS validation rerender path.
+ *
+ * Per-segment `middleware.ts` does NOT run on action POSTs (TIM-1134).
+ * Actions are dispatched by action ID, not by route segment. CSRF
+ * validation runs at the pipeline boundary. Per-action auth/validation
+ * belongs in `createActionClient({ middleware })`.
+ */
+
+import type { FormRerender } from '../action-handler.ts';
+import { handleActionRequest, isActionRequest } from '../action-handler.ts';
+import type { BodyLimitsConfig } from '../body-limits.ts';
+import { validateCsrf, type CsrfConfig } from '../csrf.ts';
+import { runWithFormFlash } from '../form-flash.ts';
+import { seedRequestCookies } from '../cookie-context.ts';
+import type { RouteMatcher } from '../pipeline.ts';
+import type { SensitiveFieldsOption } from '../sensitive-fields.ts';
+import type { RevalidateRenderer } from '../actions.ts';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a `RevalidateRenderer` for a specific request.
+ *
+ * The renderer needs to forward cookies/headers from the originating
+ * request when fetching the revalidated route. We pass the request in
+ * via a builder so the wrapper doesn't need to know about route matching,
+ * segment param coercion, or element building — those concerns stay in
+ * `rsc-entry/index.ts`.
+ */
+export type RevalidateRendererFactory = (req: Request) => RevalidateRenderer;
+
+/** Dependencies for the CSRF wrapper. */
+export interface ActionDispatchDeps {
+  /** CSRF configuration (Origin allow-list, on/off switch). */
+  csrfConfig: CsrfConfig;
+}
+
+/** Dependencies for the action dispatcher (used inside the pipeline). */
+export interface ActionDispatcherDeps {
+  /** CSRF configuration — defense-in-depth check inside the action handler. */
+  csrfConfig: CsrfConfig;
+  /** Body size limits forwarded to `handleActionRequest`. */
+  bodyLimits?: BodyLimitsConfig['limits'];
+  /** Sensitive-field deny-list forwarded to `handleActionRequest`. */
+  sensitiveFields?: SensitiveFieldsOption;
+  /** Per-request factory that builds a `RevalidateRenderer`. */
+  buildRevalidateRenderer: RevalidateRendererFactory;
+  /**
+   * Route matcher — used for the route-type check that skips action
+   * detection on `route.ts` API handlers (TIM-870).
+   */
+  matchRoute?: RouteMatcher;
+}
+
+// ─── CSRF Wrapper ─────────────────────────────────────────────────────────
+
+/**
+ * Wrap a pipeline function with pipeline-boundary CSRF validation.
+ *
+ * The returned handler is the framework's outermost request entry point.
+ * It validates the `Origin` header on every unsafe-method request before
+ * any dispatch decision — this is the ONLY line of defense for `route.ts`
+ * API handlers, which never see the action handler.
+ *
+ * Action dispatch has moved inside the pipeline (TIM-1213) so proxy.ts
+ * runs on every request. This wrapper now only handles CSRF.
+ */
+export function wrapPipelineWithActionDispatch(
+  pipeline: (req: Request) => Promise<Response>,
+  deps: ActionDispatchDeps
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    // Pipeline-boundary CSRF validation (LOCAL-773).
+    // Runs on EVERY unsafe-method request, before any dispatch decision.
+    const csrfResult = validateCsrf(req, deps.csrfConfig);
+    if (!csrfResult.ok) {
+      return new Response(null, { status: csrfResult.status });
+    }
+
+    return pipeline(req);
+  };
+}
+
+// ─── Action Dispatcher ────────────────────────────────────────────────────
+
+/**
+ * Build the `dispatchAction` callback for `PipelineConfig`.
+ *
+ * Called after proxy.ts runs (inside the pipeline) for every request.
+ * Checks if the request is a server action POST, handles the route-type
+ * check (TIM-870), dispatches to the action handler, and handles the
+ * no-JS validation rerender path.
+ *
+ * Returns `Response` if the request was handled as an action, `null` to
+ * fall through to normal routing.
+ */
+export function buildActionDispatcher(
+  deps: ActionDispatcherDeps
+): (
+  req: Request,
+  canonicalPath: string,
+  reenter: (req: Request) => Promise<Response>
+) => Promise<Response | null> {
+  return async (
+    req: Request,
+    canonicalPath: string,
+    reenter: (req: Request) => Promise<Response>
+  ): Promise<Response | null> => {
+    if (!isActionRequest(req)) return null;
+
+    // Route-type check (TIM-870): match the route BEFORE any body parsing.
+    // If the matched route is an API route (route.ts), skip action detection
+    // entirely — server actions only live on page routes; POSTs to route.ts
+    // are API requests whose body must reach the handler untouched.
+    //
+    // Use `canonicalPath` from the pipeline — NOT `new URL(req.url).pathname`,
+    // which re-encodes the path. The matcher expects the decoded canonical form.
+    if (deps.matchRoute) {
+      const match = deps.matchRoute(canonicalPath);
+      if (match) {
+        const leaf = match.segments[match.segments.length - 1];
+        if (leaf?.route) {
+          return null;
+        }
+      }
+    }
+
+    // Action handler dispatch
+    const actionResponse = await handleActionRequest(req, {
+      csrf: deps.csrfConfig,
+      bodyLimits: { limits: deps.bodyLimits },
+      sensitiveFields: deps.sensitiveFields,
+      revalidateRenderer: deps.buildRevalidateRenderer(req),
+    });
+
+    if (actionResponse) {
+      // No-JS validation rerender
+      if ('rerender' in actionResponse) {
+        const formRerender = actionResponse as FormRerender;
+        // Build a synthetic GET request for the rerender pipeline:
+        //   - Same URL (so route matching lands on the same page)
+        //   - Cookie header DROPPED entirely. The post-action RYW state
+        //     is threaded into the rerender request context as a parsed
+        //     `Map<string, string>` via `seedRequestCookies` below.
+        //   - Method GET because the rerender is conceptually a page render.
+        const rerenderHeaders = new Headers(req.headers);
+        rerenderHeaders.delete('cookie');
+        const rerenderReq = new Request(req.url, {
+          method: 'GET',
+          headers: rerenderHeaders,
+        });
+        seedRequestCookies(rerenderReq, formRerender.cookies);
+        const response = await runWithFormFlash(formRerender.rerender, () => reenter(rerenderReq));
+        // Apply Set-Cookie headers snapshotted from the action's ALS scope.
+        for (const value of formRerender.setCookieHeaders) {
+          response.headers.append('Set-Cookie', value);
+        }
+        return response;
+      }
+      return actionResponse;
+    }
+
+    return null;
+  };
+}