basalt-ui 1.24.0 → 1.26.0

package/src/guard/types.ts

@@ -1,12 +1,12 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 25 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 27 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 25 theme-guard violation kinds. */
+/** The 27 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -33,6 +33,8 @@ export type GuardKind =
   | 'css-raw-surface'
   | 'inline-font-size'
   | 'hidden-inline-style'
+  | 'in-body-page-title'
+  | 'raw-selection-control'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/index.ts

@@ -14,6 +14,14 @@ export {
 } from './provider'
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
+export { CTL_THEME, CtlSlot } from './theme'
+export type { CtlSlotProps } from './theme'
+/**
+ * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
+ * COMPONENTS that project it (`ActionGroup`, `OverflowMenu`, `SyncButton`, and the filter family)
+ * live on `basalt-ui/controls` — only the types a `PageBar`/`BasaltShell` prop mentions are here.
+ */
+export type { BarAction, ActionGroupProps, GlobalAction } from './controls/actions'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
 export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion'
 export {
@@ -22,6 +30,7 @@ export {
   AppSidebar,
   SidebarSearch,
   type SidebarSearchConfig,
+  type SidebarSearchActions,
   SidebarAccount,
   MobileNav,
   type MobileNavProps,
@@ -31,11 +40,16 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  PageHeaderProvider,
-  PageActions,
-  PageActionsOutlet,
+  PageBar,
+  type PageBarProps,
   type SidebarSection,
   type SidebarItem,
+  type SidebarBlock,
+  type SidebarBlockItem,
+  type SidebarBlockTone,
+  type SidebarListBlock,
+  type SidebarProgressBlock,
+  type SidebarCustomBlock,
   type NavAnchor,
   type NavAnchorProps,
   type NavMobilePlacement,
@@ -72,14 +86,41 @@ export {
   type StandardSchemaV1,
 } from './register'
 
-// ── Persisted state + online hook (state.ts) ─────────────────────────────────────────────────────
+// ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
+// The `field.*` VALUE is deliberately not re-exported here — `basalt-ui/forms` already owns the
+// name `field` on its own barrel. Import it from `basalt-ui/router-tanstack` (beside
+// `createSearchStore`) or from `basalt-ui/state` (beside `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
-  useOnlineStatus,
   readPersistedValue,
+  createLocalStore,
+  type LocalStore,
+  type AnyField,
+  type BooleanField,
+  type EnumField,
+  type FieldHandle,
+  type FieldLane,
+  type FieldOption,
+  type FieldValue,
+  type MultiField,
+  type NumberField,
+  type RangeField,
+  type RangeParams,
+  type RangePresets,
+  type RangeValue,
+  type ResolvedLane,
+  type SearchValues,
+  type StoredValues,
+  type StringField,
 } from './state'
 
+// ── WidgetHeader (unified section/widget/card heading primitive, docs/CONTROLS-SPEC.md §2.2) ─────
+export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
+
+// ── Section (tier-2 heading composer over WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ───────────────
+export { Section, type SectionProps } from './section'
+
 // ── Dashboard composites (KPI atoms + settings building blocks) ──────────────────────────────────
 export {
   DeltaBadge,

package/src/nav/types.ts

@@ -40,6 +40,8 @@ export type SidebarItem = {
   /** Plain href — the no-router fallback, and the breadcrumb parent target. */
   href?: string
   active?: boolean
+  /** A parent on the path to the active row. NOT active itself — never carries `aria-current`. */
+  ancestor?: boolean
   disabled?: boolean
   onClick?: (e: MouseEvent) => void
   /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
@@ -70,6 +72,88 @@ export type SidebarSection = {
   mobile?: false | NavSectionMobile
 }
 
+/**
+ * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
+ * members are `VX.status` keys by construction. Declared here rather than imported from
+ * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
+ * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
+ * `@mantine/core` installed.
+ */
+export type SidebarBlockTone = 'good' | 'warn' | 'bad'
+
+/** One row inside a `kind: 'list'` block. Same router seam as `SidebarItem` — `Anchor`, then href. */
+export type SidebarBlockItem = {
+  key: string
+  label: string
+  /** Trailing muted text (a timestamp, a count, an owner). */
+  meta?: string
+  icon?: ReactNode
+  /** Renders a status dot in place of a missing `icon`; reads `--vx-status-*`, never a hex. */
+  tone?: SidebarBlockTone
+  Anchor?: NavAnchor
+  href?: string
+  onClick?: () => void
+}
+
+/**
+ * A list of non-destination rows under a micro-label — "Awaiting action", "Recents", a project
+ * list. `count` is the header badge (and what earns a rail dot); `max` shows the first N with a
+ * "Show more" toggle past it.
+ */
+export type SidebarListBlock = {
+  kind: 'list'
+  key: string
+  label: string
+  icon?: ReactNode
+  count?: number
+  /** Rows shown before the "Show more" toggle. Omit to show every row. */
+  max?: number
+  items: SidebarBlockItem[]
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+  collapsible?: boolean
+  /** Collapsed-rail projection. @default 'dot' when `count` is set, `'hidden'` otherwise */
+  rail?: 'dot' | 'hidden'
+  /** @default 'more' */
+  mobile?: 'more' | 'hidden'
+}
+
+/** A "Getting started 1 of 5" progress row. Pinned above the settings footer; never in the nav. */
+export type SidebarProgressBlock = {
+  kind: 'progress'
+  key: string
+  label: string
+  value: number
+  total: number
+  onClick?: () => void
+  /** @default 'bottom' — the only placement a progress row has. */
+  placement?: 'bottom'
+  /** Collapsed-rail projection: a ring on the settings row. @default 'ring' */
+  rail?: 'ring' | 'hidden'
+  /** @default 'hidden' */
+  mobile?: 'more' | 'hidden'
+}
+
+/**
+ * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
+ * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
+ * from mobile for the same reason that prop was.
+ */
+export type SidebarCustomBlock = {
+  kind: 'custom'
+  key: string
+  node: ReactNode
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+}
+
+/**
+ * A sidebar block — DECLARED DATA, never a `ReactNode` slot (law C13, `docs/CONTROLS-SPEC.md`
+ * §2.3), which is what lets basalt own the collapsed-rail badge and the mobile More-sheet
+ * projection instead of each consumer hand-rolling both.
+ */
+export type SidebarBlock = SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+
 export type MobileNavSurface = 'link' | 'menu' | 'sheet'
 
 /** One row inside a `menu`/`sheet` slot, grouped under its source section. */
@@ -108,8 +192,6 @@ export type MobileNavConfig = {
   menuMax?: number
   /** @default 'More' */
   moreLabel?: string
-  /** Extra content pinned to the bottom of the More surface. */
-  moreExtra?: ReactNode
   /** Scroll container for active-slot re-tap. @default document.scrollingElement */
   getScrollElement?: () => HTMLElement | null
 }

package/src/notifications/bell.tsx

@@ -1,6 +1,6 @@
 /**
  * NotificationBell — ActionIcon + Indicator showing the unread Inbox count, opens a
- * NotificationCenter in a Popover. Designed for the shell `globalActions` slot (ReactNode).
+ * NotificationCenter in a Popover. Designed for the shell `globalActions` slot (`GlobalAction[]`).
  *
  * The badge counts unread Inbox items (errors / warnings / actionable notifications you haven't
  * seen) — not every toast that fired. Opening the bell does NOT mark anything read; items are
@@ -11,7 +11,7 @@
  *
  * // In the shell's globalActions prop:
  * <BasaltShell
- *   globalActions={<NotificationBell />}
+ *   globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]}
  *   {...rest}
  * />
  */
@@ -33,7 +33,10 @@ export type NotificationBellProps = {
  * Bell icon button with an unread-Inbox indicator. Opens a NotificationCenter popover.
  *
  * @example
- * <BasaltShell globalActions={<NotificationBell />} {...rest} />
+ * <BasaltShell
+ *   globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]}
+ *   {...rest}
+ * />
  */
 export function NotificationBell({ label = 'Notifications' }: NotificationBellProps) {
   const [opened, { open, toggle, close }] = useDisclosure(false)

package/src/notifications/index.ts

@@ -20,7 +20,7 @@
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
  * // Shell bell (globalActions slot):
- * <BasaltShell globalActions={<NotificationBell />} ... />
+ * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
 
 // ── notify core ───────────────────────────────────────────────────────────────

package/src/router-tanstack/field.ts

@@ -0,0 +1,31 @@
+/**
+ * `field.*` — the field vocabulary `createSearchStore` takes, re-exported at the surface a consumer
+ * imports it from (`basalt-ui/router-tanstack`, beside the store factory).
+ *
+ * The builders and their codecs LIVE in `../state` on purpose: a field is declarative data with no
+ * router in it, and `createLocalStore` — the router-free lane, published on `basalt-ui/state` —
+ * has to build the same fields without pulling in `@tanstack/react-router`. One definition, two
+ * surfaces, no second description of the same param.
+ *
+ * Full field reference: the JSDoc on `field` itself, and `docs/CONTROLS-SPEC.md` §4.
+ */
+export { field } from '../state'
+export type {
+  AnyField,
+  BooleanField,
+  EnumField,
+  FieldHandle,
+  FieldLane,
+  FieldOption,
+  FieldValue,
+  MultiField,
+  NumberField,
+  RangeField,
+  RangeParams,
+  RangePresets,
+  RangeValue,
+  ResolvedLane,
+  SearchValues,
+  StoredValues,
+  StringField,
+} from '../state'

package/src/router-tanstack/index.ts

@@ -3,10 +3,32 @@
  * Optional peer: @tanstack/react-router.
  * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
  * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
- * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
- * the search-param stores — no Mantine, no JSX.
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs, plus
+ * `createSearchStore` + the `field.*` vocabulary (and the two deprecated enum-only wrappers it
+ * replaced) — no Mantine, no JSX.
  */
 
+export { createSearchStore, type CreateSearchStoreOptions, type SearchStore } from './search-store'
+export { field } from './field'
+export type {
+  AnyField,
+  BooleanField,
+  EnumField,
+  FieldHandle,
+  FieldLane,
+  FieldOption,
+  FieldValue,
+  MultiField,
+  NumberField,
+  RangeField,
+  RangeParams,
+  RangePresets,
+  RangeValue,
+  ResolvedLane,
+  SearchValues,
+  StoredValues,
+  StringField,
+} from './field'
 export {
   createSearchParamStore,
   type SearchParamStore,

package/src/router-tanstack/multi-search-param-store.test.ts

@@ -1,8 +1,26 @@
-import { describe, expect, test } from 'bun:test'
+/**
+ * The deprecated multi wrapper's contract, unchanged across the rewrite onto
+ * `createSearchStore` — plus the storage path two of these tests used to claim was unreachable.
+ *
+ * `bun test` runs under happy-dom (root `bunfig.toml` preload), so `localStorage` has always been
+ * REAL here: "no localStorage in this environment" was false, and it meant the fallback-to-storage
+ * half of `validateSearch` — the entire reason the store exists — was asserted only in the
+ * single-value store's tests (D12).
+ */
+import { beforeEach, describe, expect, test } from 'bun:test'
 import { createMultiSearchParamStore } from './multi-search-param-store'
 
 const VALUES = ['api', 'design', 'guide'] as const
 
+/** Writes the wrapper's single-value envelope — the layout it has used since 1.0.0. */
+function persist(key: string, value: readonly string[], version = 1): void {
+  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: version, value }))
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
 describe('createMultiSearchParamStore', () => {
   describe('validateSearch', () => {
     test('URL value wins when it decodes to a non-empty array', () => {
@@ -30,10 +48,17 @@ describe('createMultiSearchParamStore', () => {
       expect(a.tags).toEqual(['api', 'design'])
     })
 
-    test('a non-array URL value falls through to the fallback (no localStorage in this env)', () => {
+    test('a non-array URL value falls through to storage, then to the fallback', () => {
       const store = createMultiSearchParamStore({ key: 'tags-e', param: 'tags', values: VALUES })
       expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: [] })
       expect(store.validateSearch({})).toEqual({ tags: [] })
+
+      persist('tags-e', ['guide', 'api'])
+      // Storage is read, and normalized on the way out like any other source.
+      expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: ['api', 'guide'] })
+      expect(store.validateSearch({})).toEqual({ tags: ['api', 'guide'] })
+      // A valid URL array still wins over it.
+      expect(store.validateSearch({ tags: ['design'] })).toEqual({ tags: ['design'] })
     })
 
     test('an empty URL array falls through to the fallback', () => {
@@ -48,9 +73,52 @@ describe('createMultiSearchParamStore', () => {
   })
 
   describe('readStored', () => {
-    test('returns null when nothing is persisted (no localStorage in this test environment)', () => {
+    test('returns null when nothing is persisted', () => {
       const store = createMultiSearchParamStore({ key: 'tags-g', param: 'tags', values: VALUES })
       expect(store.readStored()).toBeNull()
     })
+
+    test('returns the normalized stored selection, and null for a stale envelope version', () => {
+      const store = createMultiSearchParamStore({ key: 'tags-h', param: 'tags', values: VALUES })
+      persist('tags-h', ['guide', 'nope', 'api'])
+      expect(store.readStored()).toEqual(['api', 'guide'])
+
+      const versioned = createMultiSearchParamStore({
+        key: 'tags-i',
+        param: 'tags',
+        values: VALUES,
+        version: 1,
+      })
+      persist('tags-i', ['api'], 2)
+      expect(versioned.readStored()).toBeNull()
+    })
+
+    test('a stored EMPTY selection reads back as empty — a cleared filter stays cleared', () => {
+      // `{ v: 1, value: [] }` is exactly what `useStore()`'s setter writes when a user clears every
+      // filter. The empty-array-means-absent rule is a URL rule; applying it to storage too would
+      // resurrect the fallback on upgrade, which is not what "byte-compatible" means.
+      const store = createMultiSearchParamStore({
+        key: 'tags-empty',
+        param: 'tags',
+        values: VALUES,
+        fallback: ['guide'],
+      })
+      persist('tags-empty', [])
+
+      expect(store.readStored()).toEqual([])
+      expect(store.validateSearch({})).toEqual({ tags: [] })
+      expect(store.linkSearch()).toEqual({ tags: [] })
+      // …while an empty URL array still falls through to storage, as it always has.
+      persist('tags-empty', ['api'])
+      expect(store.validateSearch({ tags: [] })).toEqual({ tags: ['api'] })
+    })
+
+    test('linkSearch carries the stored selection at CALL time', () => {
+      const store = createMultiSearchParamStore({ key: 'tags-j', param: 'tags', values: VALUES })
+      expect(store.linkSearch()).toEqual({ tags: [] })
+
+      persist('tags-j', ['design'])
+      expect(store.linkSearch()).toEqual({ tags: ['design'] })
+    })
   })
 })

package/src/router-tanstack/multi-search-param-store.ts

@@ -1,54 +1,34 @@
 /**
- * createMultiSearchParamStore — the multi-select sibling of `createSearchParamStore`, for search
- * params backed by an ANY-OF set (e.g. a tag filter) instead of a single value (e.g. a tab).
+ * @deprecated `createMultiSearchParamStore` is a thin wrapper over `createSearchStore`
+ * and is removed in 1.29.0. Replace it with `field.multi`:
  *
- * Same three-concern factory shape as `createSearchParamStore`:
- * 1. `validateSearch` — pass directly to `createFileRoute({ validateSearch })`.
- *    Falls back to localStorage when the URL param is absent or invalid, then to `fallback`.
- * 2. `useStore` — React hook: `const [values, persist] = store.useStore()`.
- *    Call `persist(next)` alongside `navigate` so the selection survives navigation.
- * 3. `readStored` — plain function for non-React contexts (tests, guards).
- * 4. `linkSearch` — the click-time `search:` thunk for a nav link, ready-made.
+ *     const store = createSearchStore({
+ *       key: 'article-tags',
+ *       fields: { tags: field.multi(['api', 'design', 'guide'], []) },
+ *     })
  *
- * Headless — no Mantine, no JSX. Same tier as `createSearchParamStore`.
+ * Two differences to know when you migrate:
  *
- * ## Encoding — array-native, not CSV
+ * - **An empty URL array is a VALUE in the new store**, not "absent". This wrapper keeps the old
+ *   rule (`?tags=[]` falls through to localStorage, then to `fallback`) so an existing consumer's
+ *   links behave identically; `field.multi` treats a cleared selection as a cleared selection.
+ * - `useStore` is localStorage-only. `store.field.tags.use()` reads the URL first (A8).
  *
- * TanStack Router's default search serialization is `stringifySearchWith(JSON.stringify,
- * JSON.parse)`, and its `stringifyValue` branches on `typeof val === 'object' && val !== null` —
- * an array is an object, so `{ tags: ['a', 'b'] }` serializes to `?tags=%5B%22a%22%2C%22b%22%5D`
- * and `parseSearchWith(JSON.parse)` reverses it losslessly. This store deals entirely in arrays
- * (what `validateSearch` returns is exactly what the router stringifies), so a CSV encoding is not
- * reachable from here — there is no string-building step to intercept. A consumer who wants
- * prettier URLs (e.g. `?tags=a,b`) configures router-global `parseSearch`/`stringifySearch` (see
- * TanStack Router's documented custom-search-param-serialization recipe); this store keeps working
- * untouched either way, because it hands the router an array, not an encoding.
+ * Encoding is unchanged and array-native: TanStack Router's default
+ * `stringifySearchWith(JSON.stringify, JSON.parse)` round-trips `{ tags: ['a', 'b'] }` losslessly,
+ * so there is no CSV step to intercept — a consumer wanting `?tags=a,b` configures router-global
+ * `parseSearch`/`stringifySearch` and this store keeps working untouched, because it hands the
+ * router an array rather than an encoding.
  *
- * ## Decoding — defensive and canonical
+ * Decoding is unchanged too: array-only input, allowlist-filtered, deduped, then re-sorted into
+ * `values` DECLARATION order — so `['api', 'design']` and `['design', 'api']` normalize to the same
+ * array, and one logical selection has one URL.
  *
- * Any value pulled from the URL or localStorage is normalized in this order:
- * 1. Accept only `Array.isArray` input — anything else decodes to empty.
- * 2. Keep only entries present in `opts.values` (drops tampered values and values dropped from the
- *    vocabulary since the URL/localStorage entry was written).
- * 3. Dedupe.
- * 4. Re-sort into `opts.values` DECLARATION order.
- *
- * Canonical ordering means `['api', 'design']` and `['design', 'api']` normalize to the SAME
- * array — one URL for one logical selection, so history entries and any loader cache keyed on the
- * search stay stable regardless of the order a user toggled filters in.
- *
- * @example
- * export const articleTags = createMultiSearchParamStore({
- *   key: 'article-tags', param: 'tags',
- *   values: ['api', 'design', 'guide'] as const,
- * })
- *
- * export const Route = createFileRoute('/content')({
- *   validateSearch: articleTags.validateSearch,
- * })
+ * The four returned members (`validateSearch`, `useStore`, `readStored`, `linkSearch`), their
+ * signatures and the single-value localStorage envelope are preserved byte-for-byte.
  */
-
-import { createPersistedState, readPersistedValue } from '../state'
+import { createPersistedState, field } from '../state'
+import { buildSearchStore } from './search-store'
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -73,7 +53,7 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
   validateSearch: (search: Record<string, unknown>) => { [K in P]: readonly T[] }
   /**
    * React hook: `const [current, persist] = store.useStore()`.
-   * Call `persist(next)` in your filter's `onChange` alongside `navigate()`.
+   * localStorage only — it does NOT read or write the URL.
    */
   useStore: () => readonly [readonly T[], (next: readonly T[]) => void]
   /** Plain read — for use outside React (tests, guards, fallback reads). */
@@ -84,54 +64,43 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
    * for why a module-scope literal silently defeats the store.
    *
    * No dev warning rides on this one, unlike the single-value store: an empty array in the URL is
-   * indistinguishable from an absent param here (`validateSearch` falls back to storage for both),
-   * so a link declaring `{ tags: [] }` restores correctly and there is no broken state to detect.
+   * indistinguishable from an absent param here, so a link declaring `{ tags: [] }` restores
+   * correctly and there is no broken state to detect.
    */
   linkSearch: () => { [K in P]: readonly T[] }
 }
 
 // ── Implementation ─────────────────────────────────────────────────────────
 
+/** @deprecated Use `createSearchStore` + `field.multi`. Removed in 1.29.0. */
 export function createMultiSearchParamStore<const T extends string, const P extends string>(
   opts: MultiSearchParamStoreOptions<T, P>,
 ): MultiSearchParamStore<T, P> {
   const version = opts.version ?? 1
   const fallback = opts.fallback ?? []
-  const allowed = new Set<string>(opts.values)
-
-  /** Array-only, allowlist-filtered, deduped, canonically re-sorted into `opts.values` order. */
-  const normalize = (raw: unknown): readonly T[] => {
-    if (!Array.isArray(raw)) return []
-    const present = new Set<T>()
-    for (const entry of raw) {
-      if (typeof entry === 'string' && allowed.has(entry)) present.add(entry as T)
-    }
-    return opts.values.filter((value) => present.has(value))
-  }
-
-  const readStored = (): readonly T[] | null => {
-    const raw = readPersistedValue(opts.key, version)
-    if (!Array.isArray(raw)) return null
-    return normalize(raw)
-  }
-
-  const linkSearch = (): { [K in P]: readonly T[] } => {
-    return { [opts.param]: readStored() ?? fallback } as { [K in P]: readonly T[] }
-  }
-
-  const validateSearch = (search: Record<string, unknown>): { [K in P]: readonly T[] } => {
-    const fromUrl = normalize(search[opts.param])
-    if (fromUrl.length > 0) {
-      return { [opts.param]: fromUrl } as { [K in P]: readonly T[] }
-    }
-    return { [opts.param]: readStored() ?? fallback } as { [K in P]: readonly T[] }
-  }
+  const store = buildSearchStore({
+    key: opts.key,
+    version,
+    fields: { [opts.param]: field.multi(opts.values, fallback) },
+    legacyValueField: opts.param,
+  })
 
-  const useStore = createPersistedState<readonly T[]>({
+  const persisted = createPersistedState<readonly T[]>({
     key: opts.key,
     version,
     initial: fallback,
   })
+  // A reader, like the single-value wrapper's — see the note there.
+  const useStore = (): readonly [readonly T[], (next: readonly T[]) => void] => {
+    store.markReaderWired()
+    return persisted()
+  }
 
-  return { validateSearch, useStore, readStored, linkSearch }
+  return {
+    validateSearch: (search) => store.validateSearch(search) as { [K in P]: readonly T[] },
+    useStore,
+    readStored: () =>
+      (store.readStored() as Record<string, readonly T[] | undefined>)[opts.param] ?? null,
+    linkSearch: () => store.linkSearch() as { [K in P]: readonly T[] },
+  }
 }