basalt-ui 1.27.0 → 1.29.0

package/src/surfaces.ts

@@ -48,18 +48,25 @@ 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',
+  'query-dual-import',
+  'query-fn-unwrap',
+  'deprecated-export',
+  'forms-field-key',
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
   'agent-resume-guard',
   'agent-no-raw-usechat',
   'ai-sdk-major',
+  'no-import-meta-env',
 ] as const
 
 /** One registered oxlint plugin rule id — the literal union of {@link PLUGIN_RULE_ID_LIST}. */
@@ -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
@@ -226,7 +233,7 @@ const MANTINE_BANS = [
 
 /**
  * The one hard source for the enforcement seam. Keys split into two kinds:
- * - JS-subpath keys (., ./charts, ./tokens, ./theme-lab, ./vite, ./guard, ./query, ./router-tanstack, ./forms, ./notifications, ./commands, ./data, ./data/table, ./data/virtual, ./agent, ./state, ./connectivity) — real package.json exports.
+ * - JS-subpath keys (., ./charts, ./tokens, ./theme-lab, ./vite, ./guard, ./router-tanstack, ./forms, ./notifications, ./commands, ./data/table, ./data/virtual, ./agent, ./state) — real package.json exports. `./query`, `./connectivity` and bare `./data` are dropped (C1) — their public surface is absorbed onto `.`.
  * - #-prefixed synthetic keys (#app) — the synthetic global app-wide ban layer. The #-prefix
  *   guarantees it is never mistaken for an export path.
  *
@@ -267,9 +274,25 @@ export const SURFACES = {
       'raw-scroll-container',
       'page-bar-budget',
       'shadow-basalt-export',
+      // The mount-order law, guarded as of 1.28.0 (F5) — same-file static ancestry, so `warn`.
+      // `deprecated-export` sits here too: the ledger it reads spans subpaths.
+      'provider-above-router',
+      'deprecated-export',
+      // `import.meta.env` is a Vite-ism that fails outside a Vite build (SSR/server code, Node
+      // scripts, tests) — process.env.NODE_ENV works everywhere basalt code runs. Repo-local,
+      // scoped to all of src/**, one surface required by coverage (C2 consolidation).
+      'no-import-meta-env',
+    ],
+    // agent/rules/basalt-mantine.md — stated, not guarded. The other law that stood here gained
+    // `provider-above-router` 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. (`duplicate-notifications-mount`, the
+    // other 1.28.0 mount-order rule, retired — `BasaltNotifications` no longer exists.)
+    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, useBreakpoint, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',
@@ -277,6 +300,7 @@ export const SURFACES = {
       'remend',
       'shiki',
       'beautiful-mermaid',
+      '@tanstack/react-router-devtools',
     ],
     forbiddenImports: [], // the no-charts/tokens-reexport invariant is comment-only today; Phase-4 plugin
   },
@@ -285,13 +309,7 @@ export const SURFACES = {
     layer: 'headless',
     rule: 'charts',
     skill: ['basalt-charts'],
-    guardKinds: [
-      'raw-hex',
-      'raw-color-fn',
-      'raw-visx-axis',
-      'unframed-chart',
-      'chart-missing-aria-label',
-    ],
+    guardKinds: ['raw-hex', 'raw-color-fn', 'raw-visx-axis', 'chart-missing-aria-label'],
     pluginRules: [
       'hand-rolled-plot',
       'chart-legend-literal',
@@ -358,7 +376,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'],
@@ -375,20 +393,15 @@ export const SURFACES = {
     // @visx/* ban dropped — `basalt/visx-boundary` now bans it universally outside charts.
     forbiddenImports: [...MANTINE_BANS],
   }, // 6th JS subpath
-  './query': {
-    kind: 'doctrine',
+  './format': {
+    kind: 'tooling',
     layer: 'headless',
-    rule: 'batteries',
-    skill: ['basalt-app'],
-    guardKinds: [],
-    pluginRules: [],
-    description: 'createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools',
-    optionalPeers: ['@tanstack/react-query-devtools'],
+    description:
+      'money/percent/integer/compact/deltaPct/duration/durationClock/clock/relativeTime/weekday/km/kcal — Intl-backed, Mantine-free, React-free formatting; charts/utils/format.ts re-exports fmtCompact/fmtPercent/fmtCurrency/fmtInt/fmtAxisDate/fmtTooltipDate from here (C5 consolidation, one implementation)',
     globs: {
       shipped: [],
-      repo: ['packages/basalt-ui/src/query/**'],
+      repo: ['packages/basalt-ui/src/format/**'],
     },
-    // @visx/* ban dropped — `basalt/visx-boundary` now bans it universally outside charts.
     forbiddenImports: [...MANTINE_BANS],
   },
   './router-tanstack': {
@@ -400,7 +413,7 @@ export const SURFACES = {
     // Law C10 — a nav link's `search` and a reader's `from` are both this bridge's contract.
     pluginRules: ['search-literal-link', 'use-search-from-literal'],
     description:
-      'TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; deprecated createSearchParamStore/createMultiSearchParamStore wrappers until 1.29.0)',
+      'TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; the deprecated createSearchParamStore/createMultiSearchParamStore wrappers were removed in 1.29.0, C1 consolidation)',
     optionalPeers: ['@tanstack/react-router'],
     globs: {
       shipped: [],
@@ -415,9 +428,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 deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), 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)',
     optionalPeers: ['@mantine/form'],
     forbiddenImports: [],
   },
@@ -445,18 +462,6 @@ export const SURFACES = {
     optionalPeers: ['@mantine/spotlight', '@mantine/modals', '@tanstack/react-hotkeys'],
     forbiddenImports: [],
   },
-  './data': {
-    kind: 'doctrine',
-    layer: 'mantine-coupled',
-    rule: 'batteries',
-    skill: ['basalt-design'],
-    guardKinds: [],
-    pluginRules: [],
-    description:
-      'Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in',
-    optionalPeers: ['@tanstack/react-table', '@tanstack/react-virtual'],
-    forbiddenImports: [],
-  },
   './data/table': {
     kind: 'doctrine',
     layer: 'mantine-coupled',
@@ -554,12 +559,15 @@ export const SURFACES = {
     // 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`, `control-size-literal` and
-    // `responsive-twin` all ship `error`; `control-outside-home` is the one grace entry left in
-    // `PLUGIN_RULE_GRACE`, re-dated to 1.28.0 against the wave-7 measurement (see its `why`).
-    // The budget rules live on `.` with `PageBar` itself.
+    // `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',
     ],
@@ -572,9 +580,26 @@ 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/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). 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: [],
+    // `@mantine/dates` is an optional peer basaltViteConfig pre-bundles the whole @mantine scope
+    // for — a consumer without the peer (linewatch) must never resolve it through this surface.
+    // Nothing under src/controls may import it, statically or lazily — repo-local only, same
+    // pattern as MANTINE_BANS above (a shipped ban would be redundant with peerDependenciesMeta).
+    globs: {
+      shipped: [],
+      repo: ['packages/basalt-ui/src/controls/**'],
+    },
+    forbiddenImports: [
+      v(
+        '@mantine/dates',
+        '@mantine/dates is an OPTIONAL peer (docs/CONTROLS-SPEC.md §3) — ./controls must resolve with no @mantine/dates installed. The one reach lives in src/controls-dates/, injected into range-filter.tsx’s customPicker seam.',
+      ),
+      vg(
+        '@mantine/dates/*',
+        '@mantine/dates is an OPTIONAL peer (docs/CONTROLS-SPEC.md §3) — ./controls must resolve with no @mantine/dates installed. The one reach lives in src/controls-dates/, injected into range-filter.tsx’s customPicker seam.',
+      ),
+    ],
   },
   './controls-dates': {
     kind: 'doctrine',
@@ -600,28 +625,15 @@ 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],
   },
 
-  './connectivity': {
-    kind: 'doctrine',
-    layer: 'mantine-coupled',
-    rule: 'mantine',
-    skill: ['basalt-app'],
-    guardKinds: [],
-    pluginRules: [],
-    description:
-      'ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator — auto-mounted by BasaltProvider',
-    optionalPeers: [],
-    forbiddenImports: [],
-  },
-
   // ── Non-JS published assets (ToolingSpec; not JS subpaths — check-coverage exempts these) ─────
   './styles.css': {
     kind: 'tooling',
@@ -660,7 +672,10 @@ export const SURFACES = {
     rule: 'batteries',
     skill: ['basalt-app'],
     guardKinds: [],
-    pluginRules: [],
+    // query-dual-import / query-fn-unwrap: reassigned here from the now-dropped `./query` surface
+    // (C1 consolidation — createBasaltQueryClient/unwrap/BasaltQueryDevtools are root barrel
+    // exports now, but their doctrine stays `batteries` — "use the shipped thing" — not `mantine`).
+    pluginRules: ['query-dual-import', 'query-fn-unwrap'],
     globs: {
       // Shipped is a catch-all (not just src/**+app/**) so consumer code under components/, lib/,
       // features/, etc. is also covered. The @visx/*-only-in-charts and Mantine-free charts/tokens

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,
@@ -103,6 +104,13 @@ export { useBasaltSpacing } from './use-basalt-spacing'
 // merge/precedence contract.
 export { CTL_THEME, CtlSlot, type CtlSlotProps } from './ctl-theme'
 
+// `ThemeToggle` moved into this directory (C1 consolidation, merging the former `theme-toggle/`
+// dir) but is deliberately NOT re-exported from this barrel: it imports `motion/react` eagerly,
+// and this file resolves from `./controls` (via `CtlSlot`) among others — re-exporting it here
+// would make `motion` a hard transitive peer of every consumer of this barrel, not just of
+// `ThemeToggle` itself. The root barrel (`src/index.ts`) imports it straight from
+// `./theme/theme-toggle`, unchanged from before the merge.
+
 // Typed `theme.other.basaltDerive` / `theme.other.basaltFonts` / `theme.other.basaltRadius` /
 // `theme.other.basaltDensity` reads (Mantine's `MantineThemeOther` ships an index signature, so
 // this merge is additive — no widening of the existing `[key: string]: any`). Set by
@@ -547,6 +555,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 +759,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 +793,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 +806,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 +980,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 +995,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 +1010,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 +1241,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 +1288,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 +1354,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 +1377,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 +1422,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 +1450,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.