basalt-ui 1.27.0 → 1.28.0

package/dist/theme/index.js

@@ -2,6 +2,7 @@ import {
   Accordion,
   ActionIcon,
   Alert,
+  AppShell,
   Badge,
   Breadcrumbs,
   Button,
@@ -299,6 +300,18 @@ function buildTheme(data, options = {}) {
           }
         }
       }),
+      // 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)" } })
+      }),
       // "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,
@@ -475,13 +488,32 @@ function buildTheme(data, options = {}) {
       Chip: Chip.extend({
         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
@@ -490,7 +522,10 @@ function buildTheme(data, options = {}) {
       // 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
@@ -499,21 +534,57 @@ function buildTheme(data, options = {}) {
         styles: (_theme, props) => ({
           root: {
             backgroundColor: "color-mix(in srgb, var(--vx-ink) 6%, transparent)",
-            padding: `${SPACE_FIXED.segmentedTrackInset}px`
+            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)`
+              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 } : {}
             }
           } : {}
         })
@@ -635,9 +706,13 @@ function buildTheme(data, options = {}) {
           }
         }
       }),
-      // 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 },
@@ -646,7 +721,7 @@ function buildTheme(data, options = {}) {
             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,
@@ -661,7 +736,7 @@ function buildTheme(data, options = {}) {
             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,
@@ -812,6 +887,8 @@ const CTL_PADDING_X = 10;
 const CTL_INPUT_PADDING_Y = 4;
 const CTL_SEGMENT_PADDING_Y = 2.5;
 const CTL_CHEVRON_SIZE = 14;
+const CTL_NUMBER_CHEVRON_SIZE = 10;
+const CTL_NUMBER_RIGHT_SECTION_WIDTH = 17;
 const CTL_TOGGLE_SIZE = 16;
 const CTL_RADIO_DOT_SIZE = CTL_TOGGLE_SIZE * 0.4;
 const CTL_SWITCH_HEIGHT = 18;
@@ -819,6 +896,7 @@ const CTL_SWITCH_WIDTH = 30;
 const CTL_SWITCH_THUMB_SIZE = 12;
 const CTL_SWITCH_TRACK_LABEL_SIZE = 5;
 const CTL_SWITCH_TRACK_LABEL_PADDING = 2;
+const CTL_SLIDER_TRACK_SIZE = 6;
 function ctlSizeVars() {
   const ctlHeight = "calc(var(--vx-space-control-height-ctl) * var(--mantine-scale))";
   return {
@@ -835,6 +913,8 @@ function ctlSizeVars() {
     "--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))`,
@@ -855,7 +935,11 @@ function ctlSizeVars() {
     "--switch-width-ctl": `calc(${pxRem(CTL_SWITCH_WIDTH)} * var(--mantine-scale))`,
     "--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)
+    "--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))`
   };
 }
 function buildCssVariablesResolver(data) {
@@ -885,7 +969,8 @@ function buildCssVariablesResolver(data) {
       // 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
@@ -912,7 +997,7 @@ function buildCssVariablesResolver(data) {
       "--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.

package/dist/theme/nav-link.module.css

@@ -1,60 +1,71 @@
 /*
- * Active nav row = heavier weight over the ink tint `--nl-bg` carries (set in theme/index.ts,
- * applied unconditionally by Mantine's own `[data-active]` CSS). NO depth: an active row is a
- * SELECTED ROW, not a raised control — it deliberately reads as a stronger version of the hover
- * tint rather than as a button, so the row never competes with the real filled controls around it.
+ * Active nav row = an ACCENT-tinted fill plus heavier weight, so the row reads unambiguously as
+ * SELECTED rather than merely hovered (docs/DESIGN-SPEC.md §5). The fill was previously the ink
+ * tint `--nl-bg` carries (theme/index.ts) at 9% — visually indistinguishable from the 6% ink hover
+ * tint on a dark surface, which is what let a hovered row read as a second active item. NO depth:
+ * an active row is a SELECTED ROW, not a raised control.
+ *
+ * `[data-active]` is the ONLY style hook here — `use-nav.ts` already resolves exactly one winner
+ * per route and stamps `data-active` on it, so keying these selectors on `aria-current="page"` too
+ * only risked a second, looser router-native match repainting a row basalt's own model disagreed
+ * with. `aria-current` stays on the DOM (React Router/TanStack Router set it) for a11y; it is just
+ * not a CSS hook.
  *
  * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
- * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS
- * module never
- * sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]` there
- * throws a React warning), so the state selectors live here. React Router's NavLink marks the
- * active item via `aria-current` rather than the `active` prop's `data-active`, so both states are
- * matched.
+ * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS module
+ * never sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]`
+ * there throws a React warning), so the state selectors live here.
  */
-.root[data-active],
-.root[aria-current='page'] {
+.root[data-active] {
+  background-color: color-mix(in srgb, var(--vx-accent) 12%, transparent);
   font-weight: 600;
 }
 
+/* Active + hover — one step stronger than the resting active fill, so a pointer over the active row
+ * still reads as feedback rather than as a flat, unresponsive selection. */
+@media (hover: hover) {
+  .root[data-active]:hover {
+    background-color: color-mix(in srgb, var(--vx-accent) 16%, transparent);
+  }
+}
+
 /*
  * Active-icon accent: only the leftSection (the icon, `data-position="left"`) turns accent-colored
  * — the label stays ink (via `--nl-color`). Targets Mantine's own `data-position` attribute rather
  * than a custom class, so the rightSection (child-expand chevron) is untouched.
  */
-.root[data-active] [data-position='left'],
-.root[aria-current='page'] [data-position='left'] {
+.root[data-active] [data-position='left'] {
   color: var(--vx-accent);
 }
 
 /*
  * Inactive rows: muted text, faint icon (docs/DESIGN-SPEC.md §5 Sidebar — "inactive = muted text,
  * faint icon"). Mantine's own NavLink.css never sets a color on the base rule — it only colors the
- * label under `[data-active]`/`[aria-current='page']` — so an inactive row otherwise falls through
- * to the ambient `--mantine-color-text` (ink), same reasoning as the active-icon rule above.
+ * label under `[data-active]` — so an inactive row otherwise falls through to the ambient
+ * `--mantine-color-text` (ink), same reasoning as the active-icon rule above.
  */
-.root:not([data-active]):not([aria-current='page']) {
+.root:not([data-active]) {
   color: var(--vx-muted);
 }
 
-.root:not([data-active]):not([aria-current='page']) [data-position='left'] {
+.root:not([data-active]) [data-position='left'] {
   color: var(--vx-faint);
 }
 
 /*
- * Inactive hover — the ink-6% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5). Lives here (not
- * only in the shell module) so a consumer's `SidebarItem.Anchor` path gets the same hover;
- * Mantine's own
- * hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6), which this outranks on specificity.
- * Active rows keep their panel fill + `--nl-hover` untouched.
+ * Inactive hover — the ink-5% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5; dropped from 6%
+ * so it reads clearly below the active row's 12% accent fill instead of nearly matching its old 9%
+ * ink fill). Lives here (not only in the shell module) so a consumer's `SidebarItem.Anchor` path
+ * gets the same hover; Mantine's own hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6),
+ * which this outranks on specificity. Active rows keep their accent fill above, untouched here.
  */
 @media (hover: hover) {
-  .root:not([data-active]):not([aria-current='page']):hover {
-    background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
+  .root:not([data-active]):hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 5%, transparent);
     color: var(--vx-ink);
   }
 
-  .root:not([data-active]):not([aria-current='page']):hover [data-position='left'] {
+  .root:not([data-active]):hover [data-position='left'] {
     color: var(--vx-ink);
   }
 }

package/dist/theme/segmented-control.module.css

@@ -13,6 +13,28 @@
   font-weight: 600;
 }
 
+/*
+ * Mantine's own `.control` ships `flex: 1` with no `min-width` override, so its initial value
+ * (`auto`) floors every option at its min-content width — a `fullWidth` track therefore still
+ * splits UNEVENLY (a long label's column stays wider than its siblings) instead of dividing the
+ * track equally, which is what `fullWidth` promises. `min-width: 0` lets flex-basis (not content)
+ * decide each column's share; Mantine's own `.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.
+ *
+ * Scoped to `[data-full-width]` — the same attribute Mantine's own CSS keys `display: flex` off
+ * (`SegmentedControl.css`) — because a bare `.control { min-width: 0 }` regressed the OTHER shape:
+ * a non-`fullWidth` track (two or three options in a `Section`/`StatCard` header's `actions` slot)
+ * is shrink-to-fit by design, and stripping every segment's min-content floor let a squeezing
+ * ancestor collapse it below its own labels' natural width with no ellipsis at all ("Absolute"
+ * clipped to "Absolut"). Outside `fullWidth`, `.control` keeps the browser's own `min-width: auto`
+ * — the ordinary flex-item protection — and the root's own `min-width: max-content`
+ * (`theme/index.ts`'s `SegmentedControl.extend`) is the backstop above it.
+ */
+[data-full-width] .control {
+  min-width: 0;
+}
+
 /*
  * Numeric segment labels read mono `VX.text.xs` (`docs/CONTROLS-SPEC.md` §3 last paragraph, C7) —
  * a consumer opts in with a bare `data-numeric` attribute on the `SegmentedControl` itself (an

package/dist/theme/segmented-control.module.css.d.ts

@@ -4,5 +4,6 @@
  */
 declare const classes: {
   readonly label: string
+  readonly control: string
 }
 export default classes

package/dist/theme-lab/boot.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Theme-lab boot — the production-entry half of the theme lab, split out of `index.tsx` on purpose.
+ *
+ * `applyOverrides(loadOverrides())` is called at PRODUCTION module scope by every consumer's
+ * `main.tsx` (see `README.md`'s "Wire the runtime" section) to re-apply a persisted tuning session
+ * on load — but `index.tsx` also hosts `ThemeLabControls` (11 `@mantine/core` imports) and
+ * re-exports `DeriveControls`, which is DEV-tool UI. None of the three boot functions should assume
+ * a browser: `readVar` in particular used to append a probe `<span>` to `document.body` with no
+ * guard at all, which threw outright under SSR.
+ *
+ * What is actually enforced (`boot.test.ts`): every DOM-touching export is a no-op / empty-result
+ * with no `document`, never a throw, and this module statically imports nothing from `@mantine/*` or
+ * React. There is no `basalt-ui/theme-lab/boot` subpath and no dist-layering check on it — a prod
+ * entry still imports `basalt-ui/theme-lab` and gets `index.tsx`, which re-exports this module
+ * alongside `ThemeLabControls`. Whether a bundler actually tree-shakes the unused Mantine UI back out
+ * of a prod build that only calls `applyOverrides`/`loadOverrides`/`readVar` is bundler-dependent,
+ * not something this split guarantees on its own.
+ */
+export type ColorTunable = {
+    var: string;
+    label: string;
+};
+export type ColorGroup = {
+    title: string;
+    items: ColorTunable[];
+};
+export type Overrides = Record<string, string>;
+/** Gradient strength knobs (percent values, theme-independent). */
+export declare const AREA_TOP_VAR = "--vx-area-top";
+export declare const AREA_BOTTOM_VAR = "--vx-area-bottom";
+/**
+ * Structural `--vx-*` vars worth tuning by eye — the ones `tokens/palette.ts` hand-authors and
+ * that never move with the derive config (ColorInput is hex-only, so `rgba()`/`color-mix()` chrome
+ * vars like `--vx-axis` / `--vx-grid` are intentionally omitted regardless).
+ *
+ * Identity/color tuning lives exclusively in `DeriveControls` (one accent seed + bounded knobs,
+ * `tokens/derive.ts`) — every `--vx-*` var GENERATED from that config (the accent family, the 12
+ * categorical fills, the ink ramp, most of the surface stops, the `good`/`warn`/`bad`
+ * status/semantic hues) has been pruned from here on purpose: hand-tuning a hex the derive engine
+ * regenerates on every render is a dead knob. What remains is a low-level inspector for the
+ * genuinely NON-derived structural tokens only.
+ *
+ * Generic by design: argo's domain series (Health / Strength / Walking) are NOT shipped — a
+ * consumer passes its own series groups to `ThemeLabControls` via the `groups` prop.
+ */
+export declare const COLOR_GROUPS: ColorGroup[];
+/** SSR-safe: with no `document` (and so no `localStorage`), returns an empty overrides map. */
+export declare function loadOverrides(): Overrides;
+export declare function saveOverrides(o: Overrides): void;
+/**
+ * Clears every managed var, then re-applies the given overrides. The single mutation point.
+ * SSR-safe: with no `document`, this is a no-op.
+ */
+export declare function applyOverrides(o: Overrides): void;
+/**
+ * Current value of a color var as a hex `ColorInput` can display (reflects any active override or
+ * the stylesheet default). SSR-safe: with no `document`, returns `''`.
+ *
+ * Reading the custom property directly is not enough: an UNREGISTERED custom property computes to
+ * its literal source text, so a `color-mix()`-derived token (every surface — see `SURFACE` in
+ * tokens/palette.ts) comes back as the string `"color-mix(in srgb, #3f3f46 50%, #27272a)"`, which
+ * ColorInput cannot parse — it renders an empty swatch. Painting the var onto a probe element and
+ * reading a real COLOR property instead forces the browser to resolve it to an rgb triple.
+ */
+export declare function readVar(name: string): string;
+//# sourceMappingURL=boot.d.ts.map

package/dist/theme-lab/boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../src/theme-lab/boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AACzD,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CAAA;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE9C,mEAAmE;AACnE,eAAO,MAAM,YAAY,kBAAkB,CAAA;AAC3C,eAAO,MAAM,eAAe,qBAAqB,CAAA;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EA2BpC,CAAA;AAOD,+FAA+F;AAC/F,wBAAgB,aAAa,IAAI,SAAS,CAQzC;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAOhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAOjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB5C"}

package/dist/theme-lab/boot.js

@@ -0,0 +1,82 @@
+const AREA_TOP_VAR = "--vx-area-top";
+const AREA_BOTTOM_VAR = "--vx-area-bottom";
+const COLOR_GROUPS = [
+  {
+    // `excellent` (top-of-scale grade) and `neutral` (mid-scale) keep their own hand-authored BP
+    // families — unlike `good`/`warn`/`bad`, which are the SAME derived hues as `Semantic` and are
+    // not independently tunable here.
+    title: "Status (chart-only)",
+    items: [
+      { var: "--vx-status-excellent", label: "Excellent" },
+      { var: "--vx-status-neutral", label: "Neutral" }
+    ]
+  },
+  {
+    // Chart line/dot chrome — hand-authored off the zinc `BP.gray`/`BP.white`/`BP.darkGray`
+    // families, independent of the derive config.
+    title: "Chart chrome",
+    items: [
+      { var: "--vx-line", label: "Line" },
+      { var: "--vx-line2", label: "Line 2" },
+      { var: "--vx-dot-stroke", label: "Dot stroke" }
+    ]
+  },
+  {
+    // The floating-layer surface (menus, popovers, tooltips, modals, drawers) — the one SURFACE
+    // stop the derive engine has no law for, so it stays a hand-picked hex/color-mix().
+    title: "Surface",
+    items: [{ var: "--vx-surface-overlay", label: "Overlay" }]
+  }
+];
+const COLOR_VARS = COLOR_GROUPS.flatMap((g) => g.items.map((i) => i.var));
+const MANAGED_VARS = [...COLOR_VARS, AREA_TOP_VAR, AREA_BOTTOM_VAR];
+const KEY = "basalt-theme-lab";
+function loadOverrides() {
+  if (typeof document === "undefined") return {};
+  try {
+    const raw = localStorage.getItem(KEY);
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+function saveOverrides(o) {
+  if (typeof document === "undefined") return;
+  try {
+    localStorage.setItem(KEY, JSON.stringify(o));
+  } catch {
+  }
+}
+function applyOverrides(o) {
+  if (typeof document === "undefined") return;
+  const el = document.documentElement;
+  for (const v of MANAGED_VARS) el.style.removeProperty(v);
+  for (const [k, val] of Object.entries(o)) {
+    if (val) el.style.setProperty(k, val);
+  }
+}
+function readVar(name) {
+  if (typeof document === "undefined") return "";
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+  if (raw.startsWith("#")) return raw;
+  if (!raw) return "";
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = `var(${name})`;
+  document.body.appendChild(probe);
+  const computed = getComputedStyle(probe).color;
+  probe.remove();
+  const channels = computed.match(/[\d.]+/g);
+  if (!channels || channels.length < 3) return raw;
+  const hex = channels.slice(0, 3).map((c) => Math.round(Number(c)).toString(16).padStart(2, "0")).join("");
+  return `#${hex}`;
+}
+export {
+  AREA_BOTTOM_VAR,
+  AREA_TOP_VAR,
+  COLOR_GROUPS,
+  applyOverrides,
+  loadOverrides,
+  readVar,
+  saveOverrides
+};

package/dist/theme-lab/index.d.ts

@@ -1,49 +1,10 @@
 import type { ReactNode } from 'react';
+import { applyOverrides, AREA_BOTTOM_VAR, AREA_TOP_VAR, COLOR_GROUPS, loadOverrides, readVar, saveOverrides } from './boot.js';
+import type { ColorGroup, ColorTunable, Overrides } from './boot.js';
 export { DeriveControls } from './derive-controls.js';
 export type { DeriveControlsProps } from './derive-controls.js';
-export type ColorTunable = {
-    var: string;
-    label: string;
-};
-export type ColorGroup = {
-    title: string;
-    items: ColorTunable[];
-};
-export type Overrides = Record<string, string>;
-/** Gradient strength knobs (percent values, theme-independent). */
-export declare const AREA_TOP_VAR = "--vx-area-top";
-export declare const AREA_BOTTOM_VAR = "--vx-area-bottom";
-/**
- * Structural `--vx-*` vars worth tuning by eye — the ones `tokens/palette.ts` hand-authors and
- * that never move with the derive config (ColorInput is hex-only, so `rgba()`/`color-mix()` chrome
- * vars like `--vx-axis` / `--vx-grid` are intentionally omitted regardless).
- *
- * Identity/color tuning lives exclusively in {@link DeriveControls} (one accent seed + bounded
- * knobs, `tokens/derive.ts`) — every `--vx-*` var GENERATED from that config (the accent family,
- * the 12 categorical fills, the ink ramp, most of the surface stops, the `good`/`warn`/`bad`
- * status/semantic hues) has been pruned from here on purpose: hand-tuning a hex the derive engine
- * regenerates on every render is a dead knob. What remains is a low-level inspector for the
- * genuinely NON-derived structural tokens only.
- *
- * Generic by design: argo's domain series (Health / Strength / Walking) are NOT shipped — a
- * consumer passes its own series groups to {@link ThemeLabControls} via the `groups` prop.
- */
-export declare const COLOR_GROUPS: ColorGroup[];
-export declare function loadOverrides(): Overrides;
-export declare function saveOverrides(o: Overrides): void;
-/** Clears every managed var, then re-applies the given overrides. The single mutation point. */
-export declare function applyOverrides(o: Overrides): void;
-/**
- * Current value of a color var as a hex `ColorInput` can display (reflects any active override or
- * the stylesheet default).
- *
- * Reading the custom property directly is not enough: an UNREGISTERED custom property computes to
- * its literal source text, so a `color-mix()`-derived token (every surface — see `SURFACE` in
- * tokens/palette.ts) comes back as the string `"color-mix(in srgb, #3f3f46 50%, #27272a)"`, which
- * ColorInput cannot parse — it renders an empty swatch. Painting the var onto a probe element and
- * reading a real COLOR property instead forces the browser to resolve it to an rgb triple.
- */
-export declare function readVar(name: string): string;
+export { applyOverrides, AREA_BOTTOM_VAR, AREA_TOP_VAR, COLOR_GROUPS, loadOverrides, readVar, saveOverrides, };
+export type { ColorGroup, ColorTunable, Overrides };
 export type ThemeLabControlsProps = {
     /** Color groups to render as tunable swatches. Defaults to the framework {@link COLOR_GROUPS}. */
     groups?: ColorGroup[];

package/dist/theme-lab/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme-lab/index.tsx"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AACzD,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CAAA;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE9C,mEAAmE;AACnE,eAAO,MAAM,YAAY,kBAAkB,CAAA;AAC3C,eAAO,MAAM,eAAe,qBAAqB,CAAA;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EA2BpC,CAAA;AAOD,wBAAgB,aAAa,IAAI,SAAS,CAOzC;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAMhD;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAMjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB5C;AAsBD,MAAM,MAAM,qBAAqB,GAAG;IAClC,kGAAkG;IAClG,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,yFAAyF;IACzF,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAqB,EACrB,MAAM,EACN,QAAQ,EACR,SAAS,GACV,EAAE,qBAAqB,+BA8GvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme-lab/index.tsx"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EACL,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,OAAO,EACP,aAAa,EACd,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAI5D,OAAO,EACL,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,OAAO,EACP,aAAa,GACd,CAAA;AACD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,CAAA;AAsBnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,kGAAkG;IAClG,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,yFAAyF;IACzF,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAqB,EACrB,MAAM,EACN,QAAQ,EACR,SAAS,GACV,EAAE,qBAAqB,+BA8GvB"}