basalt-ui 1.26.0 → 1.28.0

package/src/state/persisted-or-local.ts

@@ -0,0 +1,50 @@
+/**
+ * Internal — one disclosure flag that persists only when the caller named a key.
+ *
+ * `Section`'s collapse and `PageAside`'s fold are the same hook written twice: an optional
+ * `persistKey` decides whether the flag survives a reload, and both a `useState` and a
+ * `createPersistedState` hook are ALWAYS called so the hook order is stable across a key appearing
+ * or disappearing. Only the branch the caller asked for is returned, so an unpersisted surface
+ * never writes to storage.
+ *
+ * `scope` stays a parameter rather than being folded into `key`: it is what keeps
+ * `basalt:section:<key>` and `basalt:aside:<key>` from colliding when two surfaces on one page
+ * persist under the same name.
+ *
+ * Not exported from `../state` — this is an internal hook, not part of the `./state` surface.
+ */
+import { useMemo, useState } from 'react'
+import { createPersistedState } from './persisted'
+
+/** The key an unpersisted caller parks on — never read, because that branch returns local state. */
+const UNPERSISTED_KEY = '__local__'
+
+export function usePersistedOrLocal<T>({
+  scope,
+  persistKey,
+  initial,
+}: {
+  /** The storage namespace — `section`, `aside`. Prefixed onto `persistKey`. */
+  scope: string
+  /** Persist under `basalt:<scope>:<persistKey>`. Omitted → local state, nothing written. */
+  persistKey: string | undefined
+  /** First-render value, respected only while nothing is persisted. */
+  initial: T
+}): readonly [T, (next: T) => void] {
+  const [local, setLocal] = useState(initial)
+  // `createPersistedState` is a per-key module FACTORY, so it is memoized rather than called during
+  // render — the same reason `shell/index.tsx` memoizes its collapse store.
+  const usePersisted = useMemo(
+    () =>
+      createPersistedState<T>({
+        key: `${scope}:${persistKey ?? UNPERSISTED_KEY}`,
+        version: 1,
+        initial,
+      }),
+    [scope, persistKey, initial],
+  )
+  const [persisted, setPersisted] = usePersisted()
+
+  if (persistKey !== undefined) return [persisted, setPersisted] as const
+  return [local, setLocal] as const
+}

package/src/state/persisted.ts

@@ -32,6 +32,42 @@ export type PersistedStateOptions<T> = {
   readonly schema?: StandardSchemaV1<unknown, T>
 }
 
+/**
+ * Every subscriber for ONE storage key, shared by every `createPersistedState` instance over that
+ * key — plus the single `storage` event listener the key needs.
+ *
+ * Module-level rather than per-instance because two instances of the same key are ordinary, not a
+ * mistake: a page's `createSearchStore` and a widget's `createPersistedState` legitimately name the
+ * same key, and a consumer re-exporting a store from two modules ends up there by accident. With
+ * per-instance listener sets a write through one instance updated localStorage and notified only
+ * its own hooks, so the other instance's components kept rendering the stale value until something
+ * else re-rendered them — in the SAME tab, while the cross-tab path (the `storage` event) worked.
+ *
+ * The map is keyed by the NAMESPACED key and holds no window reference; a channel is created on
+ * first subscribe, which only happens in the browser (`subscribe` is never passed on the server).
+ */
+type KeyChannel = {
+  readonly listeners: Set<() => void>
+  handler: ((e: StorageEvent) => void) | null
+}
+
+const channels = new Map<string, KeyChannel>()
+
+/** Wake every hook on a key, whichever instance holds it. */
+function notify(storageKey: string): void {
+  const channel = channels.get(storageKey)
+  if (channel === undefined) return
+  for (const listener of channel.listeners) listener()
+}
+
+function channelFor(storageKey: string): KeyChannel {
+  const existing = channels.get(storageKey)
+  if (existing !== undefined) return existing
+  const created: KeyChannel = { listeners: new Set(), handler: null }
+  channels.set(storageKey, created)
+  return created
+}
+
 /** The envelope stored in localStorage: `{ v: number, value: unknown }`. */
 type Envelope = { v: number; value: unknown }
 
@@ -73,16 +109,19 @@ function parseStorage<T>(raw: string | null, opts: PersistedStateOptions<T>): T
   }
 }
 
-function writeStorage<T>(opts: PersistedStateOptions<T>, next: T): void {
-  const storageKey = `basalt:${opts.key}`
+function writeEnvelope(storageKey: string, version: number, value: unknown): void {
   try {
-    const envelope: Envelope = { v: opts.version, value: next }
+    const envelope: Envelope = { v: version, value }
     window.localStorage.setItem(storageKey, JSON.stringify(envelope))
   } catch {
     // Silently fail (storage full, private browsing, etc.)
   }
 }
 
+function writeStorage<T>(opts: PersistedStateOptions<T>, next: T): void {
+  writeEnvelope(`basalt:${opts.key}`, opts.version, next)
+}
+
 /**
  * Versioned, Standard-Schema-validated localStorage state via useSyncExternalStore (no zustand).
  * SSR-safe (getServerSnapshot returns `initial`). Cross-tab via the storage event.
@@ -100,32 +139,25 @@ export function createPersistedState<T>(
 ): () => readonly [T, (next: T) => void] {
   const storageKey = `basalt:${opts.key}`
 
-  // One Set of subscriber callbacks — mirrors notifications/store.ts single-listener-to-Set pattern.
-  const listeners = new Set<() => void>()
-
-  // ONE module-scoped 'storage' event listener per key, registered lazily on first subscriber.
-  // Removed when the last subscriber unsubscribes (cleanup semantics preserved).
-  let storageHandler: ((e: StorageEvent) => void) | null = null
-
   const subscribe = (cb: () => void): (() => void) => {
-    listeners.add(cb)
-
-    // Attach the shared window listener on the first subscriber.
-    if (storageHandler === null) {
-      storageHandler = (e: StorageEvent): void => {
-        if (e.key === storageKey) {
-          for (const listener of listeners) listener()
-        }
+    // The subscriber set is the KEY's, not this instance's — see `KeyChannel`.
+    const channel = channelFor(storageKey)
+    channel.listeners.add(cb)
+
+    // ONE 'storage' event listener per key, registered lazily on the first subscriber and removed
+    // when the last one leaves (cleanup semantics preserved).
+    if (channel.handler === null) {
+      channel.handler = (e: StorageEvent): void => {
+        if (e.key === storageKey) notify(storageKey)
       }
-      window.addEventListener('storage', storageHandler)
+      window.addEventListener('storage', channel.handler)
     }
 
     return () => {
-      listeners.delete(cb)
-      // Detach the shared window listener when the last subscriber unsubscribes.
-      if (listeners.size === 0 && storageHandler !== null) {
-        window.removeEventListener('storage', storageHandler)
-        storageHandler = null
+      channel.listeners.delete(cb)
+      if (channel.listeners.size === 0 && channel.handler !== null) {
+        window.removeEventListener('storage', channel.handler)
+        channel.handler = null
       }
     }
   }
@@ -158,8 +190,9 @@ export function createPersistedState<T>(
 
   const setState = (next: T): void => {
     writeStorage(opts, next)
-    // Notify in-tab listeners (the 'storage' event only fires in OTHER tabs)
-    for (const cb of listeners) cb()
+    // Notify every in-tab listener on this KEY — the 'storage' event fires in OTHER tabs only, and
+    // a second instance of the same key has its own hooks to wake.
+    notify(storageKey)
   }
 
   // Detect SSR once at creation time — the environment doesn't change between renders.
@@ -209,3 +242,20 @@ export function readPersistedValue(key: string, version?: number): unknown | nul
     return null
   }
 }
+
+/**
+ * Write a value under the namespaced key `basalt:<key>` in the same versioned envelope
+ * `createPersistedState` writes, and wake every hook on that key — the write half of
+ * `readPersistedValue`, and plain in the same way: no React required.
+ *
+ * The one call site is a store field's `clear()`, which has to DELETE its key from the store's
+ * record from an event handler, where the hook's setter is not in reach. Not exported from the
+ * `basalt-ui/state` barrel: the two store factories are the API, this is their seam.
+ *
+ * @internal
+ */
+export function writePersistedValue(key: string, version: number, value: unknown): void {
+  const storageKey = `basalt:${key}`
+  writeEnvelope(storageKey, version, value)
+  notify(storageKey)
+}

package/src/state.ts

@@ -30,6 +30,10 @@ export {
   type RangeValue,
   type RangeParams,
   type RangePresets,
+  type RangeWindow,
+  type RangeWindows,
+  type FieldFallback,
+  type FieldSetOptions,
   type EnumField,
   type MultiField,
   type RangeField,
@@ -42,11 +46,4 @@ export {
   type FieldHandle,
   type SearchValues,
   type StoredValues,
-  // @internal — the seam `createSearchStore` is built on, not a consumer API.
-  type FieldCodec,
-  type StoreEntry,
-  type StoreCoreOptions,
-  type StoreCore,
-  resolveFieldCodec,
-  createStoreCore,
 } from './state/fields'

package/src/surfaces.ts

@@ -48,12 +48,19 @@ export const PLUGIN_RULE_ID_LIST = [
   'raw-scroll-container',
   'hand-rolled-filter',
   'control-outside-home',
+  'bound-control-outside-home',
   'control-size-literal',
   'page-bar-budget',
   'in-body-page-title',
   'responsive-twin',
   'search-literal-link',
   'use-search-from-literal',
+  'provider-above-router',
+  'duplicate-notifications-mount',
+  'query-dual-import',
+  'query-fn-unwrap',
+  'deprecated-export',
+  'forms-field-key',
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
@@ -78,7 +85,7 @@ export type SkillName = 'basalt-app' | 'basalt-design' | 'basalt-charts'
  * @example
  * const l: Layer = 'headless'
  */
-export type Layer = 'mantine-coupled' | 'headless' | 'app-global' | 'non-js-asset'
+export type Layer = 'mantine-coupled' | 'headless' | 'app-global' | 'non-js-asset' | 'build-tooling'
 
 /**
  * A single import ban. `{ctx}` in the message is filled per target so shipped/repo wording
@@ -267,9 +274,22 @@ export const SURFACES = {
       'raw-scroll-container',
       'page-bar-budget',
       'shadow-basalt-export',
+      // The two mount-order laws, guarded as of 1.28.0 (F5) — both same-file static ancestry, so
+      // both `warn`. `deprecated-export` sits here too: the ledger it reads spans subpaths, and
+      // `BasaltProvider`'s three flattened connectivity props are most of it.
+      'provider-above-router',
+      'duplicate-notifications-mount',
+      'deprecated-export',
+    ],
+    // agent/rules/basalt-mantine.md — stated, not guarded. The other two laws that stood here
+    // gained `provider-above-router` / `duplicate-notifications-mount` at 1.28.0; this one has no
+    // AST form left to catch, because `cssVariablesResolver` is now `Omit`ted from the accepted
+    // prop type and a hand-built `createTheme` is a consumer's own call to make.
+    advisoryLaws: [
+      "no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs",
     ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',
@@ -358,7 +378,7 @@ export const SURFACES = {
   },
   './vite': {
     kind: 'tooling',
-    layer: 'mantine-coupled',
+    layer: 'build-tooling',
     description:
       'basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette',
     optionalPeers: ['vite-plugin-pwa'],
@@ -381,7 +401,10 @@ export const SURFACES = {
     rule: 'batteries',
     skill: ['basalt-app'],
     guardKinds: [],
-    pluginRules: [],
+    // Both laws this surface used to declare advisory (F5), guarded as of 1.28.0 and both `warn`:
+    // `query-dual-import`'s softer half reads intent ("this file is already a basalt file") and
+    // `query-fn-unwrap` is a text heuristic inside a syntactic range. See their grace entries.
+    pluginRules: ['query-dual-import', 'query-fn-unwrap'],
     description: 'createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools',
     optionalPeers: ['@tanstack/react-query-devtools'],
     globs: {
@@ -415,9 +438,13 @@ export const SURFACES = {
     rule: 'batteries',
     skill: ['basalt-design'],
     guardKinds: [],
-    pluginRules: [],
+    // The one change in the 1.28.0 forms minor a compiler cannot see: `inputProps` stopped
+    // returning `key`, and the pre-1.28.0 spread still type-checks, renders and validates — it
+    // only stops resetting. `warn` through the 1.30.0 grace because it fires on what every
+    // consumer ships today (`PLUGIN_RULE_GRACE`).
+    pluginRules: ['forms-field-key'],
     description:
-      'Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)',
+      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema; deprecated `field` alias for `inputProps` until the surface next changes)',
     optionalPeers: ['@mantine/form'],
     forbiddenImports: [],
   },
@@ -553,12 +580,16 @@ export const SURFACES = {
     // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
     // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
     guardKinds: ['raw-selection-control'],
-    // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter` ships `error` — "inside a
-    // slot" is structural; the other three are grace entries in `PLUGIN_RULE_GRACE` until 1.27.0.
-    // The budget rules live on `.` with `PageBar` itself.
+    // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
+    // `responsive-twin` all ship `error`; the two C1 placement rules are the grace entries in
+    // `PLUGIN_RULE_GRACE`, both promoting at 1.30.0 — `control-outside-home` re-dated against the
+    // wave-7 measurement, `bound-control-outside-home` new since 1.28.0 (ASIDE-SPEC G5: the basalt
+    // half of C1, where a bound control in a section body rendered as a stray pill). The budget
+    // rules live on `.` with `PageBar` itself.
     pluginRules: [
       'hand-rolled-filter',
       'control-outside-home',
+      'bound-control-outside-home',
       'control-size-literal',
       'responsive-twin',
     ],
@@ -571,7 +602,7 @@ export const SURFACES = {
       'C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy',
     ],
     description:
-      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
     optionalPeers: [],
     forbiddenImports: [],
   },
@@ -599,10 +630,10 @@ export const SURFACES = {
     optionalPeers: [],
     // Consumers import basalt-ui/state from node_modules (lint-ignored), so there is nothing to
     // enforce consumer-side, and a shipped **/state* glob would wrongly hit consumers' own
-    // Mantine-using state files. Enforce only basalt's own src/state.ts.
+    // Mantine-using state files. Enforce basalt's own barrel AND its implementation files.
     globs: {
       shipped: [],
-      repo: ['packages/basalt-ui/src/state.ts'],
+      repo: ['packages/basalt-ui/src/state.ts', 'packages/basalt-ui/src/state/**'],
     },
     // @visx/* ban dropped — `basalt/visx-boundary` now bans it universally outside charts.
     forbiddenImports: [...MANTINE_BANS],

package/src/theme/ctl-theme.tsx

@@ -78,6 +78,16 @@ export const CTL_THEME: MantineThemeOverride = {
   },
 }
 
+/**
+ * **`Slider` is deliberately NOT here, and `--slider-size-ctl` still is** (`theme/index.ts`). The
+ * tier's var set is what the size means, and `controls/slider-control.tsx` states `size="ctl"`
+ * itself the way every control on `./controls` does. Putting it in this map instead would widen
+ * `basalt/control-size-literal` — the rule is scoped to `CTL_THEME_TAGS`, ships at `error`, and a
+ * widened `error` rule lands its new form with no grace period at all (C16, `docs/CONTROLS-SPEC.md`
+ * §6). A `Slider` a consumer sizes by hand in a slot therefore keeps working; the one basalt draws
+ * is on the tier because it says so.
+ */
+
 /**
  * The `tier="widget"` slot theme — ActionIcon-ONLY, at the 24px `size="icon"` step
  * (`--ai-size-icon` → `--vx-space-control-height-widget`, `docs/CONTROLS-SPEC.md` §5).

package/src/theme/index.ts

@@ -19,6 +19,7 @@ import {
   Accordion,
   ActionIcon,
   Alert,
+  AppShell,
   Badge,
   Breadcrumbs,
   Button,
@@ -547,6 +548,24 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           },
         },
       }),
+      // Region seams (docs/DESIGN-SPEC.md §5, §8 #12): the ONE lever for every AppShell edge —
+      // Mantine declares `--app-shell-border-color` on the shell element per scheme, which beats
+      // an inherited `:root` value, so a theme-level `vars` override (merged into the root's
+      // inline style) wins. Sections keep their default `withBorder: true`; the color is this.
+      // `styles` would also land on the same root style attribute, just through Mantine's own
+      // `[key: string]: any` index rather than a typed field.
+      // Cast: `AppShellCssVariables` declares only `--app-shell-transition-duration` /
+      // `-timing-function`, yet Mantine's OWN AppShell.css sets `--app-shell-border-color` on the
+      // same root.
+      AppShell: AppShell.extend({
+        vars: () =>
+          ({ root: { '--app-shell-border-color': 'var(--vx-divider)' } }) as unknown as {
+            root: Record<
+              '--app-shell-transition-duration' | '--app-shell-transition-timing-function',
+              string | undefined
+            >
+          },
+      }),
       // "Ink earns its color" — a nav selection is UI state, not the identity accent on the LABEL.
       // The active item is a SELECTED ROW, not a raised control: the same ink-tint idiom as the
       // hover state (one step stronger, ink-9%), no panel fill and no `shadow-card` — a raised,
@@ -733,13 +752,32 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
         classNames: (_theme, props) =>
           (props.variant ?? 'filled') === 'filled' ? { label: controlsClasses.chipLabel } : {},
       }),
-      // Track = ink-6% tint, radius 7, 2px padding; active segment = panel bg + `shadow-ctrl`,
-      // radius 5. `--sc-radius`/`--sc-color` don't reach the root track background (Mantine
-      // hardcodes that to a raw gray step), so it's forced via `styles.root` same as Card/Paper.
-      // The active-only ink label color + weight can't live in the flat `styles.label` object
-      // (applies to every option regardless of state), so it's in segmented-control.module.css
+      // Track = ink-6% tint, radius 7, 2px padding; active segment = an ink-mixed panel fill +
+      // `shadow-ctrl`, radius 5. `--sc-radius`/`--sc-color` don't reach the root track background
+      // (Mantine hardcodes that to a raw gray step), so it's forced via `styles.root` same as
+      // Card/Paper. The active-only ink label color + weight can't live in the flat `styles.label`
+      // object (applies to every option regardless of state), so it's in segmented-control.module.css
       // instead — same pattern as NavLink's active-icon accent.
       //
+      // The indicator's fill is `color-mix(in srgb, var(--vx-ink) 12%, var(--vx-surface-panel))`,
+      // not a flat `--vx-surface-panel` — a flat panel fill is indistinguishable from the track's
+      // OWN parent on the one surface that IS `--vx-surface-panel` (the aside's `panel` filter
+      // surface, `docs/CONTROLS-SPEC.md` §3): the track (ink-6% over panel) and the indicator (panel,
+      // flat) then differ by 6% ink with no other cue, and `shadow-ctrl` alone (a bare
+      // `0 1px 2px` drop, no ring) reads as "barely there". This is NOT the `raised`-token doctrine
+      // in `tokens/palette.ts` (`SHADOW.raised`'s "a default control nested in a Card has no boundary
+      // but the drop — raise the drop, do not reintroduce an edge") — that doctrine is scoped to the
+      // shared Button/ActionIcon/Input depth token, whose fill is a real surface color a border would
+      // outline. The indicator's own fill has no such constraint, so a second ink-mix step (12%, double
+      // the track's) is the fix: it holds up on every surface the control mounts on, not only the
+      // panel-nested one.
+      //
+      // `.control`'s `min-width: 0` (`segmented-control.module.css`) is the other half of an even
+      // `fullWidth` split — Mantine's own `.control` ships `flex: 1` with no `min-width` override, so
+      // the initial `auto` floors every option at its min-content width and a `fullWidth` track splits
+      // UNEVENLY. The label already carries `overflow: hidden` + `text-overflow: ellipsis`, so a
+      // label that no longer fits its equal share truncates instead of forcing the column wide.
+      //
       // The track's padding is `SPACE_FIXED.segmentedTrackInset`, a plain literal — NOT a
       // `--vx-space-*` var — because it is density-EXEMPT: it is load-bearing for the nested-corner
       // law (`RADIUS.card === RADIUS_STEP.tight + segmentedTrackInset`, see that constant's doc in
@@ -748,7 +786,10 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // density.
       SegmentedControl: SegmentedControl.extend({
         defaultProps: { radius: radius.card },
-        classNames: { label: segmentedControlClasses.label },
+        classNames: {
+          label: segmentedControlClasses.label,
+          control: segmentedControlClasses.control,
+        },
         // `label` gets a `ctl`-only min-height (function-form `styles`, same `props.size === …` gate
         // as Button/ActionIcon/Input's `vars` overrides above) so a `size="ctl"` SegmentedControl
         // matches the ctl Button/Input box exactly instead of following its own fixed padding — see
@@ -758,21 +799,57 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           root: {
             backgroundColor: 'color-mix(in srgb, var(--vx-ink) 6%, transparent)',
             padding: `${SPACE_FIXED.segmentedTrackInset}px`,
+            // The OUTER safety net a `.control`'s own `min-width: 0` (`segmented-control.module.css`)
+            // cannot provide by itself: that rule only lets each SEGMENT shrink below its own label's
+            // content width so `fullWidth` can split evenly — it does nothing to stop the WHOLE TRACK
+            // from being squeezed by an ANCESTOR flex row with room to spare (a `Section`/`StatCard`
+            // header's `actions` slot), which silently clipped "Absolute" to "Absolut" with no
+            // ellipsis at all. `min-width: max-content` pins the root to the sum of its labels'
+            // natural widths — it now OVERFLOWS a too-narrow ancestor instead of shrinking into it,
+            // which is also what makes the overflow MEASURABLE (`panel-row.tsx`'s `useTrackFits`
+            // compares the root's rendered width against its parent's available space). Inside that
+            // floor, `fullWidth` with room to spare still splits its segments evenly exactly as
+            // before — the floor only ever raises the STARTING point flex-grow distributes surplus
+            // from, never removes the segments' own equal-share arithmetic.
+            minWidth: 'max-content',
           },
           indicator: {
-            backgroundColor: 'var(--vx-surface-panel)',
+            backgroundColor: 'color-mix(in srgb, var(--vx-ink) 12%, var(--vx-surface-panel))',
             boxShadow: 'var(--vx-shadow-ctrl)',
             borderRadius: 'var(--vx-radius-tight)',
           },
           // Conditionally spread the WHOLE key (never a present `label: undefined`) — the package
           // builds under `exactOptionalPropertyTypes`, which treats a key present-but-`undefined` as
           // a type error distinct from the key being absent.
+          //
+          // `width: '100%'` + `minWidth: 0` are load-bearing, not cosmetic: `inline-flex` is a
+          // shrink-to-fit box by default (like `inline-block`), so switching `.label` to it for
+          // vertical centering ALSO switched its width from "fills `.control`'s box" (a plain
+          // `display: block`'s default) to "sized to its own content" — which is invisible until
+          // `fullWidth` forces every `.control` to an EQUAL share (`segmented-control.module.css`'s
+          // `min-width: 0`): a label wider than that equal share then rendered at its own full
+          // content width, overflowing its column and getting hard-clipped by the track's own
+          // `overflow: hidden` instead of ellipsizing inside it ("Same period last year" cut off
+          // mid-word). `width: 100%` makes the inline-flex box fill `.control` again, and `minWidth:
+          // 0` is the same flex-item footgun `.control` itself needed — `.label` is ALSO a flex
+          // container's item once `fullWidth`'s `.root { display: flex }` applies, so it inherits an
+          // `auto` (content-based) minimum unless told otherwise.
           ...(props.size === 'ctl'
             ? {
                 label: {
                   display: 'inline-flex',
                   alignItems: 'center',
                   minHeight: `calc(var(--vx-space-control-height-ctl) * var(--mantine-scale) - ${2 * SPACE_FIXED.segmentedTrackInset}px)`,
+                  // `width: '100%'` only when `fullWidth` — it is what makes an EQUAL-SPLIT
+                  // segment's label fill its column instead of shrink-to-fit around its own text
+                  // (the "Same period last year" clipped-with-no-ellipsis case). A NON-`fullWidth`
+                  // track (a header's `actions` slot, two or three options) wants the opposite: its
+                  // label sized to its OWN content, so the root's `min-width: max-content` (below)
+                  // measures the label's true natural width rather than an equal 1/2 or 1/3 share
+                  // computed through `.control`'s `flex-basis: 0%` — forcing `width: 100%` there
+                  // too under-computed the shrink-to-fit root by a few px ("Absolute" clipped to
+                  // "Absolut" even with the floor in place).
+                  ...(props.fullWidth === true ? { width: '100%', minWidth: 0 } : {}),
                 },
               }
             : {}),
@@ -896,9 +973,13 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           },
         },
       }),
-      // Modal/Drawer: overlay surface + overlay shadow on the content. The header goes transparent —
-      // Mantine paints it `--mantine-color-body`, which read as a grey band over the overlay
-      // surface. Title = head font; close button = the ghost idiom (floating.module.css).
+      // Modal/Drawer: overlay surface + overlay shadow on the content, the SAME surface on the
+      // header. Mantine's header is `position: sticky` by default, painted `--mantine-color-body` —
+      // basalt used to drop that to `transparent`, which reads fine over a body that never scrolls
+      // under it but shows every scrolled row straight through the title once one does (the mobile
+      // filter sheet, the shell's "More" nav sheet). The header stays sticky; only its own
+      // background moves back to opaque, matching the content box it sits above rather than the page
+      // behind it. Title = head font; close button = the ghost idiom (floating.module.css).
       Modal: Modal.extend({
         defaultProps: { radius: radius.floating },
         classNames: { close: floatingClasses.closeButton },
@@ -907,7 +988,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
             backgroundColor: 'var(--vx-surface-overlay)',
             boxShadow: 'var(--vx-shadow-overlay)',
           },
-          header: { backgroundColor: 'transparent' },
+          header: { backgroundColor: 'var(--vx-surface-overlay)' },
           title: {
             fontFamily: 'var(--basalt-font-head)',
             fontWeight: 550,
@@ -922,7 +1003,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
             backgroundColor: 'var(--vx-surface-overlay)',
             boxShadow: 'var(--vx-shadow-overlay)',
           },
-          header: { backgroundColor: 'transparent' },
+          header: { backgroundColor: 'var(--vx-surface-overlay)' },
           title: {
             fontFamily: 'var(--basalt-font-head)',
             fontWeight: 550,
@@ -1153,13 +1234,30 @@ const CTL_INPUT_PADDING_Y = 4
 const CTL_SEGMENT_PADDING_Y = 2.5
 /** A `ctl` Combobox chevron. Mantine's own `xs` value; restated because it cannot be referenced. */
 const CTL_CHEVRON_SIZE = 14
+/**
+ * The `ctl` NumberInput's stepper column, in px — Mantine's own `xs` pair (`--ni-chevron-size-xs`,
+ * `--ni-right-section-width-xs`; `NumberInput.css`), restated for the same reason `CTL_CHEVRON_SIZE`
+ * is: `xs` is Mantine's own `--input-height-xs: 30px`, the ONE built-in size tier that already equals
+ * the `ctl` height, so its stepper column is the size a 30px NumberInput was always meant to carry.
+ * Both vars are load-bearing, not cosmetic — `NumberInput.mjs`'s `varsResolver` sets
+ * `--ni-chevron-size` via `getSize(size, 'ni-chevron-size')` (undeclared at `:root` for a custom
+ * size, so a `size="ctl"` NumberInput fell back to the property's initial value, and
+ * `.controls { max-width: calc(var(--ni-chevron-size) * 1.7) }` — `NumberInput.css:21` — resolved to
+ * an invalid `calc()` and dropped its `max-width` entirely, so the stacked chevrons stretched across
+ * the whole right section), and `rightSectionWidth` defaults to a raw
+ * `` `var(--ni-right-section-width-${size})` `` template (`NumberInput.mjs:412`) rather than a
+ * `getSize` call, so `ctl-tier-coverage.test.ts`'s scan cannot discover it — it is declared here
+ * because the CSS reads it, not because a scan requires it.
+ */
+const CTL_NUMBER_CHEVRON_SIZE = 10
+const CTL_NUMBER_RIGHT_SECTION_WIDTH = 17
 /**
  * The `ctl` tier's Radio/Checkbox indicator box, in px — 16, the SAME square
  * `theme/icon-slot.module.css` gives every icon in the tier, and for the same reason: a 13.5px
  * option label needs a mark it reads as part of the row rather than as a control beside it. Mantine's
  * default is `sm` (20px) and its `md` is 24px, both of which made the popover a column of controls
- * (`controls/filter-sheet.tsx`'s `SheetOptionList` doc records the sheet's version of the same
- * finding — there the fix was to remove the indicator entirely).
+ * (the sheet/panel forms found the same thing and went further — `docs/CONTROLS-SPEC.md` §3's
+ * `PanelChoice`/facet rows draw no Radio/Checkbox indicator at all, a hidden native input instead).
  */
 const CTL_TOGGLE_SIZE = 16
 /**
@@ -1183,6 +1281,14 @@ const CTL_SWITCH_THUMB_SIZE = 12
  *  the last tier whose label still fits an 18px track. */
 const CTL_SWITCH_TRACK_LABEL_SIZE = 5
 const CTL_SWITCH_TRACK_LABEL_PADDING = 2
+/**
+ * The `ctl` Slider's TRACK height, in px. The thumb is not a second number: Mantine derives it as
+ * `calc(var(--slider-size) * 2)` (`Slider.mjs`'s `varsResolver`), so 6 lands a 12px thumb — the same
+ * moving part the `ctl` Switch carries, which is what makes a row of inspector rows read as one
+ * family. Mantine's own `md` (8 → a 16px thumb) is the tier's whole icon box, and its `xs`
+ * (4 → 8px) is smaller than the tier's radio dot.
+ */
+const CTL_SLIDER_TRACK_SIZE = 6
 
 /**
  * The `size="ctl"` / `size="icon"` Mantine size-tier var sets (`docs/CONTROLS-SPEC.md` §5, C5) —
@@ -1241,6 +1347,8 @@ function ctlSizeVars(): Record<string, string> {
     '--sc-padding-ctl': `${pxRem(CTL_SEGMENT_PADDING_Y)} calc(${pxRem(CTL_PADDING_X)} * var(--mantine-scale))`,
     '--combobox-option-padding-ctl': `${pxRem(CTL_SEGMENT_PADDING_Y)} ${pxRem(CTL_PADDING_X)}`,
     '--combobox-chevron-size-ctl': pxRem(CTL_CHEVRON_SIZE),
+    '--ni-chevron-size-ctl': pxRem(CTL_NUMBER_CHEVRON_SIZE),
+    '--ni-right-section-width-ctl': `calc(${pxRem(CTL_NUMBER_RIGHT_SECTION_WIDTH)} * var(--mantine-scale))`,
     '--badge-height-ctl': ctlHeight,
     '--badge-padding-x-ctl': `calc(${pxRem(CTL_PADDING_X)} * var(--mantine-scale))`,
     '--badge-fz-ctl': `calc(${pxRem(VX.text.xs)} * var(--mantine-scale))`,
@@ -1262,6 +1370,10 @@ function ctlSizeVars(): Record<string, string> {
     '--switch-thumb-size-ctl': `calc(${pxRem(CTL_SWITCH_THUMB_SIZE)} * var(--mantine-scale))`,
     '--switch-label-font-size-ctl': pxRem(CTL_SWITCH_TRACK_LABEL_SIZE),
     '--switch-track-label-padding-ctl': pxRem(CTL_SWITCH_TRACK_LABEL_PADDING),
+    // Slider — the inspector row's control (`SliderControl`, `docs/ASIDE-SPEC.md` §1). One prefix
+    // only: `slider-size` is the track, and every other dimension (the thumb, the root's inline
+    // padding, the vertical hit box) is derived from it in `Slider.css`.
+    '--slider-size-ctl': `calc(${pxRem(CTL_SLIDER_TRACK_SIZE)} * var(--mantine-scale))`,
   }
 }
 
@@ -1303,7 +1415,8 @@ function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
       '--mantine-color-default-border': 'transparent',
       '--mantine-color-dimmed': `var(--vx-neutral, ${NEUTRAL.neutral.light})`, // secondary / muted text
       '--mantine-color-text': `var(--vx-ink, ${INK.ink.light})`, // primary body/heading text
-      '--app-shell-border-color': `var(--vx-surface-border, ${SURFACE.border.light})`,
+      // `--app-shell-border-color` is set by `components.AppShell.extend({ vars })` above — this
+      // entry was dead (an element-level declaration always beats an inherited `:root` value).
       // THE strict-surface lever. Mantine components do NOT chain border/surface colors through
       // `--mantine-color-default-*`; each hardcodes a RAW ramp step (`--mantine-color-gray-{2,3,4}`
       // on light) directly — which is why AppShell/Table/Input/Divider/Tabs/Popover/Accordion borders
@@ -1330,7 +1443,7 @@ function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
       '--mantine-color-default-border': 'transparent',
       '--mantine-color-dimmed': `var(--vx-neutral, ${NEUTRAL.neutral.dark})`,
       '--mantine-color-text': `var(--vx-ink, ${INK.ink.dark})`,
-      '--app-shell-border-color': `var(--vx-surface-border, ${SURFACE.border.dark})`,
+      // See the light block above — `--app-shell-border-color` is set by `AppShell.extend` now.
       // Dark components read `--mantine-color-dark-4` (border) raw. `buildDarkTuple` already sets
       // dark-4, but to a slightly lighter step than the hairline token, so layout borders read
       // marginally heavier than card borders. Pin dark-4 to the SAME "line" token for parity.