@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

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

@@ -17,57 +17,56 @@
 
 // @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-entries plugin
+import { loadCdnPurgeHandler } 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 type { ManifestSegmentNode } from '../route-matcher.js';
+import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
+import { initDevTracing } from '../tracing.js';
+import { createRevalidateRendererFactory } from './revalidate-renderer.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 { capturePrebuiltPayloads } from '../prebuilt-builder.js';
+import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.js';
+import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.js';
+import { createAutoSitemapHandler } from '../sitemap-handler.js';
 
 /**
  * Resolve the Server-Timing mode from timber.config.ts.
@@ -84,20 +83,24 @@ function resolveServerTimingMode(
   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;
-
 /**
- * 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.
  *
@@ -105,21 +108,84 @@ export function setDevPipelineErrorHandler(handler: (error: Error, phase: string
  * 103 Early Hints → middleware.ts → render (RSC → SSR → HTML).
  */
 async function createRequestHandler(manifest: typeof routeManifest, runtimeConfig: typeof config) {
-  // Load the user's instrumentation.ts — register() is awaited before the
-  // server accepts any requests. The logger and onRequestError hooks are
-  // wired into the framework. This runs once at startup.
-  // 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 CDN purge handler so revalidateTag triggers CDN purge (TIM-1166).
+  const userCdnPurge = await loadCdnPurgeHandler();
+  if (userCdnPurge) {
+    const { setCdnPurgeHandler } = await import('../../cdn/purge-store.js');
+    setCdnPurgeHandler(userCdnPurge as Parameters<typeof setCdnPurgeHandler>[0]);
+  } else if (typeof process !== 'undefined' && process.env?.TIMBER_RUNTIME === 'cloudflare') {
+    // Auto-wire Workers Cache purge on Cloudflare — no API token needed,
+    // available on all plans via ctx.cache.purge({ tags }) (TIM-1170).
+    const { WorkersCachePurge } = await import('../../cdn/workers-cache-purge.js');
+    const { setCdnPurgeHandler } = await import('../../cdn/purge-store.js');
+    setCdnPurgeHandler(new WorkersCachePurge());
+  }
+
+  // Wire the prebuilt payload source so cache.component wrappers can look
+  // up cached flight payloads at request time (TIM-1122). The source is
+  // platform-aware: Node/Nitro reads from disk; Cloudflare reads from
+  // static assets via globalThis.__TIMBER_PREBUILT_SOURCE__ (set by the
+  // generated _worker.js before this module loads).
+  // In dev mode there are no prebuilt artifacts — source stays null and
+  // all cache.component wrappers render dynamically.
+  if (!isDevMode()) {
+    const platformSource = (globalThis as Record<string, unknown>).__TIMBER_PREBUILT_SOURCE__ as
+      | import('../prebuilt/payload-source.js').PrebuiltPayloadSource
+      | undefined;
+    if (platformSource) {
+      setPrebuiltPayloadSource(platformSource);
+    } else {
+      // Default: Node/fs-based source — prebuilt/ is alongside rsc/ in the
+      // adapter output directory, so resolve relative to this entry.
+      try {
+        const { readFile: fsReadFile } = await import('node:fs/promises');
+        const { join: pathJoin, dirname } = await import('node:path');
+        const { fileURLToPath } = await import('node:url');
+        const entryDir = dirname(fileURLToPath(import.meta.url));
+        const prebuiltDir = pathJoin(entryDir, '..', 'prebuilt');
+        setPrebuiltPayloadSource({
+          async loadManifest() {
+            try {
+              const data = await fsReadFile(pathJoin(prebuiltDir, 'manifest.json'), 'utf-8');
+              return JSON.parse(data);
+            } catch {
+              return null;
+            }
+          },
+          async readPayload(file) {
+            try {
+              return await fsReadFile(pathJoin(prebuiltDir, file));
+            } catch {
+              return null;
+            }
+          },
+        });
+      } catch {
+        // node:fs not available (e.g. edge runtimes without the global
+        // override) — source stays null, wrappers render dynamically.
+      }
+    }
   }
 
+  // Wire RSC flight functions so prebuilt-runtime can revive cached payloads
+  // and capture re-renders without a dynamic import (TIM-1165).
+  const rscMod = await import('../../rsc-runtime/rsc.js');
+  setRscFunctions({
+    createFromReadableStream: rscMod.createFromReadableStream,
+    renderToReadableStream: rscMod.renderToReadableStream,
+  });
+
   const matchRoute = createRouteMatcher(manifest);
   const matchMetadataRoute = createMetadataRouteMatcher(manifest);
 
@@ -134,6 +200,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   const clientBootstrap = buildClientScripts({
     ...runtimeConfig,
     clientJavascript: clientJsConfig ?? { disabled: false, enableHMRInDev: false },
+    devBrowserLogs: (runtimeConfig as Record<string, unknown>).devBrowserLogs as string | undefined,
     buildManifest: buildManifest as BuildManifest,
   });
 
@@ -144,6 +211,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
@@ -167,15 +246,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.
@@ -183,11 +269,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) {
@@ -208,13 +290,47 @@ 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;
+        // devHmrOptions is set by the dev server after this module is
+        // imported (read at request time, not closure-capture time).
+        const html = generateDev404Page(pathname, routes, pipelineConfig.devHmrOptions);
+        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.
@@ -223,18 +339,120 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     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,
+        // HMR options for the dev error page's auto-reload WebSocket —
+        // set by the dev server after import, read at request time.
+        isDev ? pipelineConfig.devHmrOptions : 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,
+          req,
+          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
@@ -242,268 +460,114 @@ 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;
-
-  // 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);
-      }
-    }
-    // No PageComponent found
-    if (error instanceof Error && error.message.startsWith('No page component')) {
-      return new Response(null, { status: 404 });
-    }
-    throw error;
-  }
+  const actionsConfig = (runtimeConfig as Record<string, unknown>).actions as
+    | { runMiddleware?: boolean }
+    | undefined;
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
-    routeResult;
+  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,
+    // Revalidation renderer — runs the target route's `middleware.ts`
+    // chain BEFORE building the element tree so a server action that
+    // revalidates a protected path honors that path's auth, tenant
+    // isolation, and request-header injection. Closes the silent-bypass
+    // bug where `revalidatePath('/admin')` from a public action would
+    // serialize the admin RSC tree without ever consulting admin's
+    // middleware. Also validates the user-supplied `path` as a local
+    // root-relative URL to reject `revalidatePath('//evil.com/admin')`
+    // and similar scheme/authority injections. See TIM-996 and
+    // design/08-forms-and-actions.md §"revalidatePath()".
+    buildRevalidateRenderer: createRevalidateRendererFactory({
+      matchRoute,
+      coerceSegmentParams,
+      buildManifest: buildManifest as BuildManifest,
+    }),
+  });
 
-  // 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);
-  }
+  return { handler, pipelineConfig };
+}
 
-  // 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>`;
-  }
+// 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 '../early-hints-sender.js';
 
-  const fontEntries = collectRouteFonts(segments, typedManifest);
-  if (fontEntries.length > 0) {
-    headHtml += buildFontPreloadTags(fontEntries);
-  }
+// 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 '../waituntil-bridge.js';
 
-  // 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);
-    }
-  }
+// Re-export for the Cloudflare adapter's generated _worker.js to bridge
+// ctx.cache from the ExecutionContext into the per-request ALS. The
+// WorkersCachePurge handler reads from this ALS to call ctx.cache.purge().
+export { runWithWorkersCachePurge } from '../workers-cache-bridge.js';
 
-  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}>`;
-    }
-  }
+/**
+ * Post-build flight capture entry point (TIM-1119). The capture pass must
+ * run inside the built RSC bundle — the prebuilt component registry, the
+ * ALS instances, and the flight renderer are module instances in THIS
+ * bundle's graph; an outside import of the framework package would get
+ * fresh, empty copies. The timber-prebuilt plugin imports the built
+ * `rsc/index.js` after the 5-step build and calls this export.
+ * See design/44-render-at-build-time.md §Build Phase.
+ */
+export function __timber_capturePrebuilt(
+  options: import('../prebuilt-builder.js').CaptureOptions
+): Promise<import('../prebuilt-builder.js').CaptureSummary> {
+  return capturePrebuiltPayloads(routeManifest, options);
+}
 
-  // Render to RSC Flight stream with signal tracking.
-  const { rscStream, signals } = renderRscStream(element, _req);
+// Schema codecs are needed by both the capture path (param coercion) and
+// the request handler, so register them unconditionally.
+setGlobalSchemaCodecs(globalSchemaCodecs);
+
+// Singleflight timeout protects against deadlocked cache calls — needed
+// in both capture mode (components may call timber.cache) and normal mode.
+const renderTimeoutMs = (config as Record<string, unknown>).renderTimeoutMs as number | undefined;
+if (renderTimeoutMs) {
+  const { setDefaultSingleflightTimeout } = await import('../../cache/timber-cache.js');
+  setDefaultSingleflightTimeout(renderTimeoutMs);
+  setComponentRefreshTimeout(renderTimeoutMs);
+}
 
-  // 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);
-  }
+// Run instrumentation before the capture-mode guard — components may
+// depend on globals or SDKs initialized in register().
+await loadInstrumentation(loadUserInstrumentation);
 
-  // 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
-    );
-  }
+// Wire the cache handler — prebuilt components may call timber.cache
+// during capture and must see the configured store, not the fallback.
+const userCacheHandler = await loadCacheHandler();
+if (userCacheHandler) {
+  const { setCacheHandler } = await import('../../cache/handler-store.js');
+  setCacheHandler(userCacheHandler as Parameters<typeof setCacheHandler>[0]);
+}
 
-  // 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
-    );
-  }
+// In capture mode the plugin only calls __timber_capturePrebuilt — skip
+// the remaining production startup (CDN purge, OTEL, route matchers)
+// which is expensive and unnecessary.
+const isCaptureMode = !!(globalThis as Record<string, unknown>).__TIMBER_CAPTURE_MODE__;
 
-  // 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
-    );
-  }
+let _handler: ((req: Request) => Promise<Response>) | undefined;
+let _pipelineConfig: PipelineConfig | undefined;
 
-  // 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,
-  });
+if (!isCaptureMode) {
+  const result = await createRequestHandler(routeManifest, config);
+  _handler = result.handler;
+  _pipelineConfig = result.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';
-
-// 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';
+/**
+ * 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!;