@rangojs/router 0.17.0 → 0.19.0

package/src/router/instrument.ts

@@ -28,7 +28,14 @@
  * is a direct call — no wrapper, no timestamp, no allocation.
  */
 
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import {
+  recordTagOwnersArmed,
+  runInSegmentTagScope,
+} from "../cache/cache-tag.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { getRouterContext } from "./router-context.js";
 import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
@@ -352,11 +359,56 @@ export function observeHandler<C, R>(
   handler: (ctx: C) => R,
   ctx: C,
 ): R {
-  const tracing = _getRequestContext()?._tracing;
+  return observeHandlerIn(_getRequestContext(), id, handler, ctx);
+}
+
+function observeHandlerIn<C, R>(
+  reqCtx: RequestContext | undefined,
+  id: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const tracing = reqCtx?._tracing;
   if (!tracing || tracing.phases.handler === false) return handler(ctx);
   return observePhase(PHASES.handler(id), () => handler(ctx));
 }
 
+/**
+ * observeHandler, inside segment `segmentId`'s tag scope, so the tags the
+ * handler records reach the route's cache() record (#957, cache-tag.ts
+ * runInSegmentTagScope). `spanId` is observeHandler's `id`. A request that
+ * cannot write a record takes observeHandler's path as is, with the same one
+ * request-context read: no scope, no closure.
+ */
+export function observeSegmentHandler<C, R>(
+  segmentId: string,
+  spanId: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const reqCtx = _getRequestContext();
+  if (!recordTagOwnersArmed(reqCtx)) {
+    return observeHandlerIn(reqCtx, spanId, handler, ctx);
+  }
+  return observeInSegmentScope(segmentId, reqCtx, spanId, handler, ctx);
+}
+
+// Separate from observeSegmentHandler: a closure there would make V8
+// allocate its captured-variable context on every call, armed or not.
+function observeInSegmentScope<C, R>(
+  segmentId: string,
+  reqCtx: RequestContext | undefined,
+  spanId: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  return runInSegmentTagScope(
+    segmentId,
+    (c) => observeHandlerIn(reqCtx, spanId, handler, c),
+    ctx,
+  );
+}
+
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

package/src/router/intercept-resolution.ts

@@ -32,6 +32,7 @@ import { resolveLoaderData } from "./segment-resolution/loader-cache.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
 import { getRouterContext } from "./router-context.js";
+import { runInSegmentTagScope } from "../cache/cache-tag.js";
 import {
   RangoContext,
   latchPprHeaderScopeForEntries,
@@ -63,6 +64,8 @@ function latchPprHeaderScopeForInterceptTarget(
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
  * If no when() conditions are defined, the intercept always activates.
+ * A selector that throws yields the conservative default, no intercept (the
+ * full page renders), and is logged; it never fails the request.
  *
  * During action revalidation, when() is NOT evaluated.
  */
@@ -83,7 +86,15 @@ export function evaluateInterceptWhen(
     return false;
   }
 
-  return intercept.when.every((fn) => fn(selectorContext));
+  try {
+    return intercept.when.every((fn) => fn(selectorContext));
+  } catch (error) {
+    console.error(
+      `[rango] intercept({ when }) for route "${selectorContext.to.routeName ?? intercept.routeName}" (${intercept.slotName}) threw; rendering the full page without the intercept.`,
+      error,
+    );
+    return false;
+  }
 }
 
 /**
@@ -332,12 +343,18 @@ export async function resolveInterceptEntry<TEnv>(
     );
   }
 
+  // The intercept segment's id, and the tag scope its handler and layout
+  // record in (#957, cache-tag.ts runInSegmentTagScope).
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
   let handlerResult: ReactNode;
   try {
+    const handler = interceptEntry.handler;
     handlerResult =
-      typeof interceptEntry.handler === "function"
-        ? handleHandlerResult(interceptEntry.handler(context))
-        : interceptEntry.handler;
+      typeof handler === "function"
+        ? handleHandlerResult(
+            runInSegmentTagScope(slotSegmentId, handler, context),
+          )
+        : handler;
   } catch (error) {
     handlerResult = renderInterceptHandlerError(
       error,
@@ -355,14 +372,19 @@ export async function resolveInterceptEntry<TEnv>(
 
   let layoutElement: ReactNode | undefined;
   if (interceptEntry.layout) {
-    if (typeof interceptEntry.layout === "function") {
-      const layoutResult = await interceptEntry.layout(context);
+    const layout = interceptEntry.layout;
+    if (typeof layout === "function") {
+      const layoutResult = await runInSegmentTagScope(
+        slotSegmentId,
+        layout,
+        context,
+      );
       if (layoutResult instanceof Response) {
         throw layoutResult;
       }
       layoutElement = layoutResult;
     } else {
-      layoutElement = interceptEntry.layout;
+      layoutElement = layout;
     }
   }
 
@@ -413,7 +435,7 @@ export async function resolveInterceptEntry<TEnv>(
   }
 
   const interceptSegment = {
-    id: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+    id: slotSegmentId,
     namespace: `intercept:${interceptEntry.routeName}`,
     type: "parallel" as const,
     index: 0,

package/src/router/loader-resolution.ts

@@ -9,6 +9,16 @@ import type { EntryData } from "../server/context";
 import { observePhase, PHASES } from "./instrument.js";
 import { contextGet, isNonCacheable } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import {
+  linkLoaderTags,
+  linkRecordedTags,
+  linkValueTags,
+  loaderTagSetsArmed,
+  markTagSetStart,
+  readValueTags,
+  tagLoaderValue,
+} from "../cache/cache-tag.js";
+import { executionStart } from "../cache/tag-invalidation.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -388,6 +398,18 @@ function createLoaderExecutor<TEnv>(
      * payload's handle-stream lifetime.
      */
     silentHandles?: boolean;
+    /**
+     * A stale refresh's executor (setupLoaderAccess _runLoaderIsolated): its
+     * runs' pushes are diverted from the page's store, so a run's end says
+     * nothing about the page's replayed values (HandleStore.settleLoaderRun).
+     */
+    detached?: boolean;
+    /**
+     * loaderId -> the cache() tags of that loader's binding in this request
+     * (setupLoaderAccess _bindLoaderCacheTags): an execution of it outside
+     * the binding answers for them too (#964).
+     */
+    bindingTags?: ReadonlyMap<string, Set<string>>;
   },
 ): (
   loader: LoaderDefinition<any, any>,
@@ -396,6 +418,8 @@ function createLoaderExecutor<TEnv>(
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
   const reqCtxRef = _getRequestContext();
   const silentHandles = executorOptions?.silentHandles === true;
+  // A run's end reports to the page's store only when its pushes reach it.
+  const reportsRunEnd = !silentHandles && executorOptions?.detached !== true;
   const internal = ctx as InternalHandlerContext<any, TEnv>;
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
@@ -438,8 +462,24 @@ function createLoaderExecutor<TEnv>(
     // loader's cache() read-through lives in loader-cache.ts
     // (executeLoaderData), whose ctx.use override serves a later handler read
     // the binding's result.
-    if (loaderPromises.has(loader.$$id)) {
-      return loaderPromises.get(loader.$$id)!;
+    //
+    // A read is a consumption: the value bakes into the reader's output, so
+    // the loader's tags follow the reader onto a cache() record (#957) and
+    // into the reader's own loader-cache entry (#964, readValueTags; armed
+    // only where a loader cache() can read them).
+    const reqCtx = reqCtxRef ?? _getRequestContext();
+    linkLoaderTags(loader.$$id, reqCtx);
+    const recordTags = loaderTagSetsArmed(reqCtx);
+    // A loader body reads a cache()-bound loader through its binding too, so
+    // every reader in the request gets the one value a HIT served. The
+    // binding's own MISS (callerLoaderId null) runs the loader below.
+    const bound =
+      callerLoaderId !== null &&
+      internal._loaderCacheOverrides?.get(loader.$$id);
+    const memo = bound || loaderPromises.get(loader.$$id);
+    if (memo) {
+      if (recordTags) readValueTags(memo);
+      return memo;
     }
 
     // Get loader function - either from loader object or fetchable registry
@@ -534,7 +574,7 @@ function createLoaderExecutor<TEnv>(
           return collectHandleData(keyOrVar, snapshot, segmentOrder);
         }
         if (isNonCacheable(variables, keyOrVar)) {
-          assertNonCacheableReadAllowed(keyOrVar);
+          assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
         }
         return contextGet(variables, keyOrVar);
       }) as typeof ctx.get,
@@ -680,42 +720,39 @@ function createLoaderExecutor<TEnv>(
     // does not grant rendered() to handler-invoked loaders. Uses a body-only
     // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
     //
-    // `handlerInvoked` (!isDslLoader) rides on the scope for the CONSUMPTION-
-    // LANE RULE: a handler-consumed loader's value is a BAKED copy in every
-    // shared artifact (cache(), "use cache", the PPR shell), so its identity
-    // reads are exempt from the shell-capture guard — same allowance the
-    // cache-purity guards give it. DSL segment loaders keep their lane
-    // machinery (live = masked at capture, bake = guarded). A DSL loader's
-    // nested deps inherit isDslLoader=false only when the CHAIN started in a
-    // handler; a chain started by the segment funnel stays DSL (the loader
-    // scope ALS survives the body's awaits).
-    // Shell fast path eligibility: a HANDLER-invoked loader executing during a
-    // capture is handler-layer dynamism — on a handler-free (replayed) HIT it
-    // would never re-run, freezing its consumption-lane value (#672's "fresh
-    // per serve" slot shape). Mark the capture; the entry declines the fast
-    // path and keeps the full tail. DSL loaders re-run on every HIT and never
-    // set this.
-    if (!isDslLoader) {
-      const captureCtx = _getRequestContext();
-      if (
-        captureCtx?._shellCaptureRun &&
-        captureCtx._shellCaptureHandleLiveness
-      ) {
-        captureCtx._shellCaptureHandleLiveness.handlerInvokedLoader = true;
-      }
-    }
-
+    // The CONSUMPTION-LANE RULE: a handler-consumed loader's value is a
+    // BAKED copy in every shared artifact (cache(), "use cache", the PPR
+    // shell). The cache() guard permits its identity reads; a "use cache"
+    // body it was entered in and a PPR capture do not (server/context.ts
+    // guardIdentityRead).
+
+    const recordedTags = recordTags ? new Set<string>() : undefined;
+    // A loader-cache write that stores or reads this value gates on the
+    // earliest start behind it (#977, earliestRecordedStart).
+    if (recordedTags) markTagSetStart(recordedTags, executionStart());
+    const runEndStore = reportsRunEnd
+      ? (reqCtxRef ?? _getRequestContext())?._handleStore
+      : undefined;
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(
           () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
           loader.$$id,
-          !isDslLoader,
+          recordedTags,
         ),
       ).finally(() => {
         pendingLoaders.delete(loader.$$id);
+        // Its pushes are made: values replayed for it that none replaced
+        // go (a hole that throws or skips its push shows none).
+        runEndStore?.settleLoaderRun(loader.$$id);
       }),
     );
+    if (recordedTags) {
+      tagLoaderValue(promise, recordedTags);
+      readValueTags(promise);
+      const bindingTags = executorOptions?.bindingTags?.get(loader.$$id);
+      if (bindingTags) linkRecordedTags(recordedTags, bindingTags);
+    }
 
     // Auxiliary-lane tracking: keeps the handle store open for this body's
     // ctx.handle() pushes without joining `settled` (the handler barrier that
@@ -759,8 +796,6 @@ export function setupLoaderAccess<TEnv>(
   const reqCtxRef = _getRequestContext();
   const handleStoreRef = reqCtxRef?._handleStore;
 
-  const useLoader = createLoaderExecutor(ctx, loaderPromises);
-
   // Loader-cache HIT replay (loader-cache.ts replayLoaderHandles): a cached
   // entry records its ctx.use dependencies' pushes too, and a dependency is
   // memoized here and shared with live readers. A loader that already ran
@@ -773,12 +808,33 @@ export function setupLoaderAccess<TEnv>(
     claimed.add(loaderId);
     return true;
   };
+  // A loader cache() binding's tags reach every execution of that loader
+  // outside the binding: one a reader started before the binding (linked
+  // here), a later one, or a refresh's (bindingTags).
+  const executor: { bindingTags?: Map<string, Set<string>> } = {};
+  internal._bindLoaderCacheTags = (loaderId, tags) => {
+    (executor.bindingTags ??= new Map()).set(loaderId, tags);
+    const started = loaderPromises.get(loaderId);
+    if (started) linkValueTags(started, tags);
+  };
+  const useLoader = createLoaderExecutor(ctx, loaderPromises, executor);
   // A refresh's pushes are diverted, so its loader ctxs never claim
-  // (cache-runtime.ts refreshView).
+  // (cache-runtime.ts refreshView). It reads each loader fresh, not through
+  // the page's bindings: a stale refresh must not rebuild its entry from
+  // another stale entry.
   internal._runLoaderIsolated = (loader) =>
     createLoaderExecutor(
-      Object.create(ctx, { _claimLoaderPushes: { value: undefined } }),
+      Object.create(ctx, {
+        _claimLoaderPushes: { value: undefined },
+        _loaderCacheOverrides: { value: undefined },
+      }),
       new Map(),
+      {
+        get bindingTags() {
+          return executor.bindingTags;
+        },
+        detached: true,
+      },
     )(loader, null);
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {

package/src/router/logging.ts

@@ -1,3 +1,4 @@
+import { requestHeaders } from "../server/request-headers.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
@@ -61,10 +62,11 @@ function nextId(prefix: string, counter: number): string {
 }
 
 function getHeaderRequestId(request: Request): string | null {
+  const headers = requestHeaders(request);
   const candidate =
-    request.headers.get("x-rsc-router-request-id") ??
-    request.headers.get("x-request-id") ??
-    request.headers.get("cf-ray");
+    headers.get("x-rsc-router-request-id") ??
+    headers.get("x-request-id") ??
+    headers.get("cf-ray");
   if (!candidate) return null;
   const trimmed = candidate.trim();
   return trimmed.length > 0 ? trimmed : null;

package/src/router/match-api.ts

@@ -1,8 +1,14 @@
+import { requestHeaders } from "../server/request-headers.js";
 import {
   CacheScope,
   createCacheScope,
   resolveShellImplicitCacheScope,
 } from "../cache/cache-scope.js";
+import { armLoaderTagSets, armRecordTagOwners } from "../cache/cache-tag.js";
+import {
+  bindsLoaderCache,
+  routeLoaderLanes,
+} from "./segment-resolution/loader-cache.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -35,8 +41,7 @@ import {
   _getRequestContext,
   setRequestContextPrevRouteKey,
 } from "../server/request-context.js";
-import { isAutoGeneratedRouteName } from "../route-name.js";
-import type { DefaultRouteName } from "../types/global-namespace.js";
+import { publicRouteName } from "../route-name.js";
 import { debugLog, debugWarn } from "./logging.js";
 import {
   resolveRoute,
@@ -60,7 +65,7 @@ export async function createMatchContextForFull<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const isHmr = !!request.headers.get("X-RSC-HMR");
+  const isHmr = !!requestHeaders(request).get("X-RSC-HMR");
   // HMR: clear the manifest cache so stale handler references are discarded.
   if (isHmr) {
     clearManifestCache();
@@ -150,6 +155,26 @@ export async function createMatchContextForFull<TEnv>(
     Store.metrics = metricsStore;
   }
 
+  // A shell capture's implicit doc scope, or a document HIT tail's (which
+  // replaces any route-derived scope: the tail replays the shell's doc
+  // record), or else the route's own scope.
+  const cacheScope = resolveShellImplicitCacheScope(snapshot.cacheScope);
+  // A scope means a route cache() record may be written: arm its tag owners
+  // before any handler runs (#957). A document HIT tail writes no record and
+  // runs no handler, so it arms nothing. A loader bound with its own cache()
+  // needs the per-execution loader tag sets before any loader runs (#964):
+  // loaders still run on a HIT.
+  if (cacheScope && !_getRequestContext()?._shellImplicitCache?.docTail) {
+    armRecordTagOwners();
+  }
+  if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
+  // A shell capture credits a push under a live-lane loader's body to that
+  // loader (shell-capture.ts deriveShellCaptureContext). The lanes are set
+  // before any loader runs: a bake-lane loader can start a later one.
+  if (reqCtx?._shellCaptureRun) {
+    reqCtx._shellCaptureLoaderLanes = routeLoaderLanes(snapshot.entries);
+  }
+
   return {
     request,
     url: cleanUrl,
@@ -172,23 +197,23 @@ export async function createMatchContextForFull<TEnv>(
     metricsStore,
     Store,
     interceptContextMatch: null,
-    interceptSelectorContext: {
-      from: cleanUrl,
-      to: cleanUrl,
-      params: matched.params,
-      request,
-      env,
-      segments: { path: [], ids: [] },
-      toRouteName:
-        matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-          ? (matched.routeKey as DefaultRouteName)
-          : undefined,
-    },
+    interceptSelectorContext: (() => {
+      const here = {
+        url: cleanUrl,
+        params: matched.params,
+        routeName: publicRouteName(matched.routeKey),
+      };
+      return {
+        from: here,
+        to: here,
+        request,
+        env,
+        segments: { path: [], ids: [] },
+      };
+    })(),
     isSameRouteNavigation: false,
     interceptResult: null,
-    // Shell fast path: a capture or an eligible document/navigation HIT may
-    // substitute an implicit doc-level scope (a route-derived scope wins).
-    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
+    cacheScope,
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
@@ -217,7 +242,7 @@ export async function createMatchContextForPartial<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const isHmr = !!request.headers.get("X-RSC-HMR");
+  const isHmr = !!requestHeaders(request).get("X-RSC-HMR");
 
   // HMR: clear manifest cache so stale handler references are discarded
   if (isHmr) {
@@ -335,31 +360,27 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  setRequestContextPrevRouteKey(
-    nav.effectiveFromMatch?.routeKey,
-    nav.effectiveFromUrl,
-    nav.effectiveFromMatch?.params ?? nav.prevParams,
-  );
+  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
 
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: nav.effectiveFromUrl,
-    to: cleanUrl,
-    params: matched.params,
+    // The source's params come from matching its URL (the intercept source
+    // while one is open), like its route name.
+    from: {
+      url: nav.effectiveFromUrl,
+      params: nav.effectiveFromMatch?.params ?? {},
+      routeName: publicRouteName(nav.effectiveFromMatch?.routeKey),
+    },
+    to: {
+      url: cleanUrl,
+      params: matched.params,
+      routeName: publicRouteName(matched.routeKey),
+    },
     request,
     env,
     segments: {
       path: nav.effectiveFromUrl.pathname.split("/").filter(Boolean),
       ids: nav.filteredSegmentIds,
     },
-    fromRouteName:
-      nav.effectiveFromMatch?.routeKey &&
-      !isAutoGeneratedRouteName(nav.effectiveFromMatch.routeKey)
-        ? (nav.effectiveFromMatch.routeKey as DefaultRouteName)
-        : undefined,
-    toRouteName:
-      matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-        ? (matched.routeKey as DefaultRouteName)
-        : undefined,
   };
   const isAction = !!actionContext;
 
@@ -400,7 +421,37 @@ export async function createMatchContextForPartial<TEnv>(
     clientSegmentSet.delete(snapshot.manifestEntry.shortCode);
   }
 
+  // Whether an intercept targets this route at all: the same walk as above
+  // with isAction=true, which skips when(). If one does, the response depends
+  // on the source even when none applied (a when() that rejected it, a
+  // same-route navigation), so it must not share the source-agnostic prefetch
+  // slot (#1007). The walk is over the TARGET's chain, so a route no
+  // intercept targets never depends on the source this way.
+  const targetsIntercept = (routeKey: string): boolean =>
+    findInterceptForRoute(
+      routeKey,
+      snapshot.manifestEntry.parent,
+      null,
+      true,
+    ) !== null;
+  const interceptTargeted =
+    !!interceptResult ||
+    (!skipInterceptForAction &&
+      (targetsIntercept(matched.routeKey) ||
+        (snapshot.localRouteName !== matched.routeKey &&
+          targetsIntercept(snapshot.localRouteName))));
+
   const isIntercept = !!interceptResult;
+  // A normal-route navigation may replay a PPR shell's canonical segment
+  // snapshot. Intercepts remain source-dependent and always use their normal
+  // cache path.
+  const cacheScope = isIntercept
+    ? snapshot.cacheScope
+    : resolveShellImplicitCacheScope(snapshot.cacheScope);
+  // A scope means a route cache() record may be written: arm its tag owners
+  // before any handler runs (#957); see the full-match site for #964's arm.
+  if (cacheScope) armRecordTagOwners();
+  if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
 
   return {
     request,
@@ -427,12 +478,8 @@ export async function createMatchContextForPartial<TEnv>(
     interceptSelectorContext,
     isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    // A normal-route navigation may replay a PPR shell's canonical segment
-    // snapshot. Intercepts remain source-dependent and always use their normal
-    // cache path.
-    cacheScope: isIntercept
-      ? snapshot.cacheScope
-      : resolveShellImplicitCacheScope(snapshot.cacheScope),
+    interceptTargeted,
+    cacheScope,
     isIntercept,
     actionContext,
     isAction,

package/src/router/match-context.ts

@@ -176,6 +176,11 @@ export interface MatchContext<TEnv = any> {
   interceptSelectorContext: InterceptSelectorContext;
   isSameRouteNavigation: boolean;
   interceptResult: InterceptResult | null;
+  /**
+   * An intercept targets this route, matched or not (a same-route navigation
+   * skips it), so the response depends on the source. Partial matches only.
+   */
+  interceptTargeted?: boolean;
 
   // Cache
   cacheScope: CacheScope | null;

package/src/router/match-handlers.ts

@@ -9,7 +9,6 @@ import type {
   NotFoundBoundaryHandler,
 } from "../types";
 import {
-  isPprEntry,
   type EntryData,
   type InterceptEntry,
   type InterceptSelectorContext,
@@ -47,7 +46,8 @@ import {
   buildCacheSignalSegments,
 } from "./telemetry.js";
 import { _getRequestContext } from "../server/request-context.js";
-import { evaluatePprTransitionWhen } from "./transition-when.js";
+import { ShellRecordUnavailableError } from "../cache/shell-snapshot.js";
+import { recordTransitionWhenRefs } from "./transition-when.js";
 
 /**
  * Per-call telemetry lifecycle emitter for match()/matchPartial(). Each method
@@ -234,33 +234,14 @@ export function createMatchHandlers<TEnv = any>(
     if (reqCtx) reqCtx._cacheSignal = segments;
   };
 
-  const evaluatePprTransitionWhenForMatch = (
-    ctx: MatchContext<TEnv>,
-    isPartial: boolean,
-  ): void => {
+  const recordTransitionWhenRefsForMatch = (ctx: MatchContext<TEnv>): void => {
     const reqCtx = _getRequestContext();
     if (!reqCtx) return;
-    reqCtx._pprTransitionDecisions = undefined;
-    if (!isPprEntry(ctx.manifestEntry)) return;
-
-    evaluatePprTransitionWhen(
-      ctx.entries,
-      reqCtx,
-      {
-        params: ctx.matched.params,
-        routeName: ctx.interceptSelectorContext.toRouteName,
-      },
-      (error, segmentId) =>
-        callOnError(error, "rendering", {
-          request: ctx.request,
-          url: ctx.url,
-          env: ctx.env,
-          params: ctx.matched.params,
-          segmentId,
-          isPartial,
-          handledByBoundary: false,
-        }),
-    );
+    const entry = ctx.manifestEntry;
+    recordTransitionWhenRefs(ctx.entries, reqCtx, {
+      routeName: ctx.routeKey,
+      pattern: entry?.type === "route" ? entry.pattern : undefined,
+    });
   };
 
   async function createMatchContextForFull(
@@ -349,7 +330,7 @@ export function createMatchHandlers<TEnv = any>(
           }
 
           const ctx = result as MatchContext<TEnv>;
-          evaluatePprTransitionWhenForMatch(ctx, false);
+          recordTransitionWhenRefsForMatch(ctx);
 
           try {
             const state = createPipelineState();
@@ -380,6 +361,10 @@ export function createMatchHandlers<TEnv = any>(
               emitter.end(0, false, error.status);
               throw error;
             }
+            // A document shell HIT tail's doc record could not supply the
+            // handler layer: a serve-path signal serveShellHit degrades, not a
+            // routing error (the record's decode failure was already reported).
+            if (error instanceof ShellRecordUnavailableError) throw error;
             emitter.error(
               error instanceof Error ? error : new Error(String(error)),
               "routing",
@@ -461,7 +446,7 @@ export function createMatchHandlers<TEnv = any>(
               emitter.end(0, false);
               return null;
             }
-            evaluatePprTransitionWhenForMatch(ctx, true);
+            recordTransitionWhenRefsForMatch(ctx);
 
             if (isRouterDebugEnabled()) {
               startRevalidationTrace({