@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/skills/use-cache/SKILL.md

@@ -52,8 +52,9 @@ export async function ProductCard({ id }: { id: string }) {
 
 ## Named Cache Profiles
 
-Define profiles in createRouter. Profile names map to `"use cache: <name>"` and
-`cache('<name>')` in the DSL.
+Define profiles in createRouter. Profile names map to `"use cache: <name>"` in
+the directive. The DSL `cache()` does not accept a string profile name; use an
+options object (`cache({ ttl: 60 })`) or the `"use cache: <name>"` directive.
 
 ```typescript
 createRouter({
@@ -340,13 +341,13 @@ that same namespace). The separate `revalidate()` export is the client-update ax
 
 ## Interaction with Other Caching
 
-| Mechanism          | Granularity        | When       | Use case                                        |
-| ------------------ | ------------------ | ---------- | ----------------------------------------------- |
-| `"use cache"`      | Function/component | Runtime    | Cache individual data fetches or components     |
-| `cache()` DSL      | Route segment      | Runtime    | Cache entire route subtrees with children       |
-| `cache('profile')` | Route segment      | Runtime    | Same as cache() with a named profile            |
-| `Static()`         | Route segment      | Build-time | Render once, never re-render                    |
-| `Prerender()`      | Route segment      | Build-time | Pre-render known params, optional live fallback |
+| Mechanism            | Granularity        | When       | Use case                                        |
+| -------------------- | ------------------ | ---------- | ----------------------------------------------- |
+| `"use cache"`        | Function/component | Runtime    | Cache individual data fetches or components     |
+| `cache()` DSL        | Route segment      | Runtime    | Cache entire route subtrees with children       |
+| `cache({ ttl })` DSL | Route segment      | Runtime    | Cache a route subtree with explicit options     |
+| `Static()`           | Route segment      | Build-time | Render once, never re-render                    |
+| `Prerender()`        | Route segment      | Build-time | Pre-render known params, optional live fallback |
 
 ## Dev Mode
 

package/src/browser/event-controller.ts

@@ -168,6 +168,22 @@ export interface ActionHandle extends Disposable {
   startStreaming(): StreamingToken;
   /** Record segments that were revalidated */
   recordRevalidatedSegments(segmentIds: string[]): void;
+  /**
+   * Claim the subset of a location-state payload this action may write. A key
+   * is claimed only if no later-initiated action in the SAME cohort has already
+   * claimed it, so same-key concurrent writes resolve to the last-initiated
+   * action while distinct keys from every action survive. Recording the claim
+   * stops a later-settling earlier action from overwriting it. Arbitration is
+   * scoped to the action's cohort (its originating history entry, captured at
+   * startAction), so an action on one entry cannot suppress an action on
+   * another that happens to write the same slot.
+   *
+   * Contract: this guarantees the FINAL value is the last-initiated action's,
+   * not that the loser is never momentarily visible. When an earlier-initiated
+   * action settles first, its value is merged and observable until the
+   * later-initiated winner's response lands and overwrites it.
+   */
+  claimLocationState(state: Record<string, unknown>): Record<string, unknown>;
   /** Complete the action with result */
   complete(result?: unknown): void;
   /** Fail the action with error */
@@ -194,7 +210,12 @@ export interface EventController {
   abortNavigation(): void;
 
   // Action operations
-  startAction(actionId: string, args: unknown[]): ActionHandle;
+  startAction(
+    actionId: string,
+    args: unknown[],
+    /** Originating history entry key; scopes location-state arbitration. */
+    cohort?: string,
+  ): ActionHandle;
   abortAllActions(): void;
 
   // State access
@@ -308,6 +329,28 @@ export function createEventController(
 
   const concurrentRevalidatedSegments = new Set<string>();
 
+  // Monotonic dispatch counter: every startAction() takes the next value
+  // (private), so a larger sequence means the action was initiated later.
+  let actionDispatchSeq = 0;
+
+  // Concurrent location-state arbitration, scoped PER COHORT (history entry).
+  // Each cohort owns a slotKey->winningDispatchSeq map plus a refcount of its
+  // inflight actions; claimLocationState() consults its own cohort's map so
+  // same-key writes within one entry resolve to the last-initiated action
+  // regardless of settle order, while actions on different entries never
+  // compete. A cohort's map is freed once its LAST action's cleanup runs — the
+  // same brief post-settle grace (doSettle's 100ms timer) as other action
+  // teardown, not when every action everywhere settles — so a long-running
+  // action in one cohort can never retain arbitration keys from other cohorts
+  // that have since drained. It is never cleared in clearConsolidation, which
+  // fires
+  // per-action on divert/error and would let a later-settling earlier action
+  // wrongly reclaim a key a sibling already won.
+  const cohortArbitration = new Map<
+    string,
+    { keySeq: Map<string, number>; inflight: number }
+  >();
+
   let activeStreamCount = 0;
 
   let handleData: HandleData = {};
@@ -510,10 +553,29 @@ export function createEventController(
   // Action Operations
   // ========================================================================
 
-  function startAction(actionId: string, args: unknown[]): ActionHandle {
+  function startAction(
+    actionId: string,
+    args: unknown[],
+    cohort?: string,
+  ): ActionHandle {
     const id = `${actionId}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    // Private to this handle: never exposed on the returned ActionHandle.
+    const dispatchSeq = actionDispatchSeq++;
     const abort = new AbortController();
 
+    // Register this action under its cohort (originating history entry). The
+    // cohort's arbitration is created on first use and freed when its last
+    // action settles (see doSettle). Keyless entries share the "" cohort.
+    const cohortId = cohort ?? "";
+    let arb = cohortArbitration.get(cohortId);
+    if (!arb) {
+      arb = { keySeq: new Map<string, number>(), inflight: 0 };
+      cohortArbitration.set(cohortId, arb);
+    }
+    // const so the captured reference stays non-undefined inside doSettle.
+    const arbitration = arb;
+    arbitration.inflight++;
+
     // Track if this action started while others were pending (concurrent)
     const hadConcurrent = inflightActions.size > 0;
     if (hadConcurrent) {
@@ -537,11 +599,28 @@ export function createEventController(
     let settled = false;
     let streamingEnded = false;
     let actionCompleted = false;
+    let cohortReleased = false;
     let pendingResult:
       | { type: "success"; value?: unknown }
       | { type: "error"; value: unknown }
       | null = null;
 
+    // Release this action's hold on its cohort arbitration exactly once: drop
+    // the refcount and, only if the map still points at THIS arbitration object,
+    // delete it. A newer generation may have replaced it (e.g. abortAllActions
+    // cleared the map and a fresh action recreated the same cohort id), so a
+    // stale settlement must never delete the newer one by id.
+    function releaseCohort() {
+      if (cohortReleased) return;
+      cohortReleased = true;
+      if (
+        --arbitration.inflight <= 0 &&
+        cohortArbitration.get(cohortId) === arbitration
+      ) {
+        cohortArbitration.delete(cohortId);
+      }
+    }
+
     function doSettle() {
       if (settled) return;
       settled = true;
@@ -549,6 +628,9 @@ export function createEventController(
       // Cleanup after brief delay (allow useAction to read result)
       setTimeout(() => {
         inflightActions.delete(id);
+        // Free this cohort's arbitration once its last action has settled, so
+        // a long-running action elsewhere cannot pin keys from a drained entry.
+        releaseCohort();
         // Check for consolidation
         if (inflightActions.size === 0) {
           // All actions done - reset tracking
@@ -625,6 +707,26 @@ export function createEventController(
         segmentIds.forEach((id) => concurrentRevalidatedSegments.add(id));
       },
 
+      claimLocationState(state: Record<string, unknown>) {
+        const winning: Record<string, unknown> = {};
+        // Arbitrate against this action's OWN captured arbitration object, not a
+        // live map lookup: a concurrent map clear/replace (abortAllActions, a
+        // stale settlement) must not make this action silently stop recording
+        // and accept every key.
+        const keySeq = arbitration.keySeq;
+        for (const key of Object.keys(state)) {
+          const prevSeq = keySeq.get(key);
+          // Strictly-greater: a later-initiated action wins a key over an
+          // earlier one in the same cohort regardless of arrival order. Equal
+          // cannot happen (dispatchSeq is unique per action).
+          if (prevSeq === undefined || dispatchSeq > prevSeq) {
+            keySeq.set(key, dispatchSeq);
+            winning[key] = state[key];
+          }
+        }
+        return winning;
+      },
+
       complete(result?: unknown) {
         settleWith({ type: "success", value: result });
       },
@@ -646,6 +748,10 @@ export function createEventController(
       [Symbol.dispose]() {
         // If aborted, another navigation/error took over - don't touch state
         if (abort.signal.aborted) {
+          // Aborted actions skip doSettle, so release the cohort hold here to
+          // keep the per-cohort refcount balanced (no leak when an action is
+          // aborted individually rather than via abortAllActions).
+          releaseCohort();
           inflightActions.delete(id);
           notify();
           notifyAction(actionId);
@@ -680,6 +786,7 @@ export function createEventController(
     }
     hadAnyConcurrentActions = false;
     concurrentRevalidatedSegments.clear();
+    cohortArbitration.clear();
     notify();
     // Notify all action listeners directly by subscription ID.
     // actionListeners keys are subscription IDs (possibly short names like

package/src/browser/partial-update.ts

@@ -545,6 +545,18 @@ export function createPartialUpdater(
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
+        // Mirror the partial branch's history-key staleness guard (above): the
+        // await above is a real async suspension, so the user may have navigated
+        // away while this background revalidation was draining. Dropping a late
+        // full-update here prevents it from clobbering the freshly committed UI
+        // of the page the user moved to.
+        const historyKeyNow = store.getHistoryKey();
+        if (historyKeyNow !== historyKeyAtStart) {
+          debugLog(
+            `[Browser] Stale revalidation (full update): history key changed (${historyKeyAtStart} -> ${historyKeyNow}), skipping UI update`,
+          );
+          return;
+        }
         startTransition(() => {
           if (fullHasTransition && addTransitionType) {
             addTransitionType("action");

package/src/browser/prefetch/cache.ts

@@ -268,6 +268,23 @@ export function storePrefetch(
   cache.set(key, { entry, timestamp: now });
 }
 
+/**
+ * Remove a single stored prefetch entry. Used to evict an entry whose body
+ * stream stalled after headers arrived (its payload / streamComplete never
+ * settle), so future prefetches and navigation refetch instead of dedupe-ing
+ * against — and awaiting — a stuck entry.
+ *
+ * Identity-guarded: only evicts when the entry CURRENTLY stored under `key` is
+ * the exact `entry` we published. A generation check alone is insufficient —
+ * after this entry is consumed (consumePrefetch) and a fresh prefetch
+ * republishes under the SAME key in the SAME generation, a gen-only guard would
+ * delete that valid newer entry. Reference identity drops only our own stalled
+ * entry.
+ */
+export function removePrefetch(key: string, entry: DecodedPrefetch): void {
+  if (cache.get(key)?.entry === entry) cache.delete(key);
+}
+
 /**
  * Capture the current generation. The returned value is passed to
  * storePrefetch so it can detect stale completions.

package/src/browser/prefetch/fetch.ts

@@ -22,6 +22,7 @@ import {
   markPrefetchInflight,
   setInflightPromiseWithAliases,
   storePrefetch,
+  removePrefetch,
   clearPrefetchInflight,
   currentGeneration,
   type DecodedPrefetch,
@@ -44,6 +45,19 @@ type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 
 let decoder: PrefetchDecoder | null = null;
 
+/**
+ * Hard ceiling for ANY prefetch fetch (hover/direct AND queue-driven). A server
+ * that stalls leaves the fetch pending forever — its `.finally()` never runs,
+ * `clearPrefetchInflight` never fires, and `hasPrefetch(key)` stays true,
+ * permanently deduping every future prefetch of that URL. The hover path passes
+ * no signal; the queue passes its own AbortController signal that only aborts on
+ * navigation, never on a stall — so the timeout is layered on BOTH (combined
+ * with any caller signal via AbortSignal.any) and aborts the stalled fetch so it
+ * settles (rejects) and the inflight key is always released. Generous so a
+ * slow-but-live response is never cut short.
+ */
+const PREFETCH_FETCH_TIMEOUT_MS = 30_000;
+
 /**
  * Wire the RSC decoder used to eagerly decode prefetched responses. Called
  * once from initBrowserApp with the same createFromFetch the navigation client
@@ -149,6 +163,47 @@ function executePrefetchFetch(
     : [wildcardKey, sourceKey];
   for (const k of inflightKeys) markPrefetchInflight(k);
 
+  // Always layer a stall timeout. It covers BOTH "no response ever arrives"
+  // (strands the inflight key) AND "the body stalls after headers" (leaves a
+  // published entry whose payload/streamComplete never settle, that future
+  // prefetches dedupe against and navigation awaits forever). Applies to the
+  // hover/direct path (no caller signal) and the queue-driven path (whose caller
+  // signal only aborts on navigation, never on a stall). On fire it aborts the
+  // fetch/stream and evicts the published entry if one exists; it is NOT cleared
+  // when headers arrive (see below) — it is cleared when the stream completes, or
+  // in `.finally()` for paths that publish no streaming entry.
+  let publishedKey: string | undefined;
+  let publishedEntry: DecodedPrefetch | undefined;
+  const timeoutController = new AbortController();
+  const timeoutId: ReturnType<typeof setTimeout> = setTimeout(() => {
+    timeoutController.abort();
+    // Body stalled after headers: evict the published-but-never-settling entry
+    // so future prefetches/navigation refetch. Identity-guarded (pass the exact
+    // entry) so a fresh entry republished under the same key — after this one was
+    // consumed — is NOT dropped. The abort cancels the tee (its finally resolves
+    // streamComplete) and rejects the eager decode.
+    if (publishedKey !== undefined && publishedEntry !== undefined) {
+      removePrefetch(publishedKey, publishedEntry);
+    }
+  }, PREFETCH_FETCH_TIMEOUT_MS);
+  let effectiveSignal: AbortSignal;
+  if (!signal) {
+    effectiveSignal = timeoutController.signal;
+  } else if (typeof AbortSignal.any === "function") {
+    // Combine the caller's signal (navigation-abort) with the timeout so either
+    // can settle the fetch.
+    effectiveSignal = AbortSignal.any([signal, timeoutController.signal]);
+  } else {
+    // Legacy runtime without AbortSignal.any: forward the caller's abort onto the
+    // timeout controller so a single signal carries both reasons.
+    effectiveSignal = timeoutController.signal;
+    if (signal.aborted) timeoutController.abort();
+    else
+      signal.addEventListener("abort", () => timeoutController.abort(), {
+        once: true,
+      });
+  }
+
   const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     // During an action's flight the state is not rotated, so the old
@@ -157,7 +212,7 @@ function executePrefetchFetch(
     // fence's HTTP-cache-bypass requirement applies to prefetch as well as
     // navigation fetches).
     ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
-    signal,
+    signal: effectiveSignal,
     headers: {
       "X-Rango-State": getRangoState(),
       "X-RSC-Router-Client-Path": window.location.href,
@@ -197,7 +252,7 @@ function executePrefetchFetch(
       const tracked = teeWithCompletion(
         response,
         () => resolveStreamComplete(),
-        signal,
+        effectiveSignal,
         // Speculative prefetch: a never-consumed/aborted stream error is benign.
         true,
       );
@@ -211,11 +266,23 @@ function executePrefetchFetch(
 
       const entry: DecodedPrefetch = { payload, streamComplete, scope };
       storePrefetch(storageKey, entry, gen);
+      // The stall timeout now owns the body stream: arm eviction (publishedKey)
+      // and clear the timer once the stream completes. The tee's finally resolves
+      // streamComplete on normal completion AND on abort, so a healthy body pays
+      // no lingering timer while a stalled one is evicted when the timer fires.
+      publishedKey = storageKey;
+      publishedEntry = entry;
+      streamComplete.then(() => clearTimeout(timeoutId));
       return entry;
     })
     .catch(() => null)
     .finally(() => {
       clearPrefetchInflight(inflightKeys[0]!);
+      // Clear the stall timer here ONLY for paths that published no streaming
+      // entry (null return / fetch error / abort): the operation is fully done.
+      // When an entry WAS published, the timer stays armed to bound the body
+      // stream and is cleared on streamComplete (above) or on fire (eviction).
+      if (publishedKey === undefined) clearTimeout(timeoutId);
     });
 
   setInflightPromiseWithAliases(inflightKeys, promise);

package/src/browser/react/Link.tsx

@@ -39,8 +39,18 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
-const isTouchDevice =
-  typeof window !== "undefined" && window.matchMedia("(hover: none)").matches;
+/**
+ * Read current touch/no-hover capability. Evaluated at the point of use (per
+ * render) rather than once at module load, so `prefetch="adaptive"` reacts to
+ * input-capability changes on hybrid devices (touch laptops, tablets gaining or
+ * losing a pointer) and after SSR -> hydrate. The SSR guard returns a stable
+ * `false` (pointer/hover default) so the resolved strategy doesn't drift on the
+ * server vs the first client render.
+ */
+function isTouchDevice(): boolean {
+  if (typeof window === "undefined") return false;
+  return window.matchMedia("(hover: none)").matches;
+}
 
 /**
  * Prefetch strategy for the Link component
@@ -57,6 +67,20 @@ export type PrefetchStrategy =
   | "adaptive"
   | "none";
 
+/**
+ * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
+ * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
+ * "hover" on pointer devices. Non-adaptive strategies pass through unchanged.
+ * Reads touch capability live (not a module-load snapshot) so the result
+ * tracks input-capability changes.
+ */
+export function resolveAdaptiveStrategy(
+  prefetch: PrefetchStrategy,
+): PrefetchStrategy {
+  if (prefetch !== "adaptive") return prefetch;
+  return isTouchDevice() ? "viewport" : "hover";
+}
+
 /**
  * Link component props
  */
@@ -228,9 +252,10 @@ export const Link: ForwardRefExoticComponent<
     return to === "/" ? bn : bn + to;
   }, [to, isExternal, ctx?.basename]);
 
-  // Resolve adaptive: viewport on touch devices, hover on pointer devices
-  const resolvedStrategy =
-    prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
+  // Resolve adaptive: viewport on touch devices, hover on pointer devices.
+  // isTouchDevice() is read here (per render), not from a module-load snapshot,
+  // so a device whose input capability changes resolves to the current value.
+  const resolvedStrategy = resolveAdaptiveStrategy(prefetch);
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);

package/src/browser/react/NavigationProvider.tsx

@@ -166,6 +166,14 @@ export interface NavigationProviderProps {
    * load (X-RSC-Reload), so the target app establishes its own shell on load.
    */
   appShellRef?: AppShellRef;
+
+  /**
+   * CSP nonce to expose via NonceContext. Production leaves this undefined — the
+   * browser has no nonce (it is a server-side HTML concern), and SSR provides the
+   * nonce through its own NonceContext.Provider. Test harnesses (renderRoute) set
+   * it to seed a nonce so components calling useNonce() can be exercised.
+   */
+  nonce?: string;
 }
 
 /**
@@ -200,6 +208,7 @@ export function NavigationProvider({
   version,
   basename,
   appShellRef,
+  nonce,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -377,9 +386,10 @@ export function NavigationProvider({
 
   // Match SSR tree shape: NonceContext.Provider is always present so
   // hydration sees the same component tree. Value is undefined on the
-  // client — CSP nonces are a server-side HTML concern.
+  // client — CSP nonces are a server-side HTML concern — unless a test
+  // harness seeded one via the `nonce` prop.
   content = (
-    <NonceContext.Provider value={undefined}>{content}</NonceContext.Provider>
+    <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
   );
 
   return (

package/src/browser/react/location-state-shared.ts

@@ -255,7 +255,14 @@ export function createLocationState<TState>(
         );
       }
       const key = getKey();
-      const current = window.history.state ?? {};
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `?? {}` only
+      // catches null/undefined, so spreading a primitive would yield indexed
+      // char/no keys and corrupt history.state. Coerce any non-object to a fresh
+      // dict — mirrors the delete() guard.
+      const existing = window.history.state;
+      const current =
+        existing !== null && typeof existing === "object" ? existing : {};
       window.history.replaceState(
         { ...current, [key]: value },
         "",
@@ -275,7 +282,12 @@ export function createLocationState<TState>(
       }
       const key = getKey();
       const current = window.history.state;
-      if (current == null || !(key in current)) return;
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `key in
+      // <primitive>` throws, so require an object before the `in` check; a
+      // primitive carries no slots, so deletion is a no-op.
+      if (current === null || typeof current !== "object" || !(key in current))
+        return;
       const next = { ...current };
       delete next[key];
       window.history.replaceState(next, "", window.location.href);

package/src/browser/react/use-href.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback } from "react";
 import { href, type ValidPaths } from "../../href-client.js";
 import { useMount } from "./use-mount.js";
 
@@ -36,5 +37,11 @@ import { useMount } from "./use-mount.js";
  */
 export function useHref(): (path: `/${string}`) => string {
   const mount = useMount();
-  return (path: `/${string}`) => href(path as ValidPaths, mount);
+  // Memoize on `mount` (stable within a route) so the returned function is
+  // referentially stable across re-renders — a consumer can safely pass it as a
+  // dependency or a prop to a memoized child without forcing re-renders.
+  return useCallback(
+    (path: `/${string}`) => href(path as ValidPaths, mount),
+    [mount],
+  );
 }

package/src/browser/react/use-link-status.ts

@@ -95,6 +95,13 @@ export function useLinkStatus(): LinkStatus {
 
   const prevPending = useRef(basePending);
 
+  // Tracks whether the most recent setOptimisticPending call pinned the value
+  // to a non-idle (loading) state. Used to decide whether to emit a release
+  // update when returning to idle, so the optimistic store doesn't stay pinned
+  // to `true` if a parent transition (e.g. the <Link> click / view transition
+  // commit) is still pending. Mirrors useNavigation's optimisticPinnedRef.
+  const optimisticPinnedRef = useRef(false);
+
   const [pending, setOptimisticPending] = useOptimistic(basePending);
 
   useEffect(() => {
@@ -109,11 +116,25 @@ export function useLinkStatus(): LinkStatus {
       if (isPending !== prevPending.current) {
         prevPending.current = isPending;
 
-        // Use optimistic update for immediate feedback during navigation
-        if (state.state !== "idle") {
+        const shouldPin = isPending && state.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic value so the spinner shows immediately even if
+          // a parent transition (e.g. <Link> click) defers the urgent
+          // setBasePending commit.
+          startTransition(() => {
+            setOptimisticPending(isPending);
+          });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale `true` while any parent
+          // transition is still pending, even after basePending flipped to
+          // false at navigation completion — leaving the link spinner stuck.
           startTransition(() => {
             setOptimisticPending(isPending);
           });
+          optimisticPinnedRef.current = false;
         }
 
         // Always update base state

package/src/browser/response-adapter.ts

@@ -88,8 +88,19 @@ export function teeWithCompletion(
   signal?: AbortSignal,
   silent = false,
 ): Response {
+  // Once-guard: a mid-stream read error runs both the finally block and the
+  // rejection's .catch, so onComplete must be settled exactly once across all
+  // paths (no-body early return, finally, catch).
+  let settled = false;
+  const settle = () => {
+    if (!settled) {
+      settled = true;
+      onComplete();
+    }
+  };
+
   if (!response.body) {
-    onComplete();
+    settle();
     return response;
   }
 
@@ -107,13 +118,13 @@ export function teeWithCompletion(
     } finally {
       if (onAbort) signal!.removeEventListener("abort", onAbort);
       reader.releaseLock();
-      onComplete();
+      settle();
     }
   })().catch((error) => {
     if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
-    onComplete();
+    settle();
   });
 
   return new Response(rscStream, {

package/src/browser/rsc-router.tsx

@@ -116,6 +116,8 @@ export interface BrowserAppContext {
   initialTheme?: Theme;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
+  /** Whether the hydrated tree should be wrapped in React.StrictMode */
+  strictMode?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
   /**
@@ -476,6 +478,7 @@ export async function initBrowserApp(
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    strictMode: initialPayload.metadata?.strictMode ?? true,
     version,
     appShellRef,
   };

package/src/browser/scroll-restoration.ts

@@ -191,10 +191,15 @@ export function saveCurrentScrollPosition(): void {
 
 /**
  * Persist scroll positions to sessionStorage.
- * If the write fails due to quota exceeded, progressively evict the oldest
- * entries and retry until it succeeds or the store is empty.
+ * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
+ * entries ONCE and retry the write a single time; if that still fails, remove
+ * our storage key entirely so we don't block other sessionStorage consumers.
+ * This is a single evict-then-retry-then-clear ladder, not a loop.
+ *
+ * Exported so that single eviction/retry/clear ladder is unit-testable directly.
+ * The browser drives it from the `pagehide` handler.
  */
-function persistToSessionStorage(): void {
+export function persistToSessionStorage(): void {
   try {
     sessionStorage.setItem(
       SCROLL_STORAGE_KEY,