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

package/src/server/rsc-entry/rsc-payload.ts

@@ -14,6 +14,7 @@ import type { RouteMatch } from '../pipeline.js';
 import type { RedirectSignal } from '../primitives.js';
 import type { LayoutComponentEntry } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { SlotSkipEntry } from '../slot-resolver.js';
 
 import {
   buildRedirectResponse,
@@ -21,6 +22,7 @@ import {
   createDebugChannelSink,
   RSC_CONTENT_TYPE,
 } from './helpers.js';
+import { requestContextAls } from '../als-registry.js';
 import type { RenderSignals } from './rsc-stream.js';
 
 /**
@@ -40,7 +42,8 @@ export async function buildRscPayloadResponse(
   layoutComponents: LayoutComponentEntry[],
   match: RouteMatch,
   responseHeaders: Headers,
-  skippedSegments?: string[]
+  skippedSegments?: string[],
+  slotSkipInfo?: SlotSkipEntry[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
   // Race the first read against signal detection — if an async component
@@ -194,9 +197,19 @@ export async function buildRscPayloadResponse(
   // client rendering. No X-Timber-Head header needed. See TIM-1151.
 
   // Send segment metadata so the client can populate its segment cache
-  // for state tree diffing on subsequent navigations.
+  // for state tree diffing on subsequent navigations. On the RSC payload
+  // path, taint results are available because the shell has rendered by
+  // the time we reach this point (first chunk already read from the stream).
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const segmentInfo = buildSegmentInfo(segments, layoutComponents);
+  const store = requestContextAls.getStore();
+  const segmentInfo = buildSegmentInfo(
+    segments,
+    layoutComponents,
+    slotSkipInfo,
+    store?.taintResults,
+    store?.orphanTaint,
+    skippedSegments
+  );
   responseHeaders.set('X-Timber-Segments', JSON.stringify(segmentInfo));
 
   // Send skipped segments so the client can merge the partial RSC payload

package/src/server/rsc-entry/ssr-renderer.ts

@@ -20,6 +20,7 @@ import type { RouteMatch } from '../pipeline.js';
 import { SsrStreamError } from '../primitives.js';
 import type { LayoutComponentEntry } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { SlotSkipEntry } from '../slot-resolver.js';
 import type { NavContext } from '../ssr-bridge-types.js';
 
 import { htmlEscapeJsonString } from '../flight-scripts.js';
@@ -100,6 +101,7 @@ interface SsrRenderOptions {
   deferSuspenseFor: number;
   /** Tier 2 global-error.tsx file, if present in app/. */
   globalError?: GlobalErrorFile;
+  slotSkipInfo?: SlotSkipEntry[];
 }
 
 /**
@@ -168,7 +170,7 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   // Skipped when client JS is disabled — no client JS to consume it.
   const segmentScript = clientJsDisabled
     ? ''
-    : `<script>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents)))}</script>`;
+    : `<script>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents, opts.slotSkipInfo)))}</script>`;
 
   // Embed route params in HTML so useSegmentParams() works on initial hydration.
   // Without this, useSegmentParams() returns {} until the first client navigation.

package/src/server/slot-resolver.ts

@@ -29,6 +29,9 @@ 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 { runInTaintScope } from './request-context.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 
@@ -49,14 +52,26 @@ async function loadComponent(loader: {
 /**
  * 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.
+ *
+ * When taintKey is provided, wraps the component in a taint scope so
+ * accessor calls (getHeaders, cookies, etc.) inside the default.tsx
+ * are attributed to this slot instead of poisoning orphanTaint.
  */
 async function renderDefaultFallback(
   slotNode: ManifestSegmentNode,
-  h: CreateElementFn
+  h: CreateElementFn,
+  taintKey?: string
 ): Promise<React.ReactElement | null> {
   if (!slotNode.default) return null;
   const DefaultComp = await loadComponent(slotNode.default);
   if (!DefaultComp) return null;
+  if (taintKey && !isClientReference(DefaultComp)) {
+    const TaintedDefault = async (props: Record<string, unknown>) =>
+      runInTaintScope(taintKey, () =>
+        (DefaultComp as (props: Record<string, unknown>) => unknown)(props)
+      );
+    return h(TaintedDefault, {});
+  }
   return h(DefaultComp, {});
 }
 
@@ -80,7 +95,9 @@ export async function resolveSlotElement(
   match: RouteMatch,
   h: CreateElementFn,
   interception?: InterceptionContext,
-  parentTreePath?: string
+  parentTreePath?: string,
+  accessVerdicts?: SlotAccessVerdict[],
+  taintKey?: 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
@@ -115,7 +132,7 @@ export async function resolveSlotElement(
       // 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"
-      const denyFallback = await renderDefaultFallback(slotNode, h);
+      const denyFallback = await renderDefaultFallback(slotNode, h, taintKey);
 
       // Build the slot page element.
       // Client references ('use client' pages) must NOT be called as functions —
@@ -131,9 +148,11 @@ export async function resolveSlotElement(
       if (isClientReference(SlotPage)) {
         element = h(SlotPage, {});
       } else {
+        const slotTaintKey = taintKey;
         const SafeSlotPage = async (props: Record<string, unknown>) => {
+          const run = async () => (SlotPage as (props: Record<string, unknown>) => unknown)(props);
           try {
-            return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
+            return slotTaintKey ? await runInTaintScope(slotTaintKey, run) : await run();
           } catch (error) {
             // RedirectSignal must propagate — the pipeline handles redirects
             // at the top level. Swallowing it here would silently return
@@ -161,7 +180,13 @@ export async function resolveSlotElement(
       // 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);
+      element = await wrapWithIntermediateSegments(
+        slotMatch.chain,
+        element,
+        h,
+        accessVerdicts,
+        taintKey
+      );
 
       // Wrap with slot root's layout — INSIDE the access gate, so the layout
       // server component never executes when access.ts denies. See TIM-1074.
@@ -174,7 +199,7 @@ export async function resolveSlotElement(
       // 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);
+      element = await wrapWithAccessGate(slotNode, element, h, accessVerdicts, taintKey);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -196,8 +221,12 @@ export async function resolveSlotElement(
     }
   }
 
-  // No matching page — render default.tsx fallback
-  return renderDefaultFallback(slotNode, h);
+  // 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
+  // slot instead of poisoning orphanTaint for the entire request.
+  return renderDefaultFallback(slotNode, h, taintKey);
 }
 
 // ─── Element Wrapping Helpers ───────────────────────────────────────────────
@@ -221,13 +250,15 @@ export async function resolveSlotElement(
 async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
-  h: CreateElementFn
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[],
+  taintKey?: string
 ): 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);
+    element = await wrapWithAccessGate(seg, element, h, accessVerdicts, taintKey);
   }
   return element;
 }
@@ -253,7 +284,9 @@ async function wrapWithLayout(
 async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
-  h: CreateElementFn
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[],
+  taintKey?: string
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
 
@@ -270,7 +303,17 @@ async function wrapWithAccessGate(
   // Extract slot name from the directory name (strip @ prefix)
   const slotName = slotNode.segmentName?.replace(/^@/, '') ?? '';
 
-  const defaultFallback = await renderDefaultFallback(slotNode, h);
+  const defaultFallback = await renderDefaultFallback(slotNode, h, taintKey);
+
+  // 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,
@@ -279,6 +322,7 @@ async function wrapWithAccessGate(
     createElement: h,
     defaultFallback,
     children: element,
+    verdict: preVerdict?.verdict,
   });
 }
 
@@ -439,3 +483,268 @@ function findInterceptingMatch(
 
   return null;
 }
+
+// ─── 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;
+}
+
+/**
+ * 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 [];
+
+  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;
+      }
+      // 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;
+}
+
+interface ResolveSlotPropsArgs {
+  segment: ManifestSegmentNode;
+  segmentId: string;
+  match: RouteMatch;
+  h: CreateElementFn;
+  interception?: InterceptionContext;
+  parentTreePath: string;
+  departingUrl: string | null;
+  destinationUrl: string;
+  clientStateTree: ClientStateTree | null;
+  slotSkipInfo: SlotSkipEntry[];
+}
+
+/**
+ * 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('/');
+  }
+
+  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 =
+      destMatch !== null &&
+      !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
+      ? 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,
+      });
+      // Skipped slots don't render, so they're not request-dependent.
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: false,
+        denied: false,
+      });
+    } else {
+      const resolvedElement = await resolveSlotElement(
+        slotManifest,
+        match,
+        h,
+        interception,
+        parentTreePath,
+        chainVerdicts,
+        slotKey
+      );
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        children: resolvedElement,
+      });
+      // Conservative pre-render default: true. Overridden by taint
+      // results in buildSegmentInfo() after renderToReadableStream
+      // completes — runInTaintScope records whether the slot page
+      // actually called getHeaders/cookies/getSearchParams.
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: true,
+        denied: accessBlocked,
+      });
+    }
+  }
+
+  return slotProps;
+}

package/src/server/state-tree-diff.ts

@@ -15,6 +15,8 @@
  */
 
 import { swallow } from './logger.js';
+import { matchUrlParts } from './tree-match.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── Segment Key Computation ─────────────────────────────────────
 
@@ -59,27 +61,48 @@ export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
   return keys;
 }
 
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}
+
 // ─── State Tree Parsing ──────────────────────────────────────────
 
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+  slots?: Set<string> | null;
+}
+
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
- * Returns a Set of segment paths the client has cached, or null if
+ * Returns a Set of segment paths the client has cached (with an
+ * additional `slots` property for cached slot paths), or null if
  * the header is missing, malformed, or empty. Parsing happens before
  * renderToReadableStream — not inside the React render pass.
  *
- * @returns Set of sync segment paths, or null if no valid state tree
+ * @returns ClientStateTree with segments and slots, or null if no valid state tree
  */
-export function parseClientStateTree(req: Request): Set<string> | null {
+export function parseClientStateTree(req: Request): ClientStateTree | null {
   const header = req.headers.get('X-Timber-State-Tree');
   if (!header) return null;
 
   try {
-    const parsed = JSON.parse(header) as { segments?: unknown };
+    const parsed = JSON.parse(header) as { segments?: unknown; slots?: unknown };
     if (!Array.isArray(parsed.segments) || parsed.segments.length === 0) {
       return null;
     }
-    return new Set(parsed.segments as string[]);
+    const result = new Set(parsed.segments as string[]) as ClientStateTree;
+    result.slots =
+      Array.isArray(parsed.slots) && parsed.slots.length > 0
+        ? new Set(parsed.slots as string[])
+        : null;
+    return result;
   } catch (err) {
     swallow(err, 'malformed X-Timber-State-Tree header');
     return null;
@@ -120,10 +143,83 @@ export function shouldSkipSegment(
   if (!layoutComponent) return false;
   if (isLeaf) return false;
 
-  // Async layouts always re-render — they may depend on per-request data
-  // (cookies, headers, database queries) that changes between navigations.
-  // constructor.name check: AsyncFunction.name === 'AsyncFunction'
+  // Pre-render guard: async layouts may depend on per-request data.
+  // Taint tracking (runInTaintScope) handles the post-render client-side
+  // caching decision via X-Timber-Segments. This server-side check remains
+  // conservative because taint results aren't available at element-build time.
   if (layoutComponent.constructor.name === 'AsyncFunction') return false;
 
   return true;
 }
+
+// ─── Slot Skip Decision ─────────────────────────────────────────
+
+interface ShouldSkipSlotArgs {
+  slotKey: string;
+  clientSlots: Set<string> | null;
+  slotNode: ManifestSegmentNode;
+  departingUrlParts: string[];
+  destinationUrlParts: string[];
+}
+
+/**
+ * Determine whether a parallel route slot can be skipped.
+ *
+ * A slot is skipped when ALL of:
+ * 1. The client has this slot cached (slotKey is in clientSlots)
+ * 2. The slot's matched page is the SAME for both the departing and
+ *    destination URLs (same page file + same extracted params)
+ *
+ * The comparison uses matchUrlParts to find what each URL would match
+ * in the slot's sub-tree, then compares the matched page file and params.
+ *
+ * This is a performance optimization only, NOT a security boundary.
+ * Slot access.ts always runs via SlotAccessGate regardless.
+ */
+export function shouldSkipSlot({
+  slotKey,
+  clientSlots,
+  slotNode,
+  departingUrlParts,
+  destinationUrlParts,
+}: ShouldSkipSlotArgs): boolean {
+  if (!clientSlots) return false;
+  if (!clientSlots.has(slotKey)) return false;
+
+  const departingMatch = matchUrlParts(slotNode, departingUrlParts);
+  const destinationMatch = matchUrlParts(slotNode, destinationUrlParts);
+
+  // Both null (no match) — slot shows default.tsx in both cases
+  if (!departingMatch && !destinationMatch) return true;
+  // One null, one not — match changed
+  if (!departingMatch || !destinationMatch) return false;
+
+  const departingLeaf = departingMatch.chain[departingMatch.chain.length - 1];
+  const destinationLeaf = destinationMatch.chain[destinationMatch.chain.length - 1];
+
+  // Both must have a page, and the page file must be the same
+  if (!departingLeaf.page || !destinationLeaf.page) {
+    return !departingLeaf.page && !destinationLeaf.page;
+  }
+  if (departingLeaf.page.filePath !== destinationLeaf.page.filePath) return false;
+
+  // Compare extracted params — if any differ, the slot content may change
+  return paramsEqual(departingMatch.params, destinationMatch.params);
+}
+
+function paramsEqual(
+  a: Record<string, string | string[]>,
+  b: Record<string, string | string[]>
+): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    const va = a[key];
+    const vb = b[key];
+    if (Array.isArray(va) && Array.isArray(vb)) {
+      if (va.length !== vb.length || va.some((v, i) => v !== vb[i])) return false;
+    } else if (va !== vb) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/server/tree-builder.ts

@@ -180,6 +180,16 @@ export interface SlotAccessGateProps {
   createElement: CreateElement;
   defaultFallback: ReactNode;
   children: ReactNode;
+  /**
+   * Pre-computed verdict from eager access evaluation. When provided,
+   * SlotAccessGate replays it synchronously instead of re-calling accessFn.
+   * 'pass' → render children. DenySignal → graceful degradation.
+   * undefined → call accessFn during render (backward compat, error re-run).
+   */
+  verdict?:
+    | 'pass'
+    | import('./primitives.js').DenySignal
+    | import('./primitives.js').RedirectSignal;
 }
 
 /**