basalt-ui 1.32.1 → 1.33.0

package/src/guard/index.ts

@@ -1,10 +1,11 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 27 violation kinds.
+ * GUARD_RULES: the closed registry of all 28 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
+import { BASALT_VX_NAMES } from './vx-names'
 
 export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
@@ -286,6 +287,62 @@ const INLINE_FONT_SIZE =
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/
 
+/**
+ * A `var(--vx-*)` REFERENCE with a literal name. The name must end on an alphanumeric and must not
+ * run into a `${…}` interpolation, so `var(--vx-fill-${hue})` — a name computed at runtime — never
+ * matches a truncated `--vx-fill`.
+ */
+const VX_VAR_REF = /var\(\s*(--vx-[A-Za-z0-9-]*[A-Za-z0-9])(?![A-Za-z0-9-]|\$\{)/g
+
+/**
+ * A `--vx-*` name the file DECLARES — a consumer's own custom property, never unknown. Only a real
+ * declaration position counts, because the set is file-wide and one false hit silences every
+ * finding for that name in the file:
+ *
+ * - a CSS declaration (`--vx-x: …`, in a stylesheet or in CSS text inside a template literal),
+ *   directly after a line start, `{` or `;`;
+ * - a quoted style-object key (`{ '--vx-x': … }`), directly after `{` or `,` — but not a TS
+ *   member key (`'--vx-x'?: …`, or one typed `string`/`number`);
+ * - `setProperty('--vx-x', …)`.
+ *
+ * A quoted name used as an EXPRESSION — a ternary arm, a `case` label, an argument — is a reference,
+ * not a declaration, and never matches.
+ */
+const VX_LOCAL_DECLARATION =
+  /(?:^|[{;])\s*(--vx-[A-Za-z0-9-]*[A-Za-z0-9])\s*:|[{,]\s*(['"])(--vx-[A-Za-z0-9-]*[A-Za-z0-9])\2\s*:(?!\s*(?:string|number)\b)|\bsetProperty\(\s*['"](--vx-[A-Za-z0-9-]*[A-Za-z0-9])['"]/gm
+
+/**
+ * `--vx-*` names basalt once emitted and no longer does, with the replacement MIGRATING names
+ * (`null`: deleted with no replacement). Hand-kept on purpose: it is history, it only grows, and
+ * `vx-names.test.ts` pins that none of these is live and every replacement is.
+ */
+const REMOVED_VX_NAMES: Readonly<Record<string, string | null>> = {
+  '--vx-space-touch-target': '--vx-hit',
+  '--vx-space-touch-control-height': '--vx-hit',
+  '--vx-space-app-header-mobile-actions-height': '--vx-space-sticky-header-clearance',
+  '--vx-space-sticky-header-clearance-mobile': '--vx-space-sticky-header-clearance',
+  '--vx-space-sidebar-brand-inset-top': null,
+}
+
+const KNOWN_VX_NAMES: ReadonlySet<string> = new Set(BASALT_VX_NAMES)
+
+/**
+ * The bare family roots basalt never emits — `--vx-space`, `--vx-surface`, `--vx-status`, … — derived
+ * from the `--vx-<family>-` prefixes of the emitted names, minus any root that is itself a token
+ * (`--vx-hit`, `--vx-accent`). Nobody emits one: basalt only ever writes `<root>-<key>`, and so does
+ * `groupTokens`. It is the one shape of unknown name basalt can judge WITHOUT seeing the consumer's
+ * palette.
+ *
+ * An unknown name INSIDE a family (`--vx-surface-2`) is deliberately not judged. `groupTokens(name,
+ * map)` takes any `name`, so `--vx-surface-custom` may be a consumer group declared in a file this
+ * scan cannot see, and a per-file guard has no honest way to tell that from a typo.
+ */
+const BASALT_VX_FAMILY_ROOTS: ReadonlySet<string> = new Set(
+  BASALT_VX_NAMES.map((n) => /^(--vx-[A-Za-z0-9]+)-/.exec(n)?.[1]).filter(
+    (root): root is string => root !== undefined && !KNOWN_VX_NAMES.has(root),
+  ),
+)
+
 // Raw Mantine ramp step used for surface color — gray/dark + a step digit.
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g
 
@@ -861,38 +918,14 @@ export type GraceEntry = { since: string; promote: string; why: string }
  * }
  */
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
-  'raw-selection-control': {
-    since: '1.26.0',
-    promote: '1.33.0',
+  'unknown-vx-token': {
+    since: '1.33.0',
+    promote: '1.34.0',
     why:
-      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
-      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
-      'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
-      'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
-      'reading in the guard, and the reason this one lands warn rather than error even though its ' +
-      'law is settled. ONE LAW, TWO LANES, ONE PROMOTION: it moves with its AST twin, ' +
-      '`basalt/control-outside-home`, whose PLUGIN_RULE_GRACE entry carries the full argument and ' +
-      'the measurement, and it must never be promoted or extended alone — a consumer waiving one ' +
-      'spelling and failing the other is the exact confusion `WAIVER_ID_ALIASES` exists to close. ' +
-      'RE-MEASURED 2026-09-09 across the whole fleet on 1.29.2: 29 AST-lane incumbents in five ' +
-      "repos, plus three of basalt's own (data-table, notifications/center, theme-lab). Extended " +
-      'to 1.31.0 because 1.30.0 is the FIRST release in which either lane names a home a ' +
-      'provider-only consumer can reach — every home both messages listed was a shell slot, and ' +
-      'the shell-less `PageBar` sentence ships in this minor. Promoting in the same minor that ' +
-      'makes a rule satisfiable gives nobody a window to act. 1.31.0 is when the 29 are ' +
-      're-measured against that number.',
-  },
-  'raw-media-query': {
-    since: '1.31.0',
-    promote: '1.33.0',
-    why:
-      "The CSS-text twin of the oxlint plugin's `basalt/raw-breakpoint` — ONE LAW, TWO LANES, ONE " +
-      'PROMOTION, so it moves with that rule and never alone (`configs/oxlint-plugin.test.ts` › twin lanes share one promotion pins the pair). New in ' +
-      'the wave-11 responsive/touch guards; reaching CSS is a NEW file type for this check, same ' +
-      "reasoning as `css-raw-surface`, with incumbents in basalt's own tree at ship time, so it " +
-      'shipped warn. Extended 1.32.0 -> 1.33.0 with its twin: 1.31.0 named ' +
-      'no reachable container primitive, and 1.32.0 is the first minor that documents one ' +
-      '(`CONTAINER_CLASSES` + the declared `@container` names, MIGRATING § `basalt/raw-breakpoint`).',
+      'New kind (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
+      '`var(--vx-space-touch-target)` that nothing reported. A new kind rejects code every previous ' +
+      'release accepted, so it lands warn for one minor. Measured at ship time: argo, linewatch, rb, ' +
+      'rollhook, obsidian, weatherorb, image-share, email-gateway, image-gen 0.',
   },
 }
 
@@ -1132,6 +1165,13 @@ export const WAIVER_ID_ALIASES: Readonly<Record<string, readonly string[]>> = {
   'raw-selection-control': ['control-outside-home'],
 }
 
+/**
+ * The ids that are a guard kind AND an oxlint plugin rule — one law, two lanes, one annotation.
+ * {@link PLUGIN_RULE_IDS} leaves them out by design, so `--audit-allows` would otherwise never ask
+ * oxlint about them. `waiver-audit.test.ts` pins this against the plugin's own rule table.
+ */
+const DUAL_LANE_IDS: ReadonlySet<string> = new Set(['in-body-page-title'])
+
 /** The shortest string accepted as a written reason — enough to exclude a stray separator. */
 const MIN_ALLOW_REASON_LENGTH = 4
 
@@ -1973,7 +2013,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 27 guard kinds. The triad test asserts
+ * The closed registry of all 28 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -2215,6 +2255,17 @@ export const GUARD_RULES = {
     appliesTo: (relPath) => relPath.endsWith('.css'),
     message: `Raw viewport/container breakpoint in CSS — a width @media belongs to shell/** against SIZE_CLASSES (useSizeClass() is the JS seam); an @container name must be one of ${[...DECLARED_CONTAINER_NAMES].join(' / ')}, and a basalt-card or unnamed @container query must sit at a boundary in ${[...CONTAINER_CLASS_LITERALS_PX].map((px) => `${px}px`).join(' / ')} (the other declared names have no numeric table yet, so their literals are not judged); and a pointer query other than (pointer: coarse) or (pointer: fine) has no framework meaning. Same law the oxlint plugin enforces as basalt/raw-breakpoint over JSX; this is the CSS half.`,
   },
+  'unknown-vx-token': {
+    kind: 'unknown-vx-token',
+    pattern: VX_VAR_REF, // handled inline (removed map + family roots); entry keeps the registry complete
+    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Two shapes are judged, the only two basalt can judge without seeing your palette: a REMOVED name — ${Object.entries(
+      REMOVED_VX_NAMES,
+    )
+      .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)
+      .join(
+        '; ',
+      )} — and a bare family root nothing emits (${[...BASALT_VX_FAMILY_ROOTS].join(', ')}): name the token under it from basalt-ui/tokens.css. Any other unknown name is never judged, because defineSeries/groupTokens may declare it in a file this scan cannot see.`,
+  },
 } as const satisfies Record<GuardKind, GuardRule>
 
 /**
@@ -2389,6 +2440,22 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     [...codeText.matchAll(STYLE_BOUND_IDENTIFIER)].map((m) => m[1] ?? ''),
   )
 
+  /** `--vx-*` names this file declares — its own custom properties, which `unknown-vx-token` skips. */
+  const locallyDeclaredVx = new Set(
+    [...codeText.matchAll(VX_LOCAL_DECLARATION)].map((m) => m[1] ?? m[3] ?? m[4] ?? ''),
+  )
+
+  // unknown-vx-token: a removed name, or a bare family root nothing emits — see the roots' doc.
+  // Scanned over the whole comment-stripped text rather than per line, so a formatter-wrapped
+  // `var(\n  --vx-x\n)` is seen; the finding lands on the line the NAME is on.
+  for (const m of codeText.matchAll(VX_VAR_REF)) {
+    const name = m[1] ?? ''
+    if (locallyDeclaredVx.has(name)) continue
+    if (!Object.hasOwn(REMOVED_VX_NAMES, name) && !BASALT_VX_FAMILY_ROOTS.has(name)) continue
+    const at = (m.index ?? 0) + m[0].length - name.length
+    push('unknown-vx-token', lineStarts.findLastIndex((start) => start <= at) + 1, name)
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const line = codeLines[i] ?? ''
 
@@ -2793,6 +2860,15 @@ export type AllowAnnotationSite = {
   readonly guardKinds: readonly GuardKind[]
   /** The subset of `rules` the oxlint plugin owns — outside `checkSource`'s reach. */
   readonly pluginRules: readonly string[]
+  /**
+   * Every id an `oxlint` run can prove live: `pluginRules`, plus a guard kind that is ALSO a plugin
+   * rule (`in-body-page-title`) or aliases one ({@link WAIVER_ID_ALIASES}). A waiver is live if
+   * EITHER lane still needs it — judging only `pluginRules` called rb's live `in-body-page-title`
+   * waivers dead, and deleting them made oxlint exit 1. A bare LINE-scope annotation covers every
+   * plugin rule (the plugin's `allowCovers`), so it lists all of them; a bare file-scope one waives
+   * nothing in either lane and lists none.
+   */
+  readonly oxlintRules: readonly string[]
   /** Words that occupied the id slot but name no rule. Their presence makes the parse fail closed. */
   readonly unknownRules: readonly string[]
   /** A written reason follows the ids. */
@@ -2831,19 +2907,33 @@ export function findAllowAnnotations(
     cfg.allowComment,
     syntax,
   )
-  return declared.map(({ line, annotation }) => ({
-    line,
-    scope: annotation.scope,
-    rules: [...annotation.rules],
-    guardKinds: annotation.rules.filter((id): id is GuardKind => Object.hasOwn(GUARD_RULES, id)),
-    pluginRules: annotation.rules.filter(
-      (id) => !Object.hasOwn(GUARD_RULES, id) && PLUGIN_RULE_IDS.has(id),
-    ),
-    unknownRules: [...annotation.unknownRules],
-    hasReason: annotation.hasReason,
-    bare: annotation.rules.length === 0 && annotation.unknownRules.length === 0,
-    text: lines[line - 1] ?? '',
-  }))
+  const everyOxlintRule = [...PLUGIN_RULE_IDS, ...DUAL_LANE_IDS]
+  return declared.map(({ line, annotation }) => {
+    const bare = annotation.rules.length === 0 && annotation.unknownRules.length === 0
+    return {
+      line,
+      scope: annotation.scope,
+      rules: [...annotation.rules],
+      guardKinds: annotation.rules.filter((id): id is GuardKind => Object.hasOwn(GUARD_RULES, id)),
+      pluginRules: annotation.rules.filter(
+        (id) => !Object.hasOwn(GUARD_RULES, id) && PLUGIN_RULE_IDS.has(id),
+      ),
+      oxlintRules:
+        bare && annotation.scope === 'line'
+          ? everyOxlintRule
+          : [
+              ...new Set(
+                annotation.rules
+                  .flatMap((id) => [id, ...(WAIVER_ID_ALIASES[id] ?? [])])
+                  .filter((id) => PLUGIN_RULE_IDS.has(id) || DUAL_LANE_IDS.has(id)),
+              ),
+            ],
+      unknownRules: [...annotation.unknownRules],
+      hasReason: annotation.hasReason,
+      bare,
+      text: lines[line - 1] ?? '',
+    }
+  })
 }
 
 /** The token a neutralized annotation is rewritten to. Shares no substring with `theme-allow`. */

package/src/guard/types.ts

@@ -1,7 +1,7 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 27 violation kinds the theme guard can emit — `unframed-chart`
+ * GuardKind is the closed set of 28 violation kinds the theme guard can emit — `unframed-chart`
  * retired at the C2 consolidation wave: its only case (a hand-authored `<ChartLegend items={[...]}>`
  * array literal) is fully subsumed by the oxlint plugin's `basalt/chart-legend-literal`, which also
  * catches the `.map()`-over-a-non-series form the regex never could. `'unframed-chart'` stays a
@@ -11,7 +11,7 @@
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 27 theme-guard violation kinds. */
+/** The 28 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -40,6 +40,7 @@ export type GuardKind =
   | 'in-body-page-title'
   | 'raw-selection-control'
   | 'raw-media-query'
+  | 'unknown-vx-token'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/guard/vx-names.ts

@@ -0,0 +1,257 @@
+// GENERATED by scripts/gen-vx-names.ts — do not edit. `vx-names.test.ts` fails on drift.
+
+/** Every `--vx-*` name basalt emits: `dist/tokens.css` plus its component-scoped names. */
+export const BASALT_VX_NAMES: readonly string[] = [
+  '--vx-accent',
+  '--vx-accent-fill',
+  '--vx-accent-fill-hover',
+  '--vx-accent-hover',
+  '--vx-accentFill',
+  '--vx-accentFillHover',
+  '--vx-accentHover',
+  '--vx-area-bottom',
+  '--vx-area-top',
+  '--vx-axis',
+  '--vx-axis-stroke',
+  '--vx-axisStroke',
+  '--vx-bad',
+  '--vx-bad-ref',
+  '--vx-bad-solid',
+  '--vx-badRef',
+  '--vx-badSolid',
+  '--vx-crosshair',
+  '--vx-divider',
+  '--vx-dot-stroke',
+  '--vx-dotStroke',
+  '--vx-faint',
+  '--vx-fill-cyan',
+  '--vx-fill-grape',
+  '--vx-fill-gray',
+  '--vx-fill-green',
+  '--vx-fill-hover-cyan',
+  '--vx-fill-hover-grape',
+  '--vx-fill-hover-gray',
+  '--vx-fill-hover-green',
+  '--vx-fill-hover-indigo',
+  '--vx-fill-hover-lime',
+  '--vx-fill-hover-orange',
+  '--vx-fill-hover-pink',
+  '--vx-fill-hover-red',
+  '--vx-fill-hover-teal',
+  '--vx-fill-hover-violet',
+  '--vx-fill-hover-yellow',
+  '--vx-fill-indigo',
+  '--vx-fill-lime',
+  '--vx-fill-orange',
+  '--vx-fill-pink',
+  '--vx-fill-red',
+  '--vx-fill-teal',
+  '--vx-fill-violet',
+  '--vx-fill-yellow',
+  '--vx-fillHover-cyan',
+  '--vx-fillHover-grape',
+  '--vx-fillHover-gray',
+  '--vx-fillHover-green',
+  '--vx-fillHover-indigo',
+  '--vx-fillHover-lime',
+  '--vx-fillHover-orange',
+  '--vx-fillHover-pink',
+  '--vx-fillHover-red',
+  '--vx-fillHover-teal',
+  '--vx-fillHover-violet',
+  '--vx-fillHover-yellow',
+  '--vx-good',
+  '--vx-good-ref',
+  '--vx-good-soft',
+  '--vx-good-solid',
+  '--vx-goodRef',
+  '--vx-goodSoft',
+  '--vx-goodSolid',
+  '--vx-grid',
+  '--vx-hit',
+  '--vx-hit-gap',
+  '--vx-ink',
+  '--vx-ink2',
+  '--vx-keyboard-inset',
+  '--vx-legend-text',
+  '--vx-legendText',
+  '--vx-line',
+  '--vx-line2',
+  '--vx-muted',
+  '--vx-neutral',
+  '--vx-on-accent',
+  '--vx-onAccent',
+  '--vx-prose-measure',
+  '--vx-radius-card',
+  '--vx-radius-ctrl',
+  '--vx-radius-fine',
+  '--vx-radius-floating',
+  '--vx-radius-pill',
+  '--vx-radius-tight',
+  '--vx-shadow-card',
+  '--vx-shadow-ctrl',
+  '--vx-shadow-overlay',
+  '--vx-shadow-raised',
+  '--vx-space-agent-code-inset',
+  '--vx-space-agent-error-inset-x',
+  '--vx-space-agent-error-inset-y',
+  '--vx-space-agent-message-inset-x',
+  '--vx-space-agent-message-inset-y',
+  '--vx-space-agent-part-gap-top',
+  '--vx-space-agent-rail-inset-x',
+  '--vx-space-agent-scroll-button-gap-top',
+  '--vx-space-agent-transcript-inset',
+  '--vx-space-app-shell-header-lead-min',
+  '--vx-space-app-shell-inset',
+  '--vx-space-app-shell-inset-mobile',
+  '--vx-space-article-card-meta-gap-top',
+  '--vx-space-article-card-tag-inset-x',
+  '--vx-space-article-card-tag-inset-y',
+  '--vx-space-article-card-tags-gap',
+  '--vx-space-article-column-gap',
+  '--vx-space-article-footer-gap',
+  '--vx-space-article-footer-margin-top',
+  '--vx-space-article-footer-padding-top',
+  '--vx-space-article-header-gap',
+  '--vx-space-article-header-margin-bottom',
+  '--vx-space-article-header-padding-bottom',
+  '--vx-space-article-meta-row-gap',
+  '--vx-space-article-nav-target-gap',
+  '--vx-space-article-toc-rail-width',
+  '--vx-space-badge-inset-x',
+  '--vx-space-badge-inset-y',
+  '--vx-space-callout-inset-x',
+  '--vx-space-callout-inset-y',
+  '--vx-space-callout-title-row-gap',
+  '--vx-space-card-inset-x',
+  '--vx-space-card-inset-y',
+  '--vx-space-code-block-body-inset-y',
+  '--vx-space-code-block-content-inset-x',
+  '--vx-space-code-block-floating-copy-offset',
+  '--vx-space-code-block-header-gap',
+  '--vx-space-code-block-header-inset-right',
+  '--vx-space-code-block-header-inset-y',
+  '--vx-space-code-block-header-right-gap',
+  '--vx-space-control-gap',
+  '--vx-space-control-height',
+  '--vx-space-control-height-ctl',
+  '--vx-space-control-height-tag',
+  '--vx-space-control-height-widget',
+  '--vx-space-guide-body-gap-bottom',
+  '--vx-space-guide-footer-gap-top',
+  '--vx-space-guide-footer-inset-top',
+  '--vx-space-icon-size',
+  '--vx-space-input-height',
+  '--vx-space-mermaid-container-inset',
+  '--vx-space-mobile-nav-icon-size',
+  '--vx-space-mobile-nav-row-height',
+  '--vx-space-mobile-nav-tab-gap',
+  '--vx-space-mobile-nav-tab-inset-x',
+  '--vx-space-mobile-nav-tab-inset-y',
+  '--vx-space-nav-icon-gap',
+  '--vx-space-page-bar-row-height',
+  '--vx-space-prose-article-block-gap',
+  '--vx-space-prose-article-h1-gap-bottom',
+  '--vx-space-prose-article-h1-gap-top',
+  '--vx-space-prose-article-h2-rule-gap',
+  '--vx-space-prose-article-heading-gap-bottom',
+  '--vx-space-prose-article-heading-gap-top',
+  '--vx-space-prose-article-list-gap-bottom',
+  '--vx-space-prose-article-list-gap-top',
+  '--vx-space-prose-article-list-indent',
+  '--vx-space-prose-article-paragraph-gap',
+  '--vx-space-prose-chat-heading-gap-bottom',
+  '--vx-space-prose-chat-heading-gap-top',
+  '--vx-space-prose-chat-list-gap-bottom',
+  '--vx-space-prose-chat-list-indent',
+  '--vx-space-prose-chat-list-item-gap',
+  '--vx-space-prose-chat-nested-list-gap',
+  '--vx-space-prose-code-block-inset-x',
+  '--vx-space-prose-code-block-inset-y',
+  '--vx-space-prose-heading-anchor-gap',
+  '--vx-space-prose-inline-code-inset-x',
+  '--vx-space-prose-inline-code-inset-y',
+  '--vx-space-prose-quote-indent',
+  '--vx-space-prose-quote-inset-y',
+  '--vx-space-prose-table-cell-inset-x',
+  '--vx-space-prose-table-cell-inset-y',
+  '--vx-space-row-inset-x',
+  '--vx-space-row-inset-y',
+  '--vx-space-row-line-height',
+  '--vx-space-section-gap',
+  '--vx-space-section-header-height',
+  '--vx-space-settings-row-gap',
+  '--vx-space-settings-row-inset-y',
+  '--vx-space-sheet-row-height',
+  '--vx-space-sidebar-account-inset-bottom',
+  '--vx-space-sidebar-account-inset-top',
+  '--vx-space-sidebar-account-inset-x',
+  '--vx-space-sidebar-avatar-size',
+  '--vx-space-sidebar-block-row-height',
+  '--vx-space-sidebar-brand-inset-x',
+  '--vx-space-sidebar-child-list-gap-bottom',
+  '--vx-space-sidebar-child-list-gap-top',
+  '--vx-space-sidebar-child-list-indent',
+  '--vx-space-sidebar-child-row-indent',
+  '--vx-space-sidebar-child-row-inset-y',
+  '--vx-space-sidebar-region-gap',
+  '--vx-space-sidebar-search-gap',
+  '--vx-space-sidebar-search-trigger-height',
+  '--vx-space-sidebar-section-gap',
+  '--vx-space-sidebar-section-label-gap',
+  '--vx-space-stack-lg',
+  '--vx-space-stack-md',
+  '--vx-space-stack-sm',
+  '--vx-space-stack-xl',
+  '--vx-space-stack-xs',
+  '--vx-space-stat-card-gap',
+  '--vx-space-sticky-header-clearance',
+  '--vx-space-toc-link-indent',
+  '--vx-space-toc-link-inset-y',
+  '--vx-space-toc-root-gap',
+  '--vx-space-toc-sub-indent',
+  '--vx-space-virtual-row-inset-x',
+  '--vx-space-virtual-row-inset-y',
+  '--vx-space-widget-header-height',
+  '--vx-status-bad',
+  '--vx-status-excellent',
+  '--vx-status-good',
+  '--vx-status-neutral',
+  '--vx-status-warn',
+  '--vx-surface-bg',
+  '--vx-surface-border',
+  '--vx-surface-elevated',
+  '--vx-surface-field',
+  '--vx-surface-hairline',
+  '--vx-surface-overlay',
+  '--vx-surface-panel',
+  '--vx-surface-panel-hover',
+  '--vx-surface-panelHover',
+  '--vx-surface-subtle',
+  '--vx-text-display',
+  '--vx-text-h1',
+  '--vx-text-h2',
+  '--vx-text-kpi',
+  '--vx-text-lg',
+  '--vx-text-md',
+  '--vx-text-micro',
+  '--vx-text-nano',
+  '--vx-text-sm',
+  '--vx-text-xl',
+  '--vx-text-xs',
+  '--vx-tooltip-bg',
+  '--vx-tooltip-border',
+  '--vx-tooltip-muted',
+  '--vx-tooltip-shadow',
+  '--vx-tooltip-text',
+  '--vx-tooltipBg',
+  '--vx-tooltipBorder',
+  '--vx-tooltipMuted',
+  '--vx-tooltipShadow',
+  '--vx-tooltipText',
+  '--vx-warn',
+  '--vx-warn-ref',
+  '--vx-warn-solid',
+  '--vx-warnRef',
+  '--vx-warnSolid',
+]

package/src/notifications/mount-guard.ts

@@ -12,7 +12,6 @@
  * as `provider/lab-theme.ts`.
  */
 import { useEffect } from 'react'
-import { isDev } from '../common/is-dev'
 
 let mountedNotificationsCount = 0
 
@@ -25,7 +24,7 @@ let mountedNotificationsCount = 0
 export function useNotificationsMountGuard(): void {
   useEffect(() => {
     mountedNotificationsCount++
-    if (mountedNotificationsCount > 1 && isDev()) {
+    if (mountedNotificationsCount > 1 && process.env.NODE_ENV !== 'production') {
       console.warn(
         '[basalt] more than one Notifications overlay is mounted at once — mount exactly ONE ' +
           "<BasaltOverlays notifications /> (they all render Mantine's <Notifications />, so " +

package/src/provider/index.tsx

@@ -34,7 +34,6 @@ import { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from
 import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
-import { isDev } from '../common/is-dev'
 import { useMediaQuery } from '../common/use-media-query'
 import { registerColorSchemeSetter } from '../commands/shell-bridge'
 import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
@@ -125,7 +124,7 @@ export type BasaltProviderProps = {
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
 
 function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
-  if (isDev()) {
+  if (process.env.NODE_ENV !== 'production') {
     // eslint-disable-next-line no-console -- intentional dev-only diagnostic when no onError is supplied
     console.error('[BasaltProvider] unhandled error', ctx.kind, error)
   }
@@ -382,7 +381,7 @@ const providerMounts = createMountCounter()
 
 function useDuplicateProviderGuard(): void {
   useEffect(() => {
-    if (providerMounts.mount() > 1 && isDev()) {
+    if (providerMounts.mount() > 1 && process.env.NODE_ENV !== 'production') {
       console.warn(
         '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
           'BasaltProviders double-mount MantineProvider, the palette <style> and ' +

package/src/provider/lab-theme.ts

@@ -33,9 +33,9 @@
  * The delta also carries `other.basaltDerive`/`basaltRadius`/`basaltDensity`, so `BasaltBridge`'s
  * existing injection emits the matching `--vx-*` CSS off the running theme — one path, both halves.
  *
- * DEV-tool path only, twice over: it is compiled out of a production build entirely (see
- * {@link LAB_ENABLED}), and even in a dev build, with the "Apply" switch off — or in any app that
- * never mounts the panel, since the persisted key is written by nothing else —
+ * DEV-tool path only, twice over: it is compiled out of a production build entirely (see the
+ * DEV-build gate on `useLabTheme`), and even in a dev build, with the "Apply" switch off — or in
+ * any app that never mounts the panel, since the persisted key is written by nothing else —
  * {@link applyLabOverride} returns the consumer theme verbatim.
  */
 import { mergeThemeOverrides } from '@mantine/core'
@@ -44,7 +44,6 @@ import { useMemo } from 'react'
 import { useDeriveControlsState, toDeriveOverride } from '../theme-lab/derive-state'
 import type { DeriveOverride } from '../theme-lab/derive-state'
 import { baseTheme, createBasaltTheme } from '../theme'
-import { isDev } from '../common/is-dev'
 
 type Plain = Record<string, unknown>
 
@@ -124,20 +123,27 @@ export function applyLabOverride(
   return mergeThemeOverrides(theme, themeOverrideDelta(baseTheme, labTheme))
 }
 
-/**
- * DEV-build gate. `BasaltProvider` is the mandatory `.` entry, so an unconditional subscription to
- * the lab store would make EVERY production app pay a localStorage read + schema validation on first
- * render and keep a `window` 'storage' listener registered for its whole lifetime — to answer a
- * question ("is the dev lab active?") that is always "no" in an app that never mounts
- * `<DeriveControls>`. Resolved ONCE at module scope, so it also lets a bundler drop
- * `useLabThemeDev` (and with it the `theme-lab/derive-state` import) from a production build.
+/*
+ * DEV-build gate (on `useLabTheme` below). `BasaltProvider` is the mandatory `.` entry, so an
+ * unconditional subscription to the lab store would make EVERY production app pay a localStorage
+ * read + schema validation on first render and keep a `window` 'storage' listener registered for
+ * its whole lifetime — to answer a question ("is the dev lab active?") that is always "no" in an
+ * app that never mounts `<DeriveControls>`.
+ *
+ * Resolved ONCE at module scope, so a bundler can drop `useLabThemeDev` (and with it the
+ * `theme-lab/derive-state` + `state/persisted` imports) from a production build — but only
+ * because the gate is a literal, dotted `process.env.NODE_ENV` read inside the ternary itself.
+ * Measured (minified prod builds, dev branch behind an import): the literal read folds in
+ * Vite/Rolldown, esbuild, Bun and webpack + terser alike, in both the dotted and the bracketed
+ * form; dotted is kept as the form every `define` implementation matches. A cross-module
+ * `isDev()` call and a module-level `const` both LEAK the dev branch in esbuild and Bun (and
+ * `isDev()` in Rolldown too), which is how 1.32.1 shipped the whole lab store in every production
+ * app's first-paint chunk. `check-budgets.ts`'s provider-only budget pins it.
  *
- * The cost: the lab does nothing in a PRODUCTION BUILD of a playground/dev app. It is a dev tool run
- * through a dev server (`bun run dev`), so that is the right side of the trade — but if you ever
- * preview the playground via `vite build && vite preview`, the sliders will be inert there.
+ * The cost: the lab does nothing in a PRODUCTION BUILD of a playground/dev app. It is a dev tool
+ * run through a dev server (`bun run dev`), so that is the right side of the trade — but if you
+ * ever preview the playground via `vite build && vite preview`, the sliders will be inert there.
  */
-const LAB_ENABLED = isDev()
-
 /**
  * Dev build: subscribed to the lab store.
  *
@@ -159,9 +165,10 @@ function useLabThemeProd(overrides: MantineThemeOverride | undefined): MantineTh
 }
 
 /**
- * `BasaltProvider`'s theme resolution. Picked at module scope, not per render — both implementations
- * call their hooks unconditionally at their own top level, and which one is bound never changes for
- * the app's lifetime, so the hook order is as stable as a plain function's (a `LAB_ENABLED ? use…()`
- * inline in one function body would be a conditional hook call and a `react/rules-of-hooks` error).
+ * `BasaltProvider`'s theme resolution. Picked at module scope, not per render — both
+ * implementations call their hooks unconditionally at their own top level, and which one is bound
+ * never changes for the app's lifetime, so the hook order is as stable as a plain function's (a
+ * `dev ? use…()` inline in one function body would be a conditional hook call and a
+ * `react/rules-of-hooks` error).
  */
-export const useLabTheme = LAB_ENABLED ? useLabThemeDev : useLabThemeProd
+export const useLabTheme = process.env.NODE_ENV !== 'production' ? useLabThemeDev : useLabThemeProd