@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

package/src/loader.ts

@@ -19,6 +19,7 @@ import type {
   LoaderFn,
 } from "./types.js";
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
@@ -46,8 +47,21 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   const loaderId = __injectedId || "";
 
-  if (!loaderId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Loader", "createLoader");
+  // Client/SSR build of createLoader. Under a test runner it needs no id
+  // (loaderId stays ""; the react-server build in loader.rsc.ts adds the runtime
+  // fallback for whole-router construction). Otherwise (dev or a real build) a
+  // missing id means an UNSUPPORTED shape the plugin skipped — fail loud rather
+  // than ship `$$id: ""` (which would make a client useLoader read the wrong
+  // key). The rich diagnostic stays behind the NODE_ENV check so production folds
+  // it away and ships the small throw. isUnderTestRunner() is runtime-safe.
+  if (!loaderId && !isUnderTestRunner()) {
+    if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    }
+    throw new Error(
+      "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+        "Export it as `export const X = createLoader(...)`.",
+    );
   }
 
   return {

package/src/prerender.ts

@@ -38,6 +38,7 @@ import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Named route resolution types -------------------------------------------
 
@@ -273,6 +274,11 @@ export interface PrerenderHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader). Only
+// assigned in a bare unit test where the Vite plugin did not inject an id; never
+// fires in a real build (the plugin always injects).
+let runtimePrerenderIdCounter = 0;
+
 // -- Overloads --------------------------------------------------------------
 //
 // T accepts: named route string (global or .local) OR explicit param object.
@@ -376,12 +382,27 @@ export function Prerender<TParams extends Record<string, any>>(
     );
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Prerender on every build, so a missing id means
+  // either no plugin (a bare test — fall back below) or an UNSUPPORTED shape the
+  // plugin silently skipped (dev OR a real build — fail loud; a synthetic id
+  // would degrade to a silent prerender miss). The message is already small (no
+  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
+  // runtime-safe — never a bare `process.env` access.
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rango] Prerender: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Prerender: missing $$id. Use `export const X = Prerender(...)` " +
+        "and ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  // Under vitest with no plugin id: assign a process-stable runtime id so a
+  // whole-app router with Prerender routes constructs in a bare test (for
+  // dispatch / assertGeneratedRoutesMatch). Never reached in a real build (the
+  // throw above fires there); prerender storage/lookup keys on routeName +
+  // paramHash, never $$id (mirrors createHandle / createLoader).
+  if (!id) {
+    id = `__rango_runtime_prerender_${runtimePrerenderIdCounter++}`;
+  }
 
   return {
     __brand: "prerenderHandler" as const,

package/src/router/basename.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a router basename to its canonical form: a single leading slash,
+ * no trailing slash, and `undefined` for an empty or bare-"/" value.
+ *
+ * This is the single source of truth used by both createRouter() (so the RSC
+ * handler stores a canonical basename on the request context) and the testing
+ * primitives (so a consumer can pass the same un-normalized string their
+ * createRouter() accepts and observe the same redirect() prefixing).
+ */
+export function normalizeBasename(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  const trimmed = basename.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : undefined;
+}

package/src/router/match-handlers.ts

@@ -33,10 +33,13 @@ import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
+  type CacheSegmentSignal,
   safeEmit,
   resolveSink,
   getRequestId,
+  buildCacheSignalSegments,
 } from "./telemetry.js";
+import { _getRequestContext } from "../server/request-context.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -51,6 +54,12 @@ export interface MatchHandlerDeps<TEnv = any> {
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   telemetry?: TelemetrySink;
+  /**
+   * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
+   * match/matchPartial stash a coarse route-level cache signal on the request
+   * context for the response-finalization path to emit. Default off.
+   */
+  cacheSignalEnabled?: boolean;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -113,6 +122,25 @@ export function createMatchHandlers<TEnv = any>(
   } = deps;
   const hasTelemetry = !!deps.telemetry;
   const telemetry = resolveSink(deps.telemetry);
+  const cacheSignalEnabled = !!deps.cacheSignalEnabled;
+  // Compute the coarse cache signal when EITHER telemetry needs it (for the
+  // cache.decision event) OR the debug header gate is on. When neither is set,
+  // this is never called — zero extra work on the hot path.
+  const buildSignal = (
+    routeKey: string,
+    state: {
+      cacheHit: boolean;
+      cacheSource?: "runtime" | "prerender";
+      shouldRevalidate?: boolean;
+    },
+  ): CacheSegmentSignal[] => buildCacheSignalSegments(routeKey, state);
+  // Stash the signal on the request context for the response path to emit as
+  // the X-Rango-Cache header. Only when the debug gate is on.
+  const recordSignalIfEnabled = (segments: CacheSegmentSignal[]): void => {
+    if (!cacheSignalEnabled) return;
+    const reqCtx = _getRequestContext();
+    if (reqCtx) reqCtx._cacheSignal = segments;
+  };
 
   async function createMatchContextForFull(
     request: Request,
@@ -208,17 +236,24 @@ export function createMatchHandlers<TEnv = any>(
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry || cacheSignalEnabled) {
+              const signalSegments = buildSignal(ctx.routeKey, state);
+              recordSignalIfEnabled(signalSegments);
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                  segments: signalSegments,
+                });
+              }
+            }
             if (hasTelemetry) {
-              safeEmit(telemetry, {
-                type: "cache.decision",
-                timestamp: performance.now(),
-                requestId,
-                pathname,
-                routeKey: ctx.routeKey,
-                hit: state.cacheHit,
-                shouldRevalidate: !!state.shouldRevalidate,
-                source: state.cacheSource,
-              });
               safeEmit(telemetry, {
                 type: "request.end",
                 timestamp: performance.now(),
@@ -363,17 +398,24 @@ export function createMatchHandlers<TEnv = any>(
                 state,
               );
               flushRevalidationTrace();
+              if (hasTelemetry || cacheSignalEnabled) {
+                const signalSegments = buildSignal(ctx.routeKey, state);
+                recordSignalIfEnabled(signalSegments);
+                if (hasTelemetry) {
+                  safeEmit(telemetry, {
+                    type: "cache.decision",
+                    timestamp: performance.now(),
+                    requestId: partialRequestId,
+                    pathname,
+                    routeKey: ctx.routeKey,
+                    hit: state.cacheHit,
+                    shouldRevalidate: !!state.shouldRevalidate,
+                    source: state.cacheSource,
+                    segments: signalSegments,
+                  });
+                }
+              }
               if (hasTelemetry) {
-                safeEmit(telemetry, {
-                  type: "cache.decision",
-                  timestamp: performance.now(),
-                  requestId: partialRequestId,
-                  pathname,
-                  routeKey: ctx.routeKey,
-                  hit: state.cacheHit,
-                  shouldRevalidate: !!state.shouldRevalidate,
-                  source: state.cacheSource,
-                });
                 safeEmit(telemetry, {
                   type: "request.end",
                   timestamp: performance.now(),

package/src/router/prerender-match.ts

@@ -211,11 +211,14 @@ export async function matchForPrerender<TEnv = any>(
       header: () => {},
       setStatus: () => {},
       _setStatus: () => {},
+      _rotateStateCookie: () => {},
+      _setKeepCacheDirective: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
       method: "GET",
       _handleStore: handleStore,
+      _requestTags: new Set<string>(),
       waitUntil: () => {},
       onResponse: () => {},
       _onResponseCallbacks: [],
@@ -460,11 +463,14 @@ export async function renderStaticSegment<TEnv = any>(
     header: () => {},
     setStatus: () => {},
     _setStatus: () => {},
+    _rotateStateCookie: () => {},
+    _setKeepCacheDirective: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
     method: "GET",
     _handleStore: handleStore,
+    _requestTags: new Set<string>(),
     waitUntil: () => {},
     onResponse: () => {},
     _onResponseCallbacks: [],

package/src/router/router-interfaces.ts

@@ -290,6 +290,13 @@ export interface RangoInternal<
    */
   readonly prefetchCacheTTL: number;
 
+  /**
+   * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
+   * router init and shipped to the client in payload metadata. The server-side
+   * cookie writer reads it from here; the client reads it from metadata.
+   */
+  readonly resolvedStateCookieName: string;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods

package/src/router/router-options.ts

@@ -132,6 +132,21 @@ export interface RangoOptions<TEnv = any> {
    */
   allowDebugManifest?: boolean;
 
+  /**
+   * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+   * the cache status of the matched route, for use by testing primitives such
+   * as `assertCacheStatus`.
+   *
+   * Defaults to `false`. When neither this option nor the
+   * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+   * router output is byte-identical to the default.
+   *
+   * The header encodes per-segment (v1: coarse route-level) status keyed by the
+   * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+   * production — it exposes internal cache decisions.
+   */
+  debugCacheSignal?: boolean;
+
   /**
    * Document component that wraps the entire application.
    *
@@ -481,6 +496,21 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Prefix for the rango state cookie name. The resolved name is
+   * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
+   * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
+   *
+   * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
+   * the prefix lets you align it with cookie-naming policies or consent-manager
+   * classification lists, or avoid colliding with an existing `rango-state`
+   * cookie. It is not a full-name override: the `_{routerId}` suffix is what
+   * keeps sibling apps on one origin from clobbering each other's state.
+   *
+   * @default "rango-state"
+   */
+  stateCookiePrefix?: string;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *

package/src/router/segment-resolution/loader-cache.ts

@@ -28,9 +28,11 @@ import {
   resolveSwrWindow,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { recordRequestTags } from "../../cache/cache-tag.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -87,23 +89,8 @@ async function resolveLoaderKey(
  */
 function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   const options = loaderEntry.cache?.options;
-  if (!options || !options.tags) return undefined;
-
-  if (typeof options.tags === "function") {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) return undefined;
-    try {
-      return options.tags(requestCtx);
-    } catch (error) {
-      console.error(
-        `[LoaderCache] Tags function failed, caching without tags:`,
-        error,
-      );
-      return undefined;
-    }
-  }
-
-  return options.tags;
+  if (!options) return undefined;
+  return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
 function getLoaderStore(
@@ -152,6 +139,10 @@ export function resolveLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
+  // Loader tags are config-derived, so they are the complete set whether this is
+  // a cache hit or miss; record them every time so a document built from this
+  // loader is tagged for invalidation.
+  recordRequestTags(tags);
 
   // Wrap ctx.use() so cache HIT primes the handler's memoization map.
   // ctx.use() closes over the match context's loaderPromises (not request context's).

package/src/router/state-cookie-name.ts

@@ -0,0 +1,33 @@
+import { DEFAULT_STATE_COOKIE_PREFIX } from "../browser/cookie-name.js";
+
+/**
+ * Resolve the rango state cookie name once, server-side, at router init. The
+ * resolved string is shipped in payload metadata and the client reads it
+ * verbatim, so composition happens in exactly one place.
+ *
+ * Shape: `{sanitizedPrefix}_{sanitizedRouterId}`. The prefix charset excludes
+ * `_` so the FIRST `_` is always the prefix/routerId boundary; that keeps the
+ * name injective even though a routerId may legitimately contain `_` (the
+ * counter fallback is `router_{n}`). Without that exclusion, prefix
+ * `rango-state` + id `router_0` and prefix `rango-state_router` + id `0` would
+ * both resolve to `rango-state_router_0` and silently share a cache key.
+ */
+
+// Prefix excludes `_` so it can never collide with the separator.
+function sanitizePrefix(prefix: string): string {
+  return prefix.replace(/[^A-Za-z0-9-]/g, "");
+}
+
+// routerId keeps `_` (so `router_0` survives); other illegal chars are dropped.
+function sanitizeRouterId(routerId: string): string {
+  return routerId.replace(/[^A-Za-z0-9_-]/g, "");
+}
+
+export function resolveStateCookieName(
+  prefix: string | undefined,
+  routerId: string,
+): string {
+  const sanitized = sanitizePrefix(prefix ?? DEFAULT_STATE_COOKIE_PREFIX);
+  const finalPrefix = sanitized || DEFAULT_STATE_COOKIE_PREFIX;
+  return `${finalPrefix}_${sanitizeRouterId(routerId)}`;
+}

package/src/router/telemetry.ts

@@ -90,6 +90,34 @@ export interface HandlerErrorEvent extends BaseEvent {
   params?: Record<string, string>;
 }
 
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus =
+  | "hit"
+  | "miss"
+  | "stale"
+  | "prerendered"
+  | "passthrough";
+
+export interface CacheSegmentSignal {
+  /** Segment id (v1: the route key, since status is route-level). */
+  id: string;
+  /** Segment type (v1: "route" for the coarse route-level entry). */
+  type: string;
+  /** Resolved cache status for this segment. */
+  cacheStatus: CacheSegmentStatus;
+  /** Whether stale-while-revalidate was triggered for this segment. */
+  shouldRevalidate?: boolean;
+}
+
 export interface CacheDecisionEvent extends BaseEvent {
   type: "cache.decision";
   pathname: string;
@@ -98,6 +126,12 @@ export interface CacheDecisionEvent extends BaseEvent {
   /** Whether stale-while-revalidate was triggered */
   shouldRevalidate: boolean;
   source?: "runtime" | "prerender";
+  /**
+   * Optional per-segment (v1: coarse route-level) cache status. Present only
+   * when telemetry or the debug cache signal is enabled. Optional so existing
+   * sinks are unaffected.
+   */
+  segments?: CacheSegmentSignal[];
 }
 
 export interface RevalidationDecisionEvent extends BaseEvent {
@@ -140,6 +174,71 @@ export type TelemetryEvent =
   | RequestTimeoutEvent
   | OriginCheckRejectedEvent;
 
+// ---------------------------------------------------------------------------
+// Cache signal derivation (coarse, route-level)
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export function deriveCacheStatus(state: {
+  cacheHit: boolean;
+  cacheSource?: "runtime" | "prerender";
+  shouldRevalidate?: boolean;
+}): CacheSegmentStatus {
+  if (state.cacheHit) {
+    if (state.cacheSource === "prerender") return "prerendered";
+    if (state.shouldRevalidate) return "stale";
+    return "hit";
+  }
+  return "miss";
+}
+
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export function buildCacheSignalSegments(
+  routeKey: string,
+  state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+  },
+): CacheSegmentSignal[] {
+  return [
+    {
+      id: routeKey,
+      type: "route",
+      cacheStatus: deriveCacheStatus(state),
+      shouldRevalidate: !!state.shouldRevalidate,
+    },
+  ];
+}
+
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export function formatCacheSignalHeader(
+  segments: CacheSegmentSignal[],
+): string {
+  return segments.map((s) => `${s.id}=${s.cacheStatus}`).join(", ");
+}
+
 // ---------------------------------------------------------------------------
 // Sink interface
 // ---------------------------------------------------------------------------

package/src/router.ts

@@ -57,6 +57,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
 import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -110,6 +111,7 @@ import {
   matchForPrerender as _matchForPrerender,
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
@@ -149,6 +151,7 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -158,14 +161,22 @@ export function createRouter<TEnv = any>(
     onTimeout,
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
   } = options;
 
+  // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
+  // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
+  // no X-Rango-Cache header is emitted and output is byte-identical.
+  const cacheSignalEnabled =
+    debugCacheSignalOption ||
+    (typeof process !== "undefined" &&
+      (process as { env?: Record<string, string | undefined> }).env
+        ?.RANGO_TEST_SIGNALS === "1");
+
   // Normalize basename: ensure leading slash, strip trailing slash.
-  // A bare "/" is equivalent to no basename.
-  const basename =
-    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
-      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
-      : undefined;
+  // A bare "/" is equivalent to no basename. Shared with the testing
+  // primitives via normalizeBasename so they can never drift.
+  const basename = normalizeBasename(basenameOption);
 
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
@@ -209,6 +220,14 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
+  // Resolve the rango state cookie name once, here, so the two cookie writers
+  // (the client document.cookie writer and the server Set-Cookie writer)
+  // consume one pre-composed name and cannot drift.
+  const resolvedStateCookieName = resolveStateCookieName(
+    stateCookiePrefixOption,
+    routerId,
+  );
+
   // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
   // Clamp to a non-negative integer for valid Cache-Control max-age.
   const rawTTL =
@@ -255,9 +274,14 @@ export function createRouter<TEnv = any>(
     invokeOnError(onError, error, phase, context, "Router");
   }
 
-  // Validate document is a client component
+  // Validate document is a client component. Under a test runner the "use
+  // client" transform has not run, so a real exported document has no marker;
+  // allowServerInTest lets the router construct in a bare unit test (for
+  // dispatch / assertGeneratedRoutesMatch) while a real build still throws.
   if (documentOption !== undefined) {
-    assertClientComponent(documentOption, "document");
+    assertClientComponent(documentOption, "document", {
+      allowServerInTest: true,
+    });
   }
 
   // Use default document if none provided (keeps internal name as rootLayout)
@@ -667,6 +691,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -938,6 +963,10 @@ export function createRouter<TEnv = any>(
     prefetchCacheControl,
     prefetchCacheTTL,
 
+    // Expose the resolved rango state cookie name for the server-side writer
+    // (invalidateClientCache) and for shipping to the client in metadata.
+    resolvedStateCookieName,
+
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 

package/src/rsc/handler.ts

@@ -57,6 +57,7 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -150,6 +151,13 @@ export function createRSCHandler<
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, version = VERSION, nonce: nonceProvider } = options;
 
+  // Handler-owned registry of explicit per-scope stores from cache({ store }).
+  // Lives in the closure so it is scoped per handler (multi-router deployments
+  // get separate registries) and accumulates every explicit store this handler
+  // resolves across requests. updateTag()/revalidateTag() iterate it to reach
+  // stores not covered by the app-level ctx._cacheStore.
+  const explicitTaggedStores = new Set<SegmentCacheStore>();
+
   // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
   const deps = options.deps ?? rscDeps;
   const {
@@ -441,9 +449,12 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
+      stateCookieName: router.resolvedStateCookieName,
+      version,
     });
     if (earlyMetricsStore) {
       requestContext._debugPerformance = true;
@@ -453,7 +464,7 @@ export function createRSCHandler<
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
       error: unknown,
-      category: string,
+      category: CacheErrorCategory,
     ) => {
       callOnError(error, "cache", {
         request,
@@ -1070,6 +1081,7 @@ export function createRSCHandler<
               rootLayout: router.rootLayout,
               handles: handleStore.stream(),
               version,
+              stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               initialTheme: requireRequestContext().theme,