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

package/src/server/request-context.ts

@@ -40,6 +40,7 @@ import {
   type HandleData,
 } from "./handle-store.js";
 import { isHandle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
@@ -476,6 +477,7 @@ export function _getRequestContext<TEnv = DefaultEnv>():
 export function setRequestContextParams(
   params: Record<string, string>,
   routeName?: string,
+  routeMap?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
   if (ctx) {
@@ -488,9 +490,13 @@ export function setRequestContextParams(
           : undefined
       ) as DefaultRouteName | undefined;
     }
-    // Update reverse with scoped resolution now that route is known
+    // Update reverse with scoped resolution now that route is known. Production
+    // omits routeMap and uses the global map (routes are registered globally);
+    // the testing primitives (renderToFlightString/renderServerTree) pass a
+    // scoped routeMap so `ctx.reverse` is not order-dependent on whatever router
+    // registered last.
     ctx.reverse = createReverseFunction(
-      getGlobalRouteMap(),
+      routeMap ?? getGlobalRouteMap(),
       routeName,
       params,
       routeName ? isRouteRootScoped(routeName) : undefined,
@@ -594,12 +600,9 @@ export function createRequestContext<TEnv>(
     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.
-  // All cookie/header mutations go here; cookie reads derive from it.
   let stubResponse = initialResponse
     ? new Response(null, {
         status: initialResponse.status,
@@ -608,11 +611,9 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
-  // Create handle store and loader memoization for this request
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
-  // Lazy parse cookies from the original Cookie header
   const getParsedCookies = (): Record<string, string> => {
     if (!parsedCookies) {
       parsedCookies = parseCookiesFromHeader(cookieHeader);
@@ -620,7 +621,6 @@ export function createRequestContext<TEnv>(
     return parsedCookies;
   };
 
-  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
   let responseCookieCache: Map<string, string | null> | null = null;
   const getResponseCookies = (): Map<string, string | null> => {
     if (!responseCookieCache) {
@@ -632,8 +632,6 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  // Guard: throw if a response-level side effect is called inside a cache() scope.
-  // Uses ALS to detect the scope (set during segment resolution).
   function assertNotInsideCacheScopeALS(methodName: string): void {
     if (isInsideCacheScope()) {
       throw new Error(
@@ -644,8 +642,7 @@ export function createRequestContext<TEnv>(
     }
   }
 
-  // Effective cookie read: response stub Set-Cookie wins, then original header.
-  // The stub IS the source of truth for same-request mutations.
+  // Response stub Set-Cookie wins, then original header (source of truth for mutations).
   const effectiveCookie = (name: string): string | undefined => {
     const mutations = getResponseCookies();
     if (mutations.has(name)) {
@@ -655,14 +652,11 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
-  // Theme helpers (only used when themeConfig is provided)
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
-    // Use overlay-aware read so setTheme() in the same request is reflected
     const stored = effectiveCookie(themeConfig.storageKey);
     if (stored) {
-      // Validate stored value
       if (stored === "system" && themeConfig.enableSystem) {
         return "system";
       }
@@ -676,7 +670,6 @@ export function createRequestContext<TEnv>(
   const setTheme = (theme: Theme): void => {
     if (!themeConfig) return;
 
-    // Validate theme value
     if (theme !== "system" && !themeConfig.themes.includes(theme)) {
       console.warn(
         `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
@@ -684,7 +677,6 @@ export function createRequestContext<TEnv>(
       return;
     }
 
-    // Write to stub — effectiveCookie() will pick it up on next read
     stubResponse.headers.append(
       "Set-Cookie",
       serializeCookieValue(themeConfig.storageKey, theme, {
@@ -696,10 +688,8 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
-  // Strip internal _rsc* params so userland sees a clean URL.
   const cleanUrl = stripInternalParams(url);
 
-  // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
@@ -840,7 +830,6 @@ export function createRequestContext<TEnv>(
       });
     },
 
-    // Placeholder - will be replaced below
     use: null as any,
 
     method: request.method,
@@ -869,7 +858,6 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    // Theme properties (only set when themeConfig is provided)
     get theme() {
       return themeConfig ? getTheme() : undefined;
     },
@@ -893,19 +881,17 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
 
-    // Render barrier: deferred promise resolved after non-loader segments settle.
-    _renderBarrier: null as any, // set below
-    _resolveRenderBarrier: null as any, // set below
+    _renderBarrier: null as any,
+    _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy render barrier: only allocate the Promise when a loader actually
-  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  // Lazy allocation: only create Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -916,9 +902,6 @@ export function createRequestContext<TEnv>(
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
 
-    // Closing the guard window means no handler can still form a deadlock cycle
-    // with a rendered() loader: drop the dependency-tracking state and mark it
-    // closed. WHEN this runs is the only streaming/non-streaming difference.
     const closeGuard = () => {
       ctx._renderBarrierWaiters = undefined;
       ctx._handlerLoaderDeps = undefined;
@@ -926,20 +909,8 @@ export function createRequestContext<TEnv>(
     };
 
     if (ctx._treeHasStreaming) {
-      // Streaming: rendered() keeps waiting on handleStore.settled past this
-      // point, and loading() handlers are still in flight. The eager snapshot
-      // here would be incomplete, so leave it unset — rendered() builds and
-      // caches the complete one after settled. Keep the guard window OPEN so a
-      // handler that resumes and awaits a still-waiting rendered() loader is
-      // still caught; close it once settled (every tracked handler has finished
-      // then, so none can await a loader anymore). settled resolves after
-      // rendered() seals; if no loader used rendered(), nothing seals and the
-      // (empty) guard state is simply GC'd at request end.
       handleStore.settled.then(closeGuard);
     } else {
-      // Non-streaming: all handlers have settled by now. Build and cache the
-      // snapshot so loader ctx.use(handle) calls don't rebuild it, and close the
-      // guard window immediately.
       ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
         handleStore,
         segOrder,
@@ -950,9 +921,6 @@ export function createRequestContext<TEnv>(
   };
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
-      // Barrier already resolved (cache/prerender hit) or first lazy access.
-      // Either way, replace the getter with a concrete value to avoid
-      // repeated Promise.resolve() allocations on subsequent reads.
       const p = barrierResolved
         ? Promise.resolve()
         : new Promise<void>((resolve) => {
@@ -968,24 +936,16 @@ export function createRequestContext<TEnv>(
     configurable: true,
   });
 
-  // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
     loaderPromises,
     getContext: () => ctx,
   });
 
-  // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
-/**
- * Parse Set-Cookie headers from a response into effective cookie state.
- * Returns a map of cookie name -> value (string) or name -> null (deleted).
- * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
- * Max-Age=0 is treated as a delete.
- */
 const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
 
 function parseResponseCookies(response: Response): Map<string, string | null> {
@@ -993,7 +953,6 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   const setCookies = response.headers.getSetCookie();
 
   for (const header of setCookies) {
-    // First segment before ';' is the name=value pair
     const semiIdx = header.indexOf(";");
     const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
     const eqIdx = pair.indexOf("=");
@@ -1005,11 +964,9 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
       name = decodeURIComponent(pair.substring(0, eqIdx).trim());
       value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
     } catch {
-      // Malformed encoding — skip this entry
       continue;
     }
 
-    // Max-Age=0 means the cookie is being deleted
     const isDeleted = MAX_AGE_ZERO_RE.test(header);
     result.set(name, isDeleted ? null : value);
   }
@@ -1017,10 +974,10 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   return result;
 }
 
-/**
- * Parse cookies from Cookie header
- */
-function parseCookiesFromHeader(
+// Exported for unit tests; the canonical cookie parse/serialize lives here
+// (a duplicate copy in middleware-cookies.ts was removed). Not part of the
+// public export surface.
+export function parseCookiesFromHeader(
   cookieHeader: string | null,
 ): Record<string, string> {
   if (!cookieHeader) return {};
@@ -1035,7 +992,7 @@ function parseCookiesFromHeader(
       try {
         cookies[name] = decodeURIComponent(raw);
       } catch {
-        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
+        // Malformed percent-encoding: fall back to raw value
         cookies[name] = raw;
       }
     }
@@ -1044,10 +1001,7 @@ function parseCookiesFromHeader(
   return cookies;
 }
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
-function serializeCookieValue(
+export function serializeCookieValue(
   name: string,
   value: string,
   options: CookieOptions = {},
@@ -1074,20 +1028,12 @@ export interface CreateUseFunctionOptions<TEnv> {
   getContext: () => RequestContext<TEnv>;
 }
 
-/**
- * Create the use() function for loader and handle composition.
- *
- * This is the unified implementation used by both RequestContext and HandlerContext.
- * - For loaders: executes and memoizes loader functions
- * - For handles: returns a push function to add handle data
- */
 export function createUseFunction<TEnv>(
   options: CreateUseFunctionOptions<TEnv>,
 ): RequestContext["use"] {
   const { handleStore, loaderPromises, getContext } = options;
 
   return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
-    // Handle case: return a push function
     if (isHandle(item)) {
       const handle = item;
       const ctx = getContext();
@@ -1100,30 +1046,24 @@ export function createUseFunction<TEnv>(
         );
       }
 
-      // Return a push function bound to this handle and segment
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        // If it's a function, call it immediately to get the promise
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
-
-        // Push directly - promises will be serialized by RSC and streamed
-        handleStore.push(handle.$$id, segmentId, valueOrPromise);
-      };
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          const valueOrPromise =
+            typeof dataOrFn === "function"
+              ? (dataOrFn as () => Promise<unknown>)()
+              : dataOrFn;
+
+          handleStore.push(handle.$$id, segmentId, valueOrPromise);
+        },
+      );
     }
 
-    // Loader case
     const loader = item as LoaderDefinition<any, any>;
 
-    // Return cached promise if already started
     if (loaderPromises.has(loader.$$id)) {
       return loaderPromises.get(loader.$$id);
     }
 
-    // Get loader function - either from loader object or fetchable registry
     let loaderFn = loader.fn;
     if (!loaderFn) {
       const fetchable = getFetchableLoader(loader.$$id);
@@ -1140,7 +1080,6 @@ export function createUseFunction<TEnv>(
 
     const ctx = getContext();
 
-    // Create loader context with recursive use() support
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
@@ -1157,7 +1096,6 @@ export function createUseFunction<TEnv>(
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
-        // Recursive call - will start dep loader if not already started
         return ctx.use(dep);
       }) as LoaderContext["use"],
       method: "GET",
@@ -1181,7 +1119,6 @@ export function createUseFunction<TEnv>(
       doneLoader();
     });
 
-    // Memoize for subsequent calls
     loaderPromises.set(loader.$$id, promise);
 
     return promise;

package/src/ssr/index.tsx

@@ -71,7 +71,7 @@ export interface SSRRenderOptions {
  */
 export interface SSRDependencies<TEnv = unknown> {
   /**
-   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   * createFromReadableStream from @rangojs/router/internal/deps/ssr
    */
   createFromReadableStream: <T>(
     stream: ReadableStream<Uint8Array>,
@@ -86,7 +86,7 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => Promise<ReactDOMReadableStream>;
 
   /**
-   * injectRSCPayload from rsc-html-stream/server
+   * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
    */
   injectRSCPayload: (
     rscStream: ReadableStream<Uint8Array>,
@@ -218,10 +218,10 @@ function createSsrEventController(opts: {
  *
  * @example
  * ```tsx
- * import { createSSRHandler } from "rsc-router/ssr";
- * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
- * import { injectRSCPayload } from "rsc-html-stream/server";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
  * export const renderHTML = createSSRHandler({
  *   createFromReadableStream,
@@ -263,6 +263,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       let payload: Promise<RscPayload> | undefined;
       let handlesPromise: Promise<HandleData> | undefined;
       let ssrContextValue: NavigationStoreContextValue | undefined;
+      let rootPromise: Promise<React.ReactNode> | undefined;
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
@@ -296,17 +297,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         };
 
         // Build content tree from segments.
-        // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
-        const reconstructedRoot = renderSegments(
-          resolved.metadata?.segments ?? [],
-          {
+        // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+        // Memoize like payload/handles above: renderSegments is async, so
+        // React.use() on a fresh promise suspends and replays SsrRoot, which
+        // would re-run the entire segment-tree build on every initial render.
+        rootPromise ??= Promise.resolve(
+          renderSegments(resolved.metadata?.segments ?? [], {
             rootLayout: resolved.metadata?.rootLayout,
-          },
+          }),
         );
-        let content: React.ReactNode =
-          reconstructedRoot instanceof Promise
-            ? React.use(reconstructedRoot)
-            : reconstructedRoot;
+        let content: React.ReactNode = React.use(rootPromise);
 
         // Wrap content with ThemeProvider if theme is enabled
         if (themeConfig) {

package/src/static-handler.ts

@@ -37,8 +37,6 @@ import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { isUnderTestRunner } from "./runtime-env.js";
 
-// -- Types ------------------------------------------------------------------
-
 export interface StaticHandlerOptions {
   /**
    * Keep handler in server bundle for live fallback (default: false).
@@ -62,11 +60,8 @@ export interface StaticHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
-// -- 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).
+// Process-stable fallback id counter (mirrors createHandle/createLoader/Prerender).
+// Only assigned in bare unit tests where the Vite plugin did not inject an id.
 let runtimeStaticIdCounter = 0;
 
 export function Static<TParams extends Record<string, any> = {}>(
@@ -75,8 +70,6 @@ export function Static<TParams extends Record<string, any> = {}>(
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
-// -- Implementation ---------------------------------------------------------
-
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
   optionsOrId?: StaticHandlerOptions | string,
@@ -100,25 +93,12 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  // 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. 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++}`;
   }
@@ -131,11 +111,6 @@ export function Static<TParams extends Record<string, any>>(
   };
 }
 
-// -- Type guard -------------------------------------------------------------
-
-/**
- * Type guard to check if a value is a StaticHandlerDefinition.
- */
 export function isStaticHandler(
   value: unknown,
 ): value is StaticHandlerDefinition {

package/src/testing/cache-status.ts

@@ -12,7 +12,14 @@
  * 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).
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
  *
  * 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.
@@ -37,18 +44,6 @@ 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> {
@@ -71,25 +66,6 @@ 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,
@@ -131,19 +107,6 @@ export interface CacheSink {
   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 = {
@@ -154,9 +117,6 @@ export function createCacheSink(): CacheSink {
   return { sink, events };
 }
 
-/**
- * Filter captured telemetry events down to `cache.decision` events.
- */
 export function filterCacheDecisions(
   events: readonly TelemetryEvent[],
 ): CacheDecisionEvent[] {
@@ -164,3 +124,39 @@ export function filterCacheDecisions(
     (e): e is CacheDecisionEvent => e.type === "cache.decision",
   );
 }
+
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export function assertCacheDecision(
+  events: readonly TelemetryEvent[],
+  routeKey: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const segments = filterCacheDecisions(events).flatMap(
+    (d) => d.segments ?? [],
+  );
+  const seg = segments.find((s) => s.id === routeKey);
+  if (seg === undefined) {
+    const known = segments.map((s) => s.id);
+    throw new Error(
+      `assertCacheDecision: no cache.decision segment for routeKey "${routeKey}". ` +
+        `Seen: ${known.length > 0 ? known.join(", ") : "(none)"}. Wire ` +
+        `createRouter({ telemetry: createCacheSink().sink }) and drive an RSC request.`,
+    );
+  }
+  if (seg.cacheStatus !== expected) {
+    throw new Error(
+      `assertCacheDecision: routeKey "${routeKey}" expected "${expected}" but got "${seg.cacheStatus}".`,
+    );
+  }
+}

package/src/testing/collect-handle.ts

@@ -17,27 +17,6 @@
 
 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>>,
@@ -55,9 +34,7 @@ export function collectHandle<TData, TAccumulated>(
     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.
+  // Drop empty arrays matching production behavior (segment count/indices).
   const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
   return collectFn(nonEmpty);
 }