@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.171

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

@@ -6,43 +6,159 @@
  * 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 { randomUUID } from 'node:crypto';
 
-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 {
+  METADATA_ROUTE_CONVENTIONS,
+  getMetadataRouteAutoLink,
+  resolveServePathForFile,
+} from './metadata-routes.js';
+
+// In dev mode, use a per-startup nonce for metadata route cache busting
+// instead of per-file content hashes (avoids rehashing on every request).
+let _devNonce: string | undefined;
+function getDevNonce(): string {
+  _devNonce ??= randomUUID().slice(0, 8);
+  return _devNonce;
+}
 import { DenySignal, RedirectSignal } from './primitives.js';
 import { AccessGate } from './access-gate.js';
+import { requestContextAls } from './als-registry.js';
+import {
+  PageDenyBoundary,
+  buildDenyPageChain,
+  renderMatchingDenyPage,
+  setDenyStatus,
+} from './deny-boundary.js';
+import type { DenyPageEntry } from './deny-boundary.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 { SegmentProvider } from '../client/segment-context.js';
+import { SegmentOutlet } from '../client/segment-outlet.js';
+import { ChildSegmentOutlet } from '../client/child-segment-outlet.js';
+import { ChildSegmentProvider } from '../client/child-segment-provider.js';
+
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
-import { shouldSkipSegment } from './state-tree-diff.js';
+import { shouldSkipSegment, computeSegmentKeys } from './state-tree-diff.js';
+import type { HeadElement } from './metadata.js';
 
-// ─── Types ────────────────────────────────────────────────────────────────
+/**
+ * Convert HeadElement descriptors to React elements for Float hoisting.
+ *
+ * React 19 Float hoists <title>, <meta>, and <link> rendered anywhere in
+ * the tree into <head> during SSR, and manages them in document.head
+ * during client-side rendering. This replaces the X-Timber-Head header
+ * side-channel and the imperative client DOM applier.
+ */
+export function headElementsToReact(elements: HeadElement[]): React.ReactElement {
+  const children: React.ReactElement[] = [];
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (el.tag === 'title' && el.content !== undefined) {
+      children.push(createElement('title', { key: `t${i}` }, el.content));
+    } else if (el.attrs) {
+      children.push(createElement(el.tag, { key: `h${i}`, ...el.attrs }));
+    }
+  }
+  return createElement(Fragment, null, ...children);
+}
+import { loadModule } from './safe-load.js';
 
-/** Head element for client-side metadata updates. */
-export interface HeadElement {
-  tag: string;
-  content?: string;
-  attrs?: Record<string, string | null>;
+/**
+ * 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 wraps outside SegmentOutlet — recurse through it.
+  const props = element.props as Record<string, unknown>;
+  if (element.type === AccessGate && 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');
+
+/**
+ * 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.
+ */
+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 a defineSegmentParams 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;
@@ -53,8 +169,6 @@ export interface LayoutComponentEntry {
 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[];
   /** Layout components loaded along the segment chain. */
   layoutComponents: LayoutComponentEntry[];
   /** Segments from the route match. */
@@ -68,46 +182,142 @@ 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>;
 }
 
+// ─── Module Processing Helpers ─────────────────────────────────────────────
+
 /**
- * Wraps a DenySignal or RedirectSignal with the layout components loaded
- * so far, enabling the caller to render deny pages inside the layout shell.
+ * Reject the legacy `generateMetadata` export with a helpful migration message.
+ * Throws if the module exports `generateMetadata` instead of `metadata`.
  */
-export class RouteSignalWithContext extends Error {
-  constructor(
-    public readonly signal: DenySignal | RedirectSignal,
-    public readonly layoutComponents: LayoutComponentEntry[],
-    public readonly segments: ManifestSegmentNode[]
-  ) {
-    super(signal.message);
+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() { ... }`
+    );
   }
 }
 
+/**
+ * Extract and resolve metadata from a module (layout or page).
+ * Handles both static metadata objects and async metadata functions.
+ * Returns the resolved Metadata, or null if none exported.
+ *
+ * Metadata functions no longer receive { params } — they access params
+ * via getSegmentParams() from ALS, same as page/layout components.
+ */
+async function extractMetadata(
+  mod: Record<string, unknown>,
+  segment: ManifestSegmentNode
+): Promise<Metadata | null> {
+  if (typeof mod.metadata === 'function') {
+    type MetadataFn = () => Promise<Metadata>;
+    return (
+      (await withSpan(
+        'timber.metadata',
+        { 'timber.segment': segment.segmentName ?? segment.urlPath },
+        () => (mod.metadata as MetadataFn)()
+      )) ?? null
+    );
+  }
+  if (mod.metadata) {
+    return mod.metadata as Metadata;
+  }
+  return null;
+}
+
+/**
+ * Extract `deferSuspenseFor` from a module and return the maximum
+ * of the current value and the module's value.
+ */
+function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
+  if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
+    return mod.deferSuspenseFor;
+  }
+  return current;
+}
+
 // ─── Builder ──────────────────────────────────────────────────────────────
 
 /**
  * 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?: Set<string> | null,
+  metadataRouteHashes?: Record<string, string>
 ): Promise<RouteElementResult> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
-  // Params are passed as a Promise to match Next.js 15+ convention.
-  const paramsPromise = Promise.resolve(match.params);
+  // ── Access pre-pass ──────────────────────────────────────────────────
+  // Run access checks eagerly to determine which segments are denied.
+  // This gates metadata() resolution: denied segments' metadata functions
+  // are never called, preventing unauthorized side effects (DB queries)
+  // and metadata content leaking into the <head> of denied responses.
+  //
+  // Verdicts are passed to AccessGate for synchronous replay (DenySignal
+  // renders the deny page in-tree; RedirectSignal propagates). For PASSING
+  // segments, no verdict is passed — AccessGate re-runs access during
+  // renderToReadableStream to populate React.cache for layout dedup.
+  //
+  // See TIM-1027, design/04-authorization.md, design/13-security.md.
+  const accessVerdicts = new Map<number, DenySignal | RedirectSignal>();
+  let firstDeniedIndex = Infinity;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (!segment.access || i >= firstDeniedIndex) continue;
+
+    try {
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => Promise<void>) | undefined;
+      if (accessFn) {
+        await withSpan(
+          'timber.access.pre',
+          { 'timber.segment': segment.segmentName ?? 'unknown' },
+          () => accessFn()
+        );
+      }
+    } catch (error: unknown) {
+      if (error instanceof DenySignal || error instanceof RedirectSignal) {
+        accessVerdicts.set(i, error);
+        firstDeniedIndex = i;
+      } else {
+        throw error;
+      }
+    }
+  }
 
-  // Load all modules along the segment chain
+  // ── Module loading + metadata resolution ─────────────────────────────
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
   const layoutComponents: LayoutComponentEntry[] = [];
   let PageComponent: ((...args: unknown[]) => unknown) | null = null;
@@ -116,196 +326,226 @@ export async function buildRouteElement(
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
+    const isDenied = i >= firstDeniedIndex;
 
     // Load layout
     if (segment.layout) {
-      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 });
+
+      // Param coercion is handled in the pipeline (Stage 2c) before
+      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
+
+      rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
+      if (!isDenied) {
+        const layoutMetadata = await extractMetadata(mod, segment);
+        if (layoutMetadata) {
+          metadataEntries.push({ metadata: layoutMetadata, isPage: false });
         }
-      } 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;
       }
+      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);
+
+      // Param coercion is handled in the pipeline (Stage 2c) before
+      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
 
-      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 });
+      rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
+      if (!isDenied) {
+        const pageMetadata = await extractMetadata(mod, segment);
+        if (pageMetadata) {
+          metadataEntries.push({ metadata: pageMetadata, 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;
       }
+      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
   }
 
   if (!PageComponent) {
-    throw new Error(`No page component found for route: ${new URL(req.url).pathname}`);
+    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}`
+    );
   }
 
-  // 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;
-        }
-      }
+  // Build deny page fallback chains for each segment position.
+  // When AccessGate or PageDenyBoundary catches a DenySignal, they render
+  // the matching deny page in-tree instead of throwing into React Flight.
+  // The chain walks from the current segment outward to root, collecting
+  // status-code files (403.tsx → 4xx.tsx → error.tsx) in fallback order.
+  // See TIM-666.
+  const denyPageChains = new Map<number, DenyPageEntry[]>();
+  for (let i = 0; i < segments.length; i++) {
+    const chain = await buildDenyPageChain(segments, i);
+    if (chain.length > 0) {
+      denyPageChains.set(i, chain);
     }
   }
 
-  // Resolve metadata
+  // Resolve metadata and convert to React elements that React 19 Float
+  // hoists into <head> during both SSR and client rendering. This replaces
+  // the previous HeadElement descriptor system (string splice for SSR,
+  // X-Timber-Head header for RSC nav, imperative DOM updates on client).
+  // React manages <title>/<meta>/<link> lifecycle across navigations.
+  // See design/16-metadata.md, TIM-1151.
   const resolvedMetadata = resolveMetadata(metadataEntries);
   const headElements = renderMetadataToElements(resolvedMetadata);
 
-  // Auto-link metadata route files (icon, apple-icon, manifest) from segments.
+  // Auto-link metadata route files (icon, apple-icon, manifest, opengraph-image).
+  // opengraph-image emits both og:image and twitter:image (no separate twitter-image convention).
+  // Skip OG auto-linking when the user already declared images in metadata.
   // See design/16-metadata.md §"Auto-Linking"
-  for (const segment of segments) {
+  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);
+  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);
+  const requestUrl = new URL(req.url);
+  const requestPathname = requestUrl.pathname;
+  // In dev mode, use the request origin so OG URLs resolve to localhost.
+  // In production, use metadataBase (the canonical domain).
+  const ogBase =
+    process.env.NODE_ENV !== 'production'
+      ? new URL(requestUrl.origin)
+      : resolvedMetadata.metadataBase;
+
+  for (let si = 0; si < segments.length; si++) {
+    const segment = segments[si];
     if (!segment.metadataRoutes) continue;
+    // Skip auto-linking for denied segments — same gate as metadata().
+    if (si >= firstDeniedIndex) 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);
+      // Skip auto-linking entirely if user declared openGraph.images (covers both og + twitter)
+      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;
+      // Build the href using the actual request path (not the pattern with [param]).
+      // For nestable routes, the metadata route sits under the same resolved path
+      // as the page. For root-only routes, use '/'.
+      const resolvedPrefix = convention.nestable
+        ? requestPathname === '/'
+          ? ''
+          : requestPathname
+        : '';
+      const metaFile = segment.metadataRoutes[baseName];
+      const fileServePath = metaFile?.filePath
+        ? resolveServePathForFile(baseName, metaFile.filePath)
+        : convention.serveExtension
+          ? `${convention.servePath}.${convention.serveExtension}`
+          : convention.servePath;
+      let href = `${resolvedPrefix}/${fileServePath}`;
+      // Append cache-bust query param for image metadata routes
+      if (convention.type === 'opengraph-image') {
+        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;
+        const cacheBust = fileHash ?? getDevNonce();
+        href = `${href}?${cacheBust}`;
+      }
+      // Resolve to absolute URL for og:image/twitter:image (social crawlers need full URLs)
+      if (ogBase && convention.type === 'opengraph-image') {
+        href = new URL(href, ogBase).toString();
+      }
+      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {
+        // Skip auto-linked twitter:image when user declared twitter.images
+        if (
+          hasUserTwitterImage &&
+          autoLink.tag === 'meta' &&
+          'name' in autoLink &&
+          autoLink.name === 'twitter:image'
+        )
+          continue;
+        if (autoLink.tag === 'link') {
+          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
+          if (autoLink.type) attrs.type = autoLink.type;
+          headElements.push({ tag: 'link', attrs });
+        } else {
+          const attrs: Record<string, string> = { content: autoLink.content };
+          if (autoLink.property) attrs.property = autoLink.property;
+          if (autoLink.name) attrs.name = autoLink.name;
+          headElements.push({ tag: 'meta', attrs });
+        }
       }
     }
   }
 
+  // Convert HeadElement descriptors to React elements for Float hoisting.
+  // Placed at the page segment level so they're always re-rendered on
+  // SPA navigation (sync layouts may be skipped by segment tree diffing).
+  const metadataElement = headElementsToReact(headElements);
+
   // Build element tree: page wrapped in layouts (innermost to outermost)
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // 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).
+  // ChildSegmentProvider 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,
+      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, {});
+  }
+
+  // Wrap page + metadata in a Fragment so Float-hoisted elements are at
+  // the page segment level (always re-rendered, never skipped by segment
+  // tree diffing). React 19 Float hoists the <title>/<meta>/<link>
+  // children into <head> regardless of where they appear in the tree.
+  element = h(Fragment, null, metadataElement, element);
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -316,147 +556,290 @@ 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
+  // Compute state-tree keys for all segments. Route groups accumulate
+  // ancestor group names for globally unique keys (e.g., "/(a)/(shared)"
+  // instead of just "/(shared)"). This is the single key computation —
+  // the same keys are used for skip decisions, SegmentOutlet props, and
+  // the X-Timber-Segments header (via buildSegmentInfo).
+  const segmentKeys = computeSegmentKeys(segments);
+
+  // Pre-compute the contiguous skippable prefix (top-down).
   //
-  // 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]);
+
+      // Never skip denied segments — their AccessGate must render the
+      // deny page, not reuse the client's cached (passing) layout.
+      if (i >= firstDeniedIndex) break;
+
+      if (shouldSkipSegment(segmentKeys[i], layoutComponent, isLeaf, clientStateTree)) {
+        skippableSet.add(i);
+      } else if (layoutComponent) {
+        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();
+      }
+    }
+  }
+
+  let outermostSegmentProvider: React.ReactElement | null = null;
 
   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);
-      continue;
-    }
+      skippedSegments.unshift(segmentKeys[i]);
+
+      // 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).
+      if (segment.access) {
+        const accessMod = await loadModule(segment.access);
+        const accessFn = accessMod.default as (() => unknown) | undefined;
+        if (accessFn) {
+          const verdict = accessVerdicts.get(i);
+          element = h(AccessGate, {
+            accessFn,
+            segmentName: segment.segmentName,
+            denyPages: denyPageChains.get(i),
+            ...(verdict ? { verdict } : {}),
+            children: element,
+          });
+        }
+      }
 
-    // This segment is rendered — mark that future (outer) segments have
-    // a rendered layout below them and can safely be skipped.
-    if (layoutComponent) {
-      hasRenderedLayoutBelow = true;
+      continue;
     }
 
     // Wrap with error boundaries from this segment (inside layout).
+    // Keep ALL error boundaries (including 4xx) — they're the safety net for
+    // DenySignal from nested server components that escape AccessGate/PageDenyBoundary
+    // try/catch. Status-code files must be 'use client' TSX or MDX to serialize
+    // as error boundary fallbacks. See TIM-666.
     element = await wrapSegmentWithErrorBoundaries(segment, element, h);
 
-    // 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),
-          children: element,
-        });
-      }
-    }
-
-    // Wrap with layout if this segment has one — traced with OTEL span
+    // 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
+      // Resolve parallel slots for this layout.
+      // Compute the parent tree path so slots can build their full
+      // segment path for per-slot param storage in ALS.
+      const parentTreePath =
+        '/' +
+        segments
+          .slice(0, i + 1)
+          .map((s) => s.segmentName)
+          .filter(Boolean)
+          .join('/');
       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
+          interception,
+          parentTreePath
         );
       }
 
-      const segmentPath = segment.urlPath.split('/');
+      // '/'.split('/') → ['', ''] (length 2), but root should be [''] (length 1).
+      // The extra empty string makes useSelectedLayoutSegment skip the first URL segment.
+      const rawPath = segment.urlPath.split('/');
+      const segmentPath = rawPath.length === 2 && rawPath[1] === '' ? [''] : rawPath;
       const 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 segmentId = segmentKeys[i];
+
+      // Build the layout element.
+      // Layouts receive <ChildSegmentOutlet /> as children — a stable client
+      // reference — instead of the varying inner content. The actual child
+      // content is provided via ChildSegmentProvider above the layout.
+      // This makes layout cache.component hits possible: the cached payload
+      // contains a deterministic children reference, not varying content.
+      // See design/45-cache-lifetimes.md §Layout Propagation.
+      const childOutlet = h(ChildSegmentOutlet, {});
+      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) {
+            if (error instanceof DenySignal && layoutDenyPages) {
+              const denyElement = renderMatchingDenyPage(layoutDenyPages, error.status, error.data);
+              if (denyElement) {
+                setDenyStatus(error.status);
+                return denyElement;
+              }
+            }
+            // Non-deny errors (RedirectSignal, runtime errors) propagate normally
+            // to onError — signalDetected / renderError handling covers those.
+            throw error;
+          } finally {
+            onLayoutSettled?.();
+          }
+        };
+        layoutElement = h(TracedLayout, {
+          ...slotProps,
+          children: childOutlet,
+        });
+      }
+
+      // Wrap the layout in ChildSegmentProvider so ChildSegmentOutlet
+      // (inside the layout's children) can read the actual child content.
+      layoutElement = h(ChildSegmentProvider, {
+        childContent: element,
+        children: layoutElement,
+      });
+
+      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.
+    // If access denies, the deny page renders here — the layout above
+    // never executes. Parent layouts (from outer iterations) form the shell.
+    // See TIM-662, TIM-666, design/04-authorization.md §"Access Failure".
+    if (segment.access) {
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => unknown) | undefined;
+      if (accessFn) {
+        // Pass verdict for denied/redirected segments so AccessGate replays
+        // without re-execution. Passing segments omit verdict so AccessGate
+        // re-runs access during render for React.cache population.
+        const verdict = accessVerdicts.get(i);
+        element = h(AccessGate, {
+          accessFn,
+          segmentName: segment.segmentName,
+          denyPages: denyPageChains.get(i),
+          ...(verdict ? { verdict } : {}),
+          children: element,
+        });
+      }
+    }
+  }
+
+  // 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);
+  }
+
+  // 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]);
   }
 
   return {
     element,
-    headElements: headElements as HeadElement[],
     layoutComponents,
     segments,
     deferSuspenseFor,
     skippedSegments,
+    shellSettled,
   };
 }