@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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

@@ -12,6 +12,14 @@
  * references. The stream is then passed to the SSR entry (in a separate
  * Vite environment) which decodes it and renders HTML.
  *
+ * This file is intentionally orchestration-only (audited: TIM-968). It
+ * wires virtual modules, config, and one-time startup (cache handler,
+ * instrumentation, CDN purge, prebuilt payload source) into the pipeline
+ * and delegates all rendering work to siblings in this directory
+ * (render-route.ts, error-renderer.ts, deny-fallback.ts,
+ * revalidate-renderer.ts, wrap-action-dispatch.ts, ...). Don't add
+ * rendering or response-shaping logic here — extract it to a sibling.
+ *
  * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
  */
 
@@ -23,81 +31,76 @@ import config from 'virtual:timber-config';
 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';
-import { callSsr } from './ssr-bridge.js';
-import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.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, buildActionDispatcher } from './wrap-action-dispatch.ts';
+import type { BodyLimitsConfig } from '../body-limits.ts';
+import type { BuildManifest } from '../build-manifest.ts';
+import { resolveLogMode } from '../../dev-tools/logger.ts';
+import { sendEarlyHints103 } from '../early-hints-sender.ts';
+import { collectEarlyHintHeaders } from '../early-hints.ts';
+import { buildClientScripts } from '../html-injectors.ts';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.ts';
+import { createPipeline } from '../pipeline.ts';
+import { coerceSegmentParams, setGlobalSchemaCodecs } from '../param-coercion.ts';
+import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.ts';
+import { createInterceptedRouteMatcher } from '../children-interception.ts';
+import { initDevTracing } from '../tracing.ts';
+import { createRevalidateRendererFactory } from './revalidate-renderer.ts';
+
+import { renderFallbackError as renderFallback } from '../fallback-error.ts';
+import { loadInstrumentation } from '../instrumentation.ts';
+import { createDenyFallbackRenderer } from './deny-fallback.ts';
+import { renderNoMatchPage } from './error-renderer.ts';
+import { renderRoute } from './render-route.ts';
+import { isDebug, isDevMode, setDebugFromConfig } from '../debug.ts';
+import { setSourceMapCallback } from '../dev-source-map.ts';
+import { requestContextAls } from '../als-registry.ts';
+import { capturePrebuiltPayloads } from '../prebuilt-builder.ts';
+import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.ts';
+import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.ts';
+import { setKeyDisciplineStrict } from '../prebuilt/key-discipline.ts';
+import { createAutoSitemapHandler } from '../sitemap-handler.ts';
+import { generateStaticSite } from '../static-generator.ts';
 
 /**
  * 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.
+ * Otherwise default to `'total'`.
  */
 function resolveServerTimingMode(
   config: Record<string, unknown>,
-  isDev: boolean
+  _isDev: boolean
 ): 'detailed' | 'total' | false {
   const userValue = config.serverTiming as 'detailed' | 'total' | false | undefined;
   if (userValue !== undefined) return userValue;
-  return isDev ? 'detailed' : 'total';
+  return '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 pipeline
- * errors into the Vite browser error overlay. No-op in production.
+ * 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 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.ts');
+    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.ts');
+    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.ts');
+    const { setCdnPurgeHandler } = await import('../../cdn/purge-store.ts');
+    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.ts').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.ts');
+  setRscFunctions({
+    createFromReadableStream: rscMod.createFromReadableStream,
+    renderToReadableStream: rscMod.renderToReadableStream,
+  });
+
   const matchRoute = createRouteMatcher(manifest);
   const matchMetadataRoute = createMetadataRouteMatcher(manifest);
 
@@ -131,9 +197,12 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     | { disabled: boolean; enableHMRInDev: boolean }
     | undefined;
   const clientJsDisabled = clientJsConfig?.disabled ?? false;
+  const clientSegmentCache =
+    ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false;
   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 +213,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.ts').SensitiveFieldsOption }
+    | undefined;
+  if (formsConfig) {
+    const { setGlobalSensitiveFieldsConfig } = await import('../sensitive-fields.ts');
+    setGlobalSensitiveFieldsConfig(formsConfig.stripSensitiveFields);
+  }
+
   // Two separate flags for two different security levels:
   //
   // isDev (isDevMode) — gates client-visible behavior: dev error pages with
@@ -167,15 +248,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.ts');
       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 +271,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,33 +292,139 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         req,
         match,
         responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
+        {
+          clientBootstrap,
+          clientJsDisabled,
+          clientSegmentCache,
+          rootSegment: manifest.root,
+          buildManifest: typedBuildManifest,
+          globalError: manifest.globalError,
+          devDebugRegistry: pipelineConfig.devDebugRegistry,
+        },
         interception
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
-      return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
+      // In dev mode, when the app authored no 404 page, substitute a helpful
+      // page listing available routes and suggesting similar paths in place
+      // of the framework default. Only for GET requests that accept HTML —
+      // HEAD/API/RSC clients must not receive an HTML body (TIM-793).
+      //
+      // This is passed *into* the chain rather than applied to its result:
+      // the old version detected "no user-defined 404.tsx" by testing the
+      // response for an empty body, which stopped being true once the chain
+      // grew a real terminal (TIM-1258).
+      const acceptsHtml = (req.headers.get('accept') ?? '').includes('text/html');
+      const wantsDev404 = isDev && req.method === 'GET' && acceptsHtml;
+
+      // The dev page is loaded up front: the chain's terminal is synchronous,
+      // and dev-tools must stay out of the production bundle (dynamic import).
+      const devPage = wantsDev404
+        ? await import('../../dev-tools/404-page.ts').catch(() => null)
+        : null;
+
+      const defaultPage = devPage
+        ? (_status: number, headers: Headers) => {
+            const routes = devPage.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 = devPage.generateDev404Page(pathname, routes, pipelineConfig.devHmrOptions);
+            return new Response(html, {
+              status: 404,
+              headers: {
+                ...Object.fromEntries(headers.entries()),
+                'content-type': 'text/html; charset=utf-8',
+              },
+            });
+          }
+        : undefined;
+
+      return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap, defaultPage);
     },
     interceptionRewrites: manifest.interceptionRewrites,
+    matchInterceptedRoute: createInterceptedRouteMatcher(manifest.root),
     // 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,
     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
+      ),
+    // Deny fallback — renders the deny page (403.tsx, 404.tsx, etc.) for
+    // DenySignals that escape from middleware or the render phase.
+    // See deny-fallback.ts, design/04-authorization.md, design/10-error-handling.md.
+    renderDenyFallback: createDenyFallbackRenderer({
+      rootSegment: manifest.root,
+      clientBootstrap,
+    }),
+    // 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),
+
+    // Server action dispatch — runs after proxy.ts, before route matching
+    // (TIM-1213). Moved into the pipeline so proxy.ts runs on action POSTs,
+    // matching the design doc: "proxy.ts runs on every request, no exclusions."
+    // Per-segment `middleware.ts` does NOT run on action POSTs (TIM-1134).
+    dispatchAction: buildActionDispatcher({
+      csrfConfig: {
+        csrf: runtimeConfig.csrf,
+        allowedOrigins: (runtimeConfig as Record<string, unknown>).allowedOrigins as
+          | string[]
+          | undefined,
+      },
+      bodyLimits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
+      sensitiveFields: formsConfig?.stripSensitiveFields,
+      matchRoute,
+      buildRevalidateRenderer: createRevalidateRendererFactory({
+        matchRoute,
+        coerceSegmentParams,
+        buildManifest: buildManifest as BuildManifest,
+      }),
+    }),
   };
 
   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.
+  // CSRF validation lives in the wrapper (not inside the pipeline) so it
+  // runs before proxy.ts and covers every unsafe-method request. Server
+  // action dispatch has moved into the pipeline (TIM-1213) so proxy.ts
+  // runs on action POSTs. See LOCAL-773.
   const csrfConfig = {
     csrf: runtimeConfig.csrf,
     allowedOrigins: (runtimeConfig as Record<string, unknown>).allowedOrigins as
@@ -242,268 +432,118 @@ 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);
-  };
-}
+  const handler = wrapPipelineWithActionDispatch(pipeline, {
+    csrfConfig,
+  });
 
-/**
- * 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);
-  }
+  return { handler, pipelineConfig };
+}
 
-  // 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;
-  }
+// 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.ts';
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
-    routeResult;
+// 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.ts';
 
-  // 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);
-  }
+// 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.ts';
 
-  // 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 the Cloudflare adapter's generated _worker.js to strip the
+// body from edge-cache hits on HEAD requests (TIM-1325). RFC 9110 §9.3.2.
+export { stripHeadBody } from '../head-response.ts';
 
-  const fontEntries = collectRouteFonts(segments, typedManifest);
-  if (fontEntries.length > 0) {
-    headHtml += buildFontPreloadTags(fontEntries);
-  }
+/**
+ * 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.ts').CaptureOptions
+): Promise<import('../prebuilt-builder.ts').CaptureSummary> {
+  return capturePrebuiltPayloads(routeManifest, options);
+}
 
-  // 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);
-    }
+/**
+ * Post-build static site generation entry point (TIM-1238). Renders every
+ * route in the manifest to HTML + RSC flight payloads. Must run inside the
+ * built RSC bundle — the handler, route manifest, and page module loaders
+ * are module instances in THIS bundle's graph.
+ *
+ * Unlike capture mode, this needs the full pipeline handler, so it must
+ * NOT run when __TIMBER_CAPTURE_MODE__ is set.
+ *
+ * See design/11-platform.md §"static output mode".
+ */
+export function __timber_generateStaticSite(
+  options: import('../static-generator.ts').StaticGenerationOptions
+): Promise<import('../static-generator.ts').StaticGenerationSummary> {
+  if (!_handler) {
+    throw new Error(
+      '[timber] __timber_generateStaticSite requires the full request handler. ' +
+        'Do not call in capture mode (__TIMBER_CAPTURE_MODE__).'
+    );
   }
+  return generateStaticSite(routeManifest, _handler, options);
+}
 
-  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}>`;
-    }
-  }
+// 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.ts');
+  setDefaultSingleflightTimeout(renderTimeoutMs);
+  setComponentRefreshTimeout(renderTimeoutMs);
+}
 
-  // Render to RSC Flight stream with signal tracking.
-  const { rscStream, signals } = renderRscStream(element, _req);
+const cacheConfig = (config as Record<string, unknown>).cache as
+  | { strictKeyDiscipline?: boolean }
+  | undefined;
+if (cacheConfig?.strictKeyDiscipline === true) {
+  setKeyDisciplineStrict(true);
+}
 
-  // 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.ts');
+  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!;