@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/server/slot-resolver.ts

@@ -16,33 +16,75 @@
  * See design/02-rendering-pipeline.md §"Parallel Slots"
  */
 
-import { TimberErrorBoundary } from '#/client/error-boundary.js';
-import SlotErrorFallback from '#/client/slot-error-fallback.js';
+import { TimberErrorBoundary } from '../client/error-boundary.js';
+import SlotErrorFallback from '../client/slot-error-fallback.js';
 import { SlotAccessGate } from './access-gate.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import { isClientReference } from './route-element-builder.js';
+import { loadModule } from './safe-load.js';
 import type { InterceptionContext, RouteMatch } from './pipeline.js';
-import { DenySignal } from './primitives.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
+import { logRenderError } from './logger.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
+import { setSlotParams } from './request-context.js';
+import { coerceSlotParams } from './param-coercion.js';
+import { matchUrlParts } from './tree-match.js';
+import { SegmentOutlet } from '../client/segment-outlet.js';
+import { computeSlotKey, shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
+import { isStaticRequestDependent } from './request-dep.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 
+// ─── Module Loading Helpers ─────────────────────────────────────────────────
+
+/**
+ * Load a module and extract its default export as a component function.
+ * Returns undefined if no default export exists.
+ */
+async function loadComponent(loader: {
+  load: () => Promise<unknown>;
+  filePath: string;
+}): Promise<((...args: unknown[]) => unknown) | undefined> {
+  const mod = await loadModule(loader);
+  return mod.default as ((...args: unknown[]) => unknown) | undefined;
+}
+
+/**
+ * Load and render the default.tsx fallback for a slot node.
+ * Returns null if the slot has no default.tsx or it has no default export.
+ */
+async function renderDefaultFallback(
+  slotNode: ManifestSegmentNode,
+  h: CreateElementFn
+): Promise<React.ReactElement | null> {
+  if (!slotNode.default) return null;
+  const DefaultComp = await loadComponent(slotNode.default);
+  if (!DefaultComp) return null;
+  return h(DefaultComp, {});
+}
+
+// ─── Slot Element Resolution ────────────────────────────────────────────────
+
 /**
  * Resolve the element for a parallel slot.
  *
  * Finds a matching page in the slot's sub-tree for the current route.
  * Falls back to default.tsx if no match, or null if no default.
  *
- * When a match is found, the element is wrapped with:
- * 1. Error boundaries from each segment in the slot's matched chain
- * 2. Layouts from each segment in the slot's matched chain
- * 3. SlotAccessGate if the slot root has access.ts
+ * When a match is found, the element is wrapped per segment in the slot's
+ * matched chain with (innermost → outermost):
+ * 1. Error boundaries
+ * 2. Layout
+ * 3. SlotAccessGate if the segment has access.ts (gate OUTSIDE the layout,
+ *    so a denied layout never executes — see TIM-1074)
  */
 export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  parentTreePath?: string,
+  accessVerdicts?: SlotAccessVerdict[]
 ): Promise<React.ReactElement | null> {
   // When interception is active, try to match intercepting children in this
   // slot against the target pathname. If an intercepting child matches, render
@@ -54,125 +96,89 @@ export async function resolveSlotElement(
     : findSlotMatch(slotNode, match);
 
   if (slotMatch) {
-    const mod = (await slotMatch.page.load()) as Record<string, unknown>;
-    if (mod.default) {
-      const SlotPage = mod.default as (...args: unknown[]) => unknown;
+    // Store per-slot params in ALS so getSegmentParams(segmentPath) returns
+    // the slot's own param types (e.g. catch-all → string[] vs dynamic → string).
+    if (parentTreePath && Object.keys(slotMatch.slotParams).length > 0) {
+      // Build the full tree path: parent prefix + slot chain segment names.
+      const slotSuffix = slotMatch.chain
+        .map((s) => s.segmentName)
+        .filter(Boolean)
+        .join('/');
+      const prefix = parentTreePath === '/' ? '' : parentTreePath;
+      const fullSlotPath = `${prefix}/${slotSuffix}`;
+
+      // Coerce slot params through global schema codecs (same as main route).
+      const coerced = coerceSlotParams(slotMatch.chain, slotMatch.slotParams);
+      setSlotParams(fullSlotPath, coerced);
+    }
 
+    const SlotPage = await loadComponent(slotMatch.page);
+    if (SlotPage) {
       // Load default.tsx fallback for notFound() handling in the slot page.
       // When a slot page calls notFound() or deny(), it should gracefully
       // degrade to default.tsx or null — not crash the page. This matches
       // Next.js behavior. See design/02-rendering-pipeline.md
       // §"Slot Access Failure = Graceful Degradation"
-      let denyFallback: React.ReactElement | null = null;
-      if (slotNode.default) {
-        const defaultMod = (await slotNode.default.load()) as Record<string, unknown>;
-        const DefaultComp = defaultMod.default as ((...args: unknown[]) => unknown) | undefined;
-        if (DefaultComp) {
-          denyFallback = h(DefaultComp, { params: paramsPromise, searchParams: {} });
-        }
-      }
-
-      // Wrap the slot page to catch DenySignal (from notFound() or deny())
-      // at the component level. This prevents the signal from reaching the
-      // RSC onError callback and being tracked as a page-level denial, which
-      // would cause the pipeline to replace the entire successful SSR response
-      // with a deny page. Instead, the slot gracefully degrades.
-      const denyFallbackCapture = denyFallback;
-      const SafeSlotPage = async (props: Record<string, unknown>) => {
-        try {
-          return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
-        } catch (error) {
-          if (error instanceof DenySignal) {
-            return denyFallbackCapture;
-          }
-          throw error;
-        }
-      };
-
-      let element: React.ReactElement = h(SafeSlotPage, {
-        params: paramsPromise,
-        searchParams: {},
-      });
-
-      // Wrap with error boundaries and layouts from intermediate slot segments
-      // (everything between slot root and leaf). Process innermost-first, same
-      // order as route-element-builder.ts handles main segments. The slot root
-      // (index 0) is handled separately after the access gate below.
-      for (let i = slotMatch.chain.length - 1; i > 0; i--) {
-        const seg = slotMatch.chain[i];
-
-        // Error boundaries from this segment
-        element = await wrapSegmentWithErrorBoundaries(seg, element, h);
-
-        // Layout from this segment
-        if (seg.layout) {
-          const layoutMod = (await seg.layout.load()) as Record<string, unknown>;
-          if (layoutMod.default) {
-            const Layout = layoutMod.default as (...args: unknown[]) => unknown;
-            element = h(Layout, {
-              params: paramsPromise,
-              searchParams: {},
-              children: element,
-            });
-          }
-        }
-      }
-
-      // Wrap in SlotAccessGate if slot root has access.ts.
-      // On denial: denied.tsx → default.tsx → null (graceful degradation).
-      // See design/04-authorization.md §"Slot-Level Auth".
-      if (slotNode.access) {
-        const accessMod = (await slotNode.access.load()) as Record<string, unknown>;
-        const accessFn = accessMod.default as
-          | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-          | undefined;
-        if (accessFn) {
-          // Load denied.tsx fallback
-          let deniedFallback: React.ReactElement | null = null;
-          if (slotNode.denied) {
-            const deniedMod = (await slotNode.denied.load()) as Record<string, unknown>;
-            const DeniedComponent = deniedMod.default as
-              | ((...args: unknown[]) => unknown)
-              | undefined;
-            if (DeniedComponent) {
-              deniedFallback = h(DeniedComponent, {});
+      const denyFallback = await renderDefaultFallback(slotNode, h);
+
+      // Build the slot page element.
+      // Client references ('use client' pages) must NOT be called as functions —
+      // they are proxy objects that throw when invoked. For client references,
+      // use createElement directly. Error catching is unnecessary because client
+      // references are serialized as references in the RSC Flight stream — they
+      // don't execute on the server. See TIM-627.
+      //
+      // For server components, wrap in SafeSlotPage to catch ALL errors at the
+      // component level. This prevents errors from leaving unresolved Flight
+      // rows in the RSC stream — see TIM-524 for details.
+      let element: React.ReactElement;
+      if (isClientReference(SlotPage)) {
+        element = h(SlotPage, {});
+      } else {
+        const SafeSlotPage = async (props: Record<string, unknown>) => {
+          try {
+            return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
+          } catch (error) {
+            // RedirectSignal must propagate — the pipeline handles redirects
+            // at the top level. Swallowing it here would silently return
+            // fallback content instead of redirecting. See TIM-554.
+            if (error instanceof RedirectSignal) {
+              throw error;
             }
-          }
-
-          // Load default.tsx fallback
-          let defaultFallback: React.ReactElement | null = null;
-          if (slotNode.default) {
-            const defaultMod = (await slotNode.default.load()) as Record<string, unknown>;
-            const DefaultComp = defaultMod.default as ((...args: unknown[]) => unknown) | undefined;
-            if (DefaultComp) {
-              defaultFallback = h(DefaultComp, { params: paramsPromise, searchParams: {} });
+            if (error instanceof DenySignal) {
+              return denyFallback;
             }
+            // Log the error but don't re-throw — returning fallback ensures
+            // the Flight row is resolved and the page hydrates correctly.
+            logRenderError({
+              method: '',
+              path: '',
+              error,
+            });
+            return denyFallback;
           }
-
-          const params = await paramsPromise;
-          element = h(SlotAccessGate, {
-            accessFn,
-            params,
-            searchParams: {},
-            deniedFallback,
-            defaultFallback,
-            children: element,
-          });
-        }
+        };
+        element = h(SafeSlotPage, {});
       }
 
-      // Wrap with slot root's layout (outermost, outside access gate)
-      if (slotNode.layout) {
-        const layoutMod = (await slotNode.layout.load()) as Record<string, unknown>;
-        if (layoutMod.default) {
-          const Layout = layoutMod.default as (...args: unknown[]) => unknown;
-          element = h(Layout, {
-            params: paramsPromise,
-            searchParams: {},
-            children: element,
-          });
-        }
-      }
+      // Wrap with error boundaries, layouts, and access gates from
+      // intermediate slot segments (everything between slot root and leaf).
+      // Process innermost-first, same order as route-element-builder.ts
+      // handles main segments. The slot root (index 0) is handled below.
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h, accessVerdicts);
+
+      // Wrap with slot root's layout — INSIDE the access gate, so the layout
+      // server component never executes when access.ts denies. See TIM-1074.
+      element = await wrapWithLayout(slotNode, element, h);
+
+      // Wrap in SlotAccessGate if slot root has access.ts. The gate is
+      // OUTSIDE the layout, matching the segment model in
+      // route-element-builder.ts: a denied layout must not render, or it
+      // would fetch/serialize protected data into the RSC Flight stream.
+      // On denial: denied.tsx → default.tsx → null (graceful degradation),
+      // rendered WITHOUT the denied slot's own layout.
+      // See design/04-authorization.md §"Slot-Level Auth".
+      element = await wrapWithAccessGate(slotNode, element, h, accessVerdicts);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -180,7 +186,7 @@ export async function resolveSlotElement(
       // Catch-all error boundary: ensures slot errors NEVER propagate to the
       // parent layout. Without this, a slot without error.tsx that throws
       // causes SSR's renderToReadableStream to reject, triggering renderDenyPage
-      // which re-executes all layout server components (including headers() calls
+      // which re-executes all layout server components (including getHeaders() calls
       // that fail in the SSR environment). The null fallback means the slot
       // degrades to nothing — consistent with the slot access denial behavior.
       // See design/02-rendering-pipeline.md §"Slot Access Failure = Graceful Degradation"
@@ -194,25 +200,115 @@ export async function resolveSlotElement(
     }
   }
 
-  // No matching page — render default.tsx fallback
-  if (slotNode.default) {
-    const mod = (await slotNode.default.load()) as Record<string, unknown>;
-    if (mod.default) {
-      const DefaultComponent = mod.default as (...args: unknown[]) => unknown;
-      return h(DefaultComponent, { params: paramsPromise, searchParams: {} });
-    }
+  // No matching page — render default.tsx fallback.
+  // Per design/02-rendering-pipeline.md: "No access check for default.tsx."
+  // Access verdicts from the eager evaluation are not applied here.
+  // Pass taintKey so accessor calls inside default.tsx are scoped to this
+  return renderDefaultFallback(slotNode, h);
+}
+
+// ─── Element Wrapping Helpers ───────────────────────────────────────────────
+
+/**
+ * Wrap an element with error boundaries, access gates, and layouts from
+ * intermediate slot segments (indices 1..n, skipping the slot root at index 0).
+ * Processes innermost-first to match route-element-builder.ts ordering.
+ *
+ * Access gates are enforced for every intermediate segment that has access.ts,
+ * not just the slot root. Without this, nested slot children (e.g.,
+ * @admin/reports/access.ts) and intercepting route children with access.ts
+ * would bypass authorization. See TIM-999.
+ *
+ * Wrap order per segment (innermost → outermost): error boundaries → layout
+ * → access gate. The gate must be OUTSIDE the layout so a denying access.ts
+ * prevents the layout server component from executing — otherwise the layout
+ * would fetch/serialize protected data into the RSC Flight stream. Matches
+ * route-element-builder.ts. See TIM-1074.
+ */
+async function wrapWithIntermediateSegments(
+  chain: ManifestSegmentNode[],
+  element: React.ReactElement,
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[]
+): Promise<React.ReactElement> {
+  for (let i = chain.length - 1; i > 0; i--) {
+    const seg = chain[i];
+    element = await wrapSegmentWithErrorBoundaries(seg, element, h);
+    element = await wrapWithLayout(seg, element, h);
+    element = await wrapWithAccessGate(seg, element, h, accessVerdicts);
   }
+  return element;
+}
 
-  // No page and no default — slot renders nothing
-  return null;
+/**
+ * Wrap an element with a segment's layout component, if present.
+ */
+async function wrapWithLayout(
+  node: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: CreateElementFn
+): Promise<React.ReactElement> {
+  if (!node.layout) return element;
+  const Layout = await loadComponent(node.layout);
+  if (!Layout) return element;
+  return h(Layout, { children: element });
+}
+
+/**
+ * Wrap an element with a SlotAccessGate if the node has access.ts.
+ * On denial: denied.tsx → default.tsx → null (graceful degradation).
+ */
+async function wrapWithAccessGate(
+  slotNode: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[]
+): Promise<React.ReactElement> {
+  if (!slotNode.access) return element;
+
+  const accessFn = await loadComponent(slotNode.access);
+  if (!accessFn) return element;
+
+  let DeniedComponent: ((...args: unknown[]) => unknown) | null = null;
+  if (slotNode.denied) {
+    DeniedComponent = (await loadComponent(slotNode.denied)) ?? null;
+  }
+
+  const slotName = slotNode.segmentName?.replace(/^@/, '') ?? '';
+
+  const defaultFallback = await renderDefaultFallback(slotNode, h);
+
+  // Look up pre-computed verdict from eager evaluation. Only replay
+  // denial/redirect verdicts — 'pass' verdicts must NOT be replayed
+  // because the access function may warm React.cache (e.g., requireUser())
+  // for layout/page dedup, and replaying 'pass' skips the cache-warming
+  // call. 'error' verdicts are also excluded — the gate must re-run
+  // accessFn so the error reaches the slot's error boundary.
+  const preVerdict = accessVerdicts?.find(
+    (v) => v.node === slotNode && v.verdict !== 'pass' && v.verdict !== 'error'
+  );
+
+  return h(SlotAccessGate, {
+    accessFn,
+    DeniedComponent,
+    slotName,
+    createElement: h,
+    defaultFallback,
+    children: element,
+    verdict: preVerdict?.verdict,
+  });
 }
 
+// ─── Slot Matching ──────────────────────────────────────────────────────────
+
 /** Result of matching a slot's sub-tree against the current route. */
 interface SlotMatchResult {
   /** The page file at the matched leaf. */
   page: NonNullable<ManifestSegmentNode['page']>;
   /** The full chain of slot nodes traversed (slot root → … → leaf with page). */
   chain: ManifestSegmentNode[];
+  /** Params collected from the slot's segment chain (may differ from main route params). */
+  slotParams: Record<string, string | string[]>;
 }
 
 /**
@@ -231,7 +327,7 @@ interface SlotMatchResult {
  * to find the deepest matching page.
  */
 function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMatchResult | null {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
   // Find the parent segment that owns this slot by comparing urlPaths.
   // The slot's urlPath matches its parent's urlPath (slots don't add URL depth).
@@ -253,90 +349,60 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
   // against the slot's children.
   const remainingSegments = parentIndex >= 0 ? segments.slice(parentIndex + 1) : [];
 
-  // If no remaining segments, the slot's own page matches
-  if (remainingSegments.length === 0) {
-    if (slotNode.page) {
-      return { page: slotNode.page, chain: [slotNode] };
-    }
-    // Check for optional-catch-all child — [[...slug]] matches zero segments
-    for (const child of slotNode.children ?? []) {
-      if (child.segmentType === 'optional-catch-all' && child.page) {
-        return { page: child.page, chain: [slotNode, child] };
-      }
-    }
-    return null;
-  }
+  // Extract raw URL parts from the remaining main-route segments.
+  // Use rawSegmentParams (pre-coercion) to ensure we get actual URL strings,
+  // not codec-transformed values. Fall back to segmentParams for tests/compat.
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const urlParts = extractUrlParts(remainingSegments, rawParams);
 
-  // Walk the slot's children to match remaining URL segments.
-  // Track the chain so we can apply error boundaries and layouts.
-  const chain: ManifestSegmentNode[] = [slotNode];
-  let currentNode = slotNode;
-  for (const seg of remainingSegments) {
-    const childName = seg.segmentName;
-    const directChildren = currentNode.children ?? [];
-
-    let found: ManifestSegmentNode | null = null;
-    for (const child of directChildren) {
-      // Exact static match
-      if (child.segmentType === 'static' && child.segmentName === childName) {
-        found = child;
-        break;
-      }
-    }
+  // Match URL parts against the slot's segment tree using the shared walker.
+  // Handles zero parts (slot's own page), catch-all, optional-catch-all,
+  // groups, backtracking, and correct priority ordering.
+  const result = matchUrlParts(slotNode, urlParts);
+  if (!result) return null;
 
-    // Try dynamic segments if no static match
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'dynamic') {
-          found = child;
-          break;
-        }
-      }
-    }
+  const leaf = result.chain[result.chain.length - 1];
+  if (!leaf.page) return null;
 
-    // Try catch-all segments — these consume ALL remaining URL segments,
-    // so we break out of the outer loop immediately.
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'catch-all' || child.segmentType === 'optional-catch-all') {
-          found = child;
-          break;
-        }
-      }
-      if (found) {
-        chain.push(found);
-        currentNode = found;
-        break;
-      }
-    }
+  return { page: leaf.page, chain: result.chain, slotParams: result.params };
+}
 
-    // Try group children (transparent)
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'group') {
-          for (const groupChild of child.children ?? []) {
-            if (groupChild.segmentName === childName) {
-              found = groupChild;
-              break;
-            }
-          }
-          if (found) break;
-        }
+/**
+ * Extract raw URL path parts from a main-route segment chain.
+ *
+ * Each dynamic segment consumed one URL part (its param value).
+ * Static segments consumed their own name. Groups are transparent.
+ * Catch-all segments consumed multiple parts (their param value is string[]).
+ *
+ * Uses rawSegmentParams (pre-coercion) to get actual URL strings.
+ * Values are coerced to String() defensively in case a codec leaked
+ * a non-string value into the params map.
+ */
+export function extractUrlParts(
+  segments: ManifestSegmentNode[],
+  mainParams: Record<string, string | string[]>
+): string[] {
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.segmentType === 'group') continue;
+    if (seg.segmentType === 'static') {
+      parts.push(seg.segmentName);
+    } else if (seg.paramName) {
+      const value = mainParams[seg.paramName];
+      if (Array.isArray(value)) {
+        parts.push(...value.map(String));
+      } else if (value !== undefined) {
+        // Reconstruct the original URL part for affixed segments.
+        // The param value is the stripped middle (e.g. "123" for [id].png
+        // matching "123.png"), so we re-attach prefix/suffix so that slot
+        // matching through matchUrlParts sees the original part.
+        const prefix = seg.paramPrefix ?? '';
+        const suffix = seg.paramSuffix ?? '';
+        parts.push(prefix + String(value) + suffix);
       }
     }
-
-    if (!found) {
-      // No matching child in slot tree — slot doesn't match this URL
-      return null;
-    }
-    chain.push(found);
-    currentNode = found;
   }
-
-  if (currentNode.page) {
-    return { page: currentNode.page, chain };
-  }
-  return null;
+  return parts;
 }
 
 /**
@@ -372,63 +438,321 @@ function findInterceptingMatch(
     }
     if (matchIdx < 0) continue;
 
-    // Walk the intercepting child's sub-tree to match remaining target parts
+    // Match remaining target parts against the intercepting child's sub-tree.
     const remaining = targetParts.slice(matchIdx + 1);
-    const chain: ManifestSegmentNode[] = [slotNode, child];
-
-    if (remaining.length === 0) {
-      if (child.page) {
-        return { page: child.page, chain };
+    const result = matchUrlParts(child, remaining);
+    if (result) {
+      const leaf = result.chain[result.chain.length - 1];
+      if (leaf.page) {
+        return {
+          page: leaf.page,
+          // Prepend slotNode — matchUrlParts starts from child, not slot root
+          chain: [slotNode, ...result.chain],
+          slotParams: result.params,
+        };
       }
-      continue;
     }
+  }
 
-    let currentNode = child;
-    let matched = true;
-    for (const part of remaining) {
-      const children = currentNode.children ?? [];
-      let found: ManifestSegmentNode | null = null;
-
-      // Static match
-      for (const c of children) {
-        if (c.segmentType === 'static' && c.segmentName === part) {
-          found = c;
-          break;
-        }
-      }
+  return null;
+}
 
-      // Dynamic match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'dynamic') {
-            found = c;
-            break;
-          }
-        }
-      }
+// ─── Slot Access Evaluation ─────────────────────────────────────────────────
+
+/** Result of eagerly evaluating one segment's access.ts. */
+export interface SlotAccessVerdict {
+  node: ManifestSegmentNode;
+  /**
+   * 'pass' — access allowed.
+   * DenySignal/RedirectSignal — access denied, replayed in SlotAccessGate.
+   * 'error' — unknown error. Forces full render. No verdict passed to
+   *   SlotAccessGate, so it calls accessFn during render and the error
+   *   reaches the slot's error boundary.
+   */
+  verdict: 'pass' | 'error' | DenySignal | RedirectSignal;
+}
 
-      // Catch-all match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'catch-all' || c.segmentType === 'optional-catch-all') {
-            found = c;
-            break;
-          }
-        }
-      }
+/**
+ * Eagerly evaluate the access chain for a slot (root + intermediate segments).
+ *
+ * Runs each access.ts top-down (outermost first). If any denies, the chain
+ * stops (shallowest failure wins, matching segment access semantics).
+ *
+ * Verdicts are stored for replay in SlotAccessGate / wrapWithIntermediateSegments
+ * so access.ts is called exactly once per request.
+ */
+async function evaluateSlotAccessChain(
+  slotRoot: ManifestSegmentNode,
+  chain: ManifestSegmentNode[]
+): Promise<SlotAccessVerdict[]> {
+  // Collect all nodes with access.ts: slot root + intermediate chain segments
+  const nodesWithAccess: ManifestSegmentNode[] = [];
+  if (slotRoot.access) nodesWithAccess.push(slotRoot);
+  for (let i = 1; i < chain.length; i++) {
+    if (chain[i].access) nodesWithAccess.push(chain[i]);
+  }
+
+  if (nodesWithAccess.length === 0) return [];
 
-      if (!found) {
-        matched = false;
+  const results: SlotAccessVerdict[] = [];
+  for (const node of nodesWithAccess) {
+    const accessFn = await loadComponent(node.access!);
+    if (!accessFn) {
+      results.push({ node, verdict: 'pass' });
+      continue;
+    }
+    try {
+      await accessFn();
+      results.push({ node, verdict: 'pass' });
+    } catch (e) {
+      if (e instanceof DenySignal) {
+        results.push({ node, verdict: e });
+        break; // shallowest failure wins
+      }
+      if (e instanceof RedirectSignal) {
+        results.push({ node, verdict: e });
         break;
       }
-      chain.push(found);
-      currentNode = found;
+      // Unknown error — record as 'error' to force full render (blocks
+      // canSkip via accessBlocked). No verdict is passed to SlotAccessGate
+      // (wrapWithAccessGate filters 'error' out), so the gate calls
+      // accessFn during render and the error reaches the error boundary.
+      results.push({ node, verdict: 'error' });
+      break;
     }
+  }
+  return results;
+}
+
+// ─── Slot Caching ──────────────────────────────────────────────────────────
+
+export interface SlotSkipEntry {
+  slotKey: string;
+  parentSegmentId: string;
+  /**
+   * Whether the slot's components called request accessors (getHeaders,
+   * getSearchParams, cookies) during their last render. Replaces the
+   * unreliable AsyncFunction heuristic — taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
+  /** Whether the slot's access.ts denied on this render. */
+  denied: boolean;
+  /** Whether the slot was skipped (content not rendered, client keeps cached). */
+  skipped?: boolean;
+}
+
+interface ResolveSlotPropsArgs {
+  segment: ManifestSegmentNode;
+  segmentId: string;
+  match: RouteMatch;
+  h: CreateElementFn;
+  interception?: InterceptionContext;
+  parentTreePath: string;
+  departingUrl: string | null;
+  destinationUrl: string;
+  clientStateTree: ClientStateTree | null;
+  slotSkipInfo: SlotSkipEntry[];
+}
 
-    if (matched && currentNode.page) {
-      return { page: currentNode.page, chain };
+/**
+ * Resolve all parallel route slots for a layout, wrapping each in a
+ * SegmentOutlet for client-side caching. Slots whose matched content
+ * hasn't changed between the departing and destination URLs are rendered
+ * with `skip=true` so the client keeps its cached content.
+ */
+export async function resolveSlotProps({
+  segment,
+  segmentId,
+  match,
+  h,
+  interception,
+  parentTreePath,
+  departingUrl,
+  destinationUrl,
+  clientStateTree,
+  slotSkipInfo,
+}: ResolveSlotPropsArgs): Promise<Record<string, unknown>> {
+  const slotProps: Record<string, unknown> = {};
+  const slotEntries = Object.entries(segment.slots ?? {});
+  if (slotEntries.length === 0) return slotProps;
+
+  // Parse URLs to extract pathnames for slot skip comparison.
+  // The departing URL (X-Timber-URL) is an untrusted request header —
+  // catch parse failures and fall back to no-cache (full render).
+  const destParsed = new URL(destinationUrl, 'http://localhost');
+  let depParsed: URL | null = null;
+  if (departingUrl) {
+    try {
+      depParsed = new URL(departingUrl, 'http://localhost');
+    } catch {
+      // Malformed departing URL — disable slot skipping for this request
     }
   }
+  const destinationPathname = destParsed.pathname;
+  const departingPathname = depParsed?.pathname ?? null;
+
+  // Compute URL parts for slot skip comparison.
+  // Include the owning segment (segIdx + 1) to match findSlotMatch,
+  // which slices at parentIndex + 1. Filter out the root segment
+  // (segmentName === '') — it maps to '/' and doesn't consume a URL part.
+  const segIdx = match.segments.indexOf(segment);
+  const parentSegments =
+    segIdx >= 0 ? match.segments.slice(0, segIdx + 1).filter((s) => s.segmentName !== '') : [];
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const parentConsumedParts = extractUrlParts(parentSegments, rawParams);
+  const sliceAt = parentConsumedParts.length;
+
+  function splitPathname(pathname: string): string[] {
+    return pathname === '/' ? [] : pathname.slice(1).split('/');
+  }
 
-  return null;
+  const destinationAll = splitPathname(destinationPathname);
+  const departingAll = departingPathname ? splitPathname(departingPathname) : null;
+  const destinationParts = destinationAll.slice(sliceAt);
+  const departingParts = departingAll ? departingAll.slice(sliceAt) : null;
+  const clientSlots = clientStateTree?.slots ?? null;
+
+  // Check if parent segment's URL parts changed (e.g., /users/1 → /users/2).
+  let parentParamsChanged = false;
+  if (departingAll) {
+    const depParent = departingAll.slice(0, sliceAt);
+    const destParent = destinationAll.slice(0, sliceAt);
+    parentParamsChanged =
+      depParent.length !== destParent.length || depParent.some((p, i) => p !== destParent[i]);
+  }
+
+  for (const [slotName, slotNode] of slotEntries) {
+    const slotManifest = slotNode as ManifestSegmentNode;
+    const slotKey = computeSlotKey(segmentId, `@${slotName}`);
+
+    // Match the slot's sub-tree against the destination URL parts.
+    // Used for both the skip decision and eager access evaluation.
+    const destMatch = matchUrlParts(slotManifest, destinationParts);
+
+    // Seed slot params BEFORE eager access evaluation so that access.ts
+    // files calling getSegmentParams() see the slot's own coerced params,
+    // not the main route's. This is the same seeding that resolveSlotElement
+    // does, but we need it here for the eager path.
+    if (destMatch && parentTreePath && Object.keys(destMatch.params).length > 0) {
+      const slotSuffix = destMatch.chain
+        .map((s) => s.segmentName)
+        .filter(Boolean)
+        .join('/');
+      const prefix = parentTreePath === '/' ? '' : parentTreePath;
+      const fullSlotPath = `${prefix}/${slotSuffix}`;
+      const coerced = coerceSlotParams(destMatch.chain, destMatch.params);
+      setSlotParams(fullSlotPath, coerced);
+    }
+
+    // Check non-access skip conditions first. If any of these fail,
+    // the slot can't be skipped regardless of access — no need to run
+    // the eager access evaluation (which would double-run access.ts
+    // since the in-tree gate also calls it during render).
+    const hasInterceptingChildren = slotManifest.children.some(
+      (c) => c.segmentType === 'intercepting'
+    );
+    const isSkipCandidate =
+      !interception &&
+      !hasInterceptingChildren &&
+      !parentParamsChanged &&
+      departingParts !== null &&
+      shouldSkipSlot({
+        slotKey,
+        clientSlots,
+        slotNode: slotManifest,
+        departingUrlParts: departingParts,
+        destinationUrlParts: destinationParts,
+      });
+
+    // Eagerly evaluate the slot's access chain only for skip candidates.
+    // This serves two purposes:
+    // 1. Satisfies security principle #3 (auth always runs) for skipped slots
+    // 2. Determines whether access denied (denied slots must not be skipped)
+    //
+    // Non-skip-candidate slots skip eager evaluation — their access.ts
+    // runs during render via SlotAccessGate (normal path). Per design doc:
+    // "No access check for default.tsx" (destMatch null = unmatched slot).
+    const chainVerdicts =
+      isSkipCandidate && destMatch
+        ? await evaluateSlotAccessChain(slotManifest, destMatch.chain)
+        : [];
+    const accessBlocked = chainVerdicts.some((v) => v.verdict !== 'pass');
+    const canSkip = isSkipCandidate && !accessBlocked;
+
+    if (canSkip) {
+      // Access already ran eagerly (all verdicts 'pass') — principle #3 satisfied.
+      // No gate wrapper needed.
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        skip: true,
+        children: null,
+      });
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: false,
+        denied: false,
+        skipped: true,
+      });
+    } else {
+      const resolvedElement = await resolveSlotElement(
+        slotManifest,
+        match,
+        h,
+        interception,
+        parentTreePath,
+        chainVerdicts
+      );
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        children: resolvedElement,
+      });
+      // Static analysis: check if any file in the slot's RENDERED tree
+      // is request-dependent. Only check layouts when destMatch exists —
+      // unmatched slots render default.tsx directly without layouts.
+      let slotRequestDep = false;
+      const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+      const hasRenderedPage = destMatch && destLeaf?.page;
+      if (hasRenderedPage) {
+        // Check slot root layout (rendered by wrapWithLayout)
+        if (
+          slotManifest.layout?.filePath &&
+          isStaticRequestDependent(slotManifest.layout.filePath)
+        ) {
+          slotRequestDep = true;
+        }
+        // Check intermediate slot layouts
+        if (!slotRequestDep) {
+          for (const seg of destMatch.chain) {
+            if (seg.layout?.filePath && isStaticRequestDependent(seg.layout.filePath)) {
+              slotRequestDep = true;
+              break;
+            }
+          }
+        }
+        // Check leaf page
+        if (!slotRequestDep) {
+          if (destLeaf?.page?.filePath && isStaticRequestDependent(destLeaf.page.filePath)) {
+            slotRequestDep = true;
+          }
+        }
+      } else {
+        // No match — only default.tsx is rendered (no layouts)
+        const defaultFile = slotManifest.default?.filePath;
+        if (!defaultFile) {
+          slotRequestDep = true; // No entry file → conservative
+        } else {
+          slotRequestDep = isStaticRequestDependent(defaultFile);
+        }
+      }
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: slotRequestDep,
+        denied: accessBlocked,
+      });
+    }
+  }
+
+  return slotProps;
 }