semiotic 3.8.5 → 3.8.6

package/CLAUDE.md

@@ -4,7 +4,7 @@
 - Install: `npm install semiotic`
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-- **Use sub-path imports** — `semiotic/xy` (138KB gz), `semiotic/ordinal` (117KB gz), `semiotic/network` (124KB gz), `semiotic/geo` (98KB gz), `semiotic/realtime` (151KB gz), `semiotic/realtime/core` (145KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (205KB gz), `semiotic/server/node` (205KB gz), `semiotic/server/edge` (224KB gz), `semiotic/utils` (83KB gz), `semiotic/utils/core` (81KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (84KB gz), `semiotic/recipes/core` (83KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (8KB gz), `semiotic/physics` (153KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (462KB gz), `semiotic/ai/core` (77KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (4KB gz). Full `semiotic` is 376KB gz.
+- **Use sub-path imports** — `semiotic/xy` (143KB gz), `semiotic/ordinal` (119KB gz), `semiotic/network` (125KB gz), `semiotic/geo` (98KB gz), `semiotic/realtime` (152KB gz), `semiotic/realtime/core` (146KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (207KB gz), `semiotic/server/node` (207KB gz), `semiotic/server/edge` (226KB gz), `semiotic/utils` (83KB gz), `semiotic/utils/core` (81KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (84KB gz), `semiotic/recipes/core` (83KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (8KB gz), `semiotic/physics` (154KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (468KB gz), `semiotic/ai/core` (78KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (4KB gz). Full `semiotic` is 382KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
 
@@ -21,8 +21,9 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 ## XY Charts (`semiotic/xy`)
 
 **LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `band` ({y0Accessor, y1Accessor, style?, perSeries?, interactive?} or array for fan charts; participates in yExtent; non-interactive by default), `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `styleRules` (per-series), `tooltip="multi"` for hover-anywhere
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `semanticGradient` (`{stops: [{offset: 0–1, color?, opacity?}]}`; offset follows the resolved y-domain), `semanticLine` (true with semanticGradient; false keeps the normal stroke/lineGradient), `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
 **DifferenceChart** — Two-series A/B. Fills between with `seriesAColor` where A>B, `seriesBColor` where B>A; crossovers interpolated. `data`, `xAccessor`, `seriesAAccessor` ("a"), `seriesBAccessor` ("b"), `seriesALabel`/`seriesBLabel`, `seriesAColor` (var(--semiotic-danger))/`seriesBColor` (var(--semiotic-info)), `showLines` (true), `lineWidth` (1.5), `showPoints` (false), `pointRadius` (3), `curve` ("linear"), `areaOpacity` (0.6), `gradientFill`, `xExtent`/`yExtent`, `pointIdAccessor`, `windowSize`. Push via `ref.push({x,a,b})`. Accessor outputs coerce through `toNumber`.
+**BumpChart** — Ranking-over-x. Each x-column ranks series by `yAccessor`; rank is vertical position. `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy` ("series"), `rankDirection` ("descending"|"ascending"), `ribbon` (false — encode magnitude as true perpendicular-offset ribbon width instead of fixed-width lines; line↔ribbon share centerline geometry so `animate` tweens width only), `curve` ("smooth"|"linear"), `ribbonSizeRange` ([4,28]), `samplesPerSegment` (12), `lineWidth` (3), `highlightTop` (color only the N best series by mean rank; the rest share `neutralColor`), `neutralColor`, `styleRules` (per-series; resolve against each series' first observation), `showPoints`, `showLabels` (true|"start"|"end"|"both"), `hoverHighlight`, `annotations` (x may use original x values incl. `Date`). Wraps XYCustomChart.
 **StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` ("zero"|"wiggle" streamgraph|"silhouette" centered), `stackOrder` ("key"|"insideOut"|"asc"|"desc"). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`. `tooltip="multi"` interpolates between samples.
 **Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `symbolBy` (categorical field → glyph **shape**: each mark becomes a d3-shape glyph; size still tracks `sizeBy`/`pointRadius`), `symbolMap` ({category → shape}; unmapped auto-assign — pass it for legend-matchable shapes), `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `styleRules` (per-point; `axis:"x"`/`"y"` thresholds), `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
@@ -36,7 +37,7 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 
 ## Ordinal Charts (`semiotic/ordinal`)
 
-**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (true | {topOpacity, bottomOpacity} | {colorStops}; tip→base), `styleRules`, `regression`
+**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`
 **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order), `styleRules`
 **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default), `styleRules`
 **SwarmPlot** — `colorBy`, `sizeBy`, `symbolBy` (categorical field → glyph shape, like Scatterplot), `symbolMap`, `pointRadius`, `pointOpacity`
@@ -58,7 +59,7 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
 
 ## Network Charts (`semiotic/network`)
 
-**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `nodeStroke`/`nodeStrokeWidth` (node-only outline), `edgeWidth`, `edgeColor`/`edgeOpacity` (edge-only stroke), `iterations` (300), `forceStrength` (0.1 — link-attraction multiplier), `layoutExecution` ("auto" default | "worker" | "sync" — auto runs big layouts in a Web Worker by estimated cost, sync fallback everywhere), `layoutLoadingContent` (ReactNode while worker layout pends; `false` suppresses), `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showLabels`, `nodeLabel`, `styleRules` (style groups of nodes — rules see the raw node; `ctx.category` = colorBy group). **Node vs edge stroking**: the generic `stroke`/`strokeWidth`/`opacity` style *all* marks uniformly; to stroke nodes and edges separately use node-only `nodeStroke`/`nodeStrokeWidth` (e.g. `nodeStroke="none"` drops the node ring) and edge-only `edgeColor`/`edgeWidth`/`edgeOpacity`. Precedence per property: specific > generic > built-in default (so an explicit `edgeColor` is no longer clobbered by a generic `stroke`).
+**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `nodeStroke`/`nodeStrokeWidth` (node-only outline), `edgeWidth`, `edgeColor`/`edgeOpacity` (edge-only stroke), `iterations` (300), `forceStrength` (0.1 — link-attraction multiplier), `layoutExecution` ("auto" default | "worker" | "sync" — auto runs big layouts in a Web Worker by estimated cost, sync fallback everywhere), `layoutLoadingContent` (ReactNode while worker layout pends; `false` suppresses), `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showLabels`, `nodeLabel`, `styleRules` (style groups of nodes — rules see the raw node; `ctx.category` = colorBy group). **Node vs edge stroking**: the generic `stroke`/`strokeWidth`/`opacity` style *all* marks uniformly; to stroke nodes and edges separately use node-only `nodeStroke`/`nodeStrokeWidth` (e.g. `nodeStroke="none"` drops the node ring) and edge-only `edgeColor`/`edgeWidth`/`edgeOpacity`. Precedence per property: specific > generic > built-in default.
 **SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `nodePaddingRatio`, `showLabels`
 **ProcessSankey** — temporal sankey with real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`), `domain` (req `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node), `colorBy`/`colorScheme`/`showLegend`/`legendPosition`, `pairing` ("value"|"temporal"), `packing` ("off"|"reuse"), `laneOrder` ("crossing-min"|"inside-out"|"crossing-min+inside-out"|"insertion"), `lifetimeMode` ("full"|"half"), `ribbonLane` ("source"|"target"|"both"), `showLaneRails`, `showLabels` (true), `showQualityReadout`, `showParticles` + `particleStyle`, `timeFormat`/`valueFormat`, push API via ref. Static-graph cycles OK as long as edges move forward in time. Use ProcessSankey for time-stamped events; SankeyDiagram for static snapshots.
 **ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `showLabels`

package/README.md

@@ -16,21 +16,21 @@ AI coding assistants generate correct chart code on the first try.
 <img src="./docs/public/assets/img/semiotic-release-dashboard.svg" alt="Semiotic release dashboard showing chart count, bundle sizes, capability coverage, chart families, and documentation growth" width="100%">
 <!-- semiotic-readme-dashboard:end -->
 
-## What's New in 3.8.5
-
-3.8.5 adds a new physics chart and two network/word-cloud recipes, then closes another round of
-server/browser render gaps:
-
-- New `CrucibleChart` (`semiotic/physics`): bounded peer components undergo authored phases and
-  events, form declared products, and settle into reason-labelled outlets with full source lineage.
-- New `wordTrailsLayout` and `netEnsembleLayout` recipes (`semiotic/recipes`) for quantitatively
-  anchored word clouds and small-multiple layouts of disconnected graph ensembles, plus a
-  Langren-style strip layout for `DistanceCartogram` and separate node/edge stroke controls on
-  `ForceDirectedGraph`.
-- `renderChart` now runs a chart's custom `svgAnnotationRules` server-side, honors `frameProps`
-  axis/legend/label overrides, and renders ordinal `x-threshold` annotations—closing SSR gaps that
-  used to silently drop custom overlays and chrome toggles. `renderChartWithEvidence` also exposes
-  the resolved margin and plot rectangle.
+## What's New in 3.8.6
+
+3.8.6 adds a ranking chart and semantic-line area bands, then refines legend layout across the
+client and server renderers:
+
+- New `BumpChart` (`semiotic/xy`): ranks every series within each x-column and connects each
+  series' rank across columns. Set `ribbon` to encode the original magnitude as true
+  perpendicular-offset ribbon width instead of a fixed-width line — both modes share one
+  centerline, so the toggle animates as a pure width change.
+- `AreaChart` gains `semanticLine` (default on) for hard, value-banded color segments along the
+  area's top stroke, and `gradientFill`/`lineGradient`/`semanticGradient` now share one
+  `{ stops }` config (with `GradientConfig` and friends exported).
+- Legend layout gains `legendLayout.sideGutter` (space between a side legend and axis chrome) and
+  a `legendDistance` control, with content-measured side-legend widths and tightened defaults,
+  aligned across the client and SSR renderers.
 
 ```jsx
 import { LineChart } from "semiotic/xy"
@@ -379,16 +379,16 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **138 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **117 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **124 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/xy` | **143 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **119 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **125 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
 | `semiotic/geo` | **98 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **151 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
-| `semiotic/realtime/core` | **145 KB** | Streaming chart types, HOCs, and buffer helpers |
+| `semiotic/realtime` | **152 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/realtime/core` | **146 KB** | Streaming chart types, HOCs, and buffer helpers |
 | `semiotic/realtime/react` | **1 KB** | Stream status and synced push hooks |
-| `semiotic/server` | **205 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/node` | **205 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/edge` | **224 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
+| `semiotic/server` | **207 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/node` | **207 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/edge` | **226 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
 | `semiotic/utils` | **83 KB** | ThemeProvider, numeric/accessibility audits, serialization — no chart components |
 | `semiotic/utils/core` | **81 KB** | Pure theme helpers, numeric/accessibility audits, and serialization |
 | `semiotic/utils/react` | **6 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
@@ -400,14 +400,14 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
 | `semiotic/themes/react` | **6 KB** | ThemeProvider/useTheme and hooks |
 | `semiotic/data` | **4 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
 | `semiotic/value` | **8 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
-| `semiotic/physics` | **153 KB** | GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, PhysicalFlowChart, PhysicsCustomChart |
+| `semiotic/physics` | **154 KB** | GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, PhysicalFlowChart, PhysicsCustomChart |
 | `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
 | `semiotic/physics/rapier` | **1 KB** | Rapier peer guard + adapter decision metadata (no chart components) |
-| `semiotic/ai` | **462 KB** | All schema-backed charts + validation — optimized for LLM code generation |
-| `semiotic/ai/core` | **77 KB** | suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components |
+| `semiotic/ai` | **468 KB** | All schema-backed charts + validation — optimized for LLM code generation |
+| `semiotic/ai/core` | **78 KB** | suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components |
 | `semiotic/controls` | **12 KB** | DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
 | `semiotic/rough` | **4 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
-| `semiotic` | **376 KB** | Everything below (full bundle) |
+| `semiotic` | **382 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -428,23 +428,23 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
 
 | Public named import | Runtime | gzip cold-consumer bundle |
 |---|---:|---:|
-| `import { LineChart } from "semiotic"` | browser | **148.0 KiB** |
-| `import { LineChart } from "semiotic/xy"` | browser | **148.0 KiB** |
-| `import { BarChart } from "semiotic/ordinal"` | browser | **122.1 KiB** |
-| `import { SankeyDiagram } from "semiotic/network"` | browser | **127.3 KiB** |
-| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **121.3 KiB** |
-| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **169.7 KiB** |
+| `import { LineChart } from "semiotic"` | browser | **152.8 KiB** |
+| `import { LineChart } from "semiotic/xy"` | browser | **152.8 KiB** |
+| `import { BarChart } from "semiotic/ordinal"` | browser | **122.9 KiB** |
+| `import { SankeyDiagram } from "semiotic/network"` | browser | **127.8 KiB** |
+| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **122.5 KiB** |
+| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **170.9 KiB** |
 | `import { useStreamStatus } from "semiotic/realtime/react"` | browser | **0.6 KiB** |
-| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **137.1 KiB** |
+| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **138.0 KiB** |
 | `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.2 KiB** |
 | `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** |
-| `import { renderChart } from "semiotic/server"` | node | **263.8 KiB** |
-| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **165.7 KiB** |
-| `import { renderToImage } from "semiotic/server/node"` | node | **264.3 KiB** |
-| `import { suggestCharts } from "semiotic/ai"` | browser | **214.3 KiB** |
-| `import { suggestCharts } from "semiotic/ai/core"` | browser | **34.1 KiB** |
+| `import { renderChart } from "semiotic/server"` | node | **266.6 KiB** |
+| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **165.0 KiB** |
+| `import { renderToImage } from "semiotic/server/node"` | node | **267.0 KiB** |
+| `import { suggestCharts } from "semiotic/ai"` | browser | **219.7 KiB** |
+| `import { suggestCharts } from "semiotic/ai/core"` | browser | **34.7 KiB** |
 | `import { bin } from "semiotic/data"` | browser | **0.4 KiB** |
-| `import { ChoroplethMap } from "semiotic/geo"` | browser | **107.3 KiB** |
+| `import { ChoroplethMap } from "semiotic/geo"` | browser | **108.2 KiB** |
 | `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.4 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes"` | browser | **3.4 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes/core"` | browser | **3.4 KiB** |
@@ -470,7 +470,7 @@ import { ChoroplethMap } from "semiotic/geo"
 
 **Tree-shaking & multi-subpath imports**: Family entries (`semiotic/xy`, `semiotic/network`, `semiotic/ai`, …) are built as one ESM graph with **shared chunks**. Stream frames, renderers, and other common code ship once and are imported by every entry that needs them — so combining `semiotic/ai` + `semiotic/xy` + `semiotic/network` does **not** mean paying for three full copies of the runtime. The package is marked `"sideEffects": false`, so modern bundlers keep only the named exports you retain (e.g. `LineChart` + `suggestCharts`). Prefer family subpaths for clarity; import AI helpers from `semiotic/ai` or the lighter `semiotic/ai/core` when you do not need the chart catalog.
 
-**When to use `"semiotic"`**: Fine when you want one import for mixed families. With shared chunks it is no longer “sum every subpath” — the cold-consumer table above is the better guide for a single named import, and multi-family apps should not see the old double-pay tax.
+**When to use `"semiotic"`**: Fine when you want one import for mixed families. Shared chunks prevent duplicated runtime code across family subpaths; the cold-consumer table above is the better guide for a single named import.
 
 ## TypeScript
 
@@ -557,7 +557,7 @@ host-header allowlisting. For ChatGPT Apps domain verification, set
 | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string plus a "Render evidence" JSON block (mark counts by scene type, resolved axis domains, empty flag, annotation count, accessible name) so agents can verify the chart drew data marks, or validation errors with fix suggestions. |
 | **`renderInteractiveChart`** | Render a static-data chart as a ChatGPT Apps widget. Uses the same Semiotic server render path as `renderChart`, then hydrates an iframe UI with fit, zoom, data, hover, and render-evidence controls. |
 | **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list the complete schema-backed catalog. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
-| **`suggestChart`** | Legacy sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
+| **`suggestChart`** | Sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
 | **`suggestCharts`** | Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props. |
 | **`suggestStreamCharts`** | Recommend realtime charts from a stream schema, throughput, and retention hints. |
 | **`suggestDashboard`** | Build a multi-panel dashboard suggestion that covers distinct analytical intents. |

package/ai/behaviorContracts.cjs

@@ -27,8 +27,8 @@ const DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->"
 // diagnoseConfig as "OK" in static mode. Keying off the presence of a `data`
 // property catches them (and still includes the charts that DO list `data`).
 //
-// `STATIC_DATA_COMPONENTS` stays exported as a Set for test/legacy callers
-// that probe the surface, and is rebuilt from disk at module load time.
+// `STATIC_DATA_COMPONENTS` is exported as a Set and rebuilt from disk at
+// module load time.
 function loadStaticDataComponentsFromSchema() {
   // Source layout has this file at `<repo>/ai/behaviorContracts.cjs` and the
   // schema at `<repo>/ai/schema.json` — `__dirname` works directly.

package/ai/componentMetadata.cjs

@@ -4,7 +4,7 @@ const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "physics"
 
 const COMPONENTS_BY_CATEGORY = {
   xy: [
-    "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
+    "LineChart", "BumpChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
     "MultiAxisLineChart", "CandlestickChart", "BubbleChart", "Heatmap",
     "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart",
   ],

package/ai/dist/mcp-server.js

@@ -6898,6 +6898,7 @@ var require_componentMetadata = __commonJS({
     var COMPONENTS_BY_CATEGORY = {
       xy: [
         "LineChart",
+        "BumpChart",
         "AreaChart",
         "DifferenceChart",
         "StackedAreaChart",
@@ -33016,6 +33017,7 @@ var import_geo = require("semiotic/geo");
 var COMPONENT_REGISTRY = {
   LineChart: { component: import_ai.LineChart, category: "xy" },
   AreaChart: { component: import_ai.AreaChart, category: "xy" },
+  BumpChart: { component: import_ai.BumpChart, category: "xy" },
   DifferenceChart: { component: import_ai.DifferenceChart, category: "xy" },
   StackedAreaChart: { component: import_ai.StackedAreaChart, category: "xy" },
   Scatterplot: { component: import_ai.Scatterplot, category: "xy" },

package/ai/examples.md

@@ -147,7 +147,12 @@ const data = [
   data={data}
   xAccessor="month"
   yAccessor="revenue"
-  gradientFill
+  gradientFill={{
+    stops: [
+      { offset: 0, opacity: 0.8 },
+      { offset: 1, opacity: 0.05 }
+    ]
+  }}
   xLabel="Month"
   yLabel="Revenue ($)"
 />
@@ -180,7 +185,12 @@ const data = [
     y0Accessor="p5"
     showLine={false}
     areaOpacity={0.3}
-    gradientFill
+    gradientFill={{
+      stops: [
+        { offset: 0, opacity: 0.8 },
+        { offset: 1, opacity: 0.05 }
+      ]
+    }}
     width={600}
     height={400}
   />
@@ -235,6 +245,38 @@ Fills the region between two series with a color that switches based on which se
 
 Key props: `seriesALabel` / `seriesBLabel` (legend + tooltip), `seriesAColor` / `seriesBColor` (defaults to `var(--semiotic-danger)` / `var(--semiotic-info)`), `showLines` (default `true` — draws both series on top of the fill), `areaOpacity` (0.6), `gradientFill` (same shape as AreaChart), `windowSize` (max raw rows in push buffer; FIFO eviction). Push API: `ref.current.push({ x, a, b })` — accessor outputs coerce through a `toNumber` helper so `Date` (time series) and numeric strings (CSV/JSON) work transparently.
 
+### BumpChart
+
+```jsx
+import { BumpChart } from "semiotic/ai"
+
+const data = [
+  { quarter: "Q1", team: "North", sales: 420 },
+  { quarter: "Q1", team: "South", sales: 380 },
+  { quarter: "Q1", team: "East",  sales: 510 },
+  { quarter: "Q1", team: "West",  sales: 290 },
+  { quarter: "Q2", team: "North", sales: 460 },
+  { quarter: "Q2", team: "South", sales: 500 },
+  { quarter: "Q2", team: "East",  sales: 480 },
+  { quarter: "Q2", team: "West",  sales: 350 },
+  { quarter: "Q3", team: "North", sales: 610 },
+  { quarter: "Q3", team: "South", sales: 470 },
+  { quarter: "Q3", team: "East",  sales: 520 },
+  { quarter: "Q3", team: "West",  sales: 540 }
+]
+
+<BumpChart
+  data={data}
+  xAccessor="quarter"
+  yAccessor="sales"
+  lineBy="team"
+  highlightTop={2}
+  xLabel="Quarter"
+/>
+```
+
+Ranks every series within each x-column and connects each series' rank across columns — the classic "who's leading over time" chart. `yAccessor` is the magnitude used to rank (highest value = rank 1 by default; use `rankDirection="ascending"` when lower is better). `highlightTop` colors only the N best series by mean rank and greys the rest via `neutralColor`. Set `ribbon={true}` to encode the raw magnitude as true perpendicular-offset ribbon width instead of fixed-width lines — line and ribbon share the same centerline geometry, so `animate` tweens only the width. Endpoint labels show by default (`showLabels`).
+
 ### StackedAreaChart
 
 ```jsx