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

package/src/server/skippable-prefix.ts

@@ -11,7 +11,9 @@ import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
 import { consumedUrlParts } from './chain-url-parts.js';
-import { computeSlotKey } from '../routing/segment-keys.js';
+import { computeSlotContentKey, computeSlotKey } from '../routing/segment-keys.js';
+import { matchUrlParts } from './tree-match.js';
+import { slotUrlParts } from './slot-resolver.js';
 
 /**
  * Truncate the skippable prefix when a skippable layout has slots whose
@@ -22,6 +24,9 @@ import { computeSlotKey } from '../routing/segment-keys.js';
  * Removing the segment from the skippable set forces it to render with
  * its slots. The prefix must stay contiguous, so all segments after the
  * first changed-slot segment are also removed.
+ *
+ * Uses key-based diffing (TIM-1370): computes the destination content key
+ * per slot and checks if the client's advertised set contains it.
  */
 export function truncateSkippableForChangedSlots(
   skippableSet: Set<number>,
@@ -31,23 +36,8 @@ export function truncateSkippableForChangedSlots(
   clientStateTree: ClientStateTree,
   req: Request
 ): void {
-  const departingUrl = req.headers.get('X-Timber-URL');
-  let depParsed: URL | null = null;
-  if (departingUrl) {
-    try {
-      depParsed = new URL(departingUrl, 'http://localhost');
-    } catch {
-      skippableSet.clear();
-      return;
-    }
-  }
-  const destPathname = new URL(req.url, 'http://localhost').pathname;
-  const depPathname = depParsed?.pathname ?? null;
-  const split = (p: string) => (p === '/' ? [] : p.slice(1).split('/'));
-  const destAll = split(destPathname);
-  const depAll = depPathname ? split(depPathname) : null;
-  const clientSlots = clientStateTree.slots ?? null;
-  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const clientSlotKeys = clientStateTree.slots ?? null;
+  const destUrl = req.url;
 
   for (let i = 0; i < segments.length; i++) {
     if (!skippableSet.has(i)) continue;
@@ -56,33 +46,25 @@ export function truncateSkippableForChangedSlots(
     if (slotEntries.length === 0) continue;
 
     const segIdx = match.segments.indexOf(segment);
-    // The root consumes no URL part, and a climbing interception marker
-    // removes owner segments from the target — `consumedUrlParts` handles both,
-    // and is the same derivation slot matching and layout depth use.
-    const sliceAt = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match).length : 0;
-    const destParts = destAll.slice(sliceAt);
-    const depParts = depAll ? depAll.slice(sliceAt) : null;
-    let parentChanged = false;
-    if (depAll) {
-      const dp = depAll.slice(0, sliceAt),
-        dd = destAll.slice(0, sliceAt);
-      parentChanged = dp.length !== dd.length || dp.some((p, j) => p !== dd[j]);
-    }
+    const ownerParts = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match) : [];
+    const destParts = slotUrlParts(segment, match, destUrl);
 
     for (const [slotName, slotNode] of slotEntries) {
       const m = slotNode as ManifestSegmentNode;
       const k = computeSlotKey(segmentKeys[i], `@${slotName}`);
+
+      // Slots with access.ts are never skip candidates (TIM-1364).
+      const destMatch = matchUrlParts(m, destParts);
+      const hasAccessInChain = !!m.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+
+      const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+      const entryFile = destLeaf?.page?.filePath ?? null;
+      const contentKey = computeSlotContentKey(k, ownerParts, entryFile, destMatch?.params ?? {});
+
       if (
+        hasAccessInChain ||
         m.children.some((c) => c.segmentType === 'intercepting') ||
-        parentChanged ||
-        depParts === null ||
-        !shouldSkipSlot({
-          slotKey: k,
-          clientSlots,
-          slotNode: m,
-          departingUrlParts: depParts,
-          destinationUrlParts: destParts,
-        })
+        !shouldSkipSlot(contentKey, clientSlotKeys)
       ) {
         for (let j = i; j < segments.length; j++) skippableSet.delete(j);
         return;

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,10 +188,14 @@ 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, h);
+      element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
+        loadModule,
+        createElement: h,
+        errorBoundaryComponent: TimberErrorBoundary,
+      });
 
       // Catch-all error boundary: ensures slot errors NEVER propagate to the
       // parent layout. Without this, a slot without error.tsx that throws
@@ -273,14 +270,17 @@ 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--) {
     const seg = chain[i];
-    element = await wrapSegmentWithErrorBoundaries(seg, element, h);
+    element = await wrapSegmentWithErrorBoundaries(seg, element, {
+      loadModule,
+      createElement: h,
+      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;
 }
@@ -353,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;
@@ -374,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,
@@ -391,7 +380,6 @@ async function wrapWithAccessGate(
     createElement: h,
     defaultFallback,
     children: element,
-    verdict: preVerdict?.verdict,
   });
 }
 
@@ -488,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 {
@@ -571,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;
 }
 
 /**
@@ -642,7 +568,6 @@ interface ResolveSlotPropsArgs {
   h: CreateElementFn;
   interception?: InterceptionContext;
   parentTreePath: string;
-  departingUrl: string | null;
   destinationUrl: string;
   clientStateTree: ClientStateTree | null;
   slotSkipInfo: SlotSkipEntry[];
@@ -650,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,
@@ -661,7 +593,6 @@ export async function resolveSlotProps({
   h,
   interception,
   parentTreePath,
-  departingUrl,
   destinationUrl,
   clientStateTree,
   slotSkipInfo,
@@ -670,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,
@@ -781,6 +657,7 @@ export async function resolveSlotProps({
         isRequestDependent: false,
         denied: false,
         skipped: true,
+        contentKey,
       });
     } else {
       const resolvedElement = await resolveSlotElement(
@@ -788,8 +665,7 @@ export async function resolveSlotProps({
         match,
         h,
         interception,
-        parentTreePath,
-        chainVerdicts
+        parentTreePath
       );
       slotProps[slotName] = h(SegmentOutlet, {
         segmentPath: slotKey,
@@ -798,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
@@ -846,7 +725,8 @@ export async function resolveSlotProps({
         slotKey,
         parentSegmentId: segmentId,
         isRequestDependent: slotRequestDep,
-        denied: accessBlocked,
+        denied: false,
+        contentKey,
       });
     }
   }

package/src/server/ssr-bridge-types.ts

@@ -70,6 +70,18 @@ export interface NavContext {
   /** Request cookies as name→value pairs. Used by useCookie() during SSR
    *  to return correct cookie values before hydration. */
   cookies?: Map<string, string>;
+  /**
+   * Lazy thunk that produces the `<script>self.__timber_segments=…</script>`
+   * tag. Invoked by the SSR entry AFTER `renderSsrNodeStream` /
+   * `renderSsrStream` returns (shell ready ⇒ AccessGates settled), so the
+   * `getFirstDeniedSegmentIndex()` ALS value is authoritative. The result
+   * is appended to headHtml before the head injector runs.
+   *
+   * Undefined when client JS is disabled (no client to consume it).
+   * See TIM-1365, TIM-1359.
+   */
+  getHeadSegmentScript?: () => string;
+
   /**
    * Mutable flag: set by TimberErrorBoundary during SSR when it catches
    * a DenySignal (via digest). This tells the RSC entry that the denial

package/src/server/ssr-entry.ts

@@ -14,10 +14,6 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-// TIM-830: Populate the search-params registry eagerly so <Link> rendered
-// during SSR can serialize flat `Partial<T>` values via registry lookup.
-// @ts-expect-error — virtual module provided by timber-routing plugin
-import 'virtual:timber-search-params-registry';
 // TIM-949: Populate the codec registry so server-rendered <Link> components
 // use codec.serialize() instead of String() fallback for URL interpolation.
 // @ts-expect-error — virtual module provided by timber-routing plugin
@@ -236,8 +232,11 @@ export async function handleSsr(
         // stage: pipeline() destroys every stage on failure, so only an
         // output kept outside the pipeline can append the noindex script
         // and close cleanly (TIM-1019).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
         const bufferedTransform = createNodeBufferedTransform();
-        const headInjector = createNodeHeadInjector(navContext.headHtml);
+        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream, {
           renderTimeoutMs,
           errorSignal: navContext._errorSignal,
@@ -296,8 +295,11 @@ export async function handleSsr(
       // HTML fragments so downstream transforms never see chunk boundaries
       // mid-tag. This prevents RSC script injection from breaking HTML
       // structure (TIM-527).
+      // Resolve the lazy segment script now that the shell is ready
+      // (AccessGates have settled, ALS deny index is authoritative).
+      const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
       let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
-      outputStream = injectHead(outputStream, navContext.headHtml);
+      outputStream = injectHead(outputStream, resolvedHeadHtml);
       outputStream = injectRscPayload(
         outputStream,
         navContext.rscStream,

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);
 }