basalt-ui 1.23.0 → 1.23.1

package/dist/guard/index.js

@@ -108,8 +108,28 @@ const RADIUS_PROP_RE = /\bradius=(?:\{[0-9]+\}|"[0-9]+")/g;
 const MOTION_TRANSITION_NUMERIC = /\btransition\s*=\s*\{\{[^}]*\b(?:duration|stiffness|damping|mass)\s*:\s*-?\d/g;
 const MOTION_TRANSITION_EASE_ARRAY = /\btransition\s*=\s*\{\{[^}]*\bease\s*:\s*\[/g;
 const RAW_CHART_LEGEND_ARRAY = /<ChartLegend\b[^>]*?\bitems\s*=\s*\{\s*\[/g;
-const CHART_ENTRY_POINT_TAG = /<(?:MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g;
+const CHART_ENTRY_POINT_TAG = /<(MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g;
 const HAS_ARIA_LABEL_PROP = /\bariaLabel\s*=/;
+const LOCAL_COMPONENT_DEF = /(?:^|[\n;}])\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\s+([A-Z]\w*)/g;
+const BASALT_NAMED_IMPORT = /import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"]basalt-ui(?:\/[^'"]*)?['"]/g;
+function localComponentNames(codeText) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of codeText.matchAll(LOCAL_COMPONENT_DEF)) out.add(m[1]);
+  return out;
+}
+function basaltImportedNames(codeText) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of codeText.matchAll(BASALT_NAMED_IMPORT)) {
+    for (const raw of m[1].split(",")) {
+      const spec = raw.trim().replace(/^type\s+/, "");
+      if (spec.length === 0) continue;
+      const parts = spec.split(/\s+as\s+/);
+      const bound = parts[parts.length - 1].trim();
+      if (bound.length > 0) out.add(bound);
+    }
+  }
+  return out;
+}
 const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g;
 const RAW_FORM_CONTROL_TAG = /<(?:input|select|textarea)\b(?:=>|[^>])*?>/g;
 const STYLES_INPUT_PART = /\bstyles\s*=\s*\{\{\s*input\s*:\s*\{([^}]*)\}/g;
@@ -964,15 +984,21 @@ function checkSource(text, relPath, cfg) {
       });
     }
   }
-  if (GUARD_RULES["unframed-chart"].enabled(cfg) && ruleApplies("unframed-chart", relPath)) {
+  const unframedChartRuns = GUARD_RULES["unframed-chart"].enabled(cfg) && ruleApplies("unframed-chart", relPath);
+  const ariaLabelRuns = GUARD_RULES["chart-missing-aria-label"].enabled(cfg) && ruleApplies("chart-missing-aria-label", relPath);
+  const localNames = unframedChartRuns || ariaLabelRuns ? localComponentNames(codeText) : /* @__PURE__ */ new Set();
+  const basaltNames = unframedChartRuns || ariaLabelRuns ? basaltImportedNames(codeText) : /* @__PURE__ */ new Set();
+  const isShippedTag = (tag) => basaltNames.has(tag) || !localNames.has(tag);
+  if (unframedChartRuns && isShippedTag("ChartLegend")) {
     for (const m of codeText.matchAll(RAW_CHART_LEGEND_ARRAY)) {
       const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split("\n").length;
       push("unframed-chart", lineNo, "items={[");
     }
   }
-  if (GUARD_RULES["chart-missing-aria-label"].enabled(cfg) && ruleApplies("chart-missing-aria-label", relPath)) {
+  if (ariaLabelRuns) {
     for (const m of codeText.matchAll(CHART_ENTRY_POINT_TAG)) {
       const tagText = m[0];
+      if (!isShippedTag(m[1])) continue;
       if (HAS_ARIA_LABEL_PROP.test(tagText)) continue;
       const startLine = codeText.slice(0, m.index ?? 0).split("\n").length;
       const endLine = startLine + (tagText.split("\n").length - 1);

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.23.0
+# basalt-ui v1.23.1
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.23.0
+Version: 1.23.1
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.23.0",
+  "version": "1.23.1",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/kinds/BandStrip.test.tsx

@@ -87,13 +87,77 @@ describe('BandStrip — fills derive from series', () => {
     // Overridden: the ramp value, not the series default.
     expect(fills).toContain('color-mix(in srgb, #a00 62%, transparent)')
   })
+})
 
-  test('a state key absent from `series` draws nothing rather than an unlegended mark', () => {
-    const { container } = renderStrip({ getBand: () => ({ state: 'nope' }) })
-    const painted = [...container.querySelectorAll('rect[fill]')].filter(
-      (r) => r.getAttribute('fill') !== 'transparent',
+/**
+ * The old contract here was "a state key absent from `series` draws nothing". On a strip whose
+ * whole vocabulary is measured/not-measured, a missing band is not "unknown" — it is a coverage
+ * gap, so a typo'd key silently asserted an absence nobody measured. These pin the replacement:
+ * loud where it is a bug being written, honest where it is a feed that grew a state.
+ */
+/** Run `fn` with the production dev-gate, restoring whatever the runner had set. */
+function inProd(fn: () => void): void {
+  const previous = process.env['NODE_ENV']
+  process.env['NODE_ENV'] = 'production'
+  try {
+    fn()
+  } finally {
+    if (previous === undefined) delete process.env['NODE_ENV']
+    else process.env['NODE_ENV'] = previous
+  }
+}
+
+describe('BandStrip — an unresolvable state key can never read as absence', () => {
+  test('a state naming no `series` entry THROWS in dev, naming the key and the known ones', () => {
+    expect(() => renderStrip({ getBand: () => ({ state: 'nope' }) })).toThrow(
+      /BandSpan.state "nope" names no `series` entry \(known: clean, loss, absent\)/,
     )
-    expect(painted).toHaveLength(0)
+  })
+
+  test('a marker naming no `series` entry throws in dev too', () => {
+    expect(() =>
+      renderStrip({ getBand: (d: Slot) => ({ ...getBand(d), marker: { state: 'typo' } }) }),
+    ).toThrow(/BandSpan.marker.state "typo"/)
+  })
+
+  test('in production it draws a dashed neutral band — never nothing, never a state fill', () => {
+    inProd(() => {
+      const { container } = renderStrip({ getBand: () => ({ state: 'nope' }) })
+      const painted = [...container.querySelectorAll('rect[fill]')].filter(
+        (r) => r.getAttribute('fill') !== 'transparent',
+      )
+      expect(painted).toHaveLength(3)
+      // The unknown treatment belongs to no legend entry: dashed outline, neutral fill, and none of
+      // the three series colours.
+      for (const rect of painted) {
+        expect(rect.getAttribute('stroke-dasharray')).toBe('3 2')
+        expect(rect.getAttribute('fill')).toBe(
+          'color-mix(in srgb, var(--vx-neutral) 20%, transparent)',
+        )
+      }
+    })
+  })
+
+  test('in production the tooltip names the unresolved key instead of a state the legend carries', async () => {
+    process.env['NODE_ENV'] = 'production'
+    try {
+      renderStrip({ getBand: () => ({ state: 'nope' }), ariaLabel: 'Availability' })
+      fireEvent.keyDown(screen.getByRole('slider'), { key: 'ArrowRight' })
+      const tip = await screen.findByRole('tooltip')
+      expect(tip.textContent).toContain('Unknown state')
+      expect(tip.textContent).toContain('nope')
+      expect(tip.textContent).not.toContain('Not measured')
+    } finally {
+      delete process.env['NODE_ENV']
+    }
+  })
+
+  test('`absentState` naming no `series` entry throws in EVERY environment — it is a prop, not a datum', () => {
+    inProd(() => {
+      expect(() => renderStrip({ absentState: 'ghost' })).toThrow(
+        /absentState "ghost" names no `series` entry/,
+      )
+    })
   })
 })
 
@@ -193,6 +257,24 @@ describe('BandStrip — the tooltip row is DERIVED from the hovered band’s sta
     expect(tip2.textContent).not.toContain('No loss')
   })
 
+  test('formatValue returning null renders an em dash, not an empty value', async () => {
+    const series: BandStripSeries<Slot>[] = SERIES.map((entry) =>
+      entry.key === 'absent'
+        ? { ...entry, formatValue: (d: Slot) => (d.loss === null ? null : `${d.loss}%`) }
+        : entry,
+    )
+    renderStrip({ series, ariaLabel: 'Availability' })
+    const slider = screen.getByRole('slider')
+    fireEvent.keyDown(slider, { key: 'ArrowRight' })
+    fireEvent.keyDown(slider, { key: 'ArrowRight' })
+    fireEvent.keyDown(slider, { key: 'ArrowRight' })
+
+    const tip = await screen.findByRole('tooltip')
+    expect(tip.textContent).toContain('Not measured')
+    // Distinct from `''`, which renders the label with no value at all.
+    expect(tip.textContent).toContain('\u2014')
+  })
+
   test('the focusable overlay carries the chart’s own aria-label, not a generic one', () => {
     renderStrip({ ariaLabel: 'Availability per bucket' })
     expect(screen.getByRole('slider').getAttribute('aria-label')).toBe('Availability per bucket')

package/src/charts/kinds/BandStrip.tsx

@@ -25,17 +25,30 @@ import { fmtAxisDate } from '../utils/format'
  * numeric value to plot — `formatValue` reads the datum directly.
  */
 export type BandStripSeries<T> = SeriesStyle & {
-  /** The derived tooltip row's value for a band in this state. Omit for a state whose NAME is the
-   * whole reading ("Not measured"), which then renders as a label with an empty value. */
-  formatValue?: (d: T) => string
+  /**
+   * The derived tooltip row's value for a band in this state.
+   *
+   * Return `null` for a datum in this state whose reading is ABSENT — the row renders
+   * {@link NO_READING} instead, which is the escape `ChartSeries.getValue` has and this shape did
+   * not: with no value accessor, an absent reading had to come back as `''` and render as a label
+   * with an empty value, indistinguishable from a state whose name is the whole reading.
+   *
+   * Omit the function entirely for a state whose NAME *is* the whole reading ("Not measured").
+   */
+  formatValue?: (d: T) => string | null
 }
 
 /** One drawn band — which state it is in, and the three ways a state can be qualified. */
 export type BandSpan = {
   /**
    * Series key naming this band's state: the tie to its legend entry, its fill, and its derived
-   * tooltip row. A key not present in `series` draws nothing — the loud failure is deliberate,
-   * since the alternative is a mark no legend entry accounts for.
+   * tooltip row.
+   *
+   * A key not present in `series` is a bug TypeScript cannot catch (this is a `string`), and it
+   * used to draw NOTHING — which on a strip whose vocabulary is measured/not-measured is
+   * indistinguishable from a real coverage gap, so a typo silently asserted "not measured". It now
+   * throws in development and draws an explicit unknown band in production; see
+   * {@link unknownStateError} for why the two differ.
    */
   state: string
   /**
@@ -99,7 +112,8 @@ export type BandStripProps<T> = {
   legend?: ChartLegendConfig | false
   /** Colour of the absence hatch. Names a `series` entry, so absence is legended like any other
    * state — a hatched band is the one mark a reader cannot decode from an axis. Default
-   * `VX.neutral`, unnamed. */
+   * `VX.neutral`, unnamed. A key naming no `series` entry throws (a PROP, so a typo can only be a
+   * wiring error) rather than falling back to the unnamed default. */
   absentState?: string
   /** Per-side overrides of the measured margins — applied last. */
   margin?: Partial<ChartMargin>
@@ -112,6 +126,52 @@ export type BandStripProps<T> = {
 
 const DEFAULT_MARKER_INSET = 6
 
+/** Rendered by a `formatValue` that returned `null` — an absent reading, told apart from a state
+ * whose name is the whole reading (which renders no value at all). */
+const NO_READING = '\u2014'
+
+/**
+ * The one band treatment that belongs to no legend entry. A dashed neutral outline appears nowhere
+ * else on a strip — not as a state fill, not as the absence hatch — so an unresolvable key reads as
+ * "unnamed", never as data.
+ */
+const UNKNOWN_MARK = {
+  fill: alpha(VX.neutral, 0.2),
+  stroke: VX.neutral,
+  strokeWidth: 1,
+  strokeDasharray: '3 2',
+} as const
+
+/** The house dev gate (`src/provider`, `src/agent-chat` use the same expression): `basaltViteConfig`
+ * defines `process.env.NODE_ENV`, so a production bundle constant-folds this to `false` and drops
+ * the throw. Read per call, never hoisted to a module const, so a test can flip it. */
+function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}
+
+/**
+ * A `state` (or `marker.state`) naming no `series` entry.
+ *
+ * Dev throws, production draws {@link UNKNOWN_MARK}: `state` comes off the DATUM, so a feed that
+ * grows a state basalt has never seen must degrade to an honest unknown rather than take the page
+ * down — while a typo, which is the same input, still fails loudly everywhere it is being written.
+ * The one outcome ruled out in both is the old one: dropping the band, which renders as absence.
+ */
+function unknownStateError(what: string, key: string, known: Iterable<string>): Error {
+  return new Error(
+    `BandStrip: ${what} "${key}" names no \`series\` entry (known: ${[...known].join(', ')}) — so ` +
+      'it has no legend entry, no colour and no tooltip row. Add the state to `series`, or map the ' +
+      'datum onto one that is there.',
+  )
+}
+
+/** A band's tooltip value: `null` from `formatValue` is an absent reading, `undefined` (no
+ * `formatValue` at all) is a state whose label is the whole row. */
+function formatBandValue<T>(style: BandStripSeries<T>, datum: T): string {
+  if (style.formatValue === undefined) return ''
+  return style.formatValue(datum) ?? NO_READING
+}
+
 /**
  * A 1-D categorical band strip: one rect per slot over a shared x axis, no y dimension at all.
  *
@@ -187,6 +247,9 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
   const { bands, margin, plotWidth, scale, cursor, point, crosshairX, step, bandWidth } = band
   const stripHeight = Math.max(plot.height - margin.top - margin.bottom, 1)
   const hatchId = `${chartId}-band-absent`
+  if (absentState !== undefined && !styleByKey.has(absentState)) {
+    throw unknownStateError('absentState', absentState, styleByKey.keys())
+  }
   const absentColor =
     (absentState === undefined ? undefined : styleByKey.get(absentState)?.color) ?? VX.neutral
 
@@ -195,16 +258,35 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
     bands.forEach((d, i) => {
       const span = getBand(d)
       const style = styleByKey.get(span.state)
-      if (style === undefined || hidden.has(span.state)) return
+      const x = i * step
+      if (style === undefined) {
+        if (isDev()) throw unknownStateError('BandSpan.state', span.state, styleByKey.keys())
+        out.push(
+          <rect
+            key={getX(d)}
+            {...UNKNOWN_MARK}
+            x={x}
+            y={0}
+            width={bandWidth}
+            height={stripHeight}
+            rx={1}
+            pointerEvents="none"
+          />,
+        )
+        return
+      }
+      if (hidden.has(span.state)) return
       // Clamped AND finite-checked. `foldedFrom` is carried by the consumer's datum, so a
       // 0/0 on an un-folded slot arrives here as NaN — which `Math.min`/`Math.max` propagate
       // straight into `width="NaN"`, a band that silently fails to paint.
       const absent = clampFraction(span.absentFraction)
       const measuredWidth = bandWidth * (1 - absent)
       const hatchWidth = bandWidth - measuredWidth
-      const x = i * step
       const markerKey = span.marker?.state ?? span.state
       const markerColor = styleByKey.get(markerKey)?.color
+      if (span.marker !== undefined && markerColor === undefined && isDev()) {
+        throw unknownStateError('BandSpan.marker.state', markerKey, styleByKey.keys())
+      }
       const inset = span.marker?.inset ?? DEFAULT_MARKER_INSET
       out.push(
         <g key={getX(d)}>
@@ -230,14 +312,14 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
               pointerEvents="none"
             />
           )}
-          {span.marker !== undefined && markerColor !== undefined && measuredWidth > 0 && (
+          {span.marker !== undefined && measuredWidth > 0 && (
             <rect
+              {...(markerColor === undefined ? UNKNOWN_MARK : { fill: markerColor })}
               x={x}
               y={inset}
               width={measuredWidth}
               height={Math.max(stripHeight - 2 * inset, 2)}
               rx={1}
-              fill={markerColor}
               pointerEvents="none"
             />
           )}
@@ -347,11 +429,22 @@ function deriveBandRow<T>(
   datum: T,
 ): { color: string; label: string; value: string; shape: 'line' | 'bar'; dashed: boolean } | null {
   const style = styleByKey.get(span.state)
-  if (style === undefined || style.tooltip === false || hidden.has(span.state)) return null
+  // Production-only: dev threw while drawing. The row names the KEY rather than a state, so the
+  // tooltip cannot read back a state the legend does not carry.
+  if (style === undefined) {
+    return {
+      color: VX.neutral,
+      label: 'Unknown state',
+      value: span.state,
+      shape: 'bar',
+      dashed: true,
+    }
+  }
+  if (style.tooltip === false || hidden.has(span.state)) return null
   return {
     color: style.color,
     label: style.label,
-    value: style.formatValue?.(datum) ?? '',
+    value: formatBandValue(style, datum),
     shape: style.mark === 'line' ? 'line' : 'bar',
     dashed: style.dash === 'dashed',
   }

package/src/charts/kinds/MirroredBars.test.tsx

@@ -191,3 +191,42 @@ describe('MirroredBars — tooltip rows are derived, each in its own pane’s un
     expect(tip.textContent).not.toContain('Upload')
   })
 })
+
+/**
+ * The `BandStrip` silent-drop class, in this kind's shape. An unresolvable pane key left the pane
+ * AND its axis unrendered — which on a chart whose point is that idle and unmeasured must stay
+ * distinguishable reads as "that half measured nothing".
+ */
+describe('MirroredBars — an unresolvable key can never read as a measured zero', () => {
+  test('a pane key naming no `series` entry throws instead of hiding the pane', () => {
+    expect(() => renderChart({ up: { key: 'uplaod', format: (v) => `${v}u`, ticks: 2 } })).toThrow(
+      /up.key "uplaod" names no `series` entry \(known: down, up, absent\)/,
+    )
+  })
+
+  test('it throws in production too — a pane key is a PROP, so a typo is always a wiring error', () => {
+    const previous = process.env['NODE_ENV']
+    process.env['NODE_ENV'] = 'production'
+    try {
+      expect(() =>
+        renderChart({ down: { key: 'donw', format: (v) => `${v}d`, ticks: 2 } }),
+      ).toThrow(/down.key "donw"/)
+    } finally {
+      if (previous === undefined) delete process.env['NODE_ENV']
+      else process.env['NODE_ENV'] = previous
+    }
+  })
+
+  test('`absentState` naming no `series` entry throws rather than hatching in an unnamed neutral', () => {
+    expect(() => renderChart({ absentState: 'ghost' })).toThrow(
+      /absentState "ghost" names no `series` entry/,
+    )
+  })
+
+  test('a resolvable absentState still draws the hatch in that entry’s colour', () => {
+    const { container } = renderChart({ absentState: 'absent' })
+    expect(container.querySelector('pattern line')?.getAttribute('stroke')).toBe(
+      'color-mix(in srgb, #555 70%, transparent)',
+    )
+  })
+})

package/src/charts/kinds/MirroredBars.tsx

@@ -25,7 +25,8 @@ import { fmtAxisDate } from '../utils/format'
 
 /** One of the two panes. Each resolves its own domain — that is the whole point of the kind. */
 export type MirroredBarPane = {
-  /** Key of the `series` entry this pane draws: its colour, its legend entry, its tooltip row. */
+  /** Key of the `series` entry this pane draws: its colour, its legend entry, its tooltip row.
+   * A key naming no entry throws — see {@link assertPaneKey}. */
   key: string
   /**
    * The pane's upper bound. `'auto'` (default) is its own visible maximum; a number pins it.
@@ -85,7 +86,8 @@ export type MirroredBarsProps<T> = {
   cursorResolution?: CursorResolution
   tooltip?: BandTooltipConfig<T> | false
   legend?: ChartLegendConfig | false
-  /** Series key whose colour the absence hatch is drawn in. Default `VX.neutral`. */
+  /** Series key whose colour the absence hatch is drawn in. Default `VX.neutral`. A key naming no
+   * `series` entry throws rather than falling back to the unnamed default. */
   absentState?: string
   margin?: Partial<ChartMargin>
   ariaLabel?: string
@@ -95,6 +97,31 @@ export type MirroredBarsProps<T> = {
 const DEFAULT_UP_FRACTION = 0.35
 const DEFAULT_PANE_TICKS = 3
 
+/**
+ * A pane key naming no `series` entry.
+ *
+ * This is `BandStrip`'s silent-drop bug in the shape this kind has: an unresolvable `up.key` left
+ * `upSeries` undefined, which made `upVisible` false, which hid the pane AND its axis — rendering
+ * as "that half measured nothing", the measured-and-idle state the whole kind exists to keep
+ * distinguishable from absence. Unlike `BandSpan.state`, a pane key is a PROP and never comes off a
+ * datum, so a typo can only ever be a wiring error: this throws in every environment, with no
+ * production fallback, because there is no honest way to draw a pane whose colour and legend entry
+ * do not exist.
+ */
+function assertPaneKey<T>(
+  side: 'up' | 'down',
+  key: string,
+  resolved: ChartSeries<T> | undefined,
+  series: readonly ChartSeries<T>[],
+): void {
+  if (resolved !== undefined) return
+  throw new Error(
+    `MirroredBars: ${side}.key "${key}" names no \`series\` entry ` +
+      `(known: ${series.map((s) => s.key).join(', ')}) — the pane would silently vanish, which ` +
+      'reads as a measured zero. Add the series, or point the pane at one that exists.',
+  )
+}
+
 /**
  * Two bar panes over ONE x scale and one cursor, mirrored around a shared baseline, each in its
  * own independent domain.
@@ -159,6 +186,8 @@ function MirroredBarsPlot<T>(props: MirroredBarsPlotProps<T>) {
   const seriesByKey = useMemo(() => new Map(series.map((s) => [s.key, s])), [series])
   const upSeries = seriesByKey.get(up.key)
   const downSeries = seriesByKey.get(down.key)
+  assertPaneKey('up', up.key, upSeries, series)
+  assertPaneKey('down', down.key, downSeries, series)
   const upVisible = upSeries !== undefined && !hidden.has(up.key)
   const downVisible = downSeries !== undefined && !hidden.has(down.key)
 
@@ -221,6 +250,13 @@ function MirroredBarsPlot<T>(props: MirroredBarsPlotProps<T>) {
   )
 
   const hatchId = `${chartId}-mirrored-absent`
+  if (absentState !== undefined && !seriesByKey.has(absentState)) {
+    throw new Error(
+      `MirroredBars: absentState "${absentState}" names no \`series\` entry ` +
+        `(known: ${series.map((s) => s.key).join(', ')}) — the hatch would fall back to an unnamed ` +
+        'neutral, and a hatched bar is the one mark a reader cannot decode from either axis.',
+    )
+  }
   const absentColor =
     (absentState === undefined ? undefined : seriesByKey.get(absentState)?.color) ?? VX.neutral
 

package/src/cli/help.test.ts

@@ -4,7 +4,15 @@
  * matched `cmd === 'sync'` first and `--help` was just another item in `flags`, ignored).
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
 import { tmpdir } from 'node:os'
 import { resolve } from 'node:path'
 
@@ -95,3 +103,68 @@ describe('run() --help short-circuits before dispatch', () => {
     expect(existsSync(resolve(dir, MANIFEST_PATH))).toBe(true)
   })
 })
+
+/**
+ * `--version` and the unknown-flag gate — one failure mode, two halves.
+ *
+ * Six consumer repos in one upgrade round reached for `basalt-ui --version` to prove WHICH CLI ran
+ * (a `bunx` cache does not re-resolve, so a pinned version and the version that gates you can
+ * differ) and got a usage dump with no version in it. The other half is the same shape: an
+ * unrecognized FLAG was silently ignored and the command exited 0, so a mistyped gate read as a
+ * passing gate.
+ */
+describe('run() --version and the unknown-flag gate', () => {
+  const version = (
+    JSON.parse(readFileSync(resolve(import.meta.dir, '../../package.json'), 'utf8')) as {
+      version: string
+    }
+  ).version
+
+  it('`--version` prints the bare resolved version and exits 0', () => {
+    const { code, log } = capture(() => run(['--version'], dir))
+    expect(code).toBe(0)
+    expect(log.trim()).toBe(version)
+  })
+
+  it('`-v` and `version` are the same thing', () => {
+    expect(capture(() => run(['-v'], dir)).log.trim()).toBe(version)
+    expect(capture(() => run(['version'], dir)).log.trim()).toBe(version)
+  })
+
+  it('the printed line is greppable on its own — no usage block around it', () => {
+    const { log } = capture(() => run(['--version'], dir))
+    expect(log).not.toContain('Usage: basalt')
+  })
+
+  it('an unrecognized flag exits 1 and NAMES it, on a command that would otherwise pass', () => {
+    const { code, log } = capture(() => run(['doctor', '--json'], dir))
+    expect(code).toBe(1)
+    expect(log).toContain("unrecognized flag '--json'")
+    expect(log).toContain('--tokens-only')
+  })
+
+  it('a near-miss flag does not slip through as a silent no-op', () => {
+    const { code, log } = capture(() => run(['check-theme', '--audit-allow'], dir))
+    expect(code).toBe(1)
+    expect(log).toContain("unrecognized flag '--audit-allow'")
+  })
+
+  it('a value-taking flag does not make its VALUE look like an unknown flag', () => {
+    const out = resolve(dir, 'tokens.css')
+    const { code } = capture(() => run(['tokens:css', '--out', out, '--only', 'core'], dir))
+    expect(code).toBe(0)
+  })
+
+  it('an unknown COMMAND names what it did not understand, above the usage block', () => {
+    const { code, log } = capture(() => run(['check-theme --audit-allows'], dir))
+    expect(code).toBe(1)
+    expect(log).toContain("unknown command 'check-theme --audit-allows'")
+    expect(log).toContain('Usage: basalt')
+  })
+
+  it('`--help` still wins over the flag gate, so a reader can always find out what is accepted', () => {
+    const { code, log } = capture(() => run(['doctor', '--json', '--help'], dir))
+    expect(code).toBe(0)
+    expect(log).toContain('Usage: basalt')
+  })
+})