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

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

@@ -6,43 +6,157 @@
  * 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 { createElement, Fragment } from 'react';
 
-import { withSpan, setSpanAttribute } from './tracing.js';
+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 { 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 { MetadataCollector, MetadataHead } from './metadata-collector.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 { requestContextAls } from './als-registry.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,
+  publishSlotSegmentParams,
+  emitSlotInfoForSkippedLayout,
+  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 } from './state-tree-diff.js';
+import { shouldSkipSegment, type ClientStateTree } from './state-tree-diff.js';
+import { truncateSkippableForChangedSlots } from './skippable-prefix.js';
+import {
+  computeSegmentKeys,
+  computeSegmentTreePaths,
+  computeSlotKey,
+} from '../routing/segment-keys.js';
+import { setFirstDeniedSegmentIndex } from './deny-boundary.js';
+import { loadModule } from './safe-load.js';
 
-// ─── Types ────────────────────────────────────────────────────────────────
+/**
+ * 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;
+}
+
+// ─── 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');
 
-/** Head element for client-side metadata updates. */
-export interface HeadElement {
-  tag: string;
-  content?: string;
-  attrs?: Record<string, string | null>;
+/**
+ * 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.
+ *
+ * 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 &&
+    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.
+ */
+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 +165,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 +184,51 @@ 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[];
+}
+
+// ─── Module Processing Helpers ─────────────────────────────────────────────
+
+/**
+ * Reject the legacy `generateMetadata` export with a helpful migration message.
+ * Throws if the module exports `generateMetadata` instead of `metadata`.
+ */
+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() { ... }`
+    );
+  }
 }
 
 /**
- * Wraps a DenySignal or RedirectSignal with the layout components loaded
- * so far, enabling the caller to render deny pages inside the layout shell.
+ * Extract `deferSuspenseFor` from a module and return the maximum
+ * of the current value and the module's value.
  */
-export class RouteSignalWithContext extends Error {
-  constructor(
-    public readonly signal: DenySignal | RedirectSignal,
-    public readonly layoutComponents: LayoutComponentEntry[],
-    public readonly segments: ManifestSegmentNode[]
-  ) {
-    super(signal.message);
+function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
+  if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
+    return mod.deferSuspenseFor;
   }
+  return current;
 }
 
 // ─── Builder ──────────────────────────────────────────────────────────────
@@ -89,26 +236,41 @@ 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.
+ * 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.
  *
  * 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 segments = match.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.
+  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;
@@ -119,193 +281,161 @@ export async function buildRouteElement(
 
     // Load layout
     if (segment.layout) {
-      const mod = (await segment.layout.load()) as Record<string, unknown>;
+      const mod = await loadModule(segment.layout);
       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;
+
+      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) {
-      // 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 loadModule(segment.page);
 
-      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;
+      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) {
-    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;
-        }
-      }
-    }
+    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}`
+    );
   }
 
-  // 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);
-      }
+  // 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 chain = await buildDenyPageChain(segments, i, segmentKeys);
+    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)
-    );
+  // Shell settlement tracking (TIM-1045 pages, TIM-1208 layouts).
+  // SlotsProvider is 'use client', so React Flight eagerly
+  // serializes both the layout and child content as independent subtrees —
+  // the page can settle before an outer layout. We need all deny-capable
+  // components 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>[] = [];
+  let resolveShortCircuit: (() => void) | undefined;
+  const trackShellComponent = (): (() => void) => {
+    let resolve!: () => void;
+    shellPromises.push(new Promise<void>((r) => (resolve = r)));
+    return resolve;
   };
 
-  let element = h(TracedPage, {
-    params: paramsPromise,
-    searchParams: {},
-  });
+  // 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) {
+    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
+    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, {});
+  }
+
+  // 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,
+      requestUrl: req.url,
+      metadataRouteHashes,
+    }),
+    element
+  );
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -316,147 +446,375 @@ 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
+  // Pre-compute the contiguous skippable prefix (top-down).
   //
-  // 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"
+  // 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).
   //
-  // 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;
+  // 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
+    );
+  }
+
+  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();
+      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 onGateSettled = trackShellComponent();
+          element = h(AccessGate, {
+            accessFn,
+            segmentName: segment.segmentName,
+            segmentKey: segmentKeys[i],
+            segmentIndex: i,
+            skippedSegment: true,
+            onSettled: onGateSettled,
+            children: element,
+          });
+        }
+      }
+
       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();
+    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).
-    element = await wrapSegmentWithErrorBoundaries(segment, element, h);
+    // 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,
+      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,
+        destinationUrl,
+        clientStateTree: clientStateTree as ClientStateTree | null,
+        slotSkipInfo,
+      });
+
+      const segmentPath = computeLayoutSegmentPath(segments, i, match);
+      const parallelRouteKeys = Object.keys(segment.slots ?? {});
+
+      // Build the layout element.
+      // Layouts receive <SlotOutlet slot={LAYOUT_CHILDREN_SLOT} /> as
+      // children — a stable client reference — instead of the varying
+      // inner content. The actual child content is provided via
+      // SlotsProvider above the layout. Uses a reserved slot name to
+      // avoid collision with user-declared cache.component slots.
+      // See design/45-cache-lifetimes.md §Layout Propagation.
+      const childOutlet = h(SlotOutlet, { slot: LAYOUT_CHILDREN_SLOT });
+      let layoutElement: React.ReactElement;
+      if (isClientReference(layoutComponent)) {
+        layoutElement = h(layoutComponent, {
+          ...slotProps,
+          children: childOutlet,
+        });
+      } 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 hasLayoutDenyChain = !!layoutDenyPages && layoutDenyPages.length > 0;
+        const onLayoutSettled = hasLayoutDenyChain ? trackShellComponent() : undefined;
+        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 (error instanceof DenySignal) {
+              setFirstDeniedSegmentIndex(i);
+              if (layoutDenyPages) {
+                return handleCaughtDeny(layoutDenyPages, error, segmentId);
+              }
+            }
+            throw error;
+          } finally {
+            onLayoutSettled?.();
+          }
+        };
+        layoutElement = h(TracedLayout, {
+          ...slotProps,
+          children: childOutlet,
+        });
+      }
+
+      // Wrap the layout in SlotsProvider so the SlotOutlet inside the
+      // layout's children can read the actual child content.
+      layoutElement = h(SlotsProvider, {
+        values: { [LAYOUT_CHILDREN_SLOT]: element },
+        children: layoutElement,
+      });
+
+      const segmentProviderElement = h(SegmentProvider, {
+        segments: segmentPath,
+        segmentId,
+        parallelRouteKeys,
+        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 if segment has access.ts.
-    // Pass the pre-computed verdict so AccessGate replays it synchronously
-    // instead of re-calling accessFn (dedup + Suspense immunity).
+    // 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 segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
+        const onGateSettled = trackShellComponent();
         element = h(AccessGate, {
           accessFn,
-          params: match.params,
-          searchParams: {},
           segmentName: segment.segmentName,
-          verdict: accessVerdicts.get(i),
+          segmentKey: segmentKeys[i],
+          segmentIndex: i,
+          denyPages: denyPageChains.get(i),
+          onSettled: onGateSettled,
           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
-        );
-      }
-
-      const segmentPath = segment.urlPath.split('/');
-      const parallelRouteKeys = Object.keys(segment.slots ?? {});
+  // 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);
+  }
 
-      // 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, {
-        segments: segmentPath,
-        segmentId,
-        parallelRouteKeys,
-        children: h(TracedLayout, {
-          ...slotProps,
-          params: paramsPromise,
-          searchParams: {},
-          children: element,
-        }),
-      });
-    }
+  // 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]);
   }
 
+  // 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,
+    shellSettled,
+    slotSkipInfo,
   };
 }