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

package/src/server/route-element-builder.ts

@@ -20,11 +20,11 @@ import { createElement, Fragment } from 'react';
 import { withSpan } from './tracing.ts';
 import type { RouteMatch } from './pipeline.ts';
 import type { ManifestSegmentNode } from './route-matcher.ts';
-import type { Metadata } from './types.ts';
-import { DenySignal, RedirectSignal } from './primitives.ts';
+import { isDenySignal, DenySignal } from './primitives.ts';
+import { isClientReference } from './utils/element-type.ts';
+import { loadRouteModules, type MetadataSource, type AccessFn } from './route-module-loader.ts';
 import { MetadataCollector, MetadataHead } from './metadata-collector.ts';
 import { AccessGate } from './access-gate.tsx';
-import { requestContextAls } from './als-registry.ts';
 import { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.ts';
 import type { DenyPageEntry } from './deny-boundary.ts';
 import {
@@ -42,115 +42,13 @@ import { SegmentOutlet } from '../client/segment-outlet.tsx';
 import { TimberErrorBoundary } from '../client/error-boundary.tsx';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
 import type { InterceptionContext } from './pipeline.ts';
-import { shouldSkipSegment, type ClientStateTree } from './state-tree-diff.ts';
-import { truncateSkippableForChangedSlots } from './skippable-prefix.ts';
-import {
-  computeSegmentKeys,
-  computeSegmentTreePaths,
-  computeSlotKey,
-} from '../routing/segment-keys.ts';
+import type { ClientStateTree } from './state-tree-diff.ts';
+import { computeSkippableSet } from './skippable-prefix.ts';
+import { computeSegmentKeys, computeSegmentTreePaths } from '../routing/segment-keys.ts';
 import { setFirstDeniedSegmentIndex } from './deny-boundary.ts';
 import { loadModule } from './safe-load.ts';
+import { replaceOutermostSegmentOutlet } from './route-element-helpers.ts';
 
-/**
- * Replace the outermost SegmentOutlet in a partial payload with its
- * SegmentProvider child. Walks through AccessGate wrappers (which sit
- * outside SegmentOutlet) to find the outlet.
- */
-function replaceOutermostSegmentOutlet(
-  element: React.ReactElement,
-  replacement: React.ReactElement
-): React.ReactElement {
-  if (element.type === SegmentOutlet) {
-    return replacement;
-  }
-  // AccessGate and MetadataCollector wrap outside SegmentOutlet — recurse through them.
-  const props = element.props as Record<string, unknown>;
-  if ((element.type === AccessGate || element.type === MetadataCollector) && props.children) {
-    const inner = replaceOutermostSegmentOutlet(props.children as React.ReactElement, replacement);
-    /* eslint-disable react/no-children-prop -- createElement API */
-    return createElement(element.type as React.FunctionComponent<Record<string, unknown>>, {
-      ...props,
-      children: inner,
-    });
-    /* eslint-enable react/no-children-prop */
-  }
-  return element;
-}
-
-/**
- * Whether a layout's returned tree still contains its children boundary.
- *
- * Layouts may forward `children` through a non-children prop or clone it with
- * React.Children/cloneElement. Checking only `props.children` or object
- * identity would incorrectly classify those layouts as suppressing their
- * descendants and let shell settlement complete before an async child deny.
- */
-export function containsLayoutChildren(
-  node: unknown,
-  boundaryType: React.ElementType,
-  seen = new WeakSet<object>()
-): boolean {
-  if (node == null || typeof node !== 'object') return false;
-  if (seen.has(node)) return false;
-  seen.add(node);
-  try {
-    if (Array.isArray(node)) {
-      return node.some((child) => containsLayoutChildren(child, boundaryType, seen));
-    }
-    if ('$$typeof' in node && 'type' in node && 'props' in node) {
-      if (node.type === boundaryType) return true;
-      // React's development element also exposes `_owner`; following it can
-      // walk back into the currently rendering layout's pending props and
-      // falsely "find" a child that the returned tree actually suppressed.
-      return containsLayoutChildren(node.props, boundaryType, seen);
-    }
-    const descriptors = Object.getOwnPropertyDescriptors(node);
-    return Object.values(descriptors).some(
-      (descriptor) =>
-        'value' in descriptor &&
-        descriptor.enumerable === true &&
-        containsLayoutChildren(descriptor.value, boundaryType, seen)
-    );
-  } catch {
-    // An opaque return value cannot safely prove that it retained the
-    // boundary. Treat it as suppression so an uninspectable Proxy cannot
-    // strand every descendant settlement promise and hang the response.
-    return false;
-  }
-}
-
-export function descendantSettleCallbacks(
-  callbacks: Array<() => void>,
-  layoutSettled: (() => void) | undefined
-): Array<() => void> {
-  // A tracked layout appended its own callback last; descendants are every
-  // callback before it. An untracked layout appended nothing, so all current
-  // callbacks belong to descendants. `slice(0, undefined)` is not equivalent
-  // to `slice()` — it returns an empty array.
-  return layoutSettled ? callbacks.slice(0, -1) : callbacks.slice();
-}
-
-// ─── Client Reference Detection ──────────────────────────────────────────
-
-/**
- * Symbol used by React Flight to mark client references.
- * Client references are proxy objects created by @vitejs/plugin-rsc for
- * 'use client' modules in the RSC environment. They must be passed to
- * createElement() — calling them as functions throws:
- * "Unexpectedly client reference export 'default' is called on server"
- */
-const CLIENT_REFERENCE_TAG = Symbol.for('react.client.reference');
-
-/**
- * Detect whether a component is a React client reference.
- * Client references have $$typeof set to Symbol.for('react.client.reference')
- * by registerClientReference() in the React Flight server runtime.
- *
- * Used to skip OTEL tracing wrappers that would call the component as a
- * function. Client components must go through createElement only — they are
- * serialized as references in the RSC Flight stream, not executed on the server.
- */
 /**
  * The `segments` array handed to a layout's `SegmentProvider` — the value
  * `useSelectedLayoutSegment(s)` reads.
@@ -173,27 +71,6 @@ export function computeLayoutSegmentPath(
   return parts.length === 0 ? [''] : ['', ...parts];
 }
 
-export function isClientReference(component: unknown): boolean {
-  return (
-    component != null &&
-    typeof component === 'function' &&
-    (component as unknown as Record<string, unknown>).$$typeof === CLIENT_REFERENCE_TAG
-  );
-}
-
-// ─── Typed Errors ────────────────────────────────────────────────────────
-
-/**
- * Thrown when an app/schema.ts segment-param codec's parse() fails.
- * The pipeline catches this and responds with 404.
- */
-export class ParamCoercionError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ParamCoercionError';
-  }
-}
-
 /**
  * Thrown when a matched route has no page component in its leaf segment.
  * The pipeline catches this and renders the custom 404 page.
@@ -234,51 +111,73 @@ export interface RouteElementResult {
    * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
    */
   skippedSegments: string[];
-  /**
-   * Resolves when every deny-capable shell component (PageDenyBoundary and
-   * each TracedLayout with a deny page chain) has finished executing, OR
-   * immediately when any of them catches a DenySignal in-tree (the HTTP
-   * status is known at that point; inner components may never run).
-   * Undefined when the route has no deny-capable server components.
-   * See TIM-1045 (pages), TIM-1208 (layouts).
-   */
-  shellSettled?: Promise<void>;
   /**
    * Slot metadata for the X-Timber-Segments header. Contains info about
    * all parallel route slots encountered during element tree construction,
    * enabling the client to populate its segment cache with slot entries.
    */
   slotSkipInfo: SlotSkipEntry[];
+  /**
+   * The deny page chain built from the leaf segment outward to root.
+   * Threaded into `renderRscStream` for late addressing of nested-component
+   * denies in Flight's `onError`. See TIM-1450.
+   */
+  leafDenyChain?: DenyPageEntry[];
 }
 
-// ─── Module Processing Helpers ─────────────────────────────────────────────
+// ─── Wrapping Helpers ────────────────────────────────────────────────────
 
 /**
- * Reject the legacy `generateMetadata` export with a helpful migration message.
- * Throws if the module exports `generateMetadata` instead of `metadata`.
+ * Wrap an element in MetadataCollector(s) for one segment's metadata sources.
+ *
+ * The loop wraps innermost-to-outermost, so the last-wrapped collector
+ * renders first. `.reverse()` ensures layout metadata is pushed before
+ * page metadata, preserving the root→page merge order required by
+ * resolveMetadata (page-authoritative). See TIM-1363.
  */
-function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: string): void {
-  if ('generateMetadata' in mod) {
-    throw new Error(
-      `${filePath}: "generateMetadata" is not a valid export. ` +
-        `Export an async function named "metadata" instead.\n\n` +
-        `  // Before\n` +
-        `  export async function generateMetadata({ params }) { ... }\n\n` +
-        `  // After\n` +
-        `  export async function metadata() { ... }`
-    );
+function wrapMetadataCollectors(
+  element: React.ReactElement,
+  sources: MetadataSource[],
+  h: (...args: unknown[]) => React.ReactElement
+): React.ReactElement {
+  for (const meta of sources) {
+    element = h(MetadataCollector, {
+      metadataExport: meta.metadataExport,
+      segmentName: meta.segmentName,
+      isPage: meta.isPage,
+      children: element,
+    });
   }
+  return element;
 }
 
 /**
- * Extract `deferSuspenseFor` from a module and return the maximum
- * of the current value and the module's value.
+ * Wrap an element in an AccessGate for one segment.
+ *
+ * Skipped segments pass `skippedSegment: true` and omit `denyPages`.
+ * Rendered segments pass `denyPages` and omit `skippedSegment`.
  */
-function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
-  if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
-    return mod.deferSuspenseFor;
-  }
-  return current;
+function wrapAccessGate(
+  element: React.ReactElement,
+  opts: {
+    accessFn: () => unknown;
+    segment: ManifestSegmentNode;
+    segmentKey: string;
+    segmentIndex: number;
+    denyPages?: DenyPageEntry[];
+    skippedSegment?: boolean;
+  },
+  h: (...args: unknown[]) => React.ReactElement
+): React.ReactElement {
+  return h(AccessGate, {
+    accessFn: opts.accessFn,
+    segmentName: opts.segment.segmentName,
+    segmentKey: opts.segmentKey,
+    segmentIndex: opts.segmentIndex,
+    ...(opts.skippedSegment ? { skippedSegment: true } : {}),
+    ...(opts.denyPages ? { denyPages: opts.denyPages } : {}),
+    children: element,
+  });
 }
 
 // ─── Builder ──────────────────────────────────────────────────────────────
@@ -286,10 +185,9 @@ function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number):
 /**
  * Build a React element tree from a matched route.
  *
- * Runs access checks eagerly to gate metadata resolution, then loads
- * modules, resolves metadata (skipping denied segments), and constructs
- * the element tree. DenySignal and RedirectSignal from access are stored
- * as AccessGate verdicts for synchronous replay during render.
+ * Loads route modules, resolves metadata (skipping denied segments via
+ * AccessGate), and constructs the element tree. Access checks run during
+ * render inside AccessGate — denied segments' metadata never executes.
  *
  * Does NOT serialize to RSC Flight — the caller decides whether to render
  * to a stream or use the element directly (e.g., for action revalidation).
@@ -314,74 +212,8 @@ export async function buildRouteElement(
   // placed below each AccessGate — denied segments' metadata() never
   // executes because AccessGate prevents MetadataCollector from rendering.
   // No pre-render access pass needed. See TIM-1363.
-  interface MetadataSource {
-    metadataExport: Metadata | (() => Promise<Metadata>);
-    segmentName: string;
-    isPage: boolean;
-    segmentIndex: number;
-  }
-  const metadataSources: MetadataSource[] = [];
-  const layoutComponents: LayoutComponentEntry[] = [];
-  let PageComponent: ((...args: unknown[]) => unknown) | null = null;
-  let deferSuspenseFor = 0;
-
-  for (let i = 0; i < segments.length; i++) {
-    const segment = segments[i];
-    const isLeaf = i === segments.length - 1;
-
-    // Load layout
-    if (segment.layout) {
-      const mod = await loadModule(segment.layout);
-      if (mod.default) {
-        layoutComponents.push({
-          component: mod.default as (...args: unknown[]) => unknown,
-          segment,
-        });
-      }
-
-      rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
-      if (mod.metadata) {
-        metadataSources.push({
-          metadataExport: mod.metadata as Metadata | (() => Promise<Metadata>),
-          segmentName: segment.segmentName ?? segment.urlPath,
-          isPage: false,
-          segmentIndex: i,
-        });
-      }
-      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
-    }
-
-    // Load page (leaf segment only)
-    if (isLeaf && segment.page) {
-      const mod = await loadModule(segment.page);
-
-      if (mod.default) {
-        PageComponent = mod.default as (...args: unknown[]) => unknown;
-      }
-      rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
-      if (mod.metadata) {
-        metadataSources.push({
-          metadataExport: mod.metadata as Metadata | (() => Promise<Metadata>),
-          segmentName: segment.segmentName ?? segment.urlPath,
-          isPage: true,
-          segmentIndex: i,
-        });
-      }
-      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
-    }
-  }
-
-  if (!PageComponent) {
-    const segmentInfo = segments
-      .map(
-        (s, i) =>
-          `  [${i}] ${s.segmentName} (page: ${s.page ? 'yes' : 'no'}, layout: ${s.layout ? 'yes' : 'no'}, children: ${s.children?.length ?? 0})${i === segments.length - 1 ? ' ← leaf' : ''}`
-      )
-      .join('\n');
-    throw new NoPageComponentError(
-      `No page component found for route: ${new URL(req.url).pathname}\nMatched segments:\n${segmentInfo}`
-    );
-  }
+  const { metadataSources, layoutComponents, PageComponent, deferSuspenseFor, accessFns } =
+    await loadRouteModules(segments, req.url);
 
   // Compute state-tree keys for all segments. Route groups accumulate
   // ancestor group names for globally unique keys (e.g., "/(a)/(shared)"
@@ -414,31 +246,8 @@ export async function buildRouteElement(
   }
 
   // Build element tree: page wrapped in layouts (innermost to outermost)
-  const h = createElement as (...args: unknown[]) => React.ReactElement;
-
-  // Shell settlement tracking (TIM-1045 pages, TIM-1208 layouts).
-  // Multiple deny-capable components can suspend independently. We need all
-  // of them to settle before committing the HTTP status.
-  //
-  // Each tracked component gets its own deferred. shellSettled resolves
-  // when ALL settle (Promise.all) OR when any in-tree deny fires
-  // (short-circuit via onDenyStatus — covers AccessGate, TracedLayout,
-  // and PageDenyBoundary without threading callbacks into each).
-  const shellPromises: Promise<void>[] = [];
-  const shellSettleCallbacks: Array<() => void> = [];
-  let resolveShortCircuit: (() => void) | undefined;
-  const trackShellComponent = (): (() => void) => {
-    let resolve!: () => void;
-    shellPromises.push(new Promise<void>((r) => (resolve = r)));
-    let settled = false;
-    const settle = () => {
-      if (settled) return;
-      settled = true;
-      resolve();
-    };
-    shellSettleCallbacks.push(settle);
-    return settle;
-  };
+  type CreateElementFn = (...args: unknown[]) => React.ReactElement;
+  const h: CreateElementFn = createElement as CreateElementFn;
 
   // Build the page element.
   // Server component pages are wrapped in PageDenyBoundary which calls
@@ -454,13 +263,11 @@ export async function buildRouteElement(
   if (isClientReference(PageComponent)) {
     element = h(PageComponent, {});
   } else if (leafDenyPages && leafDenyPages.length > 0) {
-    const onSettled = trackShellComponent();
     element = h(PageDenyBoundary, {
       Page: PageComponent,
       route: match.segments[leafIndex]?.urlPath ?? '/',
       denyPages: leafDenyPages,
       segmentKey: segmentKeys[leafIndex],
-      onSettled,
     });
   } else {
     // Server component page WITHOUT deny page chain — trace only
@@ -503,86 +310,15 @@ export async function buildRouteElement(
   const skippedSegments: string[] = [];
 
   // Pre-compute the contiguous skippable prefix (top-down).
-  //
-  // Skipped segments must form a contiguous prefix from root to avoid
-  // non-contiguous skips that break the client merge. Walk from root
-  // toward leaf, marking segments as skippable. Stop at the first
-  // segment that can't be skipped (async, not in client tree, leaf).
-  // Layoutless segments are transparent (no outlet, no layout to skip).
-  //
-  // After finding the prefix, validate: the first non-skipped layout
-  // must exist in the client's state tree (the client needs a mounted
-  // outlet there to receive the partial payload).
-  const skippableSet = new Set<number>();
-  if (clientStateTree) {
-    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, isLeaf, clientStateTree)) {
-        skippableSet.add(i);
-      } else if (layoutComponent) {
-        break;
-      }
-    }
-
-    // Ensure there's a merge point: a non-skipped layout whose key is
-    // in the client's state tree (so the client has a mounted outlet).
-    // 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) {
-        // All layouts are skippable — keep the innermost as merge point
-        for (let i = segments.length - 1; i >= 0; i--) {
-          if (skippableSet.has(i) && layoutBySegment.has(segments[i])) {
-            skippableSet.delete(i);
-            mergePointIndex = i;
-            break;
-          }
-        }
-      }
-
-      // Cross-section guard: at least one rendered layout below the
-      // prefix must exist in the client's state tree (the client needs
-      // a mounted outlet to receive the partial payload). Check ALL
-      // non-skipped layouts, not just the merge point — async layouts
-      // are excluded from the client state tree but may sit above a
-      // sync layout that IS in the 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 a skippable layout has parallel
-  // slots whose content changed, the layout cannot be skipped — it must
-  // render so its slots are included in the payload.
-  if (skippableSet.size > 0 && clientStateTree) {
-    truncateSkippableForChangedSlots(
-      skippableSet,
-      segments,
-      segmentKeys,
-      match,
-      clientStateTree,
-      req
-    );
-  }
+  // See skippable-prefix.ts for the three sub-rules and slot-change guard.
+  const skippableSet = computeSkippableSet(
+    segments,
+    segmentKeys,
+    layoutBySegment,
+    clientStateTree,
+    match,
+    req
+  );
 
   let outermostSegmentProvider: React.ReactElement | null = null;
 
@@ -630,16 +366,7 @@ export async function buildRouteElement(
       // root layout title templates). MetadataCollector wraps the element
       // inside AccessGate — if access denies, metadata is excluded.
       const skippedMeta = metadataSources.filter((s) => s.segmentIndex === i).reverse();
-      for (const meta of skippedMeta) {
-        const isDynamic = typeof meta.metadataExport === 'function';
-        element = h(MetadataCollector, {
-          metadataExport: meta.metadataExport,
-          segmentName: meta.segmentName,
-          isPage: meta.isPage,
-          ...(isDynamic ? { onSettled: trackShellComponent() } : {}),
-          children: element,
-        });
-      }
+      element = wrapMetadataCollectors(element, skippedMeta, h);
 
       // SECURITY: Even though the layout is skipped, AccessGate MUST still
       // wrap the element tree. access.ts runs on every navigation regardless
@@ -648,25 +375,28 @@ export async function buildRouteElement(
       //
       // Skipped segments omit denyPages and set skippedSegment=true. If
       // access denies at a skipped segment, AccessGate records the deny in
-      // ALS and rethrows — the response path returns rscErrorEnvelope so the
-      // client hard-navigates for a clean full render with correct deny page
-      // placement. Rendering the deny page in-tree here would appear inside
-      // the client's cached layout chrome (TIM-1074). See TIM-1363.
-      if (segment.access) {
-        const accessMod = await loadModule(segment.access);
-        const accessFn = accessMod.default as (() => unknown) | undefined;
-        if (accessFn) {
-          const onGateSettled = trackShellComponent();
-          element = h(AccessGate, {
+      // ALS and rethrows. Rendering the deny page in-tree here would appear
+      // inside the client's cached layout chrome (TIM-1074), so the throw
+      // goes to Flight's onError instead: addressed there against the leaf
+      // chain, its row is claimed by the boundary the client still has
+      // mounted at the owner (TIM-1450); with no addressable file it stays
+      // unplaced, and the response path answers with rscErrorEnvelope so the
+      // client hard-navigates for a clean full render — when the deny lands
+      // inside Flight's opening window. After it, the unaddressed row reaches
+      // the terminal boundary the last full render left mounted. See TIM-1363.
+      const accessFn = accessFns[i];
+      if (accessFn) {
+        element = wrapAccessGate(
+          element,
+          {
             accessFn,
-            segmentName: segment.segmentName,
+            segment,
             segmentKey: segmentKeys[i],
             segmentIndex: i,
             skippedSegment: true,
-            onSettled: onGateSettled,
-            children: element,
-          });
-        }
+          },
+          h
+        );
       }
 
       continue;
@@ -682,16 +412,7 @@ export async function buildRouteElement(
     // before page metadata, preserving the root→page merge order required
     // by resolveMetadata (page-authoritative). See TIM-1363.
     const segmentMetadata = metadataSources.filter((s) => s.segmentIndex === i).reverse();
-    for (const meta of segmentMetadata) {
-      const isDynamic = typeof meta.metadataExport === 'function';
-      element = h(MetadataCollector, {
-        metadataExport: meta.metadataExport,
-        segmentName: meta.segmentName,
-        isPage: meta.isPage,
-        ...(isDynamic ? { onSettled: trackShellComponent() } : {}),
-        children: element,
-      });
-    }
+    element = wrapMetadataCollectors(element, segmentMetadata, h);
 
     // Wrap with error boundaries from this segment (inside layout).
     // Keep ALL error boundaries (including 4xx) — they're the safety net for
@@ -729,7 +450,7 @@ export async function buildRouteElement(
         interception,
         parentTreePath,
         destinationUrl,
-        clientStateTree: clientStateTree as ClientStateTree | null,
+        clientStateTree: clientStateTree ?? null,
         slotSkipInfo,
       });
 
@@ -759,41 +480,48 @@ export async function buildRouteElement(
         // fallback path. See TIM-668, design/04-authorization.md.
         const layoutComponentRef = layoutComponent;
         const layoutDenyPages = denyPageChains.get(i);
-        const hasLayoutDenyChain = !!layoutDenyPages && layoutDenyPages.length > 0;
-        const onLayoutSettled = hasLayoutDenyChain ? trackShellComponent() : undefined;
-        const descendantSettlers = descendantSettleCallbacks(shellSettleCallbacks, onLayoutSettled);
-        const LayoutChildrenBoundary = ({ children }: { children: React.ReactNode }) => children;
         const TracedLayout = async (props: Record<string, unknown>) => {
           try {
-            const rendered = await withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
+            return await withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
               (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
             );
-            // A layout is allowed to suppress children. Descendant deny-capable
-            // components will never execute in that case, so settle their
-            // bookkeeping rather than leaving the RSC response waiting forever.
-            if (!containsLayoutChildren(rendered, LayoutChildrenBoundary)) {
-              for (const settle of descendantSettlers) settle();
-            }
-            return rendered;
           } catch (error: unknown) {
             // A layout that denied never renders its own chrome — it threw
             // instead of returning it — so an entry this segment owns is
             // already correctly placed here. Anything owned further up is
             // hoisted (handleCaughtDeny throws). See TIM-1356.
-            if (error instanceof DenySignal) {
+            if (isDenySignal(error)) {
               setFirstDeniedSegmentIndex(i);
               if (layoutDenyPages) {
                 return handleCaughtDeny(layoutDenyPages, error, segmentId);
               }
             }
             throw error;
-          } finally {
-            onLayoutSettled?.();
           }
         };
         layoutElement = h(TracedLayout, {
           ...slotProps,
-          children: h(LayoutChildrenBoundary, { children: element }),
+          children: element,
+        });
+
+        // A second, deny-only copy of this segment's boundaries OUTSIDE its
+        // layout. The copy above (inside the layout) is the one a page error
+        // reaches; a server component this layout renders in its own chrome
+        // is a sibling of `children`, so its throw never passes that copy —
+        // it passes this one. Claiming is by the same key, so the segment
+        // answers a nested deny in its chrome the way `TracedLayout` answers
+        // a deny in the layout body: with its own file, replacing the layout.
+        // A hoisted deny addressed further up passes through unclaimed.
+        //
+        // Inside SegmentProvider so a partial navigation, which splices the
+        // provider into the client's mounted outlet, carries it along.
+        // See TIM-1450, design/04-authorization.md §"Where a Deny Page Renders".
+        layoutElement = await wrapSegmentWithErrorBoundaries(segment, layoutElement, {
+          loadModule,
+          createElement: h,
+          errorBoundaryComponent: TimberErrorBoundary,
+          segmentKey: segmentId,
+          denyOnly: true,
         });
       }
 
@@ -822,21 +550,19 @@ export async function buildRouteElement(
     // Parent layouts (from outer iterations) form the shell. Access runs
     // exactly once, during render, inside React.cache scope — layouts
     // share the cache. See TIM-1363, design/04-authorization.md.
-    if (segment.access) {
-      const accessMod = await loadModule(segment.access);
-      const accessFn = accessMod.default as (() => unknown) | undefined;
-      if (accessFn) {
-        const onGateSettled = trackShellComponent();
-        element = h(AccessGate, {
+    const accessFn = accessFns[i];
+    if (accessFn) {
+      element = wrapAccessGate(
+        element,
+        {
           accessFn,
-          segmentName: segment.segmentName,
+          segment,
           segmentKey: segmentKeys[i],
           segmentIndex: i,
           denyPages: denyPageChains.get(i),
-          onSettled: onGateSettled,
-          children: element,
-        });
-      }
+        },
+        h
+      );
     }
   }
 
@@ -849,16 +575,27 @@ export async function buildRouteElement(
     element = replaceOutermostSegmentOutlet(element, outermostSegmentProvider);
   }
 
-  // Compose shellSettled: resolves when ALL deny-capable components settle
-  // (Promise.all) OR immediately when any component calls setDenyStatus()
-  // (short-circuit via onDenyStatus — covers AccessGate, TracedLayout, and
-  // PageDenyBoundary). See TIM-1045, TIM-1208.
-  let shellSettled: Promise<void> | undefined;
-  if (shellPromises.length > 0) {
-    const shortCircuit = new Promise<void>((r) => (resolveShortCircuit = r));
-    const store = requestContextAls.getStore();
-    if (store) store.onDenyStatus = () => resolveShortCircuit?.();
-    shellSettled = Promise.race([Promise.all(shellPromises).then(() => {}), shortCircuit]);
+  // The deny chain's terminal, for a deny that streamed as an error row and
+  // that no segment boundary — inner or outer — could claim. With the outer
+  // copies above, that is one shape only: a server component in a layout's
+  // chrome denied and no status file exists at or above that layout. Files
+  // below it are not candidates (rendering them re-runs the layout that
+  // denied), so this renders the framework default page, as the document
+  // path does for a deny with no file. A non-deny row nothing claimed ends
+  // here too: the terminal leaves the SPA so the document request renders
+  // the real error page (see TimberErrorBoundary). Outside every segment
+  // boundary, inside the payload root so hydration agrees.
+  //
+  // Skipped on partial navigations: the terminal from the last full render
+  // is still mounted above the merge point, and a copy here would sit below
+  // the skipped ancestors' boundaries and intercept denies addressed to them.
+  // See TIM-1450.
+  if (skippedSegments.length === 0) {
+    element = h(TimberErrorBoundary, {
+      lastResort: true,
+      fallbackComponent: (await import('../client/deny-last-resort.tsx')).DenyLastResort,
+      children: element,
+    });
   }
 
   // Publish the request's params beside the finished tree, as the payload's
@@ -872,7 +609,7 @@ export async function buildRouteElement(
     segments,
     deferSuspenseFor,
     skippedSegments,
-    shellSettled,
     slotSkipInfo,
+    leafDenyChain: leafDenyPages,
   };
 }