fix(router): a Suspense boundary still suspended on the client hydrates as the server rendered it when location state is read outside it - #1116

Problem

On a document load where the history entry has location state (after a reload, or Back to a page that loads its document), a <Suspense> boundary that couldn't hydrate yet got client-rendered over its server HTML. React logged Hydration failed because the server rendered text didn't match the client in dev and minified error #418 in production. A boundary is in that state when the client suspends it after the document has finished streaming: its React.lazy chunk is still loading, or a deferred-hydration gate such as a hydrate-when-visible island holds it. It only happened when a useLocationState reader rendered next to that boundary, outside it, had state.

Before / after

// page.tsx (server)
export function Page() {
  return (
    <>
      <FlashBanner />            {/* "use client": useLocationState(Flash) */}
      <Suspense fallback={<Spinner />}>
        <LazyChart />            {/* React.lazy chunk still loading at reveal */}
      </Suspense>
    </>
  );
}

• Before: the banner received the entry's state while LazyChart's boundary was still dehydrated. When the chunk arrived, the boundary hydrated against the new values, so React threw away the server HTML (dev: "Hydration failed …"; prod: Fix prefetched parallel navigation streaming #418).
• After: the boundary hydrates as the server rendered it. The banner shows undefined until every boundary of the document has hydrated, and then the entry's state, which matches what useLocationState already promised during hydration.

Consumer example

"use client";
import { useLocationState } from "@rangojs/router/client";
import { Flash } from "../location-states";

export function FlashBanner() {
  const flash = useLocationState(Flash); // undefined during hydration, then the entry's state
  return flash ? <p role="status">{flash.text}</p> : null;
}

Nothing changes in consumer code.

Semantics

Trade-off: in the fourth row, a deferred-hydration gate with no upper bound (an off-screen hydrate-when-visible island) keeps location state undefined until it hydrates. Late handle data already waited this long whenever no location-state reader sat outside the boundary.

Code change summary

The change is in src/browser/react/NavigationProvider.tsx (about 20 lines):

• The reveal transition now changes only the hydration barrier counter. Nothing reads HydrationBarrierContext, so React holds that commit until every boundary has hydrated.
• An effect after the barrier's commit sets location state in its own transition and releases the hydration lock.
• Why there: React 19.3 tells a dehydrated boundary about a context change only through propagation from an ancestor that bails out, and that propagation skips the boundary. A reader of the changed context outside the boundary therefore let the transition commit around it. The rule that follows is that the barrier must be the only update in its transition lane. Setting location state in a second startTransition inside the same callback lands in the same lane and fails the same tests.
• The full account, with react-dom 19.3.0 source locations, is in docs/internal/execution-model.md ("The reveal barrier is alone in its lane"). context.ts, feature-map.md and handle-push-ownership.md point to it.

Test plan

• Userland, render-route-hydrate.test.tsx through renderRoute: "a boundary suspended on the client when the document is revealed hydrates as rendered…", StrictMode and non-StrictMode, including a useHandle reader with late pushes. Red on base: recoverableErrors = ["Hydration failed …"].
• Internal, location-state-hydration.test.tsx on the real initBrowserApp document. Red on base.
• e2e expectGatedBoundaryHydratesWithOutsideReader (shared-e2e), dev and (production), router test-app and cloudflare-basic:
  • The test waits until no boundary is pending, then until the outside reader shows state or 3 s pass. It asserts the reader still showed the server's value before the chunk opened.
  • Red on the base provider in all four (dev "Hydration failed …", production Fix prefetched parallel navigation streaming #418); green with the fix, 3/3 repeats.
• Mutation testing (Opus review):
  • Fail: full revert (4 fail); location state back in the barrier (4 fail); lock released at barrier start (2 fail); separate transition in the same event (4 fail).
  • Pass: without startTransition; without the new guard, which is defensive and kept.
• Neighbouring e2e, dev and production: suspense-cases, held-boundary, location-state and hydration-detection in the test-app (173); the first three in cloudflare-basic (122).
• pnpm run typecheck, pnpm run test:unit:all, pnpm run lint, pnpm run format, check:e2e-bucketing, check-e2e-parity --strict, check:skills, check:docs-api.

Also in this PR: location state from a commit with no new page

The same failure had a second way in. A commit that renders no new page during the hydration window set location state at once. Such commits are:

• a shallow navigation (router.push(url, { revalidate: false, state }) or <Link revalidate={false} state>);
• a Back/Forward or revalidation that keeps every segment;
• an action that sets location state;
• a fill's server-set state.

A reader outside a boundary that was still suspended on the client got the new state, and the boundary then hydrated against it. Reproduced in both apps: dev "Hydration failed … + shallow-value − empty", production #418.

Fix (NavigationProvider.tsx): while the window is open, the treeless-commit subscription leaves the state in the event controller. The barrier's post-commit effect then applies the latest state. It defers rather than releasing the lock, because such a commit mounts no new tree, and it adds no wait on navigation.

Same trade-off: a deferred-hydration gate that stays shut holds such state with no upper bound, while the URL and search params already show the new entry. Two state-only commits during the window coalesce, and the latest wins. A navigation during the window replaces the deferred state with its own.

Tests:

• location-state-hydration.test.tsx "a treeless commit before/after reveal waits for a boundary suspended on the client", StrictMode on and off (4 cases).
• Userland render-route-hydrate.test.tsx "a back/forward while a boundary is suspended on the client waits for it to hydrate" (2 cases).
• e2e expectGatedBoundaryHydratesAfterShallowNavigation, dev and (production), both apps, 3/3 repeats. All red before the fix.
• Opus mutation testing: removing the guard, or limiting it to shallow navigations, to before the reveal or to after it, each turns cases red.
• Neighbouring e2e: test-app dev 93 and production 82; cloudflare-basic dev 66 and production 66.

Notes

• The action path is covered by unit tests through the shared commit path (commitLocationState(x, true)), not by its own e2e.
• React bug: this relies on a React 19.3 behaviour — the lanes marked on a dehydrated boundary are lost after a selective-hydration commit. If React fixes it, nothing here breaks. If React changes how it hydrates a boundary under a changed provider, the red-before-green tests running against [email protected] catch it on upgrade.