@quazardous/qdadm 2.19.0 → 2.20.0

package/src/composables/useListPage.types.ts

@@ -3,6 +3,7 @@
  *
  * Extracted from useListPage.ts for maintainability.
  */
+import type { RouteStatePersister } from '../routeState'
 import type { Ref, ComputedRef } from 'vue'
 import type { Router } from 'vue-router'
 import type { FilterQuery } from '../query/FilterQuery'
@@ -76,9 +77,45 @@ export interface ColumnConfig {
 /**
  * Filter configuration
  */
-export interface FilterConfig {
-  name: string
-  type?: 'select' | 'multiselect' | 'date' | 'checkbox' | 'dropdown' | 'autocomplete'
+/**
+ * The filter controls qdadm knows how to render.
+ *
+ * Exported as a VALUE, not only a type, so a consumer's own guard can read
+ * this list instead of copying it — a copy goes stale the day a type is
+ * added and starts rejecting correct code.
+ */
+export const FILTER_TYPES = [
+  'select',
+  'multiselect',
+  'date',
+  'checkbox',
+  'dropdown',
+  'autocomplete',
+] as const
+
+export type FilterType = (typeof FILTER_TYPES)[number]
+
+/**
+ * Everything a filter can be given EXCEPT its name (#2147).
+ *
+ * Split out rather than written as `Omit<FilterConfig, 'name'>`, and the
+ * reason is not style. `FilterConfig` carries an index signature, so
+ * `keyof` includes `string`; `Exclude<string, 'name'>` is still `string`, and
+ * the `Omit` therefore collapsed to a bare `{ [x: string]: unknown }` —
+ * ERASING every declared property.
+ *
+ * `addFilter` took that type, so **no filter option was checked at all**:
+ * not `type`, not `optionLabel`, not `local_filter`. A consumer declared
+ * `type: 'text'`, TypeScript accepted it, and the filter rendered as an empty
+ * dropdown saying "No available options". Nothing was wrong at any single
+ * step, which is why it survived.
+ *
+ * Declaring the properties here and having `FilterConfig` extend it keeps the
+ * index signature — apps do stash their own keys — while the declared ones
+ * are checked again.
+ */
+export interface FilterOptions {
+  type?: FilterType
   placeholder?: string
   options?: Array<{ label: string; value: unknown }>
   default?: unknown
@@ -101,6 +138,10 @@ export interface FilterConfig {
   [key: string]: unknown
 }
 
+export interface FilterConfig extends FilterOptions {
+  name: string
+}
+
 /**
  * Row action configuration
  */
@@ -229,8 +270,27 @@ export interface UseListPageOptions<T = unknown> {
   persistFilters?: boolean
   /** Persist the active sort per entity (session storage), restored on init (#1218). Default true. */
   persistSort?: boolean
-  /** Sync filters to URL query params (default: true) */
+  /**
+   * WRITE filters, search and the page to the URL query (default: true).
+   *
+   * Writing only. `false` has never stopped the query string being read, so
+   * a deep link someone typed by hand still restores the list — say
+   * `routeState` if you want the state kept somewhere else entirely.
+   */
   syncUrlParams?: boolean
+  /**
+   * Where this list's state is remembered (#2146): a slug the framework
+   * knows (`'url'`, …), or your own persister. Defaults to the URL.
+   *
+   * Setting it is a deliberate choice of medium, so it answers
+   * `syncUrlParams` rather than obeying it: a list with `routeState` set
+   * reads and writes that medium whatever the URL flag says.
+   *
+   * An unknown slug throws rather than falling back to the URL — a list
+   * quietly persisting somewhere other than where you asked is worse than
+   * one that will not start (ADR 0011).
+   */
+  routeState?: string | RouteStatePersister
   /** Filter mode: 'auto' | 'manager' | 'local' */
   filterMode?: 'auto' | 'manager' | 'local'
   /** Auto-filter threshold for 'auto' mode */
@@ -270,6 +330,15 @@ export interface ListPageProps {
   lazy: boolean
   totalRecords: number
   rows: number
+  /**
+   * Row offset of the current page — what POSITIONS the paginator (#2145).
+   *
+   * In lazy mode the table renders exactly the rows it is handed and has no
+   * way to know which page they are; `first` is the only thing that tells it.
+   * Without it, a restored page 2 showed page 2's rows under a paginator
+   * highlighting 1.
+   */
+  first: number
   rowsPerPageOptions: number[]
   sortField: string | null
   sortOrder: number
@@ -382,7 +451,7 @@ export interface UseListPageReturn<T = unknown> {
   filterValues: Ref<Record<string, unknown>>
   filteredItems: ComputedRef<T[]>
   fromCache: Ref<boolean>
-  addFilter: (name: string, config: Omit<FilterConfig, 'name'>) => void
+  addFilter: (name: string, config: FilterOptions) => void
   removeFilter: (name: string) => void
   setFilterValue: (name: string, value: unknown) => void
   updateFilters: (values: Record<string, unknown>) => void

package/src/composables/useListPage.utils.ts

@@ -40,6 +40,35 @@ export function persistPageSize(size: number): void {
   setCookie(COOKIE_NAME, size, COOKIE_EXPIRY_DAYS)
 }
 
+/**
+ * Settle the rows-per-page a list opens on (#2146).
+ *
+ * The seam owns this now, so the stored value arrives from whichever medium
+ * the app chose. The LEGACY bare-number cookie is read only when the seam has
+ * nothing — an existing user's choice must survive the move, or a comfort
+ * setting they picked once quietly resets on upgrade.
+ *
+ * Anything outside {@link PAGE_SIZE_OPTIONS} falls back to the default: the
+ * value reaches us from a cookie or a query string that anyone can edit, and
+ * a row count the paginator cannot offer would leave its dropdown showing a
+ * blank.
+ */
+export function restorePageSize(stored: unknown, defaultSize: number): number {
+  const fromSeam = Number(stored)
+  if (PAGE_SIZE_OPTIONS.includes(fromSeam)) return fromSeam
+  return getSavedPageSize(defaultSize)
+}
+
+/**
+ * Drop the pre-seam cookie once its value has been carried over.
+ *
+ * Left in place it would outlive the setting it stands for by a year, and
+ * shadow the seam on any machine where the new store was cleared.
+ */
+export function retireLegacyPageSizeCookie(): void {
+  setCookie(COOKIE_NAME, '', -1)
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Default label formatter (snake_case → Title Case)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -129,6 +158,35 @@ export function clearSessionSort(key: string): void {
   }
 }
 
+/**
+ * Settle the sort a list opens on (#2146).
+ *
+ * The seam owns this now. The medium has not changed — the default
+ * composition routes `sort` back to `sessionStorage`, deliberately, so that
+ * moving it behind an interface changes nothing anyone can observe. Only the
+ * KEY changed, from `qdadm_sort_offers` to `qdadm:offers:sort`.
+ *
+ * Which is why the legacy entry is still read when the seam has nothing: a
+ * sort somebody set five minutes ago must not vanish because the framework
+ * was upgraded under them.
+ */
+export function restoreSort(
+  stored: { sort?: unknown; sortOrder?: unknown } | null,
+  legacyKey: string,
+  defaults: SessionSort
+): SessionSort {
+  const field = stored?.sort
+  const order = Number(stored?.sortOrder)
+  if (typeof field === 'string' && field && (order === 1 || order === -1)) {
+    return { field, order }
+  }
+
+  const legacy = getSessionSort(legacyKey)
+  if (legacy) return legacy
+
+  return defaults
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Smart filter discovery
 // ─────────────────────────────────────────────────────────────────────────────

package/src/entity/EntityManager.interface.ts

@@ -27,6 +27,7 @@
 import type { EntityBadge } from './EntityManager.types'
 import type { SignalBus } from '../kernel/SignalBus'
 import type { EntityAuthAdapter } from './auth/EntityAuthAdapter'
+import type { RouteStatePersister } from '../routeState'
 
 // ─── Base ────────────────────────────────────────────────────────────────────
 
@@ -84,6 +85,16 @@ export interface EntityManagerRead<T = unknown> extends EntityManagerBase<T>, En
   getFieldConfig: (name: string) => unknown | null
   /** Config-carrying property: always present on the class, VALUE nullable */
   localFilterThreshold?: number | null
+  /**
+   * Where lists of this entity remember their state (#2146): a slug the
+   * framework knows, or a persister instance.
+   *
+   * A property of the ENTITY, so every screen showing it agrees — a list of
+   * audit rows nobody links to can say `local_storage` once here rather than
+   * on each of the four pages that render it. A list's own `routeState`
+   * still wins; the kernel default applies when neither says anything.
+   */
+  routeState?: string | RouteStatePersister
 }
 
 // ─── CRUD ────────────────────────────────────────────────────────────────────

package/src/entity/EntityManager.ts

@@ -51,6 +51,7 @@ export type {
 } from './EntityManager.types'
 
 // Import concrete types needed in method signatures
+import type { RouteStatePersister } from '../routeState'
 import type {
   RoutingContext,
   PresaveContext,
@@ -88,6 +89,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _fields: Record<string, FieldConfig>
 
   localFilterThreshold: number | null
+  /** Where lists of this entity remember their state (#2146); null = inherit. */
+  routeState: string | RouteStatePersister | null
   /** Default null placement for local sorts (#1222); field-level nullSort wins. */
   nullSort?: NullSortMode
   protected _cacheTtlMs: number | null
@@ -163,6 +166,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       badges = null,
       fields = {},
       localFilterThreshold = null,
+      routeState = null,
       nullSort,
       cacheTtlMs = null,
       asymmetric = false,
@@ -196,6 +200,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._fields = fields
 
     this.localFilterThreshold = localFilterThreshold
+    this.routeState = routeState
     this.nullSort = nullSort
     this._cacheTtlMs = cacheTtlMs
     this._asymmetric = asymmetric

package/src/entity/EntityManager.types.ts

@@ -16,6 +16,7 @@ import type { HookRegistry } from '../hooks/HookRegistry'
 
 // Circular type import — safe because `import type` is erased at runtime
 import type { EntityManager } from './EntityManager'
+import type { RouteStatePersister } from '../routeState'
 
 // ============ INTERNAL TYPES ============
 
@@ -235,6 +236,16 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   badges?: (entity: T) => EntityBadge[]
   fields?: Record<string, FieldConfig>
   localFilterThreshold?: number | null
+  /**
+   * Where lists of this entity remember their state (#2146): a slug the
+   * framework knows, or a persister instance.
+   *
+   * A property of the ENTITY, so every screen showing it agrees — a list of
+   * audit rows nobody links to can say `local_storage` once here rather than
+   * on each of the four pages that render it. A list's own `routeState`
+   * still wins; the kernel default applies when neither says anything.
+   */
+  routeState?: string | RouteStatePersister
   /** Default null placement for local sorts: 'first' | 'last' | 'low' | 'high' (default 'last', #1222). Field-level nullSort wins. */
   nullSort?: NullSortMode
   /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */

package/src/entity/storage/ApiStorage.ts

@@ -151,7 +151,7 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   }
 
   async list(params: ListParams = {}, context: RoutingContext | null = null): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order, search, filters = {} } = params
 
     // `paramMapping` covers the WHOLE outgoing query, pagination included
     // (#2113). It used to be applied to the filters only, so `status` could
@@ -160,9 +160,23 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     // storage for that alone. The names qdadm uses internally are its own
     // business; what goes on the wire is the backend's.
     //
+    // `search` goes out too (#2147). It is part of `ListParams` and always
+    // has been, but this method never read it — a user typed in the search
+    // box, the list rebuilt its query, and the term was dropped here without
+    // a word. The rows came back unfiltered and nothing anywhere said why,
+    // which is the silent no-op ADR 0011 exists to forbid.
+    //
+    // It travels under whatever name your backend uses, like every other key:
+    // `paramMapping: { search: 'q' }`.
+    //
+    // `searchFields` deliberately stays behind. It says which fields the
+    // FRONT should look at when filtering a cached page locally; a backend
+    // that searches knows its own columns, and shipping an array parameter
+    // nobody asked for would be a new surprise in place of the old one.
+    //
     // Filters keep their precedence over the pagination keys, exactly as
     // before: a filter named `page` still wins, for better or worse.
-    const outgoing = { page, page_size, sort_by, sort_order, ...filters }
+    const outgoing = { page, page_size, sort_by, sort_order, search, ...filters }
 
     const response = await this.client.get<Record<string, unknown>>(this.endpoint, {
       params: this._applyParamMapping(outgoing),

package/src/entity/storage/LocalStorage.ts

@@ -67,7 +67,7 @@ export class LocalStorage<T extends EntityRecord = EntityRecord> extends IStorag
     items = filterItems(items, filters, { stringMatch: 'exact' })
 
     // Apply search (shared pipeline, #1192)
-    items = searchItems(items, search as string | undefined)
+    items = searchItems(items, search)
 
     const total = items.length
 

package/src/entity/storage/MemoryStorage.ts

@@ -1,7 +1,7 @@
 import { IStorage } from './IStorage'
 import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
 import { StorageError } from './errors'
-import { sortItems, filterItems, paginate, defaultGenerateId } from '../../query/clientFilter'
+import { sortItems, filterItems, paginate, defaultGenerateId, searchItems } from '../../query/clientFilter'
 
 /**
  * MemoryStorage options
@@ -61,10 +61,15 @@ export class MemoryStorage<T extends EntityRecord = EntityRecord> extends IStora
   }
 
   async list(params: ListParams = {}): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
     let items = this._getAll()
 
+    // Apply the search term (#2147). `searchItems` has existed since #1192
+    // and LocalStorage and MockApiStorage both called it; this one never did,
+    // so a search box over a MemoryStorage entity typed into the void.
+    items = searchItems(items, search)
+
     // Apply filters (shared pipeline, #1192 — legacy substring semantics)
     items = filterItems(items, filters, { stringMatch: 'includes' })
 

package/src/entity/storage/MockApiStorage.ts

@@ -151,7 +151,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
     }
 
     // Apply search (shared pipeline, #1192)
-    items = searchItems(items, search as string | undefined)
+    items = searchItems(items, search)
 
     const total = items.length
 

package/src/entity/storage/SdkStorage.ts

@@ -1,6 +1,6 @@
 import { IStorage } from './IStorage'
 import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
-import { sortItems, filterItems, paginate } from '../../query/clientFilter'
+import { sortItems, filterItems, paginate, searchItems } from '../../query/clientFilter'
 
 /**
  * SDK method result with data property
@@ -275,9 +275,13 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   }
 
   async list(params: ListParams = {}): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
-    const queryParams = { query: { page, page_size, sort_by, sort_order, ...filters } }
+    // `search` goes to the SDK with everything else (#2147). It was dropped
+    // here, so a search box over an SDK-backed entity typed into the void:
+    // the call went out without the term and the rows came back unfiltered,
+    // with nothing anywhere saying why.
+    const queryParams = { query: { page, page_size, sort_by, sort_order, search, ...filters } }
     const data = (await this._execute('list', queryParams)) as ListResult<T>
 
     let { items, total } = data
@@ -292,8 +296,13 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
 
       // Shared pipeline (#1192) — original order preserved: sort, then
       // filter (substring semantics), then paginate.
+      //
+      // The search is applied here TOO, not only sent (#2147). An SDK that
+      // ignores the term would otherwise hand back the whole collection and
+      // this branch would paginate it as if it had been searched.
       items = sortItems([...items], sort_by, sort_order)
       items = filterItems(items, filters, { stringMatch: 'includes' })
+      items = searchItems(items, search)
       total = items.length
       items = paginate(items, page, page_size)
     }

package/src/index.ts

@@ -237,10 +237,13 @@ export * from './composables/useJsonSyntax'
 export {
   useListPage,
   PAGE_SIZE_OPTIONS,
+  FILTER_TYPES,
   type UseListPageOptions,
   type UseListPageReturn,
   type ColumnConfig,
   type FilterConfig,
+  type FilterOptions,
+  type FilterType,
   type ActionConfig as ListActionConfig,
   type ResolvedAction,
   type HeaderActionConfig,
@@ -322,6 +325,22 @@ export {
   type LayoutMeta,
 } from './composables/useLayoutResolver'
 export { useSSEBridge, type UseSSEBridgeReturn } from './composables/useSSEBridge'
+
+// Route-state persistence (#2146) — where a route remembers what it shows.
+export {
+  UrlPersister,
+  isRouteStatePersister,
+  resolveRouteStatePersister,
+  createRouteStatePersisterFactory,
+  type RouteStatePersister,
+  type RouteStateScope,
+  type RouteStatePersisterSpec,
+  type RouteStatePersisterFactory,
+  type UrlPersisterOptions,
+  dottedKeyLocator,
+  namespacedKeyLocator,
+  type RouteStateKeyLocator,
+} from './routeState'
 export {
   useDeferred,
   useDeferredValue,

package/src/kernel/Kernel.registries.ts

@@ -361,8 +361,8 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     'features', 'hashMode', 'homeRoute', 'i18n', 'layouts', 'managerRegistry',
     'managerResolver', 'managers', 'moduleDefs', 'modules', 'modulesOptions',
     'notifications', 'onAuthExpired', 'pages', 'parentParamMode', 'primevue',
-    'root', 'routeParamResolver', 'routePrefix', 'sectionOrder', 'security',
-    'sse', 'storageResolver', 'toast', 'warmup',
+    'root', 'routeParamResolver', 'routePrefix', 'routeState', 'sectionOrder',
+    'security', 'sse', 'storageResolver', 'toast', 'warmup',
   ])
 
   proto._validateKernelOptions = function (this: Self): void {

package/src/kernel/Kernel.types.ts

@@ -12,6 +12,7 @@ import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
 import type { I18nOptions } from '../i18n/types'
 import type { ApiClientSource } from '../api/apiClient'
+import type { RouteStatePersister } from '../routeState'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -218,6 +219,21 @@ export interface KernelOptions {
   defaultEntityCacheTtlMs?: number
   eventRouter?: RoutesConfig
   sse?: SSEConfig
+  /**
+   * Where screens remember their route state by default (#2146): a slug the
+   * framework knows (`'url'`, `'local_storage'`, `'cookie'`, `'memory'`,
+   * `'none'`), or a persister instance.
+   *
+   * The app-wide floor. An entity overrides it for every screen showing that
+   * entity; a single list overrides it for itself. Unset means `'url'`, which
+   * is the only medium where what you are looking at is also what you can
+   * send someone.
+   *
+   * An unknown slug throws at list construction rather than falling back —
+   * a persistence choice that quietly does something else is the failure
+   * ADR 0011 forbids.
+   */
+  routeState?: string | RouteStatePersister
   debugBar?: DebugBarConfig
   notifications?: NotificationsConfig
   toast?: Record<string, unknown>

package/src/kernel/Kernel.vue.ts

@@ -323,6 +323,9 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     }
 
     app.provide('qdadmHooks', this.hookRegistry)
+    // The app-wide route-state default (#2146). Provided even when unset, so
+    // a list can tell "nobody chose" from "somebody chose and it was null".
+    app.provide('qdadmRouteState', this.options.routeState ?? null)
     app.provide('qdadmDeferred', this.deferred)
     app.provide('qdadmLayoutComponents', this.layoutComponents)
     // Surface PrimeVue presence so host-rendered <QdadmRoot /> can

package/src/plugin.ts

@@ -107,7 +107,7 @@ export interface QdadmPlugin {
 export function createQdadm(options: QdadmOptions): QdadmPlugin {
   return {
     install(app: App) {
-      // Validation des contrats requis
+      // The contracts this plugin cannot run without.
       if (!options.entityFactory && !options.orchestrator && !options.managers) {
         throw new Error('[qdadm] entityFactory, orchestrator, or managers required')
       }

package/src/query/clientFilter.ts

@@ -103,9 +103,20 @@ export function filterItems<T>(
 }
 
 /** Substring match on every string field (the adapters' full-text search). */
-export function searchItems<T>(items: T[], search?: string | null): T[] {
-  if (!search || typeof search !== 'string' || !search.trim()) return items
-  const query = search.toLowerCase().trim()
+export function searchItems<T>(items: T[], search?: unknown): T[] {
+  // A NUMBER is a search term too (#2147). This used to require a string and
+  // return the list untouched for anything else — so searching an order id
+  // that had been through a numeric round trip filtered nothing, silently,
+  // which is the failure ADR 0011 forbids. Objects and booleans are still
+  // ignored: there is no sensible text for them.
+  const term =
+    typeof search === 'string'
+      ? search
+      : typeof search === 'number' || typeof search === 'bigint'
+        ? String(search)
+        : ''
+  if (!term.trim()) return items
+  const query = term.toLowerCase().trim()
   return items.filter((item) => {
     for (const value of Object.values(item as Record<string, unknown>)) {
       if (typeof value === 'string' && value.toLowerCase().includes(query)) {

package/src/routeState/CompositePersister.ts

@@ -0,0 +1,144 @@
+/**
+ * One state, several media (#2146).
+ *
+ * The seam's signature was chosen so composition would be expressible without
+ * changing it, and this is the case that needed it: qdadm's own default.
+ * Filters, search and the page belong in a link; rows-per-page does not — it
+ * is a comfort setting somebody chose once, and putting it in the URL would
+ * mean a link imposing the sender's row count on the reader.
+ *
+ * So the default routes by key: everything to the URL, `pageSize` to the
+ * cookie it has always lived in.
+ *
+ * ```js
+ * new CompositePersister({
+ *   fallback: new UrlPersister({ router, route }),
+ *   keys: { pageSize: { persister: new CookiePersister(), scope: 'app' } },
+ * })
+ * ```
+ *
+ * A ROUTED KEY MAY PIN ITS OWN SCOPE. `pageSize` is remembered once for the
+ * whole app rather than per list — that is what the year-long
+ * `qdadm_pageSize` cookie already did, and expressing it here makes it a
+ * visible decision instead of an accident of where the code happened to live.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export interface RoutedKey {
+  persister: RouteStatePersister
+  /**
+   * Remember this key under a fixed scope instead of the caller's.
+   *
+   * For state that is one setting across the whole app rather than one per
+   * screen. Leave it out and the key follows the scope like everything else.
+   */
+  scope?: string
+}
+
+export interface CompositePersisterOptions {
+  /** Where anything unrouted goes. */
+  fallback: RouteStatePersister
+  /** Keys that live somewhere else. */
+  keys?: Record<string, RoutedKey | RouteStatePersister>
+}
+
+export class CompositePersister implements RouteStatePersister {
+  readonly name: string
+
+  private readonly _fallback: RouteStatePersister
+  private readonly _keys: Map<string, RoutedKey>
+
+  constructor(options: CompositePersisterOptions) {
+    this._fallback = options.fallback
+    this._keys = new Map(
+      Object.entries(options.keys ?? {}).map(([key, routed]) => [
+        key,
+        'persister' in routed ? routed : { persister: routed },
+      ])
+    )
+
+    const media = new Set([
+      this._fallback.name,
+      ...[...this._keys.values()].map((routed) => routed.persister.name),
+    ])
+    this.name = `composite(${[...media].join('+')})`
+  }
+
+  /**
+   * The fallback's state, with each routed key overlaid from its own medium.
+   *
+   * Order matters: a routed key wins even if the fallback happens to hold one
+   * under the same name — a stale `?pageSize=50` left in somebody's URL must
+   * not beat the cookie that owns the setting.
+   */
+  read(scope: string): Record<string, unknown> | null {
+    const base = this._fallback.read(scope)
+    const state: Record<string, unknown> = base ? { ...base } : {}
+    let found = base !== null
+
+    // Read each medium once, however many keys it owns.
+    for (const [medium, keys] of this._byMedium()) {
+      const stored = medium.persister.read(medium.scope ?? scope)
+      if (!stored) continue
+      for (const key of keys) {
+        if (stored[key] === undefined) continue
+        found = true
+        state[key] = stored[key]
+      }
+    }
+
+    return found ? state : null
+  }
+
+  /**
+   * Split the state by owner and write each medium once.
+   *
+   * A routed key ABSENT from `state` is still passed on as absent, so the
+   * empty-means-removed rule reaches the medium that owns it — otherwise
+   * clearing a filter would leave it behind in whichever store it lived in.
+   */
+  write(scope: string, state: Record<string, unknown>): void {
+    const forFallback: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (this._keys.has(key)) continue
+      forFallback[key] = value
+    }
+    this._fallback.write(scope, forFallback)
+
+    for (const [medium, keys] of this._byMedium()) {
+      const slice: Record<string, unknown> = {}
+      for (const key of keys) slice[key] = state[key]
+      medium.persister.write(medium.scope ?? scope, slice)
+    }
+  }
+
+  /**
+   * Clear the fallback, and any routed key that follows the caller's scope.
+   *
+   * A key PINNED to its own scope is deliberately left alone: `pageSize` is
+   * an app-wide setting somebody chose, and "clear this list's filters" is
+   * not a request to reset it. Clearing it here would make one list's clear
+   * button change every other list's row count.
+   */
+  clear(scope: string): void {
+    this._fallback.clear(scope)
+    for (const [medium, keys] of this._byMedium()) {
+      if (medium.scope !== undefined) continue
+      const slice: Record<string, unknown> = {}
+      for (const key of keys) slice[key] = null
+      medium.persister.write(scope, slice)
+    }
+  }
+
+  /** Group routed keys by the (persister, scope) pair that owns them. */
+  private _byMedium(): Map<RoutedKey, string[]> {
+    const grouped = new Map<string, { medium: RoutedKey; keys: string[] }>()
+    for (const [key, routed] of this._keys) {
+      const id = `${routed.persister.name} ${routed.scope ?? ''}`
+      const existing = grouped.get(id)
+      if (existing) existing.keys.push(key)
+      else grouped.set(id, { medium: routed, keys: [key] })
+    }
+    return new Map([...grouped.values()].map(({ medium, keys }) => [medium, keys]))
+  }
+}