basalt-ui 1.28.0 → 1.29.1

package/src/shell/app-sidebar.tsx

@@ -37,7 +37,7 @@ import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import type { BrandConfig, SettingsMenuItem } from './index'
-import type { SidebarBlock, SidebarItem, SidebarSection } from '../nav/types'
+import type { SidebarBlock, SidebarItem, SidebarSection } from './nav-types'
 import { NavCountBadge } from './nav-count-badge'
 import { SidebarAccount } from './app-sidebar-account'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -149,6 +149,27 @@ function IconGear() {
   )
 }
 
+/** The `SettingsMenuItem.active` glyph — no icon package, so a plain inline mark like `IconGear`
+ * above. Shared shape with `app-mobile-nav.tsx`'s own copy (that module's More sheet is a
+ * different render tree and basalt ships no icon dependency to import between them). */
+function IconCheck() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M5 12l5 5l10 -10" />
+    </svg>
+  )
+}
+
 const HOVER_OPEN_DELAY = 150
 const HOVER_CLOSE_DELAY = 200
 
@@ -465,6 +486,7 @@ export function AppSidebar(props: AppSidebarProps) {
             className={classes.footerBtn}
             onClick={entry.onClick}
             aria-label={entry.label}
+            aria-current={entry.active ? 'true' : undefined}
           >
             {/* A FIXED slot, so rows align on one icon column whether or not each ships an icon —
                 and the gear fallback is functional, not decorative: in the collapsed rail the label
@@ -477,6 +499,7 @@ export function AppSidebar(props: AppSidebarProps) {
             </Text>
             {/* The rail ring rides the FIRST row only — one progress block is one mark. */}
             {index === 0 ? ringMark : null}
+            {entry.active ? <IconCheck /> : null}
           </UnstyledButton>
         ))}
         {versionLabel !== undefined && (
@@ -499,7 +522,13 @@ export function AppSidebar(props: AppSidebarProps) {
           </Menu.Target>
           <Menu.Dropdown>
             {settingsItems.map((entry) => (
-              <Menu.Item key={entry.key} leftSection={entry.icon} onClick={entry.onClick}>
+              <Menu.Item
+                key={entry.key}
+                leftSection={entry.icon}
+                rightSection={entry.active ? <IconCheck /> : undefined}
+                onClick={entry.onClick}
+                aria-current={entry.active ? 'true' : undefined}
+              >
                 {entry.label}
               </Menu.Item>
             ))}

package/src/shell/index.tsx

@@ -18,8 +18,9 @@
  * `createPersistedState` (`../state`) keyed by `storageKey` — see `collapseStore`.
  */
 import { AppShell, Box } from '@mantine/core'
-import { Fragment, useMemo } from 'react'
+import { Fragment, useCallback, useEffect, useMemo } from 'react'
 import type { MouseEvent, ReactNode } from 'react'
+import { registerSidebarToggle } from '../commands/shell-bridge'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
@@ -40,7 +41,7 @@ import type {
   SidebarBlock,
   SidebarItem,
   SidebarSection,
-} from '../nav/types'
+} from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedState } from '../state'
 import brandClasses from './app-brand.module.css'
@@ -78,10 +79,12 @@ export {
 export { AppBreadcrumbs, type AppBreadcrumbsProps } from './app-breadcrumbs'
 export { PageBar, type PageBarProps, type PageBarSlot } from './page-bar'
 export { PageAside, type PageAsideProps, type PageAsideSlot } from './page-aside'
+export { useBreakpoint, type BreakpointName } from './use-breakpoint'
+export { PageTitle, type PageTitleProps, type PageTitleSlot } from './page-title'
 
 /**
- * The shared nav vocabulary lives in `src/nav/types.ts` so the headless router bridge can `import
- * type` it without reaching into the Mantine layer. Re-exported here so `SidebarItem` /
+ * The shared nav vocabulary lives in `src/shell/nav-types.ts` so the headless router bridge can
+ * `import type` it without reaching into the Mantine layer. Re-exported here so `SidebarItem` /
  * `SidebarSection` keep resolving straight from `basalt-ui`, exactly as before.
  */
 export type {
@@ -102,7 +105,7 @@ export type {
   MobileNavModel,
   MobileNavSlot,
   MobileNavSurface,
-} from '../nav/types'
+} from './nav-types'
 
 /** Brand identity shown in the sidebar header (logo + name). */
 export type BrandConfig = {
@@ -122,6 +125,10 @@ export type SettingsMenuItem = {
   label: string
   icon?: ReactNode
   onClick?: (e: MouseEvent) => void
+  /** This entry is the current selection (e.g. the active theme radio, the open dev tool) — a
+   * trailing check glyph renders in every form (flat footer row, gear `Menu.Item`, the mobile
+   * More-sheet row) and the row carries `aria-current="true"`. */
+  active?: boolean
 }
 
 export type BasaltShellProps = BasaltProps & {
@@ -276,30 +283,9 @@ const COLLAPSE_VERSION = 1
  */
 const collapseStores = new Map<string, () => readonly [boolean, (next: boolean) => void]>()
 
-/**
- * Seeds `basalt:<key>` from the raw pre-1.20.1 key once, so the switch doesn't silently re-expand
- * every consumer's sidebar. Mantine's `useLocalStorage` wrote a bare `JSON.stringify(value)` at the
- * un-namespaced key; only `'true'`/`'false'` are accepted, and only when the house key is empty.
- * A one-upgrade bridge, not a supported format — delete it once no consumer predates 1.20.1.
- */
-function migrateLegacyCollapse(key: string): void {
-  try {
-    if (window.localStorage.getItem(`basalt:${key}`) !== null) return
-    const legacy = window.localStorage.getItem(key)
-    if (legacy !== 'true' && legacy !== 'false') return
-    window.localStorage.setItem(
-      `basalt:${key}`,
-      JSON.stringify({ v: COLLAPSE_VERSION, value: legacy === 'true' }),
-    )
-  } catch {
-    // Storage blocked (private browsing, quota) — defaulting to expanded is a fine outcome.
-  }
-}
-
 function collapseStore(key: string): () => readonly [boolean, (next: boolean) => void] {
   const cached = collapseStores.get(key)
   if (cached) return cached
-  if (typeof window !== 'undefined') migrateLegacyCollapse(key)
   const store = createPersistedState<boolean>({ key, version: COLLAPSE_VERSION, initial: false })
   collapseStores.set(key, store)
   return store
@@ -354,11 +340,20 @@ function ShellFrame({
   // localStorage-persisted state entirely — the consumer becomes the source of truth.
   const isCollapseControlled = collapsedProp !== undefined
   const collapsed = isCollapseControlled ? collapsedProp : storedCollapsed
-  const toggleCollapse = () => {
+  const toggleCollapse = useCallback(() => {
     const next = !collapsed
     if (!isCollapseControlled) setStoredCollapsed(next)
     onCollapsedChange?.(next)
-  }
+  }, [collapsed, isCollapseControlled, setStoredCollapsed, onCollapsedChange])
+  // `commands/shell-bridge.ts`'s `toggleSidebar` handle — registered here so a consumer's
+  // `commands.tsx` calls it with ZERO module-scope bridge of its own, unlike argo's hand-rolled
+  // `sidebar-bridge.ts` this seeds from (see that file's own doc). Re-registered whenever
+  // `toggleCollapse` itself changes identity, so the handle always flips the CURRENT state rather
+  // than a stale closure's.
+  useEffect(() => {
+    registerSidebarToggle(toggleCollapse)
+    return () => registerSidebarToggle(null)
+  }, [toggleCollapse])
 
   const activeCrumb = findActiveCrumb(sections)
   // The account row, every settings entry and every mobile-reachable sidebar block render as flat

package/src/shell/mobile-nav-model.ts

@@ -22,7 +22,7 @@ import type {
   SidebarBlock,
   SidebarItem,
   SidebarSection,
-} from '../nav/types'
+} from './nav-types'
 import { sidebarBlockMobile } from './sidebar-block-model'
 
 /** Hard cap on bar slots, INCLUDING More. Five 72px slots is the widest a 360px viewport holds. */

package/src/shell/page-aside.tsx

@@ -43,14 +43,7 @@
  * read stays in JS — through `useSyncExternalStore`, so SSR, hydration and the first paint agree.
  * Recorded in `docs/CONTROLS-SPEC.md` §1 (C9) and `docs/ASIDE-SPEC.md` §0.
  */
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useMemo,
-  useState,
-  useSyncExternalStore,
-} from 'react'
+import { createContext, useCallback, useContext, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { useMantineTheme } from '@mantine/core'
@@ -61,6 +54,7 @@ import { usePersistedOrLocal } from '../state/persisted-or-local'
 import { FilterSetScope } from '../controls/filter-context'
 import { useAsidePanelSlot } from './page-bar'
 import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
+import { useMediaQueryMatches } from './use-breakpoint'
 import classes from './page-aside.module.css'
 
 type AsideRegion = {
@@ -133,50 +127,6 @@ export function AsideOutlet({ className }: { className?: string }) {
   return <div ref={setTarget} className={className} />
 }
 
-/** `window.matchMedia`, or `null` where there is no window and on a shim that does not ship it. */
-function mediaQueryList(query: string): MediaQueryList | null {
-  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return null
-  return window.matchMedia(query)
-}
-
-/**
- * Internal — a media query read through `useSyncExternalStore`, the ONE hook whose server snapshot
- * React honours during BOTH `renderToString` and the hydration pass.
- *
- * That is the whole reason it is not `@mantine/hooks`' `useMediaQuery`, which reads `matchMedia`
- * inside a `useState` INITIALIZER: on the server it returns `initialValue`, on the client's very
- * first render it returns the real match, and when that render is a HYDRATION the two disagree
- * silently — a server-rendered desktop panel hydrating on a phone against a client tree that has
- * already moved the children into the page bar's sheet. `getServerSnapshot` makes React render the
- * server's answer during hydration and re-render with the real one immediately after, which is the
- * documented, warning-free version of the same correction.
- *
- * `fallback` is what the server (and a shim with no `matchMedia`) sees. It stays the DESKTOP
- * answer, because the portalled branch is the one a shell-less or pre-hydration page can always
- * fall back to rendering.
- */
-function useMediaQueryMatches(query: string, fallback: boolean): boolean {
-  // ONE `MediaQueryList` per query, held across renders. `matchMedia()` allocates a fresh live
-  // object on every call and `getSnapshot` runs on every render AND after every store
-  // notification — so calling it in there churned an object per read, and the list `subscribe`
-  // listened on was never the one `getSnapshot` measured. Reading `.matches` off the SAME instance
-  // it subscribed to is what makes the snapshot and the notification describe one thing.
-  const list = useMemo(() => mediaQueryList(query), [query])
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      if (list === null) return () => {}
-      list.addEventListener('change', onStoreChange)
-      return () => {
-        list.removeEventListener('change', onStoreChange)
-      }
-    },
-    [list],
-  )
-  const getSnapshot = useCallback(() => list?.matches ?? fallback, [list, fallback])
-  const getServerSnapshot = useCallback(() => fallback, [fallback])
-  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
-}
-
 /** The three boxes `PageAside` paints, in every projection (`common/props.ts`). */
 export type PageAsideSlot = 'root' | 'header' | 'body'
 

package/src/shell/page-title.module.css

@@ -0,0 +1,33 @@
+/*
+ * `PageTitle` — the shell-less page-title primitive (C5 consolidation, `docs/CONTROLS-SPEC.md`
+ * law C8's third named spot alongside the breadcrumb and `PageBar.title`). Same treatment as
+ * `page-bar.module.css`'s `.title` (head font, 88% stretch, weight 550) — a page is named once,
+ * and every named spot reads identically regardless of which one a given surface uses.
+ */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-nav-icon-gap, 8px);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-xl);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+}
+
+.subtitle {
+  margin: 0;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-faint);
+}

package/src/shell/page-title.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly titleRow: string
+  readonly title: string
+  readonly subtitle: string
+}
+export default classes

package/src/shell/page-title.tsx

@@ -0,0 +1,57 @@
+/**
+ * `PageTitle` — the shell-less page-title primitive (C5 consolidation). Law C8
+ * (`docs/CONTROLS-SPEC.md` §2.2) names two sanctioned spots for a page's ONE name: the breadcrumb
+ * inside `BasaltShell`, or `PageBar.title` in a shell-less app — but neither fits a surface that
+ * has no `PageBar` at all, which is exactly what `BasaltErrorBoundary`'s default fallback and an
+ * auth gate ARE. Both were the two named `in-body-page-title` waivers this primitive closes
+ * (argo's `lib/error-boundary.tsx:36`, `lib/auth-gate.tsx:30` — each a bare `<Title order={2}>` +
+ * a muted subtitle line, hand-copied).
+ *
+ * A plain `<h1>` + CSS module, NOT Mantine's `<Title>` component — same reason `page-bar.tsx`'s
+ * own `title` row does (`page-bar.module.css`'s `.title`): `basalt/in-body-page-title` and its
+ * text-lane twin both match the JSX tag `<Title`, so a THIRD sanctioned spot built out of that
+ * same tag would need a waiver on itself. A raw, styled `<h1>` needs none — it IS the remedy, not
+ * a case of it.
+ *
+ * @example
+ * import { PageTitle } from 'basalt-ui'
+ *
+ * <PageTitle title="Something went wrong" subtitle="The page hit an unexpected error." />
+ */
+import { cx } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import type { ReactNode } from 'react'
+import classes from './page-title.module.css'
+
+export type PageTitleSlot = 'root' | 'title' | 'subtitle'
+
+export type PageTitleProps = BasaltProps &
+  SlotStylesProps<PageTitleSlot> & {
+    /** The page's one name. */
+    title: ReactNode
+    /** Optional muted line below the title. */
+    subtitle?: ReactNode
+    /** Optional leading icon, rendered before the title. Decorative — hidden from assistive tech,
+     * same convention as `WidgetHeader.icon`. */
+    icon?: ReactNode
+  }
+
+export function PageTitle(props: PageTitleProps): ReactNode {
+  assertRequiredProps('PageTitle', props, ['title'])
+  const { title, subtitle, icon, className, classNames, style } = props
+  return (
+    <div
+      className={cx(classes.root, classNames?.root, className)}
+      {...(style !== undefined && { style })}
+    >
+      <div className={cx(classes.titleRow, classNames?.title)}>
+        {icon !== undefined && <span aria-hidden="true">{icon}</span>}
+        <h1 className={classes.title}>{title}</h1>
+      </div>
+      {subtitle !== undefined && (
+        <p className={cx(classes.subtitle, classNames?.subtitle)}>{subtitle}</p>
+      )}
+    </div>
+  )
+}

package/src/shell/sidebar-block-model.ts

@@ -9,7 +9,7 @@
  * A default re-derived per call site is how the count and the renderer drift apart (see
  * `accountRowCount`'s doc for the same failure with account rows).
  */
-import type { SidebarBlock } from '../nav/types'
+import type { SidebarBlock } from './nav-types'
 
 /** Envelope version for a persisted fold flag. Bump only if the value stops being a boolean. */
 export const FOLD_VERSION = 1

package/src/shell/sidebar-blocks.tsx

@@ -21,7 +21,7 @@ import type {
   SidebarCustomBlock,
   SidebarListBlock,
   SidebarProgressBlock,
-} from '../nav/types'
+} from './nav-types'
 import { NavCountBadge } from './nav-count-badge'
 import { createPersistedState } from '../state'
 import {

package/src/shell/use-breakpoint.ts

@@ -0,0 +1,73 @@
+/**
+ * `useBreakpoint` — one media-query hook over the theme's own breakpoints, SSR/hydration-safe.
+ *
+ * Built on `useSyncExternalStore`, NOT `@mantine/hooks`' `useMediaQuery` — that hook reads
+ * `matchMedia` inside a `useState` initializer, so on the server it returns its `fallback` and on
+ * the client's very first render it returns the REAL match; when that render is a hydration pass
+ * the two disagree silently (a server-rendered desktop layout hydrating on a phone against a
+ * client tree that already moved). `useSyncExternalStore`'s `getServerSnapshot` makes React render
+ * the server's answer during hydration and correct itself immediately after — the documented,
+ * warning-free version of the same fix. `page-aside.tsx`'s own former private
+ * `useMediaQueryMatches` carried this exact rationale; it now lives here and page-aside composes
+ * this hook instead (C5 consolidation — one media-query hook, not two).
+ *
+ * `edge` defaults to `'min'` (`"at least this wide"`); pass `'max'` for `"narrower than"`. The
+ * `fallback` (what the server, and a shim with no `matchMedia`, sees) defaults to the answer that
+ * assumes the NARROW side of the query — `false` for `min`, `true` for `max` — since a component
+ * library cannot know a consumer's real device mix; a call site with its own rationale (e.g.
+ * `page-aside.tsx`'s desktop-first portal fallback) overrides it via `options.fallback`.
+ *
+ * @example
+ * import { useBreakpoint } from 'basalt-ui'
+ *
+ * const isDesktop = useBreakpoint('sm')            // >= theme.breakpoints.sm
+ * const isNarrow = !useBreakpoint('sm')             // < theme.breakpoints.sm
+ * const isWide = useBreakpoint('lg')                // >= theme.breakpoints.lg
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+import { useMantineTheme } from '@mantine/core'
+
+export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/** `window.matchMedia`, or `null` where there is no window and on a shim that does not ship it. */
+function mediaQueryList(query: string): MediaQueryList | null {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return null
+  return window.matchMedia(query)
+}
+
+/**
+ * Internal — the raw media-query read. Exported (not `default`) so `page-aside.tsx` can compose
+ * it directly for its `(min-width: theme.breakpoints.sm)` desktop check without re-deriving the
+ * query string `useBreakpoint` builds for the fixed `BreakpointName` union.
+ */
+export function useMediaQueryMatches(query: string, fallback: boolean): boolean {
+  // ONE `MediaQueryList` per query, held across renders — `matchMedia()` allocates a fresh live
+  // object on every call, and `getSnapshot` runs on every render AND after every store
+  // notification, so calling it there would churn an object per read while `subscribe` listened
+  // on a different instance than `getSnapshot` measured.
+  const list = useMemo(() => mediaQueryList(query), [query])
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (list === null) return () => {}
+      list.addEventListener('change', onStoreChange)
+      return () => {
+        list.removeEventListener('change', onStoreChange)
+      }
+    },
+    [list],
+  )
+  const getSnapshot = useCallback(() => list?.matches ?? fallback, [list, fallback])
+  const getServerSnapshot = useCallback(() => fallback, [fallback])
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}
+
+export function useBreakpoint(
+  name: BreakpointName,
+  edge: 'min' | 'max' = 'min',
+  options?: { fallback?: boolean },
+): boolean {
+  const theme = useMantineTheme()
+  const bp = theme.breakpoints[name]
+  const fallback = options?.fallback ?? edge === 'max'
+  return useMediaQueryMatches(`(${edge}-width: ${bp})`, fallback)
+}

package/src/state/fields.ts

@@ -561,13 +561,7 @@ export type FieldCodec = {
     readonly int: boolean
     readonly step: number | undefined
   }
-  /**
-   * Validate a STORED (or caller-supplied) value. `null` = unusable.
-   *
-   * Deliberately a different function from `fromSearch` for one kind: the deprecated multi store
-   * reads an empty URL array as "absent", and reusing that rule on the storage side would turn a
-   * deliberately CLEARED filter into a miss and resurrect the fallback on upgrade.
-   */
+  /** Validate a STORED (or caller-supplied) value. `null` = unusable. */
   decode(raw: unknown): unknown
   /** Pull the field out of a router search object. `null` = absent or invalid. */
   fromSearch(search: Record<string, unknown>): unknown
@@ -614,17 +608,11 @@ function sameList(a: unknown, b: unknown): boolean {
 }
 
 /**
- * Build the codec for one field. `legacyMultiEmpty` restores the DEPRECATED multi-store's rule that
- * an EMPTY url array means "absent, fall through to storage" — the deprecated wrapper's contract,
- * never the new store's, where an empty selection is a value like any other.
+ * Build the codec for one field.
  *
  * @internal — see `FieldCodec`.
  */
-export function resolveFieldCodec(
-  name: string,
-  f: AnyField,
-  opts?: { legacyMultiEmpty?: boolean },
-): FieldCodec {
+export function resolveFieldCodec(name: string, f: AnyField): FieldCodec {
   switch (f.kind) {
     case 'enum': {
       const allowed = new Set<string>(f.values)
@@ -642,19 +630,9 @@ export function resolveFieldCodec(
         }
         return f.values.filter((value) => picked.has(value))
       }
-      // The legacy empty-array rule is a URL rule ONLY. A stored `[]` is what "I cleared every
-      // filter" looks like, and the deprecated store has always read it back as `[]`.
-      const decodeUrl =
-        opts?.legacyMultiEmpty === true
-          ? (raw: unknown): unknown => {
-              const value = decode(raw)
-              return Array.isArray(value) && value.length === 0 ? null : value
-            }
-          : decode
       return single(name, f, decode, {
         optionValues: f.values,
         equals: sameList,
-        decodeUrl,
       })
     }
     case 'range': {
@@ -759,13 +737,10 @@ function single(
   extra?: {
     optionValues?: readonly string[]
     equals?: (a: unknown, b: unknown) => boolean
-    /** URL-side decoder when it differs from the storage-side one (multi, legacy layout only). */
-    decodeUrl?: (raw: unknown) => unknown
     /** Number only: the declared bounds and grain, republished onto the handle. */
     bounds?: FieldCodec['bounds']
   },
 ): FieldCodec {
-  const decodeUrl = extra?.decodeUrl ?? decode
   return {
     kind: f.kind,
     lane: f.lane,
@@ -776,7 +751,7 @@ function single(
     },
     ...(extra?.bounds !== undefined && { bounds: extra.bounds }),
     decode,
-    fromSearch: (search) => decodeUrl(search[name]),
+    fromSearch: (search) => decode(search[name]),
     toSearch: (value) => ({ [name]: value }),
     equals: extra?.equals ?? ((a, b) => a === b),
     optionValues: extra?.optionValues ?? [],
@@ -805,12 +780,6 @@ export type StoreCoreOptions = {
   readonly key: string
   readonly fields: Record<string, AnyField>
   readonly version?: number | undefined
-  /**
-   * Legacy single-value storage layout: the whole envelope value IS this field's value, the shape
-   * `createSearchParamStore` has written since 1.0.0. Set ONLY by the deprecated wrappers — a
-   * consumer's already-persisted selection has to keep resolving byte-for-byte.
-   */
-  readonly legacyValueField?: string
 }
 
 /**
@@ -967,10 +936,9 @@ function assertNoParamCollision(key: string, entries: readonly StoreEntry[]): vo
 /** @internal — the seam behind `createSearchStore` and `createLocalStore`. */
 export function createStoreCore(o: StoreCoreOptions): StoreCore {
   const version = o.version ?? 1
-  const legacy = o.legacyValueField
   const entries: StoreEntry[] = Object.entries(o.fields).map(([name, f]) => ({
     name,
-    codec: resolveFieldCodec(name, f, { legacyMultiEmpty: legacy !== undefined }),
+    codec: resolveFieldCodec(name, f),
   }))
   assertNoParamCollision(o.key, entries)
   const urlEntries = entries.filter((entry) => entry.codec.lane.url)
@@ -983,12 +951,8 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
   const usePersistedRaw = createPersistedState<unknown>({ key: o.key, version, initial: null })
   const memory = createMemoryLane()
 
-  const toRecord = (raw: unknown): StoreRecord => {
-    if (legacy !== undefined) return raw === null || raw === undefined ? {} : { [legacy]: raw }
-    return isRecord(raw) ? raw : {}
-  }
-  const fromRecord = (record: StoreRecord): unknown =>
-    legacy !== undefined ? (record[legacy] ?? null) : record
+  const toRecord = (raw: unknown): StoreRecord => (isRecord(raw) ? raw : {})
+  const fromRecord = (record: StoreRecord): unknown => record
 
   const readRecord = (): StoreRecord => toRecord(readPersistedValue(o.key, version))
 

package/src/styles.css

@@ -40,6 +40,42 @@
 }
 
 @layer basalt {
+  /* Native/PWA chrome (C5 consolidation) — three of the five rules argo's own `styles/native.css`
+     carried, moved here so every consumer gets them for free instead of hand-copying a stylesheet.
+     The other two (safe-area padding on the sidebar/main) are CSS-module rules on those specific
+     regions, not global — see `shell/app-sidebar.module.css` and `shell/app-main.module.css`.
+     Overscroll containment and the footer's safe-area-bottom inset already ship
+     (`shell/app-main.module.css`, `shell/app-mobile-nav.module.css`) and are not repeated here. */
+
+  /* Stops iOS from inflating font sizes on a rotation into landscape — `text-size-adjust` governs
+     text INFLATION, a different failure mode than the input-zoom floor just below. */
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+  }
+
+  /* Removes the grey tap-highlight flash on iOS/Android for anything actually tappable. Scoped to
+     the interactive roles/tags rather than `*` (argo's own rule): a highlight on non-interactive
+     content is not the flash this exists to remove, and `*` would also numb a consumer's own
+     custom interactive elements that don't match one of these. */
+  button,
+  a,
+  [role='button'],
+  [role='tab'] {
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  /* A long-press on a control must not select its label or pop the iOS callout menu — inputs and
+     prose content stay selectable. Same Mantine class-hook targets argo's own rule used
+     (`.mantine-Button-root`/`.mantine-NavLink-root`/`.mantine-Burger-root`): the theme layer is
+     the one place allowed to reach for a Mantine class hook directly, per `basalt-mantine.md`. */
+  .mantine-Button-root,
+  .mantine-NavLink-root,
+  .mantine-Burger-root {
+    -webkit-touch-callout: none;
+    user-select: none;
+  }
+
   /* iOS input-zoom FLOOR. Safari zooms the viewport whenever a focused input computes below 16px,
      and never zooms back out on blur — the single worst mobile-form defect. 16px is the only clean
      fix: `maximum-scale=1` / `user-scalable=no` block pinch-zoom on Android (WCAG 1.4.4),