basalt-ui 1.23.0 → 1.24.0

package/dist/query/index.d.ts

@@ -40,25 +40,7 @@ export declare function unwrap<TData>(response: Promise<{
     data: TData | null;
     error: unknown;
 }>): Promise<TData>;
-/**
- * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
- * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
- *
- * Resolution order:
- *   1. `Error` instance       → err.message
- *   2. `{ message: string }`  → message (Eden / Elysia error shape)
- *   3. `{ value: ... }`       → toErrorMessage(value) recursively (Eden nested value envelope)
- *   4. plain string            → itself
- *   5. anything else           → JSON.stringify with safe fallback to String()
- *
- * @example
- * try {
- *   await unwrap(api.resource.post({ body }))
- * } catch (e) {
- *   toast(toErrorMessage(e))
- * }
- */
-export declare function toErrorMessage(err: unknown): string;
+export { toErrorMessage, errorStatus } from './error-message.js';
 export { QueryClientProvider, QueryErrorResetBoundary, useQueryErrorResetBoundary, } from '@tanstack/react-query';
 export { useQuery, useSuspenseQuery, useMutation, useQueryClient, useInfiniteQuery, queryOptions, } from '@tanstack/react-query';
 export { BasaltQueryDevtools } from './devtools.js';

package/dist/query/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAW9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAQ/E;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAChC,QAAQ,EAAE,OAAO,CAAC;IAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GACxD,OAAO,CAAC,KAAK,CAAC,CAQhB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAcnD;AAKD,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,uBAAuB,CAAA;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAW9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAQ/E;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAChC,QAAQ,EAAE,OAAO,CAAC;IAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GACxD,OAAO,CAAC,KAAK,CAAC,CAQhB;AAID,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAK7D,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,uBAAuB,CAAA;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}

package/dist/query/index.js

@@ -23,20 +23,7 @@ async function unwrap(response) {
     );
   return data;
 }
-function toErrorMessage(err) {
-  if (err instanceof Error) return err.message;
-  if (typeof err === "string") return err;
-  if (typeof err === "object" && err !== null) {
-    const obj = err;
-    if (typeof obj["message"] === "string") return obj["message"];
-    if ("value" in obj) return toErrorMessage(obj["value"]);
-  }
-  try {
-    return JSON.stringify(err);
-  } catch {
-    return String(err);
-  }
-}
+import { toErrorMessage, errorStatus } from "./error-message.js";
 import {
   QueryClientProvider,
   QueryErrorResetBoundary,
@@ -56,6 +43,7 @@ export {
   QueryClientProvider,
   QueryErrorResetBoundary,
   createBasaltQueryClient,
+  errorStatus,
   queryOptions,
   toErrorMessage,
   unwrap,

package/dist/surfaces.d.ts

@@ -131,7 +131,7 @@ export declare const SURFACES: {
         readonly rule: "mantine";
         readonly skill: readonly ["basalt-app", "basalt-design"];
         readonly guardKinds: readonly ["raw-motion-value", "card-with-border", "raw-form-control", "sub-16-input-font", "mantine-shade-index"];
-        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)";
+        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)";
         readonly optionalPeers: readonly ["react-markdown", "remark-gfm", "rehype-sanitize", "remend", "shiki", "beautiful-mermaid"];
         readonly forbiddenImports: readonly [];
     };

package/dist/surfaces.js

@@ -29,7 +29,7 @@ const SURFACES = {
       "sub-16-input-font",
       "mantine-shade-index"
     ],
-    description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)",
+    description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)",
     optionalPeers: [
       "react-markdown",
       "remark-gfm",

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.23.0
+# basalt-ui v1.24.0
 # 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,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.23.0
+Version: 1.24.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)
+Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)
 Layer: mantine-coupled
 Rule: basalt-mantine
 OptionalPeers: react-markdown@^10.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.3.0, shiki@^4.3.0, beautiful-mermaid@^1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "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/check-theme.test.ts

@@ -654,6 +654,40 @@ describe('check-theme scans .css', () => {
   })
 })
 
+// Round 9, rollhook: `SCANNABLE_EXT` stopped at `tsx?|css|html?|webmanifest`, so the marketing
+// site's two `.astro` templates — its ENTIRE markup layer — were never opened, and check-theme
+// reported a clean 4-file scan. `.jsx` and `.vue` were missing from the same regex, so a plain-JS
+// or Vue consumer was unguarded end to end.
+describe('check-theme scans the component extensions it was skipping', () => {
+  it('flags a raw hex in an .astro template', () => {
+    fixtureAt('pages/index.astro', '<style>\n  .hero { color: #ff0000; }\n</style>\n')
+    const { code, err } = run()
+    expect(code).toBe(1)
+    expect(err).toContain('raw-hex')
+    expect(err).toContain('index.astro')
+  })
+
+  it('flags a raw hex in a .vue single-file component', () => {
+    fixtureAt('components/Hero.vue', '<style>\n  .hero { color: #ff0000; }\n</style>\n')
+    const { code, err } = run()
+    expect(code).toBe(1)
+    expect(err).toContain('Hero.vue')
+  })
+
+  it('flags a raw inline border in a .jsx component', () => {
+    fixtureAt('Card.jsx', `export const C = () => <div style={{ border: '1px solid #ccc' }} />\n`)
+    const { code, err } = run()
+    expect(code).toBe(1)
+    expect(err).toContain('raw-surface')
+    expect(err).toContain('Card.jsx')
+  })
+
+  it('stays quiet on a clean .astro file — the extension is scanned, not condemned', () => {
+    fixtureAt('pages/index.astro', '<style>\n  .hero { color: var(--vx-ink); }\n</style>\n')
+    expect(run().code).toBe(0)
+  })
+})
+
 describe('check-theme comment skipping', () => {
   it('does NOT flag a banned element mentioned in a pure line comment', () => {
     fixtureAt(

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')
+  })
+})