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

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

@@ -6,43 +6,86 @@
  * rsc-entry.ts under the 500-line limit.
  *
  * This module handles:
- * 1. Loading page/layout components from the segment chain
- * 2. Running access.ts checks (DenySignal/RedirectSignal propagate to caller)
- * 3. Resolving metadata (static object or async function, both exported as `metadata`)
+ * 1. Running access.ts checks eagerly to gate metadata resolution (TIM-1027)
+ * 2. Loading page/layout components from the segment chain
+ * 3. Resolving metadata (skipped for denied segments to prevent side effects)
  * 4. Building the React element tree (page → error boundaries → access gates → layouts)
  * 5. Resolving parallel slots
  *
  * See design/02-rendering-pipeline.md, design/04-authorization.md
  */
 
-import { createElement } from 'react';
-
-import { withSpan, setSpanAttribute } from './tracing.js';
-import type { RouteMatch } from './pipeline.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
-import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import type { HeadElement as MetadataHeadElement } from './metadata.js';
-import type { Metadata } from './types.js';
-import { METADATA_ROUTE_CONVENTIONS, getMetadataRouteAutoLink } from './metadata-routes.js';
-import { DenySignal, RedirectSignal } from './primitives.js';
-import { AccessGate } from './access-gate.js';
-import { resolveSlotElement } from './slot-resolver.js';
-import { SegmentProvider } from '#/client/segment-context.js';
-import { setParsedSearchParams } from './request-context.js';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
-import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
-import type { InterceptionContext } from './pipeline.js';
-import { shouldSkipSegment } from './state-tree-diff.js';
+import { createElement, Fragment } from 'react';
+
+import { withSpan } from './tracing.ts';
+import type { RouteMatch } from './pipeline.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { DenySignal } from './primitives.ts';
+import { isDenySignal } from './signal-identity.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 { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.ts';
+import type { DenyPageEntry } from './deny-boundary.ts';
+import {
+  resolveSlotProps,
+  publishSlotSegmentParams,
+  emitSlotInfoForSkippedLayout,
+  type SlotSkipEntry,
+} from './slot-resolver.ts';
+import { consumedUrlParts } from './chain-url-parts.ts';
+import { withPublishedParams } from './publish-params.ts';
+import type { RscPayloadRoot } from '../shared/payload-root.ts';
+import { SegmentProvider } from '../client/segment-context.ts';
+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 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, type ManifestLoader } from './safe-load.ts';
+import { loadFallbackModule } from './pipeline-helpers.ts';
+import { replaceOutermostSegmentOutlet } from './route-element-helpers.ts';
 
-// ─── Types ────────────────────────────────────────────────────────────────
+/**
+ * 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];
+}
 
-/** Head element for client-side metadata updates. */
-export interface HeadElement {
-  tag: string;
-  content?: string;
-  attrs?: Record<string, string | null>;
+/**
+ * Thrown when a matched route has no page component in its leaf segment.
+ * The pipeline catches this and renders the custom 404 page.
+ */
+export class NoPageComponentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NoPageComponentError';
+  }
 }
 
+// ─── Types ────────────────────────────────────────────────────────────────
+
 /** Layout entry with component and segment. */
 export interface LayoutComponentEntry {
   component: (...args: unknown[]) => unknown;
@@ -51,10 +94,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;
-  /** Resolved head elements for metadata. */
-  headElements: HeadElement[];
+  /**
+   * 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. */
@@ -68,20 +113,73 @@ export interface RouteElementResult {
    * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
    */
   skippedSegments: string[];
+  /**
+   * 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[];
 }
 
+// ─── Wrapping Helpers ────────────────────────────────────────────────────
+
 /**
- * Wraps a DenySignal or RedirectSignal with the layout components loaded
- * so far, enabling the caller to render deny pages inside the layout shell.
+ * 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.
  */
-export class RouteSignalWithContext extends Error {
-  constructor(
-    public readonly signal: DenySignal | RedirectSignal,
-    public readonly layoutComponents: LayoutComponentEntry[],
-    public readonly segments: ManifestSegmentNode[]
-  ) {
-    super(signal.message);
+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;
+}
+
+/**
+ * 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 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 ──────────────────────────────────────────────────────────────
@@ -89,223 +187,124 @@ export class RouteSignalWithContext extends Error {
 /**
  * Build a React element tree from a matched route.
  *
- * Loads modules, runs access checks, resolves metadata, and constructs
- * the element tree. DenySignal and RedirectSignal propagate to the caller
- * for HTTP-level handling.
+ * 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).
+ *
+ * For passing segments, AccessGate re-runs access during render so that
+ * React.cache is populated for layout dedup (TIM-662). For denied
+ * segments, the pre-computed verdict is replayed — no re-execution,
+ * no metadata side effects, no head leak (TIM-1027).
  */
 export async function buildRouteElement(
   req: Request,
   match: RouteMatch,
   interception?: InterceptionContext,
-  clientStateTree?: Set<string> | null
+  clientStateTree?: ClientStateTree | null,
+  metadataRouteHashes?: Record<string, string>
 ): Promise<RouteElementResult> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
-
-  // Params are passed as a Promise to match Next.js 15+ convention.
-  const paramsPromise = Promise.resolve(match.params);
-
-  // Load all modules along the segment chain
-  const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
-  const layoutComponents: LayoutComponentEntry[] = [];
-  let PageComponent: ((...args: unknown[]) => unknown) | null = null;
-  let deferSuspenseFor = 0;
-
+  const segments = match.segments;
+  // Status and error pages the boundaries need: a load failure is reported,
+  // and the boundary is skipped rather than failing the render.
+  const loadBoundaryModule = (file: ManifestLoader) => loadFallbackModule(file, req, segments);
+
+  // ── 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.
+  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)"
+  // 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,
+  // 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 segment = segments[i];
-    const isLeaf = i === segments.length - 1;
-
-    // Load layout
-    if (segment.layout) {
-      const mod = (await segment.layout.load()) as Record<string, unknown>;
-      if (mod.default) {
-        layoutComponents.push({
-          component: mod.default as (...args: unknown[]) => unknown,
-          segment,
-        });
-      }
-      // Reject legacy generateMetadata export — use `export async function metadata()` instead
-      if ('generateMetadata' in mod) {
-        const filePath = segment.layout.filePath ?? segment.urlPath;
-        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({ params }) { ... }`
-        );
-      }
-      // Unified metadata export: static object or async function
-      if (typeof mod.metadata === 'function') {
-        type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
-        const generated = await withSpan(
-          'timber.metadata',
-          { 'timber.segment': segment.segmentName ?? segment.urlPath },
-          () => (mod.metadata as MetadataFn)({ params: paramsPromise })
-        );
-        if (generated) {
-          metadataEntries.push({ metadata: generated, isPage: false });
-        }
-      } else if (mod.metadata) {
-        metadataEntries.push({ metadata: mod.metadata as Metadata, isPage: false });
-      }
-      // deferSuspenseFor hold window — max across all segments
-      if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > deferSuspenseFor) {
-        deferSuspenseFor = mod.deferSuspenseFor;
-      }
-    }
-
-    // Load page (leaf segment only)
-    if (isLeaf && segment.page) {
-      // Load and apply search-params.ts definition before rendering so
-      // searchParams() from @timber-js/app/server returns parsed typed values.
-      if (segment.searchParams) {
-        const spMod = (await segment.searchParams.load()) as {
-          default?: SearchParamsDefinition<Record<string, unknown>>;
-        };
-        if (spMod.default) {
-          const rawSearchParams = new URL(req.url).searchParams;
-          const parsed = spMod.default.parse(rawSearchParams);
-          setParsedSearchParams(parsed);
-        }
-      }
-
-      const mod = (await segment.page.load()) as Record<string, unknown>;
-      if (mod.default) {
-        PageComponent = mod.default as (...args: unknown[]) => unknown;
-      }
-      // Reject legacy generateMetadata export — use `export async function metadata()` instead
-      if ('generateMetadata' in mod) {
-        const filePath = segment.page.filePath ?? segment.urlPath;
-        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({ params }) { ... }`
-        );
-      }
-      // Unified metadata export: static object or async function
-      if (typeof mod.metadata === 'function') {
-        type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
-        const generated = await withSpan(
-          'timber.metadata',
-          { 'timber.segment': segment.segmentName ?? segment.urlPath },
-          () => (mod.metadata as MetadataFn)({ params: paramsPromise })
-        );
-        if (generated) {
-          metadataEntries.push({ metadata: generated, isPage: true });
-        }
-      } else if (mod.metadata) {
-        metadataEntries.push({ metadata: mod.metadata as Metadata, isPage: true });
-      }
-      // deferSuspenseFor hold window — max across all segments
-      if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > deferSuspenseFor) {
-        deferSuspenseFor = mod.deferSuspenseFor;
-      }
-    }
-  }
-
-  if (!PageComponent) {
-    throw new Error(`No page component found for route: ${new URL(req.url).pathname}`);
-  }
-
-  // Run access.ts checks before rendering — top-down through the segment chain.
-  // Verdicts are stored so AccessGate can replay them synchronously during
-  // render, avoiding duplicate execution and Suspense timing issues.
-  // DenySignal and RedirectSignal are wrapped with layout context so the caller
-  // can render deny pages inside the layout shell.
-  // See design/04-authorization.md §"access.ts Runs on Every Navigation".
-  const accessVerdicts = new Map<number, 'pass' | DenySignal | RedirectSignal>();
-
-  for (let si = 0; si < segments.length; si++) {
-    const segment = segments[si];
-    if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
-      if (accessFn) {
-        try {
-          await withSpan(
-            'timber.access',
-            { 'timber.segment': segment.segmentName ?? 'unknown' },
-            async () => {
-              try {
-                await accessFn({ params: match.params, searchParams: {} });
-                await setSpanAttribute('timber.result', 'pass');
-                accessVerdicts.set(si, 'pass');
-              } catch (error) {
-                if (error instanceof DenySignal) {
-                  await setSpanAttribute('timber.result', 'deny');
-                  await setSpanAttribute('timber.deny_status', error.status);
-                  if (error.sourceFile) {
-                    await setSpanAttribute('timber.deny_file', error.sourceFile);
-                  }
-                  accessVerdicts.set(si, error);
-                } else if (error instanceof RedirectSignal) {
-                  await setSpanAttribute('timber.result', 'redirect');
-                  accessVerdicts.set(si, error);
-                }
-                throw error;
-              }
-            }
-          );
-        } catch (error) {
-          if (error instanceof DenySignal || error instanceof RedirectSignal) {
-            throw new RouteSignalWithContext(error, layoutComponents, segments);
-          }
-          throw error;
-        }
-      }
-    }
-  }
-
-  // Resolve metadata
-  const resolvedMetadata = resolveMetadata(metadataEntries);
-  const headElements = renderMetadataToElements(resolvedMetadata);
-
-  // Auto-link metadata route files (icon, apple-icon, manifest) from segments.
-  // See design/16-metadata.md §"Auto-Linking"
-  for (const segment of segments) {
-    if (!segment.metadataRoutes) continue;
-    for (const baseName of Object.keys(segment.metadataRoutes)) {
-      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
-      if (!convention) continue;
-      // Non-nestable routes only auto-link from root
-      if (!convention.nestable && segment.urlPath !== '/') continue;
-      // Build the href: segment urlPath + serve path
-      const prefix = segment.urlPath === '/' ? '' : segment.urlPath;
-      const href = `${prefix}/${convention.servePath}`;
-      const autoLink = getMetadataRouteAutoLink(convention.type, href);
-      if (autoLink) {
-        const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
-        if (autoLink.type) attrs.type = autoLink.type;
-        headElements.push({ tag: 'link', attrs } as MetadataHeadElement);
-      }
+    const chain = await buildDenyPageChain(segments, i, segmentKeys, req);
+    if (chain.length > 0) {
+      denyPageChains.set(i, chain);
     }
   }
 
   // Build element tree: page wrapped in layouts (innermost to outermost)
-  const h = createElement as (...args: unknown[]) => React.ReactElement;
-
-  // Wrap the page component in an OTEL span
-  const TracedPage = async (props: Record<string, unknown>) => {
-    return withSpan(
-      'timber.page',
-      { 'timber.route': match.segments[match.segments.length - 1]?.urlPath ?? '/' },
-      () => (PageComponent as (props: Record<string, unknown>) => unknown)(props)
-    );
-  };
+  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
+  // them as async functions and catches DenySignal — rendering the deny
+  // page in-tree instead of throwing into React Flight. This eliminates
+  // the second render pass for deny pages. See TIM-666.
+  //
+  // Client reference pages ('use client') can't call deny() (server-only),
+  // so they go through createElement normally — no wrapper needed.
+  const leafIndex = segments.length - 1;
+  const leafDenyPages = denyPageChains.get(leafIndex);
+  let element: React.ReactElement;
+  if (isClientReference(PageComponent)) {
+    element = h(PageComponent, {});
+  } else if (leafDenyPages && leafDenyPages.length > 0) {
+    element = h(PageDenyBoundary, {
+      Page: PageComponent,
+      route: match.segments[leafIndex]?.urlPath ?? '/',
+      denyPages: leafDenyPages,
+      segmentKey: segmentKeys[leafIndex],
+    });
+  } else {
+    // Server component page WITHOUT deny page chain — trace only
+    const TracedPage = async (props: Record<string, unknown>) => {
+      return withSpan(
+        'timber.page',
+        { 'timber.route': match.segments[leafIndex]?.urlPath ?? '/' },
+        () => (PageComponent as (props: Record<string, unknown>) => unknown)(props)
+      );
+    };
+    element = h(TracedPage, {});
+  }
 
-  let element = h(TracedPage, {
-    params: paramsPromise,
-    searchParams: {},
-  });
+  // Place MetadataHead as a SIBLING of the page, not a wrapper. React
+  // renders siblings concurrently — the page starts immediately while
+  // MetadataHead awaits metadata promises. Float hoists the head
+  // elements to <head> regardless of tree position. Both resolve before
+  // onShellReady (outside Suspense), but they overlap.
+  // Placed at the page level so metadata is always re-rendered on SPA
+  // navigation (never skipped by segment tree diffing).
+  // See TIM-1363, TIM-1367, design/16-metadata.md.
+  element = h(
+    Fragment,
+    null,
+    h(MetadataHead, {
+      segments,
+      rawSegmentParams: match.rawSegmentParams,
+      requestUrl: req.url,
+      metadataRouteHashes,
+    }),
+    element
+  );
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -316,147 +315,307 @@ export async function buildRouteElement(
   // The client uses this to merge the partial payload with its cached segments.
   const skippedSegments: string[] = [];
 
-  // Wrap from innermost (leaf) to outermost (root), processing every
-  // segment in the chain. Each segment may contribute:
-  //   1. Error boundaries (status files + error.tsx)
-  //   2. Layout component — wraps children + parallel slots
-  //   3. SegmentProvider — records position for useSelectedLayoutSegment
-  //
-  // When clientStateTree is provided (from X-Timber-State-Tree header on
-  // client navigation), sync layouts the client already has are skipped.
-  // Access.ts already ran for ALL segments in the pre-render loop above.
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  //
-  // hasRenderedLayoutBelow tracks whether a non-skipped layout has been
-  // seen below the current segment. A segment can ONLY be skipped if
-  // there is a rendered layout below it — the client merger can only
-  // replace inner SegmentProviders (client component boundaries), not
-  // page content embedded in a layout's server-rendered output.
-  // Without this guard, skipping the innermost layout causes the merger
-  // to drop the layout entirely and replace it with just the page.
-  let hasRenderedLayoutBelow = false;
+  // Pre-compute the contiguous skippable prefix (top-down).
+  // 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;
+
+  // Slot caching uses key-based diffing (TIM-1370). The server computes a
+  // content key per slot and the client advertises keys for cached slots.
+  // The skip decision is a set-membership check — no departing URL needed.
+  const destinationUrl = req.url;
+  const slotSkipInfo: SlotSkipEntry[] = [];
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
     const layoutComponent = layoutBySegment.get(segment);
 
-    // Check if this segment's layout can be skipped for partial rendering.
-    // Skipped segments: no layout wrapping, no error boundaries, no slots,
-    // no AccessGate in element tree (access already ran pre-render).
-    //
-    // Additional constraints beyond shouldSkipSegment:
-    // - Must have a rendered layout below (so the merger can find an
-    //   inner SegmentProvider to splice the new content into)
-    // - Route groups are never skipped because sibling groups share the
-    //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
-    //   which would cause the wrong cached layout to be reused
-    const skip =
-      shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
-      hasRenderedLayoutBelow &&
-      segment.segmentType !== 'group';
-
-    if (skip) {
-      // Skip this segment entirely — the client uses its cached version.
-      // Access.ts already ran in the pre-render loop (security guarantee).
-      // Metadata was already resolved above (head elements are correct).
+    // Skip decision was pre-computed in the top-down prefix pass.
+    if (skippableSet.has(i)) {
       // Record for X-Timber-Skipped-Segments header (outermost first, so prepend).
-      skippedSegments.unshift(segment.urlPath);
+      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]);
+
+      // Emit slot metadata so the client's segment tree retains contentKeys
+      // for slots of skipped layouts. Without this, the client rebuilds its
+      // tree from the response and loses slot keys it can't advertise next time.
+      emitSlotInfoForSkippedLayout(segment, segmentKeys[i], match, destinationUrl, slotSkipInfo);
+
+      // 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();
+      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
+      // 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. 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,
+            segment,
+            segmentKey: segmentKeys[i],
+            segmentIndex: i,
+            skippedSegment: true,
+          },
+          h
+        );
+      }
+
       continue;
     }
 
-    // This segment is rendered — mark that future (outer) segments have
-    // a rendered layout below them and can safely be skipped.
-    if (layoutComponent) {
-      hasRenderedLayoutBelow = true;
-    }
+    // 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();
+    element = wrapMetadataCollectors(element, segmentMetadata, h);
 
     // Wrap with error boundaries from this segment (inside layout).
-    element = await wrapSegmentWithErrorBoundaries(segment, element, h);
-
-    // Wrap in AccessGate if segment has access.ts.
-    // Pass the pre-computed verdict so AccessGate replays it synchronously
-    // instead of re-calling accessFn (dedup + Suspense immunity).
-    if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
-      if (accessFn) {
-        element = h(AccessGate, {
-          accessFn,
-          params: match.params,
-          searchParams: {},
-          segmentName: segment.segmentName,
-          verdict: accessVerdicts.get(i),
+    // 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.
+    // `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: loadBoundaryModule,
+      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
+    // at the AccessGate level, wrapped by PARENT layouts only.
+    // 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. 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 = segmentTreePaths[i];
+      const slotProps = await resolveSlotProps({
+        segment,
+        segmentId,
+        match,
+        h,
+        interception,
+        parentTreePath,
+        req,
+        clientStateTree: clientStateTree ?? null,
+        slotSkipInfo,
+      });
+
+      const segmentPath = computeLayoutSegmentPath(segments, i, match);
+      const parallelRouteKeys = Object.keys(segment.slots ?? {});
+
+      // Build the layout element.
+      // Keep the descendant tree in a SERVER layout's children prop. Moving it
+      // to a client-provider prop above that layout makes React Flight evaluate
+      // and serialize it independently, even when the layout denies access or
+      // deliberately omits children. Client layouts cannot provide this
+      // containment: Flight must serialize their server-valued children props
+      // before they execute in the browser. Convention lint warns users not to
+      // treat a client layout as an authorization or data-hiding boundary.
+      let layoutElement: React.ReactElement;
+      if (isClientReference(layoutComponent)) {
+        layoutElement = h(layoutComponent, {
+          ...slotProps,
+          children: element,
+        });
+      } else {
+        // Server component layout — wrap with OTEL tracing AND DenySignal
+        // catching. If the layout calls deny(), the signal is caught here
+        // and the matching deny page renders in-tree (same pattern as
+        // AccessGate and PageDenyBoundary). Without this, DenySignal
+        // escapes to React Flight onError and triggers the re-render
+        // fallback path. See TIM-668, design/04-authorization.md.
+        const layoutComponentRef = layoutComponent;
+        const layoutDenyPages = denyPageChains.get(i);
+        const TracedLayout = async (props: Record<string, unknown>) => {
+          try {
+            return await withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
+              (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
+            );
+          } 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 (isDenySignal(error)) {
+              setFirstDeniedSegmentIndex(i);
+              if (layoutDenyPages) {
+                return handleCaughtDeny(layoutDenyPages, error, segmentId);
+              }
+            }
+            throw error;
+          }
+        };
+        layoutElement = h(TracedLayout, {
+          ...slotProps,
           children: element,
         });
-      }
-    }
 
-    // Wrap with layout if this segment has one — traced with OTEL span
-    if (layoutComponent) {
-      // Resolve parallel slots for this layout
-      const slotProps: Record<string, unknown> = {};
-      const slotEntries = Object.entries(segment.slots ?? {});
-      for (const [slotName, slotNode] of slotEntries) {
-        slotProps[slotName] = await resolveSlotElement(
-          slotNode as ManifestSegmentNode,
-          match,
-          paramsPromise,
-          h,
-          interception
-        );
+        // 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: loadBoundaryModule,
+          createElement: h,
+          errorBoundaryComponent: TimberErrorBoundary,
+          segmentKey: segmentId,
+          denyOnly: true,
+        });
       }
 
-      const segmentPath = segment.urlPath.split('/');
-      const parallelRouteKeys = Object.keys(segment.slots ?? {});
-
-      // Wrap the layout component in an OTEL span.
-      // For route groups, urlPath is "/" (groups don't add URL segments), so
-      // include the directory name to distinguish e.g. "layout /(pre-release)"
-      // from the root "layout /".
-      const segmentForSpan = segment;
-      const layoutComponentForSpan = layoutComponent;
-      const segmentLabel =
-        segmentForSpan.segmentType === 'group'
-          ? `${segmentForSpan.urlPath === '/' ? '' : segmentForSpan.urlPath}/${segmentForSpan.segmentName}`
-          : segmentForSpan.urlPath;
-      const TracedLayout = async (props: Record<string, unknown>) => {
-        return withSpan('timber.layout', { 'timber.segment': segmentLabel }, () =>
-          (layoutComponentForSpan as (props: Record<string, unknown>) => unknown)(props)
-        );
-      };
-
-      // segmentId uniquely identifies this segment for client-side element
-      // caching. For route groups, urlPath is shared with the parent (both "/"),
-      // so we include the group name to distinguish them. Without this, the
-      // segment merger's element cache would conflate root and group elements.
-      const segmentId =
-        segment.segmentType === 'group'
-          ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
-          : segment.urlPath;
-
-      element = h(SegmentProvider, {
+      const segmentProviderElement = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,
         parallelRouteKeys,
-        children: h(TracedLayout, {
-          ...slotProps,
-          params: paramsPromise,
-          searchParams: {},
-          children: element,
-        }),
+        children: layoutElement,
+      });
+
+      element = h(SegmentOutlet, {
+        segmentPath: segmentId,
+        children: segmentProviderElement,
       });
+
+      // Track the SegmentProvider for the outermost rendered layout.
+      // On partial navigation (segments skipped above), the client already
+      // has a SegmentOutlet mounted at this position. Sending another one
+      // in the payload causes double-wrapping and infinite context recursion.
+      // We'll strip the outermost SegmentOutlet after the loop.
+      outermostSegmentProvider = segmentProviderElement;
     }
+
+    // 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.
+    const accessFn = accessFns[i];
+    if (accessFn) {
+      element = wrapAccessGate(
+        element,
+        {
+          accessFn,
+          segment,
+          segmentKey: segmentKeys[i],
+          segmentIndex: i,
+          denyPages: denyPageChains.get(i),
+        },
+        h
+      );
+    }
+  }
+
+  // On partial navigation (some segments skipped), the client already has a
+  // SegmentOutlet mounted at the outermost non-skipped segment's position.
+  // Sending another SegmentOutlet in the payload causes double-wrapping —
+  // the inner outlet reads the same context update and recurses infinitely.
+  // Replace the outermost SegmentOutlet with just its SegmentProvider child.
+  if (skippedSegments.length > 0 && outermostSegmentProvider) {
+    element = replaceOutermostSegmentOutlet(element, outermostSegmentProvider);
   }
 
+  // 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
+  // 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,
-    headElements: headElements as HeadElement[],
+    payload,
     layoutComponents,
     segments,
     deferSuspenseFor,
     skippedSegments,
+    slotSkipInfo,
+    leafDenyChain: leafDenyPages,
   };
 }