@rangojs/router 0.17.0 → 0.18.0

package/src/prerender/build-shell-capture.ts

@@ -4,9 +4,9 @@
  * Runs in the RSC realm of the build's temp server, AFTER all bundles are
  * written (the prelude embeds built client asset URLs — bootstrap module,
  * chunk preloads — that only exist post-client-build). The capture core is
- * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
- * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). Build capture first replays global
+ * producer A's, verbatim: deriveShellCaptureContext (push funnel, snapshot
+ * recording, implicit doc-cache scope) + settleCaptureRecord (the record-first
+ * step) + captureAndStoreShell (gates, quiesce, tags union, putShell barrier). Build capture first replays global
  * and route middleware with a synthetic build request context
  * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
  * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
@@ -21,6 +21,7 @@
  */
 
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { MatchResult } from "../types.js";
 import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
 import {
   createRequestContext,
@@ -31,7 +32,10 @@ import {
 import {
   deriveShellCaptureContext,
   captureAndStoreShell,
+  settleCaptureRecord,
+  withinDeadline,
   delay,
+  SHELL_CAPTURE_MAX_WAIT_MS,
   SHELL_CAPTURE_RETRY_DELAY_MS,
   type ShellCaptureDescriptor,
 } from "../rsc/shell-capture.js";
@@ -134,18 +138,25 @@ export interface BuildShellCaptureResult {
   tags?: string[];
   /** On route-mismatch: what this router's match actually landed on. */
   matchedRouteName?: string;
+  /**
+   * On no-shell: the attempt ran out of ppr.captureTimeout. It is not
+   * retried: its match may still be running, and the retry would start the
+   * same work beside it (runtime twin: shell-capture.ts runShellCapture).
+   */
+  timedOut?: true;
 }
 
 /**
  * Capture the PPR shell for one prerendered URL at build time. Retries once
  * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
- * transform graph, mirroring producer A's cold-start retry — same delay).
+ * transform graph, mirroring producer A's cold-start retry — same delay),
+ * unless the attempt ran out of ppr.captureTimeout (`timedOut`).
  */
 export async function captureShellForBuild(
   opts: BuildShellCaptureOptions,
 ): Promise<BuildShellCaptureResult> {
   const first = await attemptBuildCapture(opts);
-  if (first.outcome !== "no-shell") return first;
+  if (first.outcome !== "no-shell" || first.timedOut) return first;
   if (opts.debug) {
     console.log(
       `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
@@ -215,6 +226,7 @@ async function attemptBuildCapture(
   };
 
   let mismatchedRouteName: string | undefined;
+  let timedOut = false;
   const result = await runWithRequestContext(baseCtx, async () => {
     const preview =
       typeof router.previewMatch === "function"
@@ -252,6 +264,9 @@ async function attemptBuildCapture(
         setMismatchedRouteName: (routeName) => {
           mismatchedRouteName = routeName;
         },
+        markTimedOut: () => {
+          timedOut = true;
+        },
       });
 
     const routeMiddleware =
@@ -291,6 +306,7 @@ async function attemptBuildCapture(
   if (outcome === "route-mismatch") {
     return { outcome, matchedRouteName: mismatchedRouteName };
   }
+  if (outcome === "no-shell" && timedOut) return { outcome, timedOut: true };
   return { outcome };
 }
 
@@ -310,6 +326,8 @@ interface BuildCaptureFinalOptions {
   router: any;
   url: URL;
   setMismatchedRouteName(routeName: string | undefined): void;
+  /** The attempt ran out of ppr.captureTimeout (BuildShellCaptureResult.timedOut). */
+  markTimedOut(): void;
 }
 
 async function runBuildMiddlewareEnvelope<TEnv>(
@@ -369,15 +387,28 @@ async function runBuildCaptureFinal(
   // invoking this when baseCtx._dynamic is set. A loader/handler opting out
   // DURING the capture render is caught by the derivedCtx._dynamic check below.
 
-  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+  const derivation = deriveShellCaptureContext(baseCtx, {
     ttl: opts.ttl,
     swr: opts.swr,
   });
+  const { derivedCtx, freshHandleStore } = derivation;
 
   const outcome = await runWithRequestContext(derivedCtx, async () => {
-    let match;
+    // Same one deadline as the runtime capture: the match, the record-first
+    // step, then the prerender with what is left.
+    const deadline =
+      Date.now() + (opts.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
+    let match: MatchResult;
     try {
-      match = await router.match(request, { env });
+      const matched = await withinDeadline<MatchResult>(
+        router.match(request, { env }),
+        deadline,
+      );
+      if (!matched.done) {
+        options.markTimedOut();
+        return "no-shell" as const;
+      }
+      match = matched.value;
     } catch (error) {
       if (isPlainPathMiss(error, opts.urlPath)) {
         return "route-mismatch" as const;
@@ -392,8 +423,25 @@ async function runBuildCaptureFinal(
 
     setRequestContextParams(match.params, match.routeName);
 
-    const payload = buildFullPayload(
+    // Same record-first step as the runtime capture. A prerendered URL's
+    // match comes from the prerender store (no handler runs, no doc record),
+    // which settleCaptureRecord reports as `prerender`.
+    const settled = await settleCaptureRecord(
       match,
+      derivation,
+      descriptor,
+      deadline,
+    );
+    if (settled.kind === "refused") {
+      return derivedCtx._dynamic ? ("dynamic" as const) : ("refused" as const);
+    }
+    if (settled.kind === "timeout") {
+      options.markTimedOut();
+      return "no-shell" as const;
+    }
+
+    const payload = buildFullPayload(
+      settled.match,
       // buildFullPayload reads only ctx.router.* and ctx.version.
       { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
       url,
@@ -416,9 +464,15 @@ async function runBuildCaptureFinal(
       rscStream,
       freshHandleStore,
       derivedCtx,
-      descriptor,
+      { ...descriptor, captureTimeout: Math.max(1, deadline - Date.now()) },
     );
-    return derivedCtx._dynamic ? "dynamic" : captureOutcome;
+    if (captureOutcome === "no-shell" && Date.now() >= deadline) {
+      options.markTimedOut();
+    }
+    if (derivedCtx._dynamic) return "dynamic";
+    // A route cache() record that ran out mid-capture: the in-place retry
+    // (captureShellForBuild) reads or renders a newer one.
+    return captureOutcome === "expired" ? "no-shell" : captureOutcome;
   });
 
   return {

package/src/route-definition/dsl-helpers.ts

@@ -909,12 +909,13 @@ const loader: RouteHelpers<any, any>["loader"] = (
   // resolved here, at DSL-evaluation time, for the same reason
   // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
   // flag request-mode-correct with no isSSR threading; see LoaderEntry.
+  // `bake` is the lane, the same on both evaluations.
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
-    ...(optionsGiven?.ssr === false && ctx.isSSR
-      ? { awaitBeforeFlush: true as const }
-      : {}),
+    ...(optionsGiven?.ssr === false && { bake: true as const }),
+    ...(optionsGiven?.ssr === false &&
+      ctx.isSSR && { awaitBeforeFlush: true as const }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use

package/src/router/handler-context.ts

@@ -5,7 +5,10 @@
  */
 
 import type { HandlerContext, InternalHandlerContext } from "../types";
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
 import {
@@ -18,6 +21,7 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
 } from "../server/context.js";
+import { assertThemeReadAllowed } from "../server/cookie-store.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -29,6 +33,34 @@ import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 // once at module load instead of per createHandlerContext (per-request) call.
 const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
+/** The request context a handler ctx's `theme` getter reads (THEME_DESCRIPTOR). */
+const THEME_REQUEST_CONTEXT = Symbol("rango:theme-request-context");
+
+/**
+ * ctx.theme is the visitor's theme cookie, guarded like cookies() (#971,
+ * assertThemeReadAllowed): a getter, so creating the ctx reads nothing and
+ * only a handler that reads the theme refuses a ppr capture or throws on a
+ * cache() miss. Non-enumerable, so serializing the ctx does not read it:
+ * React's dev Flight debug info JSON-stringifies server component props and
+ * replayed console.log args, and an enumerable getter read there refused the
+ * capture of a route that never read the theme. The trade: a spread or
+ * Object.assign copy of the ctx does not carry `theme`. One shared getter
+ * with the request context on a symbol key: a getter closure per ctx gives
+ * every ctx its own property shape (V8 dictionary mode). The guard reads the
+ * ambient context, as cookies() does, and falls back to the ctx's own when
+ * there is none.
+ */
+const THEME_DESCRIPTOR: PropertyDescriptor = {
+  get(this: { [THEME_REQUEST_CONTEXT]?: RequestContext }) {
+    const requestContext = this[THEME_REQUEST_CONTEXT];
+    if (!requestContext?._themeConfig) return undefined;
+    assertThemeReadAllowed(_getRequestContext() ?? requestContext, "ctx.theme");
+    return requestContext._readTheme();
+  },
+  enumerable: false,
+  configurable: true,
+};
+
 /**
  * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
  * the handler ctx (createHandlerContext) and the middleware ctx
@@ -279,7 +311,7 @@ export function createHandlerContext<TEnv>(
       // Read-time guard: non-cacheable var inside "use cache" or cache() →
       // throw. Works for both ContextVar tokens and string keys.
       if (isNonCacheable(variables, keyOrVar)) {
-        assertNonCacheableReadAllowed(keyOrVar);
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as HandlerContext<any, TEnv>["get"],
@@ -295,8 +327,7 @@ export function createHandlerContext<TEnv>(
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
     },
-    // Theme support (when enabled via router config)
-    theme: requestContext?.theme,
+    // theme: THEME_DESCRIPTOR, defined after this literal.
     setTheme: requestContext?.setTheme,
     // Location state support (delegates to request context)
     setLocationState(entries) {
@@ -325,6 +356,9 @@ export function createHandlerContext<TEnv>(
     _responseType: responseType,
     _routeName: routeName,
   };
+  (ctx as { [THEME_REQUEST_CONTEXT]?: unknown })[THEME_REQUEST_CONTEXT] =
+    requestContext;
+  Object.defineProperty(ctx, "theme", THEME_DESCRIPTOR);
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;

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,
@@ -332,12 +333,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 +362,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 +425,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,14 @@ 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,
+  readValueTags,
+  tagLoaderValue,
+} from "../cache/cache-tag.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -388,6 +396,12 @@ function createLoaderExecutor<TEnv>(
      * payload's handle-stream lifetime.
      */
     silentHandles?: 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>,
@@ -438,8 +452,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 +564,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 +710,29 @@ 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-purity guards permit its identity reads; the PPR
+    // capture guard does not (server/context.ts assertNotInsideShellCapture).
 
+    const recordedTags = recordTags ? new Set<string>() : 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);
       }),
     );
+    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 +776,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 +788,28 @@ 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(),
+      executor,
     )(loader, null);
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {

package/src/router/match-api.ts

@@ -3,6 +3,8 @@ import {
   createCacheScope,
   resolveShellImplicitCacheScope,
 } from "../cache/cache-scope.js";
+import { armLoaderTagSets, armRecordTagOwners } from "../cache/cache-tag.js";
+import { bindsLoaderCache } from "./segment-resolution/loader-cache.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -150,6 +152,20 @@ 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();
+
   return {
     request,
     url: cleanUrl,
@@ -186,9 +202,7 @@ export async function createMatchContextForFull<TEnv>(
     },
     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,
@@ -401,6 +415,16 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   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 +451,7 @@ 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),
+    cacheScope,
     isIntercept,
     actionContext,
     isAction,

package/src/router/match-handlers.ts

@@ -47,6 +47,7 @@ import {
   buildCacheSignalSegments,
 } from "./telemetry.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { ShellRecordUnavailableError } from "../cache/shell-snapshot.js";
 import { evaluatePprTransitionWhen } from "./transition-when.js";
 
 /**
@@ -380,6 +381,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",