basalt-ui 1.41.0 → 2.0.1

package/src/router-tanstack/use-nav.ts

@@ -1,5 +1,5 @@
 /**
- * `useNav` — resolve a `defineNav` definition into the two props `BasaltShell` needs.
+ * Resolve a `defineNav` definition into the two props `BasaltShell` renders from.
  *
  * One `defineNav([...])` in a leaf module produces the desktop sidebar AND the mobile bar: this
  * hook resolves active state through the router and builds each destination's anchor, which is
@@ -9,8 +9,8 @@
  * No JSX — anchors are built with `createElement`, so `./router-tanstack` stays a headless,
  * no-JSX `.ts` module per its own barrel contract.
  */
-import { createElement, useMemo } from 'react'
-import type { ElementType, ReactNode } from 'react'
+import { createElement, forwardRef, useMemo } from 'react'
+import type { AnchorHTMLAttributes, ElementType, ReactNode } from 'react'
 import { Link, useMatchRoute, useRouterState } from '@tanstack/react-router'
 import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../shell/nav-types'
 import { flattenNav } from './nav'
@@ -24,24 +24,54 @@ export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
    */
   badges?: Partial<Record<NavItemId<G>, number | ReactNode>>
   /** Override active detection entirely. */
-  isActive?: (item: AnyNavItem) => boolean
+  isActive?: (item: AnyNavItem & { id: NavItemId<G> }) => boolean
   getScrollElement?: () => HTMLElement | null
 }
 
-/** Spread straight onto `<BasaltShell {...nav} />` — both keys are `BasaltShellProps` keys. */
-export type NavBinding = { sections: SidebarSection[]; mobileNav: MobileNavConfig }
+type OverriddenAnchorProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
+  'data-status'?: string
+  'data-basalt-current'?: 'page' | 'true'
+  _asChild?: unknown
+}
 
 /**
- * Resolve a nav definition against the live router.
- *
- * @example
- * const nav = useNav(NAV, { badges: { calendar: 3 } })
- * return <BasaltShell brand={brand} {...nav}>{children}</BasaltShell>
+ * The host `Link` renders as when `isActive` overrides the router. A `Link` computes its own
+ * `isActive` and spreads `aria-current="page"` + `data-status="active"` as the LAST props it
+ * applies (`@tanstack/react-router` 1.170.x `dist/esm/link.js`, `applyLinkState`), so under an
+ * override a router-matched loser would still claim the page. `Link` renders `props._asChild` as
+ * its host element in place of `'a'` (same file, `Link`: `const host = props._asChild || "a"`) —
+ * an underscore-prefixed, undocumented seam, so `MAINTAINING.md` names it for re-verification on
+ * every router bump. This host drops the router's two attributes and re-applies only basalt's own
+ * verdict, which the anchor smuggles through `data-basalt-current`; `data-status` is re-stamped
+ * for it so both paths expose the same hooks on the winner.
+ */
+const OverriddenAnchor = forwardRef<HTMLAnchorElement, OverriddenAnchorProps>((props, ref) => {
+  const {
+    'aria-current': _routerCurrent,
+    'data-status': _routerStatus,
+    'data-basalt-current': current,
+    _asChild: _host,
+    ...rest
+  } = props
+  return createElement('a', {
+    ...rest,
+    ...(current !== undefined && { 'aria-current': current, 'data-status': 'active' }),
+    ref,
+  })
+})
+OverriddenAnchor.displayName = 'OverriddenAnchor'
+
+/** What this resolver turns a definition into: `ShellFrame`'s sidebar sections and mobile-bar tuning. */
+export type ResolvedNav = { sections: SidebarSection[]; mobileNav: MobileNavConfig }
+
+/**
+ * Resolve a nav definition against the live router into `BasaltShell`'s internal `ShellFrame`
+ * props. Shell-internal: a consumer passes `nav={NAV}` to `BasaltShell` and never calls this.
  */
 export function useNav<
   const G extends ReadonlyArray<AnyNavGroup>,
   const T extends ReadonlyArray<NavTabId<G>>,
->(config: NavConfig<G, T>, opts?: UseNavOptions<G>): NavBinding {
+>(config: NavConfig<G, T>, opts?: UseNavOptions<G>): ResolvedNav {
   // `useMatchRoute` is `useCallback(fn, [router])` — a STABLE identity across renders — and it
   // subscribes internally to `router.stores.matchRouteDeps`, so the component still re-renders on
   // navigation. That makes it safe as a memo dep, and makes the memo below actually hit.
@@ -61,7 +91,7 @@ export function useNav<
     // `active` on its own — it only says "on the path", and the pass below picks ONE winner
     // across the whole definition so a parent and its child can no longer both read `active`.
     const matchOf = (item: AnyNavItem): boolean =>
-      isActiveOverride?.(item) ??
+      isActiveOverride?.(item as AnyNavItem & { id: NavItemId<G> }) ??
       Boolean(
         matchRoute({
           to: item.link.to,
@@ -138,6 +168,10 @@ export function useNav<
         createElement(Link as ElementType, {
           ...item.link,
           activeOptions: { exact: true, includeSearch: true },
+          ...(isActiveOverride !== undefined && {
+            _asChild: OverriddenAnchor,
+            'data-basalt-current': props['aria-current'],
+          }),
           ...props,
         })
 

package/src/shell/app-mobile-nav.tsx

@@ -295,8 +295,9 @@ export function MobileNav({
   const [openKey, setOpenKey] = useState<string | null>(null)
   // The nested block sheet, keyed the same way and for the same reason.
   const [openBlockKey, setOpenBlockKey] = useState<string | null>(null)
-  // `DEFAULT_THEME.respectReducedMotion` is false in Mantine 9.3 and `createBasaltTheme` does not
-  // set it, so the preference has to be read explicitly at the call site.
+  // `createBasaltTheme` sets `respectReducedMotion: true`, which covers Mantine's own `<Transition>`
+  // timing. `scrollTo({ behavior })` below is not Mantine's, so that read stays explicit here; the
+  // `duration` literals are kept as the belt to the theme's braces, not proven redundant.
   const reduceMotion = useReducedMotion()
   const { step } = useBasaltSpacing()
 

package/src/shell/app-sidebar.tsx

@@ -221,7 +221,7 @@ function NavLinkBody({
     // default (which a consumer's `SidebarItem.Anchor` may compute independently) — mirrors
     // `app-mobile-nav.tsx`'s identical pattern so both surfaces agree on what "active" means.
     'aria-current': active ? ('page' as const) : undefined,
-    // `item.ancestor` (a parent on the winner's path — `useNav`'s exclusivity pass) is NEVER
+    // `item.ancestor` (a parent on the winner's path — the nav resolver's exclusivity pass) is NEVER
     // active and never carries `aria-current`; it only earns a `data-ancestor` hook for CSS. A
     // leaf item never has `ancestor` set, so this is a no-op there — shared here rather than
     // duplicated per render path.

package/src/shell/aside-docking.ts

@@ -1,5 +1,5 @@
 /**
- * Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — the pure decision `ShellFrame`
+ * Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — the pure decision `ShellBody`
  * sizes `AppShell.Aside` from. An open aside pushes main only in `expanded` while main keeps
  * `MAIN_MIN_WIDTH` beside the navbar; otherwise the region reserves just its rail and an open panel
  * overlays main. Unclaimed, the region is zero-wide.

package/src/shell/index.tsx

@@ -10,12 +10,13 @@
  * why the More surface must also carry the account and settings rows the sidebar footer holds on
  * desktop.
  *
- * Router-agnostic: argo's router coupling (typed `navigate`, `useMatchRoute` active detection, the
- * sidebar-collapse zustand store) stays consumer-side. The consumer resolves `item.active`,
- * `item.onClick`, `item.badge`/`item.count` and supplies `item.Anchor` — its router `<Link>`,
- * which basalt HOSTS rather than delegating rendering to. The breadcrumb is derived from the
- * active item across `sections`, not from a router hook. Collapse is persisted via basalt's own
- * `createPersistedStore` (`../state/persisted`, `createPersistedState` plus an `isSet` flag) keyed
+ * Router-coupled through ONE seam: `nav` (a `defineNav` definition) is resolved here against the
+ * TanStack Router — `useMatchRoute` active detection, each destination's `<Link>` as its
+ * `item.Anchor`, `badges` as `item.count`/`item.badge` — so the consumer wires no router callback.
+ * The pieces below (`ShellFrame`, the sidebar, the mobile bar) stay presentational and take already
+ * resolved `sections`. The breadcrumb is derived from the active item across those sections, not
+ * from a router hook. Collapse is persisted via basalt's own `createPersistedStore`
+ * (`../state/persisted`, `createPersistedState` plus an `isSet` flag) keyed
  * by `storageKey` — see `collapseStore`. While nothing is persisted the size class picks the
  * default (rail in `medium`); any stored value, `false` included, wins.
  */
@@ -48,6 +49,9 @@ import type {
 } from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedStore } from '../state/persisted'
+import { useNav } from '../router-tanstack/use-nav'
+import type { UseNavOptions } from '../router-tanstack/use-nav'
+import type { AnyNavGroup, NavConfig, NavTabId } from '../router-tanstack/nav'
 import { SizeClassHintContext, useSizeClass } from './use-size-class'
 import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
@@ -148,19 +152,13 @@ export type SettingsMenuItem = {
   current?: 'selection' | 'page'
 }
 
-export type BasaltShellProps = BasaltProps & {
+/** Everything `BasaltShell` and `ShellFrame` share — the nav arrives differently in each. */
+export type ShellBaseProps = BasaltProps & {
   /**
    * Brand identity for the sidebar header. Supplying `menu` turns the brand row into a `Name ▾`
    * workspace switcher — the rows are `AccountMenuItem`s, the shape the account menu already uses.
    */
   brand: BrandConfig & { menu?: AccountMenuItem[] }
-  /** Grouped nav sections — the ONE definition, rendered as the sidebar and projected to the bar. */
-  sections: SidebarSection[]
-  /**
-   * Mobile bar tuning. Every field optional — the defaults ARE the design, and a nav with nothing
-   * configured still produces a working bar (see `projectMobileNav`'s zero-config fallback).
-   */
-  mobileNav?: MobileNavConfig
   /**
    * Persistent, shell-owned header actions (timer, notifications, a global `SyncButton`) — DECLARED
    * DATA, not a `ReactNode` slot, so basalt owns the mobile projection: the first two ride the bar,
@@ -247,6 +245,21 @@ export type BasaltShellProps = BasaltProps & {
   children?: ReactNode
 }
 
+export type BasaltShellProps<
+  G extends ReadonlyArray<AnyNavGroup>,
+  T extends ReadonlyArray<NavTabId<G>>,
+> = ShellBaseProps &
+  UseNavOptions<G> & {
+    /**
+     * The `defineNav` definition — the ONE nav, resolved against the router here: the sidebar, the
+     * mobile bar (its tuning rides `defineNav`'s `mobile`) and the breadcrumb all derive from it.
+     * Alongside it: `badges` (a `number` becomes `item.count`, anything else `item.badge`; hoist or
+     * memoize the object), `isActive` (override active detection) and `getScrollElement` (the
+     * mobile bar's scroll container).
+     */
+    nav: NavConfig<G, T>
+  }
+
 /** Active nav item across all sections → the breadcrumb's `{ section, parent?, …, page }`. */
 function findActiveCrumb(sections: SidebarSection[]): ActiveCrumb | undefined {
   for (const section of sections) {
@@ -325,10 +338,39 @@ function collapseStore(key: string): CollapseStore {
   return store
 }
 
+/** The application shell. `nav` is resolved against the router; the rest is `ShellBaseProps`. */
+export function BasaltShell<
+  const G extends ReadonlyArray<AnyNavGroup>,
+  const T extends ReadonlyArray<NavTabId<G>>,
+>(props: BasaltShellProps<G, T>) {
+  assertRequiredProps('BasaltShell', props, ['brand', 'nav'])
+  const { nav, badges, isActive, getScrollElement, ...rest } = props
+  const { sections, mobileNav } = useNav(nav, {
+    ...(badges !== undefined && { badges }),
+    ...(isActive !== undefined && { isActive }),
+    ...(getScrollElement !== undefined && { getScrollElement }),
+  })
+  return <ShellFrame {...rest} sections={sections} mobileNav={mobileNav} />
+}
+
 /**
+ * The resolved-nav shell: what `BasaltShell` renders once `nav` is a router-resolved `sections`.
+ *
+ * @internal
+ */
+export type ShellFrameProps = ShellBaseProps & {
+  /** Grouped nav sections — rendered as the sidebar and projected onto the mobile bar. */
+  sections: SidebarSection[]
+  /** Mobile bar tuning; every field optional (see `projectMobileNav`'s zero-config fallback). */
+  mobileNav?: MobileNavConfig
+}
+
+/**
+ * @internal Renders resolved `sections`; consumers use `BasaltShell nav` instead.
+ *
  * The shell's two page-level regions are providers, and both wrap the frame rather than living
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
- * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellFrame`
+ * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellBody`
  * has to READ to size `AppShell.Aside`, so it cannot be the component that provides it.
  *
  * **Native title bar (opt-in CSS contract).** A desktop host with a macOS overlay title bar paints
@@ -338,18 +380,17 @@ function collapseStore(key: string): CollapseStore {
  * the inset plus the collapse toggle, so the 48px rail pushes the toggle to the right of the lights
  * instead of clipping it. The breadcrumb after a widened rail zone shifts right by the same amount.
  */
-export function BasaltShell(props: BasaltShellProps) {
-  assertRequiredProps('BasaltShell', props, ['brand', 'sections'])
+export function ShellFrame(props: ShellFrameProps) {
   return (
     <PageBarProvider globalActions={props.globalActions ?? []}>
       <AsideProvider>
-        <ShellFrame {...props} />
+        <ShellBody {...props} />
       </AsideProvider>
     </PageBarProvider>
   )
 }
 
-function ShellFrame({
+function ShellBody({
   brand,
   sections,
   mobileNav,
@@ -366,7 +407,7 @@ function ShellFrame({
   children,
   className,
   style,
-}: BasaltShellProps) {
+}: ShellFrameProps) {
   // The active density level's resolved spacing — the AppShell dimensions below must track it
   // (see `SPACE_STEP_BASE`'s "shell/index.tsx" group doc in `tokens/palette.ts`): their contents
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal

package/src/shell/page-aside.tsx

@@ -46,7 +46,18 @@
  * 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, useRef, useState } from 'react'
+import {
+  Activity,
+  ViewTransition,
+  createContext,
+  startTransition,
+  useCallback,
+  useContext,
+  useDeferredValue,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { cx } from '../common/props'
@@ -74,7 +85,7 @@ type AsideRegion = {
   publishFolded: (folded: boolean) => void
   /**
    * Bumped by `requestClose` — never 0 again once a close has been requested, so `PageAside` can
-   * treat "changed since mount" as "fold now" without a ref of its own. `ShellFrame` is the one
+   * treat "changed since mount" as "fold now" without a ref of its own. `ShellBody` is the one
    * caller, on Escape while the aside renders as an overlay.
    */
   closeSignal: number
@@ -141,7 +152,7 @@ export function useAsideRegion(): Pick<AsideRegion, 'claimed' | 'folded' | 'requ
 
 /**
  * Internal — whether an OPEN aside would push the main column (expanded, main keeps its floor)
- * rather than overlay it. Provided by `ShellFrame`, which alone knows the navbar width, from the
+ * rather than overlay it. Provided by `ShellBody`, which alone knows the navbar width, from the
  * same render that computes it: a state published after mount would make the first pass read
  * "cannot dock" and fold a default-open aside for one commit.
  */
@@ -255,11 +266,21 @@ export function PageAside(props: PageAsideProps): ReactNode {
   // children. `useSizeClass` (`useSyncExternalStore`) keeps SSR, the hydration pass and the first
   // client paint agreeing on which single node exists.
   const isCompact = useSizeClass() === 'compact'
-  const [folded, setFolded] = usePersistedOrLocal({
+  const [folded, storeFolded] = usePersistedOrLocal({
     scope: 'aside',
     persistKey,
     initial: defaultFolded ?? !docks,
   })
+  // V2-SPEC § 5: a fold runs in a transition so the region's `<ViewTransition>` fires. A persisted
+  // fold is a `useSyncExternalStore` read, which always commits synchronously and so never
+  // activates one; `useDeferredValue` re-renders at transition priority, which is what does.
+  // `folded` is the truth (the toggle's `aria-*`, the reserved width published to the shell);
+  // `shownFolded` only decides what is painted, one transition later.
+  const shownFolded = useDeferredValue(folded)
+  const setFolded = useCallback(
+    (next: boolean) => startTransition(() => storeFolded(next)),
+    [storeFolded],
+  )
 
   const portalled = inShell && !isCompact
   // Below `sm` the panel goes into the page bar's row 2 IF there is one. Without a row 2 there is
@@ -303,7 +324,7 @@ export function PageAside(props: PageAsideProps): ReactNode {
   // fold before the user ever asked. `closeSignalBaseline` captures the value THIS instance mounted
   // with, so only a change AFTER that point — a close requested while this instance is live — folds
   // it; a later-mounted instance still respects its own `defaultFolded`/persisted state. Guarded on
-  // `portalled`, matching where `ShellFrame` can even observe an overlay to escape out of.
+  // `portalled`, matching where `ShellBody` can even observe an overlay to escape out of.
   //
   // The baseline ADVANCES to every `closeSignal` it acts on — not just at mount. Without that, a
   // portalled false→true transition (the aside leaving and rejoining the shell, e.g. a viewport
@@ -329,26 +350,29 @@ export function PageAside(props: PageAsideProps): ReactNode {
       aria-label={title}
       {...(style !== undefined && { style })}
     >
-      {portalled && folded ? (
+      {portalled && shownFolded && (
         <div className={classes.rail}>
-          <FoldButton folded onToggle={() => setFolded(false)} />
+          <FoldButton folded={folded} onToggle={() => setFolded(false)} />
         </div>
-      ) : (
-        <>
-          <div className={cx(classes.header, classNames?.header)} data-basalt-page-aside-header="">
-            <span className={classes.title}>{title}</span>
-            {portalled && <FoldButton folded={false} onToggle={() => setFolded(true)} />}
-          </div>
-          <div className={cx(classes.body, classNames?.body)}>
-            {/* The aside body IS a home (law C1) and a filter surface: `panel` is what turns every
-                bound control inside into an inspector row. `registry: null` because there is no
-                census here — no `Filters (n)`, no `Reset all`. */}
-            <FilterSetScope surface="panel" registry={null}>
-              {children}
-            </FilterSetScope>
-          </div>
-        </>
       )}
+      {/* Hidden, not unmounted: scroll position, input values and `useState` survive a fold. A
+          hidden `Activity` runs the subtree's effect cleanups and re-runs the effects on re-show
+          (`agent/chat/thread-feed-row.tsx`), so a subscribing or streaming child resumes from its
+          own state, but anything an effect set up (a timer, a socket) is torn down while folded. */}
+      <Activity mode={portalled && shownFolded ? 'hidden' : 'visible'}>
+        <div className={cx(classes.header, classNames?.header)} data-basalt-page-aside-header="">
+          <span className={classes.title}>{title}</span>
+          {portalled && <FoldButton folded={false} onToggle={() => setFolded(true)} />}
+        </div>
+        <div className={cx(classes.body, classNames?.body)}>
+          {/* The aside body IS a home (law C1) and a filter surface: `panel` is what turns every
+              bound control inside into an inspector row. `registry: null` because there is no
+              census here — no `Filters (n)`, no `Reset all`. */}
+          <FilterSetScope surface="panel" registry={null}>
+            {children}
+          </FilterSetScope>
+        </div>
+      </Activity>
     </section>
   )
 
@@ -372,5 +396,5 @@ export function PageAside(props: PageAsideProps): ReactNode {
   if (!portalled) return inShell && !settled ? null : panel
   // `target` is null for the first commit only — the outlet's ref sets it.
   if (target === null) return null
-  return createPortal(panel, target)
+  return createPortal(<ViewTransition>{panel}</ViewTransition>, target)
 }

package/src/shell/page-bar.tsx

@@ -37,7 +37,7 @@ import {
 import { FilterPill } from '../controls/filter-pill'
 import { FilterSheet } from '../controls/filter-sheet'
 import { SyncButton } from '../controls/sync-button'
-import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions'
+import type { BarAction, GlobalAction, PageBarActions } from '../controls/actions'
 import type { SyncButtonProps } from '../controls/sync-button'
 import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import classes from './page-bar.module.css'
@@ -267,7 +267,7 @@ export type PageBarProps = BasaltProps &
      */
     title?: string
     icon?: ReactNode
-    actions?: ActionGroupProps
+    actions?: PageBarActions
     /** `scope` is fixed to `'page'` — a global sync belongs in the shell's `globalActions` (law C12). */
     sync?: Omit<SyncButtonProps, 'scope'>
     /** `FilterSet` descendants only (law C1). */
@@ -438,7 +438,7 @@ export function PageBar({
                 One `CtlSlot` for the whole row now, so the sync button and the buttons around it
                 resolve the tier from the same provider. */}
             <BarActionRow
-              {...actions}
+              {...(actions !== undefined && { primary: actions[0], secondary: actions.slice(1) })}
               host="page"
               mobileOnly={filtersEndActions}
               {...(sync !== undefined && { syncNode: <SyncButton {...sync} scope="page" /> })}

package/src/shell/page-title.tsx

@@ -2,7 +2,7 @@
  * `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
+ * has no `PageBar` at all, which is exactly what the provider's `RootBoundary` 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).

package/src/state.ts

@@ -1,49 +1,23 @@
 /**
- * `basalt-ui/state` — the headless state surface: no Mantine, no router, no JSX.
+ * `basalt-ui/state` — the headless state surface: no Mantine, no JSX. The persisted and local
+ * lanes are router-free; only `createSearchStore` reaches `@tanstack/react-router` (an optional peer).
  *
- * Two halves, one barrel:
+ * - `createPersistedState` — the versioned localStorage primitive every basalt module persists through.
+ * - `field.*`, `FieldHandle`, `EnumField`, `RangeWindow` and `createLocalStore` — the store field
+ *   vocabulary and the router-free store.
+ * - `createSearchStore` — the URL-backed store (the store half of 1.x `./router-tanstack`).
  *
- * - `./state/persisted` — `createPersistedState` / `readPersistedValue`, the versioned localStorage
- *   primitive every other basalt module persists through.
- * - `./state/fields` — the store field vocabulary (`field.*`, `FieldHandle`, the lanes) and
- *   `createLocalStore`, the router-free store. `createSearchStore` (`basalt-ui/router-tanstack`)
- *   is the router-coupled factory over the same fields.
- *
- * The split is a file boundary, not a surface boundary: this barrel is what `package.json`'s
- * `./state` export resolves to, and its named exports are pinned by `scripts/export-surface.json`.
+ * Internal consumers import the wider field types from `./state/fields`.
  */
 
-export {
-  createPersistedState,
-  type PersistedStateOptions,
-  readPersistedValue,
-} from './state/persisted'
+export { createPersistedState } from './state/persisted'
 
 export {
   field,
   createLocalStore,
-  type LocalStore,
-  // The field vocabulary
-  type FieldLane,
-  type ResolvedLane,
-  type ResolveLane,
-  type RangeValue,
-  type RangeParams,
-  type RangePresets,
-  type RangeWindow,
-  type RangeWindows,
-  type FieldFallback,
-  type FieldSetOptions,
   type EnumField,
-  type MultiField,
-  type RangeField,
-  type NumberField,
-  type BooleanField,
-  type StringField,
-  type AnyField,
-  type FieldValue,
-  type FieldOption,
   type FieldHandle,
-  type SearchValues,
-  type StoredValues,
+  type RangeWindow,
 } from './state/fields'
+
+export { createSearchStore } from './router-tanstack/search-store'

package/src/styles.css

@@ -8,13 +8,23 @@
 /* Layer order — LOW to HIGH priority. Declared up front (a `@layer` statement is allowed before
  * `@import`) so it holds no matter which order the consumer's bundler emits the stylesheets in.
  *
- * This is load-bearing, not decorative: the consumer MUST import `@mantine/core/styles.layer.css`,
- * never the plain `@mantine/core/styles.css`. Mantine's default bundle is entirely UNLAYERED, and
- * unlayered author styles outrank EVERY layered rule regardless of specificity — so with the plain
+ * This is load-bearing, not decorative: any Mantine CSS a consumer adds must be the `.layer.css`
+ * variant, never the plain `styles.css`. Mantine's default bundles are entirely UNLAYERED, and
+ * unlayered author styles outrank EVERY layered rule regardless of specificity — so with a plain
  * bundle this whole `@layer basalt` block silently loses to Mantine, including the iOS input floor
- * below. `basalt doctor` flags the wrong import. */
+ * below. This file already imports core, notifications and spotlight; `basalt doctor` flags the
+ * plain variant. */
 @layer mantine, basalt;
 
+/* Every Mantine layer bundle the provider mounts (core, Notifications, Spotlight; `@mantine/modals`
+ * ships no CSS), imported here so a consumer's one `import 'basalt-ui/styles.css'` carries them
+ * (docs/V2-SPEC.md § 1 Open). `@mantine/dates` is not here: only `./controls-dates` needs it, so it
+ * stays the consumer's import. After the `@layer` statement above on purpose: the order is already
+ * fixed, so the imports cannot reorder the layers whichever way the bundler emits them. */
+@import '@mantine/core/styles.layer.css';
+@import '@mantine/notifications/styles.layer.css';
+@import '@mantine/spotlight/styles.layer.css';
+
 /* The three-font system (docs/DESIGN-SPEC.md §3) — exact-pinned @fontsource-variable deps. Bare
  * specifiers so consumer bundlers resolve them. */
 @import '@fontsource-variable/nunito-sans';
@@ -99,9 +109,8 @@
      authoring mistake at build time; this `!important` is the runtime backstop that makes it
      un-defeatable even when a violation slips through.
 
-     `--basalt-input-fz-floor` is the one knob: `createBasaltTheme(…, { inputs: 'desktop' })` has the
-     provider set it to 0px for an app that never runs on iOS Safari (a Tauri/desktop shell), where
-     the 16px floor is only visual weight. Default stays 16px. */
+     `--basalt-input-fz-floor` defaults to 16px; the theme `inputs` option that lowered it is gone
+     (V2-SPEC § 4), so an app that never runs on iOS Safari can set the var itself. */
   input,
   select,
   textarea {
@@ -269,3 +278,94 @@
     }
   }
 }
+
+/* View transitions (V2-SPEC § 5). React names the pseudo-elements and runs the UA cross-fade; under
+ * reduced motion we remove it, which React does not do itself. */
+@layer basalt {
+  @media (prefers-reduced-motion: reduce) {
+    ::view-transition-group(*),
+    ::view-transition-old(*),
+    ::view-transition-new(*) {
+      animation: none;
+    }
+  }
+}
+
+/* Route transitions: `createBasaltRouter` starts one per navigation and tags it with a type
+ * (`routeTransitionTypes`, provider/route-transition.ts). Only the content region moves — the shell
+ * chrome stays in the static `root` snapshot. The name is scoped to the route types so React's own
+ * transitions (the aside fold) never see a second named group. The animations sit in a
+ * `no-preference` query rather than relying on the `reduce` block above: its `::view-transition-*(*)`
+ * selectors are less specific than these, so a bare rule here would win and animate under reduce. */
+@layer basalt {
+  :root:active-view-transition-type(basalt-forward, basalt-back, basalt-sibling)
+    [data-basalt-scrollport] {
+    view-transition-name: basalt-main;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    :root:active-view-transition-type(basalt-forward, basalt-back, basalt-sibling) {
+      &::view-transition-old(root),
+      &::view-transition-new(root) {
+        animation: none;
+      }
+      &::view-transition-old(basalt-main) {
+        animation: basalt-route-out 120ms ease-out both;
+      }
+      &::view-transition-new(basalt-main) {
+        animation: basalt-route-in 180ms ease-out both;
+      }
+    }
+    :root:active-view-transition-type(basalt-forward) {
+      --basalt-route-shift: 8px;
+    }
+    :root:active-view-transition-type(basalt-back) {
+      --basalt-route-shift: -8px;
+    }
+    :root:active-view-transition-type(basalt-sibling) {
+      --basalt-route-shift: 0px;
+    }
+    /* Forward is toward the inline end, which is left in RTL. */
+    :root[dir='rtl']:active-view-transition-type(basalt-forward) {
+      --basalt-route-shift: -8px;
+    }
+    :root[dir='rtl']:active-view-transition-type(basalt-back) {
+      --basalt-route-shift: 8px;
+    }
+  }
+
+  @keyframes basalt-route-out {
+    to {
+      opacity: 0;
+      transform: translateX(calc(var(--basalt-route-shift, 0px) * -1));
+    }
+  }
+
+  @keyframes basalt-route-in {
+    from {
+      opacity: 0;
+      transform: translateX(var(--basalt-route-shift, 0px));
+    }
+  }
+}
+
+/* chart-engine:start — generated by scripts/gen-chart-css.ts from chartEngineCss() */
+@layer basalt {
+  :root {
+    --ts-chart-1: var(--vx-line);
+    --ts-chart-2: var(--vx-accent);
+    --ts-chart-3: var(--vx-fill-cyan);
+    --ts-chart-4: var(--vx-fill-orange);
+    --ts-chart-5: var(--vx-fill-grape);
+    --ts-chart-6: var(--vx-fill-lime);
+    --ts-chart-tooltip-background: var(--vx-tooltip-bg);
+    --ts-chart-tooltip-color: var(--vx-tooltip-text);
+    --ts-chart-tooltip-border: var(--vx-tooltip-border);
+    --ts-chart-tooltip-shadow: var(--vx-tooltip-shadow);
+    --ts-chart-tooltip-border-radius: var(--vx-radius-ctrl);
+    --ts-chart-crosshair-label-halo: var(--vx-surface-panel);
+    --ts-chart-crosshair-marker-fill: var(--vx-surface-panel);
+    --ts-chart-focus-fill: var(--vx-surface-panel);
+  }
+}
+/* chart-engine:end */