@r0hitsharma/router-kit 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,422 @@
+# @r0hitsharma/router-kit
+
+The generic pieces every [TanStack Router](https://tanstack.com/router) app
+rebuilds: search-param schemas that never reject, a root-route cleanup that keeps
+the address bar honest, an adapter for the design system's URL-synced table, and
+a test harness that follows entry URLs to a fixed point.
+
+Consumers adopt `@tanstack/react-router` directly — it stays a peer dependency
+and this package never wraps it, never owns your route tree, and never asks you
+to describe a route twice. See [DESIGN.md](./DESIGN.md) for the dependency-shape
+decisions and what is deliberately not here.
+
+## Installation
+
+```bash
+npm install @r0hitsharma/router-kit @tanstack/react-router zod
+```
+
+`@tanstack/react-router` and `zod` are both peer dependencies. See
+[peer-version policy](#peer-version-policy) for what that means for upgrades.
+
+## The thing to know first: the query decoder coerces
+
+Your `validateSearch` never sees the raw query text — `parseSearch` has already
+decoded it, and decoding rewrites values. So a parser written against `string`
+meets four other shapes in production:
+
+| URL             | value your parser actually receives |
+| --------------- | ----------------------------------- |
+| `?rows=25`      | the number `25`                     |
+| `?dense=true`   | the boolean `true`                  |
+| `?q=` or `?q`   | the empty string `''`               |
+| `?q=a&q=b`      | the array `['a', 'b']`              |
+
+This is the single most common source of "the param works in dev and vanishes in
+production" — `?page=2` typed by hand becomes a number, a `z.string()` schema
+rejects it, and the route throws.
+
+How much coercion depends on which grammar your router was built with, and both
+common choices coerce:
+
+- **`parseSearchWith(JSON.parse)`** — the router's default, so this is what you
+  get by not configuring one. It applies the decode above and then `JSON.parse`s
+  every value still a string, so `?v=1e5` arrives as `100000`, `?v=null` as
+  `null`, and `?v=-0` as `0`.
+- **`parseSearchWith((value) => value)`** — the identity parser, for apps whose
+  params are all plain text. It stops after the decode, so those three stay
+  strings.
+
+A hand-written `parseSearch` *is* the decoder rather than a stage after it, so it
+can opt out — but then it owns the whole grammar.
+
+`toSearchText` is idempotent under either: feed its own output back through a
+render-and-redecode round trip and you get that output unchanged. What it does
+**not** promise is byte-preserved URL text — under the default grammar `?v=1e5`
+canonicalizes to `100000`, because the value really was decoded to a number.
+
+That rewrite is the *grammar's*, and it costs no redirect: the router
+restringifies the decoded search whenever it builds a location, so its own
+mount-time commit puts `?v=100000` in the address bar. Step 2's rewrites are the
+ones that redirect. Either way it is one rewrite, not a loop; the second pass is
+stable, and step 4 pins the settled form of both under both grammars.
+
+`textParam()` and `oneOfParam()` absorb all of it. Reach for `toSearchText` or
+`toSearchOption` directly when a control needs to apply the same rule while
+writing a value back.
+
+## Usage
+
+### 1. Describe the search params
+
+```ts
+import { oneOfParam, textParam } from '@r0hitsharma/router-kit';
+import { z } from 'zod';
+
+export const TABS = ['overview', 'detail'] as const;
+
+export const sharedSearchSchema = z.object({
+  q: textParam(),
+  tab: oneOfParam(TABS),
+});
+```
+
+`textParam()` trims and treats empty as absent. `oneOfParam(allowed)` keeps a
+value only if it is in the set — pass the set `as const` so the inferred type is
+the literal union rather than `string`.
+
+Every builder here is **total** and **idempotent**:
+
+- **Total** — no input fails, so `validateSearch` never rejects a URL. A
+  hand-edited, stale, or bot-mangled param degrades to absent and the route still
+  renders.
+- **Idempotent** — normalizing an already-normalized value, through a full
+  render-and-redecode round trip, returns it unchanged.
+
+Idempotence is not a nicety; step 2 does not terminate without it.
+
+### 2. Make the URL tell the truth
+
+The schemas above drop values they cannot honour, but the address bar keeps them.
+So `?range=90D` reads as ninety days of data next to a chart showing the default
+— and that is the URL that gets shared. `createValidatedSearchRedirect` closes
+the gap on the root route: the URL is either the state on screen, or it is
+replaced with the one that is.
+
+```ts
+import { createValidatedSearchRedirect } from '@r0hitsharma/router-kit';
+import {
+  createRootRoute,
+  createRouter,
+  parseSearchWith,
+  stringifySearchWith,
+} from '@tanstack/react-router';
+
+// Params here are plain text; the default JSON round trip would write
+// `?rows=1` as `?rows=%221%22`.
+const parseSearch = parseSearchWith((value: string) => value);
+const stringifySearch = stringifySearchWith(JSON.stringify);
+
+const rootRoute = createRootRoute({
+  validateSearch: sharedSearchSchema,
+  component: App,
+  beforeLoad: createValidatedSearchRedirect({ stringifySearch }),
+});
+
+export const router = createRouter({
+  routeTree,
+  parseSearch,
+  stringifySearch,
+});
+```
+
+Pass the **same** `stringifySearch` to both. It is the one function the helper
+cannot derive, and a mismatch means the cleanup rewrites to a URL the router
+reads differently — which shows up as an infinite redirect. Step 4 is what
+catches that.
+
+Two properties, both load-bearing:
+
+- **It redirects to an explicit `href`, not `to: '.'`.** A relative target
+  resolves against the *pending* location, which during a `beforeLoad` is the
+  location being navigated to, not necessarily the one whose params were just
+  validated.
+- **It requires total, idempotent schemas.** The rewritten URL is validated
+  again on arrival, so a param whose output fails to re-validate to itself
+  redirects forever.
+
+#### Declare it or lose it
+
+Read the mechanism literally: **any key no schema on the route declares is
+deleted from the URL.** That is the feature — a stale `?range=90D` has to go —
+and it does not know what it is deleting. A param some *other* system owns is
+undeclared from this route's point of view, and it goes just as fast.
+
+The way this is found in production is an OAuth callback. The provider returns
+the user to `/callback?code=…&state=…`, the root cleanup runs first, and the
+callback route reads an empty query string. The login fails, and nothing in the
+logs mentions the URL. Same shape for a `?utm_source=…` a tag manager reads on
+load, or a `?session_id=…` a payment provider appends.
+
+Two ways out, and the first is usually right:
+
+1. **Declare the key in a route schema.** Then it is typed, it is part of the
+   route's contract, and `useSearch` can read it.
+2. **Allowlist it**, for keys something outside the route tree owns:
+
+```ts
+beforeLoad: createValidatedSearchRedirect({
+  stringifySearch,
+  preserveKeys: ['code', 'state'],
+});
+```
+
+An allowlisted key is exempt from the deletion *and* from the comparison, so its
+presence never triggers a rewrite on its own, and it cannot be the param that
+fails to converge. List only keys no schema declares: a listed key never
+overrides a value validation produced, but for a value validation *rejected*
+there is no applied value to lose to, so the rejected one survives in the address
+bar — which is the lie this whole step exists to remove.
+
+For the sibling case — a value that moved out of the query string on one branch
+while shared links still carry the old key — `createSearchParamStripper` drops
+one key and carries the rest across:
+
+```ts
+const itemDetailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/items/$itemId',
+  // The id rides in the path here, so a leftover `?item=` names a second one
+  // that nothing reads.
+  beforeLoad: createSearchParamStripper('item', { stringifySearch }),
+});
+```
+
+### 3. Sync a table to the URL
+
+`createUrlSyncedTableAdapter` builds the adapter the design system's
+`useUrlSyncedTableStateAdapter` takes, reading two search keys and writing them
+back with replace semantics.
+
+```ts
+import { useUrlSyncedTableStateAdapter } from '@r0hitsharma/design-system';
+import type { UseUrlSyncedTableReturn } from '@r0hitsharma/design-system';
+import { createUrlSyncedTableAdapter } from '@r0hitsharma/router-kit';
+import { useNavigate, useSearch } from '@tanstack/react-router';
+import { useMemo } from 'react';
+
+export function useItemsTableUrlState(): UseUrlSyncedTableReturn {
+  // Not strict: a table in a drawer can stay mounted on a route where this
+  // search does not exist, and both params then read as absent.
+  const search = useSearch({ from: '/items', shouldThrow: false });
+  const navigate = useNavigate();
+
+  const adapter = useMemo(
+    () =>
+      createUrlSyncedTableAdapter({
+        search,
+        sortKey: 'sort',
+        searchKey: 'q',
+        navigate,
+      }),
+    [search, navigate],
+  );
+
+  return useUrlSyncedTableStateAdapter(adapter);
+}
+```
+
+Four things worth knowing:
+
+- **`useMemo` is required, not tidy.** `useUrlSyncedTableStateAdapter` memoizes
+  the setters it returns *on the adapter object*, so a fresh object per render
+  makes `setGlobalFilter` a new reference every time. A debounced search commit
+  holding that reference as a dependency is then torn down and re-armed on every
+  unrelated re-render, and never fires under a burst of keystrokes.
+- **`useNavigate()`'s return value goes straight in.** No wrapper: the adapter
+  fixes all three navigation fields itself, and types each as the single value it
+  takes. It navigates with `to: '.'`, which keeps the current route's path params
+  without this package knowing your route tree. A relative target resolves
+  against the pending location if there is one, which is why it is wrong in a
+  `beforeLoad` (that runs *while* one is pending) and right from an event handler
+  (normally none is). The residual case is a write landing inside another
+  navigation's microtask window — a debounced search commit racing a link click.
+- **`sortKey` and `searchKey` have no defaults.** Two tables that silently share
+  `sort`/`q` leak whichever state was set last across every switch between them,
+  and it reads as a bug in the table rather than in the URL.
+- **The read is verbatim; the schema owns trimming.** A string param reaches the
+  table exactly as the URL holds it, whitespace included, so a write-read-write
+  round trip is lossless. It has to be: the hook renders `searchParam` back into
+  the search box, so an adapter that trimmed would make `'usd '` read back as
+  `'usd'`, land the next keystroke on `'usdc'`, and leave a two-word term
+  untypeable. Trim at the route boundary instead, where it is visible and
+  opt-out-able — `textParam()` does exactly that. Values the URL cannot mean (a
+  repeated key's array, an object) read as absent, and a number or boolean the
+  decoder produced reads as its text.
+
+### 4. Prove the entry URLs settle
+
+`settleEntryUrl` builds a memory-history router from **your exported
+`router.options`**, follows every `beforeLoad` redirect to a fixed point, and
+throws if the chain never gets there.
+
+```ts
+import { settleEntryUrl } from '@r0hitsharma/router-kit/testing';
+import { describe, expect, it } from 'vitest';
+
+import { router } from '../src/router';
+
+describe('entry URLs', () => {
+  it.each([
+    '/',
+    '/items?tab=bogus',
+    '/items/42?item=7',
+    '/unknown/deep/path',
+  ])('settles %s', async (url) => {
+    await expect(settleEntryUrl(router.options, url)).resolves.toBeDefined();
+  });
+
+  it('rewrites a rejected param out of the address bar', async () => {
+    const settled = await settleEntryUrl(router.options, '/items?tab=bogus');
+
+    expect(settled.url).toBe('/items');
+  });
+});
+```
+
+Both entry points are async, so `await` them. That is not incidental: a
+`beforeLoad` is often `async` — an auth guard or a context fetch — and its
+redirect then arrives as a rejected promise rather than a synchronous throw. A
+harness that did not await would report the *rejected* route as the settled one,
+so your spec would pass while production redirected somewhere else.
+
+It takes `router.options` rather than a route tree on purpose. `parseSearch`,
+`stringifySearch`, `trailingSlash`, `caseSensitive`, and `basepath` all decide
+what a URL *means*; a harness that rebuilt them would assert against a grammar
+your app does not use — passing while production breaks, or failing on a
+difference that exists only in the test. There is one description of the
+grammar, and it is the one the app runs with.
+
+Each throw covers a failure that is invisible from inside the app:
+
+- **Non-termination** is a hung tab with a spinning address bar. Here it is a
+  thrown error naming the cycle it walked. This is also what catches a
+  `stringifySearch` that disagrees with the router's.
+- **A schema that rejected the URL** is a thrown error naming the route and the
+  validation message. The router does not throw one: it records the rejection on
+  the match and carries on with a search no schema produced. So a harness that
+  did not look would report the one URL your schemas *could not* validate as
+  settled and clean. Step 1's builders are total, so this fires for a schema
+  that is not — a bare `z.number()` on a param, most often.
+
+It does **not** assert that a hop replaces rather than pushes, because a
+`beforeLoad` redirect cannot push: every path that follows one overrides
+`replace: true` over the redirect's own options. Such an assertion would fail a
+perfectly good `throw redirect({ to: '/login' })` — `replace` undefined, replaced
+anyway. `resolveEntryUrl` still reports `replace` if you want to pin what your
+own helper *declares*.
+
+Two options of yours are overridden rather than honoured, both because a
+headless run cannot mean them: `isServer` is forced false (client mode is what
+makes `beforeLoad` run the way a cold load runs it) and `scrollRestoration` is
+forced off. The second is not cosmetic — the router arms scroll restoration from
+its own constructor via bare `history` and `document` references, so leaving it
+on would throw `ReferenceError: history is not defined` before a route was
+matched, and every app that sets it would find the harness unusable. Neither
+option has any bearing on what a URL means.
+
+Under a `basepath` (or a `rewrite`), `settled.url` and `settled.hops` come back
+in the **router's** spelling — `/items`, not `/app/items`. Both spellings of an
+entry URL resolve to the same route, so pass whichever you have; but a redirect
+target built inside a `beforeLoad` is written in the router's space, so reporting
+your string verbatim would put two spellings of one URL in a single `hops` array.
+Assert against your route paths, the way you wrote them.
+
+Known limit: the harness supplies a `beforeLoad` with `location`, `matches`,
+`params`, and `search`. A `beforeLoad` that reads route `context` or calls
+`navigate` fails loudly here rather than being silently skipped — entry-time
+redirects do not normally need either, and a loud failure is the point.
+
+## Peer-version policy
+
+| Peer                     | Range         |
+| ------------------------ | ------------- |
+| `@tanstack/react-router` | `^1.170.0`    |
+| `zod`                    | `^4.0.0`      |
+
+Both are peers because a second copy of either would break something real:
+
+- **The router** carries its types through module augmentation. Your
+  `declare module '@tanstack/react-router' { interface Register { ... } }` binds
+  to one copy, so a second one leaves your route paths and search types
+  unavailable to it. React context is per-copy too, so hooks from one copy return
+  nothing inside the other's provider.
+- **zod** schemas built here are composed into `z.object({ ... })` in your app.
+  Schemas from two copies are not reliably interchangeable, and when they are
+  not, the failure reads as an opaque variance error at the route definition
+  rather than as a duplicate dependency.
+
+The floor is the line this package is developed and tested against, and the caret
+means router and zod patch/minor upgrades do not need a release here. The one
+thing to know when upgrading the router: the cleanup and the harness both read
+`_strictSearch`, a router-internal field. It is stable in practice, and this
+package's own suite fails loudly if it moves — but that is why the floor is
+recorded rather than left open.
+
+`@r0hitsharma/design-system` is **not** a dependency of this package, not
+even an optional peer. The table adapter's type is restated structurally; see
+[DESIGN.md](./DESIGN.md), which ships in the tarball alongside this file.
+
+## Exported surface
+
+From the root entry:
+
+| Export                            | Kind     | Module               |
+| --------------------------------- | -------- | -------------------- |
+| `toSearchText`                    | function | `search-params`      |
+| `toSearchOption`                  | function | `search-params`      |
+| `textParam`                       | function | `search-params`      |
+| `oneOfParam`                      | function | `search-params`      |
+| `SearchTextParam`                 | type     | `search-params`      |
+| `SearchOptionParam`               | type     | `search-params`      |
+| `createValidatedSearchRedirect`   | function | `validated-search`   |
+| `createSearchParamStripper`       | function | `validated-search`   |
+| `rendersSameSearch`               | function | `validated-search`   |
+| `SearchRecord`                    | type     | `validated-search`   |
+| `StringifySearch`                 | type     | `validated-search`   |
+| `CanonicalSearchOptions`          | type     | `validated-search`   |
+| `ValidatedSearchRedirectOptions`  | type     | `validated-search`   |
+| `ValidatedSearchContext`          | type     | `validated-search`   |
+| `SearchParamStripperContext`      | type     | `validated-search`   |
+| `createUrlSyncedTableAdapter`     | function | `table-adapter`      |
+| `UrlSyncedTableStateAdapter`      | type     | `table-adapter`      |
+| `UrlSyncedTableAdapterOptions`    | type     | `table-adapter`      |
+| `UrlSyncedTableNavigate`          | type     | `table-adapter`      |
+| `UrlSyncedTableNavigateOptions`   | type     | `table-adapter`      |
+
+From `@r0hitsharma/router-kit/testing`:
+
+| Export                  | Kind     |
+| ----------------------- | -------- |
+| `settleEntryUrl`        | function |
+| `resolveEntryUrl`       | function |
+| `EntryRouterOptions`    | type     |
+| `EntryUrlResolution`    | type     |
+| `EntryRedirect`         | type     |
+| `EntryLeaf`             | type     |
+| `SettleEntryUrlOptions` | type     |
+| `SettledEntryUrl`       | type     |
+
+Both functions return promises — see [step 4](#4-prove-the-entry-urls-settle).
+
+## See also
+
+Sibling packages are linked by full URL, not by `../`: this file ships in the
+published tarball, where a relative path to another package resolves to nothing.
+
+- [design-system](https://github.com/r0hitsharma/uikit/tree/main/packages/design-system)
+  for `useUrlSyncedTableStateAdapter` and the `DataTable` this package's adapter
+  feeds
+- [http-client-react](https://github.com/r0hitsharma/uikit/tree/main/packages/http-client-react)
+  for the TanStack Query layer that a future loader/query glue would have to
+  straddle (see [DESIGN.md](./DESIGN.md#loader-and-query-glue))

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { oneOfParam, type SearchOptionParam, type SearchTextParam, textParam, toSearchOption, toSearchText, } from './search-params.js';
+export { createUrlSyncedTableAdapter, type UrlSyncedTableAdapterOptions, type UrlSyncedTableNavigate, type UrlSyncedTableNavigateOptions, type UrlSyncedTableStateAdapter, } from './table-adapter.js';
+export { type CanonicalSearchOptions, createSearchParamStripper, createValidatedSearchRedirect, rendersSameSearch, type SearchParamStripperContext, type SearchRecord, type StringifySearch, type ValidatedSearchContext, type ValidatedSearchRedirectOptions, } from './validated-search.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { oneOfParam, textParam, toSearchOption, toSearchText, } from './search-params.js';
+export { createUrlSyncedTableAdapter, } from './table-adapter.js';
+export { createSearchParamStripper, createValidatedSearchRedirect, rendersSameSearch, } from './validated-search.js';

package/dist/search-params.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Collapses a raw URL search value to the text a param means, or `undefined`
+ * when it means nothing.
+ *
+ * ## Why a normalizer is needed at all
+ *
+ * `validateSearch` never sees the raw query text. `parseSearch` has already
+ * decoded it, and decoding coerces spellings, so a parser written against
+ * `string` meets four other shapes in production:
+ *
+ * | URL              | value reaching the parser |
+ * | ---------------- | ------------------------- |
+ * | `?rows=25`       | the number `25`           |
+ * | `?dense=true`    | the boolean `true`        |
+ * | `?q=` or `?q`    | the empty string `''`     |
+ * | `?q=a&q=b`       | the array `['a', 'b']`    |
+ *
+ * How much coercion depends on the grammar the router was built with, and both
+ * common choices coerce:
+ *
+ * - `parseSearchWith(JSON.parse)` — the router's **default**. It applies the qss
+ *   decode above and then `JSON.parse`s every value still a string, so `?v=1e5`
+ *   arrives as `100000`, `?v=null` as `null`, and `?v=-0` as `0`.
+ * - `parseSearchWith((value) => value)` — the identity parser, for apps whose
+ *   params are plain text. Stops after the qss decode, so those three stay
+ *   strings.
+ *
+ * A hand-written `parseSearch` is the decoder rather than a stage after it, so
+ * it can opt out entirely — but then it owns the whole grammar.
+ *
+ * ## What is and is not promised
+ *
+ * **Promised: idempotence.** Feeding this function's own output back through a
+ * render-and-redecode round trip returns that output unchanged, under either
+ * grammar above. That is the property the entry-time cleanup needs to terminate.
+ *
+ * **Not promised: byte-preserved URL text.** Under the default grammar `?v=1e5`
+ * canonicalizes to `100000` and `?v=-0` to `0`, because the value really was
+ * decoded to a number.
+ *
+ * That rewrite is the *grammar's*, not the cleanup's, and it costs no redirect:
+ * the router restringifies the decoded search whenever it builds a location, and
+ * its own mount-time commit is what puts the canonical form in the address bar.
+ * The cleanup's rewrites are the ones that show up as a redirect. Either way it
+ * is one rewrite and not a loop — the second pass is stable, and
+ * `settleEntryUrl` pins the settled form of both under both grammars.
+ */
+export declare function toSearchText(value: unknown): string | undefined;
+/**
+ * Narrows a raw URL value (or a raw control value) to a closed option set.
+ * Exported alongside the schema builder because the change handlers that write
+ * a param back need the same rule the schema applied when reading it — two
+ * spellings of "is this allowed" would be one drift away from a control that
+ * can set a value the URL then drops.
+ */
+export declare function toSearchOption<T extends string>(value: unknown, allowed: readonly T[]): T | undefined;
+/**
+ * Schema shape returned by {@link textParam}. Named so the built `.d.ts` states
+ * the param's output type instead of inlining zod's internal generics.
+ */
+export type SearchTextParam = z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+/**
+ * A free-text search param: trimmed, with empty and unusable values degrading
+ * to absent. Use for identifiers, query strings, and timestamps — anything
+ * whose value set is open.
+ *
+ * Total and idempotent by construction; see the contract note on this module's
+ * builders below.
+ */
+export declare function textParam(): SearchTextParam;
+/**
+ * Schema shape returned by {@link oneOfParam}, carrying the closed option set
+ * through to the inferred search type.
+ */
+export type SearchOptionParam<T extends string> = z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<T | undefined, unknown>>>;
+/**
+ * A closed-set param: one of `allowed`, or absent. Use for tabs, modes, sort
+ * directions, and flags whose spellings are fixed — a hand-edited or stale
+ * value degrades to absent rather than reaching a component that has no case
+ * for it.
+ *
+ * Pass `allowed` as `[...] as const` (or a `readonly` tuple) so the inferred
+ * search type is the literal union rather than `string`.
+ */
+export declare function oneOfParam<T extends string>(allowed: readonly T[]): SearchOptionParam<T>;

package/dist/search-params.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+/**
+ * Collapses a raw URL search value to the text a param means, or `undefined`
+ * when it means nothing.
+ *
+ * ## Why a normalizer is needed at all
+ *
+ * `validateSearch` never sees the raw query text. `parseSearch` has already
+ * decoded it, and decoding coerces spellings, so a parser written against
+ * `string` meets four other shapes in production:
+ *
+ * | URL              | value reaching the parser |
+ * | ---------------- | ------------------------- |
+ * | `?rows=25`       | the number `25`           |
+ * | `?dense=true`    | the boolean `true`        |
+ * | `?q=` or `?q`    | the empty string `''`     |
+ * | `?q=a&q=b`       | the array `['a', 'b']`    |
+ *
+ * How much coercion depends on the grammar the router was built with, and both
+ * common choices coerce:
+ *
+ * - `parseSearchWith(JSON.parse)` — the router's **default**. It applies the qss
+ *   decode above and then `JSON.parse`s every value still a string, so `?v=1e5`
+ *   arrives as `100000`, `?v=null` as `null`, and `?v=-0` as `0`.
+ * - `parseSearchWith((value) => value)` — the identity parser, for apps whose
+ *   params are plain text. Stops after the qss decode, so those three stay
+ *   strings.
+ *
+ * A hand-written `parseSearch` is the decoder rather than a stage after it, so
+ * it can opt out entirely — but then it owns the whole grammar.
+ *
+ * ## What is and is not promised
+ *
+ * **Promised: idempotence.** Feeding this function's own output back through a
+ * render-and-redecode round trip returns that output unchanged, under either
+ * grammar above. That is the property the entry-time cleanup needs to terminate.
+ *
+ * **Not promised: byte-preserved URL text.** Under the default grammar `?v=1e5`
+ * canonicalizes to `100000` and `?v=-0` to `0`, because the value really was
+ * decoded to a number.
+ *
+ * That rewrite is the *grammar's*, not the cleanup's, and it costs no redirect:
+ * the router restringifies the decoded search whenever it builds a location, and
+ * its own mount-time commit is what puts the canonical form in the address bar.
+ * The cleanup's rewrites are the ones that show up as a redirect. Either way it
+ * is one rewrite and not a loop — the second pass is stable, and
+ * `settleEntryUrl` pins the settled form of both under both grammars.
+ */
+export function toSearchText(value) {
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    // Arrays (a repeated key), objects, `null`, and absence all mean "no usable
+    // value", which the schemas below spell as `undefined`.
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Narrows a raw URL value (or a raw control value) to a closed option set.
+ * Exported alongside the schema builder because the change handlers that write
+ * a param back need the same rule the schema applied when reading it — two
+ * spellings of "is this allowed" would be one drift away from a control that
+ * can set a value the URL then drops.
+ */
+export function toSearchOption(value, allowed) {
+    const text = toSearchText(value);
+    if (text === undefined) {
+        return undefined;
+    }
+    // Widened rather than narrowed: `includes` on a `readonly T[]` would demand a
+    // `T` here, which is the very thing being decided. One cast on the way out.
+    return allowed.includes(text)
+        ? text
+        : undefined;
+}
+/**
+ * A free-text search param: trimmed, with empty and unusable values degrading
+ * to absent. Use for identifiers, query strings, and timestamps — anything
+ * whose value set is open.
+ *
+ * Total and idempotent by construction; see the contract note on this module's
+ * builders below.
+ */
+export function textParam() {
+    return z.optional(z.unknown().transform(toSearchText));
+}
+/**
+ * A closed-set param: one of `allowed`, or absent. Use for tabs, modes, sort
+ * directions, and flags whose spellings are fixed — a hand-edited or stale
+ * value degrades to absent rather than reaching a component that has no case
+ * for it.
+ *
+ * Pass `allowed` as `[...] as const` (or a `readonly` tuple) so the inferred
+ * search type is the literal union rather than `string`.
+ */
+export function oneOfParam(allowed) {
+    return z.optional(z.unknown().transform((value) => toSearchOption(value, allowed)));
+}
+/*
+ * ## Writing a param of your own
+ *
+ * The total-and-idempotent contract (see `toSearchText`) is what
+ * `createValidatedSearchRedirect` needs to terminate, so a custom param has to
+ * keep it. Three rules cover it:
+ *
+ *  1. Build on `toSearchText`, so the decoder's coercions are already absorbed.
+ *  2. Keep the transform a pure function of that text — no state, no clock, no
+ *     counter. A param that grows or varies per call cannot converge.
+ *  3. Return absent, or a value that renders to text this module maps back to
+ *     that same value. Notably `null` is *not* such a value: it is neither
+ *     dropped as absent nor stable across both grammars.
+ *
+ * `settleEntryUrl` (from the `/testing` subpath) is the executable check — point
+ * it at the real route tree and it fails on a param that does not converge.
+ */