@timber-js/app 0.2.0-alpha.187 → 0.2.0-alpha.188

package/src/server/slot-resolver.ts

@@ -33,7 +33,7 @@ import { extractUrlParts, consumedPartsThroughSegment } from './chain-url-parts.
 import { findInterceptingMatch } from './slot-interception.js';
 import { SegmentOutlet } from '../client/segment-outlet.js';
 import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
-import { computeSlotKey } from '../routing/segment-keys.js';
+import { computeSlotKey, computeSlotContentKey } from '../routing/segment-keys.js';
 import { isStaticRequestDependent } from './request-dep.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
@@ -86,8 +86,7 @@ export async function resolveSlotElement(
   match: RouteMatch,
   h: CreateElementFn,
   interception?: InterceptionContext,
-  parentTreePath?: string,
-  accessVerdicts?: SlotAccessVerdict[]
+  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
@@ -176,13 +175,7 @@ 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,
-        accessVerdicts,
-        scope
-      );
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h, scope);
 
       // Wrap with slot root's layout — INSIDE the access gate, so the layout
       // server component never executes when access.ts denies. See TIM-1074.
@@ -195,7 +188,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, accessVerdicts, scope);
+      element = await wrapWithAccessGate(slotNode, element, h, scope);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
@@ -277,7 +270,6 @@ async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
   h: CreateElementFn,
-  accessVerdicts?: SlotAccessVerdict[],
   scope?: SlotParamScope
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
@@ -288,7 +280,7 @@ async function wrapWithIntermediateSegments(
       errorBoundaryComponent: TimberErrorBoundary,
     });
     element = await wrapWithLayout(seg, element, h, scope);
-    element = await wrapWithAccessGate(seg, element, h, accessVerdicts, scope);
+    element = await wrapWithAccessGate(seg, element, h, scope);
   }
   return element;
 }
@@ -361,7 +353,6 @@ async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
   h: CreateElementFn,
-  accessVerdicts?: SlotAccessVerdict[],
   scope?: SlotParamScope
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
@@ -382,16 +373,6 @@ async function wrapWithAccessGate(
 
   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,
@@ -399,7 +380,6 @@ async function wrapWithAccessGate(
     createElement: h,
     defaultFallback,
     children: element,
-    verdict: preVerdict?.verdict,
   });
 }
 
@@ -496,74 +476,6 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
   return { page: leaf.page, chain: result.chain, slotParams: result.params };
 }
 
-// ─── 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[],
-  scope?: SlotParamScope
-): 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 (scope ? scope(() => accessFn()) : 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 {
@@ -579,6 +491,12 @@ export interface SlotSkipEntry {
   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;
 }
 
 /**
@@ -650,7 +568,6 @@ interface ResolveSlotPropsArgs {
   h: CreateElementFn;
   interception?: InterceptionContext;
   parentTreePath: string;
-  departingUrl: string | null;
   destinationUrl: string;
   clientStateTree: ClientStateTree | null;
   slotSkipInfo: SlotSkipEntry[];
@@ -658,9 +575,16 @@ interface ResolveSlotPropsArgs {
 
 /**
  * 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.
+ * 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 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.
  */
 export async function resolveSlotProps({
   segment,
@@ -669,7 +593,6 @@ export async function resolveSlotProps({
   h,
   interception,
   parentTreePath,
-  departingUrl,
   destinationUrl,
   clientStateTree,
   slotSkipInfo,
@@ -678,106 +601,51 @@ export async function resolveSlotProps({
   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;
-
-  const sliceAt = consumedPartsThroughSegment(segment, match).length;
-
-  function splitPathname(pathname: string): string[] {
-    return pathname === '/' ? [] : pathname.slice(1).split('/');
-  }
-
-  const destinationAll = splitPathname(destinationPathname);
-  const departingAll = departingPathname ? splitPathname(departingPathname) : null;
   const destinationParts = slotUrlParts(segment, match, destinationUrl);
-  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]);
-  }
+  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.
-    // 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.
-    let eagerScope: SlotParamScope | undefined;
-    if (destMatch) {
-      const coerced = coerceSlotParams(destMatch.chain, destMatch.params);
-      const fullSlotPath = computeSlotSegmentPath(destMatch.chain, parentTreePath);
-      if (fullSlotPath && Object.keys(coerced).length > 0) {
-        setSlotParams(fullSlotPath, coerced);
-      }
-      // The eager path calls access.ts outside the React tree, so the render
-      // scope in resolveSlotElement cannot cover it. Without this, the same
-      // access.ts would read the main route's params when the slot is a skip
-      // candidate and the slot's own params when it is not.
-      eagerScope = (fn) => runWithSlotSegmentParams(fullSlotPath, coerced, fn);
-    }
+    // 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 ?? {}
+    );
 
-    // 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).
+    // 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 isSkipCandidate =
+    const canSkip =
       !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, eagerScope)
-        : [];
-    const accessBlocked = chainVerdicts.some((v) => v.verdict !== 'pass');
-    const canSkip = isSkipCandidate && !accessBlocked;
+      !hasAccessInChain &&
+      shouldSkipSlot(contentKey, clientSlotKeys);
 
     if (canSkip) {
-      // Access already ran eagerly (all verdicts 'pass') — principle #3 satisfied.
-      // No gate wrapper needed.
+      // No access.ts in this slot's chain (excluded above), so no gate needed.
       slotProps[slotName] = h(SegmentOutlet, {
         segmentPath: slotKey,
         skip: true,
@@ -789,6 +657,7 @@ export async function resolveSlotProps({
         isRequestDependent: false,
         denied: false,
         skipped: true,
+        contentKey,
       });
     } else {
       const resolvedElement = await resolveSlotElement(
@@ -796,8 +665,7 @@ export async function resolveSlotProps({
         match,
         h,
         interception,
-        parentTreePath,
-        chainVerdicts
+        parentTreePath
       );
       slotProps[slotName] = h(SegmentOutlet, {
         segmentPath: slotKey,
@@ -806,10 +674,13 @@ export async function resolveSlotProps({
       // 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];
+      // 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 (interception) {
+      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
@@ -854,7 +725,8 @@ export async function resolveSlotProps({
         slotKey,
         parentSegmentId: segmentId,
         isRequestDependent: slotRequestDep,
-        denied: accessBlocked,
+        denied: false,
+        contentKey,
       });
     }
   }

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

@@ -15,8 +15,6 @@
  */
 
 import { swallow } from './logger.js';
-import { matchUrlParts } from './tree-match.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── State Tree Parsing ──────────────────────────────────────────
 
@@ -112,72 +110,23 @@ export function shouldSkipSegment(
 
 // ─── 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)
+ * A slot is skipped when the destination content key — computed from the
+ * owning segment's URL parts, the slot name, the matched entry file, and
+ * the slot's extracted params — is in the set of keys the client advertised.
  *
- * 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 replaced URL-based departing/destination diffing in TIM-1370.
+ * The previous approach reconstructed the client's state by re-matching a
+ * departing URL against each slot's sub-tree, which was a recurring bug
+ * source because the reconstruction could drift from the client's actual
+ * mounted state. The key-based approach is a single set-membership check.
  *
  * 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;
+export function shouldSkipSlot(contentKey: string, clientSlotKeys: Set<string> | null): boolean {
+  if (!clientSlotKeys) return false;
+  return clientSlotKeys.has(contentKey);
 }

package/src/server/tree-builder.ts

@@ -138,16 +138,6 @@ 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;
 }
 
 // ─── Tree Builder ────────────────────────────────────────────────────────────

package/src/shared/segment-info.ts

@@ -39,6 +39,13 @@ export interface SegmentInfo {
   denied?: boolean;
   /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
   skipped?: boolean;
+  /**
+   * Content key for slot entries — encodes owner parts, slot name, matched
+   * entry file, and slot params. The client stores and advertises this key;
+   * the server computes the destination key and checks membership.
+   * Replaces URL-based departing/destination diffing (TIM-1370).
+   */
+  contentKey?: string;
 }
 
 /**