semiotic 3.13.2 → 3.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (214) hide show
  1. package/README.md +47 -46
  2. package/ai/artifact-surface-inventory.json +1 -1
  3. package/ai/dist/mcp-server.js +4 -4
  4. package/ai/reference.md +23 -12
  5. package/ai/schema.json +258 -96
  6. package/ai/surface-manifest.json +1 -1
  7. package/ai/task-packets/compare-category-totals.json +5 -5
  8. package/ai/task-packets/compare-category-totals.md +2 -2
  9. package/ai/task-packets/correct-published-chart.json +5 -5
  10. package/ai/task-packets/correct-published-chart.md +2 -2
  11. package/ai/task-packets/index.json +6 -6
  12. package/ai/task-packets/update-live-chart.json +5 -5
  13. package/ai/task-packets/update-live-chart.md +2 -2
  14. package/dist/c-2YFVDRU4.min.js +1 -0
  15. package/dist/c-4OVDIXAR.min.js +1 -0
  16. package/dist/c-57IIWW46.min.js +1 -0
  17. package/dist/c-62UTMRQE.min.js +1 -0
  18. package/dist/c-6QV6F3U7.min.js +1 -0
  19. package/dist/c-7S46KBYD.min.js +2 -0
  20. package/dist/c-AJSS332Z.min.js +2 -0
  21. package/dist/c-B3X2IJRQ.min.js +1 -0
  22. package/dist/c-BLLDBVFK.min.js +38 -0
  23. package/dist/c-C7TT4J7K.min.js +1 -0
  24. package/dist/{c-ZMB3VTD4.min.js → c-CJ5GA7DM.min.js} +1 -1
  25. package/dist/c-D7YDFHLY.min.js +1 -0
  26. package/dist/{c-BR2TOCUN.min.js → c-DMDFJQU4.min.js} +1 -1
  27. package/dist/{c-JDU4Y4IW.min.js → c-FRVHZIGR.min.js} +1 -1
  28. package/dist/{c-MSZ3ZDAP.min.js → c-HAZCVHI7.min.js} +1 -1
  29. package/dist/c-HN5U72U7.min.js +1 -0
  30. package/dist/c-JA5F7ITS.min.js +1 -0
  31. package/dist/{c-ISHYKYII.min.js → c-JVZRD4GL.min.js} +1 -1
  32. package/dist/{c-OOR2LN4A.min.js → c-KJGJEOSV.min.js} +1 -1
  33. package/dist/c-M2TPZE7P.min.js +1 -0
  34. package/dist/c-OA6RJZ7S.min.js +1 -0
  35. package/dist/c-OBBSIOYU.min.js +1 -0
  36. package/dist/{c-SQQZPFVY.min.js → c-QPHM7AWW.min.js} +1 -1
  37. package/dist/{c-HOMJ3C6B.min.js → c-QSEAAHEU.min.js} +1 -1
  38. package/dist/c-RQWI623R.min.js +1 -0
  39. package/dist/{c-WFSEQ2XG.min.js → c-RWFADOKS.min.js} +1 -1
  40. package/dist/{c-SDGGMIYI.min.js → c-TJGC5JEM.min.js} +1 -1
  41. package/dist/{c-H5THWQI4.min.js → c-TOXWQRXS.min.js} +3 -3
  42. package/dist/c-VBDWHTC7.min.js +1 -0
  43. package/dist/c-VBIPDCE7.min.js +1 -0
  44. package/dist/c-WTNRBWZZ.min.js +51 -0
  45. package/dist/{c-3GIPT46Z.min.js → c-XG4LL2VI.min.js} +1 -1
  46. package/dist/c-XPNBS3W2.min.js +1 -0
  47. package/dist/c-XT3G3YWU.min.js +1 -0
  48. package/dist/c-ZP6O6UHV.min.js +1 -0
  49. package/dist/c-ZVL7ULNH.min.js +1 -0
  50. package/dist/components/ChartErrorBoundary.d.ts +5 -1
  51. package/dist/components/ai/intentWeights.d.ts +22 -0
  52. package/dist/components/ai/streamSchema.d.ts +98 -0
  53. package/dist/components/ai/streamingTypes.d.ts +27 -4
  54. package/dist/components/ai/suggestCharts.d.ts +10 -2
  55. package/dist/components/ai/suggestStreamCharts.d.ts +60 -13
  56. package/dist/components/ai/suggestStreamDashboard.d.ts +9 -1
  57. package/dist/components/charts/network/processSankey/frameMargins.d.ts +1 -1
  58. package/dist/components/charts/network/processSankey/labelPlacement.d.ts +1 -1
  59. package/dist/components/charts/physics/physicsHocUtils.d.ts +1 -1
  60. package/dist/components/charts/realtime/RealtimeAccumulator.d.ts +7 -0
  61. package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +9 -2
  62. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +13 -1
  63. package/dist/components/charts/realtime/RealtimeLineChart.types.d.ts +5 -1
  64. package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +5 -1
  65. package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +7 -1
  66. package/dist/components/charts/realtime/TemporalHistogram.capability.d.ts +5 -3
  67. package/dist/components/charts/realtime/aggregate.d.ts +11 -12
  68. package/dist/components/charts/realtime/defaultRealtimeTooltip.d.ts +9 -0
  69. package/dist/components/charts/realtime/eventTime.d.ts +7 -1
  70. package/dist/components/charts/realtime/useRealtimeLineIngestion.d.ts +13 -0
  71. package/dist/components/charts/shared/ChartError.d.ts +4 -6
  72. package/dist/components/charts/shared/GaugeReadout.d.ts +39 -4
  73. package/dist/components/charts/shared/axisExtent.d.ts +2 -1
  74. package/dist/components/charts/shared/chartMode.d.ts +2 -2
  75. package/dist/components/charts/shared/gaugeLayout.d.ts +69 -0
  76. package/dist/components/charts/shared/types.d.ts +3 -0
  77. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +3 -0
  78. package/dist/components/charts/shared/useStreamStatus.d.ts +2 -2
  79. package/dist/components/charts/shared/withChartErrorBoundary.d.ts +14 -0
  80. package/dist/components/charts/xy/Scatterplot.streamCapability.d.ts +2 -0
  81. package/dist/components/charts/xy/WaterfallChart.d.ts +2 -0
  82. package/dist/components/charts/xy/WaterfallIndex.d.ts +12 -0
  83. package/dist/components/charts/xy/lineGapStrategy.d.ts +15 -3
  84. package/dist/components/legendGeometry.d.ts +148 -0
  85. package/dist/components/legendLayout.d.ts +20 -38
  86. package/dist/components/realtime/ReorderBuffer.d.ts +14 -0
  87. package/dist/components/realtime/SlidingExtent.d.ts +18 -0
  88. package/dist/components/realtime/WindowAccumulator.d.ts +5 -1
  89. package/dist/components/realtime/renderers/types.d.ts +1 -0
  90. package/dist/components/realtime/renderers/waterfallRenderer.d.ts +1 -1
  91. package/dist/components/recipes/compositional/edgeRouting.d.ts +9 -0
  92. package/dist/components/recipes/compositional/metrics.d.ts +2 -2
  93. package/dist/components/recipes/compositional/projection.d.ts +3 -1
  94. package/dist/components/recipes/compositional/routing.d.ts +3 -1
  95. package/dist/components/recipes/compositional/testFixtures.d.ts +4 -0
  96. package/dist/components/recipes/compositional/topology.d.ts +2 -0
  97. package/dist/components/recipes/compositional/types.d.ts +10 -1
  98. package/dist/components/recipes/compositional/useCompositionalInterfaces.d.ts +20 -0
  99. package/dist/components/semiotic-ai-core.d.ts +3 -2
  100. package/dist/components/semiotic-ai-stream.d.ts +3 -2
  101. package/dist/components/semiotic-recipes-react.d.ts +2 -0
  102. package/dist/components/semiotic-utils-core.d.ts +2 -0
  103. package/dist/components/server/serverChartConfigHeatmap.d.ts +13 -0
  104. package/dist/components/server/staticLegend.d.ts +5 -0
  105. package/dist/components/server/staticLegendText.d.ts +13 -0
  106. package/dist/components/server/staticSVGChrome.d.ts +2 -2
  107. package/dist/components/stream/DataSourceAdapter.d.ts +15 -62
  108. package/dist/components/stream/FrameRuntime.d.ts +3 -0
  109. package/dist/components/stream/GeoPipelineStore.d.ts +2 -0
  110. package/dist/components/stream/IngestActivity.d.ts +9 -0
  111. package/dist/components/stream/NetworkPipelineStore.d.ts +3 -1
  112. package/dist/components/stream/OrdinalPipelineStore.d.ts +5 -2
  113. package/dist/components/stream/OrdinalSVGOverlay.d.ts +1 -1
  114. package/dist/components/stream/PipelineStore.d.ts +8 -3
  115. package/dist/components/stream/accessibleDataRows.d.ts +1 -0
  116. package/dist/components/stream/axisTickUtils.d.ts +25 -5
  117. package/dist/components/stream/frameDefaultMargins.d.ts +26 -4
  118. package/dist/components/stream/frameKeyboardNavigation.d.ts +8 -1
  119. package/dist/components/stream/geoTypes.d.ts +2 -0
  120. package/dist/components/stream/graphKeyboardNavigation.d.ts +4 -2
  121. package/dist/components/stream/hitTestUtils.d.ts +7 -0
  122. package/dist/components/stream/keyboardNav.d.ts +3 -1
  123. package/dist/components/stream/navigationGraph.d.ts +10 -3
  124. package/dist/components/stream/networkFrameKeyboardNavigation.d.ts +2 -0
  125. package/dist/components/stream/networkNavGroups.d.ts +3 -0
  126. package/dist/components/stream/networkPipelineConfig.d.ts +1 -0
  127. package/dist/components/stream/networkSceneTypes.d.ts +10 -0
  128. package/dist/components/stream/networkSpatialNavigation.d.ts +3 -0
  129. package/dist/components/stream/networkTypes.d.ts +2 -0
  130. package/dist/components/stream/ordinalAxisTicks.d.ts +27 -0
  131. package/dist/components/stream/ordinalSceneBuilders/pieScene.d.ts +10 -0
  132. package/dist/components/stream/ordinalSceneBuilders/types.d.ts +2 -0
  133. package/dist/components/stream/ordinalTypes.d.ts +11 -2
  134. package/dist/components/stream/pipelineBufferUtils.d.ts +9 -0
  135. package/dist/components/stream/pipelineConfig.d.ts +7 -0
  136. package/dist/components/stream/pipelineDomainResolution.d.ts +3 -2
  137. package/dist/components/stream/roundScaleDomain.d.ts +9 -0
  138. package/dist/components/stream/stalenessBands.d.ts +1 -1
  139. package/dist/components/stream/svgOverlayUtils.d.ts +12 -0
  140. package/dist/components/stream/types.d.ts +10 -2
  141. package/dist/components/stream/useFrame.d.ts +7 -4
  142. package/dist/components/stream/useOrdinalFrameHandle.d.ts +4 -14
  143. package/dist/components/stream/useStalenessCheck.d.ts +5 -3
  144. package/dist/components/stream/useStreamingDataHandle.d.ts +24 -0
  145. package/dist/components/stream/useXYFrameHandle.d.ts +4 -14
  146. package/dist/components/stream/xyDateTicks.d.ts +33 -4
  147. package/dist/components/stream/xyFrameAxisTypes.d.ts +2 -0
  148. package/dist/components/stream/xyPlugins/registry.d.ts +7 -0
  149. package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts +11 -2
  150. package/dist/components/stream/xySceneBuilders/types.d.ts +4 -0
  151. package/dist/components/types/legendTypes.d.ts +12 -1
  152. package/dist/geo.min.js +155 -152
  153. package/dist/geo.module.min.js +1 -1
  154. package/dist/network.module.min.js +1 -1
  155. package/dist/ordinal.module.min.js +1 -1
  156. package/dist/physics.module.min.js +1 -1
  157. package/dist/processSankeyLayoutWorker.js +1 -1
  158. package/dist/semiotic-ai-core.d.ts +3 -2
  159. package/dist/semiotic-ai-core.min.js +5 -5
  160. package/dist/semiotic-ai-core.module.min.js +4 -4
  161. package/dist/semiotic-ai.module.min.js +2 -2
  162. package/dist/semiotic-artifact.min.js +6 -6
  163. package/dist/semiotic-artifact.module.min.js +5 -5
  164. package/dist/semiotic-atlas-selection.module.min.js +1 -1
  165. package/dist/semiotic-atlas.module.min.js +1 -1
  166. package/dist/semiotic-client-cjs-shared.min.js +1022 -1018
  167. package/dist/semiotic-client-compositional.module.min.js +1 -1
  168. package/dist/semiotic-client-shared.module.min.js +1 -1
  169. package/dist/semiotic-experimental-auxiliary.module.min.js +1 -1
  170. package/dist/semiotic-experimental-node-auxiliary.module.min.js +1 -1
  171. package/dist/semiotic-line.module.min.js +1 -1
  172. package/dist/semiotic-realtime-core.module.min.js +1 -1
  173. package/dist/semiotic-realtime-react.module.min.js +1 -1
  174. package/dist/semiotic-recipes-core-cjs-base.min.js +101 -101
  175. package/dist/semiotic-recipes-core.module.min.js +1 -1
  176. package/dist/semiotic-recipes-react.d.ts +2 -0
  177. package/dist/semiotic-recipes-react.min.js +8 -8
  178. package/dist/semiotic-server-edge-node.module.min.js +3 -3
  179. package/dist/semiotic-server-edge.min.js +399 -394
  180. package/dist/semiotic-server-edge.module.min.js +3 -3
  181. package/dist/semiotic-server-node.min.js +399 -394
  182. package/dist/semiotic-utils-core.d.ts +2 -0
  183. package/dist/semiotic-utils-core.min.js +11 -11
  184. package/dist/semiotic-utils-core.module.min.js +3 -3
  185. package/dist/semiotic-value.module.min.js +1 -1
  186. package/dist/semiotic.module.min.js +1 -1
  187. package/dist/server.min.js +399 -394
  188. package/dist/server.module.min.js +3 -3
  189. package/dist/xy.module.min.js +1 -1
  190. package/package.json +11 -11
  191. package/dist/c-27SDQN3J.min.js +0 -1
  192. package/dist/c-2N7IU2NY.min.js +0 -1
  193. package/dist/c-4EUQNA7N.min.js +0 -2
  194. package/dist/c-5EPR4KFB.min.js +0 -1
  195. package/dist/c-5KZ3NO6X.min.js +0 -1
  196. package/dist/c-7UN2WUMI.min.js +0 -1
  197. package/dist/c-BRBTXINY.min.js +0 -1
  198. package/dist/c-C3Z7ZRAA.min.js +0 -1
  199. package/dist/c-C4WRRUZ5.min.js +0 -1
  200. package/dist/c-CXDAWBOW.min.js +0 -1
  201. package/dist/c-DJ6DT5BL.min.js +0 -51
  202. package/dist/c-DNBFFE3P.min.js +0 -1
  203. package/dist/c-HR5AH3MA.min.js +0 -1
  204. package/dist/c-HTL37JCD.min.js +0 -1
  205. package/dist/c-JS2D7A2P.min.js +0 -1
  206. package/dist/c-L6OT4OVA.min.js +0 -1
  207. package/dist/c-NB2UEX5C.min.js +0 -1
  208. package/dist/c-OU7A3IUL.min.js +0 -1
  209. package/dist/c-PNLTF6YG.min.js +0 -37
  210. package/dist/c-QVKOXC3S.min.js +0 -1
  211. package/dist/c-SIQVOV6A.min.js +0 -1
  212. package/dist/c-TBMFC5CR.min.js +0 -1
  213. package/dist/c-XF5ILLBG.min.js +0 -1
  214. package/dist/c-YQHGEETR.min.js +0 -2
package/ai/reference.md CHANGED
@@ -10,7 +10,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
10
10
  - Install: `npm install semiotic`
11
11
  <!-- semiotic-bundle-sizes:start -->
12
12
  <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
13
- - **Use sub-path imports** — `semiotic/atlas` (321KB gz), `semiotic/atlas/core` (15KB gz), `semiotic/access` (31KB gz), `semiotic/evidence` (47KB gz), `semiotic/artifact` (125KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (145KB gz), `semiotic/xy` (183KB gz), `semiotic/ordinal` (134KB gz), `semiotic/network` (180KB gz), `semiotic/network/zoom` (189KB gz), `semiotic/network/perspective` (2KB gz), `semiotic/network/perspective/core` (3KB gz), `semiotic/vite` (1KB gz), `semiotic/geo` (111KB gz), `semiotic/realtime` (215KB gz), `semiotic/realtime/core` (213KB gz), `semiotic/realtime/react` (2KB gz), `semiotic/server` (278KB gz), `semiotic/server/node` (278KB gz), `semiotic/server/edge` (284KB gz), `semiotic/utils` (112KB gz), `semiotic/utils/core` (102KB gz), `semiotic/utils/react` (10KB gz), `semiotic/recipes` (117KB gz), `semiotic/recipes/core` (114KB gz), `semiotic/recipes/react` (3KB gz), `semiotic/themes` (13KB gz), `semiotic/themes/core` (13KB gz), `semiotic/themes/react` (9KB gz), `semiotic/data` (5KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (188KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (667KB gz), `semiotic/ai/core` (143KB gz), `semiotic/controls` (19KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (2KB gz). Full `semiotic` is 429KB gz.
13
+ - **Use sub-path imports** — `semiotic/atlas` (324KB gz), `semiotic/atlas/core` (15KB gz), `semiotic/access` (31KB gz), `semiotic/evidence` (47KB gz), `semiotic/artifact` (126KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (150KB gz), `semiotic/xy` (187KB gz), `semiotic/ordinal` (139KB gz), `semiotic/network` (183KB gz), `semiotic/network/zoom` (192KB gz), `semiotic/network/perspective` (2KB gz), `semiotic/network/perspective/core` (3KB gz), `semiotic/vite` (1KB gz), `semiotic/geo` (114KB gz), `semiotic/realtime` (222KB gz), `semiotic/realtime/core` (220KB gz), `semiotic/realtime/react` (2KB gz), `semiotic/server` (284KB gz), `semiotic/server/node` (284KB gz), `semiotic/server/edge` (289KB gz), `semiotic/utils` (113KB gz), `semiotic/utils/core` (102KB gz), `semiotic/utils/react` (10KB gz), `semiotic/recipes` (118KB gz), `semiotic/recipes/core` (115KB gz), `semiotic/recipes/react` (3KB gz), `semiotic/themes` (13KB gz), `semiotic/themes/core` (13KB gz), `semiotic/themes/react` (9KB gz), `semiotic/data` (5KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (190KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (680KB gz), `semiotic/ai/core` (148KB gz), `semiotic/controls` (19KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (2KB gz). Full `semiotic` is 437KB gz.
14
14
  <!-- semiotic-bundle-sizes:end -->
15
15
  - CLI: `npx -p semiotic semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y|--evaluate]` · MCP: `npx -y -p semiotic semiotic-mcp`
16
16
 
@@ -18,7 +18,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
18
18
  HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless you need control they don't expose. Stream Frames pass `RealtimeNode`/`RealtimeEdge` wrappers in callbacks, not your data. Every HOC accepts `frameProps`, has an error boundary + dev-mode validation. TypeScript `strict: true`.
19
19
 
20
20
  ## Common Props (chart HOCs only)
21
- `title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke`, `strokeWidth`, `opacity`, `enableHover` (true), `tooltip` (boolean | "multi" | function | config), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading`, `loadingContent` (ReactNode; `false` suppresses), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations`, `accessibleTable` (true; use `{ portalTarget: "element-id" }` to portal its interactive UI outside a consumer-owned `role="img"`), `hoverHighlight` (requires `colorBy`), `hoverRadius` (30), `animate` (boolean | {duration?, easing?, intro?}), `axisExtent` ("nice"|"exact" — pins first/last tick to data min/max; XY x/y + ordinal value axis only; override per XY axis with `frameProps.axes[i].extent`), `maxDevicePixelRatio` (canvas backing-store cap; defaults 3 desktop / 2 coarse-pointer or narrow viewports; very large canvases are further capped to an 8-megapixel, 16K-side backing-store budget; canvases repaint on browser zoom / display-density changes).
21
+ `title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke`, `strokeWidth`, `opacity`, `enableHover` (true), `tooltip` (boolean | "multi" | function | config), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading`, `loadingContent` (ReactNode; `false` suppresses), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations`, `accessibleTable` (true; use `{ portalTarget: "element-id" }` to portal its interactive UI outside a consumer-owned `role="img"`), `hoverHighlight` (requires `colorBy`), `hoverRadius` (30), `animate` (boolean | {duration?, easing?, intro?}), `axisExtent` ("nice"|"exact"|"rounded" — nice ticks stay inside the padded domain; exact includes its ends without value padding; rounded widens open XY y / ordinal value-domain ends after padding and final layout; pinned ends and explicit ticks stay fixed; override per XY axis with `frameProps.axes[i].extent`), `maxDevicePixelRatio` (canvas backing-store cap; defaults 3 desktop / 2 coarse-pointer or narrow viewports; very large canvases are further capped to an 8-megapixel, 16K-side backing-store budget; canvases repaint on browser zoom / display-density changes).
22
22
 
23
23
  **Resolved chart size**: `resolveChartSize(chartName, props)` from `semiotic/utils` or `semiotic/utils/core` returns the same viewport dimensions the chart uses: mode defaults, chart-specific primary sizes, explicit dimensions, supported `size` aliases, and responsive rules. Supply `containerSize: { width, height }` for measured responsive axes; without it, responsive axes return their initial fallback. Minimap includes its overview, ScatterplotMatrix reports its field/cell grid (excluding outside title/legend), and BigNumber retains CSS sizes including undefined for auto-sized inline content. `emptyContent`/`loadingContent` reserve the resolved chart slot, follow responsive sizing, and stretch custom content across the available width while centering its text.
24
24
 
@@ -64,7 +64,7 @@ All XY charts below (plus BumpChart and MinimapChart's detail chart) accept top-
64
64
  **RidgelinePlot** — + `bins`, `amplitude` (1.5)
65
65
  **DotPlot** — + `sort` ("auto"), `dotRadius`, `showGrid` (true default), `regression`
66
66
  **PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`, `valueFormat` (default tooltip)
67
- **DonutChart** — PieChart + `innerRadius` (60), `centerContent` (strings/numbers, including zero, render as native SVG text; custom HTML uses a correctly namespaced `foreignObject`)
67
+ **DonutChart** — PieChart + `innerRadius` (60), `centerContent` (strings/numbers, including zero, render as native SVG text; custom HTML uses a correctly namespaced `foreignObject`). Slices are identified by the legend and tooltips (no slice labels). An `innerRadius` too large for the available radius falls back to a 12px ring. In push mode the frame keeps its 200-row window unless `frameProps.windowSize` is raised.
68
68
  **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor?`, `connectorOpacity`, `orientation`, `valueFormat` (tooltip + vertical value-axis ticks)
69
69
  **RadarChart** — multivariate comparison on a shared radial axis. Long-form rows: one observation per series × attribute. `categoryAccessor` ("attribute"), `valueAccessor` ("value"), `seriesAccessor` (defaults to `colorBy`), `pointRadius` (4), `valueExtent` (`[0, data-max]` default), `valueFormat` (radial ticks + default tooltip). Axes must be comparable magnitudes.
70
70
  **SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (req), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`, `roundedTop` (pixel radius on outer ends of each lane; middles stay square; single-segment lanes round all four)
@@ -79,11 +79,13 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
79
79
 
80
80
  ## Network Charts (`semiotic/network`)
81
81
 
82
+ Sankey and tree/cluster layouts use 20px of symmetric padding in primary/mobile mode, with boundary labels facing into the plot instead of fixed side gutters. Treemap and partition use 10px, including when selected through `TreeDiagram.layout`; circlepack uses 40px. Titles and legends reserve their own space. Explicit `margin` overrides remain supported.
83
+
82
84
  **ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `nodeStroke`/`nodeStrokeWidth` (node-only outline), `edgeWidth`, `edgeColor`/`edgeOpacity` (edge-only stroke), `iterations` (300), `forceStrength` (0.1 — link-attraction multiplier), `layoutExecution` ("auto" default | "worker" | "sync" — auto runs big layouts in a Web Worker by estimated cost, sync fallback everywhere), `layoutLoadingContent` (ReactNode while worker layout pends; `false` suppresses), `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showLabels`, `nodeLabel`, `styleRules` (style groups of nodes — rules see the raw node; `ctx.category` = colorBy group). **Node vs edge stroking**: the generic `stroke`/`strokeWidth`/`opacity` style *all* marks uniformly; to stroke nodes and edges separately use node-only `nodeStroke`/`nodeStrokeWidth` (e.g. `nodeStroke="none"` drops the node ring) and edge-only `edgeColor`/`edgeWidth`/`edgeOpacity`. Precedence per property: specific > generic > built-in default.
83
85
  **SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `nodePaddingRatio`, `showLabels`
84
86
  **ProcessSankey** — temporal sankey with real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`; zero-duration OK), `domain` (req `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node), `nodeLabel` (visible lane-label accessor), `colorBy`/`colorScheme`/`showLegend`/`legendPosition`, `styleRules` (band fills; `fill` may be a color or **HatchFill** — canvas + SSR), `selection`/`linkedHover`, `selectionDatum` ("raw" default | "scene" — what selection predicates see), `pairing` ("value"|"temporal", default temporal), `packing` ("off"|"reuse"), `laneOrder` ("crossing-min"|"inside-out"|"crossing-min+inside-out"|"insertion"), `maxValueScale` (pixels-per-unit cap), `lanePlacement` ("stack"|"hug" — hug/binding maxValueScale also post-scale geometry-refines order), `lifetimeMode` ("full"|"half", default half), `ribbonLane` ("source"|"target"|"both"), `ribbonMinRun` (0 exact | pixel minimum | "auto" — **source-only feeder** runway + source-band handoff; not a general min-edge length), `showLaneRails`, `showLabels` (true|false|"auto" density budget; auto sheds keep deferred text for selection reveal), `labelPriorityAccessor` / `maxLabels` (auto priority + hard cap), `showQualityReadout` (crossings/pixel + non-fatal validation warnings), `layoutExecution` ("auto"|"worker"|"sync" — auto offloads packing/ordering to a module worker by cost; SSR always sync), `layoutWorkerThreshold`, `layoutLoadingContent`, `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showParticles` + `particleStyle`, `timeFormat`/`valueFormat`, push API via ref (`getScales` → time + centerlines; `getCustomLayout` → `{ layout, bands, ribbons, warnings, … }` with `layout.layoutQuality`). Pure quality helpers from `semiotic/network`: `diagnoseProcessSankeyLayout` / `diagnoseProcessSankeyProps` / `explainProcessSankeyLayout` (also fed into `diagnoseConfig("ProcessSankey", props)`). **Validation policy**: static/MCP hard-fail duplicate ids; React push warns on duplicates and strips non-finite systemIn/Out times. Static-graph cycles OK as long as edges move forward in time. Use ProcessSankey for time-stamped events; SankeyDiagram for static snapshots.
85
87
 
86
- ProcessSankey time values (`domain`, edge times, node lifetimes, and axis tick dates) accept numbers, JavaScript `Date` objects, numeric strings, or ISO date strings. The required domain is `[start, end]` with `start <= end`; JSON/MCP configs use numbers or strings. Numeric strings remain numeric. Date-only strings and ISO datetimes without an explicit timezone use UTC. `timeFormat` receives numbers for numeric domains and Dates for Date/ISO domains; explicit `axisTicks[].label` takes precedence. Omit `axisTicks` for automatic ticks or pass `[]` to hide them.
88
+ ProcessSankey time values (`domain`, edge times, node lifetimes, and axis tick dates) accept numbers, JavaScript `Date` objects, numeric strings, or ISO date strings. The required domain is `[start, end]` with `start <= end`; JSON/MCP configs use numbers or strings. Numeric strings remain numeric. Date-only strings and ISO datetimes without an explicit timezone use UTC. `timeFormat` receives numbers for numeric domains and Dates for Date/ISO domains; explicit `axisTicks[].label` takes precedence. Omit `axisTicks` for automatic ticks or pass `[]` to hide them. Horizontal ProcessSankey charts use 20px side padding with boundary labels fitted inside the plot; visible side legends reserve their measured width. Explicit margins remain authoritative unless legend content needs more space.
87
89
 
88
90
  **ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `showLabels`
89
91
  **TreeDiagram** — `data` (root), `layout`, `orientation`, `childrenAccessor`, `colorBy`, `colorByDepth`
@@ -175,7 +177,9 @@ Helpers exported: `buildFormatter`, `formatSignedDelta`, `formatDeltaPercent`, `
175
177
 
176
178
  Push API: `ref.current.push({time, value})`. All pushed data must include a time field.
177
179
 
178
- **RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`; **stacked** via `categoryAccessor` + `colors` — bars sum by category within each bin; **mirrored/diverging** via `direction="down"` flipping the value domain — pair two halves with a shared `timeExtent`/`valueExtent` for an up/down detail view, and overlay extra instances on the same extent for layered envelopes), **TemporalHistogram** (static sibling — same props minus `windowSize`/`windowMode`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap** (+ sequential `colorScheme`; use `colorScheme="custom"` with `customColorScale(value)` for a custom ramp), **Streaming Sankey** (StreamNetworkFrame + `showParticles`). All six named realtime chart forms expose `styleRules`; aggregate histogram/heatmap rules resolve against displayed bins/cells rather than arbitrary source rows.
180
+ XY and ordinal live buffers resize reactively with `windowSize`. Bounded `data` snapshots retain every row; the first live push applies sliding retention (newest `windowSize` rows), or grows from the loaded capacity up to `maxCapacity` (default 100,000), then slides. Realtime wrappers expose `maxCapacity`; other XY/ordinal HOCs accept it through `frameProps`. Replacement discards queued pushes from the previous dataset. `getData()` flushes pending history and live rows and returns an independent array containing the original row objects. Changing capacity preserves retained row timestamps; increasing it cannot recover evicted rows. Imperative clear dismisses hover and keyboard detail; data updates preserve keyboard focus while its datum survives.
181
+
182
+ **RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`; `aggregation="count"` counts events per bin instead of summing `valueAccessor`, for streams without a numeric field; **stacked** via `categoryAccessor` + `colors` — bars sum by category within each bin; **mirrored/diverging** via `direction="down"` flipping the value domain — pair two halves with a shared `timeExtent`/`valueExtent` for an up/down detail view, and overlay extra instances on the same extent for layered envelopes), **TemporalHistogram** (static sibling — same props minus `windowSize`/`windowMode`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap** (+ sequential `colorScheme`; use `colorScheme="custom"` with `customColorScale(value)` for a custom ramp; `showLegend` draws the gradient legend, off by default like `Heatmap`, tracking the live cell domain; empty bins draw no cell, so set `background` to make them read as "no data"; `categoryAccessor` does not colour binned cells), **Streaming Sankey** (StreamNetworkFrame + `showParticles`). All six named realtime chart forms expose `styleRules`; aggregate histogram/heatmap rules resolve against displayed bins/cells rather than arbitrary source rows.
179
183
 
180
184
  Temporal histograms accept `binAlign="start"` (default) or `binAlign="center"`. Center uses a zero-anchored grid whose bins span `[timestamp - binSize/2, timestamp + binSize/2)`, so samples on grid timestamps sit at bar centers. Automatic centered extents include full first/last bins; explicit `timeExtent` remains authoritative and clips partial bins. Aggregation, stacking, bin hover data, selection coverage, and brush snapping use the same shifted boundaries.
181
185
 
@@ -272,9 +276,14 @@ Layout signature differs by family:
272
276
  **Custom-chart authoring kit** (`semiotic/recipes`; `hitTarget*` also from `semiotic/xy`/`ordinal`/`network`). The shape every hand-built custom chart converges on — draw real marks in `overlays`, emit a **transparent scene node per mark** for interaction — is first-class:
273
277
  - **`createLineageDagFit(nodes, plot, config?)`** (`semiotic/recipes`): the same pure fit used by `lineageDagLayout`, accepting raw or ingested nodes. Returns resolved `lod`, `nodeWidth`, `nodeHeight`, `layerCount`, `maxLayerSize`, `nodeBounds(node)`, `project(layer, row)` and `invert(x, y)`. Fit each main/minimap plot and LOD separately; convert view rectangles through logical coordinates instead of copying recipe constants or scaling chart widths. Coordinates exclude frame margins/scroll. A collapsed single-layer axis inverts to `layer: null`; use the full minimap width. Automatic domains use actual layer/row extents, including negative layers and uncentered or sparse rows. Explicit `layerCount` reserves `[0, count - 1]` and `maxLayerSize` reserves a centered span of `size - 1`; both expand to include the data. The row mapping keeps a minimum span of one around its midpoint. Missing `isBackEdge` flags are inferred when source layer >= target layer; explicit booleans override inference. Directed edges have arrowheads and backedges use dashed loops routed inside the plot. Empty/tiny plots preserve minimum glyph sizes and can overflow; this helper does not describe unrelated custom layouts. `ref.getCustomLayout()` already reads back emitted scene positions.
274
278
  - **`createDagreFit(nodes, edges, plot, config?)`** / **`createFlextreeFit(nodes, plot, config?)`** (`semiotic/recipes`): the exact fit `dagreLayout` / `flextreeLayout` apply to authored positions (dagre includes edge waypoints; defaults 100×36 and 80×30). Returns `fit`, `scale`, `dx`, `dy`, `bounds` (authored space; `null` when nothing is drawn), `project(point)`, `invert(point)`, and `nodeBounds(node)` (equals the drawn rect). Plot coordinates exclude frame margins; apply a zoom camera with `projectNetworkPoint` / `invertNetworkRect` from `semiotic/network/zoom`.
275
- - **Compositional DAG interfaces** (`semiotic/recipes/core`): `prepareCompositionalGraph(graph)` validates a versioned graph of nodes, parts, ports, edges and explicit transfers; every connection keeps its own ID, including exact endpoint duplicates, and parts do not acquire dependencies by sharing an owner. `routeCompositionalGraph({ requestId, prepared, view, geometry, options: compositionalLayoutOptions({ mode }) })` solves authored positions in `route-only` mode or explicit order freedoms in bounded `optimize` mode and reports infeasible pins, missing anchors, unsupported compound routing and shared-channel congestion through `diagnostics`; retain the previous accepted scene when `status === "infeasible"`. Prepare and solve outside the synchronous scene callback, then pass `layoutConfig={{ prepared, solved, showParts }}` with `layout={compositionalDagLayout}` to `NetworkCustomChart`. The solved layout is deeply frozen but never freezes the caller's graph, view or geometry objects. `patchCompositionalGraph` validates semantic mutations atomically; `traceCompositionalGraph` follows supplied connections and transfers; `CompositionalLayoutController`, `createCompositionalWorkerEngine` and `installCompositionalWorker` run asynchronous engines (request IDs stay unique for a worker engine's lifetime, including cancelled requests; a Worker `error` or port `messageerror` rejects pending requests with `REVISION_WORKER_FAILED`, and a result the worker cannot post becomes an error response, so the controller keeps its accepted layout); `CompositionalNavigator` (`semiotic/recipes/react`) adds keyboard access to parts and ports; `projectCompositionalScroll` and `CompositionalMeasurementTransaction` handle explicit scrolling and bounded measurement corrections. Serialized graphs follow `semiotic/spec/v0.1/compositional-graph.schema.json`. These are layout helpers, not serialized MCP chart components; see `/custom-charts#compositional-dags`.
279
+ - **Compositional DAG interfaces** (`semiotic/recipes/core`): `prepareCompositionalGraph(graph)` validates a versioned graph of nodes, parts, ports, edges and explicit transfers; every connection keeps its own ID, including exact endpoint duplicates, and parts do not acquire dependencies by sharing an owner. `routeCompositionalGraph({ requestId, prepared, view, geometry, options: compositionalLayoutOptions({ mode }) })` solves authored positions in `route-only` mode or explicit order freedoms in bounded `optimize` mode and reports infeasible pins, missing anchors, unsupported compound routing and shared-channel congestion through `diagnostics`. Consumers drawing solved sections retain the previous accepted scene when `status === "infeasible"`; consumers drawing their own edges should use terminal routing or the authored-row fallback below. Prepare and solve outside the synchronous scene callback, then pass `layoutConfig={{ prepared, solved, showParts }}` with `layout={compositionalDagLayout}` to `NetworkCustomChart`. The solved layout is deeply frozen but never freezes the caller's graph, view or geometry objects. `patchCompositionalGraph` validates semantic mutations atomically; `traceCompositionalGraph` follows supplied connections and transfers; `CompositionalLayoutController`, `createCompositionalWorkerEngine` and `installCompositionalWorker` run asynchronous engines (request IDs stay unique for a worker engine's lifetime, including cancelled requests; a Worker `error` or port `messageerror` rejects pending requests with `REVISION_WORKER_FAILED`, and a result the worker cannot post becomes an error response, so the controller keeps its accepted layout); `CompositionalNavigator` (`semiotic/recipes/react`) adds keyboard access to parts and ports; `projectCompositionalScroll` and `CompositionalMeasurementTransaction` handle explicit scrolling and bounded measurement corrections. Serialized graphs follow `semiotic/spec/v0.1/compositional-graph.schema.json`. These are layout helpers, not serialized MCP chart components; see `/custom-charts#compositional-dags`.
280
+ - **Authored row routing**: select `compositionalLayoutOptions({ mode: "route-only", routing: "terminals" })` when drawing your own curves. Terminals are identical to orthogonal routing; sections contain anchor/escape points without commands, crossings use escape chords, congestion and bends are zero. Exact duplicates still fan by `laneGap` and require clearance. `routing: "bump"` emits one midpoint cubic with straight stubs (horizontal for LR/RL, vertical for TB/BT); metrics flatten each cubic into 24 segments. Neither mode avoids obstacles. Engine capabilities `terminalRouting` and `bumpRouting` explicitly advertise these modes. An edge hint `route: "none"` emits direct terminal geometry excluded from metrics and bundles; same-owner connections default to it, with `route: "auto"` restoring obstacle routing. A chain is a same-owner out-port → next in-port connection plus an in-port → out-port transfer on each row. Fixed chain order preserves meaning. Fully pinned `optimize` skips owner rank placement and permits compound/cyclic owner projections; semantic cycles still need `topology: "feedback"`, as do cyclic owner projections with movable owners.
281
+ - **Row router-failure fallback**: 3.13.2 discards geometry on `ROUTING_NO_PATH` or `ROUTING_LANE_SPACE`. An application drawing its own curves should compute fresh anchors from current authored rectangles before retaining any previous solution: LR source `(card.x + card.width, card.y + row.y + row.height / 2)`, target `(card.x, card.y + row.y + row.height / 2)`. Rows are owner-local; omitted rows use the card center, folded rows use authored proxy rectangles. Preserve each edge ID, retain diagnostics, and reject missing rows. With `CompositionalLayoutController`, inspect the boolean returned by `solve` and its diagnostics; a retained `controller.solution` is not fresh geometry after a failed solve. This does not claim an obstacle-safe solution. See the tested fallback recipe at `/custom-charts/custom-layouts#compositional-dags`; upgrading to `routing: "terminals"` bypasses orthogonal routing, while exact duplicate lane clearance can still fail.
282
+ - **Nested network rectangles**: overlapping rect scene nodes prefer the smaller rectangle; equal areas prefer the deeper node. Nodes win over edges. Set `navParentId` to the owner's scene ID for owner/row keyboard grouping: arrows move among siblings, Enter descends, Escape ascends, and accessible tables use a `group` column when the authored accessible data does not already provide one. Use unique scene IDs even for repeated local row IDs. `useCompositionalInterfaces(prepared, ownerId)` from `semiotic/recipes/react` exposes `{ items, isRemoved, onOwnerKeyDown, onItemKeyDown }` for themed controls; handlers take focus callbacks `{ focusOwner, focusItem }` and the item handler also takes its index.
283
+ - **Compositional worker recipe**: in an application-owned module worker call `installCompositionalWorker(self)`; in the main thread call `createCompositionalWorkerEngine(worker)` and `controller.solve(request, engine)` on a `CompositionalLayoutController`. Namespace other protocols with distinct message types. Use request IDs such as `${chartId}:${structuralKey}:${revision}` with a revision increment for every request, including retries/cancellations; key structural solving separately from metric payload polling. Dispose the controller and engine on teardown, and terminate a worker only when its owner no longer needs it.
284
+
276
285
  - **Edge identity**: `frameProps={{ edgeIdentity: "id", edgeIdAccessor: "id" }}` keys network edges by their own IDs instead of the default source+target pair, so duplicate connections between the same owners stay distinct across bounded data, pushes, updates and static rendering. The frame ref adds `updateEdgeById(id, updater)` (owners and the ID are immutable) and single-ID `removeEdge(id)`. Clear retained push data before switching back to pair identity so distinct connections do not merge; controlled edges and their ID accessor can be replaced together in one render. These are React frame props, not serialized config fields.
277
- - **Network hit precedence and overlay edges:** among containing rectangles, the smallest area wins; equal areas keep the first `sceneNodes` entry. Nodes win over edges. `networkEdgeHitTarget` (from `semiotic/network` or `semiotic/recipes`) supplies transparent `sceneEdges` for visible SVG overlays in identical plot coordinates. The default curved path hits only the stroke; `type: "bezier" | "ribbon"` also hits the filled interior. `interactive: false` is table-only. Return `edgeHitTesting: false` from the layout to skip all edge hover, clicks, and cursors while keeping nodes interactive; edge painting and accessible table rows remain intact. Exact Canvas path hits use a spatial index prepared at custom-layout scene commits, including conservative sub-curve bounds for common cubic links. Geometry, stroke width, fill and interaction changes refresh candidates; color-only restyles reuse them and zoom tolerance stays live. Tooltip updates do not rerender the retained frame. Arbitrary filled paths with heavily overlapping interiors can still require an exact scan; use the layout opt-out when those edges need no pointer interaction. Keep overlays pointer-transparent and enable normal hover/observation handling; keyboard navigation remains node-based.
286
+ - **Network hit precedence and overlay edges:** among containing rectangles, the smallest area wins; equal areas prefer the deeper node, then keep the first `sceneNodes` entry when depth is tied. Nodes win over edges. `networkEdgeHitTarget` (from `semiotic/network` or `semiotic/recipes`) supplies transparent `sceneEdges` for visible SVG overlays in identical plot coordinates. The default curved path hits only the stroke; `type: "bezier" | "ribbon"` also hits the filled interior. `interactive: false` is table-only. Return `edgeHitTesting: false` from the layout to skip all edge hover, clicks, and cursors while keeping nodes interactive; edge painting and accessible table rows remain intact. Exact Canvas path hits use a spatial index prepared at custom-layout scene commits, including conservative sub-curve bounds for common cubic links. Geometry, stroke width, fill and interaction changes refresh candidates; color-only restyles reuse them and zoom tolerance stays live. Tooltip updates do not rerender the retained frame. Arbitrary filled paths with heavily overlapping interiors can still require an exact scan; use the layout opt-out when those edges need no pointer interaction. Keep overlays pointer-transparent and enable normal hover/observation handling; keyboard navigation remains node-based.
278
287
  - **`hitTargetPoint`/`hitTargetRect`** (XY/ordinal) + **`networkHitTarget`** (circle or rect) + **`geoHitTarget`** (geo — same transparent `PointSceneNode`; project lon/lat via `ctx.scales.projectedPoint` first): a zero-opacity, fully-transparent, hit-tested node from `{x, y, (r|width,height), datum, id, cursor?}`. The optional CSS `cursor` reaches the retained canvas and SVG/static output; it is presentation only, so pair `cursor:"pointer"` with the frame's click/observation API when the mark activates something. The `id` becomes the node's `pointId`/`id` (annotation anchor + nav-tree leaf) **and** its transition key. This is how a custom chart inherits **accessibility** (keyboard nav, focus ring, data table), **annotation** anchoring, **AI**/`onObservation` + shared selection, and **chart-mode** transitions for free — replaces the `rgba(0,0,0,0)`+`opacity:0`+`pointId`+`_transitionKey` boilerplate. The visible glyph lives in `overlays`; the focus ring still draws on the invisible target. A keyboard-focused **geoarea** outlines its polygon (a shape focus ring) rather than a centroid dot.
279
288
  - **Radial coordinate kit**: `polarToXY`/`xyToAngle` (0 = up, clockwise), `angleScale`/`radiusScale`, `ringArcPath` (annular-sector / wedge / full-ring path), `TAU` — angle ⟂ radius for two-continuous-channel radial charts (the radial analogue of the decoration kit).
280
289
  - **Edge-router kit** (custom network edges): `curvedEdgePath` (S-curve + near-level side-bow), `orthogonalEdgePath`, `boxEdgeAnchors` (box exit/entry by direction), `fanOutBend` (fan parallel edges apart). Plus cubic-Bézier evaluation — `cubicPoint`/`cubicTangent` (sample a point/tangent along a `CubicCurve` to *seat a mark on the curve* — a node mid-edge, an arrowhead at the end) and `cubicPath` (serialize to SVG).
@@ -512,7 +521,7 @@ Heuristic chart-suggestion engine — no LLM required. Charts ship capability de
512
521
  - **`profileData(data, { rawInput?, seriesField?, identifiers?, fieldRoles? })`** → `ChartDataProfile`: per-role candidate fields (x/y/series/category/size/time), distinct counts, monotonicity, structure detection, normalized `fieldRoles`, and `identifiers`. Identifier/ignored fields are excluded from every encoding candidate. Semantic hints are `measure`, `dimension`, and `temporal`; exact hints are `x`, `y`, `size`, `category`, `series`, and `time`.
513
522
  - **`rederiveProfile(profile, { primary? })`** → a new coherent `ChartDataProfile` after candidate edits or explicit primary-role changes. It revalidates assignments and recomputes category/series/x counts, repeated/monotonic x, provenance, and stackability together; assigning an identifier or non-candidate throws.
514
523
  - **`deriveProfileFields(data, candidates, fieldRoles, { primary? })`** → the lower-level derived-field projection used by `rederiveProfile`; use it when a profiler adapter owns candidates separately from the complete profile object.
515
- - **`suggestCharts(data, { intent?, allow?, deny?, maxResults?, includeVariants?, minScore?, audience?, identifiers?, fieldRoles? })`** → ranked `Suggestion[]` with `{ component, family, importPath, variant?, score, intentScores, rubric, reasons, caveats, props, propContract }`. `props` is spreadable directly. `propContract` declares `componentKind`, whether chart-HOC defaults apply, the heading prop, and the valid mode vocabulary; the same per-component contracts live in `ai/surface-manifest.json#components.suggestionPropContracts`. Capability `fieldPolicy` declarations are enforced after `buildProps`, so custom accessor vocabularies and direct values cannot reintroduce an identifier as a measure. **Receivability**: set `audience.receptionModality` (`visual` default | `screen-reader` | `sonified` | `agent`); a non-visual channel audits each candidate and down-ranks charts the audience can't receive there (8-slice pie for a screen reader), adding the audit's findings to `caveats[]` (familiarity and receivability are separate axes). `accessibilityCaveats(auditResult)` distils any audit into the same caveat strings.
524
+ - **`suggestCharts(data, { intent?, allow?, deny?, maxResults?, includeVariants?, minScore?, audience?, identifiers?, fieldRoles? })`** → ranked `Suggestion[]` with `{ component, family, importPath, variant?, score, intentScores, rubric, reasons, caveats, props, propContract }`. `props` is spreadable directly. Without `intent`, intents are weighted from the profile (time axis → trend first; aggregated categories → rank; ≥10 rows per category → distribution; two plain measures → correlation; graph/hierarchy/geo keep the mean of non-zero intent scores), and `scoreChart`/variant discovery use the same weights. Charts scoring 0 are dropped unless `minScore: 0`. `propContract` declares `componentKind`, whether chart-HOC defaults apply, the heading prop, and the valid mode vocabulary; the same per-component contracts live in `ai/surface-manifest.json#components.suggestionPropContracts`. Capability `fieldPolicy` declarations are enforced after `buildProps`, so custom accessor vocabularies and direct values cannot reintroduce an identifier as a measure. **Receivability**: set `audience.receptionModality` (`visual` default | `screen-reader` | `sonified` | `agent`); a non-visual channel audits each candidate and down-ranks charts the audience can't receive there (8-slice pie for a screen reader), adding the audit's findings to `caveats[]` (familiarity and receivability are separate axes). `accessibilityCaveats(auditResult)` distils any audit into the same caveat strings.
516
525
  - **`scoreChart(component, data, { intent?, variantKey?, audience?, identifiers?, fieldRoles? })`** → evaluate a specific chart for a dataset. It applies the same audience familiarity, target, and non-visual receivability policy as `suggestCharts`, so a direct fit score and a ranked recommendation cannot disagree about the intended audience.
517
526
  - **`useChartSuggestions(data, options)`** → memoized React hook returning `{ suggestions, profile }`.
518
527
  - **`registerChartCapability(capability)`** / **`unregisterChartCapability(name)`** — runtime registration for custom charts.
@@ -521,8 +530,8 @@ Heuristic chart-suggestion engine — no LLM required. Charts ship capability de
521
530
  - **Variants** encode that settings change what a chart is good for (e.g. StackedAreaChart's `streamgraph` variant boosts trend, penalizes part-to-whole).
522
531
  - **Interrogation tie-in**: pass `includeSuggestions: true` to `useChartInterrogation` and the ranked list lands in `context.suggestions` for the LLM.
523
532
  - **MCP tool**: `suggestCharts(data, intent?)`.
524
- - **`suggestStreamCharts(schema, { intent?, audience?, maxResults? })`** → `{ suggestions, excluded, stretchSuggestions }`. Schema fields may declare `role: "key"`; `shape` is `append` | `keyed` | `aggregate`; `throughput` is a band or rows/sec. Ordinal/value push charts (BarChart, PieChart, BigNumber, GaugeChart, …) are registered alongside the six realtime XY charts. `importPath` is a free string. `explainStreamCapabilityFit` is the same result. **`suggestStreamDashboard(schemas, { audience, intent, budget })`** composes panels; `AudienceProfile.dashboard` holds cell budget, lead families, density, and window preference.
525
- - **`applyChangelog(handle, events, { key })`** maps insert/upsert/update/retract onto `push`/`update`/`remove`. `WindowAccumulator` can emit t-digest percentiles (`p95`, `p99`) and HyperLogLog distinct counts. Ring-buffer `capacity` aliases `windowSize` so "window" can mean `aggregate.window`. `StalenessConfig.state` / `settling` override ingest-age LIVE/STALE. Realtime charts SSR from controlled `data` (and `aggregate`) via `renderChart`. `RealtimeLineChart.seriesAccessor` starts a new line per group in push mode. Scatterplot (and Bubble/ConnectedScatterplot) expose top-level `pulse` / `decay` / `staleness`.
533
+ - **`suggestStreamCharts(schema, { intent?, audience?, maxResults?, minScore? })`** → `{ suggestions, excluded, stretchSuggestions, rankingIntents, warnings }`. Schema fields may declare `role: "key"`, `cardinality` (expected distinct values), and `additive` (whether summing across events is meaningful); `shape` is `append` | `keyed` | `aggregate`; `throughput` is a band or rows/sec. Key columns of a keyed table are category candidates, and time charts split one series per value of the series role or primary category. Without `intent`, intents are weighted from the schema (a measure over time ranks as a trend first) and listed in `rankingIntents`; zero-scored charts are dropped unless `minScore: 0`. Charts that total a measure (append-stream bars/pies, the running-total `RealtimeWaterfallChart`) rank lower while additivity is unknown, say what they sum in `caveats`, and are excluded for `additive: false`; `RealtimeHistogram` counts events (`aggregation: "count"`) unless the measure is additive. Numeric throughput sizes `windowSize`/`binSize`; at high throughput the line is suggested with `aggregate` windows and per-event swarms/waterfalls/scatters are excluded. `warnings` reports unknown keys, invalid kinds or hints, and duplicate fields (kind aliases like `"timestamp"` are repaired). Ordinal/value/xy push charts (BarChart, PieChart, Scatterplot, BigNumber, GaugeChart, …) are registered alongside the realtime XY charts. `importPath` is a free string. `explainStreamCapabilityFit(schema, component, options?)` explains one chart (`suggested` with rank, `excluded`, `filtered`, or `unknown`); without a component it returns the full result. **`suggestStreamDashboard(schemas, { audience, intent, budget })`** composes panels; `AudienceProfile.dashboard` holds cell budget, lead families, density, and window preference.
534
+ - **`applyChangelog(handle, events, { key })`** maps insert/upsert/update/retract onto `push`/`update`/`remove`. `WindowAccumulator` can emit t-digest percentiles (`p95`, `p99`) and HyperLogLog distinct counts. Ring-buffer `capacity` aliases `windowSize` so "window" can mean `aggregate.window`. `StalenessConfig.state` / `settling` override ingest-age LIVE/STALE. Realtime charts SSR from controlled `data` (and `aggregate`) via `renderChart`. `RealtimeLineChart.seriesAccessor` starts a new line per group in push mode, colours each series from the categorical palette (an explicit `stroke` applies to all), and shows a series legend unless `showLegend={false}`. A custom `tickFormatTime` should keep sub-second precision for short windows (its third argument receives every tick value); epoch-millisecond numbers get clock labels automatically. Scatterplot (and Bubble/ConnectedScatterplot) expose top-level `pulse` / `decay` / `staleness`.
526
535
  - **`inferIntent` prose mode** scores registered `IntentSignals.phrases`. `communicativeActForIntent` walks composed intents through the heaviest child.
527
536
 
528
537
  ### Conversation-arc telemetry (`semiotic/ai`)
@@ -658,7 +667,7 @@ Chart live regions announce keyboard focus without announcing pointer hover acro
658
667
  - **Tooltip chrome**: `tooltip={{ content: d => <ConsumerTooltip datum={d} />, chrome: "none" }}` explicitly leaves the visual surface to the consumer without marking/mutating the renderer. Config `content` receives authored data (or histogram bin data), including `allSeries`/`xValue` when present. Custom multi configs also accept `chrome`. Field configs (`{ fields, title, chrome }`) and `TooltipRoot chrome="none"` honor explicit policy. Set `<ThemeProvider theme={{ tooltip: { chrome: "none" } }}>` to apply the default to custom renderers across charts, including raw frame callbacks. An explicit chart chrome setting overrides the theme. Existing `markTooltipChrome`, element markers, and inline ownership detection remain supported. Empty content still suppresses the entire tooltip.
659
668
 
660
669
  - **`tooltip="multi"`** / **`tooltip={{ mode: "multi", content? }}`**: multi-series hover-anywhere for LineChart, AreaChart, StackedAreaChart, DifferenceChart (wires `tooltipMode:"multi"`). RealtimeHistogram/TemporalHistogram multi lists every stacked category in the hovered bin (anywhere in the column; empty bins show nothing); other realtime, ordinal, network, geo, and physics charts fall back to one datum. Built-in multi renderer when `content` is omitted. Custom multi: `tooltip={{ mode: "multi", content: (d) => … }}` — the function receives the unwrapped raw datum with hover-root `allSeries` / `xValue` re-attached (`{group, value, valuePx, color, datum}` entries; an ungrouped series has `group: ""`). In x-extent padding outside the data, rows and `xValue` snap to the first/last sample; keyboard focus gets the same rows. Legacy escape hatch: `tooltip={fn}` + `frameProps={{ tooltipMode: "multi" }}`.
661
- - **Legend**: "bottom" expands margin ~80px. Numeric margins are minima: chart-owned legends grow their side when measurement needs more room, while preserving a larger caller baseline. MultiAxisLineChart: use `legendPosition="bottom"`. A **bottom** legend is placed *outside* the bottom axis chrome (tick labels, axis title) so it doesn't overdraw it; the band is auto-measured. Top axes are opt-in, so a **top** legend reserves nothing by default — set `frameProps.legendLayout.axisGutter` for one. `axisGutter` also overrides the measured bottom band (`0` anchors to the plot edge); `sideGutter` is the left/right counterpart for plot-adjacent chrome, and `edgeGutter` defaults to 3px to keep a side legend's focus ring inside the SVG (`0` restores flush placement).
670
+ - **Legend**: "bottom" expands margin ~80px. Numeric margins are minima: chart-owned legends grow their side when measurement needs more room, while preserving a larger caller baseline. MultiAxisLineChart: use `legendPosition="bottom"`. A **bottom** legend is placed *outside* the bottom axis chrome (tick labels, axis title) so it doesn't overdraw it; the band is auto-measured. Top axes are opt-in, so a **top** legend reserves nothing by default — set `frameProps.legendLayout.axisGutter` for one. `axisGutter` also overrides the measured bottom band (`0` anchors to the plot edge); `sideGutter` is the left/right counterpart for plot-adjacent chrome, and `edgeGutter` defaults to 3px to keep a side legend's focus ring inside the SVG (`0` restores flush placement). Left/right legends stay inside the chart: items that pass the chart bottom wrap into columns, labels truncate with an ellipsis (full text kept as hover text and accessible name), and when columns still cannot hold every item the last slot reads "+N more" with the hidden names on hover. A measured side legend takes at most 30% of the chart width (never less than the 100px box); `frameProps.legendLayout.maxWidth` sets that cap for side legends. Empty-string categories are labelled "(empty)". Top/bottom legends reserve at most 40% of the chart height and collapse extra rows into "+N more"; a single item wider than the plot truncates with an ellipsis. The standalone `<Legend>` only fits when given `maxHeight`.
662
671
  - **Horizontal bars**: need wider left margin (`margin={{ left: 120 }}`).
663
672
  - **Log scale**: non-positive bounds are replaced by the smallest and largest positive plotted values. A log scale with no positive value uses `[1, 10]`. Zero and negative samples stay in the scene and clamp to that edge, with one warning. **`xScaleType: "time"`**: creates `scaleTime`; required for landmark ticks with timestamps.
664
673
  - **`barPadding`**: pixel value (40/60 default). Reduce for small charts.
@@ -667,7 +676,7 @@ Chart live regions announce keyboard focus without announcing pointer hover acro
667
676
  - **`hoverHighlight`**: requires `colorBy` as a string field on series/category charts. `RealtimeHistogram` and `TemporalHistogram` instead match `binStart` and highlight the whole column without a category accessor.
668
677
  - **`frameProps` style functions**: bypass HOC color resolution — use `colorBy` instead.
669
678
  - **Geo imports**: always `semiotic/geo`, never `semiotic`.
670
- - **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks, tickAnchor, extent }]`. `tickAnchor: "edges"` flips first tick's `text-anchor` to `start`, last to `end` (and `dominant-baseline` on vertical axes) so edge labels don't overflow. Pairs with `axisExtent: "exact"`. Per-axis `extent: "nice"|"exact"` overrides chart-level `axisExtent` (common: exact x / nice y). Exact on a **value (y)** axis also skips y `extentPadding`; exact on x only affects tick placement.
679
+ - **Axis config**: `frameProps.axes: [{ orient, includeMin, includeMax, autoRotate, gridStyle, landmarkTicks, tickAnchor, extent }]`. `tickAnchor: "edges"` flips first tick's `text-anchor` to `start`, last to `end` (and `dominant-baseline` on vertical axes) so edge labels don't overflow. Pairs with `axisExtent: "exact"`. Per-axis `extent: "nice"|"exact"|"rounded"` overrides chart-level `axisExtent` (common: exact x / nice y). Exact on a **value (y)** axis also skips y `extentPadding`; exact on x only affects tick placement. Rounded applies to value axes only and follows push updates and final legend layout. `includeMin` / `includeMax` add a missing endpoint and replace a nearby label; they are ignored for band axes, exact ticks, and explicit values. Naturally rounded ends need neither flag; pinned ends can still use them. `resolveAxisTickCount({ axis?, size, orientation: "vertical" | "horizontal", axisExtent? })` from `semiotic/utils` returns the shared XY/rounded-ordinal tick-count hint: default 5, capped at one per 30px vertically / 70px horizontally (minimum size allowance 2), before scalePadding. `ticks` wins over its `tickCount` alias; exact mode is not size-capped. Existing ordinal nice/exact modes request 5. Resolved margins are available in server render evidence and React frame graphics callbacks.
671
680
  - **Adaptive time ticks**: `xFormat={adaptiveTimeTicks()}` or `adaptiveTimeTicks("minutes")`. Default formats in **UTC** for deterministic SSR. Timezone: `{ timeZone: "local" }` for the viewer, `{ timeZone: "America/Los_Angeles" }` (any IANA id) for a pinned region, or legacy `{ utc: false }` for local. `timeZone` wins over `utc` when both are set. Opt-in axis-label options: `includeYear` / `includeDate` (`"always"` default, `"auto"` drops the year inside `referenceTime`'s year / the date when every tick shares one day, `"never"` drops them at boundaries too), `referenceTime` (default `Date.now()`; pin it when server and client both render), and `deltaStyle: "clock"` (`"12:10"`, `"Oct 7"`). Value-only calls (tooltips) keep the full label. Horizontal axes pass index-aware formatters the ticks actually rendered after thinning.
672
681
  - **Per-axis CSS**: every axis renders as `<g class="semiotic-axis semiotic-axis-{bottom|left|right|top}" data-orient="…">`. Style via `[data-orient="left"] text { font-size: 14px }` — CSS-var defaults are set inline via `var(--semiotic-tick-font-size, …)`, so cascade overrides win cleanly. Tick text: `class="semiotic-axis-tick"`; labels: `class="semiotic-axis-label"`; titles: `class="semiotic-chart-title"`.
673
682
  - **`scalePadding`**: pixel inset on scale ranges (via `frameProps={{ scalePadding: 12 }}`).
@@ -682,3 +691,5 @@ Chart live regions announce keyboard focus without announcing pointer hover acro
682
691
  Prefer string accessors (`xAccessor="value"`) — always referentially stable. Memoize function accessors with `useCallback`.
683
692
 
684
693
  Threshold annotations (`x-threshold` and `y-threshold`) accept `endCap: "circle"` or `{ radius?, fill? }` at the top (x) or left (y) plot edge in both browser and static SVG. GaugeChart defaults to a native SVG center readout; string, number, and SVG (including fragment) centerContent and `centerLabel` stay native SVG, while other HTML centerContent uses foreignObject for SVG exports. Compact modes (context/sparkline, including via responsiveRules) hide the readout and scale labels on both paths.
694
+
695
+ Realtime aggregation retains `windowSize` windows per series by default in push mode (200); bounded snapshots keep all windows unless `aggregate.retain` is set. Explicit `retain: Infinity` opts out in React. Push publishes coalesce per animation frame while `getData()` returns current aggregates. Percentile/distinct stats enable their sketches automatically; enabling a new sketch resets push history, so preconfigure sketches for live readout switches. `aggregate.idleAdvance` closes quiet windows; combine with `eventTime.idleAdvance` to release buffered tails. `eventTime.maxFutureSkew` rejects timestamps too far ahead of `Date.now()`. Both idle policies default off. `WaterfallChart` and `RealtimeWaterfallChart` accept `initialValue` (default 0) and preserve evicted cumulative deltas until clear or bounded replacement. Frame staleness includes paused/hidden wall time, while animations remain on logical time. `useStreamStatus` observes overridden handles and publishes timestamps at poll cadence.