[natew]

Implements #1039 on the Standard Schema protocol. No Zod dependency, adapter or inspection. Owner direction and design are in the Contrast plan plans/contrast/one-search-params-schema.md. This approves building; merging and any minor release stay with review.

API

• useSearchParams() and useSearchParams({ global }) still return a read-only URLSearchParams.
• useSearchParams(schema, { global? }) returns [output, update]. The schema gets every query key as a string, or a string array when the key repeats. Path params are left out.
• update(partial, { replace? }) merges into the current URL via router.push (default) or router.replace. Path params, other keys and the hash stay. null/undefined removes a key. Writable values are string, number, boolean and arrays of those (repeated keys). Fields whose output is not writable (a Date) take the schema's input type; anything else throws TypeError.
• A rejected URL throws SearchValidationError in render, so the nearest error boundary isolates it. Async schemas throw a TypeError.
• Link gains searchParams, typed from the destination route. It is a second overload, so existing Link typing (including template-literal hrefs) is unchanged.
• validateSearch and validateParams now share one synchronous Standard Schema runner; their exports are unchanged.

Discovery and generated types

generateRouteTypes parses each route file, its ancestor layouts and their static relative or tsconfig-path imports with oxc, finds useSearchParams(schema) calls and writes SearchParamTypes into routes.d.ts as typeof import('./file')['name'], so TypeScript derives the shape. No app module is evaluated and no schema internals are read. Editing a scanned file regenerates the types (checked live: adding and removing a component updates the route's keys).

Choices to review

• Flat keys (?page=2, arrays as repeated keys), not the issue's file-name prefix or dot-notation. Prefixes would break existing URLs and renames. Two components on one route using the same key get the intersection of their types. The owner has not picked key naming; this is the default.
• getPathFromState fix. The router read repeated keys as arrays but wrote arrays as comma-joined text. It now writes repeated keys (unit test added). This changes URLs written for array params from a=1,2 to a=1&a=2.
• Link's params object still comma-joins arrays through resolveHref; searchParams uses repeated keys. Left as is.
• Discovery limits: the schema must be an exported const (or imported from one) or a package export; inline schemas and dynamic or template hrefs stay untyped, and an unassociated call logs a one-time warning. Route type generation previously read file names only; it now also reads route sources.
• Schemas must accept string | string[] where a key may repeat.
• No function-updater form for update.

Proof

• Probe across Zod 4, Valibot, ArkType and a hand-written schema: input vs output types, update types, default, transform, invalid, async, and serialization edges (null/undefined removal, empty array, special characters, key collision, hash, repeated unrelated keys, rejected objects/Dates). tsc and runtime both clean.
• Web flow in tests/test (Playwright, 28 checks): defaults, push and replace history, no remount, unrelated keys, arrays as repeated keys, back/forward, hash, malformed value breaking only its boundary, typed link hrefs, dynamic route with path param. Type errors confirmed for misspelled keys, wrong values and object-href forms.
• oxlint clean; packages/one unit tests pass except package-exports (vite-native-hmr dist not built in the worktree), packedClosure and the calendar ios test (the last also fails on main).
• Native: no native build. Covered only by the existing unit/protocol tests. Unverified on native: whether useParams includes extra keys there, and update from an unfocused screen.

[natew]

The approved feature is included in the held One minor batch #1027 on tm/macos-resume at f129407d405971e87020a698faa66a4d72827194, preserving the original authors through three focused picks:

• 34de23710d → abd23a2131
• b344b8b7e4 → 6314681e1f
• c95c352b8b → f129407d40

The full feature patch identity is unchanged. Only the two root export files combined pre-existing release-branch context automatically. The existing reviewer has been asked to check that overlap through the original review chain.

Validation on the containing branch: normal One package build and typecheck pass; existing routing/native-engine checks report 10 passed and one pre-existing skipped test. Generated declarations remain clean. No new browser or native runtime validation is claimed here.

This PR remains the source and review record. Delivery is through the held minor batch, rather than a separate main patch. Broader feature and stable-release approval remain unchanged.

[redbar0n]

Awesome! I recommend renaming validateSearch to validateSearchParams for clarity and coherence.