semiotic 3.8.0 → 3.8.2

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` (101KB gz), `semiotic/ordinal` (82KB gz), `semiotic/network` (85KB gz), `semiotic/geo` (62KB gz), `semiotic/realtime` (111KB gz), `semiotic/realtime/core` (110KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (189KB gz), `semiotic/server/node` (189KB gz), `semiotic/server/edge` (188KB gz), `semiotic/utils` (71KB gz), `semiotic/utils/core` (70KB gz), `semiotic/utils/react` (4KB gz), `semiotic/recipes` (53KB gz), `semiotic/recipes/core` (52KB gz), `semiotic/recipes/react` (1KB gz), `semiotic/themes` (6KB gz), `semiotic/themes/core` (6KB gz), `semiotic/themes/react` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (98KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (394KB gz), `semiotic/ai/core` (79KB gz), `semiotic/controls` (5KB gz). Full `semiotic` is 258KB gz.
+- **Use sub-path imports** — `semiotic/xy` (134KB gz), `semiotic/ordinal` (115KB gz), `semiotic/network` (121KB gz), `semiotic/geo` (94KB gz), `semiotic/realtime` (147KB gz), `semiotic/realtime/core` (140KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (125KB gz), `semiotic/server/node` (125KB gz), `semiotic/server/edge` (143KB gz), `semiotic/utils` (75KB gz), `semiotic/utils/core` (73KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (74KB gz), `semiotic/recipes/core` (74KB 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` (132KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (429KB gz), `semiotic/ai/core` (68KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 346KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
 
@@ -20,11 +20,11 @@ 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"), `tooltip="multi"` for hover-anywhere
+**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"`
 **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`.
 **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`, `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
+**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`
 **ConnectedScatterplot** — + `orderAccessor`, `regression`
 **QuadrantChart** — Scatterplot + `quadrants`, `xCenter`, `yCenter`
@@ -36,9 +36,9 @@ 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), `regression`
-**StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order)
-**GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default)
+**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (true | {topOpacity, bottomOpacity} | {colorStops}; 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`
 **BoxPlot** — + `showOutliers`, `outlierRadius`
 **Histogram** — + `bins` (25), `relative`. Always horizontal.
@@ -54,9 +54,11 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 
 All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
 
+**`styleRules`** (declarative threshold-aware styling — **every chart family**) — an ordered `StyleRule[]` where each `{ when, style }` matching a mark contributes its style, merged in list order so **the last applicable rule wins per property** (CSS-cascade model). Wired on: **ordinal** BarChart/StackedBarChart/GroupedBarChart (bars/segments); **XY** LineChart/AreaChart/StackedAreaChart (per-series) + Scatterplot/BubbleChart/QuadrantChart/ConnectedScatterplot (per-point); **network** ForceDirectedGraph/SankeyDiagram/ChordDiagram (nodes); **geo** ChoroplethMap (features) + ProportionalSymbolMap/DistanceCartogram (symbols); **physics** GaltonBoardChart/PhysicsPileChart/CollisionSwarmChart/EventDropChart (particles). `when` = predicate `(datum, ctx) => boolean`, a declarative threshold (`{ axis?: "x"|"y"|"value", field?, gt, gte, lt, lte, eq, ne, within:[min,max], outside, in:[...] }`), or `true`/omitted (always). `ctx` channels by family: bars `{ value, category }`; XY `{ value(=y), x, y }` (use `axis:"x"`/`"y"` to target either axis regardless of accessor field name); network/geo/physics `{ value, category }` (category = the colorBy/group). A rule's `style.fill` may be a color string or a **`HatchFill`** descriptor (`{ type:"hatch", background?, stroke?, spacing?, angle?, lineWidth?, lineOpacity? }`) resolving to a `CanvasPattern` on canvas and an SVG `<pattern>` in SSR — one declaration, both backends. Precedence: top-level primitives > per-mark style fn (`pieceStyle`/`pointStyle`/`nodeStyle`) > `styleRules` > base `colorBy`/`color`/theme. Works through `renderChart`/MCP for all wired families (use the declarative-threshold form, not predicates, when the config must serialize). `HatchFill` is also a `band`/`x-band` annotation `fill` and any scene `style.fill`. Caveats: line/area rules resolve per-series (sample datum, not per-vertex); network hierarchy charts (Tree/Treemap/CirclePack/Orbit) are NOT wired (their `colorByDepth` owns fill); MultiAxisLineChart/MinimapChart/CandlestickChart not wired. Exported from `semiotic` + each family entry + `semiotic/utils`: `StyleRule`, `resolveStyleRules`, `matchesThreshold`, `makeRuleValueResolver`, `makeXYRuleContext`, `makeNodeRuleContext`, `composeStyleRules`, `HatchFill`, `isHatchFill`. See `/features/style-rules`.
+
 ## Network Charts (`semiotic/network`)
 
-**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `edgeWidth`, `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`
+**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `edgeWidth`, `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)
 **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`
@@ -69,7 +71,7 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
 
 Import from `semiotic/geo` only — avoids d3-geo in non-geo bundles.
 
-**ChoroplethMap** — `areas` (GeoJSON Feature[] or "world-110m"), `valueAccessor`, `colorScheme`, `projection` ("equalEarth"), `graticule`, `tooltip`, `showLegend`
+**ChoroplethMap** — `areas` (GeoJSON Feature[] or "world-110m"), `valueAccessor`, `colorScheme`, `projection` ("equalEarth"), `graticule`, `tooltip`, `showLegend`, `styleRules` (flag features — rules see the feature with `properties` flattened; `fill` may be a HatchFill)
 **ProportionalSymbolMap** — `points`, `xAccessor` ("lon"), `yAccessor` ("lat"), `sizeBy`, `sizeRange`, `colorBy`, `areas?`
 **FlowMap** — `flows`, `nodes`, `valueAccessor`, `edgeColorBy`, `lineType`, `showParticles`
 **DistanceCartogram** — `points`, `center`, `costAccessor`, `strength`, `showRings`
@@ -82,7 +84,7 @@ Import from `semiotic/physics` only — not re-exported from the root `semiotic`
 
 Process/arrival/distribution charts backed by `StreamPhysicsFrame`. The settled projection is the chart; motion is explanatory context. Use when the movement has data semantics, not as decoration.
 
-**GaltonBoardChart** — `data`, `valueAccessor` ("value"), `bins` (21), `mode` ("sample"|"mechanical"), `pegRows`, `mechanicalCount`, `branchProbability`, `ballRadius`, `colorBy`, `seed`, `size`/`width`/`height`, `paused`, `frameProps`. Renders a deterministic Galton/Plinko-style distribution that settles into bins; mechanical mode can generate a seeded no-data demonstration.
+**GaltonBoardChart** — `data`, `valueAccessor` ("value"), `bins` (21), `mode` ("sample"|"mechanical"), `pegRows`, `mechanicalCount`, `branchProbability`, `ballRadius`, `colorBy`, `styleRules` (per-particle; `ctx.category` = colorBy group), `seed`, `size`/`width`/`height`, `paused`, `frameProps`. Renders a deterministic Galton/Plinko-style distribution that settles into bins; mechanical mode can generate a seeded no-data demonstration.
 **EventDropChart** — `data`, `timeAccessor` ("time"), `arrivalAccessor` ("arrivalTime"), `windows` ({size}), `watermark` ({delay}|fn), `timeScale`, `ballRadius`, `colorBy`, `seed`, `size`, `paused`, `frameProps`. Use for event-time arrival, lateness, and watermark-window stories.
 **PhysicsPileChart** — `data`, `categoryAccessor` ("category"), `valueAccessor` ("value"), `mode` ("sample"|"mechanical"), `mechanicalCount`, `mechanicalCategories`, `unitValue` (1), `ballRadius`, `colorBy`, `seed`, `showProjection`, `size`, `paused`, `frameProps`. Unitizes values into repeated bodies that settle into category piles; mechanical mode can generate a seeded no-data capacity sketch; the default projection overlay keeps exact totals readable.
 **CollisionSwarmChart** — `data`, `xAccessor` ("x"), optional `groupAccessor`, `radiusAccessor`, `pointRadius`, `xExtent`, `collisionIterations`, `settle`, `showProjection`, `colorBy`, `seed`, `size`, `paused`, `frameProps`. Uses springs plus collisions to separate overlapping dots while preserving the quantitative axis and optional group lanes.
@@ -227,6 +229,7 @@ All HOCs accept `annotations`. Coordinates use data field names.
 **Reference lines**: `y-threshold` (`value`, `label`, `color`, `labelPosition`), `x-threshold`, `band` (`y0`, `y1`), `x-band` (`x0`, `x1`, `fill`, `fillOpacity` — full-height vertical region for eras/phases; skipped when either bound is missing)
 **Ordinal**: `category-highlight`
 **Enclosures**: `enclose`, `rect-enclose`, `highlight`
+**Label backgrounds**: every region-bounding annotation (`y-threshold`, `x-threshold`, `band`, `x-band`, `enclose`, `rect-enclose`, `category-highlight`) accepts `labelBackground` for a legibility backdrop behind the label text — `"halo"`/`true` (stroke halo in the plot bg; default for threshold/band labels), `"box"` (semitransparent rounded panel), `"none"`/`false` (plain), or a config `{ type: "halo"|"box", fill?, opacity? (0.85), padding? ({x,y}), radius? (3), stroke?, haloWidth? (3) }`. One shared renderer (`AnnotationLabel`) drives client + SSR, so it works on every frame and in server SVG. `band`/`x-band` `fill` also accepts a `HatchFill` for hatched regions.
 **Statistical**: `trend`, `envelope`, `anomaly-band`, `forecast`
 **Streaming anchors**: `"fixed" | "latest" | "sticky" | "semantic"` — also exposed as `lifecycle.anchor` on the `semiotic/ai` annotation lifecycle. `"semantic"` is typed but currently falls back to fixed positioning; stableId-based re-resolution remains open.
 **Hierarchy**: any annotation accepts `emphasis: "primary" | "secondary"` across XY, ordinal, network, geo, and static SVG rendering. `secondary` dims (opacity 0.6) and yields z-order; `primary` paints at full weight and on top. Type-agnostic, no-op when unset; class hooks `annotation-emphasis--{primary|secondary}` for further styling.
@@ -336,6 +339,8 @@ Interface for proposing/scoring variants beyond `capability.variants`. The built
 
 These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.
 
+- **Accessible chart text uses direct chart props** (`accessibility.description-props`): High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.
+  Agent action: Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. For generated L1–L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.
 - **Data required by usage mode** (`props.data-required-by-usage-mode`): Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.
   Agent action: Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.
 - **Categorical color precedence** (`color.category-precedence`): When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.

package/README.md

@@ -16,16 +16,15 @@ 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.0
+## What's New in 3.8.2
 
-3.8.0 makes chart status, layout, and review workflows more explicit:
+3.8.2 makes the hosted MCP accessibility contract internally consistent:
 
-- `ChartContainer` notifications add a non-intrusive bell/popover for chart-level findings.
-- ForceDirectedGraph can run expensive layouts in a Web Worker with synchronous SSR/hydration parity.
-- `x-band` annotations, minimum-width interval lanes, and custom-layout readback make dense,
-  time-oriented charts easier to inspect.
-- The DataPitfalls bridge and GoFish DisplayList adapter remain experimental and are exposed from
-  `semiotic/experimental` with `unstable_` names.
+- Chart schemas, validation, repair guidance, and audits consistently expose `title`,
+  `description`, `summary`, and `accessibleTable`.
+- Hosted `getChartSchema` returns structured output for component lists, schemas, and errors,
+  including direct and `ChartContainer` accessibility guidance.
+- The public MCP profile remains a focused five-tool surface with render-proven `createChart` output.
 
 ```jsx
 import { LineChart } from "semiotic/xy"
@@ -372,34 +371,35 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **101 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **82 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **85 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **62 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **111 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
-| `semiotic/realtime/core` | **110 KB** | Streaming chart types, HOCs, and buffer helpers |
+| `semiotic/xy` | **134 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **115 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **121 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **94 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **147 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/realtime/core` | **140 KB** | Streaming chart types, HOCs, and buffer helpers |
 | `semiotic/realtime/react` | **1 KB** | Stream status and synced push hooks |
-| `semiotic/server` | **189 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/node` | **189 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/edge` | **188 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
-| `semiotic/utils` | **71 KB** | ThemeProvider, validators, serialization — no chart components |
-| `semiotic/utils/core` | **70 KB** | Theme helpers and serialization utilities |
-| `semiotic/utils/react` | **4 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
-| `semiotic/recipes` | **53 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
-| `semiotic/recipes/core` | **52 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
-| `semiotic/recipes/react` | **1 KB** | Glyph and React layout-selection helpers |
-| `semiotic/themes` | **6 KB** | Theme presets only (tufte, carbon, etc.) |
-| `semiotic/themes/core` | **6 KB** | Theme presets and token helpers |
-| `semiotic/themes/react` | **4 KB** | ThemeProvider/useTheme and hooks |
-| `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
-| `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
-| `semiotic/physics` | **98 KB** | GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, PhysicalFlowChart, PhysicsCustomChart |
+| `semiotic/server` | **125 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/node` | **125 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/edge` | **143 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
+| `semiotic/utils` | **75 KB** | ThemeProvider, validators, serialization — no chart components |
+| `semiotic/utils/core` | **73 KB** | Theme helpers and serialization utilities |
+| `semiotic/utils/react` | **6 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
+| `semiotic/recipes` | **74 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/recipes/core` | **74 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/recipes/react` | **2 KB** | Glyph and React layout-selection helpers |
+| `semiotic/themes` | **7 KB** | Theme presets only (tufte, carbon, etc.) |
+| `semiotic/themes/core` | **7 KB** | Theme presets and token helpers |
+| `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` | **132 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` | **394 KB** | All schema-backed charts + validation — optimized for LLM code generation |
-| `semiotic/ai/core` | **79 KB** | suggestCharts, validateProps, describeChart, repairChartConfig, tool adapters — no chart components |
-| `semiotic/controls` | **5 KB** | DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
-| `semiotic` | **258 KB** | Everything below (full bundle) |
+| `semiotic/ai` | **429 KB** | All schema-backed charts + validation — optimized for LLM code generation |
+| `semiotic/ai/core` | **68 KB** | suggestCharts, validateProps, describeChart, repairChartConfig, tool adapters — no chart components |
+| `semiotic/controls` | **12 KB** | DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
+| `semiotic/rough` | **3 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
+| `semiotic` | **346 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -420,33 +420,34 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
 
 | Public named import | Runtime | gzip cold-consumer bundle |
 |---|---:|---:|
-| `import { LineChart } from "semiotic"` | browser | **290.2 KiB** |
-| `import { LineChart } from "semiotic/xy"` | browser | **138.9 KiB** |
-| `import { BarChart } from "semiotic/ordinal"` | browser | **114.3 KiB** |
-| `import { SankeyDiagram } from "semiotic/network"` | browser | **118.2 KiB** |
-| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **157.2 KiB** |
-| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **157.2 KiB** |
+| `import { LineChart } from "semiotic"` | browser | **145.9 KiB** |
+| `import { LineChart } from "semiotic/xy"` | browser | **145.9 KiB** |
+| `import { BarChart } from "semiotic/ordinal"` | browser | **120.6 KiB** |
+| `import { SankeyDiagram } from "semiotic/network"` | browser | **125.7 KiB** |
+| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **118.3 KiB** |
+| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **166.2 KiB** |
 | `import { useStreamStatus } from "semiotic/realtime/react"` | browser | **0.6 KiB** |
-| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **109.5 KiB** |
+| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **114.7 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 | **249.5 KiB** |
-| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **190.7 KiB** |
-| `import { renderToImage } from "semiotic/server/node"` | node | **249.9 KiB** |
-| `import { suggestCharts } from "semiotic/ai"` | browser | **414.4 KiB** |
-| `import { suggestCharts } from "semiotic/ai/core"` | browser | **44.0 KiB** |
+| `import { renderChart } from "semiotic/server"` | node | **165.0 KiB** |
+| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **80.9 KiB** |
+| `import { renderToImage } from "semiotic/server/node"` | node | **165.4 KiB** |
+| `import { suggestCharts } from "semiotic/ai"` | browser | **204.9 KiB** |
+| `import { suggestCharts } from "semiotic/ai/core"` | browser | **31.1 KiB** |
 | `import { bin } from "semiotic/data"` | browser | **0.4 KiB** |
-| `import { ChoroplethMap } from "semiotic/geo"` | browser | **102.8 KiB** |
+| `import { ChoroplethMap } from "semiotic/geo"` | browser | **105.2 KiB** |
+| `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.3 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes"` | browser | **3.4 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes/core"` | browser | **3.4 KiB** |
 | `import { ThemeProvider } from "semiotic/themes/react"` | browser | **4.4 KiB** |
-| `import { validateProps } from "semiotic/utils"` | browser | **20.4 KiB** |
-| `import { smartTickFormat } from "semiotic/utils/core"` | browser | **18.9 KiB** |
-| `import { useReducedMotion } from "semiotic/utils/react"` | browser | **1.8 KiB** |
-| `import { waffleLayout } from "semiotic/recipes"` | browser | **1.3 KiB** |
-| `import { waffleLayout } from "semiotic/recipes/core"` | browser | **1.3 KiB** |
-| `import { Glyph } from "semiotic/recipes/react"` | browser | **0.9 KiB** |
-| `import { BigNumber } from "semiotic/value"` | browser | **5.6 KiB** |
+| `import { validateProps } from "semiotic/utils"` | browser | **6.4 KiB** |
+| `import { smartTickFormat } from "semiotic/utils/core"` | browser | **0.2 KiB** |
+| `import { useReducedMotion } from "semiotic/utils/react"` | browser | **0.3 KiB** |
+| `import { waffleLayout } from "semiotic/recipes"` | browser | **2.5 KiB** |
+| `import { waffleLayout } from "semiotic/recipes/core"` | browser | **2.5 KiB** |
+| `import { Glyph } from "semiotic/recipes/react"` | browser | **0.8 KiB** |
+| `import { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** |
 | `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.3 KiB** |
 
 <!-- semiotic-cold-consumer:end -->
@@ -459,9 +460,9 @@ import { SankeyDiagram } from "semiotic/network"
 import { ChoroplethMap } from "semiotic/geo"
 ```
 
-**Tree-shaking**: Each sub-path is a separate, pre-bundled artifact marked `"sideEffects": false`, so importing from `semiotic/xy` never pulls in `semiotic/ordinal` or `semiotic/network`. Note the boundary: within a family artifact the charts are **already combined into one module**, so importing only `LineChart` from `semiotic/xy` still loads the whole XY family artifact (≈98 KB gz) — bundlers cannot tree-shake individual charts back out of a pre-bundled family. Cross-family separation is real; per-chart separation within a family is not (granular per-chart entries are planned). Pick the narrowest sub-path for your charts.
+**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"`**: 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.
+**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.
 
 ## TypeScript
 

package/ai/behaviorContracts.cjs

@@ -147,6 +147,15 @@ const PUSH_MODE_COMPONENTS = [
 const STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema()
 
 const BEHAVIOR_CONTRACTS = [
+  {
+    id: "accessibility.description-props",
+    category: "accessibility",
+    title: "Accessible chart text uses direct chart props",
+    severity: "warning",
+    appliesTo: {},
+    summary: "High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.",
+    agentAction: "Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. For generated L1–L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.",
+  },
   {
     id: "props.data-required-by-usage-mode",
     category: "required-props",