You Might Not Need URL State

You Might Not Need URL State

Arguments:

• scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "app/workspace/[workspaceId]/tables/", "whole codebase"
• fix: whether to apply fixes (default: true). Set to false to only propose changes.

User arguments: $ARGUMENTS

Context

Shareable client view-state (active tab/panel, filters, search query, sort, pagination, selected-entity id, an open "view" modal/drawer that is a destination) lives in the URL via nuqs — driven by a co-located search-params.ts, never read via useSearchParams().get(...) and never mutated by hand-built query strings. Remote data stays in React Query; high-frequency / large / ephemeral / socket-synced state stays in Zustand; purely local UI stays in useState.

.claude/rules/sim-url-state.md is the source of truth — read it first.

References

Read these before analyzing:

1. .claude/rules/sim-url-state.md — the decision framework, conventions, debounced-input pattern, sort convention, selected-entity deep-link pattern, and the workflow-editor carve-out
2. https://nuqs.dev/docs/parsers — parsers (parseAsString/parseAsInteger/parseAsBoolean/parseAsStringLiteral/parseAsArrayOf/createParser)
3. https://nuqs.dev/docs/options — withDefault, history, shallow, clearOnDefault
4. https://nuqs.dev/docs/server-side — createSearchParamsCache for server reads

Anti-patterns to detect

1. Manual param reads for state: useSearchParams().get(...) or new URLSearchParams(window.location.search) used to read view-state. Replace with useQueryState/useQueryStates bound to a search-params.ts. (Read-once auth/invite/redirect signals are NOT view-state — the list and the per-surface new caveat are in .claude/rules/sim-url-state.md "Read-once auth / redirect signals"; leave those on useSearchParams.)
2. Hand-built query mutation: constructing a query string + router.replace/router.push to change a param on the current path. Use a nuqs setter. (A router.push that changes the route path is fine; an outbound new URLSearchParams building an href/window.open/download/API URL is fine.)
3. window.history.replaceState/pushState to mutate a param.
4. URL state duplicated into a store/useState + synced with an effect (or a popstate listener). The URL is the single source of truth; derive from it, don't mirror it. (Exception: the remembered list-preference snapshot for Files/Tables/Knowledge via useResourceListPreferences, per sim-url-state.md "Remembered list-preference exception".)
5. Objects in the URL: serializing a TableDefinition/SkillDefinition/etc. Store the id and derive the object from the loaded list (items.find(i => i.id === id)).
6. High-frequency / large state in the URL: cursor, pan/zoom, un-debounced keystrokes, big JSON blobs. Debounce text search via useDebouncedSearchSetter (never a local useState mirror + reconcile effect, and never inline limitUrlUpdates wiring); keep canvas/presence/resize state in Zustand.
7. Shareable view-state trapped in useState: a tab/filter/sort/pagination/selected-entity that should be a link but lives in local state. Migrate it to the URL.
8. Missing Suspense boundary: a component newly calling useQueryState/useQueryStates whose page entry has no <Suspense> wrapper (Next.js requires it for useSearchParams). Add one whose fallback is the route's loading.tsx default export, or a real in-page fallback for a continuity-focused peer switch that deliberately has no loading.tsx (never fallback={null} on a page entry; see sim-url-state.md "Suspense boundary").
9. import { z } for param validation in client code: use nuqs parsers instead.
10. Re-implemented shared wiring: a hand-rolled SORT_DIRECTIONS/default-sort constants/activeSort derivation instead of createSortParams + useUrlSort, or an inline debounced-search setter instead of useDebouncedSearchSetter/useSettingsSearch.