@rangojs/router 0.18.0 → 0.19.1

package/src/server/request-context.ts

@@ -49,7 +49,7 @@ import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
-import type { TransitionWhenFn } from "../types/segments.js";
+import type { TransitionWhenRecord } from "../router/transition-when.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import {
@@ -64,8 +64,16 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
   clearPprHeaderScope,
+  runInsideLoaderRun,
+  type LoaderRunIdentity,
 } from "./context.js";
-import { assertThemeReadAllowed } from "./cookie-store.js";
+import { readStartedLoaderValue, trackLoaderRun } from "../cache/cache-tag.js";
+import {
+  guardRawCookieRead,
+  guardRequestHeaders,
+  readGuardedTheme,
+} from "./cookie-store.js";
+import { requestHeaders } from "./request-headers.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -76,6 +84,10 @@ import {
   getSearchSchema,
 } from "../route-map-builder.js";
 import { parseSearchParams } from "../search-params.js";
+import {
+  executionStart,
+  type ExecutionStart,
+} from "../cache/invalidation-order.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
@@ -146,10 +158,24 @@ export interface RequestContext<
   /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
   _dynamic?: boolean;
 
-  /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
+  /**
+   * @internal Get a cookie value (effective: request + response mutations).
+   * Use cookies().get() instead. Guarded like cookies() (#976).
+   */
   cookie(name: string): string | undefined;
-  /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
+  /**
+   * @internal Get all cookies (effective merged view). Use
+   * cookies().getAll() instead. Guarded like cookies() (#976).
+   */
   cookies(): Record<string, string>;
+  /**
+   * @internal `cookie()` without the identity guard: the read behind the
+   * cookies() store, which guards at its own call and records per read
+   * method. Non-enumerable, like `_readTheme`.
+   */
+  _readCookie(name: string): string | undefined;
+  /** @internal `cookies()` without the identity guard (see `_readCookie`). */
+  _readCookies(): Record<string, string>;
   /** @internal Set a cookie on the response. Use cookies().set() instead. */
   setCookie(name: string, value: string, options?: CookieOptions): void;
   /** @internal Delete a cookie. Use cookies().delete() instead. */
@@ -182,19 +208,18 @@ export interface RequestContext<
   /**
    * @internal The context createRequestContext() returned. A context derived
    * from it with Object.create (a PPR HIT tail, a shell capture, a background
-   * revalidation render) inherits it, so per-request invalidation state
-   * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
-   * whichever derived object called or read (#973).
+   * revalidation render) inherits it, so per-request invalidation state (the
+   * stores' masks) is keyed by the request, not by whichever derived object
+   * called or read (#973).
    */
   _requestRoot?: RequestContext<any, any>;
   /**
-   * @internal The tags this request invalidated with
-   * updateTag()/revalidateTag(), each with its position in the invalidation
-   * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
-   * "use cache" execution that started before one of its own tags was
-   * invalidated is neither joined nor written (cache-runtime.ts, #973).
+   * @internal Where the request started in the isolate's invalidation order
+   * (cache/invalidation-order.ts), taken when createRequestContext() ran. The
+   * document cache gates its write on it (#977): a middleware ahead of the
+   * document cache can read tagged data the document bakes.
    */
-  _tagInvalidations?: Map<string, number>;
+  _requestStart?: ExecutionStart;
   /**
    * @internal The handler has handed the response to the host (rsc/handler.ts
    * `rango.response`): header and cookie writes after this are lost, as from
@@ -242,16 +267,13 @@ export interface RequestContext<
   readonly _handleStore: HandleStore;
 
   /**
-   * @internal transition({ when }) predicates for segments matched this request,
-   * keyed by segment id. Collected during resolution (the function is stripped
-   * from the serialized segment config), then evaluated post-handler in
-   * rsc-rendering — outside any cache scope — to drop the transition of any
-   * segment whose predicate returns false.
+   * @internal transition({ when }) client references of the matched entry
+   * chain, keyed by segment id. Recorded at match time from the static route
+   * definition (router/transition-when.ts) and attached to the payload's
+   * segments right before Flight (rsc/attach-transition-when.ts). The server
+   * never calls them, and no cache or snapshot stores them.
    */
-  _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
-
-  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
-  _pprTransitionDecisions?: Map<string, boolean>;
+  _transitionWhenRefs?: ReadonlyMap<string, TransitionWhenRecord>;
 
   /**
    * @internal Post-match serve-source truth for the PPR replay reporter.
@@ -279,8 +301,8 @@ export interface RequestContext<
    * capture task's derived request context (built by shell-capture.ts). This is
    * the switch every capture-specific behavior reads: loader masking
    * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
-   * cookies()/headers() capture guard (cookie-store.ts
-   * assertNotInsideShellCapture). The foreground render never sets it, so the
+   * identity-read capture guard (server/context.ts guardIdentityRead). The
+   * foreground render never sets it, so the
    * served response is byte-identical to axis 1. The capture descriptor itself
    * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
    * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
@@ -308,6 +330,16 @@ export interface RequestContext<
    */
   _shellCaptureUnrecordedLoaderPush?: true;
 
+  /**
+   * @internal The lane of each loader the capture's matched route registers
+   * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
+   * before any loader runs. The capture's push funnel credits a push made
+   * under a live-lane loader's body, at any depth, to that loader
+   * (shell-capture.ts deriveShellCaptureContext). Own property of the
+   * capture's derived context only.
+   */
+  _shellCaptureLoaderLanes?: ReadonlyMap<string, "live" | "bake">;
+
   /**
    * @internal Record keys resolved for this request (CacheScope
    * resolveKeyFrom): by the scope's `key()` (one result) or its store's
@@ -414,7 +446,9 @@ export interface RequestContext<
      * scope replaces any route-derived cache() scope for the tail's match
      * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
      * ShellRecordUnavailableError instead of resolving segments
-     * (withCacheLookup): a HIT never runs a handler.
+     * (withCacheLookup): a HIT never runs a handler. The record's
+     * loader-owned handle pushes restore as authoritative
+     * (HandleStore.pushRestored): the prelude rendered them.
      */
     docTail?: true;
     /**
@@ -468,8 +502,9 @@ export interface RequestContext<
 
   /**
    * @internal Set by the capture guard (server/context.ts
-   * tripShellCaptureGuard) when it throws DURING a capture render: the read
-   * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+   * guardIdentityRead) when it throws DURING a capture render: the read
+   * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
+   * "ctx.theme") and the fix the
    * refusal warning gives for it. Load-bearing for the
    * bake lane: a guard throw inside an executing loader is swallowed by
    * wrapLoaderPromise into per-loader error UI, which would otherwise bake
@@ -611,12 +646,27 @@ export interface RequestContext<
   /**
    * @internal The theme cookie (or the default) read with no identity guard.
    * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
-   * call it after assertThemeReadAllowed; the router's own payload read goes
-   * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+   * call it after guardIdentityRead (readGuardedTheme); the router's own payload read goes
+   * through payloadInitialTheme (rsc/full-payload.ts), except the unmatched
+   * route's 404 (rsc/handler.ts), which is never stored. Undefined without
    * theme config.
    */
   _readTheme(): Theme | undefined;
 
+  /**
+   * @internal Set by the document-cache middleware (cache/document-cache.ts)
+   * before it runs a render whose response it may store: the MISS and the
+   * stale refresh. payloadInitialTheme reads it (#978).
+   */
+  _documentCacheRender?: boolean;
+
+  /**
+   * @internal Set by payloadInitialTheme when the document payload carries
+   * the visitor's theme and it differs from the no-cookie default. The
+   * document cache does not store that response (#978).
+   */
+  _payloadVisitorTheme?: boolean;
+
   /**
    * Attach location state entries to the current response.
    *
@@ -660,20 +710,6 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
-  /**
-   * @internal Navigation/action source data the transition({ when }) gate reads
-   * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
-   * come from the navigation snapshot (set at match time); action* are stashed
-   * at the action-bearing gate call sites. All undefined when there is no source
-   * (initial full load) or no action (plain navigation).
-   */
-  _gateCurrentUrl?: URL;
-  _gateCurrentParams?: Record<string, string>;
-  _gateActionId?: string;
-  _gateActionUrl?: URL;
-  _gateActionResult?: unknown;
-  _gateFormData?: FormData;
-
   /**
    * @internal True while the post-action revalidation render is running (set by
    * revalidateAfterAction). The "use cache" runtime reads this to prefer
@@ -872,11 +908,12 @@ export type PublicRequestContext<
   RequestContext<TEnv, TParams>,
   | "cookie"
   | "cookies"
+  | "_readCookie"
+  | "_readCookies"
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
-  | "_transitionWhen"
-  | "_pprTransitionDecisions"
+  | "_transitionWhenRefs"
   | "_pprReplayPostMatchReason"
   | "_cacheStore"
   | "_searchParamsFilter"
@@ -885,6 +922,7 @@ export type PublicRequestContext<
   | "_shellLoaderSeed"
   | "_shellCaptureLoaderRecords"
   | "_shellCaptureUnrecordedLoaderPush"
+  | "_shellCaptureLoaderLanes"
   | "_resolvedCacheKeys"
   | "_shellKey"
   | "_shellForcedMiss"
@@ -901,15 +939,11 @@ export type PublicRequestContext<
   | "_pendingBackgroundTasks"
   | "_themeConfig"
   | "_readTheme"
+  | "_documentCacheRender"
+  | "_payloadVisitorTheme"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
-  | "_gateCurrentUrl"
-  | "_gateCurrentParams"
-  | "_gateActionId"
-  | "_gateActionUrl"
-  | "_gateActionResult"
-  | "_gateFormData"
   | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderErrors"
@@ -938,7 +972,7 @@ export type PublicRequestContext<
   | "_freshReads"
   | "_setFreshReadsCookie"
   | "_requestRoot"
-  | "_tagInvalidations"
+  | "_requestStart"
   | "_responseSent"
   | "_variables"
   | "_classifiedRoute"
@@ -1042,17 +1076,10 @@ export function setRequestContextParams(
  */
 export function setRequestContextPrevRouteKey(
   prevRouteKey: string | undefined,
-  currentUrl?: URL,
-  currentParams?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
   if (!ctx) return;
   if (prevRouteKey !== undefined) ctx._prevRouteKey = prevRouteKey;
-  // Source URL/params for the transition({ when }) gate (effectiveFromUrl /
-  // effectiveFromMatch.params from the navigation snapshot). Same write point as
-  // _prevRouteKey, which doubles as fromRouteName.
-  if (currentUrl !== undefined) ctx._gateCurrentUrl = currentUrl;
-  if (currentParams !== undefined) ctx._gateCurrentParams = currentParams;
 }
 
 /**
@@ -1134,7 +1161,10 @@ export function createRequestContext<TEnv>(
     stateCookieName,
     version: stateVersion,
   } = options;
-  const cookieHeader = request.headers.get("Cookie");
+  // ctx.request.headers is guarded like headers() (#976); every router read
+  // of this request's headers goes through requestHeaders().
+  guardRequestHeaders(request);
+  const cookieHeader = requestHeaders(request).get("Cookie");
   let rangoStateRotated = false;
   const freshCookie = stateCookieName
     ? freshReadsCookieName(stateCookieName)
@@ -1233,6 +1263,26 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
+  // The effective jar: request cookies minus deletions plus same-request writes.
+  const effectiveCookies = (): Record<string, string> => {
+    const parsed = getParsedCookies();
+    const mutations = getResponseCookies();
+    if (mutations.size === 0) return { ...parsed };
+    // Build result without delete (avoids V8 dictionary-mode de-opt)
+    const deleted = new Set<string>();
+    for (const [k, v] of mutations) {
+      if (v === null) deleted.add(k);
+    }
+    const result: Record<string, string> = {};
+    for (const key of Object.keys(parsed)) {
+      if (!deleted.has(key)) result[key] = parsed[key];
+    }
+    for (const [k, v] of mutations) {
+      if (v !== null) result[k] = v;
+    }
+    return result;
+  };
+
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
@@ -1312,29 +1362,23 @@ export function createRequestContext<TEnv>(
       );
     },
 
+    // The visitor's cookies, guarded like cookies() (#976): before, a plain
+    // read that a ppr shell, a cache() entry or a "use cache" entry stored
+    // for every visitor.
     cookie(name: string): string | undefined {
+      guardRawCookieRead(ctx, "getRequestContext().cookie()");
       return effectiveCookie(name);
     },
 
     cookies(): Record<string, string> {
-      const parsed = getParsedCookies();
-      const mutations = getResponseCookies();
-      if (mutations.size === 0) return { ...parsed };
-      // Build result without delete (avoids V8 dictionary-mode de-opt)
-      const deleted = new Set<string>();
-      for (const [k, v] of mutations) {
-        if (v === null) deleted.add(k);
-      }
-      const result: Record<string, string> = {};
-      for (const key of Object.keys(parsed)) {
-        if (!deleted.has(key)) result[key] = parsed[key];
-      }
-      for (const [k, v] of mutations) {
-        if (v !== null) result[k] = v;
-      }
-      return result;
+      guardRawCookieRead(ctx, "getRequestContext().cookies()");
+      return effectiveCookies();
     },
 
+    // Non-enumerable, defined after this literal.
+    _readCookie: effectiveCookie,
+    _readCookies: effectiveCookies,
+
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
       stubResponse.headers.append(
@@ -1383,7 +1427,7 @@ export function createRequestContext<TEnv>(
       // decodeStateValue decodes exactly once) AND is the same parser the client
       // mirror uses, so both seats read the same jar entry.
       const prevRaw =
-        (request.headers.get("x-rango-state") || null) ??
+        (requestHeaders(request).get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
       const value = mintStateValue(stateVersion ?? "0", prevRaw);
       // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
@@ -1460,7 +1504,6 @@ export function createRequestContext<TEnv>(
     method: request.method,
 
     _handleStore: handleStore,
-    _transitionWhen: [],
     _cacheStore: cacheStore,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
@@ -1560,20 +1603,18 @@ export function createRequestContext<TEnv>(
   // the ambient context, as cookies() does, and falls back to the receiver.
   // _readTheme is the unguarded read: non-enumerable too, so a spread copy of
   // the context (the fetchable-loader ctx, loader-fetch.ts) cannot carry it.
+  // The same holds for the unguarded cookie reads (#976).
   Object.defineProperties(ctx, {
     theme: {
       get(this: RequestContext<TEnv>): Theme | undefined {
-        if (!themeConfig) return undefined;
-        assertThemeReadAllowed(
-          _getRequestContext() ?? this,
-          "getRequestContext().theme",
-        );
-        return getTheme();
+        return readGuardedTheme(this, "getRequestContext().theme");
       },
       enumerable: false,
       configurable: true,
     },
     _readTheme: { enumerable: false },
+    _readCookie: { enumerable: false },
+    _readCookies: { enumerable: false },
   });
 
   (ctx as any)[NOCACHE_SYMBOL] = true;
@@ -1585,6 +1626,7 @@ export function createRequestContext<TEnv>(
     configurable: true,
     writable: true,
   });
+  ctx._requestStart = executionStart();
   return ctx;
 }
 
@@ -1820,8 +1862,11 @@ export function createUseFunction<TEnv>(
 
     const loader = item as LoaderDefinition<any, any>;
 
-    if (loaderPromises.has(loader.$$id)) {
-      return loaderPromises.get(loader.$$id);
+    const memo = loaderPromises.get(loader.$$id);
+    if (memo) {
+      // Same refusal as the handler ctx.use memo hit (#1011): a "use cache"
+      // body reading a value whose run read request identity.
+      return readStartedLoaderValue(memo, loader.$$id);
     }
 
     let loaderFn = loader.fn;
@@ -1908,9 +1953,11 @@ export function createUseFunction<TEnv>(
     // (observePhase), so a loader resolved via this base request-context ctx.use
     // co-emits the "loader:<id>" perf metric AND the "rango.loader" span — no
     // drift between the two ctx.use implementations.
+    const run: LoaderRunIdentity = { loaderId: loader.$$id };
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
-      Promise.resolve(loaderFn(loaderCtx)),
+      Promise.resolve(runInsideLoaderRun(run, () => loaderFn(loaderCtx))),
     );
+    trackLoaderRun(promise, run);
 
     loaderPromises.set(loader.$$id, promise);
 

package/src/server/request-headers.ts

@@ -0,0 +1,134 @@
+/**
+ * The guarded `ctx.request.headers` (#976) and the router's raw reads.
+ *
+ * The Request the router hands to user code (handler, middleware and loader
+ * `ctx.request`, `getRequestContext().request`) carries an own `headers`
+ * getter that shadows the prototype's and runs the identity guard
+ * (cookie-store.ts guardRequestHeaders). A Proxy around the Request is not an
+ * option: `fetch(request)`, `new Request(request)` and `request.clone()` read
+ * the platform's internal slots, which a Proxy does not have. The own getter
+ * keeps the object a real Request, and those operations never call it.
+ */
+
+/** The Headers each shadowed request's getter returns. */
+const RAW_HEADERS = new WeakMap<Request, Headers>();
+
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+
+/**
+ * Set while the platform or a request facade reads a shadowed request's
+ * headers for itself, not for user code (runUnguarded).
+ */
+let unguarded = false;
+
+function runUnguarded<T>(fn: () => T): T {
+  const outer = unguarded;
+  unguarded = true;
+  try {
+    return fn();
+  } finally {
+    unguarded = outer;
+  }
+}
+
+/**
+ * A request's headers, past the guard. The rule: router code never reads a
+ * request's headers through the getter, only through this, so the guard sees
+ * user reads alone. Several router reads run inside the scopes the guard
+ * refuses (the state cookie rotation at a ppr capture, match's HMR marker,
+ * a store's cf-ray inside a "use cache" body, telemetry inside a loader
+ * fill); the rest follow the rule so a new call site cannot drift into one.
+ */
+export function requestHeaders(request: Request): Headers {
+  return RAW_HEADERS.get(request) ?? request.headers;
+}
+
+/**
+ * Shadow `request.headers` with an own, non-enumerable getter that calls
+ * `beforeRead` and returns the request's own Headers (stable per request, so
+ * a header set through it stays visible to every reader). Idempotent. Leaves
+ * the request as is when `headers` is a non-configurable own property (a
+ * runtime that defines it per instance). Three inherited members are
+ * shadowed with it:
+ *
+ * - `clone()` returns a clone shadowed the same way. A plain clone was a
+ *   Request without the getter, so `ctx.request.clone().headers` read the
+ *   visitor's headers past the guard. (`new Request(ctx.request)` still
+ *   returns a plain Request: the constructor cannot be intercepted.)
+ * - `_request`, on a lazy srvx NodeRequest (what @vitejs/plugin-rsc's Node
+ *   dev and preview servers and the vercel-output launcher hand the
+ *   router), runs unguarded: it builds the platform Request on first use
+ *   from `this.headers`, for clone() and the body readers. Through the
+ *   getter, a clone() inside a cache() boundary threw as a user read. It
+ *   stays lazy, so a request whose body srvx reads from its buffered
+ *   `rawBody` never builds one.
+ * - Node's util.inspect hook runs unguarded: undici's inspect reads
+ *   `this.headers`, so `console.log(ctx.request)` inside a "use cache" body
+ *   threw. A log is not a read into a shared entry.
+ */
+export function shadowRequestHeaders(
+  request: Request,
+  beforeRead: () => void,
+): Request {
+  if (RAW_HEADERS.has(request)) return request;
+  const own = Object.getOwnPropertyDescriptor(request, "headers");
+  if (own && !own.configurable) return request;
+  const lazy = inheritedGetter(request, "_request");
+  if (lazy) {
+    Object.defineProperty(request, "_request", {
+      get(this: Request): unknown {
+        return runUnguarded(() => lazy.call(this));
+      },
+      configurable: true,
+    });
+  }
+  const raw = request.headers;
+  RAW_HEADERS.set(request, raw);
+  Object.defineProperty(request, "headers", {
+    get(): Headers {
+      if (!unguarded) beforeRead();
+      return raw;
+    },
+    enumerable: false,
+    configurable: true,
+  });
+  const clone = request.clone;
+  defineMethod(request, "clone", function (this: Request): Request {
+    return shadowRequestHeaders(clone.call(this), beforeRead);
+  });
+  const inspect = (request as unknown as Record<symbol, unknown>)[INSPECT];
+  if (typeof inspect === "function") {
+    defineMethod(
+      request,
+      INSPECT,
+      function (this: Request, ...args: unknown[]) {
+        return runUnguarded(() => inspect.apply(this, args));
+      },
+    );
+  }
+  return request;
+}
+
+function defineMethod(
+  target: object,
+  key: PropertyKey,
+  value: (...args: never[]) => unknown,
+): void {
+  Object.defineProperty(target, key, {
+    value,
+    configurable: true,
+    writable: true,
+  });
+}
+
+/** The getter `key` resolves to on `target`'s prototype chain, if any. */
+function inheritedGetter(
+  target: object,
+  key: string,
+): (() => unknown) | undefined {
+  for (let o = Object.getPrototypeOf(target); o; o = Object.getPrototypeOf(o)) {
+    const found = Object.getOwnPropertyDescriptor(o, key);
+    if (found) return found.get;
+  }
+  return undefined;
+}

package/src/server.ts

@@ -48,6 +48,10 @@ export {
 // Component utilities (used internally for server/client boundary checks)
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
 
+// transition({ when }) strict validation: the generated routes-manifest module
+// enables it in the app's RSC realm (see transition-when-ref.ts).
+export { enableTransitionWhenValidation } from "./transition-when-ref.js";
+
 // Client URL projection registry (Vite discovery/bootstrap bridge)
 export {
   clearClientUrlProjections,

package/src/testing/dispatch.ts

@@ -627,9 +627,9 @@ export async function dispatch<TEnv = any>(
       const manifestEntry = preview?.manifestEntry;
       if (manifestEntry) {
         // Lazy so the testing barrel's eager graph stays plugin-rsc-free (see the
-        // import note above): the leaf takes createCacheScope/resolveCacheTags as
-        // INJECTED deps so it never imports plugin-rsc; we hand it the lazily
-        // imported pair here, only once a response route actually matched.
+        // import note above): the leaf takes createCacheScope as an INJECTED
+        // dep so it never imports plugin-rsc; we hand it the lazily imported
+        // builder here, only once a response route actually matched.
         const cacheScopeMod = await import("../cache/cache-scope.js");
         const { serveResponseRouteWithCache } =
           await import("../rsc/response-cache-serve.js");
@@ -645,10 +645,7 @@ export async function dispatch<TEnv = any>(
           responseType: responseType as string,
           url,
           executeHandler,
-          deps: {
-            createCacheScope: cacheScopeMod.createCacheScope,
-            resolveCacheTags: cacheScopeMod.resolveCacheTags,
-          },
+          deps: { createCacheScope: cacheScopeMod.createCacheScope },
         });
         if (cached !== undefined) return cached;
       }

package/src/testing/e2e/index.ts

@@ -53,6 +53,7 @@ export {
   SHELL_STATUS_HEADER,
   type PprReplayBypassReason,
   type PprReplayStatus,
+  type ShellCachePartition,
   type ShellStatus,
   type ShellStatusTarget,
 } from "../shell-status.js";

package/src/testing/index.ts

@@ -49,6 +49,8 @@ export type {
 
 export { runTransitionWhen } from "./run-transition-when.js";
 export type {
+  RunTransitionWhenAction,
+  RunTransitionWhenLocation,
   RunTransitionWhenOptions,
   RunTransitionWhenResult,
 } from "./run-transition-when.js";
@@ -91,12 +93,15 @@ export {
 export type {
   PprReplayBypassReason,
   PprReplayStatus,
+  ShellCachePartition,
   ShellStatus,
   ShellStatusTarget,
 } from "./shell-status.js";
 
 export { collectHandle } from "./collect-handle.js";
 
+export { withLocationStateKey } from "./location-state-key.js";
+
 export {
   diffGeneratedRoutes,
   assertGeneratedRoutesMatch,

package/src/testing/internal/action-id.ts

@@ -0,0 +1,25 @@
+import { resolveActionRefId } from "../../router/is-action.js";
+
+/**
+ * The id a testing primitive's `action` option names: a single imported
+ * server action (its `$id ?? $$id`, as the action boundary derives it) or a
+ * raw actionId string. A function without either id throws, naming the
+ * primitive.
+ */
+export function resolveTestActionId(
+  action: ((...args: never[]) => unknown) | string | undefined,
+  primitive: string,
+): string | undefined {
+  if (action === undefined) return undefined;
+  if (typeof action === "string") return action;
+  const id = resolveActionRefId(action);
+  if (id === undefined) {
+    throw new Error(
+      `${primitive}: \`action\` must be a single imported server action ` +
+        "(carrying its build-injected id) or an actionId string. The passed " +
+        "function has no $id/$$id — outside a built app, pass the id string " +
+        'your predicate should match (e.g. "src/actions/cart.ts#addToCart").',
+    );
+  }
+  return id;
+}

package/src/testing/internal/context.ts

@@ -250,7 +250,7 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   locationState: Record<string, unknown>;
 } {
   return {
-    cookies: { ...ctx.cookies() },
+    cookies: ctx._readCookies(),
     locationState: resolveLocationStateEntries(ctx._locationState ?? []),
   };
 }