@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

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

@@ -5,25 +5,32 @@
  * returned directly without SSR HTML rendering. The client decodes it via
  * `createFromFetch` and renders into the hydrated React root.
  *
- * Design docs: 19-client-navigation.md §"RSC Payload Handling",
- *              16-metadata.md §"Head Elements"
+ * Design docs: 19-client-navigation.md §"RSC Payload Handling"
  */
 
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { RedirectSignal } from '#/server/primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-
-import {
-  buildRedirectResponse,
-  buildSegmentInfo,
-  createDebugChannelSink,
-  RSC_CONTENT_TYPE,
-} from './helpers.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { RedirectSignal } from '../primitives.js';
+import type { LayoutComponentEntry } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { SlotSkipEntry } from '../slot-resolver.js';
+
+import { buildRedirectResponse, buildSegmentInfo, createDebugChannelSink } from './helpers.js';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.js';
+
+import { rscErrorEnvelope } from '../../shared/rsc-error-envelope.js';
+
 import type { RenderSignals } from './rsc-stream.js';
 
+/**
+ * Ceiling on waiting for a first chunk that is already in flight, used only
+ * when an addressed deny won the race against it. Matches the 50ms ceiling
+ * documented for the race itself: long enough that the error row — which is
+ * what the render just produced — arrives, short enough that a stalled stream
+ * cannot hold the response open.
+ */
+const FIRST_CHUNK_CEILING_MS = 50;
+
 /**
  * Build an RSC payload Response for a client-side navigation request.
  *
@@ -39,10 +46,9 @@ export async function buildRscPayloadResponse(
   signals: RenderSignals,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutComponentEntry[],
-  headElements: HeadElement[],
-  match: RouteMatch,
   responseHeaders: Headers,
-  skippedSegments?: string[]
+  skippedSegments?: string[],
+  slotSkipInfo?: SlotSkipEntry[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
   // Race the first read against signal detection — if an async component
@@ -69,17 +75,52 @@ export async function buildRscPayloadResponse(
     | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
     | { type: 'signal' };
 
-  const first: RaceResult = await Promise.race([
-    reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
-    signalDetected.then(() => ({ type: 'signal' as const })),
-  ]);
+  // Retained rather than inlined into the race below. When a signal wins, the
+  // usual answer is to cancel — but an ADDRESSED deny is one whose error row
+  // the client's boundary is going to render, so that payload has to survive
+  // (TIM-1356). Taking delivery of the read already in flight is not the
+  // "bare read() after a signal won" the async rules forbid; issuing a second
+  // one would be. It still gets a ceiling below.
+  const pendingRead = reader.read();
+
+  let first: RaceResult;
+  try {
+    first = await Promise.race([
+      pendingRead.then((chunk) => ({ type: 'data' as const, chunk })),
+      signalDetected.then(() => ({ type: 'signal' as const })),
+    ]);
+  } catch (_readError) {
+    // RSC stream failed on first read — unhandled error in the page component.
+    // Return an error response so the client can hard-navigate for the
+    // SSR-rendered error page. See design/10-error-handling.md.
+    reader.cancel().catch(() => {});
+    signals.onSignal = undefined;
+    return rscErrorEnvelope(500, responseHeaders);
+  }
 
   // If data arrived first, still check signals — they may have fired
-  // concurrently. Also do a final ceiling timeout check for edge cases
-  // where the signal fires just after the first read resolves.
+  // concurrently. Wait for all deny-capable shell components (layouts
+  // with deny chains + page) to settle so async deny() calls preceded
+  // by I/O are captured. See TIM-1045, TIM-1208.
   if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
-    // Brief yield to let any in-flight microtask rejections complete.
-    await new Promise<void>((r) => setTimeout(r, 0));
+    // Sync deny (AccessGate pre-pass replay) sets getDenyStatus() during
+    // renderToReadableStream — before the first chunk is read. Skip the
+    // wait entirely: components below the denied gate never execute.
+    const { getDenyStatus: earlyDenyCheck } = await import('../deny-boundary.js');
+    if (signals.shellSettled && !earlyDenyCheck()) {
+      // Wait for all deny-capable shell components to finish, or for an
+      // in-tree layout deny to short-circuit (setDenyStatus already
+      // called), or for a signal to escape to onError. TIM-1045, TIM-1208.
+      await Promise.race([signals.shellSettled, signalDetected]);
+      // Shell components' finally blocks resolve before React Flight's
+      // onError fires. Yield one macrotask so onError can set
+      // signals.redirectSignal / signals.renderError before we check.
+      await new Promise<void>((r) => setTimeout(r, 0));
+    } else if (!earlyDenyCheck()) {
+      // No deny-capable shell components (client component page, no deny
+      // chain) — brief yield to let in-flight microtask rejections complete.
+      await new Promise<void>((r) => setTimeout(r, 0));
+    }
   }
 
   // Detach the callback — no longer needed after this point.
@@ -88,24 +129,105 @@ export async function buildRscPayloadResponse(
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
   if (trackedRedirect) {
-    reader.cancel();
-    return buildRedirectResponse(req, trackedRedirect, responseHeaders);
+    reader.cancel().catch(() => {});
+    return buildRedirectResponse(trackedRedirect, req, responseHeaders);
   }
-  if (signals.denySignal) {
-    reader.cancel();
+  // An addressed deny needs no fallback: the payload already carries its error
+  // row, aimed at the boundary the client has mounted at that segment, which
+  // renders it. Cancelling would throw a finished render away and re-run the
+  // whole route — the exact cost TIM-666 removed. The status still lands,
+  // because the catch site called setDenyStatus() before re-throwing (read
+  // below via getDenyStatus).
+  //
+  // The question is asked of `unplacedDeny`, not of `denySignal.ownerKey`,
+  // because one render can produce both kinds and `denySignal` holds only one
+  // of them. A deny nothing could place has no boundary that may claim it, so
+  // its row would otherwise stream to a client with nothing to render it —
+  // and it needs the fallback whether or not some other deny was addressed
+  // first. See TIM-1356.
+  if (signals.unplacedDeny) {
+    reader.cancel().catch(() => {});
+
+    // A skipped segment whose access just flipped to deny marks the signal
+    // for hard-navigate: rendering a deny page here would execute the denied
+    // segment's protected layout and place it inside cached client chrome
+    // (TIM-1074). Return rscErrorEnvelope so the client hard-navigates for
+    // a clean full render with correct deny page placement. See TIM-1363.
+    if (signals.unplacedDeny._hardNavigate) {
+      return rscErrorEnvelope(signals.unplacedDeny.status, responseHeaders);
+    }
+
+    // Read the denied segment index from ALS — set by AccessGate during
+    // render. See TIM-1358, TIM-1365.
+    const { getFirstDeniedSegmentIndex: getDeniedIdx } = await import('../deny-boundary.js');
     return renderDenyPageAsRsc(
-      signals.denySignal,
+      signals.unplacedDeny,
       segments,
       layoutComponents as LayoutEntry[],
+      req,
       responseHeaders,
-      createDebugChannelSink
+      createDebugChannelSink,
+      getDeniedIdx()
     );
   }
 
+  // Check for unhandled errors (RenderError or plain Error).
+  // These aren't redirect/deny signals but the RSC stream will be broken.
+  // Return an error response so the client can hard-navigate for the
+  // SSR-rendered error page. See design/10-error-handling.md
+  // §"Error Page Rendering for Client Navigation".
+  if (signals.renderError) {
+    reader.cancel().catch(() => {});
+    return rscErrorEnvelope(signals.renderError.status, responseHeaders);
+  }
+
   // Extract the first chunk from the race result.
-  // If the signal won the race, read the first chunk now (the stream
-  // was already cancelled above, but we need a firstRead shape below).
-  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+  // If the signal won the race but neither redirect nor deny was detected
+  // (edge case), cancel the reader immediately rather than issuing a bare
+  // read() that could hang forever if the RSC stream has stalled.
+  // See TIM-519.
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else if (signals.denySignal?.ownerKey) {
+    // An addressed deny won the race before its own error row surfaced.
+    // Cancelling here would hand the client a 4xx payload with nothing in it
+    // — no row for the owning boundary to render, so the navigation shows
+    // nothing at all. Take delivery of the read already in flight instead,
+    // under a ceiling so a stalled stream still cannot hang the response.
+    const TIMED_OUT = Symbol('first-chunk-timeout');
+    const raced = await Promise.race([
+      pendingRead,
+      new Promise<typeof TIMED_OUT>((resolve) =>
+        setTimeout(() => resolve(TIMED_OUT), FIRST_CHUNK_CEILING_MS)
+      ),
+    ]);
+
+    // Missing the ceiling must not be reported as a finished stream. Under
+    // event-loop contention or slow serialization the row is late rather than
+    // absent, and fabricating `done: true` here would produce the very empty
+    // 4xx this branch exists to prevent.
+    //
+    // Nor can it fall to `renderDenyPageAsRsc`. That renderer re-resolves from
+    // the FULL leaf chain and wraps whatever it finds, ignoring `ownerKey` —
+    // so an `/admin` denial addressed to a root `4xx.tsx` would come back as
+    // `/admin/secret/403.tsx` with the denied layouts executed, which is the
+    // TIM-1074 leak TIM-1358 still owns. A deny this path already placed
+    // correctly must not be handed to it.
+    //
+    // So: hard-navigate. The document request renders the same deny through
+    // the boundary at its owner, with the placement intact. A full page load
+    // is a real cost, on a path that needs a status page and a stalled stream
+    // to reach at all.
+    if (raced === TIMED_OUT) {
+      reader.cancel().catch(() => {});
+      return rscErrorEnvelope(signals.denySignal.status, responseHeaders);
+    }
+    firstRead = raced;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
 
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
@@ -131,22 +253,39 @@ export async function buildRscPayloadResponse(
   });
 
   responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-  // Vary on Accept so CDNs cache HTML and RSC responses separately
-  // for the same URL. The client appends ?_rsc=<id> as a cache-bust,
-  // but Vary ensures correct behavior even without the query param.
-  responseHeaders.set('Vary', 'Accept');
-
-  // Send resolved head elements so the client can update document.title
-  // and <meta> tags after SPA navigation. See design/16-metadata.md.
-  const encoded = encodeURIComponent(JSON.stringify(headElements));
-  if (encoded.length <= 4096) {
-    responseHeaders.set('X-Timber-Head', encoded);
-  }
+
+  // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload as
+  // React elements — React 19 Float manages them in document.head during
+  // client rendering. No X-Timber-Head header needed. See TIM-1151.
 
   // Send segment metadata so the client can populate its segment cache
-  // for state tree diffing on subsequent navigations.
+  // for state tree diffing on subsequent navigations. Request-dependency
+  // is determined by static module-graph analysis (not runtime taint).
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const segmentInfo = buildSegmentInfo(segments, layoutComponents);
+  // Read the deny state before describing the tree — what mounted depends on it.
+  // Both values are recorded in ALS during render by AccessGate's catch path.
+  const { getDenyStatus, getFirstDeniedSegmentIndex } = await import('../deny-boundary.js');
+  const denyStatus = getDenyStatus();
+  const resolvedDenyIndex = getFirstDeniedSegmentIndex();
+
+  // Emitted in full even when a deny rendered, because this header answers two
+  // questions and they diverge here. The client picks its merge point out of
+  // this list (`buildSegmentUpdates`), and a partial payload with no merge
+  // point is never inserted at all — the URL commits over the stale previous
+  // UI. So it has to keep describing the chain the payload was BUILT against.
+  //
+  // What it must not also do on a deny is seed the segment cache, since the
+  // deny page replaced a subtree and part of that chain never mounted. That
+  // half is handled at the commit site from the response status, where the
+  // merge point has already been chosen. See `client/router-pipeline.ts` and
+  // TIM-1356.
+  const segmentInfo = buildSegmentInfo(
+    segments,
+    layoutComponents,
+    slotSkipInfo,
+    skippedSegments,
+    resolvedDenyIndex
+  );
   responseHeaders.set('X-Timber-Segments', JSON.stringify(segmentInfo));
 
   // Send skipped segments so the client can merge the partial RSC payload
@@ -155,14 +294,8 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
-  if (Object.keys(match.params).length > 0) {
-    responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
-  }
-
   return new Response(patchedStream, {
-    status: 200,
+    status: denyStatus ?? 200,
     headers: responseHeaders,
   });
 }

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

@@ -10,14 +10,23 @@
  *              13-security.md §"Errors don't leak"
  */
 
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.js';
+import type { RscPayloadRoot } from '../../shared/payload-root.js';
 
-import { logRenderError } from '#/server/logger.js';
-import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
-import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
+import { randomUUID } from 'node:crypto';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
-import { isDebug } from '#/server/debug.js';
+import { logRenderError } from '../logger.js';
+import { DenySignal, RedirectSignal, RenderError } from '../primitives.js';
+import { checkAndWarnRscPropError } from '../rsc-prop-warnings.js';
+
+import {
+  createDebugChannelSink,
+  createDebugChannelCollector,
+  isAbortError,
+  type DebugComponentEntry,
+} from './helpers.js';
+import { isDebug } from '../debug.js';
+import { isDevMode } from '../debug.js';
 
 /**
  * Mutable signal state captured during RSC rendering.
@@ -31,19 +40,54 @@ import { isDebug } from '#/server/debug.js';
  */
 export interface RenderSignals {
   denySignal: DenySignal | null;
+  /**
+   * The first deny that no in-tree catch site could place — no `ownerKey`, so
+   * no boundary may claim its error row and only the re-render fallback can
+   * produce a page for it.
+   *
+   * Tracked apart from `denySignal` because one render can produce both. A
+   * deep page can hoist a 404 to a boundary that will render it while an
+   * outer layout separately throws a 403 nothing matches; whichever lands in
+   * `denySignal` first, the unplaced one still needs the fallback, and
+   * deciding from `denySignal.ownerKey` alone would strand it. See TIM-1356.
+   */
+  unplacedDeny: DenySignal | null;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /**
+   * The last unhandled error seen by RSC onError that isn't a signal.
+   * Used as a fallback when SSR fails (SsrStreamError) but no structured
+   * signal was captured — provides the original error for the error page
+   * instead of relying on SsrStreamError.cause extraction.
+   *
+   * NOT used for page-level error detection (that would break Suspense
+   * error isolation). Only consumed when SSR actually fails.
+   */
+  lastUnhandledError: unknown | null;
   /** Callback fired when a redirect or deny signal is captured in onError. */
   onSignal?: () => void;
+  /**
+   * Resolves when every deny-capable shell component (PageDenyBoundary +
+   * TracedLayouts with deny chains) has settled, OR immediately when any
+   * catches a DenySignal in-tree (status is known). Set by renderRoute
+   * after element-tree construction. Awaited by buildRscPayloadResponse
+   * before committing HTTP status. See TIM-1045, TIM-1208.
+   */
+  shellSettled?: Promise<void>;
+  /** Callback fired when an unhandled error (non-signal) is captured. Used
+   *  to halt Flight data injection into the inline stream. */
+  onUnhandledError?: () => void;
 }
 
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 
 /**
- * Render a React element tree to an RSC Flight stream.
+ * Render a payload root (tree plus its params) to an RSC Flight stream.
  *
  * The stream serializes server components as rendered output and client
  * components ("use client") as serialized references with module ID + export name.
@@ -53,18 +97,24 @@ export interface RscStreamResult {
  * fires onError during stream consumption. Signals are captured in the
  * returned `signals` object for the caller to handle.
  */
-export function renderRscStream(element: React.ReactElement, req: Request): RscStreamResult {
+export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStreamResult {
   const signals: RenderSignals = {
     denySignal: null,
+    unplacedDeny: null,
     redirectSignal: null,
     renderError: null,
+    lastUnhandledError: null,
   };
 
   let rscStream: ReadableStream<Uint8Array> | undefined;
 
+  // In dev mode, collect debug channel data for the error overlay.
+  // In production, use the discard sink (no overhead).
+  const debugChannel = isDevMode() ? createDebugChannelCollector() : createDebugChannelSink();
+
   try {
     rscStream = renderToReadableStream(
-      element,
+      payload,
       {
         signal: req.signal,
         onError(error: unknown) {
@@ -73,9 +123,18 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           if (isAbortError(error) || req.signal?.aborted) return;
           if (error instanceof DenySignal) {
             signals.denySignal = error;
+            if (!error.ownerKey) signals.unplacedDeny ??= error;
             signals.onSignal?.();
-            // Return structured digest for client-side error boundaries
-            return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
+            // Return structured digest for client-side error boundaries.
+            // `ownerKey` is set when an in-tree catch site hoisted the deny
+            // to the segment owning the matched file — it addresses the
+            // boundary that may render it. See TIM-1356.
+            return JSON.stringify({
+              type: 'deny',
+              status: error.status,
+              data: error.data,
+              ownerKey: error.ownerKey,
+            });
           }
           if (error instanceof RedirectSignal) {
             signals.redirectSignal = error;
@@ -126,13 +185,48 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
             checkAndWarnRscPropError(error, new URL(req.url).pathname);
           }
 
-          // Track unhandled errors for pre-flush handling (500 status)
-          if (!signals.renderError) {
-            signals.renderError = { error, status: 500 };
-          }
-          logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+          // Log the error but do NOT track it as a page-level render error.
+          // If this error is inside a <Suspense> boundary, React will emit
+          // an error row in the Flight stream and the Suspense fallback will
+          // render on the client. Tracking it as signals.renderError would
+          // cause the pipeline to treat the entire page as a 500, even though
+          // the shell rendered successfully. See TIM-524.
+          //
+          // Only track as renderError if no Suspense boundary contains it —
+          // React will call onShellError for truly unrecoverable errors.
+
+          // Track the last unhandled error so the pipeline can use it
+          // if SSR fails (SsrStreamError). This is NOT used for page-level
+          // error detection — only as a fallback when SSR actually fails.
+          signals.lastUnhandledError = error;
+          signals.onUnhandledError?.();
+
+          // Return a digest so React emits a per-row error in the Flight
+          // stream instead of leaving the lazy reference unresolved.
+          //
+          // SECURITY: Never include error.message in the digest — it may
+          // contain SQL queries, filesystem paths, secret fragments, or
+          // internal IDs. Use a generic message with a correlation ID so
+          // the error can be matched to server logs.
+          // See design/13-security.md §"Errors don't leak".
+          const errorId = randomUUID();
+          logRenderError({
+            method: req.method,
+            path: new URL(req.url).pathname,
+            error,
+            errorId,
+          });
+          return JSON.stringify({
+            type: 'error',
+            message: isDevMode()
+              ? error instanceof Error
+                ? error.message
+                : String(error)
+              : 'An unexpected error occurred.',
+            errorId,
+          });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -146,6 +240,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
   } catch (error) {
     if (error instanceof DenySignal) {
       signals.denySignal = error;
+      if (!error.ownerKey) signals.unplacedDeny ??= error;
     } else if (error instanceof RedirectSignal) {
       signals.redirectSignal = error;
     } else {
@@ -160,5 +255,14 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     }
   }
 
-  return { rscStream, signals };
+  return {
+    rscStream,
+    signals,
+    // Expose the debug channel collector's getComponents in dev mode.
+    // The caller can retrieve component tree info when handling errors.
+    getDebugComponents:
+      'getComponents' in debugChannel
+        ? (debugChannel as { getComponents: () => DebugComponentEntry[] }).getComponents
+        : undefined,
+  };
 }

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 } from '../ssr-bridge-types.js';
 
 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' }
-  );
+  let ssrEntry: typeof import('../ssr-entry.js');
+  try {
+    ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.js')>(
+      '../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);
 }