@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

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

@@ -20,115 +20,36 @@ import { createElement, Fragment } from 'react';
 import { withSpan } from './tracing.js';
 import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
-import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import type { Metadata } from './types.js';
-import { collectMetadataRouteHeadElements } from './metadata-routes.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
+import { MetadataCollector, MetadataHead } from './metadata-collector.js';
 import { AccessGate } from './access-gate.js';
 import { requestContextAls } from './als-registry.js';
-import {
-  PageDenyBoundary,
-  buildDenyPageChain,
-  renderMatchingDenyPage,
-  setDenyStatus,
-} from './deny-boundary.js';
+import { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.js';
 import type { DenyPageEntry } from './deny-boundary.js';
 import { LAYOUT_CHILDREN_SLOT } from './prebuilt/slots.js';
-import { resolveSlotProps, extractUrlParts, type SlotSkipEntry } from './slot-resolver.js';
+import { resolveSlotProps, publishSlotSegmentParams, type SlotSkipEntry } from './slot-resolver.js';
+import { consumedUrlParts } from './chain-url-parts.js';
+import { withPublishedParams } from './publish-params.js';
+import type { RscPayloadRoot } from '../shared/payload-root.js';
 import { SegmentProvider } from '../client/segment-context.js';
 import { SegmentOutlet } from '../client/segment-outlet.js';
 import { SlotOutlet } from '../client/slot-outlet.js';
 import { SlotsProvider } from '../client/slot-provider.js';
 
+import { TimberErrorBoundary } from '../client/error-boundary.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
+import { shouldSkipSegment, type ClientStateTree } from './state-tree-diff.js';
+import { truncateSkippableForChangedSlots } from './skippable-prefix.js';
 import {
-  shouldSkipSegment,
-  shouldSkipSlot,
   computeSegmentKeys,
+  computeSegmentTreePaths,
   computeSlotKey,
-  type ClientStateTree,
-} from './state-tree-diff.js';
-import { headElementsToReact } from './metadata.js';
+} from '../routing/segment-keys.js';
+import { setFirstDeniedSegmentIndex } from './deny-boundary.js';
 import { loadModule } from './safe-load.js';
 
-/**
- * Truncate the skippable prefix when a skippable layout has slots whose
- * content changed between the departing and destination URLs (TIM-1232).
- *
- * Without this, changed slots at skipped layouts are never sent to the
- * client — the `continue` in the main loop skips slot resolution entirely.
- * Removing the segment from the skippable set forces it to render with
- * its slots. The prefix must stay contiguous, so all segments after the
- * first changed-slot segment are also removed.
- */
-function truncateSkippableForChangedSlots(
-  skippableSet: Set<number>,
-  segments: ManifestSegmentNode[],
-  segmentKeys: string[],
-  match: RouteMatch,
-  clientStateTree: ClientStateTree,
-  req: Request
-): void {
-  const departingUrl = req.headers.get('X-Timber-URL');
-  let depParsed: URL | null = null;
-  if (departingUrl) {
-    try {
-      depParsed = new URL(departingUrl, 'http://localhost');
-    } catch {
-      skippableSet.clear();
-      return;
-    }
-  }
-  const destPathname = new URL(req.url, 'http://localhost').pathname;
-  const depPathname = depParsed?.pathname ?? null;
-  const split = (p: string) => (p === '/' ? [] : p.slice(1).split('/'));
-  const destAll = split(destPathname);
-  const depAll = depPathname ? split(depPathname) : null;
-  const clientSlots = clientStateTree.slots ?? null;
-  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
-
-  for (let i = 0; i < segments.length; i++) {
-    if (!skippableSet.has(i)) continue;
-    const segment = segments[i];
-    const slotEntries = Object.entries(segment.slots ?? {});
-    if (slotEntries.length === 0) continue;
-
-    const segIdx = match.segments.indexOf(segment);
-    const parents =
-      segIdx >= 0 ? match.segments.slice(0, segIdx + 1).filter((s) => s.segmentName !== '') : [];
-    const sliceAt = extractUrlParts(parents, rawParams).length;
-    const destParts = destAll.slice(sliceAt);
-    const depParts = depAll ? depAll.slice(sliceAt) : null;
-    let parentChanged = false;
-    if (depAll) {
-      const dp = depAll.slice(0, sliceAt),
-        dd = destAll.slice(0, sliceAt);
-      parentChanged = dp.length !== dd.length || dp.some((p, j) => p !== dd[j]);
-    }
-
-    for (const [slotName, slotNode] of slotEntries) {
-      const m = slotNode as ManifestSegmentNode;
-      const k = computeSlotKey(segmentKeys[i], `@${slotName}`);
-      if (
-        m.children.some((c) => c.segmentType === 'intercepting') ||
-        parentChanged ||
-        depParts === null ||
-        !shouldSkipSlot({
-          slotKey: k,
-          clientSlots,
-          slotNode: m,
-          departingUrlParts: depParts,
-          destinationUrlParts: destParts,
-        })
-      ) {
-        for (let j = i; j < segments.length; j++) skippableSet.delete(j);
-        return;
-      }
-    }
-  }
-}
-
 /**
  * Replace the outermost SegmentOutlet in a partial payload with its
  * SegmentProvider child. Walks through AccessGate wrappers (which sit
@@ -141,9 +62,9 @@ function replaceOutermostSegmentOutlet(
   if (element.type === SegmentOutlet) {
     return replacement;
   }
-  // AccessGate wraps outside SegmentOutlet — recurse through it.
+  // AccessGate and MetadataCollector wrap outside SegmentOutlet — recurse through them.
   const props = element.props as Record<string, unknown>;
-  if (element.type === AccessGate && props.children) {
+  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>>, {
@@ -175,6 +96,28 @@ const CLIENT_REFERENCE_TAG = Symbol.for('react.client.reference');
  * 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.
+ *
+ * Only its **length** matters: both hooks take `segments.length` as a depth and
+ * index the live pathname with it. So this is really "how many URL parts had
+ * been consumed by the time this layout rendered", which is
+ * `consumedUrlParts` — the same derivation slot matching and the slot-skip
+ * slicing use, so a layout and the slots beside it cannot disagree about how
+ * deep they are. The root consumes nothing → `['']`, length 1.
+ *
+ * @internal — exported for tests; production has exactly one caller.
+ */
+export function computeLayoutSegmentPath(
+  segments: ManifestSegmentNode[],
+  index: number,
+  match: RouteMatch
+): string[] {
+  const parts = consumedUrlParts(segments, index, match);
+  return parts.length === 0 ? [''] : ['', ...parts];
+}
+
 export function isClientReference(component: unknown): boolean {
   return (
     component != null &&
@@ -186,7 +129,7 @@ export function isClientReference(component: unknown): boolean {
 // ─── Typed Errors ────────────────────────────────────────────────────────
 
 /**
- * Thrown when a defineSegmentParams codec's parse() fails.
+ * 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 {
@@ -217,8 +160,12 @@ export interface LayoutComponentEntry {
 
 /** Result of building a route element tree. */
 export interface RouteElementResult {
-  /** The React element tree (page wrapped in layouts, access gates, error boundaries). */
-  element: React.ReactElement;
+  /**
+   * The payload root: the React element tree (page wrapped in layouts, access
+   * gates, error boundaries) plus the params it rendered with, as siblings.
+   * See shared/payload-root.ts for why params are not a wrapper around it.
+   */
+  payload: RscPayloadRoot;
   /** Layout components loaded along the segment chain. */
   layoutComponents: LayoutComponentEntry[];
   /** Segments from the route match. */
@@ -334,47 +281,19 @@ export async function buildRouteElement(
 ): Promise<RouteElementResult> {
   const segments = match.segments;
 
-  // ── Access pre-pass ──────────────────────────────────────────────────
-  // Run access checks eagerly to determine which segments are denied.
-  // This gates metadata() resolution: denied segments' metadata functions
-  // are never called, preventing unauthorized side effects (DB queries)
-  // and metadata content leaking into the <head> of denied responses.
-  //
-  // Verdicts are passed to AccessGate for synchronous replay (DenySignal
-  // renders the deny page in-tree; RedirectSignal propagates). For PASSING
-  // segments, no verdict is passed — AccessGate re-runs access during
-  // renderToReadableStream to populate React.cache for layout dedup.
-  //
-  // See TIM-1027, design/04-authorization.md, design/13-security.md.
-  const accessVerdicts = new Map<number, DenySignal | RedirectSignal>();
-  let firstDeniedIndex = Infinity;
-
-  for (let i = 0; i < segments.length; i++) {
-    const segment = segments[i];
-    if (!segment.access || i >= firstDeniedIndex) continue;
-
-    try {
-      const accessMod = await loadModule(segment.access);
-      const accessFn = accessMod.default as (() => Promise<void>) | undefined;
-      if (accessFn) {
-        await withSpan(
-          'timber.access.pre',
-          { 'timber.segment': segment.segmentName ?? 'unknown' },
-          () => accessFn()
-        );
-      }
-    } catch (error: unknown) {
-      if (error instanceof DenySignal || error instanceof RedirectSignal) {
-        accessVerdicts.set(i, error);
-        firstDeniedIndex = i;
-      } else {
-        throw error;
-      }
-    }
+  // ── Module loading ──────────────────────────────────────────────────
+  // Load layout/page modules and collect metadata sources. Metadata
+  // resolution is deferred to render time via MetadataCollector components
+  // 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;
   }
-
-  // ── Module loading + metadata resolution ─────────────────────────────
-  const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
+  const metadataSources: MetadataSource[] = [];
   const layoutComponents: LayoutComponentEntry[] = [];
   let PageComponent: ((...args: unknown[]) => unknown) | null = null;
   let deferSuspenseFor = 0;
@@ -382,7 +301,6 @@ export async function buildRouteElement(
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
-    const isDenied = i >= firstDeniedIndex;
 
     // Load layout
     if (segment.layout) {
@@ -394,15 +312,14 @@ export async function buildRouteElement(
         });
       }
 
-      // Param coercion is handled in the pipeline (Stage 2c) before
-      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
-
       rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
-      if (!isDenied) {
-        const layoutMetadata = await extractMetadata(mod, segment);
-        if (layoutMetadata) {
-          metadataEntries.push({ metadata: layoutMetadata, isPage: false });
-        }
+      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);
     }
@@ -411,18 +328,17 @@ export async function buildRouteElement(
     if (isLeaf && segment.page) {
       const mod = await loadModule(segment.page);
 
-      // Param coercion is handled in the pipeline (Stage 2c) before
-      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
-
       if (mod.default) {
         PageComponent = mod.default as (...args: unknown[]) => unknown;
       }
       rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
-      if (!isDenied) {
-        const pageMetadata = await extractMetadata(mod, segment);
-        if (pageMetadata) {
-          metadataEntries.push({ metadata: pageMetadata, isPage: true });
-        }
+      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);
     }
@@ -440,45 +356,36 @@ export async function buildRouteElement(
     );
   }
 
+  // Compute state-tree keys for all segments. Route groups accumulate
+  // ancestor group names for globally unique keys (e.g., "/(a)/(shared)"
+  // instead of just "/(shared)"). This is the single key computation —
+  // the same keys are used for skip decisions, SegmentOutlet props, the
+  // X-Timber-Segments header (via buildSegmentInfo), the error boundaries,
+  // and deny page ownership.
+  //
+  // Computed here, before the deny chains below, because each chain entry
+  // records the key of the segment that owns it.
+  const segmentKeys = computeSegmentKeys(segments);
+  // The directory path of each segment — the key `setSlotParams` and codegen
+  // both use for a slot beneath it, and the identity interception scoping
+  // compares against. One derivation, so a slot cannot be keyed two ways.
+  const segmentTreePaths = computeSegmentTreePaths(segments);
+
   // Build deny page fallback chains for each segment position.
   // When AccessGate or PageDenyBoundary catches a DenySignal, they render
   // the matching deny page in-tree instead of throwing into React Flight.
   // The chain walks from the current segment outward to root, collecting
-  // status-code files (403.tsx → 4xx.tsx → error.tsx) in fallback order.
-  // See TIM-666.
+  // status-code files (403.tsx → 4xx.tsx → error.tsx) in fallback order,
+  // each tagged with the key of the segment it came from so the catch site
+  // can tell a file it owns from an ancestor's. See TIM-666, TIM-1356.
   const denyPageChains = new Map<number, DenyPageEntry[]>();
   for (let i = 0; i < segments.length; i++) {
-    const chain = await buildDenyPageChain(segments, i);
+    const chain = await buildDenyPageChain(segments, i, segmentKeys);
     if (chain.length > 0) {
       denyPageChains.set(i, chain);
     }
   }
 
-  // Resolve metadata and convert to React elements that React 19 Float
-  // hoists into <head> during both SSR and client rendering. This replaces
-  // the previous HeadElement descriptor system (string splice for SSR,
-  // X-Timber-Head header for RSC nav, imperative DOM updates on client).
-  // React manages <title>/<meta>/<link> lifecycle across navigations.
-  // See design/16-metadata.md, TIM-1151.
-  const resolvedMetadata = resolveMetadata(metadataEntries);
-  const headElements = renderMetadataToElements(resolvedMetadata);
-
-  // Auto-link metadata route files (icon, apple-icon, manifest, opengraph-image).
-  // See design/16-metadata.md §"Auto-Linking"
-  const autoLinkedElements = collectMetadataRouteHeadElements(
-    segments,
-    firstDeniedIndex,
-    resolvedMetadata,
-    new URL(req.url),
-    metadataRouteHashes
-  );
-  headElements.push(...autoLinkedElements);
-
-  // Convert HeadElement descriptors to React elements for Float hoisting.
-  // Placed at the page segment level so they're always re-rendered on
-  // SPA navigation (sync layouts may be skipped by segment tree diffing).
-  const metadataElement = headElementsToReact(headElements);
-
   // Build element tree: page wrapped in layouts (innermost to outermost)
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
@@ -519,6 +426,7 @@ export async function buildRouteElement(
       Page: PageComponent,
       route: match.segments[leafIndex]?.urlPath ?? '/',
       denyPages: leafDenyPages,
+      segmentKey: segmentKeys[leafIndex],
       onSettled,
     });
   } else {
@@ -533,11 +441,18 @@ export async function buildRouteElement(
     element = h(TracedPage, {});
   }
 
-  // Wrap page + metadata in a Fragment so Float-hoisted elements are at
-  // the page segment level (always re-rendered, never skipped by segment
-  // tree diffing). React 19 Float hoists the <title>/<meta>/<link>
-  // children into <head> regardless of where they appear in the tree.
-  element = h(Fragment, null, metadataElement, element);
+  // Wrap page in MetadataHead — a server component that reads all
+  // metadata entries collected by MetadataCollector components above it,
+  // merges them, and renders Float-hoisted head elements as siblings of
+  // the page. Placed at the page level so metadata is always re-rendered
+  // on SPA navigation (never skipped by segment tree diffing).
+  // See TIM-1363, design/16-metadata.md.
+  element = h(MetadataHead, {
+    segments,
+    requestUrl: req.url,
+    metadataRouteHashes,
+    children: element,
+  });
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -548,13 +463,6 @@ export async function buildRouteElement(
   // The client uses this to merge the partial payload with its cached segments.
   const skippedSegments: string[] = [];
 
-  // Compute state-tree keys for all segments. Route groups accumulate
-  // ancestor group names for globally unique keys (e.g., "/(a)/(shared)"
-  // instead of just "/(shared)"). This is the single key computation —
-  // the same keys are used for skip decisions, SegmentOutlet props, and
-  // the X-Timber-Segments header (via buildSegmentInfo).
-  const segmentKeys = computeSegmentKeys(segments);
-
   // Pre-compute the contiguous skippable prefix (top-down).
   //
   // Skipped segments must form a contiguous prefix from root to avoid
@@ -572,10 +480,6 @@ export async function buildRouteElement(
       const isLeaf = i === segments.length - 1;
       const layoutComponent = layoutBySegment.get(segments[i]);
 
-      // Never skip denied segments — their AccessGate must render the
-      // deny page, not reuse the client's cached (passing) layout.
-      if (i >= firstDeniedIndex) break;
-
       if (shouldSkipSegment(segmentKeys[i], layoutComponent, isLeaf, clientStateTree)) {
         skippableSet.add(i);
       } else if (layoutComponent) {
@@ -645,8 +549,27 @@ export async function buildRouteElement(
 
   // Slot caching: the departing URL (X-Timber-URL header) and the
   // destination URL (request URL) are compared to determine which
-  // slots' content has changed. Full URLs (with search) are passed
-  // so slot pages reading getSearchParams() are correctly re-rendered.
+  // slots' content has changed.
+  //
+  // Pathnames only. The client sends `X-Timber-URL` as a pathname
+  // (`client/router.ts` takes `.pathname` on both branches) and
+  // `slot-resolver.ts` reads `.pathname` from both sides, so search
+  // params take no part in the skip decision.
+  //
+  // Nothing here can tell whether a slot's content depends on the query.
+  // What is supposed to make that safe lives elsewhere: a slot whose server
+  // render varies with the query must reach it through a request accessor
+  // (page components are built with no props), which the request-dep analysis
+  // is meant to catch — and that analysis is incomplete for accessors reached
+  // through indirection, so this is currently a real staleness hole. See
+  // TIM-1291 and design/19-client-navigation.md. A slot whose *client* subtree
+  // varies with the query reads useSearchParams(), which re-renders from
+  // NavigationContext whether or not the slot was skipped; that half is
+  // unconditional.
+  //
+  // Do not add search to the comparison by sending the full departing URL:
+  // the header is hashed into the public `_rsc` cache key (TIM-1268),
+  // and a digest does not anonymize a guessable query string.
   const departingUrl = req.headers.get('X-Timber-URL');
   const destinationUrl = req.url;
   const slotSkipInfo: SlotSkipEntry[] = [];
@@ -661,20 +584,63 @@ export async function buildRouteElement(
       // Record for X-Timber-Skipped-Segments header (outermost first, so prepend).
       skippedSegments.unshift(segmentKeys[i]);
 
+      // A skipped layout never reaches resolveSlotProps below, but its slots
+      // stay mounted on the client — so their params still have to be
+      // published, or useSegmentParams(slotPath) falls back to the main
+      // route's record after any navigation that skipped their parent
+      // (TIM-1285). Params only: nothing renders and no access chain runs,
+      // because an unchanged slot is what made this layout skippable.
+      publishSlotSegmentParams(segment, match, destinationUrl, segmentTreePaths[i]);
+
+      // No error boundaries are wrapped for a skipped segment — the `continue`
+      // below returns before that walk. A deny addressed to this segment
+      // therefore finds no boundary in the payload, and since TIM-1356 the
+      // payload path no longer falls back to a re-render for an addressed
+      // deny. What makes that sound is the precondition for skipping at all:
+      // `shouldSkipSegment` only returns true when this exact segment key is
+      // in the client's state tree, which means the client rendered this
+      // segment on an earlier navigation and still has its boundaries mounted,
+      // carrying the same key this build would have stamped. The payload
+      // splices in below them, so the throw passes through them on its way up.
+      //
+      // Metadata from skipped segments still needs to be collected (e.g.,
+      // 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,
+        });
+      }
+
       // SECURITY: Even though the layout is skipped, AccessGate MUST still
       // wrap the element tree. access.ts runs on every navigation regardless
       // of cached layouts or state tree content.
       // See design/13-security.md §"Auth always runs" (test #11).
+      //
+      // 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 verdict = accessVerdicts.get(i);
+          const onGateSettled = trackShellComponent();
           element = h(AccessGate, {
             accessFn,
             segmentName: segment.segmentName,
-            denyPages: denyPageChains.get(i),
-            ...(verdict ? { verdict } : {}),
+            segmentKey: segmentKeys[i],
+            segmentIndex: i,
+            skippedSegment: true,
+            onSettled: onGateSettled,
             children: element,
           });
         }
@@ -683,12 +649,42 @@ export async function buildRouteElement(
       continue;
     }
 
+    // Wrap with MetadataCollector(s) INSIDE error boundaries so a
+    // metadata() throw is caught by this segment's status-file boundaries,
+    // not an ancestor's. Still inside AccessGate (placed below) — when
+    // access denies, neither MetadataCollector nor error boundaries render.
+    //
+    // Reversed: the loop wraps innermost-to-outermost, so the last-wrapped
+    // collector renders first. Reversing ensures layout metadata is pushed
+    // 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,
+      });
+    }
+
     // Wrap with error boundaries from this segment (inside layout).
     // Keep ALL error boundaries (including 4xx) — they're the safety net for
     // DenySignal from nested server components that escape AccessGate/PageDenyBoundary
     // try/catch. Status-code files must be 'use client' TSX or MDX to serialize
     // as error boundary fallbacks. See TIM-666.
-    element = await wrapSegmentWithErrorBoundaries(segment, element, h);
+    // `segmentKey` makes each boundary addressable: a deny hoisted to this
+    // segment carries its owner's key, and every other boundary declines it
+    // rather than catching it first and rendering at the wrong depth
+    // (TIM-1356).
+    element = await wrapSegmentWithErrorBoundaries(segment, element, {
+      loadModule,
+      createElement: h,
+      errorBoundaryComponent: TimberErrorBoundary,
+      segmentKey: segmentKeys[i],
+    });
 
     // Wrap with layout BEFORE AccessGate — AccessGate is OUTSIDE the layout.
     // When AccessGate denies, the layout never renders. The deny page appears
@@ -696,42 +692,26 @@ export async function buildRouteElement(
     // This prevents leaking layout UI (sidebars, nav) on denied pages.
     // See design/04-authorization.md §"Access Failure".
     if (layoutComponent) {
-      // Resolve parallel slots for this layout, wrapping each in
-      // SegmentOutlet for client-side caching. Unchanged slots get
-      // skip=true so the client keeps its cached content.
-      //
-      // Skip slot resolution for denied segments (TIM-1229): when a
-      // parent segment's AccessGate denies, the layout never renders,
-      // so slot props are never consumed. Resolving them is wasted work
-      // and could trigger side effects in slot access.ts functions.
+      // Resolve parallel slots for this layout. If a parent AccessGate
+      // denies during render, the layout never renders and slot props
+      // are never consumed. Slot access functions may still fire eagerly
+      // for skip-candidate slots — a follow-up will make that lazy.
       const segmentId = segmentKeys[i];
-      const parentTreePath =
-        '/' +
-        segments
-          .slice(0, i + 1)
-          .map((s) => s.segmentName)
-          .filter(Boolean)
-          .join('/');
-      const slotProps =
-        i >= firstDeniedIndex
-          ? {}
-          : await resolveSlotProps({
-              segment,
-              segmentId,
-              match,
-              h,
-              interception,
-              parentTreePath,
-              departingUrl,
-              destinationUrl,
-              clientStateTree: clientStateTree as ClientStateTree | null,
-              slotSkipInfo,
-            });
-
-      // '/'.split('/') → ['', ''] (length 2), but root should be [''] (length 1).
-      // The extra empty string makes useSelectedLayoutSegment skip the first URL segment.
-      const rawPath = segment.urlPath.split('/');
-      const segmentPath = rawPath.length === 2 && rawPath[1] === '' ? [''] : rawPath;
+      const parentTreePath = segmentTreePaths[i];
+      const slotProps = await resolveSlotProps({
+        segment,
+        segmentId,
+        match,
+        h,
+        interception,
+        parentTreePath,
+        departingUrl,
+        destinationUrl,
+        clientStateTree: clientStateTree as ClientStateTree | null,
+        slotSkipInfo,
+      });
+
+      const segmentPath = computeLayoutSegmentPath(segments, i, match);
       const parallelRouteKeys = Object.keys(segment.slots ?? {});
 
       // Build the layout element.
@@ -765,11 +745,14 @@ export async function buildRouteElement(
               (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
             );
           } catch (error: unknown) {
-            if (error instanceof DenySignal && layoutDenyPages) {
-              const denyElement = renderMatchingDenyPage(layoutDenyPages, error.status, error.data);
-              if (denyElement) {
-                setDenyStatus(error.status);
-                return denyElement;
+            // 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) {
+              setFirstDeniedSegmentIndex(i);
+              if (layoutDenyPages) {
+                return handleCaughtDeny(layoutDenyPages, error, segmentId);
               }
             }
             throw error;
@@ -810,23 +793,23 @@ export async function buildRouteElement(
       outermostSegmentProvider = segmentProviderElement;
     }
 
-    // Wrap in AccessGate OUTSIDE the layout.
-    // If access denies, the deny page renders here — the layout above
-    // never executes. Parent layouts (from outer iterations) form the shell.
-    // See TIM-662, TIM-666, design/04-authorization.md §"Access Failure".
+    // Wrap in AccessGate OUTSIDE the layout, error boundaries, and MetadataCollector.
+    // If access denies, neither the layout nor MetadataCollector renders.
+    // 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) {
-        // Pass verdict for denied/redirected segments so AccessGate replays
-        // without re-execution. Passing segments omit verdict so AccessGate
-        // re-runs access during render for React.cache population.
-        const verdict = accessVerdicts.get(i);
+        const onGateSettled = trackShellComponent();
         element = h(AccessGate, {
           accessFn,
           segmentName: segment.segmentName,
+          segmentKey: segmentKeys[i],
+          segmentIndex: i,
           denyPages: denyPageChains.get(i),
-          ...(verdict ? { verdict } : {}),
+          onSettled: onGateSettled,
           children: element,
         });
       }
@@ -854,8 +837,13 @@ export async function buildRouteElement(
     shellSettled = Promise.race([Promise.all(shellPromises).then(() => {}), shortCircuit]);
   }
 
+  // Publish the request's params beside the finished tree, as the payload's
+  // root row. Last, because the partial-navigation rewrite above rebuilds the
+  // tree and this takes it as it finally stands.
+  const payload = withPublishedParams(element);
+
   return {
-    element,
+    payload,
     layoutComponents,
     segments,
     deferSuspenseFor,