semiotic 3.5.1 → 3.5.3

package/CLAUDE.md

@@ -2,7 +2,10 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- **Use sub-path imports** — `semiotic/xy` (77KB gz), `semiotic/ordinal` (64KB), `semiotic/network` (51KB), `semiotic/geo` (49KB), `semiotic/realtime` (84KB), `semiotic/server` (64KB), `semiotic/recipes` (4KB), `semiotic/utils` (20KB), `semiotic/themes` (4KB), `semiotic/data` (3KB). Full `semiotic` is 165KB gz.
+<!-- semiotic-bundle-sizes:start -->
+<!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
+- **Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
+<!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 
@@ -12,7 +15,7 @@
 - Every HOC accepts `frameProps` for pass-through. TypeScript `strict: true`. Every HOC has error boundary + dev-mode validation.
 
 ## Common Props (all HOCs)
-`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke` (uniform stroke color — CSS var OK), `strokeWidth` (uniform stroke width in px), `opacity` (uniform 0–1 opacity), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30), `animate` (boolean | { duration?, easing?, intro? } — animated intro on first render + smooth transitions on data change; intro defaults to true when animate is enabled)
+`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke` (uniform stroke color — CSS var OK), `strokeWidth` (uniform stroke width in px), `opacity` (uniform 0–1 opacity), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `loadingContent` (ReactNode — replaces the default skeleton when `loading` is true; pass `false` to suppress the loading UI entirely), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30), `animate` (boolean | { duration?, easing?, intro? } — animated intro on first render + smooth transitions on data change; intro defaults to true when animate is enabled), `axisExtent` ("nice" default | "exact" — pins first/last tick to actual data min/max with equidistant intermediates. Applies to XY x/y axes and ordinal value axis only; no-op on network/geo/hierarchy. Explicit `tickValues` still wins.)
 
 **Primitive styling props** (`color`, `stroke`, `strokeWidth`, `opacity`) apply to any shape the chart draws (bars, circles, lines, wedges, rects). Precedence: top-level prop > `frameProps.*Style` function return > HOC base > theme fallback. Use CSS variables (`stroke="var(--semiotic-border)"`) for theme-aware, cascade-overridable styling. For per-datum customization, keep using the function-form `frameProps.pieceStyle` / `pointStyle` / `lineStyle` etc. — the top-level prop overlays on top of whatever the function returns.
 
@@ -20,12 +23,13 @@
 
 ## 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`, `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `tooltip="multi"` for hover-anywhere series comparison
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `tooltip="multi"` for hover-anywhere area comparison
-**StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` (`"zero"` default | `"wiggle"` for streamgraph | `"silhouette"` for centered), `stackOrder` (`"key"` default alpha | `"insideOut"` largest-in-middle | `"asc"`/`"desc"` by total). For canonical streamgraph aesthetic: `baseline="wiggle"` + `stackOrder="insideOut"` puts the largest series in the middle as a central anchor with smaller series wrapping outward. `baseline` is mutually exclusive with `normalize`. No `lineBy`/`lineDataAccessor`. Pass `tooltip="multi"` for hover-anywhere mode: a single tooltip lists every stacked series at the hovered x, with values interpolated between rendered path samples.
-**Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`
-**BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40])
-**ConnectedScatterplot** — + `orderAccessor`
+**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` (asymmetric min/max envelope: `{ y0Accessor, y1Accessor, style?, perSeries?, interactive? }` or array for fan charts; participates in yExtent; non-interactive by default; hovered datum is enriched with `band: {y0,y1}` and `bands: [...]`), `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `tooltip="multi"` for hover-anywhere series comparison
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `band` (same shape as LineChart — decorative envelope under the area), `tooltip="multi"` for hover-anywhere area comparison
+**DifferenceChart** — Two-series A/B comparison. Fills the area between with `seriesAColor` where A > B and `seriesBColor` where B > A; crossovers interpolated. Props: `data`, `xAccessor` ("x"), `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` (max raw rows in push buffer; FIFO eviction). Push API via `ref.current.push({x, a, b})`. Accessor outputs coerce through `toNumber` so `Date` + numeric strings are accepted.
+**StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` (`"zero"` default | `"wiggle"` streamgraph | `"silhouette"` centered), `stackOrder` (`"key"` alpha | `"insideOut"` largest-in-middle | `"asc"`/`"desc"`). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`/`lineDataAccessor`. `tooltip="multi"` lists every series at the hovered x (values interpolated between samples).
+**Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `regression` (boolean | "linear" | "polynomial" | "loess" | RegressionConfig — sugar for a trend-annotation overlay; sits underneath user annotations)
+**BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
+**ConnectedScatterplot** — + `orderAccessor`, `regression`
 **QuadrantChart** — Scatterplot + `quadrants` (required), `xCenter`, `yCenter`
 **MultiAxisLineChart** — Dual Y-axis. `series` (required: `[{ yAccessor, label?, color?, format?, extent? }]`). Falls back to multi-line if not 2 series.
 **Heatmap** — `data`, `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
@@ -35,7 +39,7 @@
 
 ## Ordinal Charts (`semiotic/ordinal`)
 
-**BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`true` | `{topOpacity, bottomOpacity}` | `{colorStops}` — same API as AreaChart; runs tip→base)
+**BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`true` | `{topOpacity, bottomOpacity}` | `{colorStops}` — same API as AreaChart; runs tip→base), `regression` (boolean | "linear" | "polynomial" | "loess" | RegressionConfig — sugar for a trend-annotation overlay; categories regressed as category-index, line projects through band scale)
 **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (default false — insertion order)
 **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (default false — insertion order)
 **SwarmPlot** — `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
@@ -43,13 +47,13 @@
 **Histogram** — + `bins` (25), `relative`. Always horizontal.
 **ViolinPlot** — + `bins`, `curve`, `showIQR`
 **RidgelinePlot** — + `bins`, `amplitude` (1.5)
-**DotPlot** — + `sort` ("auto" — insertion order when streaming, value-desc on static), `dotRadius`, `showGrid` default true
+**DotPlot** — + `sort` ("auto" — insertion order when streaming, value-desc on static), `dotRadius`, `showGrid` default true, `regression`
 **PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
 **DonutChart** — PieChart + `innerRadius` (60), `centerContent`
 **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor` (optional), `connectorOpacity`, `orientation`
-**SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (required), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`
+**SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (required), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`, `roundedTop` (pixel radius applied to both outer ends of each lane — left+right for horizontal, top+bottom for vertical. Middle segments stay square so adjacent pieces butt against each other; single-segment lanes round all four corners.)
 **LikertChart** — `categoryAccessor`, `valueAccessor`|`levelAccessor`+`countAccessor`, `levels` (required), `orientation`, `colorScheme`
-**GaugeChart** — `value` (required), `min`, `max`, `thresholds`, `arcWidth`, `sweep`, `fillZones`, `showNeedle`, `centerContent`
+**GaugeChart** — `value` (required), `min`, `max`, `thresholds`, `arcWidth`, `cornerRadius` (pixel radius for rounded segment ends — same semantics as DonutChart), `sweep`, `fillZones`, `showNeedle`, `centerContent`
 
 All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
 
@@ -57,6 +61,7 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
 
 **ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `edgeWidth`, `iterations` (300), `forceStrength` (0.1), `showLabels`, `nodeLabel`
 **SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `nodePaddingRatio`, `showLabels`
+**ProcessSankey** — temporal sankey with a real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`), `domain` (required `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node — lane spans `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`), `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` (default true), `showQualityReadout`, `showParticles` + `particleStyle` (same shape as SankeyDiagram, canvas + ParticlePool), `timeFormat`/`valueFormat`, push API via ref. Static-graph cycles are valid as long as edges move forward in time. Use for time-stamped flow events; use `SankeyDiagram` for static total-flow snapshots.
 **ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `showLabels`
 **TreeDiagram** — `data` (root), `layout`, `orientation`, `childrenAccessor`, `colorBy`, `colorByDepth`
 **Treemap** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `showLabels`
@@ -131,7 +136,7 @@ import {
 <NetworkCustomChart nodes={nodes} edges={edges} layout={flextreeLayout} layoutConfig={{ ... }} />
 ```
 
-**Recipes subpath** (`semiotic/recipes`, 4KB gz) ships pure layout functions. They emit standard SceneNodes — no chart code. BYO heavy deps (`d3-flextree`, `dagre`) live in user code.
+**Recipes subpath** (`semiotic/recipes`) ships pure layout functions. They emit standard SceneNodes — no chart code. BYO heavy deps (`d3-flextree`, `dagre`) live in user code.
 
 ### Chrome (labels, axes, legends): the recipe owns it
 
@@ -170,11 +175,9 @@ const [hovered, setHovered] = useState(null)
 />
 ```
 
-The same predicate hook is the integration point for richer interactions on the roadmap: a future `<ParallelCoordinatesBrushes>` overlay that drag-brushes per-axis ranges, and `useBrushSelection`-style linked brushing across coordinated charts (selection store would carry per-field range constraints, downstream charts consume them via the same hook).
-
 ### Built-in chrome works when the layout uses standard scales
 
-Layouts that draw *within* the frame's standard scales can just use the HOC's chrome. Pass `showAxes` on `XYCustomChart` / `OrdinalCustomChart` and the frame will render the same x/y or o/r axes the built-in HOCs do — useful for custom XY layouts that overlay points/lines on regular axes. The recipe-managed chrome is for the cases where standard axes can't help (variable-width bars under a band scale, per-row independent scales, etc.).
+Pass `showAxes` on `XYCustomChart` / `OrdinalCustomChart` to get the same x/y or o/r axes the built-in HOCs render — useful for custom layouts that overlay points/lines on regular scales. Recipe-managed chrome is for cases where standard axes don't fit (variable-width bars under a band scale, per-row independent scales, etc.).
 
 **Notes:**
 - Coords are plot-relative (the frame translates the canvas/SVG group by `margin`). Read `ctx.dimensions.plot` for the drawing rect. Radial ordinal projection is the one exception: `plot.x = -width/2`, `plot.y = -height/2` because the canvas ctx is center-translated.
@@ -219,7 +222,7 @@ Server SVGs include `role="img"`, `<title>`, `<desc>`, grid, legend, annotations
 - **GroupedBarChart** — `data`, `categoryAccessor`, `valueAccessor`, `groupBy` (required).
 - **PieChart/DonutChart** — `data`, `categoryAccessor`, `valueAccessor`.
 - **FunnelChart** — `data`, `stepAccessor` ("step"), `valueAccessor` ("value"). Renders with trapezoid connectors, no axes.
-- **GaugeChart** — `value`. Optional: `thresholds` (array of `{value, color, label}`), `min`, `max`, `sweep`, `arcWidth`.
+- **GaugeChart** — `value`. Optional: `thresholds` (array of `{value, color, label}`), `min`, `max`, `sweep`, `arcWidth`, `cornerRadius`.
 - **SwimlaneChart** — `data`, `categoryAccessor`, `subcategoryAccessor` (required), `valueAccessor`.
 - **ForceDirectedGraph** — `nodes`, `edges` (both required). If deriving nodes from edge endpoints, materialize `nodes` before returning JSX/renderChart props.
 - **SankeyDiagram** — `edges` (required), `valueAccessor`.
@@ -240,7 +243,7 @@ All HOCs accept `annotations` (array). Coordinates use data field names.
 
 ## Theming
 
-CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-secondary`, `--semiotic-surface`, `--semiotic-success`, `--semiotic-danger`, `--semiotic-warning`, `--semiotic-error`, `--semiotic-info`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-annotation-color`, `--semiotic-legend-font-size`, `--semiotic-title-font-size`, `--semiotic-tick-font-family`, `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
+CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-secondary`, `--semiotic-surface`, `--semiotic-success`, `--semiotic-danger`, `--semiotic-warning`, `--semiotic-error`, `--semiotic-info`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-annotation-color`, `--semiotic-legend-font-size`, `--semiotic-title-font-size`, `--semiotic-tick-font-family`, `--semiotic-tick-font-size` (10px default — drives axis tick text), `--semiotic-axis-label-font-size` (12px default — drives axis-label text + foreignObject ticks), `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
 
 ```jsx
 <ThemeProvider theme="tufte">       {/* Named preset */}
@@ -297,9 +300,8 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 - **Legend**: "bottom" expands margin ~80px. MultiAxisLineChart: use `legendPosition="bottom"`.
 - **Log scale**: Domain min clamped to 1e-6.
 - **barPadding**: Pixel value (40/60 default). Reduce for small charts.
-- **sort on StackedBarChart/GroupedBarChart**: Default `false` preserves insertion order. The underlying frame defaults to value-descending if `oSort` is undefined, so always pass `sort` explicitly if order matters.
-- **sort `"auto"`** (BarChart/StackedBarChart/GroupedBarChart/DotPlot): insertion order while streaming, value-desc on static data. The right choice when using the push API — avoids categories shuffling as values fluctuate. DotPlot's default; opt-in on others.
-- **Tooltip format cascade**: `valueFormat` (ordinal) / `xFormat` / `yFormat` (XY) / `valueFormat` on Heatmap flow to the default tooltip automatically, so axis and tooltip read identically. Only applies to the default tooltip — a custom `tooltip` prop fully overrides; re-pass the formatter inside `Tooltip({format})` / `MultiLineTooltip({fields:[{format}]})` if you want it there. Bespoke-tooltip charts (Histogram, FunnelChart, LikertChart, GaugeChart) don't participate; customize via `tooltip`.
+- **sort** (BarChart/StackedBarChart/GroupedBarChart/DotPlot): `false` preserves insertion order; `"auto"` = insertion-order while streaming, value-desc on static (DotPlot default — opt-in on others, avoids category shuffling under the push API). StackedBar/GroupedBar default to `false`; the underlying frame value-sorts when `oSort` is undefined, so always pass `sort` explicitly if order matters.
+- **Tooltip format cascade**: `valueFormat`/`xFormat`/`yFormat` flow to the default tooltip automatically, so axis and tooltip read identically. A custom `tooltip` prop fully overrides — re-pass via `Tooltip({format})` / `MultiLineTooltip({fields:[{format}]})`. Bespoke-tooltip charts (Histogram, FunnelChart, LikertChart, GaugeChart) don't participate; customize via `tooltip`.
 - **Horizontal bars**: Need wider left margin: `margin={{ left: 120 }}`.
 - **Push API**: Omit `data` entirely. `data={[]}` clears on every render.
 - **frameProps style functions**: Bypass HOC color resolution — use `colorBy` prop instead.
@@ -307,12 +309,13 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 - **fillArea**: `fillArea={["seriesA"]}` fills named series only. Names must match `lineBy`/`colorBy` keys.
 - **hoverHighlight**: Requires `colorBy` as a string field.
 - **tooltip="multi"**: Shows all series at hovered X for LineChart, AreaChart, and StackedAreaChart. Custom fn receives `datum.allSeries`.
-- **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks }]`
+- **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks, tickAnchor }]`. `tickAnchor: "edges"` flips the first tick's `text-anchor` to `start` and the last to `end` on horizontal axes (and `dominant-baseline` to `hanging`/`auto` on vertical axes) so edge labels don't overflow the plot. Pairs naturally with `axisExtent: "exact"`.
+- **Targeting individual axes from CSS**: every axis renders as its own `<g class="semiotic-axis semiotic-axis-{bottom|left|right|top}" data-orient="…">`. Style with `[data-orient="left"] text { font-size: 14px }` or via the class names — no `!important` needed because the CSS-var defaults are set inline via `var(--semiotic-tick-font-size, …)`, so cascade overrides win cleanly. Tick text carries `class="semiotic-axis-tick"`; labels carry `class="semiotic-axis-label"`; titles carry `class="semiotic-chart-title"`.
 - **xScaleType: "time"**: Creates `scaleTime`. Required for landmark ticks with timestamps.
 - **scalePadding**: Pixel inset on scale ranges. Pass via `frameProps={{ scalePadding: 12 }}`.
 - **categoryFormat/xFormat/yFormat**: Can return ReactNode (renders in `<foreignObject>`).
 - **Tick deduplication**: Adjacent identical labels auto-removed.
-- **Composing overlays**: XY/Ordinal charts paint `--semiotic-bg` across the full canvas by default, hiding anything beneath. When stacking charts (e.g. `position: absolute` overlay on top of a base), pass `frameProps={{ background: "transparent" }}` on the overlay to skip the fill. Network/Geo frames don't paint bg by default, so this only matters for XY/Ordinal.
+- **Composing overlays**: XY/Ordinal charts paint `--semiotic-bg` across the canvas; stack with `frameProps={{ background: "transparent" }}` on the overlay. Network/Geo don't paint bg by default.
 
 ## Performance
 

package/README.md

@@ -13,7 +13,7 @@ dashboards when you need them. Structured schemas and an MCP server so
 AI coding assistants generate correct chart code on the first try.
 
 ```jsx
-import { LineChart } from "semiotic/xy"    // 143 KB gzip
+import { LineChart } from "semiotic/xy"
 
 <LineChart
   data={salesData}
@@ -35,7 +35,7 @@ generate correct code without examples.
 Semiotic ships with everything an AI coding assistant needs to generate
 correct visualizations without trial and error:
 
-- **`semiotic/ai`** — a single import with 35 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
+- **`semiotic/ai`** — a single import with 41 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
 - **`ai/schema.json`** — machine-readable prop schemas for every component
 - **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
 - **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
@@ -240,12 +240,12 @@ import { LineChart, BarChart } from "semiotic"
 
 | Category | Components |
 |---|---|
-| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` |
-| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` |
-| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
+| **XY** | `LineChart` `AreaChart` `DifferenceChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` `CandlestickChart` `ScatterplotMatrix` |
+| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` `GaugeChart` |
+| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `ProcessSankey` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
 | **Geo** | `ChoroplethMap` `ProportionalSymbolMap` `FlowMap` `DistanceCartogram` |
 | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
-| **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
+| **Coordination** | `LinkedCharts` |
 | **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
 | **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` `StreamGeoFrame` |
 
@@ -280,21 +280,27 @@ for color, size, aggregation, and binning.
 
 ## Bundle Sizes
 
-Semiotic ships 11 entry points. **Don't import from `"semiotic"` unless you need everything** — use the sub-path that matches your chart type:
+Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need everything** — use the sub-path that matches your chart type:
+
+<!-- semiotic-bundle-sizes:start -->
+<!-- Auto-generated by `scripts/sync-bundle-sizes.mjs`. Edit dist/*, not this block. -->
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **143 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 7 more XY charts |
-| `semiotic/ordinal` | **109 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **98 KB** | ForceDirectedGraph, SankeyDiagram, Treemap, + 4 more |
-| `semiotic/geo` | **93 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **145 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
-| `semiotic/server` | **100 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/utils` | **31 KB** | ThemeProvider, validators, serialization — no chart components |
-| `semiotic/themes` | **5 KB** | Theme presets only (tufte, carbon, etc.) |
-| `semiotic/data` | **5 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
-| `semiotic/ai` | **269 KB** | All 38 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **278 KB** | Everything above (full bundle) |
+| `semiotic/xy` | **85 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **68 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **63 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **51 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **90 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
+| `semiotic/server` | **117 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/utils` | **22 KB** | ThemeProvider, validators, serialization — no chart components |
+| `semiotic/recipes` | **5 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/themes` | **4 KB** | Theme presets only (tufte, carbon, etc.) |
+| `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
+| `semiotic/ai` | **188 KB** | All 41 HOCs + validation — optimized for LLM code generation |
+| `semiotic` | **186 KB** | Everything below (full bundle) |
+
+<!-- semiotic-bundle-sizes:end -->
 
 ```jsx
 // Import from the sub-path, not from "semiotic"
@@ -306,7 +312,7 @@ import { ChoroplethMap } from "semiotic/geo"
 
 **Tree-shaking**: Each sub-path is a self-contained bundle with `"sideEffects": false`. Bundlers (webpack, Rollup, Vite, esbuild) will tree-shake unused exports. If you only use `LineChart` from `semiotic/xy`, the bar/pie/network code is never included.
 
-**When to use `"semiotic"`**: Only if your app uses charts from 3+ categories (XY + ordinal + network) and you'd rather have one import than three. The full bundle is 278 KB gzip — comparable to a single D3 import.
+**When to use `"semiotic"`**: Only if your app uses charts from 3+ categories (XY + ordinal + network) and you'd rather have one import than three. The full bundle is roughly the sum of every sub-path bundle above — see the `semiotic` row of the table for the current number.
 
 ## TypeScript
 
@@ -383,7 +389,7 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 | Tool | Description |
 |------|-------------|
 | **`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 or validation errors with fix suggestions. |
-| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 43 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
+| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 45 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
 | **`suggestChart`** | Recommend chart types for a data sample. Pass `{ data: [{...}, ...] }` with 1–5 sample objects. Optionally include `intent` (`"comparison"`, `"trend"`, `"distribution"`, `"relationship"`, `"composition"`, `"geographic"`, `"network"`, `"hierarchy"`). Returns ranked suggestions with example props. |
 | **`diagnoseConfig`** | Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes. |
 | **`reportIssue`** | Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass `{ title: "...", body: "...", labels: ["bug"] }`. Returns a URL the user can open to submit. |
@@ -496,7 +502,7 @@ Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Cl
 
 Agent-facing API surface:
 
-- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (43 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
+- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (45 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
 - [**`semiotic.nteract.io/llms.txt`**](https://semiotic.nteract.io/llms.txt) + [**`/llms-full.txt`**](https://semiotic.nteract.io/llms-full.txt) — deployed at the docs site per the [llms.txt standard](https://llmstxt.org). Agents fetch the navigation map (`llms.txt`) or the full inlined docs (`llms-full.txt`) over HTTP; they're not part of the npm package itself.
 
 ## Documentation

package/ai/chartSuggestions.cjs

@@ -1,11 +1,133 @@
 "use strict"
 
+const path = require("path")
+
 const VALID_INTENTS = [
   "comparison", "trend", "distribution", "relationship", "composition",
   "geographic", "network", "hierarchy",
 ]
 const MAX_SAMPLE_SIZE = 5
 
+// Capability matrix loaded from `ai/capabilities.json` — generated
+// from `chartSpecs.ts` via `npm run docs:capabilities`. Used to
+// filter suggestions when the caller passes capability constraints.
+// Loaded lazily so a test or build that hasn't generated the file
+// yet still imports cleanly; if the JSON is missing AND a caller
+// passes capability constraints, `suggestCharts` returns an explicit
+// error rather than silently filtering everything out (would happen
+// because `chartSatisfiesCapabilities` fails closed for unknown
+// chart names).
+//
+// `__dirname` points at the cjs source location at runtime —
+// when bundled into `ai/dist/mcp-server.js` `__dirname` is
+// `ai/dist/`, so we also probe the parent directory. Mirrors the
+// `schema.json` loader's two-candidate pattern.
+//
+// `_capabilityMatrixLoaded` differentiates "load attempted, file
+// missing → empty {}" from "load not yet attempted". Without this
+// flag, a build that's missing capabilities.json would set
+// `_capabilityMatrix = {}` and every subsequent call would short-
+// circuit on `if (_capabilityMatrix)` (because `{}` is truthy) and
+// never re-probe — the right behavior for a steady state but
+// incompatible with detecting "loader failed".
+let _capabilityMatrix = null
+let _capabilityMatrixLoaded = false
+function loadCapabilityMatrix() {
+  if (_capabilityMatrixLoaded) return _capabilityMatrix
+  const candidates = [
+    path.join(__dirname, "capabilities.json"),
+    path.join(__dirname, "..", "capabilities.json"),
+  ]
+  for (const candidate of candidates) {
+    try {
+      const json = require(candidate)
+      if (json && json.charts) {
+        _capabilityMatrix = json.charts
+        _capabilityMatrixLoaded = true
+        return _capabilityMatrix
+      }
+    } catch {
+      // try next candidate
+    }
+  }
+  _capabilityMatrixLoaded = true
+  return _capabilityMatrix
+}
+
+// Mapping from the capability arg names callers pass (push,
+// linkedHover, ssr, selection, legend) to the chartSpecs field
+// names in capabilities.json (supportsPush, supportsLinkedHover,
+// etc.). Caller-side names are short for ergonomics; matrix-side
+// names mirror the chartSpecs schema so search/grep finds both.
+const CAPABILITY_KEY_MAP = {
+  push: "supportsPush",
+  linkedHover: "supportsLinkedHover",
+  ssr: "supportsSSR",
+  selection: "supportsSelection",
+  legend: "supportsLegend",
+}
+
+const VALID_CAPABILITY_KEYS = Object.keys(CAPABILITY_KEY_MAP)
+
+/**
+ * Test a chart name against a capability constraint object. Returns
+ * `true` when the chart satisfies every constraint (or when no
+ * constraints are set). Unknown chart names fail closed — better to
+ * drop a suggestion than recommend a chart we can't confirm
+ * supports the caller's needs.
+ *
+ * `requirements` shape:
+ *   { push?: boolean, linkedHover?: boolean, ssr?: boolean,
+ *     selection?: boolean, legend?: boolean }
+ *
+ * Each key, when set to `true`, means "the chart MUST support this".
+ * `false` means "the chart MUST NOT support this" (rare, but
+ * symmetric — useful for "give me a chart that intentionally has no
+ * legend"). Unset keys are ignored.
+ */
+function chartSatisfiesCapabilities(chartName, requirements) {
+  if (!requirements || Object.keys(requirements).length === 0) return true
+  const matrix = loadCapabilityMatrix()
+  if (matrix == null) return false // matrix unavailable — fail closed
+  const spec = matrix[chartName]
+  if (!spec) return false // unknown chart — fail closed
+  for (const [shortKey, want] of Object.entries(requirements)) {
+    if (want == null) continue
+    const matrixKey = CAPABILITY_KEY_MAP[shortKey]
+    if (!matrixKey) continue // unknown short key — ignore (validated upstream)
+    const has = spec[matrixKey] === true
+    if (has !== want) return false
+  }
+  return true
+}
+
+/**
+ * Explain why a chart doesn't satisfy a capability constraint set —
+ * used in the `filteredOut[].reason` payload so callers see the
+ * specific mismatched constraint(s) rather than the chart's
+ * data-shape rationale. Returns null when no mismatch (defensive;
+ * callers should only invoke this on charts that already failed
+ * `chartSatisfiesCapabilities`).
+ */
+function explainCapabilityMismatch(chartName, requirements) {
+  if (!requirements || Object.keys(requirements).length === 0) return null
+  const matrix = loadCapabilityMatrix()
+  if (matrix == null) return "capability matrix unavailable (run `npm run docs:capabilities`)"
+  const spec = matrix[chartName]
+  if (!spec) return `${chartName} not found in capability matrix`
+  const mismatches = []
+  for (const [shortKey, want] of Object.entries(requirements)) {
+    if (want == null) continue
+    const matrixKey = CAPABILITY_KEY_MAP[shortKey]
+    if (!matrixKey) continue
+    const has = spec[matrixKey] === true
+    if (has !== want) {
+      mismatches.push(`requires ${shortKey}=${want} but ${matrixKey}=${has}`)
+    }
+  }
+  return mismatches.length > 0 ? mismatches.join("; ") : null
+}
+
 function summarizeFields(data, keys) {
   const numericFields = []
   const stringFields = []
@@ -72,6 +194,7 @@ function uniqueNetworkNodes(data, sourceField, targetField) {
 function suggestCharts(args = {}) {
   const data = args.data
   const intent = args.intent
+  const capabilities = args.capabilities
 
   if (intent && !VALID_INTENTS.includes(intent)) {
     return {
@@ -80,10 +203,35 @@ function suggestCharts(args = {}) {
     }
   }
 
+  if (capabilities) {
+    if (typeof capabilities !== "object" || Array.isArray(capabilities)) {
+      return {
+        ok: false,
+        error: "capabilities must be an object like { push: true, linkedHover: true, ssr: true, selection: true, legend: true }.",
+      }
+    }
+    const unknown = Object.keys(capabilities).filter((k) => !VALID_CAPABILITY_KEYS.includes(k))
+    if (unknown.length > 0) {
+      return {
+        ok: false,
+        error: `Unknown capability key(s): ${unknown.join(", ")}. Expected: ${VALID_CAPABILITY_KEYS.join(", ")}.`,
+      }
+    }
+    // Probe matrix availability up front so callers see a clear error
+    // instead of an empty-suggestions silent-failure when
+    // capabilities.json is missing from the build.
+    if (loadCapabilityMatrix() == null) {
+      return {
+        ok: false,
+        error: "Capability matrix unavailable: ai/capabilities.json is missing. Run `npm run docs:capabilities` to generate it. (Capability filtering requires the matrix; suggestions without a `capabilities` arg still work.)",
+      }
+    }
+  }
+
   if (!data || !Array.isArray(data) || data.length === 0) {
     return {
       ok: false,
-      error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy'.",
+      error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy', or capabilities: { push, linkedHover, ssr, selection, legend }.",
     }
   }
 
@@ -257,12 +405,37 @@ function suggestCharts(args = {}) {
     })
   }
 
+  // Apply capability filter as the last step so data-shape inference
+  // logic stays oblivious to it. Suggestions are kept in their
+  // confidence-ranked order; we just drop anything that doesn't
+  // satisfy the caller's constraints.
+  const filteredSuggestions = capabilities
+    ? suggestions.filter((s) => chartSatisfiesCapabilities(s.component, capabilities))
+    : suggestions
+
   return {
     ok: true,
     intent,
+    capabilities,
     fieldSummary: `Fields: ${keys.join(", ")} (${numericFields.length} numeric, ${stringFields.length} categorical, ${dateFields.length} date)`,
     fields,
-    suggestions,
+    suggestions: filteredSuggestions,
+    // Surface the pre-filter set when a capability constraint was
+    // applied — caller can see which suggestions were dropped and
+    // whether to relax the constraint.
+    ...(capabilities && filteredSuggestions.length < suggestions.length && {
+      filteredOut: suggestions
+        .filter((s) => !chartSatisfiesCapabilities(s.component, capabilities))
+        .map((s) => ({
+          component: s.component,
+          // The `reason` here is the capability mismatch (which
+          // constraint failed), not the original data-shape rationale
+          // — callers debugging an empty result need to know which
+          // capability to relax, not why the chart was originally
+          // suggested.
+          reason: explainCapabilityMismatch(s.component, capabilities) || "did not satisfy capability constraints",
+        })),
+    }),
   }
 }
 
@@ -270,7 +443,10 @@ function formatSuggestionReport(result) {
   if (!result.ok) return result.error
 
   if (result.suggestions.length === 0) {
-    return `Could not confidently recommend a chart type.\n\n${result.fieldSummary}\n\nTry providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`
+    const tail = result.capabilities && result.filteredOut && result.filteredOut.length > 0
+      ? `\n\nDropped by capability filter (${formatCapabilityConstraints(result.capabilities)}):\n${result.filteredOut.map((s) => `- ${s.component}: ${s.reason}`).join("\n")}\n\nRelax the capability constraints, or use getSchema to browse alternatives.`
+      : `\n\nTry providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`
+    return `Could not confidently recommend a chart type.\n\n${result.fieldSummary}${tail}`
   }
 
   const lines = result.suggestions.map((suggestion, i) => {
@@ -284,8 +460,20 @@ function formatSuggestionReport(result) {
   return lines.join("\n\n") + themingTip
 }
 
+function formatCapabilityConstraints(capabilities) {
+  return Object.entries(capabilities)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(", ")
+}
+
 module.exports = {
   VALID_INTENTS,
+  VALID_CAPABILITY_KEYS,
   formatSuggestionReport,
   suggestCharts,
+  // Exported for tests + callers that want to filter their own
+  // chart-name set without re-running the suggestion pipeline.
+  chartSatisfiesCapabilities,
+  explainCapabilityMismatch,
 }

package/ai/componentMetadata.cjs

@@ -4,7 +4,7 @@ const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime"]
 
 const COMPONENTS_BY_CATEGORY = {
   xy: [
-    "LineChart", "AreaChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
+    "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
     "MultiAxisLineChart", "CandlestickChart", "BubbleChart", "Heatmap",
     "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart",
   ],
@@ -14,8 +14,8 @@ const COMPONENTS_BY_CATEGORY = {
     "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart",
   ],
   network: [
-    "ForceDirectedGraph", "SankeyDiagram", "ChordDiagram", "TreeDiagram",
-    "Treemap", "CirclePack", "OrbitDiagram",
+    "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram",
+    "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram",
   ],
   geo: [
     "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram",