basalt-ui 1.13.0 → 1.15.0

package/agent/skills/basalt-charts/SKILL.md

@@ -1,46 +1,61 @@
 ---
 name: basalt-charts
-description: Add or extend a chart in a basalt-ui app — pick a kind vs go bespoke (Rule of Three), register a consumer series with defineSeries/groupTokens (since VX.series is app-side, not shipped), compose the visx primitives, and respect the @visx-only-in-charts + Mantine-free boundary. Use when adding a new chart, a new metric/series color, or extracting a repeated chart shape into a kind.
+description: Add or extend a chart in a basalt-ui app — pick a kind vs go bespoke (Rule of Three), register a consumer series with defineSeries/groupTokens (since VX.series is app-side, not shipped), compose CartesianChart (or ChartFrame directly for a non-single-plot shape), and respect the @visx-only-in-charts + Mantine-free boundary. Use when adding a new chart, a new metric/series color, or extracting a repeated chart shape into a kind.
 when_to_use: User wants to add a chart, restyle an existing one structurally, introduce a new metric/series and its color, extract a recurring chart shape into a reusable kind, or asks where chart series colors live / how to register them. The how-to companion to /basalt-design (which owns the aesthetic law).
 ---
 
 `/basalt-charts` is the how-to for the chart system. `/basalt-design` owns the aesthetic law
 (palette, restraint, the theme-lab loop) and the DESIGN.md precedence — read it for "what color /
 how should this look". This skill answers "how do I wire it" with basalt-ui's `./charts` and
-`./tokens` surfaces.
+`./tokens` surfaces. `docs/CHARTS-SPEC.md` is the ground truth for the chart-primitive contract
+everything below assumes — composing `CartesianChart` (single-plot) or `ChartFrame` directly
+(multi-pane/radial/matrix) is mandatory, mechanically enforced (see "Respect the boundary" below).
 
 ## The decision: kind vs bespoke (Rule of Three)
 
 Before writing chart code, decide which of three paths you are on:
 
-1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `Donut`,
-   `MultiLine`, `DualPanel`, `Heatmap`. If the shape matches, use it — props are declarative (data,
-   width/height, `getX`/`getY` accessors, zones/thresholds/refLines as plain arrays, `seriesLabel`,
-   `formatValue`). Done.
-   - **`MultiLine`** — N series on a shared y-axis: legend-hover dimming, per-series synced dots,
-     dashed companion (MA) lines, per-point markers (PR stars / status dots), zones + refLines,
-     fixed or auto domain (also covers z-score/σ charts via a fixed symmetric domain + zero
-     refLine). Replaces bespoke multi-line / relative-progression / training-load /
-     strength-composite / fitness-trends.
+1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`,
+   `DualPanel`, `Heatmap`, `Donut`. If the shape matches, use it — props are declarative (`data`,
+   `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per axis, zones/thresholds/refLines
+   as plain arrays). Done.
+   - **`ZonedLine`** — a single-series line with zone bands, thresholds, x-zones, refLines.
+   - **`Bars`** — 1+ stacked positive/negative bar series, optional line overlays, dual-axis config.
+   - **`StackedArea`** — opaque stacked bands, auto cumulative-top y-domain.
+   - **`MultiLine`** — N series on a shared y-axis (or two, via `y2`): legend-hover dimming,
+     per-series synced dots, dashed companion (MA) lines, per-point markers (PR stars / status
+     dots), zones + refLines, fixed or auto domain (also covers z-score/σ charts via a fixed
+     symmetric domain + zero refLine). Replaces bespoke multi-line / relative-progression /
+     training-load / strength-composite / fitness-trends.
    - **`DualPanel`** — top line-pane + bottom signed-histogram pane sharing ONE x-scale and ONE
      cursor; optional fill-between two top lines, zones, refLines. Replaces bespoke divergence /
      momentum.
    - **`Heatmap`** — category×category intensity grid (`color-mix` alpha), per-cell tooltip,
      optional gradient legend strip. Replaces bespoke time-of-day.
+   - **`Donut`** — proportional donut, optional `centerContent` overlay.
 2. **Extract a new kind (second instance of a pattern).** When you are about to build the _second_
    chart of a shape that has no shipped kind, extract a kind. Don't extract on the first; don't
    wait past the third. A new kind lives in the consumer's chart kinds dir (or, if generic enough
    to promote, gets contributed to basalt-ui `src/charts/kinds/`). Migrate both call sites onto it.
-3. **Stay bespoke (genuinely unique).** A one-off dual-panel shape (e.g. MACD) composes the
-   primitives directly in the page's chart file — not in `kinds/`.
+   A single-plot kind composes `CartesianChart`, drawing only marks; a multi-pane or non-cartesian
+   kind composes `ChartFrame` directly (see "Compose the primitives" below).
+3. **Stay bespoke (genuinely unique).** A one-off shape (e.g. a dual-panel MACD, or two series on
+   genuinely different scales that don't fit any kind's config surface) composes `CartesianChart`
+   or `ChartFrame` directly in the page's chart file — not in `kinds/`.
 
 > Anti-pattern: a single `<Chart type="..." config={...} />` god-component that switches by kind.
 > That is the Recharts trap. Prefer N small kinds. **If a chart doesn't fit the primitives, add a
 > kind — don't loosen the primitives.**
 
-A good kind's props: `data`, `width`, `height`, `chartId`, generic `getX`/`getY` accessors, zones /
-thresholds / refLines arrays, `seriesLabel`, `formatValue`, optional `tooltipLabel`. Bespoke escape
-hatches (`renderExtraTooltipRows`) are fine; they must not grow into a god-object config.
+A good kind's props: `data`, `chartId`, generic `getX` accessor, `height`/`aspectRatio`/`fill`,
+zones / thresholds / refLines arrays, one `AxisConfig` object per axis, `series: ChartSeries<T>[]`
+as the single source of truth for color/label/legend/tooltip. Bespoke escape hatches
+(`tooltip.extraRows`, `tooltip.prependRows`) are fine; they must not grow into a god-object config.
+
+`ZonedLine` and `MultiLine` also take `xZones?: XZoneSpec[]` — vertical time-window bands, the
+counterpart to the horizontal zones above. `{ from?, to?, fill }` bounds are `getX` **domain keys**
+(the label string, not a date/timestamp); an omitted bound is the plot edge, a key missing from the
+domain skips the band rather than clamping to one.
 
 ## Register a consumer series (VX.series is app-side)
 
@@ -84,73 +99,95 @@ export const PALETTE_CSS = buildPaletteCss({
 - Inject `PALETTE_CSS` once (BasaltProvider injects the framework palette; the consumer appends its
   series CSS — or passes `injectPalette={false}` and head-injects both).
 - Then charts read `SERIES.hrv`, never a hex. This is what keeps `basalt-ui check-theme` green.
+- A series with nothing visible to point at (flat at the domain floor, all-zero) can still carry a
+  qualifier: pass `note` on the series' `SeriesStyle` (flows to `LegendEntry.note` via
+  `deriveLegend`) and `ChartLegend` renders it, muted, after the label.
 
 Theme tuning of these series happens in the theme lab — pass them as `groups` to
 `ThemeLabControls` (see `/basalt-design`).
 
 ## Compose the primitives (never hand-roll)
 
-Every chart — kind or bespoke — composes the shipped primitives. The contract is social and
-lint-backed; it is easier to compose them than to work around them.
+Every chart — kind or bespoke — composes `CartesianChart` for a single plot rect, or `ChartFrame`
+directly for a multi-pane / non-cartesian shape (`DualPanel`'s two panes, `Heatmap`'s grid,
+`Donut`'s ring). Either way the contract is the same: the primitive owns margin, scales, grid,
+axes, legend, the shared cursor, and the tooltip; you supply `series` and draw ONLY marks. This is
+mandatory, not a convention — `basalt/hand-rolled-plot` fails the build on a bypass (see "Respect
+the boundary" below); it is easier to compose it than to work around it.
+
+**The common case — a single-plot chart:**
 
 ```tsx
-import {
-  ChartCard,
-  ChartLegend,
-  AxisBottomDate,
-  AxisLeftNumeric,
-  HoverOverlay,
-  AreaGradient,
-  areaFillUrl,
-  ChartTooltip,
-  TooltipHeader,
-  TooltipRow,
-  useChartTooltip,
-  useHoverSync,
-  VX,
-  alpha,
-} from 'basalt-ui/charts' // ./charts re-exports the token layer too
+import { CartesianChart, LinePath, curveMonotoneX, VX } from 'basalt-ui/charts'
+import type { ChartSeries } from 'basalt-ui/charts'
 import { SERIES } from '../lib/series'
 
-function HrvChart({ data, width, height }: HrvChartProps) {
-  const tip = useChartTooltip<HrvPoint>()
-  // ... scales ...
+type HrvPoint = { date: string; hrv: number }
+
+const HRV_SERIES: ChartSeries<HrvPoint>[] = [
+  { key: 'hrv', label: 'HRV', color: SERIES.hrv, mark: 'line', getValue: (d) => d.hrv },
+]
+
+function HrvChart({ data }: { data: HrvPoint[] }) {
   return (
-    <ChartCard title="HRV" info="7-day rolling">
-      <svg width={width} height={height}>
-        <AreaGradient id="hrv" color={SERIES.hrv} />
-        {/* ...LinePath fill={areaFillUrl('hrv')} stroke={SERIES.hrv}... */}
-        <AxisLeftNumeric scale={yScale} /* tokenized ticks */ />
-        <AxisBottomDate scale={xScale} />
-        <HoverOverlay {...tip.overlayProps} />
-      </svg>
-      <ChartLegend entries={[{ label: 'HRV', color: SERIES.hrv, shape: 'line' }]} />
-      <ChartTooltip {...tip.tooltipProps}>
-        <TooltipHeader>{/* date */}</TooltipHeader>
-        <TooltipRow swatch={SERIES.hrv} label="HRV" value={/* ... */} />
-      </ChartTooltip>
-    </ChartCard>
+    <CartesianChart
+      data={data}
+      chartId="hrv"
+      getX={(d) => d.date}
+      series={HRV_SERIES}
+      y={{ domain: 'auto', format: (v) => `${Math.round(v)} ms` }}
+      height={240}
+    >
+      {({ xScale, yScale, visible }) =>
+        visible.map((s) => (
+          <LinePath<HrvPoint>
+            key={s.key}
+            data={data}
+            x={(d) => xScale(d.date) ?? 0}
+            y={(d) => yScale(s.getValue(d) ?? 0)}
+            stroke={s.color}
+            strokeWidth={VX.lineWidth}
+            curve={curveMonotoneX}
+          />
+        ))
+      }
+    </CartesianChart>
   )
 }
 ```
 
-Never substitute: hand-rolled legend markup, a raw `<AxisLeft>`/`<AxisBottom>`, a direct
-`@visx/tooltip` import, or an `rgba()` fill. Use `ChartLegend`, the tokenized axes, `ChartTooltip`,
-and `alpha(token, a)`. Sparklines (`charts/sparklines/`) are the one exemption from the
-Card/Legend/Tooltip composition — but they still use `VX.*` tokens.
+`CartesianChart` draws the grid, both axes, the shared cursor + crosshair + dots, and the derived
+tooltip for you — `HrvChart` above draws nothing but the line: no hover wiring, no manual
+`<AxisLeft>`/`<AxisBottom>`, no tooltip assembly.
+
+**Dual-axis is `y2`, not a flag.** Passing `y2` is what turns on the right axis (margin widens by
+measurement); a series opts in with `axis: 'right'` on its `ChartSeries` entry. See
+`apps/playground/src/demo/ChartsPage.tsx`'s `SessionsRevenueChart` for a full worked example (two
+series on genuinely different scales — session counts vs. `$k` revenue — composed directly from
+`CartesianChart` because no shipped kind's config surface covers a dual-axis line pair).
+
+Never substitute: hand-rolled legend markup, a raw `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>`, a
+direct `@visx/tooltip` import, or an `rgba()` fill. Sparklines (`charts/sparklines/`) are the one
+exemption from the `CartesianChart`/legend/tooltip composition — but they still use `VX.*` tokens.
+
+## The cursor is shared by default
 
-## Cross-chart cursor sync
+No provider needed. `useChartCursor` reads a module-level external store, so every chart on the
+page — kind or bespoke, `CartesianChart` or `ChartFrame` — shares one cursor out of the box, and
+resolution is **domain-aware** (nearest parsed date/number within a chart's own step, not exact
+string match), so a chart that folds its calendar into weekly buckets still tracks a hover from an
+unfolded daily sibling.
 
-Wrap a group of date-aligned charts in `ChartHoverSync` (from `basalt-ui/charts`) to activate
-cross-chart cursor sync — hovering one chart casts a ghost crosshair on every sibling. Without the
-provider, `useHoverSync` runs per-chart only (and logs a dev warning):
+Wrap a subtree in `ChartCursorScope` to **isolate** it onto a private cursor instead — the inverse
+of the old opt-in pattern, for e.g. two independent dashboards rendered side by side over the same
+calendar that must NOT sync with each other:
 
 ```tsx
-import { ChartHoverSync } from 'basalt-ui/charts'
-;<ChartHoverSync>
+import { ChartCursorScope } from 'basalt-ui/charts'
+;<ChartCursorScope>
   <ChartCard>…</ChartCard>
   <ChartCard>…</ChartCard>
-</ChartHoverSync>
+</ChartCursorScope>
 ```
 
 ## Respect the boundary (oxlint-enforced)
@@ -171,15 +208,28 @@ import { ChartHoverSync } from 'basalt-ui/charts'
 - **No raw visx axes.** `basalt-ui check-theme`'s `raw-visx-axis` guard fails the build on a raw
   `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>` inside any `/charts/` file — use the tokenized
   `AxisLeftNumeric` / `AxisRightNumeric` / `AxisBottomDate` (escape via `theme-allow`).
+- **No hand-rolled plot assembly.** `basalt/hand-rolled-plot` fails the build on a chart-assembly
+  primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
+  rendered in a file that doesn't compose `CartesianChart`. Escape: a `theme-allow` comment on the
+  first such site — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`, `Donut`) declares
+  itself. The file that defines `CartesianChart` is exempt definitionally.
+- **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
+  array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws
+  (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no
+  longer draws.
+- Both ship at `warn` in the consumer preset (`configs/oxlint.json`) for one minor and `error`
+  repo-local (the "grace minor" doctrine in `packages/basalt-ui/CLAUDE.md`) — promoting to `error`
+  in the next minor.
 
 ## Checklist for a new chart
 
 - Picked the right path: reused a kind / extracted on the second instance / stayed bespoke for a
   true one-off.
+- Composed `CartesianChart` (single plot) or `ChartFrame` directly (multi-pane / non-cartesian) —
+  never hand-assembled margin/scales/axes/cursor/tooltip.
 - Any new metric color is a `{ light, dark }` pair in the consumer series file, exposed via
   `seriesTokens`/`groupTokens`, and wired into `PALETTE_CSS` via `buildPaletteCss`.
 - Charts read `SERIES.*` / `VX.*` — `basalt-ui check-theme` green, zero raw hex.
-- Composed `ChartCard` / `ChartLegend` / tokenized axes / `ChartTooltip` — no hand-rolled markup,
-  no direct `@visx/tooltip`.
+- Marks draw `ctx.visible`, never the `series` prop, so a legend toggle actually removes them.
 - `@visx/*` stays inside chart files; chart code imports no `@mantine/*`.
 - Tuned both schemes via the theme lab where the hue needed it (defer to `/basalt-design`).

package/agent/skills/basalt-design/SKILL.md

@@ -233,9 +233,10 @@ Every chart composes the shipped primitives — never hand-rolled equivalents:
   `<AxisLeft>`/`<AxisBottom>` (they miss theme tokens + smart ticks). Now lint-enforced:
   `basalt-ui check-theme`'s `raw-visx-axis` guard fails the build on a raw axis inside a `/charts/`
   file (escape via `theme-allow`).
-- **`HoverOverlay`** + `HoverContext` + `useChartTooltip` for hover/crosshair. Wrap a group of
-  date-aligned charts in **`ChartHoverSync`** to cast a ghost crosshair across all siblings on hover
-  (without it, `useHoverSync` runs per-chart only and warns in dev).
+- **The cursor is shared by default** — `CartesianChart` wires the hover overlay, crosshair, dots
+  and tooltip itself, and every chart on the page tracks one cursor through a module-level store
+  with no provider. Reach for `useChartCursor` only in a hand-composed non-single-plot shape, and
+  for **`ChartCursorScope`** only to opt a subtree OUT of sharing.
 - **`AreaGradient`** / `areaFillUrl` for the soft single-hue fill.
 
 Shipped kinds beyond `ZonedLine` / `Bars` / `StackedArea` / `Donut`: **`MultiLine`** (N series on a

package/configs/oxlint-plugin.js

@@ -803,6 +803,156 @@ const aiSdkMajor = {
   },
 }
 
+// ── Rule 12 — hand-rolled-plot ───────────────────────────────────────────────────────────────────
+
+/**
+ * The primitives `CartesianChart` assembles. Rendering one of these directly means the file is
+ * re-implementing the plot assembly — margins, scales, axes, cursor, crosshair, tooltip — that the
+ * primitive owns for every other chart, which is exactly how charts drift apart from each other.
+ */
+const PLOT_ASSEMBLY_TAGS = new Set([
+  'AxisLeftNumeric',
+  'AxisRightNumeric',
+  'AxisBottomDate',
+  'HoverOverlay',
+  'Crosshair',
+])
+
+/**
+ * Composing this means the file is USING the chart system rather than re-implementing it.
+ * `ChartFrame` deliberately does NOT count: composing the frame directly and then hand-assembling
+ * axes and a cursor on top of it IS the drift this rule exists to catch. A genuinely non-single-
+ * plot shape does exactly that — and declares it with a `theme-allow` comment, so the exception is
+ * a decision someone wrote down rather than a default anyone can fall into.
+ */
+const PLOT_OWNER_TAGS = new Set(['CartesianChart'])
+
+/**
+ * Import sources that make a JSX tag one of BASALT's chart primitives rather than a component the
+ * consumer happens to have named `Crosshair`. Matching bare tag names would false-positive on any
+ * app with its own overlay component — and this rule ships to consumers, so that matters.
+ */
+const CHART_IMPORT_SOURCE = /(^|\/)basalt-ui\/charts|(^|\/)charts(\/|$)|(^|\.\.\/)primitives\//
+
+/** Local names imported from a basalt charts entry — the only tags either chart rule considers. */
+function collectChartImports(node, into) {
+  if (!CHART_IMPORT_SOURCE.test(node.source?.value ?? '')) return
+  for (const spec of node.specifiers ?? []) {
+    if (spec.local?.name !== undefined) into.add(spec.local.name)
+  }
+}
+
+const HAND_ROLLED_PLOT_MESSAGE =
+  'Chart assembly primitive rendered without composing CartesianChart — that primitive already ' +
+  'owns the measured margins, both y scales, the axes, grid, shared cursor, crosshair and ' +
+  'tooltip. Hand-assembling them is how two charts stop matching. Compose CartesianChart and ' +
+  'render only marks. A genuinely non-single-plot shape (multi-pane, radial, matrix) composes ' +
+  'ChartFrame instead — add a theme-allow comment to declare that. (basalt/hand-rolled-plot)'
+
+const handRolledPlot = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow assembling a cartesian plot by hand instead of composing CartesianChart.',
+    },
+    schema: [],
+  },
+  create(context) {
+    // File-scoped, not node-scoped: the verdict depends on whether a plot OWNER appears anywhere
+    // in the file, which is only known once the whole file has been walked.
+    const assemblyNodes = []
+    const chartImports = new Set()
+    let ownsPlot = false
+    let definesOwner = false
+
+    // A rule that says "compose CartesianChart" cannot fire inside the module that DEFINES
+    // CartesianChart — that file is the assembly. Detected by declaration rather than by path so
+    // it stays honest: this is definitional, not basalt exempting itself for convenience (the
+    // self-exemption habit is what let the 1.4.0 regression reach consumers — see docs/STATUS.md).
+    const notesOwnerDefinition = (name) => {
+      if (name === 'CartesianChart') definesOwner = true
+    }
+
+    return {
+      ImportDeclaration(node) {
+        collectChartImports(node, chartImports)
+      },
+      FunctionDeclaration(node) {
+        notesOwnerDefinition(node.id?.name)
+      },
+      VariableDeclarator(node) {
+        notesOwnerDefinition(node.id?.name)
+      },
+      JSXOpeningElement(node) {
+        const tagName = node.name?.name
+        if (PLOT_OWNER_TAGS.has(tagName)) ownsPlot = true
+        else if (PLOT_ASSEMBLY_TAGS.has(tagName)) assemblyNodes.push(node)
+      },
+      'Program:exit'() {
+        if (ownsPlot || definesOwner) return
+        // Only the FIRST site is reported, and the whole check is FILE-scoped rather than
+        // component-scoped. Both are deliberate. File scope is forced by the shape of the correct
+        // pattern: `<CartesianChart>{() => <AxisLeftNumeric …/>}</CartesianChart>` puts the axis
+        // inside a render-prop arrow, a different function from the component that owns the chart
+        // — component scope would flag the canonical usage. One report because declaring an
+        // exception is a decision about the FILE ("this shape isn't a single cartesian plot"), so
+        // one `theme-allow` settles it instead of one comment per axis and overlay.
+        const [first] = assemblyNodes.filter((node) => chartImports.has(node.name?.name))
+        if (first === undefined || hasThemeAllow(context, first)) return
+        context.report({ node: first, message: HAND_ROLLED_PLOT_MESSAGE })
+      },
+    }
+  },
+}
+
+// ── Rule 13 — chart-legend-literal ───────────────────────────────────────────────────────────────
+
+const CHART_LEGEND_LITERAL_MESSAGE =
+  'Hand-authored ChartLegend items — the legend must be DERIVED from the same `series` array the ' +
+  'chart draws (deriveLegend, or just let ChartFrame/CartesianChart do it). A hand-written list ' +
+  'is a second source of truth that silently goes stale: it keeps naming a series after the plot ' +
+  'stops drawing it. (basalt/chart-legend-literal)'
+
+const chartLegendLiteral = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Require ChartLegend items to be derived from the series descriptor.' },
+    schema: [],
+  },
+  create(context) {
+    const chartImports = new Set()
+
+    return {
+      ImportDeclaration(node) {
+        collectChartImports(node, chartImports)
+      },
+      JSXOpeningElement(node) {
+        if (node.name?.name !== 'ChartLegend' || !chartImports.has('ChartLegend')) return
+        const items = node.attributes?.find(
+          (attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'items',
+        )
+        const expression = items?.value?.expression
+        if (expression?.type !== 'ArrayExpression') return
+        // Only a list that is ENTIRELY object literals is a hand-authored legend. An array that
+        // spreads or calls something (`[...deriveLegend(series), note]`) is derived-and-extended,
+        // which is legitimate — flagging it would push people to disable the rule.
+        //
+        // Known and accepted gap: hoisting the literal to a `const` one line up
+        // (`const items = [...]; <ChartLegend items={items} />`) reads as an Identifier here and
+        // is not flagged. Following that would mean local flow analysis for a bypass nobody
+        // reaches by accident; the rule targets the shape people actually write.
+        const allObjectLiterals =
+          expression.elements.length > 0 &&
+          expression.elements.every((el) => el?.type === 'ObjectExpression')
+        if (!allObjectLiterals) return
+        if (hasThemeAllow(context, node)) return
+        context.report({ node, message: CHART_LEGEND_LITERAL_MESSAGE })
+      },
+    }
+  },
+}
+
 // ── Plugin export ───────────────────────────────────────────────────────────────────────────────
 
 export default {
@@ -812,6 +962,8 @@ export default {
     'raw-size-literal': rawSizeLiteral,
     'card-inset': cardInset,
     'chart-in-raw-surface': chartInRawSurface,
+    'hand-rolled-plot': handRolledPlot,
+    'chart-legend-literal': chartLegendLiteral,
     'raw-scroll-container': rawScrollContainer,
     'visx-boundary': visxBoundary,
     'visx-tooltip': visxTooltip,

package/configs/oxlint-plugin.test.ts

@@ -28,6 +28,8 @@ beforeEach(() => {
         'basalt/no-raw-font-size': 'error',
         'basalt/card-inset': 'error',
         'basalt/chart-in-raw-surface': 'error',
+        'basalt/hand-rolled-plot': 'error',
+        'basalt/chart-legend-literal': 'error',
         'basalt/visx-boundary': 'error',
         'basalt/visx-tooltip': 'error',
         'basalt/token-layer-boundary': 'error',
@@ -476,3 +478,108 @@ describe('basalt agent rules promotion', () => {
     },
   )
 })
+
+// ── hand-rolled-plot ─────────────────────────────────────────────────────────
+
+const CHARTS_IMPORT = `import { AxisLeftNumeric, CartesianChart, ChartLegend, Crosshair, HoverOverlay } from 'basalt-ui/charts'\n`
+
+describe('basalt/hand-rolled-plot', () => {
+  it('flags an axis primitive in a file that never composes CartesianChart', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => <svg><AxisLeftNumeric scale={s} /></svg>\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  it('does NOT flag the same primitive when CartesianChart is composed', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => <CartesianChart>{() => <AxisLeftNumeric scale={s} />}</CartesianChart>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+
+  it('reports ONCE per file — declaring the exception is a file-level decision', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => (
+  <svg>
+    {/* theme-allow: multi-pane shape, not a single cartesian plot */}
+    <AxisLeftNumeric scale={a} />
+    <HoverOverlay width={1} height={1} />
+    <Crosshair x={0} top={0} bottom={1} />
+  </svg>
+)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+
+  it('does NOT flag a same-named component that is NOT a basalt chart primitive', () => {
+    const { code, rules } = run(
+      `import { Crosshair } from './my-own-widgets'
+export const C = () => <svg><Crosshair x={0} /></svg>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+
+  it('does NOT flag the module that DEFINES CartesianChart (function form)', () => {
+    const { code, rules } = run(
+      `import { AxisBottomDate } from '../primitives/Axes'
+export function CartesianChart() {
+  return <svg><AxisBottomDate scale={s} top={0} tickValues={[]} /></svg>
+}\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+
+  it('does NOT flag the module that DEFINES CartesianChart (const form)', () => {
+    const { code, rules } = run(
+      `import { AxisBottomDate } from '../primitives/Axes'
+export const CartesianChart = () => <svg><AxisBottomDate scale={s} top={0} tickValues={[]} /></svg>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+})
+
+// ── chart-legend-literal ─────────────────────────────────────────────────────
+
+describe('basalt/chart-legend-literal', () => {
+  it('flags a hand-authored items array', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => <ChartLegend items={[{ key: 'a', label: 'A', color: 'red' }]} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('chart-legend-literal')
+  })
+
+  it('does NOT flag items derived from the series descriptor', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => <ChartLegend items={deriveLegend(series)} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+
+  it('does NOT flag a derived-and-extended list — that is legitimate composition', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => <ChartLegend items={[...deriveLegend(series), note]} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+
+  it('honors a theme-allow escape', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => (
+  // theme-allow: static reference legend, no series behind it
+  <ChartLegend items={[{ key: 'a', label: 'A', color: 'red' }]} />
+)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+})

package/configs/oxlint.json

@@ -20,6 +20,8 @@
     "basalt/raw-size-literal": "warn",
     "basalt/card-inset": "error",
     "basalt/chart-in-raw-surface": "error",
+    "basalt/hand-rolled-plot": "warn",
+    "basalt/chart-legend-literal": "warn",
     "basalt/raw-scroll-container": "error",
     "basalt/visx-boundary": "error",
     "basalt/visx-tooltip": "error",

package/dist/charts/cursor/resolve.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Domain-aware resolution of a BROADCAST cursor key against a chart's own points.
+ *
+ * The layer this replaced matched keys byte-for-byte, so two charts shared a cursor only if they emitted identical
+ * strings. A chart that folded its domain to fit a narrow viewport stopped owning most of the keys
+ * its siblings broadcast, and the shared crosshair then landed on roughly one hover in three with
+ * no rule a reader could infer — patched per chart by a manual `resolveKey`. Resolving on the
+ * PARSED domain instead makes that automatic (`docs/CHARTS-SPEC.md` §3).
+ */
+/**
+ * A key as a comparable number: numeric-looking strings as numbers, everything else as a date.
+ * Neither (a plain category like "Direct") → null, which degrades to exact-match only — correct,
+ * since "nearest category" is meaningless.
+ */
+export declare function parseKey(key: string): number | null;
+export type DomainIndex<T> = {
+    byKey: Map<string, T>;
+    /** Parsed positions, ascending. Empty when the domain isn't parseable. */
+    values: number[];
+    /** Points parallel to `values`. */
+    points: T[];
+    /** Median spacing — the tolerance within which a foreign key still resolves. */
+    step: number;
+};
+/** Build the lookup structure once per `data` identity. */
+export declare function buildDomainIndex<T>(data: readonly T[], getKey: (d: T) => string): DomainIndex<T>;
+/**
+ * The own point a broadcast `key` maps to: exact match first, else the nearest parsed position
+ * within one domain step. Out of range → null, so charts over unrelated domains never paint a
+ * cursor for each other — which is what makes "shared by default" safe.
+ */
+export declare function resolveCursorPoint<T>(index: DomainIndex<T>, key: string): T | null;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/charts/cursor/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/charts/cursor/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnD;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,mCAAmC;IACnC,MAAM,EAAE,CAAC,EAAE,CAAA;IACX,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CA4BhG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CA+BlF"}