@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

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

@@ -17,72 +17,86 @@
 
 // @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';
-import {
-  buildRedirectResponse,
-  createDebugChannelSink,
-  escapeHtml,
-  isRscPayloadRequest,
-} 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';
+// @ts-expect-error — virtual module provided by timber-entries plugin
+import loadCacheHandler from 'virtual:timber-cache-handler';
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import globalSchemaCodecs from 'virtual:timber-schema';
+
+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, setGlobalSchemaCodecs } 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 { createDebugChannelSink, isRscPayloadRequest } from './helpers.js';
+import { renderRoute } from './render-route.js';
 import { callSsr } from './ssr-bridge.js';
-import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.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';
 
-// 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;
+/**
+ * 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';
+}
 
 /**
- * Set the dev pipeline error 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.
  *
- * Called by the dev server after importing this module to wire pipeline
- * errors into the Vite browser error overlay. No-op in production.
+ * No-op in production.
  */
-export function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void {
-  _devPipelineErrorHandler = handler;
+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.
  *
@@ -96,18 +110,37 @@ 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);
   const matchMetadataRoute = createMetadataRouteMatcher(manifest);
 
+  // TIM-931: Register global schema codecs for param coercion.
+  // When app/schema.ts exists, globalSchemaCodecs is a Record<string, Codec>;
+  // otherwise null. Registered once at startup so all coercion paths
+  // (pipeline-phases.ts, action-middleware-runner.ts, revalidation) share
+  // the same codec source.
+  setGlobalSchemaCodecs(globalSchemaCodecs);
+
   // Build the client bootstrap configuration.
   // When client JavaScript is disabled, no scripts are injected
   // (unless enableHMRInDev is true in dev mode — then only HMR client).
@@ -129,6 +162,18 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     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
@@ -152,15 +197,22 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       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.
@@ -168,11 +220,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) {
@@ -193,33 +241,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 (pipelineConfig.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;
+            pipelineConfig.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
@@ -227,268 +405,79 @@ 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);
-  }
+  const actionsConfig = (runtimeConfig as Record<string, unknown>).actions as
+    | { runMiddleware?: boolean }
+    | undefined;
 
-  // 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;
-
-  // 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);
+  const handler = 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);
-  }
-
-  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
-  // The font CSS is set on globalThis by the transformed font file's
-  // side-effect import of virtual:timber-font-css-register.
-  const fontCss = (globalThis as Record<string, unknown>).__timber_font_css as string | undefined;
-  if (fontCss) {
-    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
-  }
-
-  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
+      // 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,
+        undefined,
+        null,
+        (buildManifest as BuildManifest).metadataRouteHashes
       );
-    }
-    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,
+      return {
+        element: routeResult.element,
+        headElements: routeResult.headElements,
+      };
+    },
   });
+
+  return { handler, pipelineConfig };
 }
 
 // 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';
+
+const { handler: _handler, pipelineConfig: _pipelineConfig } = await createRequestHandler(
+  routeManifest,
+  config
+);
+
+/**
+ * The pipeline configuration object. Exported so the dev server can set
+ * `devPipelineErrorHandler` after import without a module-level singleton.
+ */
+export const pipelineConfig = _pipelineConfig;
 
-export default await createRequestHandler(routeManifest, config);
+export default _handler;