@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

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

@@ -1,18 +1,31 @@
 /**
  * SSR Bridge — loads the SSR entry and passes the RSC stream for HTML rendering.
+ *
+ * This is the RSC → SSR environment hop. The two environments are separate
+ * Vite module graphs; `NavContext` is the serializable contract that crosses
+ * the boundary. See `../ssr-bridge-types.ts` for the contract definition.
  */
 
 /// <reference types="@vitejs/plugin-rsc/types" />
 
-import type { NavContext } from '#/server/ssr-entry.js';
+import type { NavContext, SsrRenderResult } from '../ssr-bridge-types.ts';
 
 export async function callSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
-): Promise<Response> {
-  const ssrEntry = await import.meta.viteRsc.import<typeof import('#/server/ssr-entry.js')>(
-    '../ssr-entry.js',
-    { environment: 'ssr' }
-  );
+): Promise<SsrRenderResult> {
+  let ssrEntry: typeof import('../ssr-entry.ts');
+  try {
+    ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.ts')>(
+      '../ssr-entry.js',
+      { environment: 'ssr' }
+    );
+  } catch (error) {
+    const original = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[timber] Failed to load SSR entry from RSC environment.\n  ${original}\n  This usually means a module evaluation error in the SSR bundle.`,
+      { cause: error }
+    );
+  }
   return ssrEntry.handleSsr(rscStream, navContext);
 }

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

@@ -12,25 +12,79 @@
  *              05-streaming.md §"deferSuspenseFor and the Hold Window"
  */
 
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPage } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import { SsrStreamError } from '#/server/primitives.js';
-import type { LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { NavContext } from '#/server/ssr-entry.js';
-
-import {
-  buildRedirectResponse,
-  buildSegmentInfo,
-  createDebugChannelSink,
-  isAbortError,
-  parseCookiesFromHeader,
-} from './helpers.js';
-import { renderErrorPage } from './error-renderer.js';
-import { callSsr } from './ssr-bridge.js';
-import type { RenderSignals } from './rsc-stream.js';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { flightInitScript } from '../flight-scripts.ts';
+import { getCspNonce } from '../csp-nonce.ts';
+import { nonceAttr } from '../render-utils.ts';
+import { appVisibleSearch } from '../../shared/rsc-cache-key.ts';
+import type { LayoutEntry } from '../deny-renderer.ts';
+import type { RouteMatch } from '../pipeline.ts';
+import { isSsrStreamError } from '../signal-identity.ts';
+import type { LayoutComponentEntry } from '../route-element-builder.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import type { SlotSkipEntry } from '../slot-resolver.ts';
+import type { NavContext, SsrRenderResult } from '../ssr-bridge-types.ts';
+
+import { htmlEscapeJsonString } from '../flight-scripts.ts';
+import { buildSegmentInfo, isAbortError } from './helpers.ts';
+import { getCookiesForSsr } from '../cookie-context.ts';
+import { getDenyStatus, getFirstDeniedSegmentIndex } from '../deny-boundary.ts';
+import { renderErrorPage, type GlobalErrorFile } from './error-renderer.ts';
+import { callSsr } from './ssr-bridge.ts';
+import type { RenderSignals } from './render-signals.ts';
+import type { DenySignal, RedirectSignal } from '../primitives.ts';
+import { recordTiming } from '../server-timing.ts';
+import { teeWithErrorPropagation } from '../stream-utils.ts';
+import { addSpanEventSync } from '../tracing.ts';
+import { isDevMode } from '../debug.ts';
+import { swallow } from '../logger.ts';
+
+/**
+ * Maximum number of queueMicrotask yields during signal promotion.
+ * The known rejection chain depth for a withSpan-wrapped component is 3+
+ * microtasks. We use 5 to tolerate additional async wrappers or React
+ * Flight internals adding extra microtask hops. Do not increase beyond 8 —
+ * a deeper chain indicates a structural problem.
+ */
+const SIGNAL_PROMOTION_MAX_YIELDS = 5;
+
+/**
+ * Number of additional microtask yields used by the cap-reached detection
+ * phase (TIM-970). After the promotion loop burns its full cap without
+ * capturing a signal, we yield a few more times to distinguish "no signal
+ * was ever coming" (state 2) from "signal arrived one microtask past the
+ * cap" (state 3 — the silent-miss path). These yields are telemetry-only:
+ * if a late signal is observed it triggers a warn/span-event but is NOT
+ * promoted, because raising the effective promotion cap is deferred to
+ * the E.2 investigation. Without this phase, every default `deferSuspenseFor=0`
+ * render would emit a cap-reached warning even though nothing was missed.
+ */
+const SIGNAL_PROMOTION_DETECTION_EXTRA_YIELDS = 3;
+
+/**
+ * Test-only observable: records how many microtask yields were consumed
+ * during the last signal promotion check. Import this in tests to assert
+ * the actual rejection chain depth and detect regressions if wrappers
+ * add more async hops.
+ *
+ * Only populated when the object is imported and exists — production
+ * bundles that don't import it pay zero cost (the typeof check is free).
+ */
+export const __test_only_signalPromotionDepth: { value: number } = { value: 0 };
+
+/**
+ * Test-only observable: true when the promotion loop hit the cap without
+ * capturing a signal (the silent-miss path — state 3 in TIM-970). False
+ * when the loop captured a signal at any depth, when it was skipped via
+ * `fizzAllReadyResolved`, or when no signal was ever expected at a depth
+ * shallower than the cap.
+ *
+ * Pairs with `__test_only_signalPromotionDepth`: depth alone cannot
+ * distinguish "cap hit with signal captured on yield 5" from "cap hit with
+ * signal arriving on yield 6+" — both read `.value === 5`. This flag closes
+ * that gap. See TIM-970, design/05-streaming.md §"Signal Promotion".
+ */
+export const __test_only_signalPromotionCapHit: { value: boolean } = { value: false };
 
 interface SsrRenderOptions {
   req: Request;
@@ -44,6 +98,9 @@ interface SsrRenderOptions {
   clientJsDisabled: boolean;
   headHtml: string;
   deferSuspenseFor: number;
+  /** Tier 2 global-error.tsx file, if present in app/. */
+  globalError?: GlobalErrorFile;
+  slotSkipInfo?: SlotSkipEntry[];
 }
 
 /**
@@ -56,13 +113,18 @@ interface SsrRenderOptions {
  * SSR will attempt to render the element tree progressively. Two outcomes:
  *
  * 1. deny() outside Suspense: the error appears in the RSC shell. SSR's
- *    renderToReadableStream fails (rejects). We catch the failure, check
- *    denySignal, and render the deny page with the correct status code.
+ *    renderToReadableStream fails (rejects). We catch the failure, find
+ *    the captured denySignal, and rethrow it to the pipeline.
  *
  * 2. deny() inside Suspense: the SSR shell succeeds (200 committed). The
  *    error streams into the connection as a React error boundary. The
  *    status is already committed — per design/05-streaming.md this is the
  *    expected degraded behavior for deny inside Suspense.
+ *
+ * @throws the captured `DenySignal` or `RedirectSignal` when one decides the
+ *   response. `runRenderPhase()` turns it into a `deny` / `redirect` outcome,
+ *   and the pipeline renders the deny page or builds the redirect, exactly as
+ *   for a signal thrown out of render (design/49 §"C").
  */
 export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Response> {
   const {
@@ -77,157 +139,258 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     clientJsDisabled,
     headHtml,
     deferSuspenseFor,
+    globalError,
   } = opts;
 
   // Tee the RSC stream — one copy goes to SSR for HTML rendering,
   // the other is inlined in the HTML for client-side hydration.
-  const [ssrStream, inlineStream] = rscStream.tee();
-
-  // Embed segment metadata in HTML for initial hydration.
-  // The client reads this to populate its segment cache before the
-  // first navigation, enabling state tree diffing from the start.
-  // Skipped when client JS is disabled — no client JS to consume it.
-  const segmentScript = clientJsDisabled
-    ? ''
-    : `<script>self.__timber_segments=${JSON.stringify(buildSegmentInfo(segments, layoutComponents))}</script>`;
-
-  // Embed route params in HTML so useParams() works on initial hydration.
-  // Without this, useParams() returns {} until the first client navigation.
-  const paramsScript =
-    clientJsDisabled || Object.keys(match.params).length === 0
-      ? ''
-      : `<script>self.__timber_params=${JSON.stringify(match.params)}</script>`;
+  // Uses teeWithErrorPropagation to ensure errors on either branch
+  // cancel the other (preventing hung responses) and to monitor
+  // buffer divergence between SSR and inline consumers.
+  //
+  // When client JS is disabled, skip the tee — the inline stream would
+  // never be consumed, causing monotonic buffer divergence that eventually
+  // triggers the 5MB guard and cancels the SSR stream.
+  let ssrStream: ReadableStream<Uint8Array>;
+  let inlineStream: ReadableStream<Uint8Array> | undefined;
+  if (clientJsDisabled) {
+    ssrStream = rscStream;
+    inlineStream = undefined;
+  } else {
+    [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
+  }
+
+  // Segment metadata for initial hydration: deferred to shell-flush time.
+  // The SSR entry invokes this thunk AFTER renderSsrNodeStream /
+  // renderSsrStream returns (shell ready ⇒ AccessGates settled), so
+  // getFirstDeniedSegmentIndex() returns the authoritative ALS value
+  // rather than the pre-render Infinity. See TIM-1365, TIM-1359.
 
+  // Middleware has already run; if it read `ctx.nonce` for its CSP header,
+  // that is the value every inline script must wear.
+  const nonce = getCspNonce();
+
+  const reqUrl = new URL(req.url);
   const navContext: NavContext = {
-    pathname: new URL(req.url).pathname,
-    params: match.params,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    pathname: reqUrl.pathname,
+    search: appVisibleSearch(reqUrl).search,
     statusCode: 200,
     responseHeaders,
-    headHtml: headHtml + clientBootstrap.preloadLinks + segmentScript + paramsScript,
+    headHtml:
+      headHtml +
+      clientBootstrap.preloadLinks +
+      // Initialize __timber_f in <head> so it exists before any streaming
+      // chunk scripts arrive in <body>. See flight-scripts.ts, LOCAL-415.
+      (clientJsDisabled ? '' : flightInitScript(nonce)),
+    getHeadSegmentScript: clientJsDisabled
+      ? undefined
+      : () =>
+          `<script${nonceAttr(nonce)}>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents, opts.slotSkipInfo, undefined, getFirstDeniedSegmentIndex())))}</script>`,
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    nonce,
     // Skip RSC inline stream when client JS is disabled — no client to hydrate.
     rscStream: clientJsDisabled ? undefined : inlineStream,
     deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
     signal: req.signal,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
+    // Stops the Flight injector writing <script> tags once an unhandled RSC
+    // error is captured. Without this, React's Flight encoder may write model
+    // data for a chunk that already received an error row, causing the
+    // client's Flight decoder to crash with "enqueueModel is not a
+    // function". See TIM-938.
+    _errorSignal: signals.unhandledError,
   };
 
-  // Helper: check if render-phase signals were captured and return the
-  // appropriate HTTP response. Used after both successful SSR (signal
-  // promotion from Suspense) and failed SSR (signal outside Suspense).
+  // The signal a render captured, if any. Used after both successful SSR
+  // (signal promotion from Suspense) and failed SSR (signal outside Suspense).
+  // A captured deny or redirect is reported, not rendered: callers cancel the
+  // streams this render holds and rethrow it, and runRenderPhase() turns it
+  // into the same `deny` / `redirect` outcome a thrown signal becomes, so
+  // the pipeline's deny fallback and redirect builder answer it (design/49
+  // §"C"). Redirect wins over deny, as it always has.
   //
-  // When `skipHandledDeny` is true (SSR success path), skip DenySignal
-  // promotion if the denial was already handled by a TimberErrorBoundary
-  // (e.g., slot error boundary). The boundary sets navContext._denyHandledByBoundary
-  // during SSR rendering. See LOCAL-298.
-  function checkCapturedSignals(skipHandledDeny = false): Response | Promise<Response> | null {
-    if (signals.redirectSignal) {
-      return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
-    }
-    if (signals.denySignal && !(skipHandledDeny && navContext._denyHandledByBoundary)) {
-      return renderDenyPage(
-        signals.denySignal,
-        segments,
-        layoutComponents as LayoutEntry[],
-        req,
-        match,
-        responseHeaders,
-        clientBootstrap,
-        createDebugChannelSink,
-        callSsr
-      );
+  // A signal the detection phase below saw arrive past the promotion cap is
+  // discarded rather than promoted; this flag records that without writing
+  // into the producer's signals.
+  let detectionConfirmedLateSignal = false;
+  function capturedSignal(): RedirectSignal | DenySignal | null {
+    if (detectionConfirmedLateSignal) return null;
+    return signals.redirectSignal ?? signals.denySignal;
+  }
+
+  // Only the SSR call is guarded: everything after it runs on a document
+  // SSR produced, and a captured signal rethrown there must reach
+  // runRenderPhase() rather than this renderer's own failure handling.
+  let ssr: SsrRenderResult;
+  try {
+    ssr = await callSsr(ssrStream, navContext);
+  } catch (ssrError) {
+    // SSR failed, so nothing will read the teed inline stream: every answer
+    // below renders its own streams or none. Without explicit cancellation
+    // the orphaned tee branch keeps the RSC source stream alive, preventing
+    // garbage collection — so release it before anything returns or throws.
+    inlineStream
+      ?.cancel()
+      .catch((err: unknown) => swallow(err, 'orphaned RSC inline stream did not cancel'));
+
+    // Connection abort — the client disconnected (page refresh, navigation
+    // away). No response needed; return empty 499 (client closed request).
+    if (isAbortError(ssrError) || req.signal?.aborted) {
+      return new Response(null, { status: 499 });
     }
-    if (signals.renderError) {
+
+    // A captured signal explains the failure, whichever shape it took: the
+    // signal was in the shell, outside any Suspense boundary.
+    const signal = capturedSignal();
+    if (signal) throw signal;
+
+    // SsrStreamError with no captured signal: SSR's renderToReadableStream
+    // failed because the RSC stream contained an uncontained error (e.g., a
+    // slot without an error boundary).
+    //
+    // SsrStreamError is thrown in the SSR environment but caught here in
+    // RSC — separate Vite module graphs, so `instanceof` can never match.
+    // isSsrStreamError() checks the Symbol.for brand instead. See
+    // design/18-build-system.md §"Dev Mode: Signal Identity Across Program Reloads".
+    if (isSsrStreamError(ssrError)) {
+      // The cause is the error Flight relayed for the row that failed the
+      // shell — not the last error the RSC render reported, which may be one
+      // a Suspense boundary contained (TIM-1552).
       return renderErrorPage(
-        signals.renderError.error,
-        signals.renderError.status,
+        ssrError.cause ?? ssrError,
+        500,
         segments,
         layoutComponents as LayoutEntry[],
         req,
         match,
         responseHeaders,
-        clientBootstrap
+        clientBootstrap,
+        globalError,
+        getFirstDeniedSegmentIndex()
       );
     }
-    return null;
+
+    // No tracked error — rethrow (infrastructure failure)
+    throw ssrError;
   }
 
-  try {
-    const ssrResponse = await callSsr(ssrStream, navContext);
+  const { response: ssrResponse, timings: t, fizzAllReadyResolved } = ssr;
 
-    // Signal promotion: check if any signals were captured during rendering
-    // inside Suspense boundaries. If no signals are present yet, yield one
-    // microtask so async component rejections propagate to the RSC onError
-    // callback before we commit the response.
-    //
-    // When signals are already captured (onSignal already fired), skip the
-    // yield entirely — react immediately. Uses queueMicrotask instead of
-    // setTimeout(0) for the fallback to avoid yielding to the full event
-    // loop (timers phase).
-    // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
-    if (!signals.redirectSignal && !signals.denySignal && !signals.renderError) {
-      await new Promise<void>((r) => queueMicrotask(r));
-    }
+  // Record SSR sub-phase timings for the Server-Timing header. recordTiming
+  // is a no-op outside a detailed-mode timing collector.
+  recordTiming({ name: 'ssr-decode', dur: t.decodeMs, desc: 'RSC Flight decode' });
+  recordTiming({ name: 'ssr-shell', dur: t.shellMs, desc: 'Fizz onShellReady' });
+  recordTiming({ name: 'ssr-pipeline', dur: t.pipelineMs, desc: 'stream transforms' });
+  recordTiming({
+    name: 'ssr-total',
+    dur: t.totalMs,
+    desc: t.nodeStreams ? 'SSR (Node streams)' : 'SSR (Web Streams)',
+  });
 
-    const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
-    if (promoted) {
-      ssrResponse.body?.cancel();
-      return promoted;
-    }
-    return ssrResponse;
-  } catch (ssrError) {
-    // Connection abort — the client disconnected (page refresh, navigation
-    // away). No response needed; return empty 499 (client closed request).
-    if (isAbortError(ssrError) || req.signal?.aborted) {
-      return new Response(null, { status: 499 });
-    }
-
-    // SsrStreamError: SSR's renderToReadableStream failed because the RSC
-    // stream contained an uncontained error (e.g., slot without error boundary).
-    // Render the deny/error page WITHOUT layout wrapping to avoid re-executing
-    // server components (which call headers()/cookies() and fail in SSR's
-    // separate ALS scope). See LOCAL-293.
-    if (ssrError instanceof SsrStreamError) {
-      if (signals.redirectSignal) {
-        return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+  // Signal promotion: check if any signals were captured during rendering
+  // inside Suspense boundaries. If no signals are present yet, we may
+  // need to yield microtasks so async component rejections propagate
+  // through the full rejection chain to the RSC onError callback before
+  // we commit the response.
+  //
+  // Option 1 short-circuit: when Fizz's `stream.allReady` settled before
+  // the `deferSuspenseFor` hold ended (`fizzAllReadyResolved`),
+  // Flight has closed its stream, every `onError` already fired, and the
+  // signals object is fully populated. The retry loop would be a no-op.
+  // See design/spike-signal-promotion-protocol.md §"Option 1".
+  //
+  // Fallback path (hold timed out, no hold window, or shell-only return):
+  // the known rejection chain depth for a withSpan-wrapped page is 3+
+  // microtasks —
+  //   1. PageComponent throws DenySignal/RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  // so a bounded retry loop (max 5) is required to catch signals whose
+  // propagation is still in-flight when callSsr returns. The loop exits
+  // early as soon as a signal is detected. Uses queueMicrotask instead
+  // of setTimeout(0) to avoid yielding to the full event loop.
+  // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
+  if (!capturedSignal()) {
+    let yieldsConsumed = 0;
+    if (!fizzAllReadyResolved) {
+      // Promotion phase: bounded cap of SIGNAL_PROMOTION_MAX_YIELDS.
+      // A signal captured here is rethrown below and becomes the
+      // response (redirect or deny page).
+      for (let i = 0; i < SIGNAL_PROMOTION_MAX_YIELDS; i++) {
+        await new Promise<void>((r) => queueMicrotask(r));
+        yieldsConsumed++;
+        if (capturedSignal()) break;
       }
-      if (signals.denySignal) {
-        // Render deny page without layouts — pass empty layout list
-        return renderDenyPage(
-          signals.denySignal,
-          segments,
-          [] as LayoutEntry[],
-          req,
-          match,
-          responseHeaders,
-          clientBootstrap,
-          createDebugChannelSink,
-          callSsr
-        );
+
+      // Detection phase (TIM-970): if the promotion cap was hit without
+      // capturing a signal, yield a few more times to disambiguate state 2
+      // ("no signal was ever coming" — the common legitimate-200 case) from
+      // state 3 ("signal arrived one microtask past the cap" — the silent
+      // miss). Telemetry-only: if a late signal is observed it triggers
+      // the warning and span event but is NOT promoted. Promoting it would
+      // effectively raise the cap to MAX_YIELDS + DETECTION_EXTRA_YIELDS,
+      // which the ticket defers to the E.2 investigation. Setting
+      // detectionConfirmedLateSignal keeps capturedSignal() from picking
+      // them up.
+      //
+      // The signal is discarded, but a late deny's status still applies: an
+      // in-tree catch site that hoisted it recorded the status before
+      // rethrowing (handleCaughtDeny), so the getDenyStatus() override below
+      // serves this document with the deny's 4xx. A late deny that no status
+      // file matched recorded nothing and stays a 200, as does any deny that
+      // lands after this window — the override is read once, below.
+      if (yieldsConsumed === SIGNAL_PROMOTION_MAX_YIELDS && !capturedSignal()) {
+        for (let i = 0; i < SIGNAL_PROMOTION_DETECTION_EXTRA_YIELDS; i++) {
+          await new Promise<void>((r) => queueMicrotask(r));
+          if (capturedSignal()) {
+            detectionConfirmedLateSignal = true;
+            break;
+          }
+        }
       }
-      if (signals.renderError) {
-        return renderErrorPage(
-          signals.renderError.error,
-          signals.renderError.status,
-          segments,
-          [] as LayoutEntry[],
-          req,
-          match,
-          responseHeaders,
-          clientBootstrap
+    }
+    __test_only_signalPromotionDepth.value = yieldsConsumed;
+    __test_only_signalPromotionCapHit.value = detectionConfirmedLateSignal;
+
+    if (detectionConfirmedLateSignal) {
+      if (isDevMode()) {
+        console.warn(
+          `[timber] Signal promotion cap reached (${SIGNAL_PROMOTION_MAX_YIELDS} microtask yields) — a deny()/redirect() signal arrived just past the cap and was discarded. ` +
+            `Likely cause: a page using deny()/redirect() inside a deeply-wrapped async component (custom withSpan, decorators, etc.). ` +
+            `Simplify the async chain or reduce withSpan/wrapper depth. ` +
+            `See design/05-streaming.md §"Signal Promotion".`
         );
       }
-      // No captured signal — return bare 500
-      return new Response(null, { status: 500, headers: responseHeaders });
+      addSpanEventSync('timber.ssr.signal_promotion_cap_reached', {
+        depth: SIGNAL_PROMOTION_MAX_YIELDS,
+        signal_types_checked: 'redirect,deny',
+      });
     }
+  }
 
-    // SSR shell rendering failed — the error was outside Suspense.
-    // Check captured signals (redirect, deny, render error).
-    const signalResponse = checkCapturedSignals();
-    if (signalResponse) return signalResponse;
+  // A captured signal replaces this document, so its body is never read.
+  const promoted = capturedSignal();
+  if (promoted) {
+    ssrResponse.body
+      ?.cancel()
+      .catch((err: unknown) => swallow(err, 'discarded SSR document body did not cancel'));
+    throw promoted;
+  }
 
-    // No tracked error — rethrow (infrastructure failure)
-    throw ssrError;
+  // Check if a DenySignal was caught in-tree by AccessGate or
+  // PageDenyBoundary. The deny page was rendered as a normal element
+  // (no error in the Flight stream), so SSR succeeded with status 200.
+  // Override the status code from the ALS-stored deny status. See TIM-666.
+  // A hoisted deny whose signal arrived past the promotion cap lands here
+  // too, with the status its catch site recorded (see the detection phase).
+  const denyStatus = getDenyStatus();
+  if (denyStatus) {
+    return new Response(ssrResponse.body, {
+      status: denyStatus,
+      headers: ssrResponse.headers,
+    });
   }
+
+  return ssrResponse;
 }

package/src/server/rsc-error-envelope.ts

@@ -0,0 +1,18 @@
+import { TIMBER_ERROR_HEADER } from '../shared/rsc-error-envelope.ts';
+import { errorResponseHeaders } from './error-response-headers.ts';
+
+/**
+ * Build the hard-navigate envelope for a status code.
+ *
+ * Preserve middleware's request-wide headers and cookies, but discard the
+ * abandoned body's framing, validators, and cache policy. Every producer,
+ * including errors returned normally during render, gets this cleanup here.
+ * The input header bag is left intact. The body deliberately carries no message —
+ * only the status already on the wire (design/13-security.md principle 4).
+ */
+export function rscErrorEnvelope(status: number, responseHeaders?: Headers): Response {
+  const headers = errorResponseHeaders(responseHeaders);
+  headers.set(TIMBER_ERROR_HEADER, '1');
+  headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status }), { status, headers });
+}

package/src/server/rsc-prop-warnings.ts

@@ -16,7 +16,7 @@
  * Task: TIM-358
  */
 
-import { isDebug } from './debug.js';
+import { isDebug } from './debug.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 

package/src/server/safe-load.ts

@@ -0,0 +1,53 @@
+/**
+ * loadModule — enriched error context for route manifest .load() failures.
+ *
+ * Wraps the lazy `load()` functions from the route manifest with a
+ * try/catch that re-throws with the file path and original cause.
+ *
+ * Loads the render can do without (status, error and fallback pages) go
+ * through `loadFallbackModule()` in pipeline-helpers.ts instead, which logs
+ * and reports the failure and resolves to `null` — never a bare
+ * `.catch(() => null)`, which skips a broken page silently (TIM-1458).
+ *
+ * See design/spike-TIM-551-dynamic-import-audit.md §"Proposed Wrapping Strategy"
+ */
+
+/** A manifest file reference with a lazy import function and file path. */
+export interface ManifestLoader {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
+
+/**
+ * Custom error class for module load failures.
+ *
+ * Preserves the original error as `cause` while providing a
+ * human-readable message with the file path.
+ */
+export class ModuleLoadError extends Error {
+  /** The file path that failed to load. */
+  readonly filePath: string;
+
+  constructor(filePath: string, cause: unknown) {
+    const originalMessage = cause instanceof Error ? cause.message : String(cause);
+    super(`[timber] Failed to load module ${filePath}\n  ${originalMessage}`, { cause });
+    this.name = 'ModuleLoadError';
+    this.filePath = filePath;
+  }
+}
+
+/**
+ * Load a route manifest module with enriched error context.
+ *
+ * On success: returns the module object (same as `loader.load()`).
+ * On failure: throws `ModuleLoadError` with file path and original cause.
+ *
+ * Error rendering paths that need fallthrough use `loadFallbackModule()`.
+ */
+export async function loadModule<T = Record<string, unknown>>(loader: ManifestLoader): Promise<T> {
+  try {
+    return (await loader.load()) as T;
+  } catch (error) {
+    throw new ModuleLoadError(loader.filePath, error);
+  }
+}