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

package/src/rsc/helpers.ts

@@ -12,6 +12,24 @@ import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isRedirectResponse } from "../response-utils.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
 
 /**
  * Copy stub headers from the request context onto a target Headers instance:
@@ -85,6 +103,7 @@ export function createResponseWithMergedHeaders(
   const mergedHeaders = new Headers(init.headers);
   applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
   // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
   // notFound, 500 for error). Default ctx.res.status is 200.

package/src/rsc/progressive-enhancement.ts

@@ -254,6 +254,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
         version: ctx.version,
+        stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
         warmupEnabled: ctx.router.warmupEnabled,
         initialTheme: requireRequestContext().theme,
@@ -362,6 +363,7 @@ async function renderPeErrorBoundary<TEnv>(
       rootLayout: ctx.router.rootLayout,
       handles: handleStore.stream(),
       version: ctx.version,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       initialTheme: requireRequestContext().theme,

package/src/rsc/response-route-handler.ts

@@ -12,7 +12,7 @@ import { contextGet } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { traverseBack } from "../router/pattern-matching.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
-import { createCacheScope } from "../cache/cache-scope.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
   createReverseFunction,
@@ -277,6 +277,11 @@ export async function handleResponseRoute<TEnv>(
           }
         }
 
+        // Resolve cache tags for this document entry (static or dynamic),
+        // while request context is available. Passed to putResponse so the
+        // entry is tag-invalidatable.
+        const responseTags = resolveCacheTags(cacheScope.config, reqCtx);
+
         // Save pre-handler callbacks (registered by app-level middleware
         // before we reach the cache block) and clear the live array.
         // createResponseWithMergedHeaders (inside the handler) eagerly
@@ -318,6 +323,7 @@ export async function handleResponseRoute<TEnv>(
                     fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
+                    responseTags,
                   );
                 }
               } catch (error) {
@@ -346,6 +352,7 @@ export async function handleResponseRoute<TEnv>(
                 response.clone(),
                 cacheScope!.ttl,
                 cacheScope!.swr,
+                responseTags,
               );
             } catch (error) {
               console.error(`[ResponseCache] Cache write failed:`, error);

package/src/rsc/rsc-rendering.ts

@@ -53,6 +53,7 @@ export async function handleRscRendering<TEnv>(
       handles: handleStore.stream(),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       initialTheme: reqCtx.theme,
     },
@@ -99,6 +100,7 @@ export async function handleRscRendering<TEnv>(
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+          stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };
     }

package/src/rsc/types.ts

@@ -43,6 +43,8 @@ export interface RscPayload {
     version?: string;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
+    /** Server-resolved rango state cookie name; the client reads it verbatim. */
+    stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */

package/src/runtime-env.ts

@@ -0,0 +1,18 @@
+// Runtime-safe detection of a test runner (Vitest), used to decide whether a
+// create*() call with no plugin-injected $$id may fall back to a synthetic id (a
+// bare test) or must fail loud (dev / a real build).
+//
+// `process` is absent in some target runtimes (the browser, certain edge/worker
+// RSC environments), so probe it through `globalThis` with optional chaining —
+// NEVER a bare `process.env.VITEST`, which would ReferenceError before the
+// intended error is thrown. Unlike `process.env.NODE_ENV` (folded by the app's
+// build `define`), `VITEST` is not folded, so this stays a small runtime check;
+// it lives only on the create*() error path (id missing), which never runs in a
+// correct production build.
+//
+// Vitest sets `VITEST` in every test process — the node project and the
+// react-server forks alike (the RSC project forces NODE_ENV=production, so NODE_ENV
+// cannot distinguish it from a real build; `VITEST` can). A real build never sets it.
+export function isUnderTestRunner(): boolean {
+  return !!globalThis.process?.env?.VITEST;
+}

package/src/server/cookie-store.ts

@@ -8,7 +8,7 @@
  */
 
 import type { CookieOptions } from "../router/middleware-types.js";
-import { getRequestContext } from "./request-context.js";
+import { getRequestContext, _getRequestContext } from "./request-context.js";
 import { isInsideCacheScope } from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
@@ -168,6 +168,57 @@ export function headers(): ReadonlyHeaders {
   }) as unknown as ReadonlyHeaders;
 }
 
+/**
+ * Force the calling client's caches to miss from now on, from the server seat:
+ * write a rotated `Set-Cookie` for the rango state. The responding client
+ * applies it on receipt, and its history cache is marked stale by the
+ * jar-divergence observer at its next read. Per-client and lazy — it rotates
+ * only the client that receives this response, not every client.
+ *
+ * Idempotent within a request (one `Set-Cookie`). Inert (a dev warning) when
+ * called outside a request context. Like `cookies()`, it throws inside a
+ * `"use cache"` / `cache()` boundary, but is allowed from a loader (loaders are
+ * the dynamic holes of a cached document).
+ */
+export function invalidateClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "invalidateClientCache");
+  ctx._rotateStateCookie();
+}
+
+/**
+ * Suppress a server action's automatic client-cache invalidation: tell the
+ * action bridge this action changed nothing a route renders, so it should leave
+ * the client's state and caches alone (no rotation, no prefetch wipe, no
+ * broadcast, no revalidation refetch). Per-response, not per-action-definition —
+ * only the execution knows whether anything changed.
+ *
+ * Sets an internal response header the bridge reads. Idempotent within a
+ * request. Inert (a dev warning) outside a request context — there is no
+ * automatic invalidation to suppress.
+ */
+export function keepClientCache(): void {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] keepClientCache() was called outside a request context; ignored.",
+      );
+    }
+    return;
+  }
+  assertNotInsideCacheContext(ctx, "keepClientCache");
+  ctx._setKeepCacheDirective();
+}
+
 /**
  * Create a CookieStore backed by a RequestContext.
  * @internal Shared between cookies() shorthand and context methods.

package/src/server/request-context.ts

@@ -11,7 +11,14 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
+import {
+  KEEP_CACHE_HEADER,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "../browser/cookie-name.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type {
@@ -102,6 +109,10 @@ export interface RequestContext<
   setStatus(status: number): void;
   /** @internal Set status bypassing cache-exec guard (for framework error handling) */
   _setStatus(status: number): void;
+  /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
+  _rotateStateCookie(): void;
+  /** @internal Set the keepClientCache() directive header on the response. */
+  _setKeepCacheDirective(): void;
 
   /**
    * Access loader data or push handle data.
@@ -140,6 +151,25 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Handler-owned registry of explicit per-scope stores from
+   * cache({ store }). Created once per createRSCHandler() and threaded into
+   * every request context, so it accumulates every explicit store the handler
+   * resolves. updateTag()/revalidateTag() iterate this set plus _cacheStore to
+   * reach every store that may hold tagged entries. The app-level store is not
+   * added here (it is always reachable via _cacheStore).
+   */
+  _explicitTaggedStores?: Set<SegmentCacheStore>;
+
+  /**
+   * @internal Union of every cache tag resolved while producing this request's
+   * response (from cache({ tags }), runtime cacheTag(), and loader cache tags).
+   * Populated at the tag-resolution sites via recordRequestTags(). Read by the
+   * document cache middleware so a full-page entry is tagged with everything its
+   * content used and can therefore be invalidated by updateTag()/revalidateTag().
+   */
+  _requestTags: Set<string>;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -318,9 +348,13 @@ export interface RequestContext<
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
    * creation. Cache-runtime and other subsystems call this to surface
-   * errors without failing the response.
+   * errors without failing the response. `category` is surfaced to consumers as
+   * `metadata.category` on the onError context (phase `cache`).
    */
-  _reportBackgroundError?: (error: unknown, category: string) => void;
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
 
   /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
   _debugPerformance?: boolean;
@@ -336,6 +370,15 @@ export interface RequestContext<
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
 /**
@@ -355,6 +398,8 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_cacheStore"
+  | "_explicitTaggedStores"
+  | "_requestTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_themeConfig"
@@ -375,8 +420,11 @@ export type PublicRequestContext<
   | "_metricsStore"
   | "_basename"
   | "_setStatus"
+  | "_rotateStateCookie"
+  | "_setKeepCacheDirective"
   | "_variables"
   | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -500,6 +548,11 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Handler-owned registry of explicit per-scope stores for cross-store tag
+   * invalidation. Created once per handler, reused across requests.
+   */
+  explicitTaggedStores?: Set<SegmentCacheStore>;
   /** Optional cache profiles for "use cache" resolution (per-router) */
   cacheProfiles?: Record<
     string,
@@ -509,6 +562,10 @@ export interface CreateRequestContextOptions<TEnv> {
   executionContext?: ExecutionContext;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
   themeConfig?: ResolvedThemeConfig | null;
+  /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
+  stateCookieName?: string;
+  /** Build version, used as the prefix of a server-rotated rango state value. */
+  version?: string;
 }
 
 /**
@@ -529,11 +586,16 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    explicitTaggedStores,
     cacheProfiles,
     executionContext,
     themeConfig,
+    stateCookieName,
+    version: stateVersion,
   } = options;
   const cookieHeader = request.headers.get("Cookie");
+  // One Set-Cookie per request no matter how many invalidateClientCache() calls.
+  let rangoStateRotated = false;
   let parsedCookies: Record<string, string> | null = null;
 
   // Create stub response for collecting headers/cookies.
@@ -723,6 +785,45 @@ export function createRequestContext<TEnv>(
       stubResponse.headers.set(name, value);
     },
 
+    // Rotate the rango state cookie for the responding client (the server seat
+    // of invalidateClientCache). Writes ONE Set-Cookie per request with the
+    // value {version}:{timestamp}; the `:` stays raw (the cookie-name.ts
+    // serializer), not the URL-encoded form serializeCookieValue would produce.
+    // The timestamp is strictly greater than the client's current one (inbound
+    // X-Rango-State), so a same-millisecond server rotation still differs from
+    // the client value and the divergence observer fires.
+    _rotateStateCookie(): void {
+      if (rangoStateRotated) return;
+      rangoStateRotated = true;
+      if (!stateCookieName) return;
+      // The client's current value, for the monotonic guard: prefer the
+      // X-Rango-State header (router navigation/prefetch fetches send it), but
+      // fall back to the request's rango state cookie — action POSTs / plain
+      // app fetch()s carry no router header yet DO send the cookie. Without the
+      // fallback, prevTs stays 0 and a same-ms mint can equal the client value,
+      // leaving the divergence observer silent. `|| null` so an empty header
+      // ('' from proxy normalization) falls through instead of short-circuiting.
+      // getRawCookieValue reads the cookie undecoded (the wire value
+      // 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) ??
+        getRawCookieValue(cookieHeader, stateCookieName);
+      const value = mintStateValue(stateVersion ?? "0", prevRaw);
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeStateCookie(stateCookieName, value, url.protocol === "https:"),
+      );
+      invalidateResponseCookieCache();
+    },
+
+    // Set the keepClientCache() directive header. The action bridge reads it on
+    // the response and suppresses its automatic invalidation. `.set` makes this
+    // idempotent (one header regardless of call count).
+    _setKeepCacheDirective(): void {
+      stubResponse.headers.set(KEEP_CACHE_HEADER, "1");
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertNotInsideCacheScopeALS("setStatus");
@@ -746,6 +847,8 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _explicitTaggedStores: explicitTaggedStores,
+    _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {

package/src/static-handler.ts

@@ -35,6 +35,7 @@ import type { Handler } from "./types.js";
 import type { StaticBuildContext } from "./prerender.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Types ------------------------------------------------------------------
 
@@ -63,6 +64,11 @@ export interface StaticHandlerDefinition<
 
 // -- Function ---------------------------------------------------------------
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader /
+// Prerender). 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 runtimeStaticIdCounter = 0;
+
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
   options?: StaticHandlerOptions,
@@ -94,12 +100,28 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Static 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 static/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] Static: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Static: missing $$id. Use `export const X = Static(...)` 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 Static() routes constructs in a bare test. Never
+  // reached in a real build (the throw above fires there); staticHandlerId is
+  // read only during RSC serving (never in dispatch / assertGeneratedRoutesMatch),
+  // and the build static manifest keys on the plugin id. Mirrors createHandle /
+  // createLoader / Prerender.
+  if (!id) {
+    id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
+  }
 
   return {
     __brand: "staticHandler" as const,

package/src/testing/cache-status.ts

@@ -0,0 +1,166 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal).
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+
+import type {
+  CacheDecisionEvent,
+  CacheSegmentStatus,
+  TelemetryEvent,
+  TelemetrySink,
+} from "../router/telemetry.js";
+
+const CACHE_HEADER = "X-Rango-Cache";
+
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | { headers: Headers };
+
+/**
+ * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
+ *
+ * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
+ * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
+ * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
+ * Entries without a status are ignored.
+ *
+ * @example
+ * parseCacheHeader("product.detail=hit, shop.layout=stale")
+ * // => { "product.detail": "hit", "shop.layout": "stale" }
+ */
+export function parseCacheHeader(
+  headerValue: string | null | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!headerValue) return result;
+  for (const rawEntry of headerValue.split(",")) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const eq = entry.indexOf("=");
+    if (eq === -1) continue;
+    const id = entry.slice(0, eq).trim();
+    const status = entry.slice(eq + 1).trim();
+    if (id.length === 0 || status.length === 0) continue;
+    result[id] = status;
+  }
+  return result;
+}
+
+function getHeaders(target: CacheStatusTarget): Headers {
+  return target.headers;
+}
+
+/**
+ * Assert that the `X-Rango-Cache` header reports `expected` status for the
+ * given route. Throws a descriptive error when the header is missing (gate
+ * off), the route is absent, or the status differs.
+ *
+ * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
+ * carries — NOT the URL pattern (`/products/:id`). The signal is built from
+ * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
+ *
+ * The header is produced by the RSC render pipeline, so get the Response from
+ * the router's real fetch path (`router.fetch(...)`), with the debug cache
+ * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
+ * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
+ *
+ * @example
+ * // debugCacheSignal must be enabled on the router under test.
+ * const res = await router.fetch(new Request("https://app/products/42"));
+ * assertCacheStatus(res, "product.detail", "hit");
+ */
+export function assertCacheStatus(
+  target: CacheStatusTarget,
+  segment: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const headerValue = getHeaders(target).get(CACHE_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertCacheStatus: response has no ${CACHE_HEADER} header. ` +
+        `Enable the debug cache signal via createRouter({ debugCacheSignal: true }) ` +
+        `or RANGO_TEST_SIGNALS=1.`,
+    );
+  }
+  const map = parseCacheHeader(headerValue);
+  const actual = map[segment];
+  if (actual === undefined) {
+    const known = Object.keys(map);
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" not found in ${CACHE_HEADER} ` +
+        `("${headerValue}"). Known segments: ${
+          known.length > 0 ? known.join(", ") : "(none)"
+        }.`,
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+  /** Wire into `createRouter({ telemetry: sink })`. */
+  sink: TelemetrySink;
+  /** All telemetry events captured so far, in emit order. */
+  events: TelemetryEvent[];
+}
+
+/**
+ * Create a capturing telemetry sink for asserting on `cache.decision` events.
+ *
+ * This is the ZERO-production-surface path: no response header is emitted, the
+ * consumer just inspects the captured events.
+ *
+ * @example
+ * const { sink, events } = createCacheSink();
+ * const router = createRouter({ telemetry: sink, ... });
+ * // ...send a request through the router's RSC fetch path...
+ * const decisions = filterCacheDecisions(events);
+ * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
+ */
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+/**
+ * Filter captured telemetry events down to `cache.decision` events.
+ */
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}

package/src/testing/collect-handle.ts

@@ -0,0 +1,63 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to a flat array with a warning.
+ */
+
+import { getCollectFn, type Handle } from "../handle.js";
+
+/**
+ * Run a handle's collect function on per-segment pushed values.
+ *
+ * @param handle - The handle whose collect to run.
+ * @param segments - Per-segment pushed values: each entry is the array of values
+ *   one route segment pushed for this handle, in parent -> child order. Empty
+ *   per-segment arrays are dropped before the collect runs, matching production
+ *   collectHandleData (a segment that pushed nothing is not passed through).
+ * @returns The accumulated value the handle's collect produces.
+ *
+ * @example
+ * ```ts
+ * // Default flatten
+ * collectHandle(Breadcrumbs, [[{ label: "Home", href: "/" }], [{ label: "P", href: "/p" }]]);
+ * // -> [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]
+ *
+ * // Custom "last wins"
+ * const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
+ * collectHandle(PageTitle, [["Home"], ["Product"]]); // -> "Product"
+ * ```
+ */
+export function collectHandle<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  segments: ReadonlyArray<ReadonlyArray<TData>>,
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id) as
+    | ((segments: TData[][]) => TAccumulated)
+    | undefined;
+
+  if (!collectFn) {
+    console.warn(
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
+        `function. Import the handle's module so createHandle() runs. Falling ` +
+        `back to a flat array.`,
+    );
+    return segments.flat() as unknown as TAccumulated;
+  }
+
+  // Match production collectHandleData (handle.ts): segments that pushed
+  // nothing (empty arrays) are dropped before the collect runs, so a collect
+  // that inspects segment count or indices sees the same input as at runtime.
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+  return collectFn(nonEmpty);
+}