fix(router): useLocationState hydrates as undefined inside Suspense (#992) - #1017

Closes #992.

Problem

useLocationState reads history.state on the first client render once <html> has data-hydrated. The root sets that attribute from an effect after it hydrates. A reader inside a <Suspense> boundary often hydrates later. By then data-hydrated is set, so the initializer renders the stored value while the server rendered undefined. React reports a hydration mismatch and client-renders the boundary.

The old deferred read covered readers that hydrate with the root. In an RSC app most per-page UI sits under <Suspense>, so it missed the common case. Seen with React 19.2. A long-lived history entry (soft navigation, then hard reload) is what puts a value in history.state for that reload.

Before / after

export const GridState = createLocationState<{ count: number }>();

export function Grid() {
  const state = useLocationState(GridState);
  return <p>{state?.count ?? 0}</p>;
}

// page
<Suspense fallback={<p>…</p>}>
  <Grid />
</Suspense>

router.push(url, { state: [GridState({ count: 3 })] });
// then hard-reload that history entry

Before, the server renders 0, the boundary hydrates 3, and React reports "Hydration failed because the server rendered text didn't match the client". After, the hydrating render is 0, and the reader updates to 3 on the next render. No API change. Callers do not adopt anything.

End-to-end consumer example

A filter grid whose selection lives in location state, rendered under the route's suspense boundary:

export const Filters = createLocationState<{ category: string }>();

"use client";
export function FilterBar() {
  const filters = useLocationState(Filters);
  return <p>{filters?.category ?? "all"}</p>;
}

// server page
<Suspense fallback={<p>Loading filters</p>}>
  <FilterBar />
</Suspense>

The shopper picks shoes, which navigates with state: [Filters({ category: "shoes" })]. They reload. The server still renders all. The bar then shows shoes without a hydration mismatch, including under StrictMode.

Semantics

Code-change summary

useLocationState in packages/rangojs-router/src/browser/react/location-state.ts now reads through useSyncExternalStore(subscribe, getSnapshot, () => undefined). React uses the server snapshot for whichever render is hydrating, wherever the component sits, then re-renders with the client snapshot. Flash's read-once value stays in a ref so the clear-after-paint effect cannot clobber it under StrictMode. createLocationState options are unchanged. location-state-shared.ts is unchanged.

Test plan

• packages/rangojs-router/src/testing/__tests__/location-state-hydration.test.tsx (new, 8 tests). Pins: hydrating persistent and flash readers stay undefined then show the stored value, with and without StrictMode; a non-hydrating mount reads on the first render; popstate and __rsc_locationstate; plain useLocationState() late-hydrates from history.state.state. Before the hook change, the persistent, flash, and plain hydration tests failed because the first render was the stored value.
• Existing renderRoute location-state tests (3), mini (4), and cloudflare-basic location-state (7) passed after the change.
• pnpm run typecheck
• pnpm run test:unit:all
• pnpm run lint
• pnpm run format
• Dev and production e2e for location state. Not run. The new test hydrates with hydrateRoot in happy-dom while data-hydrated is already set. It is not a streamed Suspense boundary inside the RSC shell.

Notes

No migration. Stored history entries are unchanged. A reader still updates to the stored value immediately after hydration, so a reload can still flash the empty value for one paint. That is the same catch-up the root-hydration path already did.

Added 2026-10-03: e2e coverage and a hydration mode for renderRoute

Rebased onto main (0.20.0 plus #1016 and #1019). Three commits on top of the fix.

Dev and production e2e, both apps

New page in the router test-app (/location-state/late-suspense/:gate) and in cloudflare-basic (/location-state-late-suspense/:gate): a useLocationState reader inside a <Suspense> boundary whose server content is held until the test releases it (GET <page>/:gate/release, 15 s safety timeout). The shared body expectLateSuspenseReaderHydratesClean (tests/shared-e2e/src/index.ts) loads the page, waits for the root to hydrate, asserts the fallback is still visible, releases the boundary, writes state, reloads, repeats, and requires the stored value with no hydration error (guardHydrationErrors). "The boundary hydrates after the root" is therefore asserted, not left to a timer.

Red with main's hook in the router test-app: dev fails with Hydration failed because the server rendered text didn't match the client, production with Minified React error #418. Green with the fix: router location-state file dev 60 passed, production 29 passed; cloudflare-basic dev 15 passed, production 13 passed. The late-Suspense test was repeated 3 times per mode in the router app, 3/3 each.

renderRoute(routes, { hydrate: true })

The PR's hook test had to call hydrateRoot with hand-written server HTML because renderRoute mounts with createRoot. The repo rule is to extend the primitive when it cannot reach a feature, so renderRoute (from @rangojs/router/testing/dom) gains a hydration mode:

const { serverHtml, recoverableErrors, getByTestId } = await renderRoute(
  [{ path: "/grid", Component: Grid }],
  { hydrate: true, locationState: [[GridState, { count: 3 }]] },
);
expect(serverHtml).toContain(">0<"); // the server never sees history.state
expect(recoverableErrors).toEqual([]); // no hydration mismatch
expect(getByTestId("count").textContent).toBe("3");

Limits, also in the docs: history, localStorage and navigator stay defined in the server pass, so a hook reading them outside a server snapshot can pass here and still mismatch in real SSR; an attribute-only mismatch is not a recoverable error.

Tests (src/testing/__tests__/render-route-hydrate.test.tsx): server HTML and interactivity of a simple component; a deliberate typeof window mismatch is reported; the #992 contract through the primitive with a real late <Suspense> boundary, StrictMode on and off (red on main's hook: Hydration failed because the server rendered text didn't match the client); the root marker; suspended content; an unguarded document read rejects and restores the globals; an old RTL is refused.

Docs: skills/testing/client-components.md, skills/testing/SKILL.md, skills/testing/server-tree.md, docs/testing.md, docs/internal/feature-map.md, and two ## Unreleased CHANGELOG entries (the fix, and the new option).

Gate on the pushed head: pnpm run typecheck, pnpm run test:unit:all (router 7117, RSC 440), pnpm run lint, pnpm run format, check:e2e-bucketing, check:e2e-parity --strict, check:docs-api; no *.gen.ts drift.

Notes:

• The @testing-library/react check inspects render's source for onRecoverableError. Reviewers preferred a behavioral probe or a raised peer range; it is kept because an old version silently reporting no hydration errors is worse than a throw, and the peer range is unchanged.
• feat(router)!: location state is versioned by the app version; createLocationState gains clearOnReload (#994) #1020 is stacked on this branch and needs a rebase after this merges.