Upgrade nuqs to ^2.9.2 before the shared hook lands

[frankieramirez]

Part of #353.

Question

Nothing to decide — upgrade nuqs from 2.9.0 to ^2.9.2 and confirm the seven tables still behave.

Why this blocks a decision. nuqs#1501: useQueryState(s) permanently desyncs after a discarded render under the React Router adapter with React 19 concurrent rendering. It reproduces on 2.9.0 and 2.9.1 and is fixed in 2.9.2 (released 2026-07-24). Surfaced while resolving #356; independently verified — frontend/package-lock.json resolves nuqs to exactly 2.9.0, so this repo is on an affected version now.

The URL-synchronisation half of #360 cannot be designed honestly against a version with a known desync bug: any decision to put more state in the URL, or to have the shared hook own URL sync at all, would be weighing a hazard that is already fixed upstream. And a hook mounted at seven call sites is the wrong moment to discover it.

package.json already declares ^2.9.2-compatible range (^2.9.0), so this is a lockfile move, not a dependency-policy change.

Work:

1. npm --prefix frontend install nuqs@^2.9.2, committing the lockfile change.
2. Run the frontend suite (npm --prefix frontend test) and npm run lint.
3. Exercise SeriesTable's URL state by hand — page next/prev, sort change, filter change, browser back/forward, and a reload at a deep ?page=N — since that is the only table with URL-synced state and the existing tests do not cover the back/forward path.
4. Note in the resolution whether anything in nuqs 2.9.1/2.9.2 changes the conclusions recorded in Is the nuqs shadow-state dance still necessary on nuqs 2.9? #356, particularly the batching behaviour (part 5) that the shared hook is expected to rely on.

Explicitly not in this ticket: removing the shadow useState in SeriesTable.tsx:98-104. #356 established it is unnecessary, but its removal is entangled with the page-clamp effect at :267-276 and belongs to the migration, not to a dependency bump. Keep this ticket to the upgrade so a regression has one obvious suspect.

[frankieramirez]

Resolution

nuqs is on 2.9.2. Branch fix/upgrade-nuqs-2-9-2, commit 31c41367 — not yet merged.

frontend/package.json moved ^2.9.0 → ^2.9.2 and the lockfile followed. Raising the floor (rather than only the lock) is deliberate: it stops a fresh npm install resolving back onto an affected version. The only other lockfile movement is nuqs' own dependency @standard-schema/spec 1.0.0 → 1.1.0, which dedupes against the copy vitest already pulled. Nothing else moved.

npm run lint clean, npm --prefix frontend test 141/141 across 27 files, production build succeeds.

The bug was live here

Confirmed rather than assumed: src/App.tsx:10 imports NuqsAdapter from nuqs/adapters/react-router/v7 on React 19 — exactly the configuration nuqs#1501 affects — and SeriesTable.tsx is the only nuqs consumer in the codebase, so the blast radius was the Library page's sort/filter/page state.

The upstream fix (nuqs#1502) is three lines in useQueryStates.ts, and worth knowing the shape of because the shared hook inherits it:

} else if (onCommittedPathname && internalState !== stateRef.current) {
  // Recover a render-phase state update lost with an abandoned render.
  setInternalState(stateRef.current)
}

stateRef.current is authoritative and internalState is a mirror that could drift permanently. That is the same class of failure the shadow useState in SeriesTable.tsx:98-104 was believed to guard against — now fixed at the layer that actually owns it, which strengthens #356's recommendation to delete the shadow state rather than weakening it.

Step 4 — does 2.9.1/2.9.2 change anything #356 concluded?

No. Every load-bearing finding survives, and two get stronger. Checked against the installed 2.9.2 dist/, not the changelog.

• Part 5 batching — unchanged, byte for byte. All three rules are still in the throttle queue (dist/debounce-ILelSlWG.js, renamed from debounce-CmIkjWrj.js): highest rate limit wins (timeMs > this.timeMs, :142), push escalates the batch (:138), shallow: false escalates (:140). The single-updateMap-per-tick mechanism is intact. The shared hook's setParams({ sort: next, page: null }) plan is safe.
• Part 1's mechanism — unchanged. emitter.emit(...) still fires synchronously inside update, outside any transition (dist/index.js:554); startTransition still only rides along in the URL-write options (:565). The conclusion that the adapter's transition was never what protected the shadow state still holds.
• Stronger — limitUrlUpdates precedence is now honoured in code, not just documented. 2.9.1 #1480 fixed it; dist/index.js:568 now reads callOptions.limitUrlUpdates ?? parser.limitUrlUpdates ?? limitUrlUpdates. Part 4 asserted call > parser > hook-global as a fact about 2.9.0, where it was true of the docs only. If the shared hook ever gives search its 300ms via a per-parser option inside one useQueryStates map, that now actually works.
• Stronger — 2.9.1 #1469 shares internal state across duplicate library copies (new dist/key-isolation-*.js), reinforcing Part 4's single-emitter premise.
• No change touches the sortParser/eq gap (Part 3) or the two-hook shape (Part 4).

#356's owed production-build caveat is now discharged — its probes ran under jsdom on React's dev build; everything below is a real Chrome pass against vite build output.

Step 3 — the manual pass

The real database holds 1 series, so pagination was not exercisable against it. Rather than write to the user's database I served the production build behind a throwaway proxy that forwards everything to the live backend on :8090 (real auth, real config) and overrides only GET /api/series with 63 synthetic rows — 4 pages at 20/page. Data is synthetic; the router, adapter, build and browser are real.

Step	Result
page next ×2	?page=1 → rows 20–39, ?page=2 → rows 40–59
page prev	?page=1 → rows 20–39
sort change while on page=1	?sort=ComicName.asc, page dropped in the same write, rows reset to 0
status filter while on page=1	?sort=ComicName.asc&status=Paused, page dropped, sort preserved, only paused rows
search (300ms) while on page=1	?search=Marvel, page dropped — the mixed 300ms/50ms batch collapses correctly
back/forward across a route change	left to /, back restored ?sort=ComicName.asc&status=Paused exactly; forward/back round-trip stable, no drift
deep reload at ?page=2	page silently dropped — see below

history.length never grew across any of it, confirming history: "replace" is not being escalated by a batched key.

One defect found — pre-existing, not a regression

A cold load of /library?page=2&sort=ComicName.desc renders page 0 and rewrites the URL to ?sort=ComicName.desc. Deep-linking to a page does not work.

Cause is the page-clamp effect at SeriesTable.tsx:267-276, not nuqs. On first render data is empty, so pageCount is 0, so maxPage is 0, so it clamps localPage 2 → 0 and writes setParams({ page: null }) — before the data ever arrives.

A/B'd on the same build pipeline and same data: reinstalled nuqs@2.9.0, rebuilt, reloaded the identical URL — byte-identical wrong result. So this predates the upgrade and the upgrade neither causes nor fixes it. This is exactly the clamp effect #356 flagged as the removal trap entangled with the shadow state; recorded here so the migration inherits a reproduction rather than rediscovering it.

Left alone per this ticket's "explicitly not in this ticket" boundary, so a regression still has one obvious suspect.

[frankieramirez]

PR opened: #374. Leaving this ticket open until that merges, per the map's "tickets carry through to merged PRs" note.

[frankieramirez]

Landed on main — #374 merged as 979d94ce, nuqs now ^2.9.2. #360 is unblocked.