@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/server/rsc-entry/index.ts

@@ -17,71 +17,113 @@
 
 // @ts-expect-error — virtual module provided by timber-routing plugin
 import routeManifest from 'virtual:timber-route-manifest';
+// TIM-830: Populate the search-params registry eagerly so <Link> can
+// serialize flat `Partial<T>` values synchronously in RSC renders.
+// The module has side effects only — no exports consumed here.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
 // @ts-expect-error — virtual module provided by timber-build-manifest plugin
 import buildManifest from 'virtual:timber-build-manifest';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadUserInstrumentation from 'virtual:timber-instrumentation';
-
-import type { FormRerender } from '#/server/action-handler.js';
-import { handleActionRequest, isActionRequest } from '#/server/action-handler.js';
-import type { BodyLimitsConfig } from '#/server/body-limits.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
-import {
-  buildCssLinkTags,
-  buildFontPreloadTags,
-  buildModulepreloadTags,
-  collectRouteCss,
-  collectRouteFonts,
-  collectRouteModulepreloads,
-} from '#/server/build-manifest.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPage, renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import { resolveLogMode } from '#/server/dev-logger.js';
-import { sendEarlyHints103 } from '#/server/early-hints-sender.js';
-import { collectEarlyHintHeaders } from '#/server/early-hints.js';
-import { runWithFormFlash } from '#/server/form-flash.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import { buildClientScripts } from '#/server/html-injectors.js';
-import type { InterceptionContext, PipelineConfig, RouteMatch } from '#/server/pipeline.js';
-import { createPipeline } from '#/server/pipeline.js';
-import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { buildRouteElement, RouteSignalWithContext } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import { createMetadataRouteMatcher, createRouteMatcher } from '#/server/route-matcher.js';
-import { initDevTracing } from '#/server/tracing.js';
-
-import { renderFallbackError as renderFallback } from '#/server/fallback-error.js';
-import { loadInstrumentation } from '#/server/instrumentation.js';
-import { handleApiRoute } from './api-handler.js';
-import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
+// @ts-expect-error — virtual module provided by timber-entries plugin
+import loadCacheHandler from 'virtual:timber-cache-handler';
+
+import { wrapPipelineWithActionDispatch } from './wrap-action-dispatch.js';
+import type { BodyLimitsConfig } from '../body-limits.js';
+import type { BuildManifest } from '../build-manifest.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
+import { resolveLogMode } from '../../dev-tools/logger.js';
+import { sendEarlyHints103 } from '../early-hints-sender.js';
+import { collectEarlyHintHeaders } from '../early-hints.js';
+import { buildClientScripts } from '../html-injectors.js';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.js';
+import { createPipeline } from '../pipeline.js';
+import { coerceSegmentParams } from '../param-coercion.js';
+import { setSegmentParams } from '../request-context.js';
+import { buildRouteElement } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
+import { initDevTracing } from '../tracing.js';
+
+import { renderFallbackError as renderFallback } from '../fallback-error.js';
+import { loadInstrumentation } from '../instrumentation.js';
+import { loadModule } from '../safe-load.js';
+import { logRenderError } from '../logger.js';
+import { renderNoMatchPage } from './error-renderer.js';
 import {
-  buildRedirectResponse,
   createDebugChannelSink,
-  escapeHtml,
   isRscPayloadRequest,
+  type DebugComponentEntry,
 } from './helpers.js';
-import { parseClientStateTree } from '#/server/state-tree-diff.js';
-import { buildRscPayloadResponse } from './rsc-payload.js';
-import { renderRscStream } from './rsc-stream.js';
-import { renderSsrResponse } from './ssr-renderer.js';
+import { renderRoute } from './render-route.js';
 import { callSsr } from './ssr-bridge.js';
+import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
+import { setSourceMapCallback } from '../dev-source-map.js';
+import { requestContextAls } from '../als-registry.js';
+import { createAutoSitemapHandler } from '../sitemap-handler.js';
+
+/**
+ * Resolve the Server-Timing mode from timber.config.ts.
+ *
+ * If the user set `serverTiming` explicitly, use that value.
+ * Otherwise: `'detailed'` in dev, `'total'` in production.
+ */
+function resolveServerTimingMode(
+  config: Record<string, unknown>,
+  isDev: boolean
+): 'detailed' | 'total' | false {
+  const userValue = config.serverTiming as 'detailed' | 'total' | false | undefined;
+  if (userValue !== undefined) return userValue;
+  return isDev ? 'detailed' : 'total';
+}
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
-let _devPipelineErrorHandler: ((error: Error, phase: string) => void) | undefined;
+// The third argument provides RSC debug component data (from the Flight
+// debug channel) when available — used by the error overlay to show the
+// server component tree context for render errors.
+let _devPipelineErrorHandler:
+  | ((error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void)
+  | undefined;
 
 /**
  * Set the dev pipeline error handler.
  *
  * Called by the dev server after importing this module to wire pipeline
  * errors into the Vite browser error overlay. No-op in production.
+ *
+ * The handler receives an optional third argument with RSC debug component
+ * info — component names, environments, and stack frames from the Flight
+ * debug channel. This is only populated for render-phase errors.
  */
-export function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void {
+export function setDevPipelineErrorHandler(
+  handler: (error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void
+): void {
   _devPipelineErrorHandler = handler;
 }
 
+/**
+ * Set the dev source-map handler.
+ *
+ * Called by the dev server after importing this module to wire Vite's
+ * module graph source-mapping into the error rendering pipeline. Errors
+ * rendered by renderErrorPage / renderFallbackError will have their
+ * stack traces rewritten to show original source positions.
+ *
+ * No-op in production.
+ */
+export function setDevSourceMapHandler(handler: (error: Error) => void): void {
+  setSourceMapCallback(handler);
+}
+
+// Dev-only: debug components getter is stored per-request in ALS
+// (RequestContextStore.debugComponentsGetter) to avoid cross-request
+// race conditions. See TIM-557.
+
 /**
  * Create the RSC request handler from the route manifest.
  *
@@ -95,13 +137,25 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   // See design/17-logging.md §"register() — Server Startup"
   await loadInstrumentation(loadUserInstrumentation);
 
-  // Initialize cookie signing secrets from config (design/29-cookies.md §"Signed Cookies")
-  const cookieSecrets = (runtimeConfig as Record<string, unknown>).cookieSecrets as
-    | string[]
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // The manifest init module sets globalThis.__TIMBER_DEPLOYMENT_ID__ at startup.
+  // In dev mode this is undefined — skew checks are skipped.
+  const deploymentId = (globalThis as Record<string, unknown>).__TIMBER_DEPLOYMENT_ID__ as
+    | string
     | undefined;
-  if (cookieSecrets?.length) {
-    const { setCookieSecrets } = await import('#/server/request-context.js');
-    setCookieSecrets(cookieSecrets);
+  if (deploymentId) {
+    const { setDeploymentId } = await import('../version-skew.js');
+    setDeploymentId(deploymentId);
+  }
+
+  // Wire the configured cache handler into the module-level singleton (TIM-599).
+  // The cacheHandler is a class instance (e.g. RedisCacheHandler) that can't be
+  // JSON-serialized into virtual:timber-config. Instead, virtual:timber-cache-handler
+  // dynamically imports the user's timber.config.ts and extracts the handler.
+  const userCacheHandler = await loadCacheHandler();
+  if (userCacheHandler) {
+    const { setCacheHandler } = await import('../../cache/handler-store.js');
+    setCacheHandler(userCacheHandler as Parameters<typeof setCacheHandler>[0]);
   }
 
   const matchRoute = createRouteMatcher(manifest);
@@ -121,27 +175,64 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     buildManifest: buildManifest as BuildManifest,
   });
 
-  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
-  // In production, isDev is false — no tracing, no overhead.
-  // The DevSpanProcessor handles all formatting and stderr output.
-  const isDev = process.env.NODE_ENV !== 'production';
+  // Initialize debug flag from config before anything else.
+  // This allows timber.config.ts `debug: true` to enable debug logging
+  // in production without the TIMBER_DEBUG env var.
+  if ((runtimeConfig as Record<string, unknown>).debug) {
+    setDebugFromConfig(true);
+  }
+
+  // Wire the global sensitive-field stripping config so `createActionClient`
+  // instances in user code pick up `forms.stripSensitiveFields` from
+  // `timber.config.ts` without needing to plumb config through each action.
+  // See TIM-816 and design/08-forms-and-actions.md §"Validation errors".
+  const formsConfig = (runtimeConfig as Record<string, unknown>).forms as
+    | { stripSensitiveFields?: import('../sensitive-fields.js').SensitiveFieldsOption }
+    | undefined;
+  if (formsConfig) {
+    const { setGlobalSensitiveFieldsConfig } = await import('../sensitive-fields.js');
+    setGlobalSensitiveFieldsConfig(formsConfig.stripSensitiveFields);
+  }
+
+  // Two separate flags for two different security levels:
+  //
+  // isDev (isDevMode) — gates client-visible behavior: dev error pages with
+  //   stack traces, detailed Server-Timing headers, error messages in action
+  //   payloads. Statically replaced in production → tree-shaken to zero.
+  //   TIMBER_DEBUG cannot enable this.
+  //
+  // debugEnabled (isDebug) — gates server-side logging only: stderr warnings,
+  //   OTEL dev tracing, console.error fallbacks. TIMBER_DEBUG enables this.
+  //   Never affects what clients see.
+  const isDev = isDevMode();
+  const debugEnabled = isDebug();
   const slowPhaseMs = (runtimeConfig as Record<string, unknown>).slowPhaseMs as number | undefined;
 
-  if (isDev) {
+  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
+  // In production with TIMBER_DEBUG, this enables server-side tracing output
+  // without exposing anything to clients.
+  if (debugEnabled) {
     const devLogMode = resolveLogMode();
     if (devLogMode !== 'quiet') {
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
       // Patch globalThis.fetch to create OTEL spans for fetch calls.
       // Spans appear as children of the active component span in the dev log tree.
-      const { instrumentDevFetch } = await import('../dev-fetch-instrumentation.js');
+      const { instrumentDevFetch } = await import('../../dev-tools/instrumentation.js');
       instrumentDevFetch();
     }
   }
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
+  // The routing plugin emits `manifest.proxy = { load, filePath }` only when
+  // the app has an `app/proxy.ts`. Convert that to the pipeline's lazy variant
+  // so HMR re-imports per request; leave it undefined when there's no proxy.
+  const proxyConfig: PipelineConfig['proxy'] = manifest.proxy?.load
+    ? { kind: 'lazy', loader: manifest.proxy.load }
+    : undefined;
+
   const pipelineConfig: PipelineConfig = {
-    proxyLoader: manifest.proxy?.load,
+    proxy: proxyConfig,
     matchRoute,
     matchMetadataRoute,
     // 103 Early Hints — fires after route match, before middleware.
@@ -149,11 +240,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // so the browser starts fetching critical resources while the server renders.
     // In dev mode the manifest is empty — no hints are sent.
     earlyHints: (match: RouteMatch, _req: Request, responseHeaders: Headers) => {
-      const segments = match.segments as unknown as Array<{
-        layout?: { filePath: string };
-        page?: { filePath: string };
-      }>;
-      const headers = collectEarlyHintHeaders(segments, typedBuildManifest, {
+      const headers = collectEarlyHintHeaders(match.segments, typedBuildManifest, {
         skipJs: clientJsDisabled,
       });
       for (const h of headers) {
@@ -174,33 +261,163 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         req,
         match,
         responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
+        {
+          clientBootstrap,
+          clientJsDisabled,
+          rootSegment: manifest.root,
+          buildManifest: typedBuildManifest,
+          globalError: manifest.globalError,
+        },
         interception
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
-      return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
+      const response = await renderNoMatchPage(
+        req,
+        manifest.root,
+        responseHeaders,
+        clientBootstrap
+      );
+
+      // In dev mode, if the pipeline returned a bare 404 (no body — meaning
+      // no user-defined 404.tsx was found), replace it with a helpful dev
+      // page that lists available routes and suggests similar paths.
+      // Only for GET requests that accept HTML — HEAD/API/RSC clients
+      // should receive the bare 404 without an HTML body (TIM-793).
+      const acceptsHtml = (req.headers.get('accept') ?? '').includes('text/html');
+      if (isDev && !response.body && req.method === 'GET' && acceptsHtml) {
+        const { generateDev404Page, collectRoutes } = await import('../../dev-tools/404-page.js');
+        const routes = collectRoutes(manifest.root);
+        const pathname = new URL(req.url).pathname;
+        const html = generateDev404Page(pathname, routes);
+        return new Response(html, {
+          status: 404,
+          headers: {
+            ...Object.fromEntries(responseHeaders.entries()),
+            'content-type': 'text/html; charset=utf-8',
+          },
+        });
+      }
+
+      return response;
     },
     interceptionRewrites: manifest.interceptionRewrites,
     // Slow request threshold from timber.config.ts. Default 3000ms, 0 to disable.
     // See design/17-logging.md §"slowRequestMs"
     slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
-    enableServerTiming: isDev,
+    serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
     onPipelineError: isDev
       ? (error: Error, phase: string) => {
-          if (_devPipelineErrorHandler) _devPipelineErrorHandler(error, phase);
+          if (_devPipelineErrorHandler) {
+            // For render-phase errors, include RSC debug component data
+            // from the Flight debug channel (if available from the current request).
+            const store = requestContextAls.getStore();
+            const debugComponents =
+              phase === 'render' && store?.debugComponentsGetter
+                ? store.debugComponentsGetter()
+                : undefined;
+            _devPipelineErrorHandler(error, phase, debugComponents);
+          }
         }
       : undefined,
+
     renderFallbackError: (error, req, responseHeaders) =>
-      renderFallback(error, req, responseHeaders, isDev, manifest.root, clientBootstrap),
+      renderFallback(
+        error,
+        req,
+        responseHeaders,
+        isDev,
+        manifest.root,
+        clientBootstrap,
+        manifest.globalError,
+        // Project root for dev error page frame classification.
+        // Not in runtimeConfig (TIM-787: leaked to client bundles).
+        // manifest.viteRoot is the resolved Vite root string — correct even
+        // when CWD differs from project root (e.g., monorepo custom root)
+        // (TIM-807). Passing manifest.root (segment tree object) here would
+        // stringify to "[object Object]" and misclassify app frames as
+        // internal, dropping source locations from the dev error page (TIM-808).
+        isDev ? manifest.viteRoot : undefined
+      ),
+    renderDenyFallback: async (deny, req, responseHeaders, matchedRoute) => {
+      // Render the deny page (403.tsx, 404.tsx, etc.) for DenySignals
+      // that escape from middleware or the render phase.
+      //
+      // When the pipeline already matched a route (the common case — matching
+      // runs before middleware and rendering), resolve the status file against
+      // the matched chain so colocated files like a nested `403.tsx` or an API
+      // route's `401.json` are picked up. Fall back to the root chain when no
+      // match is available (e.g. proxy-stage deny before route matching).
+      // See TIM-822, design/04-authorization.md, design/10-error-handling.md.
+      const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [manifest.root];
+      const layoutComponents: LayoutEntry[] = [];
+      try {
+        for (const segment of chain) {
+          if (!segment.layout) continue;
+          const mod = await loadModule(segment.layout);
+          if (mod.default) {
+            layoutComponents.push({
+              component: mod.default as (...args: unknown[]) => unknown,
+              segment,
+            });
+          }
+        }
+      } catch (layoutError) {
+        // Layout failed to load — proceed without it. Partial layout chains
+        // are acceptable; the deny renderer wraps in whatever loaded.
+        logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
+      }
+      // Reuse the matched route's params/middleware metadata when present so
+      // downstream rendering sees the real route shape. Otherwise synthesise
+      // a root-only stub (no params, no middleware).
+      const match: RouteMatch = matchedRoute ?? {
+        segments: chain,
+        segmentParams: {},
+        middlewareChain: [],
+      };
+      // For client navigation (Accept: text/x-component), the timber router
+      // decodes the response as React Flight. Returning HTML to a Flight
+      // decoder breaks navigation, so dispatch to the RSC renderer when the
+      // request is an RSC payload request — mirroring the normal render path.
+      // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
+      if (isRscPayloadRequest(req)) {
+        return renderDenyPageAsRsc(
+          deny,
+          chain,
+          layoutComponents,
+          responseHeaders,
+          createDebugChannelSink
+        );
+      }
+      return renderDenyPage(
+        deny,
+        chain,
+        layoutComponents,
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        createDebugChannelSink,
+        callSsr
+      );
+    },
+    // Auto-generated sitemap handler — enabled when sitemap.enabled is true
+    // and no user-authored sitemap exists at the app root.
+    // See design/16-metadata.md §"Auto-generated Sitemap"
+    autoSitemapHandler: createAutoSitemapHandler(manifest.root, runtimeConfig),
   };
 
   const pipeline = createPipeline(pipelineConfig);
 
-  // Wrap the pipeline to intercept server action requests before rendering.
-  // Actions bypass the normal pipeline (no route matching, no middleware)
-  // per design/08-forms-and-actions.md §"Middleware for Server Actions".
+  // Wrap the pipeline to enforce CSRF at the request boundary and intercept
+  // server action requests. By default, the wrapper also runs the matched
+  // route's `middleware.ts` chain on action POSTs, so authentication, rate
+  // limiting, tenant isolation, and request-header injection apply to
+  // actions just like they do to page renders. See TIM-871 and
+  // design/08-forms-and-actions.md §"Middleware for Server Actions".
+  //
+  // CSRF validation lives in the wrapper (not inside the action handler) so
+  // it covers route.ts API handlers as well as server actions. See LOCAL-773.
   const csrfConfig = {
     csrf: runtimeConfig.csrf,
     allowedOrigins: (runtimeConfig as Record<string, unknown>).allowedOrigins as
@@ -208,259 +425,60 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       | undefined,
   };
 
-  return async (req: Request): Promise<Response> => {
-    if (isActionRequest(req)) {
-      const actionResponse = await handleActionRequest(req, {
-        csrf: csrfConfig,
-        bodyLimits: {
-          limits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
-        },
-        revalidateRenderer: async (path: string) => {
-          // Build the React element tree for the route at `path`.
-          // Returns the element tree (not serialized) so the action handler can
-          // combine it with the action result in a single renderToReadableStream call.
-          // Forward original request headers (cookies, session IDs, etc.).
-          const revalidateHeaders = new Headers(req.headers);
-          revalidateHeaders.set('Accept', 'text/x-component');
-          const revalidateReq = new Request(new URL(path, req.url), {
-            headers: revalidateHeaders,
-          });
-          const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
-          if (!revalidateMatch) {
-            throw new Error(`revalidatePath('${path}') — no matching route`);
-          }
-          const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
-          return {
-            element: routeResult.element,
-            headElements: routeResult.headElements,
-          };
-        },
-      });
-      if (actionResponse) {
-        // Check if this is a re-render signal (no-JS validation failure)
-        if ('rerender' in actionResponse) {
-          const formRerender = actionResponse as FormRerender;
-          // Re-render the page with the action result as flash data.
-          // Server components read it via getFormFlash() and pass it to
-          // client form components as the initial useActionState value.
-          const response = await runWithFormFlash(formRerender.rerender, () => pipeline(req));
-          return response;
-        }
-        return actionResponse;
-      }
-    }
-    return pipeline(req);
-  };
-}
-
-/**
- * Render a matched route to an HTML Response via RSC → SSR pipeline,
- * or return a raw RSC Flight stream for client-side navigation requests.
- *
- * 1. Load page/layout components from the segment chain
- * 2. Resolve metadata
- * 3. Render to RSC Flight stream (serializes "use client" as references)
- * 4. If Accept: text/x-component → return RSC stream directly
- *    Otherwise → pass RSC stream to SSR entry for HTML rendering
- */
-async function renderRoute(
-  _req: Request,
-  match: RouteMatch,
-  responseHeaders: Headers,
-  clientBootstrap: ClientBootstrapConfig,
-  clientJsDisabled: boolean,
-  interception?: InterceptionContext
-): Promise<Response> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
-  const leaf = segments[segments.length - 1];
-
-  // API routes (route.ts) — run access.ts standalone then dispatch to handler.
-  // No React render pass — AccessGate is not used, React.cache is not active.
-  // See design/04-authorization.md §"Auth in API Routes".
-  if (leaf.route && !leaf.page) {
-    return handleApiRoute(_req, match, segments, responseHeaders);
-  }
-
-  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
-  // The state tree lists sync segments the client has cached — the server
-  // skips re-rendering those layouts for a smaller, faster RSC payload.
-  // Only used for RSC requests — HTML requests always get a full render.
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const clientStateTree = isRscPayloadRequest(_req) ? parseClientStateTree(_req) : null;
+  const actionsConfig = (runtimeConfig as Record<string, unknown>).actions as
+    | { runMiddleware?: boolean }
+    | undefined;
 
-  // Build the React element tree — loads modules, runs access checks,
-  // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
-  let routeResult;
-  try {
-    routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
-  } catch (error) {
-    // RouteSignalWithContext wraps DenySignal/RedirectSignal with layout context
-    if (error instanceof RouteSignalWithContext) {
-      const { signal, layoutComponents: lc, segments: segs } = error;
-      if (signal instanceof DenySignal) {
-        if (isRscPayloadRequest(_req)) {
-          return renderDenyPageAsRsc(
-            signal,
-            segs,
-            lc as LayoutEntry[],
-            responseHeaders,
-            createDebugChannelSink
-          );
-        }
-        return renderDenyPage(
-          signal,
-          segs,
-          lc as LayoutEntry[],
-          _req,
-          match,
-          responseHeaders,
-          clientBootstrap,
-          createDebugChannelSink,
-          callSsr
-        );
-      }
-      if (signal instanceof RedirectSignal) {
-        return buildRedirectResponse(_req, signal, responseHeaders);
+  return wrapPipelineWithActionDispatch(pipeline, {
+    csrfConfig,
+    bodyLimits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
+    sensitiveFields: formsConfig?.stripSensitiveFields,
+    matchRoute,
+    coerceSegmentParams,
+    renderDenyFallback: pipelineConfig.renderDenyFallback,
+    runMiddleware: actionsConfig?.runMiddleware,
+    // Thread the pipeline's `stripTrailingSlash` setting into the wrapper
+    // so its canonicalization step (applied before `matchRoute` for
+    // action POSTs) matches the page pipeline exactly. Defaults to `true`
+    // both here and inside the wrapper.
+    stripTrailingSlash: pipelineConfig.stripTrailingSlash,
+    buildRevalidateRenderer: (req) => async (path: string) => {
+      // Build the React element tree for the route at `path`.
+      // Returns the element tree (not serialized) so the action handler can
+      // combine it with the action result in a single renderToReadableStream call.
+      // Forward original request headers (cookies, session IDs, etc.).
+      const revalidateHeaders = new Headers(req.headers);
+      revalidateHeaders.set('Accept', 'text/x-component');
+      const revalidateReq = new Request(new URL(path, req.url), {
+        headers: revalidateHeaders,
+      });
+      const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
+      if (!revalidateMatch) {
+        throw new Error(`revalidatePath('${path}') — no matching route`);
       }
-    }
-    // No PageComponent found
-    if (error instanceof Error && error.message.startsWith('No page component')) {
-      return new Response(null, { status: 404 });
-    }
-    throw error;
-  }
-
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
-
-  // Build head HTML for injection into the SSR output.
-  // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
-  // In dev mode the manifest is empty — Vite HMR handles CSS/JS.
-  //
-  // Link headers (for 103 Early Hints) are emitted by the earlyHints pipeline
-  // stage before middleware runs. Here we only emit the <head> HTML fallback tags
-  // — these ensure resources load even on platforms without Early Hints support.
-  const typedManifest = buildManifest as BuildManifest;
-  let headHtml = '';
-
-  const cssUrls = collectRouteCss(segments, typedManifest);
-  if (cssUrls.length > 0) {
-    headHtml += buildCssLinkTags(cssUrls);
-  }
-
-  const fontEntries = collectRouteFonts(segments, typedManifest);
-  if (fontEntries.length > 0) {
-    headHtml += buildFontPreloadTags(fontEntries);
-  }
-
-  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
-  if (!clientJsDisabled) {
-    const preloadUrls = collectRouteModulepreloads(segments, typedManifest);
-    if (preloadUrls.length > 0) {
-      headHtml += buildModulepreloadTags(preloadUrls);
-    }
-  }
-
-  for (const el of headElements) {
-    if (el.tag === 'title' && el.content) {
-      headHtml += `<title>${escapeHtml(el.content)}</title>`;
-    } else if (el.attrs) {
-      const attrs = Object.entries(el.attrs)
-        .filter(([, v]) => v != null)
-        .map(([k, v]) => `${k}="${escapeHtml(v as string)}"`)
-        .join(' ');
-      headHtml += `<${el.tag} ${attrs}>`;
-    }
-  }
-
-  // Render to RSC Flight stream with signal tracking.
-  const { rscStream, signals } = renderRscStream(element, _req);
-
-  // Synchronous redirect — redirect() in access.ts or a non-async component
-  // throws during renderToReadableStream creation. Return HTTP redirect.
-  if (signals.redirectSignal) {
-    return buildRedirectResponse(_req, signals.redirectSignal, responseHeaders);
-  }
-
-  // Synchronous deny — deny() in a non-async component throws during
-  // renderToReadableStream creation, caught in the try/catch above.
-  if (signals.denySignal) {
-    if (isRscPayloadRequest(_req)) {
-      return renderDenyPageAsRsc(
-        signals.denySignal,
-        segments,
-        layoutComponents as LayoutEntry[],
-        responseHeaders,
-        createDebugChannelSink
-      );
-    }
-    return renderDenyPage(
-      signals.denySignal,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap,
-      createDebugChannelSink,
-      callSsr
-    );
-  }
-
-  // Synchronous render error — renderToReadableStream threw before
-  // creating the stream. Render the error page with correct 5xx status.
-  // (Async render errors are tracked in onError and handled after SSR.)
-  if (signals.renderError && !rscStream) {
-    return renderErrorPage(
-      signals.renderError.error,
-      signals.renderError.status,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap
-    );
-  }
-
-  // For RSC payload requests (client navigation), return the RSC Flight
-  // stream directly — skip SSR HTML rendering entirely.
-  // See design/19-client-navigation.md §"RSC Payload Handling"
-  if (isRscPayloadRequest(_req)) {
-    return buildRscPayloadResponse(
-      _req,
-      rscStream!,
-      signals,
-      segments,
-      layoutComponents,
-      headElements,
-      match,
-      responseHeaders,
-      skippedSegments
-    );
-  }
-
-  // Pipe through SSR for HTML rendering with streaming Suspense support.
-  return renderSsrResponse({
-    req: _req,
-    rscStream: rscStream!,
-    signals,
-    segments,
-    layoutComponents,
-    match,
-    responseHeaders,
-    clientBootstrap,
-    clientJsDisabled,
-    headHtml,
-    deferSuspenseFor,
+      // Coerce segment params (params.ts) before building the element tree.
+      // Without this, components receive raw strings instead of typed values.
+      await coerceSegmentParams(revalidateMatch);
+      // Set coerced params in ALS so getSegmentParams() works during the
+      // revalidation render (AccessGate reads params via ALS). Without this,
+      // AccessGate → getSegmentParams() throws because segmentParams
+      // is never set. See TIM-667.
+      setSegmentParams(revalidateMatch.segmentParams);
+      const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
+      return {
+        element: routeResult.element,
+        headElements: routeResult.headElements,
+      };
+    },
   });
 }
 
 // Re-export for generated entry points (e.g., Nitro node-server/bun) to wrap
 // the handler with per-request 103 Early Hints sender via ALS.
-export { runWithEarlyHintsSender } from '#/server/early-hints-sender.js';
+export { runWithEarlyHintsSender } from '../early-hints-sender.js';
 
 // Re-export for generated entry points to wrap the handler with per-request
 // waitUntil support via ALS. See design/11-platform.md §"waitUntil()".
-export { runWithWaitUntil } from '#/server/waituntil-bridge.js';
+export { runWithWaitUntil } from '../waituntil-bridge.js';
 
 export default await createRequestHandler(routeManifest, config);