basalt-ui 1.27.0 → 1.29.0

package/src/agent-chat/thread-workspace.tsx

@@ -32,46 +32,58 @@
  *   )
  * }
  */
-import { Box, Divider, Flex, Skeleton, Stack, Text } from '@mantine/core'
+import { Box, Divider, Flex, Skeleton, Stack, Text, useMantineTheme } from '@mantine/core'
 import { useMediaQuery } from '@mantine/hooks'
 import type { JSX, ReactNode } from 'react'
 import type { AgentPart, AgentTransport, OutcomeResolver, ThreadsStore } from '../agent'
 import { useAgentThreadRuns } from '../agent'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { VX } from '../tokens'
 import { Composer } from './composer'
 import { ThreadDetailPanel } from './thread-detail-panel'
 import { ThreadFeed } from './thread-feed'
 
-const NARROW_BREAKPOINT = '(max-width: 768px)'
 const DETAIL_PANEL_WIDTH = 'clamp(440px, 40%, 520px)'
 
-export type ThreadWorkspaceProps = {
-  /**
-   * The thread-store hook, created ONCE at module scope via `createThreadsStore` and passed in —
-   * ThreadWorkspace must not call `createThreadsStore` itself.
-   */
-  readonly useThreads: () => ThreadsStore
-  /** The injected transport seam — one stream per `start()` call. */
-  readonly transport: AgentTransport<AgentPart, string>
-  /** Distills a finished thread into a feed-ready `AgentOutcome`. */
-  readonly resolveOutcome: OutcomeResolver<AgentPart>
-  /** Placeholder for the new-thread composer pinned under the feed. */
-  readonly newThreadPlaceholder?: string
-  /**
-   * Rendered in place of the feed once the store is hydrated and there really are no threads.
-   * Shown ONLY when `store.hydrated` is true — while an async store's initial load is still in
-   * flight, `ThreadWorkspace` holds a neutral loading state instead (see `FeedHydratingState`),
-   * so a server-backed workspace never asserts "no threads yet" before it actually knows that.
-   */
-  readonly emptyState?: ReactNode
-  /**
-   * Rendered in place of the feed when the store's initial load has failed — `!store.hydrated &&
-   * store.error !== undefined` (see `ThreadsStore.hydrated`'s doc for the discriminant). Shown
-   * instead of `FeedHydratingState`, so a rejected `listThreads` surfaces a legible failure rather
-   * than an endless skeleton.
-   */
-  readonly errorState?: ReactNode
-}
+// Static across every instance, so it stays a module-level constant rather than a per-render
+// literal, letting the no-override case keep a stable reference.
+const FULL_HEIGHT_STYLE = { height: '100%' } as const
+
+/** The four boxes `ThreadWorkspace` paints: `root` is the outermost pane split, `feed` is the
+ * thread-list pane, `composer` is the new-thread composer pinned under the feed, `detail` is the
+ * right-hand (or, below 768px, full-screen) open-thread pane. */
+export type ThreadWorkspaceSlot = 'root' | 'feed' | 'composer' | 'detail'
+
+export type ThreadWorkspaceProps = BasaltProps &
+  SlotStylesProps<ThreadWorkspaceSlot> & {
+    /**
+     * The thread-store hook, created ONCE at module scope via `createThreadsStore` and passed in —
+     * ThreadWorkspace must not call `createThreadsStore` itself.
+     */
+    readonly useThreads: () => ThreadsStore
+    /** The injected transport seam — one stream per `start()` call. */
+    readonly transport: AgentTransport<AgentPart, string>
+    /** Distills a finished thread into a feed-ready `AgentOutcome`. */
+    readonly resolveOutcome: OutcomeResolver<AgentPart>
+    /** Placeholder for the new-thread composer pinned under the feed. */
+    readonly newThreadPlaceholder?: string
+    /**
+     * Rendered in place of the feed once the store is hydrated and there really are no threads.
+     * Shown ONLY when `store.hydrated` is true — while an async store's initial load is still in
+     * flight, `ThreadWorkspace` holds a neutral loading state instead (see `FeedHydratingState`),
+     * so a server-backed workspace never asserts "no threads yet" before it actually knows that.
+     */
+    readonly emptyState?: ReactNode
+    /**
+     * Rendered in place of the feed when the store's initial load has failed — `!store.hydrated &&
+     * store.error !== undefined` (see `ThreadsStore.hydrated`'s doc for the discriminant). Shown
+     * instead of `FeedHydratingState`, so a rejected `listThreads` surfaces a legible failure rather
+     * than an endless skeleton.
+     */
+    readonly errorState?: ReactNode
+  }
 
 /** Default hint shown in the feed pane once hydrated with no threads (overridable via `emptyState`). */
 function FeedEmptyState(): JSX.Element {
@@ -146,10 +158,19 @@ export function ThreadWorkspace({
   newThreadPlaceholder,
   emptyState,
   errorState,
+  className,
+  style,
+  classNames,
 }: ThreadWorkspaceProps): JSX.Element {
+  assertRequiredProps('ThreadWorkspace', { useThreads }, ['useThreads'])
   const store = useThreads()
   const runs = useAgentThreadRuns({ transport, store, resolveOutcome })
-  const narrow = useMediaQuery(NARROW_BREAKPOINT)
+  // Matches `shell/page-aside.tsx`'s own `theme.breakpoints.sm` desktop check — read off the theme,
+  // not hardcoded, so a consumer that retunes `breakpoints.sm` moves the aside and this workspace
+  // together. `max-width` is the min-width complement: `sm − 0.00625em` (the same 0.1px offset
+  // Mantine's own CSS breakpoints use), so the two checks never straddle the same pixel.
+  const theme = useMantineTheme()
+  const narrow = useMediaQuery(`(max-width: calc(${theme.breakpoints.sm} - 0.00625em))`)
 
   const threads = store.threads
   const activeThread = threads.find((thread) => thread.id === store.activeId) ?? null
@@ -186,7 +207,12 @@ export function ThreadWorkspace({
   // A plain pane, NOT a card — the feed's own rows carry the card idiom (docs/DESIGN-SPEC.md §5),
   // so this pane stays flush with the page and the feed/detail split reads via the divider token.
   const feed = (
-    <Flex direction="column" h="100%" style={{ overflow: 'hidden' }}>
+    <Flex
+      direction="column"
+      h="100%"
+      className={cx(classNames?.feed)}
+      style={{ overflow: 'hidden' }}
+    >
       <Box style={{ flex: 1, minHeight: 0 }}>
         {threads.length === 0 ? (
           store.hydrated ? (
@@ -205,6 +231,7 @@ export function ThreadWorkspace({
         <Composer
           onSubmit={({ text }) => handleNewThread(text)}
           {...(newThreadPlaceholder !== undefined ? { placeholder: newThreadPlaceholder } : {})}
+          {...(classNames?.composer !== undefined && { className: classNames.composer })}
         />
       </Box>
     </Flex>
@@ -219,15 +246,27 @@ export function ThreadWorkspace({
       onStop={handleStop}
       onRetry={handleRetry}
       onClose={() => store.select(null)}
+      {...(classNames?.detail !== undefined && { className: classNames.detail })}
     />
   )
 
   if (narrow) {
-    return <Box style={{ height: '100%' }}>{store.activeId !== null ? detail : feed}</Box>
+    return (
+      <Box
+        className={cx(classNames?.root, className)}
+        style={style ? { ...FULL_HEIGHT_STYLE, ...style } : FULL_HEIGHT_STYLE}
+      >
+        {store.activeId !== null ? detail : feed}
+      </Box>
+    )
   }
 
   return (
-    <Flex style={{ height: '100%' }} gap="md">
+    <Flex
+      className={cx(classNames?.root, className)}
+      style={style ? { ...FULL_HEIGHT_STYLE, ...style } : FULL_HEIGHT_STYLE}
+      gap="md"
+    >
       <Box
         style={{
           flex: 1,

package/src/agent-chat/tool-chip.tsx

@@ -21,6 +21,9 @@ import { useDisclosure } from '@mantine/hooks'
 import type { JSX } from 'react'
 import { isToolCallSettled } from '../agent'
 import type { ToolCallPart } from '../agent'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { alpha, VX } from '../tokens'
 
 // Mirrors thread-message.tsx's micro-label/rail/code-block idiom (docs/DESIGN-SPEC.md §3/§5) —
@@ -96,7 +99,7 @@ function formatDuration(ms: number): string {
   return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`
 }
 
-export type ToolChipProps = {
+export type ToolChipProps = BasaltProps & {
   readonly part: ToolCallPart
   readonly defaultExpanded?: boolean
   /** Rendered only in 'approval-requested'. Omit both to render a read-only chip. */
@@ -119,7 +122,10 @@ export function ToolChip({
   defaultExpanded = false,
   onApprove,
   onDeny,
+  className,
+  style,
 }: ToolChipProps): JSX.Element {
+  assertRequiredProps('ToolChip', { part }, ['part'])
   const [expanded, { toggle }] = useDisclosure(defaultExpanded)
   const { label, dotToken } = stateMeta(part)
   const settled = isToolCallSettled(part)
@@ -128,7 +134,7 @@ export function ToolChip({
   const rawInput = part.state === 'output-error' ? part.rawInput : undefined
 
   return (
-    <Box style={RAIL_STYLE}>
+    <Box className={cx(className)} style={style ? { ...RAIL_STYLE, ...style } : RAIL_STYLE}>
       <Stack gap={4}>
         <UnstyledButton onClick={toggle}>
           <Group gap={6} align="center" wrap="nowrap">

package/src/agent-chat/virtualize.ts

@@ -112,6 +112,54 @@ export type ResolvedVirtualize = {
   readonly height: number | string
 }
 
+/**
+ * `ThreadFeedRow`'s OWN height contract (B3) — a strict superset of {@link VirtualizeProps} that
+ * additionally allows `height` WITHOUT `virtualize`. This is deliberately NOT a widening of
+ * `VirtualizeProps` itself (see `virtualize.type-guard.test.ts`, which pins that union rejecting
+ * `{ height }` with no `virtualize`): the two `height` modes mean different things and route to
+ * different DOM. `virtualize: true|VirtualizeOptions` + `height` still hands the row's transcript a
+ * fixed-size scroll container `@tanstack/react-virtual` owns and measures (unchanged, forwarded to
+ * `ThreadTranscript` via `resolveVirtualize`). `height` ALONE — no `virtualize` — wraps the row's
+ * TRANSCRIPT in a fixed-height `BasaltStickToBottom` (the same auto-follow-the-live-turn container
+ * `ThreadDetailPanel` already uses), leaving the composer outside/below it: a bounded, scrolling
+ * row for a thread the caller does not want to virtualize (argo's hermes-chat S7 — a 480px
+ * transcript body with inner scroll, no `@tanstack/react-virtual` peer installed).
+ */
+export type RowHeightProps =
+  | { readonly virtualize?: false; readonly height?: number | string }
+  | { readonly virtualize: true | VirtualizeOptions; readonly height: number | string }
+
+/** The resolved shape of {@link RowHeightProps} — exactly one of the three row body layouts. */
+export type ResolvedRowHeight =
+  | { readonly kind: 'virtualized'; readonly virtualize: ResolvedVirtualize }
+  | { readonly kind: 'bounded'; readonly height: number | string }
+  | { readonly kind: 'content-sized' }
+
+/**
+ * The single narrowing point `ThreadFeedRow` resolves {@link RowHeightProps} through — mirrors
+ * {@link resolveVirtualize}'s role for `VirtualizeProps`, extended with the `'bounded'` branch B3
+ * adds. Runtime-checked rather than routed through `resolveVirtualize` itself: `RowHeightProps`'
+ * inactive branch relaxes `height` from `never` to `number | string | undefined`, which is NOT
+ * structurally assignable to `VirtualizeProps` (by design — see this type's own doc), so the two
+ * resolvers stay independent rather than one calling the other with a cast.
+ */
+export function resolveRowHeight(props: RowHeightProps): ResolvedRowHeight {
+  const { virtualize, height } = props
+  if (virtualize === true || (typeof virtualize === 'object' && virtualize !== null)) {
+    // The union guarantees `height` is present on this branch — see resolveVirtualize's own doc
+    // for why the pairing is re-stated here instead of narrowed automatically.
+    return {
+      kind: 'virtualized',
+      virtualize: {
+        options: virtualize === true ? {} : virtualize,
+        height: height as number | string,
+      },
+    }
+  }
+  if (height !== undefined) return { kind: 'bounded', height }
+  return { kind: 'content-sized' }
+}
+
 /**
  * Narrows a `VirtualizeProps` pair once, centrally: `null` when virtualization is off, otherwise
  * the options object (normalizing the bare `virtualize: true` shorthand to `{}`) alongside the

package/src/charts/hooks/useBandPlot.ts

@@ -17,12 +17,12 @@
 import { scaleBand } from '@visx/scale'
 import { useCallback, useMemo, useRef } from 'react'
 import type { ReactNode, RefObject } from 'react'
-import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
 import { autoMargin } from '../layout/auto-margin'
+import { useChartTierMetrics } from '../primitives/chart-tier'
 import { maxTextWidth } from '../utils/measure-text'
-import { smartTicks } from '../utils/ticks'
+import { smartTicks, xLabelPxFor } from '../utils/ticks'
 import { useChartCursor } from './useChartCursor'
 import type { ChartCursor, CursorAnchor } from './useChartCursor'
 
@@ -177,6 +177,12 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     tooltip,
   } = input
 
+  // The tier `ChartFrame` resolved from its own MEASURED width. A banded plot needs exactly the
+  // two things `CartesianChart` reads off it: the tick font its gutters are MEASURED at (the same
+  // one `AxisBottomDate` paints — measured labels must be the painted labels, §1) and the tightened
+  // margin FLOORS (`docs/CHARTS-SPEC.md` §8).
+  const tier = useChartTierMetrics()
+
   const hasLeftAxis = leftLabels !== undefined && leftLabels.length > 0
   const xLabelsAll = useMemo(() => data.map((d) => formatX(getX(d))), [data, getX, formatX])
 
@@ -185,11 +191,13 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     const measured = autoMargin({
       ...(leftLabels !== undefined && { left: leftLabels }),
       bottom: xLabelsAll,
+      fontPx: tier.axisFont,
+      floor: tier.margin,
       ...(marginOverride !== undefined && { override: marginOverride }),
     })
     if (marginOverride?.left !== undefined && marginOverride.right !== undefined) return measured
 
-    const halfXLabel = Math.ceil(maxTextWidth(xLabelsAll, VX.axisFont) / 2)
+    const halfXLabel = Math.ceil(maxTextWidth(xLabelsAll, tier.axisFont) / 2)
     // A band axis puts its FIRST tick on the plot's left edge, so the left gutter needs the same
     // half-label law `autoMargin` already applies on the right. `autoMargin` cannot know that —
     // its left law measures a left AXIS, which a band plot may not have.
@@ -199,18 +207,18 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
       ...(marginOverride?.left === undefined && {
         left: hasLeftAxis
           ? left
-          : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, VX.margin.left),
+          : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, tier.margin.left),
       }),
       ...(marginOverride?.right === undefined && {
         right: capTerminalGutter(
           measured.right,
           width,
           TERMINAL_GUTTER_MAX_FRACTION.right,
-          VX.margin.right,
+          tier.margin.right,
         ),
       }),
     }
-  }, [leftLabels, xLabelsAll, marginOverride, hasLeftAxis, width])
+  }, [leftLabels, xLabelsAll, marginOverride, hasLeftAxis, width, tier.axisFont, tier.margin])
 
   const plotWidth = Math.max(width - margin.left - margin.right, 0)
 
@@ -250,11 +258,21 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
+  // The horizontal room one x tick label needs, from the labels `smartTicks` could actually pick —
+  // same measured-spacing law `CartesianChart` applies (`docs/CHARTS-SPEC.md` §1). `keys` (not
+  // `xLabelsAll`) because ticks are chosen from the post-fold key list.
+  const xLabelPx = useMemo(
+    () => xLabelPxFor(keys.map(formatX), tier.axisFont),
+    [keys, formatX, tier.axisFont],
+  )
+
   const tickValues = useMemo(
     () => [
-      ...(xTickValues === undefined ? smartTicks(keys, plotWidth) : xTickValues(keys, plotWidth)),
+      ...(xTickValues === undefined
+        ? smartTicks(keys, plotWidth, xLabelPx)
+        : xTickValues(keys, plotWidth)),
     ],
-    [keys, plotWidth, xTickValues],
+    [keys, plotWidth, xTickValues, xLabelPx],
   )
 
   const svgRef = useRef<SVGSVGElement>(null)

package/src/charts/index.ts

@@ -42,6 +42,8 @@ export {
 export {
   type SeriesMark,
   type SeriesDash,
+  type SeriesCurve,
+  curveFor,
   type SeriesRole,
   type LegendPlacement,
   type ChartLegendConfig,
@@ -73,10 +75,25 @@ export {
   type ChartCenterProps,
   ChartPending,
   type ChartPendingProps,
+  ChartEmpty,
+  type ChartEmptyProps,
+  ChartError,
+  type ChartErrorProps,
+  type ChartState,
+  type ResolvedChartState,
+  resolveChartState,
 } from './primitives/ChartPending'
+export {
+  useChartTier,
+  useChartTierMetrics,
+  chartTierMetrics,
+  resolveChartTier,
+  type ChartTier,
+  type ChartTierMetrics,
+} from './primitives/chart-tier'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern'
-export { ChartCard, type ChartCardProps } from './primitives/ChartCard'
+export { ChartCard, type ChartCardProps, type ChartCardSlot } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'
 export {
   ChartTooltipFloat,
@@ -84,7 +101,12 @@ export {
   TooltipRow,
   TooltipBody,
 } from './primitives/ChartTooltip'
-export { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './primitives/Axes'
+export {
+  AxisBottomDate,
+  AxisBottomNumeric,
+  AxisLeftNumeric,
+  AxisRightNumeric,
+} from './primitives/Axes'
 export { HoverOverlay } from './primitives/HoverOverlay'
 export { ZoneRects, type ZoneSpec } from './primitives/ZoneRects'
 export { XZoneRects, type XZoneSpec } from './primitives/XZoneRects'
@@ -102,8 +124,19 @@ export type { CursorResolution, DomainKind } from './cursor/resolve'
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize'
 
 // ── Utils ────────────────────────────────────────────────────────────────
-export { fmtAxisDate, fmtTooltipDate } from './utils/format'
-export { smartTicks, smartTicksEvery } from './utils/ticks'
+export {
+  fmtAxisDate,
+  fmtTooltipDate,
+  fmtCompact,
+  type FmtCompactOptions,
+  fmtPercent,
+  type FmtPercentOptions,
+  fmtCurrency,
+  type FmtCurrencyOptions,
+  fmtInt,
+  formatters,
+} from './utils/format'
+export { smartTicks, smartTicksEvery, xLabelPxFor, autoXLabelRotate } from './utils/ticks'
 export { autoMargin, probeAxisLabels, type AutoMarginInput } from './layout/auto-margin'
 export { measureText, maxTextWidth } from './utils/measure-text'
 
@@ -111,19 +144,11 @@ export { measureText, maxTextWidth } from './utils/measure-text'
 export {
   ZonedLine,
   type ZonedLineProps,
-  type ZonedLineZone,
   type ZonedLineThreshold,
   type ZonedLineRefLine,
 } from './kinds/ZonedLine'
 
-export {
-  Bars,
-  type BarsProps,
-  type BarsBar,
-  type BarsLine,
-  type BarsZone,
-  type BarsRefLine,
-} from './kinds/Bars'
+export { Bars, type BarsProps, type BarsBar, type BarsLine, type BarsRefLine } from './kinds/Bars'
 
 export { StackedArea, type StackedAreaProps } from './kinds/StackedArea'
 export { Donut, type DonutProps, type DonutDatum } from './kinds/Donut'
@@ -140,7 +165,12 @@ export {
 export { MirroredBars, type MirroredBarsProps, type MirroredBarPane } from './kinds/MirroredBars'
 
 // ── Sparklines ───────────────────────────────────────────────────────────
-export { LineSparkline, BarSparkline } from './sparklines'
+export {
+  LineSparkline,
+  type LineSparklineProps,
+  BarSparkline,
+  type BarSparklineProps,
+} from './sparklines'
 
 // ── Re-exported visx primitives ──────────────────────────────────────────
 // Bespoke charts (genuinely unique compositions per CLAUDE.md) need raw
@@ -155,6 +185,8 @@ export {
   curveMonotoneX,
   curveLinear,
   curveCatmullRom,
+  curveStep,
   curveStepAfter,
+  curveStepBefore,
   curveBasis,
 } from '@visx/curve'

package/src/charts/kinds/BandStrip.tsx

@@ -1,6 +1,8 @@
 import { Group } from '@visx/group'
 import { memo, useMemo } from 'react'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import { VX, alpha } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
@@ -17,8 +19,10 @@ import {
 import { Crosshair } from '../primitives/Crosshair'
 import { HatchPattern, hatchFill, hatchSizeFor } from '../primitives/HatchPattern'
 import { HoverOverlay } from '../primitives/HoverOverlay'
+import type { ChartState } from '../primitives/ChartPending'
 import type { ChartLegendConfig, SeriesStyle } from '../series'
 import { fmtAxisDate } from '../utils/format'
+import { isDev } from '../../common/is-dev'
 
 /**
  * A state a strip can draw. Extends `SeriesStyle` rather than `ChartSeries` because a band has no
@@ -78,7 +82,7 @@ export type BandSpan = {
   }
 }
 
-export type BandStripProps<T> = {
+export type BandStripProps<T> = BasaltProps & {
   data: readonly T[]
   /** Stable id — identifies this chart as the cursor's source. */
   chartId: string
@@ -110,8 +114,10 @@ export type BandStripProps<T> = {
   cursorResolution?: CursorResolution
   tooltip?: BandTooltipConfig<T> | false
   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
+  /** Colour of the absence hatch, AND the state that is absent. 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. A slot in this state hatches across its whole width unless its own `absentFraction`
+   * says otherwise; a slot in any other state hatches only its `absentFraction`. Default
    * `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
@@ -122,6 +128,9 @@ export type BandStripProps<T> = {
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 const DEFAULT_MARKER_INSET = 6
@@ -142,13 +151,6 @@ const UNKNOWN_MARK = {
   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.
  *
@@ -187,7 +189,12 @@ function formatBandValue<T>(style: BandStripSeries<T>, datum: T): string {
  * nothing measured, and a fact that must not be read off the ramp.
  */
 function BandStripInner<T>(props: BandStripProps<T>) {
-  const { series, chartId, height, fill, legend, ariaLabel, isPending } = props
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('BandStrip', props, ['data', 'getX', 'series', 'getBand'])
+  const { series, chartId, height, fill, legend, ariaLabel, isPending, state, className, style } =
+    props
 
   return (
     <ChartFrame
@@ -197,6 +204,9 @@ function BandStripInner<T>(props: BandStripProps<T>) {
       {...(fill !== undefined && { fill })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <BandStripPlot {...props} plot={plot} />}
@@ -279,7 +289,15 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
       // 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)
+      // A slot whose STATE is the absent one is absent in whole — `absentState` and
+      // `absentFraction` are two ways of saying the same thing, and gating the hatch on the
+      // fraction alone meant a strip declaring `absentState` painted a flat fill while the docs,
+      // the demo and its own `<pattern>` all promised hatching. An explicit `absentFraction` still
+      // wins: a partially-covered slot in the absent state says so itself.
+      const absent =
+        span.state === absentState
+          ? clampFraction(span.absentFraction ?? 1)
+          : clampFraction(span.absentFraction)
       const measuredWidth = bandWidth * (1 - absent)
       const hatchWidth = bandWidth - measuredWidth
       const markerKey = span.marker?.state ?? span.state
@@ -327,7 +345,7 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
       )
     })
     return out
-  }, [bands, getBand, getX, styleByKey, hidden, bandWidth, step, stripHeight, hatchId])
+  }, [bands, getBand, getX, styleByKey, hidden, bandWidth, step, stripHeight, hatchId, absentState])
 
   if (plotWidth <= 0 || bands.length === 0) return null
 
@@ -454,4 +472,8 @@ function deriveBandRow<T>(
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot kind is wrapped in
  * `React.memo` to retain the auto-memoization it had as source (parity with `DualPanel`).
  */
-export const BandStrip = memo(BandStripInner) as typeof BandStripInner
+const BandStripMemo = memo(BandStripInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+BandStripMemo.displayName = 'BandStrip'
+export const BandStrip = BandStripMemo as typeof BandStripInner