@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

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

@@ -15,8 +15,16 @@ import type { RscPayloadRoot } from '../../shared/payload-root.ts';
 
 import { randomUUID } from 'node:crypto';
 
+import { matchDenyEntries, type DenyPageEntry } from '../deny-boundary.ts';
 import { logRenderError } from '../logger.ts';
-import { DenySignal, RedirectSignal, RenderError } from '../primitives.ts';
+import {
+  isDenySignal,
+  isRedirectSignal,
+  isRenderError,
+  DenySignal,
+  RedirectSignal,
+  RenderError,
+} from '../primitives.ts';
 import { checkAndWarnRscPropError } from '../rsc-prop-warnings.ts';
 
 import {
@@ -41,7 +49,7 @@ import { isDevMode } from '../debug.ts';
 export interface RenderSignals {
   denySignal: DenySignal | null;
   /**
-   * The first deny that no in-tree catch site could place — no `ownerKey`, so
+   * The first deny that no in-tree catch site could place — no `owners`, so
    * no boundary may claim its error row and only the re-render fallback can
    * produce a page for it.
    *
@@ -49,7 +57,7 @@ export interface RenderSignals {
    * 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.
+   * deciding from `denySignal.owners` alone would strand it. See TIM-1356.
    */
   unplacedDeny: DenySignal | null;
   redirectSignal: RedirectSignal | null;
@@ -66,14 +74,6 @@ export interface RenderSignals {
   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;
@@ -97,7 +97,11 @@ export interface RscStreamResult {
  * fires onError during stream consumption. Signals are captured in the
  * returned `signals` object for the caller to handle.
  */
-export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStreamResult {
+export function renderRscStream(
+  payload: RscPayloadRoot,
+  req: Request,
+  leafDenyChain?: DenyPageEntry[]
+): RscStreamResult {
   const signals: RenderSignals = {
     denySignal: null,
     unplacedDeny: null,
@@ -121,22 +125,39 @@ export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStrea
           // Connection abort (user refreshed or navigated away) — suppress.
           // Not an application error; no need to track or log.
           if (isAbortError(error) || req.signal?.aborted) return;
-          if (error instanceof DenySignal) {
-            signals.denySignal = error;
-            if (!error.ownerKey) signals.unplacedDeny ??= error;
+          if (isDenySignal(error)) {
+            // Late addressing (TIM-1450): a nested-component deny escapes
+            // all in-tree catch sites and arrives here without owners.
+            // Resolve it against the leaf deny chain — when the first match
+            // is non-MDX, stamp the full candidate list so the client can
+            // find the first reachable owner via its ancestry context.
+            if (!error.owners && leafDenyChain) {
+              const entries = matchDenyEntries(leafDenyChain, error.status);
+              if (entries.length > 0 && !entries[0].isMdx) {
+                // Only non-MDX entries are addressable — MDX boundaries hold
+                // pre-rendered fallbackElements without runtime props. TIM-1451
+                // will widen exact-code MDX; until then they stay on the
+                // re-render fallback path.
+                const nonMdx = entries.filter((e) => !e.isMdx);
+                if (nonMdx.length > 0) {
+                  error.owners = nonMdx.map((e) => e.ownerKey);
+                }
+              }
+            }
+            // First-wins: two concurrent denies from separately serialized
+            // subtrees must commit a deterministic status. See
+            // spike-TIM-1441 §"two-concurrent-denials scenario".
+            signals.denySignal ??= error;
+            if (!error.owners) signals.unplacedDeny ??= error;
             signals.onSignal?.();
-            // 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,
+              owners: error.owners,
             });
           }
-          if (error instanceof RedirectSignal) {
+          if (isRedirectSignal(error)) {
             signals.redirectSignal = error;
             signals.onSignal?.();
             return JSON.stringify({
@@ -145,7 +166,7 @@ export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStrea
               status: error.status,
             });
           }
-          if (error instanceof RenderError) {
+          if (isRenderError(error)) {
             // Track the first render error for pre-flush handling
             if (!signals.renderError) {
               signals.renderError = { error, status: error.status };
@@ -238,10 +259,10 @@ export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStrea
       }
     );
   } catch (error) {
-    if (error instanceof DenySignal) {
-      signals.denySignal = error;
-      if (!error.ownerKey) signals.unplacedDeny ??= error;
-    } else if (error instanceof RedirectSignal) {
+    if (isDenySignal(error)) {
+      signals.denySignal ??= error;
+      if (!error.owners) signals.unplacedDeny ??= error;
+    } else if (isRedirectSignal(error)) {
       signals.redirectSignal = error;
     } else {
       // Synchronous render error — component threw during
@@ -249,7 +270,7 @@ export function renderRscStream(payload: RscPayloadRoot, req: Request): RscStrea
       // the server; the error page will be rendered below.
       signals.renderError = {
         error,
-        status: error instanceof RenderError ? error.status : 500,
+        status: isRenderError(error) ? error.status : 500,
       };
       logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
     }

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

@@ -20,7 +20,7 @@ import { getSlotParamsForClient } from '../request-context.ts';
 import type { LayoutEntry } from '../deny-renderer.ts';
 import { renderDenyPage } from '../deny-renderer.ts';
 import type { RouteMatch } from '../pipeline.ts';
-import { SsrStreamError } from '../primitives.ts';
+import { isSsrStreamError } from '../primitives.ts';
 import type { LayoutComponentEntry } from '../route-element-builder.ts';
 import type { ManifestSegmentNode } from '../route-matcher.ts';
 import type { SlotSkipEntry } from '../slot-resolver.ts';
@@ -405,15 +405,11 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     // Deny pages still go through RSC → SSR (plain props), so they pass empty
     // layouts to avoid re-executing server components in the RSC environment's
     // stale ALS scope. See LOCAL-293.
-    // Name-based check: SsrStreamError is thrown in the SSR environment
-    // but caught in the RSC environment. Since RSC and SSR are separate
-    // Vite module graphs, `instanceof` fails (different class identities).
-    // Use error.name instead. See design/18-build-system.md §"Virtual Module
-    // Resolution Quirks".
-    const isSsrStreamError =
-      ssrError instanceof SsrStreamError ||
-      (ssrError instanceof Error && ssrError.name === 'SsrStreamError');
-    if (isSsrStreamError) {
+    // 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)) {
       // Cancel the teed inline stream — SSR failed so this response will
       // be replaced by renderErrorPage which creates its own clean streams.
       // Without explicit cancellation the orphaned tee branch keeps the

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/skippable-prefix.ts

@@ -1,20 +1,118 @@
 /**
- * Skippable-prefix truncation.
+ * Skippable-prefix computation.
  *
- * Extracted from `route-element-builder.ts`, which was over the 500-line limit
- * (design/18-build-system.md). This is a self-contained question — "may this
- * segment's layout still be skipped, given what its slots would render?" — with
- * no dependency on element construction.
+ * Determines which layouts can be skipped on a partial navigation by
+ * computing a contiguous prefix of segments whose cached layouts need
+ * not re-render. Extracted from `route-element-builder.ts` to keep it
+ * under the 500-line limit (design/18-build-system.md).
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header".
  */
 
 import type { ManifestSegmentNode } from './route-matcher.ts';
 import type { RouteMatch } from './pipeline.ts';
-import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.ts';
+import { shouldSkipSegment, shouldSkipSlot, type ClientStateTree } from './state-tree-diff.ts';
 import { consumedUrlParts } from './chain-url-parts.ts';
 import { computeSlotContentKey, computeSlotKey } from '../routing/segment-keys.ts';
 import { matchUrlParts } from './tree-match.ts';
 import { slotUrlParts } from './slot-resolver.ts';
 
+/**
+ * Compute the set of segment indices whose layouts can be skipped.
+ *
+ * Three sub-rules in order:
+ *   (a) Contiguous prefix via `shouldSkipSegment` — stop at the first
+ *       non-skippable layout.
+ *   (b) If every layout landed in the prefix, remove the innermost one
+ *       as the merge point (the client needs a mounted outlet there).
+ *   (c) Cross-section guard — clear the whole set unless at least one
+ *       non-skipped layout's key is in `clientStateTree`.
+ *
+ * After the prefix is computed, `truncateSkippableForChangedSlots`
+ * removes any segment whose parallel slots changed content.
+ */
+export function computeSkippableSet(
+  segments: ManifestSegmentNode[],
+  segmentKeys: string[],
+  layoutBySegment: Map<ManifestSegmentNode, unknown>,
+  clientStateTree: ClientStateTree | null | undefined,
+  match: RouteMatch,
+  req: Request
+): Set<number> {
+  const skippableSet = new Set<number>();
+  if (!clientStateTree) return skippableSet;
+
+  // (a) Contiguous prefix via shouldSkipSegment.
+  for (let i = 0; i < segments.length; i++) {
+    const isLeaf = i === segments.length - 1;
+    const layoutComponent = layoutBySegment.get(segments[i]);
+
+    if (
+      shouldSkipSegment(
+        segmentKeys[i],
+        layoutComponent as ((...args: unknown[]) => unknown) | undefined,
+        isLeaf,
+        clientStateTree
+      )
+    ) {
+      skippableSet.add(i);
+    } else if (layoutComponent) {
+      break;
+    }
+  }
+
+  // (b) Ensure there's a merge point: if all layouts are in the prefix,
+  // keep the innermost as merge point.
+  if (skippableSet.size > 0) {
+    let mergePointIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+      if (skippableSet.has(i)) continue;
+      if (layoutBySegment.has(segments[i])) {
+        mergePointIndex = i;
+        break;
+      }
+    }
+
+    if (mergePointIndex === -1) {
+      for (let i = segments.length - 1; i >= 0; i--) {
+        if (skippableSet.has(i) && layoutBySegment.has(segments[i])) {
+          skippableSet.delete(i);
+          mergePointIndex = i;
+          break;
+        }
+      }
+    }
+
+    // (c) Cross-section guard: at least one rendered layout below the
+    // prefix must exist in the client's state tree.
+    let hasClientOutlet = false;
+    for (let j = 0; j < segments.length; j++) {
+      if (skippableSet.has(j)) continue;
+      if (layoutBySegment.has(segments[j]) && clientStateTree.has(segmentKeys[j])) {
+        hasClientOutlet = true;
+        break;
+      }
+    }
+    if (!hasClientOutlet) {
+      skippableSet.clear();
+    }
+  }
+
+  // Slot-change guard (TIM-1232).
+  if (skippableSet.size > 0) {
+    truncateSkippableForChangedSlots(
+      skippableSet,
+      segments,
+      segmentKeys,
+      match,
+      clientStateTree,
+      req
+    );
+  }
+
+  return skippableSet;
+}
+
 /**
  * Truncate the skippable prefix when a skippable layout has slots whose
  * content changed between the departing and destination URLs (TIM-1232).
@@ -28,7 +126,7 @@ import { slotUrlParts } from './slot-resolver.ts';
  * Uses key-based diffing (TIM-1370): computes the destination content key
  * per slot and checks if the client's advertised set contains it.
  */
-export function truncateSkippableForChangedSlots(
+function truncateSkippableForChangedSlots(
   skippableSet: Set<number>,
   segments: ManifestSegmentNode[],
   segmentKeys: string[],

package/src/server/slot-resolver.ts

@@ -20,10 +20,11 @@ import { TimberErrorBoundary } from '../client/error-boundary.tsx';
 import SlotErrorFallback from '../client/slot-error-fallback.tsx';
 import { SlotAccessGate } from './access-gate.tsx';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
-import { isClientReference } from './route-element-builder.ts';
+import { isClientReference } from './utils/element-type.ts';
+import { containSlotSubtree } from './slot-subtree-contain.ts';
 import { loadModule } from './safe-load.ts';
 import type { InterceptionContext, RouteMatch } from './pipeline.ts';
-import { DenySignal, RedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
 import { logRenderError } from './logger.ts';
 import type { ManifestSegmentNode } from './route-matcher.ts';
 import { setSlotParams, runWithSlotSegmentParams } from './request-context.ts';
@@ -140,23 +141,30 @@ export async function resolveSlotElement(
       // For server components, wrap in SafeSlotPage to catch ALL errors at the
       // component level. This prevents errors from leaving unresolved Flight
       // rows in the RSC stream — see TIM-524 for details.
+      //
+      // The catch below covers the page function. The tree it RETURNS is
+      // contained separately (`containSlotSubtree`): a server component
+      // nested in that tree runs as its own Flight task, outside this
+      // try/catch, and a deny there would otherwise reach Flight's global
+      // onError as a page-level 4xx. See slot-subtree-contain.ts, TIM-1450.
       let element: React.ReactElement;
       if (isClientReference(SlotPage)) {
         element = h(SlotPage, {});
       } else {
         const SafeSlotPage = async (props: Record<string, unknown>) => {
           try {
-            return await scope(() =>
+            const rendered = await scope(() =>
               (SlotPage as (props: Record<string, unknown>) => unknown)(props)
             );
+            return containSlotSubtree(rendered as React.ReactNode, denyFallback);
           } catch (error) {
             // RedirectSignal must propagate — the pipeline handles redirects
             // at the top level. Swallowing it here would silently return
             // fallback content instead of redirecting. See TIM-554.
-            if (error instanceof RedirectSignal) {
+            if (isRedirectSignal(error)) {
               throw error;
             }
-            if (error instanceof DenySignal) {
+            if (isDenySignal(error)) {
               return denyFallback;
             }
             // Log the error but don't re-throw — returning fallback ensures
@@ -176,11 +184,17 @@ export async function resolveSlotElement(
       // intermediate slot segments (everything between slot root and leaf).
       // Process innermost-first, same order as route-element-builder.ts
       // handles main segments. The slot root (index 0) is handled below.
-      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h, scope);
+      element = await wrapWithIntermediateSegments(
+        slotMatch.chain,
+        element,
+        h,
+        scope,
+        denyFallback
+      );
 
       // Wrap with slot root's layout — INSIDE the access gate, so the layout
       // server component never executes when access.ts denies. See TIM-1074.
-      element = await wrapWithLayout(slotNode, element, h, scope);
+      element = await wrapWithLayout(slotNode, element, h, scope, denyFallback);
 
       // Wrap in SlotAccessGate if slot root has access.ts. The gate is
       // OUTSIDE the layout, matching the segment model in
@@ -191,11 +205,15 @@ export async function resolveSlotElement(
       // See design/04-authorization.md §"Slot-Level Auth".
       element = await wrapWithAccessGate(slotNode, element, h, scope);
 
-      // Wrap with slot root's error boundaries (outermost)
+      // Wrap with slot root's error boundaries (outermost). Slot identity on
+      // every one of them, not only the catch-all below: a slot's own
+      // status page must not set the document status or empty the main
+      // route's segment cache.
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
         loadModule,
         createElement: h,
         errorBoundaryComponent: TimberErrorBoundary,
+        isSlotBoundary: true,
       });
 
       // Catch-all error boundary: ensures slot errors NEVER propagate to the
@@ -271,7 +289,8 @@ async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
   h: CreateElementFn,
-  scope?: SlotParamScope
+  scope?: SlotParamScope,
+  denyFallback?: React.ReactNode
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
     const seg = chain[i];
@@ -279,8 +298,9 @@ async function wrapWithIntermediateSegments(
       loadModule,
       createElement: h,
       errorBoundaryComponent: TimberErrorBoundary,
+      isSlotBoundary: true,
     });
-    element = await wrapWithLayout(seg, element, h, scope);
+    element = await wrapWithLayout(seg, element, h, scope, denyFallback);
     element = await wrapWithAccessGate(seg, element, h, scope);
   }
   return element;
@@ -309,13 +329,22 @@ type SlotParamScope = <T>(fn: () => T) => T;
  * Server component: the function-valued props are called here on the server
  * and never reach the Flight stream, the same way `SlotAccessGate` takes
  * `accessFn`.
+ *
+ * The layout's own chrome is part of the slot's subtree, so the tree it
+ * returns is contained like the page's: a server component the layout
+ * renders beside `children` that denies becomes the slot fallback in place,
+ * not a page-level 4xx. `children` is the element the resolver built for the
+ * level below, already contained there, and is passed to the walk as the one
+ * subtree to leave alone. See slot-subtree-contain.ts.
  */
 function ScopedSlotLayout(props: {
   layout: (props: Record<string, unknown>) => unknown;
   scope: SlotParamScope;
+  denyFallback: React.ReactNode;
   children: React.ReactElement;
 }): unknown {
-  return props.scope(() => props.layout({ children: props.children }));
+  const rendered = props.scope(() => props.layout({ children: props.children }));
+  return containSlotSubtree(rendered as React.ReactNode, props.denyFallback, props.children);
 }
 
 /**
@@ -332,7 +361,8 @@ async function wrapWithLayout(
   node: ManifestSegmentNode,
   element: React.ReactElement,
   h: CreateElementFn,
-  scope?: SlotParamScope
+  scope?: SlotParamScope,
+  denyFallback: React.ReactNode = null
 ): Promise<React.ReactElement> {
   if (!node.layout) return element;
   const Layout = await loadComponent(node.layout);
@@ -342,6 +372,7 @@ async function wrapWithLayout(
   return h(ScopedSlotLayout, {
     layout: Layout as (props: Record<string, unknown>) => unknown,
     scope,
+    denyFallback,
     children: element,
   });
 }