@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/server/cookie-parse.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical inbound-Cookie-header parser.
+ *
+ * Kept as a dependency-free leaf so any consumer (request-context, the host
+ * dispatcher, tests) can share one implementation without pulling a heavier
+ * module's graph. A duplicate copy in middleware-cookies.ts was removed; the
+ * host copy in cookie-handler.ts was collapsed onto this one. Not part of the
+ * public export surface.
+ */
+export function parseCookiesFromHeader(
+  cookieHeader: string | null,
+): Record<string, string> {
+  if (!cookieHeader) return {};
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name) {
+      const raw = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(raw);
+      } catch {
+        // Malformed percent-encoding: fall back to raw value
+        cookies[name] = raw;
+      }
+    }
+  }
+
+  return cookies;
+}

package/src/server/cookie-store.ts

@@ -8,8 +8,13 @@
  */
 
 import type { CookieOptions } from "../router/middleware-types.js";
-import { getRequestContext } from "./request-context.js";
-import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+import { getRequestContext, _getRequestContext } from "./request-context.js";
+import {
+  isInsideCacheScope,
+  getCurrentLoaderBodyId,
+  isInsideHandlerInvokedLoaderBody,
+} from "./context.js";
+import { isInsideCacheExecScope } from "../cache/cache-exec-scope.js";
 
 /**
  * A single cookie entry returned by get() and getAll().
@@ -60,7 +65,8 @@ export interface CookieStore {
  */
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext(ctx, "cookies");
+  assertNotInsideCacheContext("cookies");
+  assertNotInsideShellCapture(ctx, "cookies");
   return createCookieStore(ctx);
 }
 
@@ -84,18 +90,31 @@ export interface ReadonlyHeaders {
 type HeadersIterator<T> = IterableIterator<T>;
 
 /**
- * Throw if called inside a "use cache" function.
- * Reading request-scoped data (cookies, headers) inside a cached function
- * produces results that vary per request but the cache key does not include
- * those values, leading to one user's data being served to another.
+ * Throw if called inside a cache boundary — either a "use cache" function
+ * (`isInsideCacheExecScope()` — the AsyncLocalStorage scope the cache runtime
+ * enters around the cached body) or a `cache()` DSL boundary
+ * (`isInsideCacheScope()` — the render-store flag set while resolving a
+ * `type: "cache"` route entry).
+ *
+ * Reading request-scoped data (cookies, headers) inside a cached scope
+ * produces per-request values that are NOT reflected in the cache key, so
+ * they would be frozen into the shared cache entry and served to the wrong
+ * users. This is the same hazard for both scopes: a `cache()` boundary caches
+ * everything except loaders (it is the document-level "PPR shell"), so a read
+ * here is baked into the shell exactly like a `"use cache"` return value is
+ * baked into its cache entry.
+ *
+ * Both checks are scoped so loaders stay exempt — loaders are the dynamic
+ * "holes" of a cached document and always run fresh. `isInsideCacheScope()`
+ * returns false inside loaders by construction; `isInsideCacheExecScope()`
+ * follows the cached body's own async chain, so a loader running in PARALLEL
+ * with a slow "use cache" fetch on the same request reads cookies() freely.
+ * (Scar: the previous INSIDE_CACHE_EXEC stamp on the shared RequestContext
+ * made exactly that parallel read throw for the cached fetch's whole
+ * execution window — see cache-exec-scope.ts.)
  */
-function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
-  if (
-    ctx !== null &&
-    ctx !== undefined &&
-    typeof ctx === "object" &&
-    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
-  ) {
+function assertNotInsideCacheContext(fnName: string): void {
+  if (isInsideCacheExecScope()) {
     throw new Error(
       `${fnName}() cannot be called inside a "use cache" function. ` +
         `Request-scoped data (cookies, headers) varies per request but is not ` +
@@ -106,6 +125,82 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
         `  const data = await getCachedData(locale); // locale is now in the cache key`,
     );
   }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `${fnName}() cannot be called inside a cache() boundary. ` +
+        `A cache() scope caches everything except loaders, so request-scoped ` +
+        `data (cookies, headers) read here would be frozen into the shared ` +
+        `cached shell and served to other users. Read it inside a loader ` +
+        `instead — loaders always run fresh on every request, even on a cache hit:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
+}
+
+/**
+ * Throw if called during the ACTIVE background shell-capture render
+ * (`_shellCaptureRun` true on the derived request context built by
+ * shell-capture.ts). The captured shell prelude is shared across every user
+ * hitting the URL, so a request-scoped read here would bake one user's
+ * cookies/headers into markup served to others — same hazard as the cache
+ * scopes above, at the document tier. DSL segment loaders need no exemption:
+ * the live lane is masked (never executed) during capture, and the bake lane
+ * is exactly what this guard exists for.
+ *
+ * HANDLER-INVOKED loader bodies (`await ctx.use(Loader)` from a handler) are
+ * EXEMPT — the consumption-lane rule: handler consumption yields a BAKED
+ * shared copy in every artifact tier, and the cache-purity guards above
+ * already permit identity reads there (cache()/"use cache" bake the same
+ * reads today). Guarding only the PPR tier made the same code legal under
+ * cache() but capture-refusing under ppr (issue #672 / #674). The trade is
+ * documented: an identity read in a handler-consumed loader bakes the CAPTURE
+ * request's value into the shared shell; client-side consumption (useLoader)
+ * is the live lane.
+ *
+ * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
+ * is also present during the FOREGROUND render (it means "a capture is wanted"),
+ * and the foreground must read cookies/headers normally to serve the real user.
+ * Only the derived capture context sets `_shellCaptureRun`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers()) whose values
+ * become markup. Response directives (invalidateClientCache(),
+ * keepClientCache()) stay callable: during capture they are header effects on
+ * a discarded response, and on the live HIT path the full pipeline runs so their
+ * headers flow to the client normally.
+ *
+ * The throw makes such a route PPR-ineligible by construction: the capture
+ * render errors, nothing is stored, and every request keeps getting the
+ * normal axis-1 render.
+ */
+function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    typeof ctx === "object" &&
+    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
+  ) {
+    if (isInsideHandlerInvokedLoaderBody()) return;
+    // Flag the capture context BEFORE throwing: inside an executing bake-lane
+    // loader this throw is swallowed by wrapLoaderPromise into per-loader error
+    // UI, which would bake silently into the shared shell. The capture checks
+    // the flag after the render and refuses (shell-capture.ts). Also record
+    // WHICH loader body (if any) made the read, so the refusal warning can
+    // name the real source instead of hardcoding a lane — the read may come
+    // from a bake-lane loader OR from handler/render code (issue #672).
+    (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
+      fnName;
+    (
+      ctx as { _shellCaptureGuardTrippedLoaderId?: string }
+    )._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+    throw new Error(
+      `${fnName}() cannot be called while capturing a shared shell ` +
+        `(shell-cache middleware). The captured shell is served to every user ` +
+        `of this URL, so request-scoped data read here would leak one user's ` +
+        `${fnName === "cookies" ? "cookies" : "headers"} to others. Read it ` +
+        `inside a loader instead — loaders are never captured and always run ` +
+        `fresh per request:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
@@ -127,7 +222,8 @@ const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
  */
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext(ctx, "headers");
+  assertNotInsideCacheContext("headers");
+  assertNotInsideShellCapture(ctx, "headers");
   return new Proxy(ctx.request.headers, {
     get(target, prop, receiver) {
       if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
@@ -144,6 +240,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("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("keepClientCache");
+  ctx._setKeepCacheDirective();
+}
+
 /**
  * Create a CookieStore backed by a RequestContext.
  * @internal Shared between cookies() shorthand and context methods.

package/src/server/handle-store.ts

@@ -13,6 +13,25 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+/**
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+export function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
 function createLateHandlePushError(
   handleName: string,
   segmentId: string,
@@ -26,10 +45,6 @@ function createLateHandlePushError(
   return error;
 }
 
-/**
- * Deep clone handle data to create a snapshot.
- * @internal
- */
 function cloneHandleData(data: HandleData): HandleData {
   const clone: HandleData = {};
   for (const handleName in data) {
@@ -77,6 +92,26 @@ export interface HandleStore {
    */
   onError?: (error: Error) => void;
 
+  /**
+   * Track a promise on the AUXILIARY (loader) settlement lane. Aux tracking
+   * keeps the store OPEN for pushes (a mid-body `ctx.handle(H)(...)` from a
+   * streaming loader is legal until this lane drains) WITHOUT joining
+   * `settled` — the handler barrier that rendered()-readers, the document
+   * handle snapshot, and prerender/cache collection wait on. Two lanes exist
+   * because loader bodies stream: joining them to `settled` would block SSR
+   * markup and hydration on the slowest loader (ssr-root.tsx and
+   * rsc-router.tsx both drain the document handle stream in blocking
+   * positions), and would self-deadlock any loader awaiting ctx.rendered().
+   */
+  trackAuxiliary<T>(promise: Promise<T>): Promise<T>;
+
+  /**
+   * Promise that resolves when the store is sealed AND BOTH lanes (handler +
+   * auxiliary) have drained. Late-push legality and default stream completion
+   * key on this, not on `settled`.
+   */
+  readonly fullySettled: Promise<void>;
+
   /**
    * Push handle data for a specific handle and segment.
    * Multiple pushes to the same handle/segment accumulate in an array.
@@ -86,16 +121,32 @@ export interface HandleStore {
 
   /**
    * Get all collected handle data after all handlers have settled.
-   * Waits for `settled`, then returns the finalized data.
+   * Waits for `settled` (handler lane), then returns the data at that point.
    */
   getData(): Promise<HandleData>;
 
   /**
    * Get an async iterator that yields handle data on each push.
-   * The iterator completes when all handlers have settled.
+   * Completes at the chosen settlement barrier: "fullySettled" (default —
+   * nav/action payloads, whose consumer applies each yield progressively) or
+   * "settled" (the document lane, whose consumers drain to completion in
+   * blocking positions and must not wait on loader bodies).
    * Each yield contains the full accumulated state (not just the delta).
+   * Safe for concurrent consumers (per-consumer version cursor).
+   */
+  stream(
+    until?: "settled" | "fullySettled",
+  ): AsyncGenerator<HandleData, void, unknown>;
+
+  /**
+   * Document-lane late channel: yields full-state updates for pushes that
+   * land AFTER the handler barrier (streaming loader bodies), completing at
+   * fullySettled. Returns without yielding when the auxiliary lane is empty
+   * by the time `settled` resolves. The client consumes this post-hydration
+   * (rsc-router.tsx) and merges via the same application path as nav-lane
+   * progressive handle updates.
    */
-  stream(): AsyncGenerator<HandleData, void, unknown>;
+  streamLate(): AsyncGenerator<HandleData, void, unknown>;
 
   /**
    * Get handle data for a specific segment (for caching).
@@ -136,20 +187,64 @@ export interface HandleStore {
 export function createHandleStore(): HandleStore {
   const data: HandleData = {};
 
-  // Settlement barrier: resolved only when sealed AND inflight === 0.
-  // seal() signals "no more track() calls". Each track() increments
-  // inflightCount, each promise.finally() decrements. settled resolves
-  // once both conditions are met — even if tracks are added while
-  // earlier ones are still in flight.
+  // Settlement barriers: `settled` (handler lane) resolves when sealed AND
+  // handler inflight === 0. `fullySettled` additionally waits for the
+  // auxiliary (loader) lane. seal() signals "no more track() calls"; each
+  // track/trackAuxiliary increments its lane's count, each promise settle
+  // decrements. Barriers resolve once their conditions are met — even if
+  // tracks are added while earlier ones are still in flight.
   let sealed = false;
   let inflightCount = 0;
+  let auxInflightCount = 0;
   let drainWaiters: (() => void)[] = [];
+  let fullDrainWaiters: (() => void)[] = [];
+
+  // Swap the waiter list out before resolving: a resolver may synchronously
+  // re-await and push onto the fresh list, which must not be drained by this
+  // pass. All three waiter lists (drain, full-drain, emission) flush through
+  // here so that ordering rule cannot drift between them.
+  function flushWaiters(waiters: (() => void)[]): void {
+    for (const resolve of waiters) resolve();
+  }
+
+  // Both lanes settle identically — the handler lane (`track`) gates `settled`,
+  // the auxiliary loader lane (`trackAuxiliary`) gates `fullySettled`. Shared so
+  // neither copy can lose this rule: .then() rather than .finally(), because
+  // .finally() re-throws on a NEW branch, producing an unhandled rejection that
+  // can crash the process when the tracked promise rejects.
+  function trackSettlement<T>(
+    promise: Promise<T>,
+    release: () => void,
+  ): Promise<T> {
+    const onSettle = () => {
+      release();
+      notifyDrain();
+    };
+    promise.then(onSettle, onSettle);
+    return promise;
+  }
 
   function notifyDrain() {
     if (sealed && inflightCount === 0 && drainWaiters.length > 0) {
       const waiters = drainWaiters;
       drainWaiters = [];
-      for (const resolve of waiters) resolve();
+      flushWaiters(waiters);
+    }
+    if (sealed && inflightCount === 0 && auxInflightCount === 0) {
+      if (streamConsumed && !completed) {
+        // Late-push guard + stream termination key on FULL drain, so a
+        // streaming loader body's ctx.handle() push stays legal until the
+        // auxiliary lane empties. Armed only once a stream consumer exists —
+        // getData()-only paths (prerender collection) keep their historical
+        // no-guard behavior.
+        completed = true;
+        signalEmission();
+      }
+      if (fullDrainWaiters.length > 0) {
+        const waiters = fullDrainWaiters;
+        fullDrainWaiters = [];
+        flushWaiters(waiters);
+      }
     }
   }
 
@@ -159,44 +254,50 @@ export function createHandleStore(): HandleStore {
     notifyDrain();
   }
 
-  // Queue for pending emissions and resolver for waiting consumer
-  let pendingEmissions: HandleData[] = [];
-  let emissionResolver: (() => void) | null = null;
+  // Emission versioning. Each push bumps `version`; every stream consumer
+  // keeps its own cursor and yields whenever the version advanced past it.
+  // Multi-consumer safe (the document "settled" stream and the late channel
+  // overlap until the handler barrier): a single dirty bit + single resolver
+  // slot would drop wakeups for all but one consumer.
+  let version = 0;
+  let emissionWaiters: (() => void)[] = [];
   let completed = false;
+  let streamConsumed = false;
 
-  // Signal that a new emission is available
+  // Wake every waiting consumer (new push or a settlement barrier fired).
   function signalEmission() {
-    if (emissionResolver) {
-      const resolver = emissionResolver;
-      emissionResolver = null;
-      resolver();
+    if (emissionWaiters.length > 0) {
+      const waiters = emissionWaiters;
+      emissionWaiters = [];
+      flushWaiters(waiters);
     }
   }
 
   // Wait for the next emission or completion
-  function waitForEmission(): Promise<void> {
-    if (pendingEmissions.length > 0 || completed) {
+  // Resolve when the consumer's cursor is behind the current version, the
+  // given done-flag reader reports termination, or a new signal arrives.
+  function waitForEmission(seen: number, isDone: () => boolean): Promise<void> {
+    if (version > seen || isDone()) {
       return Promise.resolve();
     }
     return new Promise((resolve) => {
-      emissionResolver = resolve;
+      emissionWaiters.push(resolve);
     });
   }
 
   return {
     track<T>(promise: Promise<T>): Promise<T> {
       inflightCount++;
-      // Use .then(onSettle, onSettle) instead of .finally() to avoid
-      // creating an unhandled rejection branch when the tracked promise
-      // rejects (e.g. error route handlers). .finally() re-throws the
-      // rejection on a new branch that nobody catches, which can crash
-      // the server process.
-      const onSettle = () => {
+      return trackSettlement(promise, () => {
         inflightCount--;
-        notifyDrain();
-      };
-      promise.then(onSettle, onSettle);
-      return promise;
+      });
+    },
+
+    trackAuxiliary<T>(promise: Promise<T>): Promise<T> {
+      auxInflightCount++;
+      return trackSettlement(promise, () => {
+        auxInflightCount--;
+      });
     },
 
     seal() {
@@ -210,6 +311,15 @@ export function createHandleStore(): HandleStore {
       });
     },
 
+    get fullySettled(): Promise<void> {
+      if (sealed && inflightCount === 0 && auxInflightCount === 0) {
+        return Promise.resolve();
+      }
+      return new Promise<void>((resolve) => {
+        fullDrainWaiters.push(resolve);
+      });
+    },
+
     push(handleName: string, segmentId: string, value: unknown): void {
       if (completed) {
         const error = createLateHandlePushError(handleName, segmentId);
@@ -225,8 +335,8 @@ export function createHandleStore(): HandleStore {
       }
       data[handleName][segmentId].push(value);
 
-      // Queue a snapshot for emission
-      pendingEmissions.push(cloneHandleData(data));
+      // Bump the version; each consumer's cursor decides when to clone+yield.
+      version++;
       signalEmission();
     },
 
@@ -235,45 +345,75 @@ export function createHandleStore(): HandleStore {
       return this.settled.then(() => cloneHandleData(data));
     },
 
-    async *stream(): AsyncGenerator<HandleData, void, unknown> {
-      // Auto-seal: stream() is called after all track() registrations.
+    async *stream(
+      until: "settled" | "fullySettled" = "fullySettled",
+    ): AsyncGenerator<HandleData, void, unknown> {
+      streamConsumed = true;
       sealInternal();
-
-      // Set up completion handler
-      this.settled.then(() => {
-        completed = true;
+      // Re-evaluate: the store may have been sealed and drained BEFORE this
+      // consumer existed (seal() then stream()); sealInternal early-returns
+      // then, so the completed flag must be armed here.
+      notifyDrain();
+
+      // Per-consumer termination flag driven by the chosen barrier. The
+      // global `completed` (late-push guard) always keys on FULL drain via
+      // notifyDrain — a "settled"-scoped consumer finishing does not make
+      // later loader pushes illegal.
+      let done = false;
+      const barrier = until === "settled" ? this.settled : this.fullySettled;
+      barrier.then(() => {
+        done = true;
         signalEmission();
       });
 
-      // Initial small delay to batch rapid synchronous pushes
-      // This allows multiple handles pushing in quick succession to be batched
+      // Batch rapid synchronous pushes with initial delay
       await new Promise((resolve) => setTimeout(resolve, 0));
 
-      // If we already have data, yield the accumulated state
-      if (Object.keys(data).length > 0) {
-        // Clear pending emissions since we're yielding current state
-        pendingEmissions = [];
-        const snapshot = cloneHandleData(data);
-        yield snapshot;
+      let seen = 0;
+      while (true) {
+        if (version > seen && Object.keys(data).length > 0) {
+          seen = version;
+          yield cloneHandleData(data);
+        }
+        if (done) break;
+        await waitForEmission(seen, () => done);
       }
+    },
 
-      // Continue streaming on each push
-      while (!completed) {
-        await waitForEmission();
-
-        // Yield all pending emissions (yield latest only)
-        if (pendingEmissions.length > 0) {
-          // Skip intermediate states, yield the latest
-          const latest = pendingEmissions[pendingEmissions.length - 1];
-          pendingEmissions = [];
-          yield latest;
-        }
+    async *streamLate(): AsyncGenerator<HandleData, void, unknown> {
+      streamConsumed = true;
+      sealInternal();
+      // Re-evaluate: the store may have been sealed and drained BEFORE this
+      // consumer existed (seal() then stream()); sealInternal early-returns
+      // then, so the completed flag must be armed here.
+      notifyDrain();
+
+      // Skip everything the handler-barrier snapshot already carried; the
+      // document consumers (SSR seed + pre-hydration drain) deliver that
+      // state. This channel exists only for pushes that land AFTER `settled`
+      // — streaming loader bodies writing meta/breadcrumbs mid-body.
+      await this.settled;
+      let seen = version;
+      if (auxInflightCount === 0) {
+        // Auxiliary lane already drained: every loader push (if any) beat the
+        // handler barrier and rode the normal snapshot. Nothing late follows —
+        // handler pushes after settled are illegal by contract.
+        return;
       }
 
-      // Final yield only if there are pending emissions that weren't yielded
-      // (handles that pushed after our last yield but before completion)
-      if (pendingEmissions.length > 0) {
-        yield cloneHandleData(data);
+      let done = false;
+      this.fullySettled.then(() => {
+        done = true;
+        signalEmission();
+      });
+
+      while (true) {
+        if (version > seen) {
+          seen = version;
+          yield cloneHandleData(data);
+        }
+        if (done) break;
+        await waitForEmission(seen, () => done);
       }
     },
 
@@ -295,13 +435,12 @@ export function createHandleStore(): HandleStore {
         if (!data[handleName]) {
           data[handleName] = {};
         }
-        // Replace with replayed data (not append) to avoid handle bleeding between routes.
-        // When a cached segment is restored, its handles should replace any existing data
-        // for that segment, not accumulate on top of data from a different route.
+        // Replace (not append) to avoid handle bleeding between routes.
+        // Cached segment restoration should replace existing data for that
+        // segment, not accumulate on top of data from a different route.
         data[handleName][segmentId] = [...segmentHandles[handleName]];
       }
-      // Trigger emission for streaming
-      pendingEmissions.push(cloneHandleData(data));
+      version++;
       signalEmission();
     },
   };