semiotic 3.8.0 → 3.8.1

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` (108KB gz), `semiotic/ordinal` (88KB gz), `semiotic/network` (93KB gz), `semiotic/geo` (66KB gz), `semiotic/realtime` (119KB gz), `semiotic/realtime/core` (118KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (124KB gz), `semiotic/server/node` (124KB gz), `semiotic/server/edge` (123KB gz), `semiotic/utils` (59KB gz), `semiotic/utils/core` (58KB 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` (104KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (394KB gz), `semiotic/ai/core` (67KB gz), `semiotic/controls` (10KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 251KB 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.

package/README.md

@@ -16,16 +16,14 @@ 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.1
 
-3.8.0 makes chart status, layout, and review workflows more explicit:
+3.8.1 makes the hosted MCP rendering path release-ready:
 
-- `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.
+- Stateless HTTP requests no longer cancel rendering after a completed request body.
+- Hosted `createChart` now has verified SVG and render evidence with `render-proven` status.
+- `GET /health` is the sole supported MCP health endpoint; nightly remains `main`-based while
+  stable deployments are pinned to published releases.
 
 ```jsx
 import { LineChart } from "semiotic/xy"
@@ -372,18 +370,18 @@ 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` | **108 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **88 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **93 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **66 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **119 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/realtime/core` | **118 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/server` | **124 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/node` | **124 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/edge` | **123 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
+| `semiotic/utils` | **59 KB** | ThemeProvider, validators, serialization — no chart components |
+| `semiotic/utils/core` | **58 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, …) |
@@ -393,13 +391,14 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
 | `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/physics` | **104 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/core` | **67 KB** | suggestCharts, validateProps, describeChart, repairChartConfig, tool adapters — no chart components |
+| `semiotic/controls` | **10 KB** | DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
+| `semiotic/rough` | **3 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
+| `semiotic` | **251 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -420,33 +419,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 | **281.3 KiB** |
+| `import { LineChart } from "semiotic/xy"` | browser | **143.8 KiB** |
+| `import { BarChart } from "semiotic/ordinal"` | browser | **119.1 KiB** |
+| `import { SankeyDiagram } from "semiotic/network"` | browser | **124.4 KiB** |
+| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **163.5 KiB** |
+| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **163.4 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 | **113.6 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 | **164.7 KiB** |
+| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **79.9 KiB** |
+| `import { renderToImage } from "semiotic/server/node"` | node | **165.1 KiB** |
+| `import { suggestCharts } from "semiotic/ai"` | browser | **413.4 KiB** |
+| `import { suggestCharts } from "semiotic/ai/core"` | browser | **30.6 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 | **104.1 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 { validateProps } from "semiotic/utils"` | browser | **7.9 KiB** |
+| `import { smartTickFormat } from "semiotic/utils/core"` | browser | **2.1 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 { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** |
 | `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.3 KiB** |
 
 <!-- semiotic-cold-consumer:end -->

package/ai/dist/mcp-server.js

@@ -4036,7 +4036,7 @@ var require_core = __commonJS({
       constructor(opts = {}) {
         this.schemas = {};
         this.refs = {};
-        this.formats = {};
+        this.formats = /* @__PURE__ */ Object.create(null);
         this._compilations = /* @__PURE__ */ new Set();
         this._loading = {};
         this._cache = /* @__PURE__ */ new Map();
@@ -32383,6 +32383,59 @@ function resolveHTTPListenHost(args, env = process.env) {
   return getFlagValue(args, "--host")?.trim() || env.MCP_HOST?.trim() || DEFAULT_HTTP_HOST;
 }
 
+// ai/mcp-request-cancellation.ts
+function createMcpRequestCancellationSignal(req, res) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  req.once("aborted", abort);
+  req.once("close", () => {
+    if (!req.complete) abort();
+  });
+  res.once("close", () => {
+    if (!res.writableFinished) abort();
+  });
+  return controller.signal;
+}
+
+// ai/mcp-build-info.ts
+function nonEmptyEnvValue(env, name) {
+  const value = env[name]?.trim();
+  return value || void 0;
+}
+function normalizeGitSha(value) {
+  return value && /^[0-9a-f]{40,128}$/i.test(value) ? value.toLowerCase() : void 0;
+}
+function resolveDeploymentChannel(value) {
+  return value?.toLowerCase() === "nightly" ? "nightly" : "stable";
+}
+function resolveSemioticBuildInfo(options) {
+  const env = options.env ?? process.env;
+  const commitSha = normalizeGitSha(nonEmptyEnvValue(env, "SEMIOTIC_GIT_SHA"));
+  return {
+    channel: resolveDeploymentChannel(
+      nonEmptyEnvValue(env, "SEMIOTIC_DEPLOYMENT_CHANNEL")
+    ),
+    packageVersion: options.packageVersion,
+    surfaceVersion: options.surfaceVersion,
+    ...commitSha ? { commitSha, shortCommitSha: commitSha.slice(0, 7) } : {},
+    ...nonEmptyEnvValue(env, "SEMIOTIC_BUILD_ID") ? { buildId: nonEmptyEnvValue(env, "SEMIOTIC_BUILD_ID") } : {},
+    ...nonEmptyEnvValue(env, "SEMIOTIC_BUILD_TIME") ? { builtAt: nonEmptyEnvValue(env, "SEMIOTIC_BUILD_TIME") } : {},
+    toolProfile: options.toolProfile,
+    nodeVersion: options.nodeVersion ?? process.version
+  };
+}
+function mcpServerInfoForBuild(buildInfo) {
+  if (buildInfo.channel !== "nightly") {
+    return { name: "semiotic", version: buildInfo.packageVersion };
+  }
+  const packageVersion = buildInfo.packageVersion.split("+", 1)[0];
+  const nightlyVersion = packageVersion.includes("-nightly") ? packageVersion : `${packageVersion}-nightly`;
+  return {
+    name: "semiotic-nightly",
+    version: `${nightlyVersion}+${buildInfo.shortCommitSha || "unknown"}`
+  };
+}
+
 // ai/mcp-logging.ts
 var DEFAULT_MCP_LOG_LEVEL = "info";
 var DEFAULT_MCP_LOG_RETENTION_DAYS = 30;
@@ -32422,7 +32475,6 @@ var SAFE_ROUTES = /* @__PURE__ */ new Set([
   "/",
   "/mcp",
   "/health",
-  "/healthz",
   "/.well-known/openai-apps-challenge"
 ]);
 function boundedPositiveInteger(value, fallback, min, max) {
@@ -33059,6 +33111,12 @@ var {
 } = import_behaviorContracts.default;
 var schemaPath = path.resolve(__dirname, "../schema.json");
 var schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+var packageManifestPath = path.resolve(__dirname, "../../package.json");
+var packageManifest = JSON.parse(fs.readFileSync(packageManifestPath, "utf-8"));
+if (typeof packageManifest.version !== "string" || !packageManifest.version) {
+  throw new Error("Semiotic package.json must provide a package version");
+}
+var PACKAGE_VERSION = packageManifest.version;
 var schemaByComponent = {};
 for (const tool of schema.tools) {
   schemaByComponent[tool.function.name] = tool.function;
@@ -33700,7 +33758,14 @@ function capInteractiveWidgetResult(result) {
     setting: "MCP_MAX_WIDGET_OUTPUT_BYTES"
   });
 }
-var SURFACE_VERSION = `${schema.version || "3.0.0"}-ai`;
+var SURFACE_VERSION = `${PACKAGE_VERSION}-ai`;
+function buildInfoForProfile(profile) {
+  return resolveSemioticBuildInfo({
+    packageVersion: PACKAGE_VERSION,
+    surfaceVersion: SURFACE_VERSION,
+    toolProfile: profile
+  });
+}
 function profileResult(result) {
   return { ...result, surfaceVersion: SURFACE_VERSION };
 }
@@ -34610,15 +34675,25 @@ var READ_ONLY_TOOL_ANNOTATIONS = {
   openWorldHint: false
 };
 function createServer2(profile = "developer", options = {}) {
+  const buildInfo = buildInfoForProfile(profile);
   const serverRenderContext = {
     signal: options.signal,
     limits: options.limits ?? resolveMcpRenderExecutionLimits()
   };
   const srv = new McpServer({
-    name: "semiotic",
-    version: schema.version || "3.0.0",
+    ...mcpServerInfoForBuild(buildInfo),
     description: "Deterministic Semiotic chart selection, validation, rendering, and non-visual chart grounding. Use suggestCharts, getSchema, diagnoseConfig, and renderChart in that order for static chart generation."
   });
+  srv.registerResource(
+    "semiotic-build-info",
+    "semiotic://build-info",
+    {
+      title: "Semiotic Build Information",
+      description: "Read-only deployment identity for this Semiotic MCP server.",
+      mimeType: "application/json"
+    },
+    (uri) => textResource(uri, "application/json", JSON.stringify(buildInfo, null, 2))
+  );
   srv.registerResource(
     "semiotic-schema",
     "semiotic://schema",
@@ -35223,19 +35298,26 @@ async function main() {
         reason: "request_stream_error"
       }));
     });
+    const buildInfo = buildInfoForProfile(toolProfile);
     const healthBody = () => JSON.stringify({
       status: "ok",
       name: "semiotic-mcp",
-      version: schema.version || "3.0.0",
+      version: buildInfo.packageVersion,
       transport: "streamable-http",
-      mode: "stateless"
+      mode: "stateless",
+      channel: buildInfo.channel,
+      packageVersion: buildInfo.packageVersion,
+      surfaceVersion: buildInfo.surfaceVersion,
+      ...buildInfo.commitSha ? { commitSha: buildInfo.commitSha } : {},
+      ...buildInfo.buildId ? { buildId: buildInfo.buildId } : {},
+      ...buildInfo.builtAt ? { builtAt: buildInfo.builtAt } : {}
     });
+    const writeHealthResponse = (res) => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(healthBody());
+    };
     const httpServer = http.createServer(async (req, res) => {
       const requestStartedAt = Date.now();
-      const requestAbortController = new AbortController();
-      const abortRequest = () => requestAbortController.abort();
-      req.on("aborted", abortRequest);
-      req.on("close", abortRequest);
       const pathname = (() => {
         try {
           return new URL(req.url || "/", "http://localhost").pathname;
@@ -35288,9 +35370,8 @@ async function main() {
           return;
         }
       }
-      if (req.method === "GET" && (pathname === "/healthz" || pathname === "/health")) {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(healthBody());
+      if (req.method === "GET" && pathname === "/health") {
+        writeHealthResponse(res);
         return;
       }
       if (req.method === "GET" && pathname === "/.well-known/openai-apps-challenge" && openaiAppsChallengeToken) {
@@ -35312,8 +35393,7 @@ async function main() {
           res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Method not allowed (stateless server offers no SSE stream)" }, id: null }));
           return;
         }
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(healthBody());
+        writeHealthResponse(res);
         return;
       }
       if (req.method !== "POST") {
@@ -35321,6 +35401,7 @@ async function main() {
         res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Method not allowed" }, id: null }));
         return;
       }
+      const requestAbortSignal = createMcpRequestCancellationSignal(req, res);
       if (!hasSupportedAccept(String(req.headers.accept || ""))) {
         mcpLogger.warn("request_rejected", {
           reason: "unsupported_accept",
@@ -35396,7 +35477,7 @@ async function main() {
           return;
         }
         const srv = createServer2(toolProfile, {
-          signal: requestAbortController.signal,
+          signal: requestAbortSignal,
           limits: renderExecutionLimits
         });
         const transport = new StreamableHTTPServerTransport({

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.8.0",
+  "version": "3.8.1",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {

package/ai/surface-manifest.json

@@ -7,7 +7,7 @@
     "src/components/semiotic-ai.ts",
     "ai/mcp-server.ts"
   ],
-  "version": "3.8.0",
+  "version": "3.8.1",
   "components": {
     "schema": 54,
     "aiChartExports": 51,
@@ -181,9 +181,10 @@
       ],
       "activation": "semiotic-mcp --profile public or MCP_TOOL_PROFILE=public"
     },
-    "resourceCount": 7,
+    "resourceCount": 8,
     "resources": [
       "semiotic-behavior-contracts",
+      "semiotic-build-info",
       "semiotic-chatgpt-chart-widget",
       "semiotic-components",
       "semiotic-examples",

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- 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` (108KB gz), `semiotic/ordinal` (88KB gz), `semiotic/network` (93KB gz), `semiotic/geo` (66KB gz), `semiotic/realtime` (119KB gz), `semiotic/realtime/core` (118KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (124KB gz), `semiotic/server/node` (124KB gz), `semiotic/server/edge` (123KB gz), `semiotic/utils` (59KB gz), `semiotic/utils/core` (58KB 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` (104KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (394KB gz), `semiotic/ai/core` (67KB gz), `semiotic/controls` (10KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 251KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
@@ -89,12 +89,13 @@ For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdin
 `onClick={(datum, { x, y }) => ...}` — called when a data element is clicked. Receives the original datum and pixel coordinates. Works on lines, bars, areas, pie slices, nodes, and geo features.
 
 ### onObservation
-Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selection", datum: <your data>, x, y, timestamp, chartType, chartId }`. The `datum` field is your original data object. Hover-end/click-end events omit `datum`.
+Callback receiving `ChartObservation`. Pointer exploration emits `hover`/`click`; keyboard or structured traversal additionally emits semantic `focus`/`activate` with `inputType: "keyboard"|"pointer"|"touch"|"navigation-tree"`. Stable widget annotations emit `annotation-activate` with `annotationId`. Events also include `timestamp`, `chartType`, and optional `chartId`; datum events carry your original data object. Hover-end/click-end events omit `datum`.
 
 ### emphasis
 `emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
 
 ## Annotations (all chart families)
+- Give interactive `widget` annotations an `id`, `stableId`, or `provenance.stableId`; activation identity never falls back to array index. Observe widget activation on Stream Frames with `onAnnotationActivate`, or on HOCs through `frameProps.onAnnotationActivate`.
 - `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050", labelPosition: "right" }]}` — horizontal reference line (works on XY and vertical ordinal charts). `labelPosition`: "left"|"center"|"right"
 - `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff", labelPosition: "top" }]}` — vertical reference line. `labelPosition`: "top"|"center"|"bottom"
 - `annotations={[{ type: "callout-circle", x: 5, y: 20, label: "Peak", radius: 12 }]}` — data-bound callout; use `callout-rect` with `width`/`height` for a rectangular subject

package/dist/__tests__/scenarios/mcpProtocolTypes.d.ts

@@ -0,0 +1,20 @@
+import type { Datum } from "../../components/charts/shared/datumTypes";
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result: Datum;
+    error?: Datum;
+}
+export interface ListedMcpTool {
+    name: string;
+    _meta?: {
+        ui?: {
+            resourceUri: string;
+        };
+        "openai/outputTemplate"?: string;
+    };
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+    };
+}

package/dist/components/AccessibleNavTree.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import { type NavTreeNode } from "./ai/navigationTree";
+import { type OnObservationCallback } from "./store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "./charts/shared/annotationActivation";
 export interface AccessibleNavTreeProps {
     tree: NavTreeNode;
     /** Accessible name for the tree. */
@@ -22,5 +24,9 @@ export interface AccessibleNavTreeProps {
      * the conversation-arc store is enabled — zero-overhead otherwise.
      */
     chartId?: string;
+    /** Normalized focus/activation events produced by structured navigation. */
+    onObservation?: OnObservationCallback;
+    /** Observe activation of an annotation leaf in the navigation tree. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
 }
-export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId }: AccessibleNavTreeProps): React.JSX.Element;
+export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId, onObservation, onAnnotationActivate }: AccessibleNavTreeProps): React.JSX.Element;

package/dist/components/ai/chartClinicMetadata.generated.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AUTO-GENERATED from chartSpecs.ts and chartDefinitionPilot.ts by
+ * scripts/regenerate-schema.ts.
+ * Do not edit by hand; run `npm run docs:chart-specs:schema`.
+ */
+import type { ChartCategory } from "../charts/shared/chartSpecs";
+interface ChartClinicMetadata {
+    readonly category: ChartCategory;
+    readonly recommendedImport: string;
+    readonly serverImport?: "semiotic/server";
+    readonly docsRoute?: string;
+    readonly pilot?: true;
+}
+export declare const CHART_CLINIC_METADATA: Readonly<Record<string, ChartClinicMetadata>>;
+export {};

package/dist/components/ai/useNavigationSync.d.ts

@@ -1,3 +1,4 @@
+import type { ChartObservation } from "../store/ObservationStore";
 import type { NavTreeNode } from "./navigationTree";
 import type { Datum } from "../charts/shared/datumTypes";
 /**
@@ -29,8 +30,12 @@ export interface UseNavigationSyncOptions {
     matchFields?: string[];
     /** Selection name shared with the chart's `selection={{ name }}`. Default "__semiotic-nav-sync". */
     selectionName?: string;
-    /** Which canvas observations move the tree. Default ["hover", "click"]. */
-    observe?: Array<"hover" | "click">;
+    /**
+     * Which chart observations move the tree. Defaults to pointer hover/click
+     * plus keyboard focus/activation so raw frames and HOC charts stay in sync
+     * for both pointer and keyboard readers.
+     */
+    observe?: Array<"hover" | "click" | "focus" | "activate">;
     /**
      * The chart's annotations. An annotation anchored to a datum carries that
      * datum's identifying fields (the same `matchFields` used for hover sync), so
@@ -49,6 +54,16 @@ export interface UseNavigationSyncResult {
     selection: {
         name: string;
     };
+    /**
+     * Feed a chart observation directly into the sync. This is useful for raw
+     * StreamFrames or custom interactions that call `onObservation` themselves
+     * instead of publishing through the chart HOCs. Matching pointer and
+     * keyboard observations move the tree; events later received from the global
+     * observation store are de-duplicated by object identity.
+     */
+    onObservation: (observation: ChartObservation) => void;
+    /** Alias of `onObservation` for composing an externally supplied handler. */
+    handleObservation: (observation: ChartObservation) => void;
     /** Nav-tree leaf ids that an annotation anchors to — mark these as "has a note". */
     annotatedIds: Set<string>;
     /**

package/dist/components/chartContainerMobile.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+import type { MobileStandardControlRequest, MobileStandardControlsProps } from "./MobileStandardControls";
+import type { MobileInteractionProp } from "./charts/shared/types";
+export declare function canReceiveChartProps(child: ReactElement): boolean;
+export declare function isMobileStandardControlsProps(value: MobileStandardControlRequest | MobileStandardControlsProps | undefined): value is MobileStandardControlsProps;
+export declare function standardControlsFromInteraction(mobileInteraction: MobileInteractionProp | undefined): MobileStandardControlRequest | undefined;
+export declare function targetSizeFromInteraction(mobileInteraction: MobileInteractionProp | undefined): number | undefined;
+export declare function hasStandardControlsRequest(request: MobileStandardControlRequest | undefined): request is MobileStandardControlRequest;
+export declare function withStandardControls(source: MobileInteractionProp | undefined, controls: MobileStandardControlRequest | undefined): MobileInteractionProp | undefined;