@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/slot-resolver.ts

@@ -16,33 +16,79 @@
  * See design/02-rendering-pipeline.md §"Parallel Slots"
  */
 
-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 type { InterceptionContext, RouteMatch } from './pipeline.js';
-import { DenySignal } from './primitives.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
+import { TimberErrorBoundary } from '../client/error-boundary.tsx';
+import SlotErrorFallback from '../client/slot-error-fallback.tsx';
+import { SlotAccessGate } from './access-gate.tsx';
+import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
+import { isClientReference } from './utils/element-type.ts';
+import { containSlotSubtree } from './slot-subtree-contain.ts';
+import { loadModule } from './safe-load.ts';
+import type { InterceptionContext, RouteMatch } from './pipeline.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { logRenderError } from './logger.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { setSlotParams, runWithSlotSegmentParams } from './request-context.ts';
+import { coerceSlotParams } from './param-coercion.ts';
+import type { CoercedParams } from '../shared/param-value.ts';
+import { matchUrlParts } from './tree-match.ts';
+import { extractUrlParts, consumedPartsThroughSegment } from './chain-url-parts.ts';
+import { findInterceptingMatch } from './slot-interception.ts';
+import { SegmentOutlet } from '../client/segment-outlet.tsx';
+import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.ts';
+import { computeSlotKey, computeSlotContentKey } from '../routing/segment-keys.ts';
+import { isStaticRequestDependent } from './request-dep.ts';
 
 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
 ): 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,133 +100,126 @@ 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;
+    // Coerce the slot's own chain params through the global schema codecs
+    // (same as the main route) and expose them two ways:
+    //
+    //  - keyed, in the ALS slot map, so `getSegmentParams(slotPath)` resolves
+    //    from anywhere in the request;
+    //  - scoped, around every component this resolver invokes from the slot's
+    //    matched chain, so a no-arg `getSegmentParams()` inside the slot
+    //    returns the slot's params instead of the main route's. An
+    //    intercepting page has no other way to see its own params: the
+    //    pipeline re-matched the SOURCE pathname, so the main params describe
+    //    the page rendering *behind* the modal (TIM-1283).
+    //
+    // Both derive from the same coerced record, so the keyed overload and the
+    // no-arg call inside the slot can never disagree.
+    const coerced = coerceSlotParams(slotMatch.chain, slotMatch.slotParams);
+    const fullSlotPath = computeSlotSegmentPath(slotMatch.chain, parentTreePath);
+
+    if (fullSlotPath && Object.keys(coerced).length > 0) {
+      setSlotParams(fullSlotPath, coerced);
+    }
+    const scope = <T>(fn: () => T): T => runWithSlotSegmentParams(fullSlotPath, coerced, fn);
 
+    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.
+      //
+      // The catch below covers the page function. The tree it RETURNS is
+      // contained separately (`containSlotSubtree`): a server component
+      // nested in that tree runs as its own Flight task, outside this
+      // try/catch, and a deny there would otherwise reach Flight's global
+      // onError as a page-level 4xx. See slot-subtree-contain.ts, TIM-1450.
+      let element: React.ReactElement;
+      if (isClientReference(SlotPage)) {
+        element = h(SlotPage, {});
+      } else {
+        const SafeSlotPage = async (props: Record<string, unknown>) => {
+          try {
+            const rendered = await scope(() =>
+              (SlotPage as (props: Record<string, unknown>) => unknown)(props)
+            );
+            return containSlotSubtree(rendered as React.ReactNode, denyFallback);
+          } 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 (isRedirectSignal(error)) {
+              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 (isDenySignal(error)) {
+              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 slot root's error boundaries (outermost)
-      element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
+      // 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,
+        scope,
+        denyFallback
+      );
+
+      // 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, scope, denyFallback);
+
+      // 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, scope);
+
+      // Wrap with slot root's error boundaries (outermost). Slot identity on
+      // every one of them, not only the catch-all below: a slot's own
+      // status page must not set the document status or empty the main
+      // route's segment cache.
+      element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
+        loadModule,
+        createElement: h,
+        errorBoundaryComponent: TimberErrorBoundary,
+        isSlotBoundary: true,
+      });
 
       // 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 +233,198 @@ 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);
+}
+
+/**
+ * The full tree path of a slot's matched chain — the key both the ALS slot
+ * params map and the generated `getSegmentParams` overloads use.
+ *
+ * Built from the parent's tree path plus each chain node's directory name,
+ * so an intercepting node contributes its marker
+ * (`/gallery/@modal/(.)photo/[id]`) and a route group contributes its
+ * parentheses. Returns undefined when the caller has no parent tree path,
+ * which is how the resolver's test callers and any path-less entry point opt
+ * out of keyed lookups.
+ *
+ * One definition for both the render path and the eager access path: they
+ * key the same map, and a divergence would silently strand one of them.
+ */
+function computeSlotSegmentPath(
+  chain: ManifestSegmentNode[],
+  parentTreePath: string | undefined
+): string | undefined {
+  if (!parentTreePath) return undefined;
+  const slotSuffix = chain
+    .map((s) => s.segmentName)
+    .filter(Boolean)
+    .join('/');
+  const prefix = parentTreePath === '/' ? '' : parentTreePath;
+  return `${prefix}/${slotSuffix}`;
+}
+
+// ─── 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,
+  scope?: SlotParamScope,
+  denyFallback?: React.ReactNode
+): Promise<React.ReactElement> {
+  for (let i = chain.length - 1; i > 0; i--) {
+    const seg = chain[i];
+    element = await wrapSegmentWithErrorBoundaries(seg, element, {
+      loadModule,
+      createElement: h,
+      errorBoundaryComponent: TimberErrorBoundary,
+      isSlotBoundary: true,
+    });
+    element = await wrapWithLayout(seg, element, h, scope, denyFallback);
+    element = await wrapWithAccessGate(seg, element, h, scope);
   }
+  return element;
+}
+
+/**
+ * Runs a function with the slot's own segment params in scope.
+ *
+ * Applied to every component this module invokes from a slot's matched chain
+ * — page, layouts, access functions — so all of them agree on what a no-arg
+ * `getSegmentParams()` means inside a slot. A partial application would be
+ * worse than none: a layout and the page under it would disagree about the
+ * params of the same render.
+ */
+type SlotParamScope = <T>(fn: () => T) => T;
+
+/**
+ * Invokes a slot layout inside that slot's param scope.
+ *
+ * Declared at module scope, and given the layout and the scope as props,
+ * so its component identity is the same on every render. A closure created
+ * per render would be a new component type each time, and React would
+ * unmount and remount the whole layout subtree — including client
+ * components' state — on every navigation that re-renders the slot.
+ *
+ * Server component: the function-valued props are called here on the server
+ * and never reach the Flight stream, the same way `SlotAccessGate` takes
+ * `accessFn`.
+ *
+ * The layout's own chrome is part of the slot's subtree, so the tree it
+ * returns is contained like the page's: a server component the layout
+ * renders beside `children` that denies becomes the slot fallback in place,
+ * not a page-level 4xx. `children` is the element the resolver built for the
+ * level below, already contained there, and is passed to the walk as the one
+ * subtree to leave alone. See slot-subtree-contain.ts.
+ */
+function ScopedSlotLayout(props: {
+  layout: (props: Record<string, unknown>) => unknown;
+  scope: SlotParamScope;
+  denyFallback: React.ReactNode;
+  children: React.ReactElement;
+}): unknown {
+  const rendered = props.scope(() => props.layout({ children: props.children }));
+  return containSlotSubtree(rendered as React.ReactNode, props.denyFallback, props.children);
+}
 
-  // No page and no default — slot renders nothing
-  return null;
+/**
+ * Wrap an element with a segment's layout component, if present.
+ *
+ * A server-component layout is invoked through the slot param scope, so it
+ * sees the slot's params rather than the main route's — a layout and the
+ * page beneath it must not disagree about the params of one render. A
+ * client-reference layout is passed through untouched: it never executes on
+ * the server, and its params arrive over the client channel
+ * (`useSegmentParams`).
+ */
+async function wrapWithLayout(
+  node: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: CreateElementFn,
+  scope?: SlotParamScope,
+  denyFallback: React.ReactNode = null
+): Promise<React.ReactElement> {
+  if (!node.layout) return element;
+  const Layout = await loadComponent(node.layout);
+  if (!Layout) return element;
+  if (!scope || isClientReference(Layout)) return h(Layout, { children: element });
+
+  return h(ScopedSlotLayout, {
+    layout: Layout as (props: Record<string, unknown>) => unknown,
+    scope,
+    denyFallback,
+    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,
+  scope?: SlotParamScope
+): Promise<React.ReactElement> {
+  if (!slotNode.access) return element;
+
+  const loaded = await loadComponent(slotNode.access);
+  if (!loaded) return element;
+
+  // The gate calls this during render, so the scope has to travel with the
+  // function rather than wrap the call site.
+  const accessFn = scope ? () => scope(() => loaded()) : loaded;
+
+  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);
+
+  return h(SlotAccessGate, {
+    accessFn,
+    DeniedComponent,
+    slotName,
+    createElement: h,
+    defaultFallback,
+    children: element,
+  });
+}
+
+// ─── Slot Matching ──────────────────────────────────────────────────────────
+
 /** Result of matching a slot's sub-tree against the current route. */
-interface SlotMatchResult {
+export 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 (pre-coercion, may differ from main route params). */
+  slotParams: Record<string, string | string[]>;
 }
 
 /**
@@ -230,205 +442,400 @@ interface SlotMatchResult {
  * We compare the matched route's segment chain against the slot's children
  * to find the deepest matching page.
  */
-function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMatchResult | null {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
-
-  // 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).
-  // Search BACKWARDS to find the deepest (last) matching segment. Multiple
-  // segments can share the same urlPath when route groups are involved (e.g.,
-  // Root urlPath='/' and (browse) urlPath='/'). The slot's parent is always
-  // the deepest one — searching forward would incorrectly pick the root,
-  // making remainingSegments too long and breaking slot matching.
-  const slotUrlPath = slotNode.urlPath;
-  let parentIndex = -1;
+/**
+ * The index in the matched chain of the segment that owns this slot.
+ *
+ * **By identity**, because `urlPath` cannot answer it. Slots add no URL depth,
+ * so the owner shares the slot's `urlPath` — but so does every route group
+ * above it (`/` for both the root and `(browse)`), and since TIM-1280 so does
+ * an intercepting node on the children path, which sits *below* the owner.
+ * Picking the deepest urlPath match — the rule before this — therefore chose
+ * the intercepting node for a tree like `(browse)/@sidebar/` +
+ * `(browse)/(.)item/[id]/`, slicing one segment too many off the chain and
+ * handing `@sidebar` a shorter URL than it matches against. It would render
+ * its `default.tsx` where a page exists.
+ *
+ * The index must also agree with `slotUrlParts`, which slices the destination
+ * pathname at the same point and already used `indexOf(owner)`. Two derivations
+ * of one index is how they came apart; this is the shared one.
+ *
+ */
+export function findSlotOwnerIndex(
+  slotNode: ManifestSegmentNode,
+  segments: ManifestSegmentNode[]
+): number {
   for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].urlPath === slotUrlPath) {
-      parentIndex = i;
-      break;
+    for (const candidate of Object.values(segments[i].slots ?? {})) {
+      if (candidate === slotNode) return i;
     }
   }
 
+  return -1;
+}
+
+function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMatchResult | null {
+  const segments = match.segments;
+
+  const parentIndex = findSlotOwnerIndex(slotNode, segments);
+
   // The remaining segments after the parent are what we need to match
   // 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 };
+}
+
+// ─── 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;
+  /**
+   * Content key encoding owner parts + slot name + entry file + slot params.
+   * Sent to the client via X-Timber-Segments; the client advertises it back
+   * so the server can decide skips by key membership (TIM-1370).
+   */
+  contentKey: string;
+}
+
+/**
+ * The destination URL parts a segment's slots match against.
+ *
+ * A slot walks its own sub-tree starting where its owning segment stopped
+ * consuming the URL, so the parts are sliced at the length its ancestors
+ * consumed. Shared by `resolveSlotProps` and `publishSlotSegmentParams` — both
+ * have to slice identically or the two would disagree about which page a slot
+ * matched, and only one of them would be right.
+ *
+ * @internal
+ */
+export function slotUrlParts(
+  segment: ManifestSegmentNode,
+  match: RouteMatch,
+  url: string
+): string[] {
+  const pathname = new URL(url, 'http://localhost').pathname;
+  // Slice through the owning segment inclusive, to match findSlotMatch, which
+  // walks the chain from parentIndex + 1. `consumedUrlParts` drops the root
+  // (it consumes no URL part) and honors the interception anchor, so a slot on
+  // a retained owner above a climbing marker is not handed parts the target
+  // does not contain.
+  const sliceAt = consumedPartsThroughSegment(segment, match).length;
+  const all = pathname === '/' ? [] : pathname.slice(1).split('/');
+  return all.slice(sliceAt);
+}
+
+/**
+ * Seed per-slot segment params for a segment whose layout is being SKIPPED.
+ *
+ * `resolveSlotProps` seeds these as part of resolving slot props, but a skipped
+ * layout never gets there — `route-element-builder` continues past it. Its
+ * slots are still mounted on the client, though, so leaving them out of the
+ * published map made `useSegmentParams(slotPath)` fall back to the main route's
+ * record after any navigation that skipped their parent (TIM-1285).
+ *
+ * Only the params are seeded. Nothing renders, no access chain runs — a skipped
+ * layout's slots are unchanged by definition, which is what made it skippable.
+ *
+ * @internal
+ */
+export function publishSlotSegmentParams(
+  segment: ManifestSegmentNode,
+  match: RouteMatch,
+  destinationUrl: string,
+  parentTreePath: string | undefined
+): void {
+  const slotEntries = Object.entries(segment.slots ?? {});
+  if (slotEntries.length === 0) return;
+  const destinationParts = slotUrlParts(segment, match, destinationUrl);
+
+  for (const [, slotNode] of slotEntries) {
+    const destMatch = matchUrlParts(slotNode as ManifestSegmentNode, destinationParts);
+    if (!destMatch) continue;
+    const coerced = coerceSlotParams(destMatch.chain, destMatch.params);
+    const fullSlotPath = computeSlotSegmentPath(destMatch.chain, parentTreePath);
+    if (fullSlotPath && Object.keys(coerced).length > 0) {
+      setSlotParams(fullSlotPath, coerced);
     }
+  }
+}
 
-    // 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;
+/**
+ * Emit slot metadata for a layout whose rendering was SKIPPED.
+ *
+ * Skipped layouts never reach `resolveSlotProps`, but the client rebuilds
+ * its segment tree from each navigation's X-Timber-Segments response. If
+ * skipped slots are absent, the client loses their contentKeys and can't
+ * advertise them on the next navigation — breaking key-based slot skipping.
+ *
+ * This computes contentKey and isRequestDependent for each slot without
+ * rendering anything, using the same derivation as `resolveSlotProps`.
+ */
+export function emitSlotInfoForSkippedLayout(
+  segment: ManifestSegmentNode,
+  segmentId: string,
+  match: RouteMatch,
+  destinationUrl: string,
+  slotSkipInfo: SlotSkipEntry[]
+): void {
+  const slotEntries = Object.entries(segment.slots ?? {});
+  if (slotEntries.length === 0) return;
+
+  const destinationParts = slotUrlParts(segment, match, destinationUrl);
+  const ownerParts = consumedPartsThroughSegment(segment, match);
+
+  for (const [slotName, slotNode] of slotEntries) {
+    const slotManifest = slotNode as ManifestSegmentNode;
+    const slotKey = computeSlotKey(segmentId, `@${slotName}`);
+    const destMatch = matchUrlParts(slotManifest, destinationParts);
+
+    const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+    const entryFile = destLeaf?.page?.filePath ?? null;
+    const contentKey = computeSlotContentKey(
+      slotKey,
+      ownerParts,
+      entryFile,
+      destMatch?.params ?? {}
+    );
+
+    const hasAccessInChain =
+      !!slotManifest.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+
+    let slotRequestDep = hasAccessInChain;
+    if (!slotRequestDep) {
+      const hasRenderedPage = destMatch && destLeaf?.page;
+      if (hasRenderedPage) {
+        if (
+          slotManifest.layout?.filePath &&
+          isStaticRequestDependent(slotManifest.layout.filePath)
+        ) {
+          slotRequestDep = true;
+        }
+        if (!slotRequestDep) {
+          for (const seg of destMatch.chain) {
+            if (seg.layout?.filePath && isStaticRequestDependent(seg.layout.filePath)) {
+              slotRequestDep = true;
               break;
             }
           }
-          if (found) break;
+        }
+        if (!slotRequestDep && destLeaf?.page?.filePath) {
+          slotRequestDep = isStaticRequestDependent(destLeaf.page.filePath);
+        }
+      } else {
+        const defaultFile = slotManifest.default?.filePath;
+        if (!defaultFile) {
+          slotRequestDep = true;
+        } else {
+          slotRequestDep = isStaticRequestDependent(defaultFile);
         }
       }
     }
 
-    if (!found) {
-      // No matching child in slot tree — slot doesn't match this URL
-      return null;
-    }
-    chain.push(found);
-    currentNode = found;
+    slotSkipInfo.push({
+      slotKey,
+      parentSegmentId: segmentId,
+      isRequestDependent: slotRequestDep,
+      denied: false,
+      contentKey,
+    });
   }
+}
 
-  if (currentNode.page) {
-    return { page: currentNode.page, chain };
-  }
-  return null;
+interface ResolveSlotPropsArgs {
+  segment: ManifestSegmentNode;
+  segmentId: string;
+  match: RouteMatch;
+  h: CreateElementFn;
+  interception?: InterceptionContext;
+  parentTreePath: string;
+  destinationUrl: string;
+  clientStateTree: ClientStateTree | null;
+  slotSkipInfo: SlotSkipEntry[];
 }
 
 /**
- * Find a matching intercepting route in a slot's children for the target pathname.
- *
- * When interception is active, the pipeline has already re-matched the source URL.
- * Here we check the slot's intercepting children (e.g. `(.)photo/[id]`) against
- * the target pathname to find which intercepting page to render.
+ * Resolve all parallel route slots for a layout, wrapping each in a
+ * SegmentOutlet for client-side caching. Slots whose content key matches
+ * one the client advertised are rendered with `skip=true` so the client
+ * keeps its cached content.
  *
- * The interceptedSegmentName tells us the first URL segment to look for in the
- * target pathname. We then walk the intercepting child's sub-tree to match
- * remaining segments.
+ * The skip decision is key-based (TIM-1370): the server computes a content
+ * key per slot from the owning segment's URL parts, the slot name, the
+ * matched entry file, and the slot's own params. The client advertises
+ * the keys it has cached; the server checks membership. This replaces
+ * the previous approach of reconstructing the client's state from a
+ * departing URL.
  */
-function findInterceptingMatch(
-  slotNode: ManifestSegmentNode,
-  targetPathname: string
-): SlotMatchResult | null {
-  const targetParts = targetPathname === '/' ? [] : targetPathname.slice(1).split('/');
-
-  for (const child of slotNode.children) {
-    if (child.segmentType !== 'intercepting' || !child.interceptedSegmentName) continue;
-
-    const segName = child.interceptedSegmentName;
-
-    // Find where the intercepted segment name appears in the target parts.
-    // Search from the end since intercepted routes match the URL tail.
-    let matchIdx = -1;
-    for (let i = targetParts.length - 1; i >= 0; i--) {
-      if (targetParts[i] === segName) {
-        matchIdx = i;
-        break;
-      }
-    }
-    if (matchIdx < 0) continue;
-
-    // Walk the intercepting child's sub-tree to match remaining target parts
-    const remaining = targetParts.slice(matchIdx + 1);
-    const chain: ManifestSegmentNode[] = [slotNode, child];
-
-    if (remaining.length === 0) {
-      if (child.page) {
-        return { page: child.page, chain };
-      }
-      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;
+export async function resolveSlotProps({
+  segment,
+  segmentId,
+  match,
+  h,
+  interception,
+  parentTreePath,
+  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;
+
+  const destinationParts = slotUrlParts(segment, match, destinationUrl);
+  const clientSlotKeys = clientStateTree?.slots ?? null;
+
+  // Owner URL parts — the URL values consumed through this segment.
+  // These are part of the content key because the slot's page may read
+  // parent params (e.g., via getSegmentParams).
+  const ownerParts = consumedPartsThroughSegment(segment, match);
+
+  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.
+    const destMatch = matchUrlParts(slotManifest, destinationParts);
+
+    // Compute the content key for this slot at the destination URL.
+    const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+    const entryFile = destLeaf?.page?.filePath ?? null;
+    const contentKey = computeSlotContentKey(
+      slotKey,
+      ownerParts,
+      entryFile,
+      destMatch?.params ?? {}
+    );
+
+    // Auth-bearing slots are inherently request-dependent — their content
+    // changes based on user state. Skipping them would require eager
+    // evaluation of access.ts outside React.cache scope, causing double
+    // execution (TIM-1364). Instead, exclude them from skip candidates
+    // entirely and let SlotAccessGate handle access during render.
+    // The client filters these out via isRequestDependent, so their keys
+    // are never advertised — but checking here is defense-in-depth.
+    const hasAccessInChain =
+      !!slotManifest.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+    const hasInterceptingChildren = slotManifest.children.some(
+      (c) => c.segmentType === 'intercepting'
+    );
+    const canSkip =
+      !interception &&
+      !hasInterceptingChildren &&
+      !hasAccessInChain &&
+      shouldSkipSlot(contentKey, clientSlotKeys);
+
+    if (canSkip) {
+      // No access.ts in this slot's chain (excluded above), so no gate needed.
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        skip: true,
+        children: null,
+      });
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: false,
+        denied: false,
+        skipped: true,
+        contentKey,
+      });
+    } else {
+      const resolvedElement = await resolveSlotElement(
+        slotManifest,
+        match,
+        h,
+        interception,
+        parentTreePath
+      );
+      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.
+      // Slots with access.ts are inherently request-dependent — their
+      // content varies with user state (TIM-1364).
+      let slotRequestDep = hasAccessInChain;
+      const hasRenderedPage = destMatch && destLeaf?.page;
+      if (slotRequestDep) {
+        // Already marked — skip static analysis
+      } else if (interception) {
+        // `destMatch` walks the slot's ordinary children against the
+        // destination URL; the interception resolver renders an intercepting
+        // child instead, which that walk never sees. So the files analyzed
+        // below are not the files that rendered — and `false` here tells the
+        // client the slot is reusable. Stay conservative: a needlessly
+        // request-dependent slot is a wasted refetch, a wrongly static one is
+        // a stale modal.
+        slotRequestDep = true;
+      } else if (hasRenderedPage) {
+        // Check slot root layout (rendered by wrapWithLayout)
+        if (
+          slotManifest.layout?.filePath &&
+          isStaticRequestDependent(slotManifest.layout.filePath)
+        ) {
+          slotRequestDep = true;
         }
-      }
-
-      // Dynamic match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'dynamic') {
-            found = c;
-            break;
+        // Check intermediate slot layouts
+        if (!slotRequestDep) {
+          for (const seg of destMatch.chain) {
+            if (seg.layout?.filePath && isStaticRequestDependent(seg.layout.filePath)) {
+              slotRequestDep = true;
+              break;
+            }
           }
         }
-      }
-
-      // Catch-all match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'catch-all' || c.segmentType === 'optional-catch-all') {
-            found = c;
-            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);
+        }
       }
-
-      if (!found) {
-        matched = false;
-        break;
-      }
-      chain.push(found);
-      currentNode = found;
-    }
-
-    if (matched && currentNode.page) {
-      return { page: currentNode.page, chain };
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: slotRequestDep,
+        denied: false,
+        contentKey,
+      });
     }
   }
 
-  return null;
+  return slotProps;
 }