semiotic 3.8.9 → 3.9.1

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 (502) hide show
  1. package/README.md +55 -81
  2. package/agent-skill/semiotic-charts/SKILL.md +11 -2
  3. package/ai/behaviorContracts.cjs +33 -3
  4. package/ai/cli.js +53 -2
  5. package/ai/componentMetadata.cjs +15 -0
  6. package/ai/dist/mcp-server.js +1530 -611
  7. package/ai/examples.md +48 -42
  8. package/{CLAUDE.md → ai/reference.md} +43 -22
  9. package/ai/schema.json +10603 -986
  10. package/ai/surface-manifest.json +643 -2
  11. package/ai/system-prompt.md +83 -130
  12. package/dist/c-3BLJEQNG.min.js +1 -0
  13. package/dist/c-3KZD6AXJ.min.js +1 -0
  14. package/dist/c-4TWEX5HG.min.js +1 -0
  15. package/dist/c-52TEGIUJ.min.js +1 -0
  16. package/dist/c-5YCIX3VZ.min.js +1 -0
  17. package/dist/c-6FEKTA3U.min.js +1 -0
  18. package/dist/c-6O5EVOPH.min.js +1 -0
  19. package/dist/c-74HEEZGK.min.js +1 -0
  20. package/dist/c-AKAF6JAD.min.js +1 -0
  21. package/dist/c-BBKITSXB.min.js +1 -0
  22. package/dist/c-BWNB6USU.min.js +1 -0
  23. package/dist/c-C25ENHIK.min.js +1 -0
  24. package/dist/c-CDR5AO3R.min.js +1 -0
  25. package/dist/c-COHXCW3Q.min.js +1 -0
  26. package/dist/{chunk-scatterplotMatrixBrushOverlay-SDIZSN66.module.min.js → c-DADXPJXV.min.js} +0 -1
  27. package/dist/c-E3JFRRMI.min.js +1 -0
  28. package/dist/c-EBFPQHHO.min.js +1 -0
  29. package/dist/c-G36WS6LN.min.js +1 -0
  30. package/dist/c-GIKRQI4X.min.js +1 -0
  31. package/dist/c-GPYOFETM.min.js +1 -0
  32. package/dist/c-IDUHYYSI.min.js +1 -0
  33. package/dist/{chunk-chunk-FQPKOAIH.module.min.js → c-IUHFPMHD.min.js} +0 -1
  34. package/dist/c-J5G56TUH.min.js +1 -0
  35. package/dist/c-JAZ73J32.min.js +1 -0
  36. package/dist/c-KG3NXHAL.min.js +1 -0
  37. package/dist/c-KII3PLZE.min.js +1 -0
  38. package/dist/c-LIXGXMNS.min.js +1 -0
  39. package/dist/c-LVEY6D6B.min.js +1 -0
  40. package/dist/c-M4Y3BHFR.min.js +1 -0
  41. package/dist/c-MAIICR2Z.min.js +1 -0
  42. package/dist/c-MG5DM6VE.min.js +1 -0
  43. package/dist/{chunk-minimapBrushOverlay-JU57U7NM.module.min.js → c-MNF2S4AA.min.js} +0 -1
  44. package/dist/c-MT3WBK7M.min.js +1 -0
  45. package/dist/c-NY3JWV2K.min.js +1 -0
  46. package/dist/c-O6U6K4CW.min.js +1 -0
  47. package/dist/c-OCI56QF2.min.js +1 -0
  48. package/dist/c-OQ7M4AGV.min.js +1 -0
  49. package/dist/c-OXYMVK7Q.min.js +1 -0
  50. package/dist/c-PPWDL5ZI.min.js +1 -0
  51. package/dist/c-QHF5YON3.min.js +1 -0
  52. package/dist/c-RR3GO5SW.min.js +1 -0
  53. package/dist/{chunk-chunk-J5QD4RAM.module.min.js → c-RSVIHIQ4.min.js} +0 -1
  54. package/dist/{chunk-chunk-EMO5NUGE.module.min.js → c-S2BXNNJN.min.js} +0 -1
  55. package/dist/{chunk-chunk-YCQYG6J5.module.min.js → c-SLGMUBUL.min.js} +0 -1
  56. package/dist/c-SUILCHWU.min.js +1 -0
  57. package/dist/c-TZW3JGJ5.min.js +1 -0
  58. package/dist/c-US5ZFT6E.min.js +1 -0
  59. package/dist/{chunk-chunk-RZH7VZYS.module.min.js → c-USFMFKIH.min.js} +0 -1
  60. package/dist/c-UUKVD4WB.min.js +1 -0
  61. package/dist/{chunk-chunk-SV4XAZ3Q.module.min.js → c-VGW3VG3I.min.js} +0 -1
  62. package/dist/c-W3CE4A4S.min.js +1 -0
  63. package/dist/{chunk-chunk-2NVFEB7P.module.min.js → c-WJCD5EUY.min.js} +0 -1
  64. package/dist/{chunk-chunk-2JGJ5GUG.module.min.js → c-X5UBGU2V.min.js} +0 -1
  65. package/dist/c-YDAY2WFR.min.js +1 -0
  66. package/dist/c-ZOWWU34K.min.js +1 -0
  67. package/dist/components/AccessibleNavTree.d.ts +1 -1
  68. package/dist/components/CategoryColors.d.ts +1 -1
  69. package/dist/components/GradientLegend.d.ts +14 -0
  70. package/dist/components/Legend.d.ts +2 -7
  71. package/dist/components/LinkedCharts.d.ts +1 -1
  72. package/dist/components/MobileAnnotationCalloutList.d.ts +1 -1
  73. package/dist/components/ObservationReadout.d.ts +45 -0
  74. package/dist/components/ThemeProvider.d.ts +4 -4
  75. package/dist/components/Tooltip/FlippingTooltip.d.ts +5 -7
  76. package/dist/components/Tooltip/Tooltip.d.ts +30 -5
  77. package/dist/components/Tooltip/tooltipChrome.d.ts +43 -0
  78. package/dist/components/ai/chartCapabilityTypes.d.ts +86 -2
  79. package/dist/components/ai/chartClinic.d.ts +2 -0
  80. package/dist/components/ai/deriveProfileFields.d.ts +40 -0
  81. package/dist/components/ai/evaluateChart.d.ts +85 -0
  82. package/dist/components/ai/fieldPolicy.d.ts +7 -0
  83. package/dist/components/ai/fieldRoles.d.ts +24 -0
  84. package/dist/components/ai/generativeChart.d.ts +18 -2
  85. package/dist/components/ai/inferIntent.d.ts +26 -2
  86. package/dist/components/ai/intents.d.ts +35 -0
  87. package/dist/components/ai/navigationTree.d.ts +2 -2
  88. package/dist/components/ai/observedSceneAudit.d.ts +2 -1
  89. package/dist/components/ai/profileData.d.ts +11 -0
  90. package/dist/components/ai/repairChartConfig.d.ts +2 -3
  91. package/dist/components/ai/semanticEvidence.d.ts +4 -0
  92. package/dist/components/ai/semanticViability.d.ts +11 -0
  93. package/dist/components/ai/semanticViabilityRegistry.d.ts +5 -0
  94. package/dist/components/ai/streamingTypes.d.ts +4 -0
  95. package/dist/components/ai/suggestCharts.d.ts +5 -6
  96. package/dist/components/ai/suggestDashboard.d.ts +2 -3
  97. package/dist/components/ai/suggestStreamCharts.d.ts +1 -1
  98. package/dist/components/ai/suggestStretchCharts.d.ts +2 -3
  99. package/dist/components/ai/suggestionPropContracts.d.ts +20 -0
  100. package/dist/components/ai/variantDiscovery.d.ts +3 -1
  101. package/dist/components/charts/custom/NetworkCustomChart.d.ts +3 -0
  102. package/dist/components/charts/custom/OrdinalCustomChart.d.ts +3 -0
  103. package/dist/components/charts/custom/XYCustomChart.d.ts +1 -1
  104. package/dist/components/charts/geo/ChoroplethMap.d.ts +3 -1
  105. package/dist/components/charts/geo/DistanceCartogram.d.ts +2 -7
  106. package/dist/components/charts/geo/cartogramOverlay.d.ts +28 -0
  107. package/dist/components/charts/index.d.ts +4 -3
  108. package/dist/components/charts/network/ProcessSankey.d.ts +2 -136
  109. package/dist/components/charts/network/ProcessSankeyProps.d.ts +139 -0
  110. package/dist/components/charts/network/Treemap.d.ts +2 -1
  111. package/dist/components/charts/network/processSankey/boundaryHubOrdering.d.ts +23 -0
  112. package/dist/components/charts/network/processSankey/layoutGeometry.d.ts +2 -0
  113. package/dist/components/charts/network/processSankey/ordering.d.ts +3 -41
  114. package/dist/components/charts/network/processSankey/orderingTypes.d.ts +32 -0
  115. package/dist/components/charts/network/processSankey/packing.d.ts +1 -1
  116. package/dist/components/charts/network/processSankey/packingCache.d.ts +1 -1
  117. package/dist/components/charts/network/processSankey/packingOptimization.d.ts +72 -0
  118. package/dist/components/charts/ordinal/BarChart.d.ts +4 -3
  119. package/dist/components/charts/ordinal/FunnelChart.d.ts +2 -0
  120. package/dist/components/charts/ordinal/GroupedBarChart.d.ts +3 -2
  121. package/dist/components/charts/ordinal/StackedBarChart.d.ts +4 -3
  122. package/dist/components/charts/ordinal/SwimlaneChart.d.ts +2 -2
  123. package/dist/components/charts/physics/GaltonBoardChart.d.ts +2 -9
  124. package/dist/components/charts/physics/GauntletChart.d.ts +10 -41
  125. package/dist/components/charts/physics/ProcessFlowChart.d.ts +1 -1
  126. package/dist/components/charts/physics/chainReactionAccessibleTable.d.ts +9 -0
  127. package/dist/components/charts/physics/chainReactionRuntime.d.ts +2 -1
  128. package/dist/components/charts/physics/chainReactionTypes.d.ts +5 -1
  129. package/dist/components/charts/physics/crucibleBodyRenderers.d.ts +2 -2
  130. package/dist/components/charts/physics/crucibleClone.d.ts +6 -0
  131. package/dist/components/charts/physics/crucibleEffects.d.ts +1 -2
  132. package/dist/components/charts/physics/crucibleRecord.d.ts +7 -0
  133. package/dist/components/charts/physics/gauntletChrome.d.ts +4 -4
  134. package/dist/components/charts/physics/gauntletPhysics.d.ts +1 -0
  135. package/dist/components/charts/physics/gauntletPublic.d.ts +4 -0
  136. package/dist/components/charts/physics/packetFlowOverlay.d.ts +7 -0
  137. package/dist/components/charts/physics/physicsChartLayout.d.ts +8 -0
  138. package/dist/components/charts/physics/physicsChartShared.d.ts +3 -1
  139. package/dist/components/charts/physics/physicsChartUtils.d.ts +1 -1
  140. package/dist/components/charts/physics/physicsHocUtils.d.ts +25 -12
  141. package/dist/components/charts/physics/physicsProjectionOverlays.d.ts +24 -0
  142. package/dist/components/charts/physics/processFlowOverlays.d.ts +9 -0
  143. package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +15 -12
  144. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +10 -7
  145. package/dist/components/charts/realtime/RealtimeLineChart.d.ts +35 -14
  146. package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +21 -14
  147. package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +20 -13
  148. package/dist/components/charts/realtime/aggregate.d.ts +4 -1
  149. package/dist/components/charts/realtime/eventTime.d.ts +4 -0
  150. package/dist/components/charts/realtime/realtimeChartRuntime.d.ts +27 -0
  151. package/dist/components/charts/realtime/realtimeChartTypes.d.ts +30 -0
  152. package/dist/components/charts/realtime/useRealtimeCategoryColors.d.ts +30 -0
  153. package/dist/components/charts/shared/FrameTextAnnotationSVG.d.ts +10 -0
  154. package/dist/components/charts/shared/annotationActivation.d.ts +3 -7
  155. package/dist/components/charts/shared/annotationBandFill.d.ts +6 -0
  156. package/dist/components/charts/shared/annotationDispatch.d.ts +31 -0
  157. package/dist/components/charts/shared/annotationIdentity.d.ts +8 -0
  158. package/dist/components/charts/shared/annotationRules.d.ts +1 -15
  159. package/dist/components/charts/shared/boundedCategoryRegistry.d.ts +8 -0
  160. package/dist/components/charts/shared/chainReactionChartSpec.d.ts +3 -0
  161. package/dist/components/charts/shared/chartMode.d.ts +3 -2
  162. package/dist/components/charts/shared/chartSpecCore.d.ts +1 -0
  163. package/dist/components/charts/shared/frameTextAnnotation.d.ts +63 -0
  164. package/dist/components/charts/shared/gradient.d.ts +16 -0
  165. package/dist/components/charts/shared/hatchFill.d.ts +15 -0
  166. package/dist/components/charts/shared/hooks.d.ts +4 -4
  167. package/dist/components/charts/shared/legendUtils.d.ts +1 -0
  168. package/dist/components/charts/shared/streamPropsHelpers.d.ts +2 -1
  169. package/dist/components/charts/shared/styleRules.d.ts +9 -2
  170. package/dist/components/charts/shared/styleRulesWireSchema.d.ts +353 -0
  171. package/dist/components/charts/shared/types.d.ts +18 -9
  172. package/dist/components/charts/shared/useChartLegend.d.ts +43 -9
  173. package/dist/components/charts/shared/useChartSetup.d.ts +3 -1
  174. package/dist/components/charts/shared/useCustomChartSetup.d.ts +5 -2
  175. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +5 -1
  176. package/dist/components/charts/shared/useOrdinalBrush.d.ts +3 -3
  177. package/dist/components/charts/shared/useStreamingLegend.d.ts +6 -1
  178. package/dist/components/charts/value/types.d.ts +1 -1
  179. package/dist/components/charts/xy/BubbleChart.d.ts +1 -1
  180. package/dist/components/charts/xy/BumpChart.capability.d.ts +14 -1
  181. package/dist/components/charts/xy/BumpChart.d.ts +13 -73
  182. package/dist/components/charts/xy/BumpChart.semanticViability.d.ts +5 -0
  183. package/dist/components/charts/xy/CandlestickChart.d.ts +2 -2
  184. package/dist/components/charts/xy/LineChart.d.ts +2 -2
  185. package/dist/components/charts/xy/Scatterplot.d.ts +1 -1
  186. package/dist/components/charts/xy/bumpData.d.ts +44 -0
  187. package/dist/components/charts/xy/bumpIdentity.d.ts +2 -0
  188. package/dist/components/charts/xy/bumpLayout.d.ts +45 -0
  189. package/dist/components/charts/xy/bumpTooltip.d.ts +20 -0
  190. package/dist/components/legendLayout.d.ts +131 -4
  191. package/dist/components/realtime/ReorderBuffer.d.ts +2 -0
  192. package/dist/components/realtime/types.d.ts +10 -1
  193. package/dist/components/recipes/balanceSnapshotsToFlows.d.ts +42 -0
  194. package/dist/components/recipes/directedReachability.d.ts +14 -0
  195. package/dist/components/recipes/gofishDisplayListFixtures.generated.d.ts +6 -6
  196. package/dist/components/recipes/gridObservatory.d.ts +1 -1
  197. package/dist/components/recipes/networkAnalysis.d.ts +1 -18
  198. package/dist/components/recipes/physics.d.ts +7 -4
  199. package/dist/components/recipes/processPhysics.d.ts +0 -1
  200. package/dist/components/recipes/waffle.d.ts +7 -4
  201. package/dist/components/semiotic-ai-core.d.ts +13 -4
  202. package/dist/components/semiotic-ai-observations.d.ts +3 -0
  203. package/dist/components/semiotic-ai.d.ts +16 -9
  204. package/dist/components/semiotic-client-shared.d.ts +10 -0
  205. package/dist/components/semiotic-experimental.d.ts +1 -1
  206. package/dist/components/semiotic-geo.d.ts +4 -1
  207. package/dist/components/semiotic-network.d.ts +7 -4
  208. package/dist/components/semiotic-ordinal.d.ts +4 -1
  209. package/dist/components/semiotic-physics.d.ts +11 -4
  210. package/dist/components/semiotic-realtime-core.d.ts +11 -4
  211. package/dist/components/semiotic-realtime-react.d.ts +4 -3
  212. package/dist/components/semiotic-realtime.d.ts +3 -1
  213. package/dist/components/semiotic-recipes-core.d.ts +7 -5
  214. package/dist/components/semiotic-server-edge.d.ts +3 -2
  215. package/dist/components/semiotic-server.d.ts +3 -2
  216. package/dist/components/semiotic-themes-core.d.ts +5 -48
  217. package/dist/components/semiotic-utils-core.d.ts +10 -5
  218. package/dist/components/semiotic-utils-react.d.ts +2 -0
  219. package/dist/components/semiotic-utils.d.ts +1 -1
  220. package/dist/components/semiotic-xy.d.ts +4 -1
  221. package/dist/components/semiotic.d.ts +68 -26
  222. package/dist/components/server/animatedGif.d.ts +1 -1
  223. package/dist/components/server/renderEvidence.d.ts +25 -2
  224. package/dist/components/server/renderToStaticSVG.d.ts +15 -7
  225. package/dist/components/server/serverChartConfigShared.d.ts +8 -1
  226. package/dist/components/server/serverChartConfigs.d.ts +1 -0
  227. package/dist/components/server/serverChartConfigsNetwork.d.ts +3 -3
  228. package/dist/components/server/serverChartConfigsNetworkChord.d.ts +2 -0
  229. package/dist/components/server/serverChartConfigsNetworkForce.d.ts +2 -0
  230. package/dist/components/server/serverChartConfigsNetworkHierarchy.d.ts +3 -0
  231. package/dist/components/server/serverChartConfigsXY.d.ts +3 -3
  232. package/dist/components/server/serverChartConfigsXYBubble.d.ts +5 -0
  233. package/dist/components/server/serverChartConfigsXYBump.d.ts +7 -0
  234. package/dist/components/server/serverChartConfigsXYScatter.d.ts +5 -0
  235. package/dist/components/server/staticAnnotationFallbacks.d.ts +10 -0
  236. package/dist/components/server/staticAnnotations.d.ts +28 -1
  237. package/dist/components/server/staticAxisTickLabel.d.ts +13 -0
  238. package/dist/components/server/staticLegend.d.ts +1 -1
  239. package/dist/components/server/staticLegendMargin.d.ts +41 -0
  240. package/dist/components/server/staticOrdinal.d.ts +8 -2
  241. package/dist/components/server/staticPhysics.d.ts +13 -1
  242. package/dist/components/server/staticPhysicsChrome.d.ts +20 -0
  243. package/dist/components/server/staticRawLegend.d.ts +15 -0
  244. package/dist/components/server/staticSVGChrome.d.ts +16 -55
  245. package/dist/components/server/staticXYAxes.d.ts +27 -0
  246. package/dist/components/server/staticXYAxisTicks.d.ts +39 -0
  247. package/dist/components/server/staticXYGrid.d.ts +11 -0
  248. package/dist/components/server/themeResolver.d.ts +5 -1
  249. package/dist/components/store/ThemeStore.d.ts +2 -98
  250. package/dist/components/store/designTokens.d.ts +1 -1
  251. package/dist/components/store/themeCSSVariables.d.ts +10 -0
  252. package/dist/components/store/themeCore.d.ts +91 -0
  253. package/dist/components/store/themePresets.d.ts +81 -0
  254. package/dist/components/store/themeSerialization.d.ts +2 -1
  255. package/dist/components/stream/AccessibleDataTable.d.ts +12 -14
  256. package/dist/components/stream/AccessibleTablePortalImpl.d.ts +6 -0
  257. package/dist/components/stream/GeoTileRenderer.d.ts +2 -0
  258. package/dist/components/stream/NetworkCanvasHitTester.d.ts +3 -1
  259. package/dist/components/stream/NetworkSSRFrame.d.ts +2 -1
  260. package/dist/components/stream/NetworkSVGOverlay.d.ts +3 -31
  261. package/dist/components/stream/OrdinalCanvasHitTester.d.ts +2 -0
  262. package/dist/components/stream/SVGChartTitle.d.ts +9 -0
  263. package/dist/components/stream/SVGOverlay.d.ts +1 -21
  264. package/dist/components/stream/SVGUnderlay.d.ts +24 -0
  265. package/dist/components/stream/SceneToSVG.d.ts +1 -1
  266. package/dist/components/stream/StreamGeoFrame.d.ts +1 -1
  267. package/dist/components/stream/StreamOrdinalFrame.d.ts +1 -1
  268. package/dist/components/stream/StreamXYFrame.d.ts +1 -1
  269. package/dist/components/stream/accessibleDataRows.d.ts +11 -0
  270. package/dist/components/stream/accessibleDataTableModel.d.ts +40 -0
  271. package/dist/components/stream/accessibleTableTypes.d.ts +11 -0
  272. package/dist/components/stream/axisTickUtils.d.ts +19 -0
  273. package/dist/components/stream/canvasBackground.d.ts +10 -0
  274. package/dist/components/stream/canvasSetup.d.ts +9 -0
  275. package/dist/components/stream/frameCursorInteraction.d.ts +25 -0
  276. package/dist/components/stream/frameDefaultMargins.d.ts +37 -0
  277. package/dist/components/stream/frameGraphics.d.ts +18 -0
  278. package/dist/components/stream/frameGraphicsSubscription.d.ts +26 -0
  279. package/dist/components/stream/frameLegendOptions.d.ts +18 -0
  280. package/dist/components/stream/geoFrameCursorInteraction.d.ts +9 -0
  281. package/dist/components/stream/geoFrameHelpers.d.ts +29 -1
  282. package/dist/components/stream/geoTypes.d.ts +10 -11
  283. package/dist/components/stream/hitTarget.d.ts +61 -2
  284. package/dist/components/stream/moduleWorkerSession.d.ts +6 -0
  285. package/dist/components/stream/networkAnnotationAnchors.d.ts +37 -0
  286. package/dist/components/stream/networkCustomLayout.d.ts +2 -2
  287. package/dist/components/stream/networkFrameCursorInteraction.d.ts +12 -0
  288. package/dist/components/stream/networkFrameInteraction.d.ts +2 -0
  289. package/dist/components/stream/networkFramePaint.d.ts +7 -0
  290. package/dist/components/stream/networkPipelineConfig.d.ts +1 -1
  291. package/dist/components/stream/networkTypes.d.ts +30 -32
  292. package/dist/components/stream/normalizeXYData.d.ts +7 -0
  293. package/dist/components/stream/ordinalFrameCursorInteraction.d.ts +7 -0
  294. package/dist/components/stream/ordinalFrameInteraction.d.ts +29 -0
  295. package/dist/components/stream/ordinalSceneSVG.d.ts +10 -0
  296. package/dist/components/stream/ordinalTypes.d.ts +10 -4
  297. package/dist/components/stream/physics/PhysicsBodySpatialIndex.d.ts +9 -1
  298. package/dist/components/stream/physics/PhysicsCanvasTheme.d.ts +25 -0
  299. package/dist/components/stream/physics/PhysicsControllers.d.ts +0 -3
  300. package/dist/components/stream/physics/PhysicsPipelineStore.d.ts +4 -1
  301. package/dist/components/stream/physics/PhysicsSVGOverlay.d.ts +3 -24
  302. package/dist/components/stream/physics/PhysicsSettledSVG.d.ts +9 -21
  303. package/dist/components/stream/physics/PhysicsSettledSVGElement.d.ts +37 -0
  304. package/dist/components/stream/physics/PhysicsSettledScene.d.ts +7 -3
  305. package/dist/components/stream/physics/StreamPhysicsFrame.d.ts +1 -1
  306. package/dist/components/stream/physics/StreamPhysicsTypes.d.ts +23 -4
  307. package/dist/components/stream/physics/physicsAnnotationContext.d.ts +19 -0
  308. package/dist/components/stream/physics/physicsBodyCanvas.d.ts +4 -0
  309. package/dist/components/stream/physics/physicsSettledChrome.d.ts +7 -0
  310. package/dist/components/stream/physics/usePhysicsCanvasPointer.d.ts +32 -0
  311. package/dist/components/stream/physics/usePhysicsSemanticNavigation.d.ts +36 -0
  312. package/dist/components/stream/pipelineConfig.d.ts +6 -17
  313. package/dist/components/stream/pipelineDomainResolution.d.ts +1 -1
  314. package/dist/components/stream/renderBackend.d.ts +2 -0
  315. package/dist/components/stream/renderers/canvasRenderHelpers.d.ts +13 -2
  316. package/dist/components/stream/renderers/resolveCSSColor.d.ts +7 -0
  317. package/dist/components/stream/responsiveSize.d.ts +17 -0
  318. package/dist/components/stream/sceneCursor.d.ts +41 -0
  319. package/dist/components/stream/sceneRevisionDiagnostics.d.ts +1 -1
  320. package/dist/components/stream/svgOverlayUtils.d.ts +22 -1
  321. package/dist/components/stream/types.d.ts +25 -12
  322. package/dist/components/stream/useCanvasFrameHost.d.ts +3 -1
  323. package/dist/components/stream/useFrame.d.ts +24 -1
  324. package/dist/components/stream/useResponsiveSize.d.ts +6 -1
  325. package/dist/components/stream/useStalenessCheck.d.ts +1 -1
  326. package/dist/components/stream/xyFrameAxisTypes.d.ts +15 -4
  327. package/dist/components/stream/xyFrameCursorInteraction.d.ts +6 -0
  328. package/dist/components/stream/xySceneBuilders/swarmScene.d.ts +1 -1
  329. package/dist/components/stream/xySceneBuilders/types.d.ts +6 -26
  330. package/dist/components/types/legendTypes.d.ts +6 -0
  331. package/dist/components/types/marginType.d.ts +7 -8
  332. package/dist/controls.min.js +1 -1
  333. package/dist/controls.module.min.js +1 -1
  334. package/dist/forceLayoutWorker.js +1 -1
  335. package/dist/geo.min.js +1 -1
  336. package/dist/geo.module.min.js +1 -1
  337. package/dist/network.min.js +1 -1
  338. package/dist/network.module.min.js +1 -1
  339. package/dist/ordinal.min.js +1 -1
  340. package/dist/ordinal.module.min.js +1 -1
  341. package/dist/physics-matter.module.min.js +1 -1
  342. package/dist/physics-rapier.module.min.js +1 -1
  343. package/dist/physics.min.js +1 -1
  344. package/dist/physics.module.min.js +1 -1
  345. package/dist/physicsWorker.js +1 -1
  346. package/dist/processSankeyLayoutWorker.js +1 -1
  347. package/dist/realtime.min.js +1 -1
  348. package/dist/realtime.module.min.js +1 -1
  349. package/dist/rough.min.js +1 -1
  350. package/dist/rough.module.min.js +1 -1
  351. package/dist/semiotic-ai-core.d.ts +13 -4
  352. package/dist/semiotic-ai-core.min.js +1 -1
  353. package/dist/semiotic-ai-core.module.min.js +1 -1
  354. package/dist/semiotic-ai.d.ts +16 -9
  355. package/dist/semiotic-ai.min.js +1 -1
  356. package/dist/semiotic-ai.module.min.js +1 -1
  357. package/dist/semiotic-client-cjs-shared.min.js +1 -0
  358. package/dist/semiotic-client-glyph.module.min.js +2 -0
  359. package/dist/semiotic-client-responsive.module.min.js +2 -0
  360. package/dist/semiotic-client-shared.module.min.js +2 -0
  361. package/dist/semiotic-custom-layout-selection-cjs-shared.min.js +2 -0
  362. package/dist/semiotic-data.min.js +1 -1
  363. package/dist/semiotic-data.module.min.js +1 -1
  364. package/dist/semiotic-experimental-auxiliary.module.min.js +2 -0
  365. package/dist/semiotic-experimental-node-auxiliary.module.min.js +2 -0
  366. package/dist/semiotic-experimental-node.module.min.js +2 -0
  367. package/dist/semiotic-experimental-react-shared.module.min.js +2 -0
  368. package/dist/semiotic-experimental-vacp.min.js +1 -1
  369. package/dist/semiotic-experimental-vacp.module.min.js +1 -1
  370. package/dist/semiotic-experimental.d.ts +1 -1
  371. package/dist/semiotic-experimental.min.js +1 -1
  372. package/dist/semiotic-experimental.module.min.js +1 -1
  373. package/dist/semiotic-geo.d.ts +4 -1
  374. package/dist/semiotic-network.d.ts +7 -4
  375. package/dist/semiotic-ordinal.d.ts +4 -1
  376. package/dist/semiotic-physics.d.ts +11 -4
  377. package/dist/semiotic-realtime-core.d.ts +11 -4
  378. package/dist/semiotic-realtime-core.min.js +2 -1
  379. package/dist/semiotic-realtime-core.module.min.js +2 -1
  380. package/dist/semiotic-realtime-react.d.ts +4 -3
  381. package/dist/semiotic-realtime-react.min.js +1 -1
  382. package/dist/semiotic-realtime-react.module.min.js +1 -1
  383. package/dist/semiotic-realtime.d.ts +3 -1
  384. package/dist/semiotic-recipes-core-cjs-base.min.js +1 -0
  385. package/dist/semiotic-recipes-core.d.ts +7 -5
  386. package/dist/semiotic-recipes-core.min.js +9 -1
  387. package/dist/semiotic-recipes-core.module.min.js +1 -1
  388. package/dist/semiotic-recipes-geo-cjs.min.js +1 -0
  389. package/dist/semiotic-recipes-react.min.js +1 -1
  390. package/dist/semiotic-recipes-react.module.min.js +1 -1
  391. package/dist/semiotic-recipes.min.js +7 -1
  392. package/dist/semiotic-recipes.module.min.js +2 -1
  393. package/dist/semiotic-server-edge-node.module.min.js +1 -0
  394. package/dist/semiotic-server-edge.d.ts +3 -2
  395. package/dist/semiotic-server-edge.min.js +1 -1
  396. package/dist/semiotic-server-edge.module.min.js +1 -1
  397. package/dist/semiotic-server-node.min.js +1 -1
  398. package/dist/semiotic-server-node.module.min.js +1 -1
  399. package/dist/semiotic-server.d.ts +3 -2
  400. package/dist/semiotic-themes-core.d.ts +5 -48
  401. package/dist/semiotic-themes-core.min.js +1 -1
  402. package/dist/semiotic-themes-core.module.min.js +1 -1
  403. package/dist/semiotic-themes-react.min.js +1 -1
  404. package/dist/semiotic-themes-react.module.min.js +1 -1
  405. package/dist/semiotic-themes.min.js +1 -1
  406. package/dist/semiotic-themes.module.min.js +1 -1
  407. package/dist/semiotic-utils-core.d.ts +10 -5
  408. package/dist/semiotic-utils-core.min.js +1 -1
  409. package/dist/semiotic-utils-core.module.min.js +1 -1
  410. package/dist/semiotic-utils-react.d.ts +2 -0
  411. package/dist/semiotic-utils-react.min.js +1 -1
  412. package/dist/semiotic-utils-react.module.min.js +1 -1
  413. package/dist/semiotic-utils.d.ts +1 -1
  414. package/dist/semiotic-utils.min.js +2 -1
  415. package/dist/semiotic-utils.module.min.js +2 -1
  416. package/dist/semiotic-value.min.js +1 -1
  417. package/dist/semiotic-value.module.min.js +1 -1
  418. package/dist/semiotic-xy.d.ts +4 -1
  419. package/dist/semiotic.d.ts +68 -26
  420. package/dist/semiotic.min.js +1 -1
  421. package/dist/semiotic.module.min.js +1 -1
  422. package/dist/server.min.js +1 -1
  423. package/dist/server.module.min.js +1 -1
  424. package/dist/xy.min.js +1 -1
  425. package/dist/xy.module.min.js +1 -1
  426. package/package.json +53 -19
  427. package/dist/__tests__/scenarios/mcpProtocolTypes.d.ts +0 -20
  428. package/dist/chunk-OrdinalBrushOverlay-PXHQYDB2.module.min.js +0 -2
  429. package/dist/chunk-XYBrushOverlay-ECZJJLAJ.module.min.js +0 -1
  430. package/dist/chunk-XYBrushOverlay-EP2SV3UI.module.min.js +0 -2
  431. package/dist/chunk-chartContainerDataAudit-IQ3NBN3Q.module.min.js +0 -2
  432. package/dist/chunk-chunk-2B3AIKUZ.module.min.js +0 -2
  433. package/dist/chunk-chunk-2CXCXRB4.module.min.js +0 -1
  434. package/dist/chunk-chunk-2X3FJCME.module.min.js +0 -1
  435. package/dist/chunk-chunk-2ZHHWZQM.module.min.js +0 -2
  436. package/dist/chunk-chunk-4ITOQRXM.module.min.js +0 -2
  437. package/dist/chunk-chunk-5UKL5W76.module.min.js +0 -2
  438. package/dist/chunk-chunk-5VVNW5AZ.module.min.js +0 -1
  439. package/dist/chunk-chunk-5ZON5NMV.module.min.js +0 -2
  440. package/dist/chunk-chunk-66PCWJUG.module.min.js +0 -1
  441. package/dist/chunk-chunk-6S3YGYW7.module.min.js +0 -1
  442. package/dist/chunk-chunk-6V5VQVCT.module.min.js +0 -2
  443. package/dist/chunk-chunk-7C5EDZ3Z.module.min.js +0 -2
  444. package/dist/chunk-chunk-A3I4HBD5.module.min.js +0 -1
  445. package/dist/chunk-chunk-ACLDBMRH.module.min.js +0 -2
  446. package/dist/chunk-chunk-AFQHURLO.module.min.js +0 -2
  447. package/dist/chunk-chunk-DDB4TLQG.module.min.js +0 -2
  448. package/dist/chunk-chunk-DTH3SUOU.module.min.js +0 -2
  449. package/dist/chunk-chunk-DTSNLGRK.module.min.js +0 -2
  450. package/dist/chunk-chunk-DVCWU7MT.module.min.js +0 -2
  451. package/dist/chunk-chunk-FEPXDKJP.module.min.js +0 -1
  452. package/dist/chunk-chunk-FJ76HWQZ.module.min.js +0 -1
  453. package/dist/chunk-chunk-FSIHAW6L.module.min.js +0 -2
  454. package/dist/chunk-chunk-G2RGVEYY.module.min.js +0 -2
  455. package/dist/chunk-chunk-G75OPF5N.module.min.js +0 -2
  456. package/dist/chunk-chunk-HADHLMY5.module.min.js +0 -1
  457. package/dist/chunk-chunk-HAJVODLO.module.min.js +0 -2
  458. package/dist/chunk-chunk-HBFA4NN6.module.min.js +0 -1
  459. package/dist/chunk-chunk-HIV7AW2V.module.min.js +0 -2
  460. package/dist/chunk-chunk-IY7RYD4S.module.min.js +0 -1
  461. package/dist/chunk-chunk-J3QOW4OE.module.min.js +0 -0
  462. package/dist/chunk-chunk-J3XWETBJ.module.min.js +0 -2
  463. package/dist/chunk-chunk-JZAMMSQQ.module.min.js +0 -2
  464. package/dist/chunk-chunk-KTWEBFMX.module.min.js +0 -2
  465. package/dist/chunk-chunk-LSJUXBMF.module.min.js +0 -1
  466. package/dist/chunk-chunk-MXMRXSCI.module.min.js +0 -2
  467. package/dist/chunk-chunk-MXVBXFKW.module.min.js +0 -2
  468. package/dist/chunk-chunk-NWIGA3UK.module.min.js +0 -1
  469. package/dist/chunk-chunk-OFAP623Y.module.min.js +0 -2
  470. package/dist/chunk-chunk-OHLRAEQZ.module.min.js +0 -2
  471. package/dist/chunk-chunk-OZK46A5U.module.min.js +0 -1
  472. package/dist/chunk-chunk-PMR47KRY.module.min.js +0 -2
  473. package/dist/chunk-chunk-PRNXOCYZ.module.min.js +0 -2
  474. package/dist/chunk-chunk-Q2YADC2V.module.min.js +0 -2
  475. package/dist/chunk-chunk-RLKZVJMQ.module.min.js +0 -2
  476. package/dist/chunk-chunk-ROP4HI7H.module.min.js +0 -2
  477. package/dist/chunk-chunk-SK2TQMG4.module.min.js +0 -2
  478. package/dist/chunk-chunk-SKLYXNYW.module.min.js +0 -2
  479. package/dist/chunk-chunk-TCMHJWFJ.module.min.js +0 -1
  480. package/dist/chunk-chunk-TSCFL235.module.min.js +0 -1
  481. package/dist/chunk-chunk-U4NZCU5T.module.min.js +0 -2
  482. package/dist/chunk-chunk-U66USBWU.module.min.js +0 -1
  483. package/dist/chunk-chunk-UOQRPGPK.module.min.js +0 -2
  484. package/dist/chunk-chunk-VKL6DI43.module.min.js +0 -2
  485. package/dist/chunk-chunk-W62673ZE.module.min.js +0 -1
  486. package/dist/chunk-chunk-WFHZHWT7.module.min.js +0 -1
  487. package/dist/chunk-chunk-XCC25CZZ.module.min.js +0 -2
  488. package/dist/chunk-chunk-XECNOUZY.module.min.js +0 -2
  489. package/dist/chunk-chunk-XYZDTYAF.module.min.js +0 -2
  490. package/dist/chunk-chunk-YHNZCPOZ.module.min.js +0 -2
  491. package/dist/chunk-chunk-YWZB3KPI.module.min.js +0 -2
  492. package/dist/chunk-statisticalOverlays-HMYYSGPE.module.min.js +0 -2
  493. package/dist/components/stream/test-utils/frameScheduler.d.ts +0 -12
  494. package/dist/components/stream/test-utils/revisionConsumption.d.ts +0 -13
  495. package/dist/test-utils/canvasMock.d.ts +0 -86
  496. package/dist/test-utils/capturedFrameProps.d.ts +0 -67
  497. package/dist/test-utils/frameMock.d.ts +0 -81
  498. package/dist/test-utils/ordinalFixtures.d.ts +0 -48
  499. /package/dist/{chunk-chunk-JJ2OOIET.module.min.js → c-GGISSW5E.min.js} +0 -0
  500. /package/dist/{chunk-chunk-SIRIJ3DY.module.min.js → c-N4G2L7ID.min.js} +0 -0
  501. /package/dist/{chunk-chunk-CA3YDW6F.module.min.js → c-S6U5CGT5.min.js} +0 -0
  502. /package/dist/components/recipes/{mobileAnnotationStrategy.d.ts → mobileAnnotationBehavior.d.ts} +0 -0
package/ai/examples.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # Semiotic Examples
2
2
 
3
- Copy-paste-ready examples for every data shape.
3
+ Copy-paste-ready examples for every data shape. This is an on-demand catalog:
4
+ search for the relevant component or task and load that section rather than the
5
+ whole file. Verify the current component schema before using an example because
6
+ the schema is authoritative when prose drifts.
4
7
 
5
8
  ---
6
9
 
@@ -9,7 +12,7 @@ Copy-paste-ready examples for every data shape.
9
12
  ### LineChart (single line)
10
13
 
11
14
  ```jsx
12
- import { LineChart } from "semiotic/ai"
15
+ import { LineChart } from "semiotic/xy"
13
16
 
14
17
  const data = [
15
18
  { month: "Jan", revenue: 4200 },
@@ -34,7 +37,7 @@ Key props: `xAccessor`, `yAccessor`, `curve`, `showPoints`, `fillArea`
34
37
  ### LineChart (multi-line)
35
38
 
36
39
  ```jsx
37
- import { LineChart } from "semiotic/ai"
40
+ import { LineChart } from "semiotic/xy"
38
41
 
39
42
  const data = [
40
43
  { quarter: 1, sales: 120, region: "East" },
@@ -64,7 +67,7 @@ instead of forcing the value through a single field name. This is especially
64
67
  useful for multi-line data with a different metric per series.
65
68
 
66
69
  ```jsx
67
- import { LineChart } from "semiotic/ai"
70
+ import { LineChart } from "semiotic/xy"
68
71
 
69
72
  const data = [
70
73
  { timestamp: 1, metricLabel: "valueA", valueA: 12, valueB: 60 },
@@ -88,7 +91,7 @@ for a direct lookup; use a function for a computed or dynamic value.
88
91
  ### Scatterplot
89
92
 
90
93
  ```jsx
91
- import { Scatterplot } from "semiotic/ai"
94
+ import { Scatterplot } from "semiotic/xy"
92
95
 
93
96
  const data = [
94
97
  { sepalLength: 5.1, petalLength: 1.4, species: "setosa" },
@@ -113,7 +116,7 @@ Key props: `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
113
116
  ### Heatmap
114
117
 
115
118
  ```jsx
116
- import { Heatmap } from "semiotic/ai"
119
+ import { Heatmap } from "semiotic/xy"
117
120
 
118
121
  const data = [
119
122
  { day: "Mon", hour: "9am", count: 12 },
@@ -142,7 +145,7 @@ Key props: `valueAccessor`, `colorScheme` ("blues"|"reds"|"greens"|"viridis"), `
142
145
  ### Heatmap with Gradient Legend
143
146
 
144
147
  ```jsx
145
- import { Heatmap } from "semiotic/ai"
148
+ import { Heatmap } from "semiotic/xy"
146
149
 
147
150
  <Heatmap
148
151
  data={data}
@@ -160,7 +163,7 @@ Key props: `showLegend` enables gradient legend, `legendPosition` ("right"|"left
160
163
  ### AreaChart
161
164
 
162
165
  ```jsx
163
- import { AreaChart } from "semiotic/ai"
166
+ import { AreaChart } from "semiotic/xy"
164
167
 
165
168
  const data = [
166
169
  { month: 1, revenue: 4200 },
@@ -193,7 +196,7 @@ Key props: `areaBy` (group into multiple areas), `y0Accessor` (band/ribbon), `gr
193
196
  **IMPORTANT**: `showLine` on AreaChart only draws the TOP edge of the area (the `yAccessor` line). To render a separate main line (e.g., p50 median), you must layer two charts.
194
197
 
195
198
  ```jsx
196
- import { AreaChart, LineChart } from "semiotic/ai"
199
+ import { AreaChart, LineChart } from "semiotic/xy"
197
200
 
198
201
  const data = [
199
202
  { x: 0, p5: 10, p50: 25, p95: 45 },
@@ -240,7 +243,7 @@ Key props: `y0Accessor` defines band bottom, `yAccessor` defines band top, `show
240
243
  ### DifferenceChart
241
244
 
242
245
  ```jsx
243
- import { DifferenceChart } from "semiotic/ai"
246
+ import { DifferenceChart } from "semiotic/xy"
244
247
 
245
248
  const tempData = [
246
249
  { month: 1, actual: 38, normal: 32 },
@@ -276,7 +279,7 @@ Key props: `seriesALabel` / `seriesBLabel` (legend + tooltip), `seriesAColor` /
276
279
  ### BumpChart
277
280
 
278
281
  ```jsx
279
- import { BumpChart } from "semiotic/ai"
282
+ import { BumpChart } from "semiotic/xy"
280
283
 
281
284
  const data = [
282
285
  { quarter: "Q1", team: "North", sales: 420 },
@@ -303,12 +306,12 @@ const data = [
303
306
  />
304
307
  ```
305
308
 
306
- Ranks every series within each x-column and connects each series' rank across columns — the classic "who's leading over time" chart. `yAccessor` is the magnitude used to rank (highest value = rank 1 by default; use `rankDirection="ascending"` when lower is better). `highlightTop` colors only the N best series by mean rank and greys the rest via `neutralColor`. Set `ribbon={true}` to encode the raw magnitude as true perpendicular-offset ribbon width instead of fixed-width lines — line and ribbon share the same centerline geometry, so `animate` tweens only the width. Endpoint labels show by default (`showLabels`).
309
+ Ranks every series within each x-column and connects each series' rank across columns — the classic "who's leading over time" chart. `yAccessor` is the magnitude used to rank (highest value = rank 1 by default; use `rankDirection="ascending"` when lower is better). `highlightTop` colors only the N best series by mean rank and greys the rest via `neutralColor`. Set `ribbon={true}` to encode the raw magnitude as true perpendicular-offset ribbon width instead of fixed-width lines — line and ribbon share the same centerline geometry, so `animate` tweens only the width. Endpoint labels show by default (`showLabels`); use `showLabels="auto"` with `labelPriorityAccessor` and `maxLabels` for dense endpoints.
307
310
 
308
311
  ### StackedAreaChart
309
312
 
310
313
  ```jsx
311
- import { StackedAreaChart } from "semiotic/ai"
314
+ import { StackedAreaChart } from "semiotic/xy"
312
315
 
313
316
  // IMPORTANT: Use a flat array with an areaBy field for grouping.
314
317
  // Do NOT use lineBy or lineDataAccessor — those are LineChart props.
@@ -339,7 +342,7 @@ Key props: **`areaBy`** (required — groups flat data into stacked areas), `col
339
342
  ### ConnectedScatterplot
340
343
 
341
344
  ```jsx
342
- import { ConnectedScatterplot } from "semiotic/ai"
345
+ import { ConnectedScatterplot } from "semiotic/xy"
343
346
 
344
347
  const data = [
345
348
  { year: 2018, unemployment: 3.9, inflation: 2.4 },
@@ -365,7 +368,7 @@ Key props: `orderAccessor` sequences points along the path, Viridis gradient fro
365
368
  ### TemporalHistogram
366
369
 
367
370
  ```jsx
368
- import { TemporalHistogram } from "semiotic/ai"
371
+ import { TemporalHistogram } from "semiotic/realtime"
369
372
 
370
373
  // One row per event; the chart bins events into `binSize` time buckets.
371
374
  const events = [
@@ -396,7 +399,7 @@ Static-data sibling of `RealtimeHistogram` — accepts a bounded `data` array in
396
399
  ### BarChart
397
400
 
398
401
  ```jsx
399
- import { BarChart } from "semiotic/ai"
402
+ import { BarChart } from "semiotic/ordinal"
400
403
 
401
404
  const data = [
402
405
  { region: "North", total: 4200 },
@@ -421,7 +424,7 @@ Key props: `categoryAccessor`, `valueAccessor`, `orientation`, `sort`
421
424
  ### StackedBarChart
422
425
 
423
426
  ```jsx
424
- import { StackedBarChart } from "semiotic/ai"
427
+ import { StackedBarChart } from "semiotic/ordinal"
425
428
 
426
429
  const data = [
427
430
  { question: "Q1", response: "Agree", count: 45 },
@@ -449,7 +452,7 @@ Key props: **`stackBy`** (required), `normalize` for 100% stacked bars
449
452
  ### GroupedBarChart
450
453
 
451
454
  ```jsx
452
- import { GroupedBarChart } from "semiotic/ai"
455
+ import { GroupedBarChart } from "semiotic/ordinal"
453
456
 
454
457
  const data = [
455
458
  { year: "2022", product: "Widget", revenue: 120 },
@@ -474,7 +477,7 @@ Key props: **`groupBy`** (required), side-by-side bars within each category
474
477
  ### Histogram
475
478
 
476
479
  ```jsx
477
- import { Histogram } from "semiotic/ai"
480
+ import { Histogram } from "semiotic/ordinal"
478
481
 
479
482
  const data = [
480
483
  { category: "Group A", value: 12 },
@@ -504,7 +507,7 @@ Key props: `bins` (default 25), `relative` (normalize per-category)
504
507
  ### ViolinPlot
505
508
 
506
509
  ```jsx
507
- import { ViolinPlot } from "semiotic/ai"
510
+ import { ViolinPlot } from "semiotic/ordinal"
508
511
 
509
512
  const data = [
510
513
  { department: "Engineering", salary: 95000 },
@@ -537,7 +540,7 @@ Key props: `bins`, `curve` (default "catmullRom"), `showIQR` (default true)
537
540
  ### TreeDiagram
538
541
 
539
542
  ```jsx
540
- import { TreeDiagram } from "semiotic/ai"
543
+ import { TreeDiagram } from "semiotic/network"
541
544
 
542
545
  const orgChart = {
543
546
  name: "CEO",
@@ -573,7 +576,7 @@ Key props: `data` is a single root object, `childrenAccessor`, `layout`, `orient
573
576
  ### Treemap
574
577
 
575
578
  ```jsx
576
- import { Treemap } from "semiotic/ai"
579
+ import { Treemap } from "semiotic/network"
577
580
 
578
581
  const diskUsage = {
579
582
  name: "root",
@@ -611,7 +614,7 @@ Key props: `valueAccessor` controls rectangle size, `colorByDepth`
611
614
  ### CirclePack
612
615
 
613
616
  ```jsx
614
- import { CirclePack } from "semiotic/ai"
617
+ import { CirclePack } from "semiotic/network"
615
618
 
616
619
  const taxonomy = {
617
620
  name: "Life",
@@ -650,7 +653,7 @@ Key props: `valueAccessor` controls circle size, nested circles for hierarchy
650
653
  ### OrbitDiagram
651
654
 
652
655
  ```jsx
653
- import { OrbitDiagram } from "semiotic/ai"
656
+ import { OrbitDiagram } from "semiotic/network"
654
657
 
655
658
  const pipeline = {
656
659
  name: "ML Pipeline",
@@ -701,7 +704,7 @@ Key props: `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`,
701
704
  ### ForceDirectedGraph
702
705
 
703
706
  ```jsx
704
- import { ForceDirectedGraph } from "semiotic/ai"
707
+ import { ForceDirectedGraph } from "semiotic/network"
705
708
 
706
709
  const nodes = [
707
710
  { id: "Alice", team: "Engineering", influence: 10 },
@@ -741,7 +744,7 @@ Key props: **`nodes`** and **`edges`** (both required), `nodeIDAccessor` (defaul
741
744
 
742
745
  ```jsx
743
746
  import { useState } from "react"
744
- import { ForceDirectedGraph } from "semiotic/ai"
747
+ import { ForceDirectedGraph } from "semiotic/network"
745
748
 
746
749
  const [selected, setSelected] = useState(null)
747
750
 
@@ -773,7 +776,7 @@ Key props: `frameProps` passes through to the underlying `StreamNetworkFrame` fo
773
776
  ### SankeyDiagram
774
777
 
775
778
  ```jsx
776
- import { SankeyDiagram } from "semiotic/ai"
779
+ import { SankeyDiagram } from "semiotic/network"
777
780
 
778
781
  const edges = [
779
782
  { source: "Salary", target: "Budget", value: 5000 },
@@ -797,7 +800,7 @@ Key props: **`edges`** (required, nodes inferred), `valueAccessor` controls band
797
800
  ### ProcessSankey
798
801
 
799
802
  ```jsx
800
- import { ProcessSankey } from "semiotic/ai"
803
+ import { ProcessSankey } from "semiotic/network"
801
804
 
802
805
  const nodes = [
803
806
  { id: "Alice", category: "Person", xExtent: ["2026-01-06", "2026-01-06"] },
@@ -829,7 +832,7 @@ Key props: **`edges`** with `startTime`/`endTime`, **`domain`** (required `[t0,
829
832
  ### ChordDiagram
830
833
 
831
834
  ```jsx
832
- import { ChordDiagram } from "semiotic/ai"
835
+ import { ChordDiagram } from "semiotic/network"
833
836
 
834
837
  const edges = [
835
838
  { source: "US", target: "EU", value: 500 },
@@ -885,7 +888,7 @@ the initial or newly arrived rows from an effect. Formatter callbacks such as
885
888
 
886
889
  ```jsx
887
890
  import { useRef, useEffect } from "react"
888
- import { RealtimeLineChart } from "semiotic/ai"
891
+ import { RealtimeLineChart } from "semiotic/realtime"
889
892
 
890
893
  const chartRef = useRef()
891
894
 
@@ -907,13 +910,13 @@ useEffect(() => {
907
910
  />
908
911
  ```
909
912
 
910
- Key props: `timeAccessor`, `valueAccessor`, `windowSize`, `stroke`, `strokeWidth`
913
+ Key props: `timeAccessor`, `valueAccessor`, `windowSize`, `stroke`, `strokeWidth`. For bounded out-of-order input, set `eventTime={{ lateness: "2s" }}`, type the ref as `RealtimeLineChartHandle`, and call `chartRef.current?.flush()` when the source ends to release the grace-window tail in order.
911
914
 
912
915
  ### RealtimeHistogram
913
916
 
914
917
  ```jsx
915
918
  import { useRef, useEffect } from "react"
916
- import { RealtimeHistogram } from "semiotic/ai"
919
+ import { RealtimeHistogram } from "semiotic/realtime"
917
920
 
918
921
  const chartRef = useRef()
919
922
 
@@ -943,7 +946,7 @@ Key props: **`binSize`** (required), `timeAccessor` ("time"), `valueAccessor` ("
943
946
 
944
947
  ```jsx
945
948
  import { useRef, useEffect } from "react"
946
- import { RealtimeHeatmap } from "semiotic/ai"
949
+ import { RealtimeHeatmap } from "semiotic/realtime"
947
950
 
948
951
  const chartRef = useRef()
949
952
 
@@ -976,7 +979,7 @@ Use `StreamNetworkFrame` only when you need low-level control that HOC charts do
976
979
 
977
980
  ```jsx
978
981
  import { useRef, useEffect } from "react"
979
- import { StreamNetworkFrame } from "semiotic"
982
+ import { StreamNetworkFrame } from "semiotic/network"
980
983
 
981
984
  const chartRef = useRef()
982
985
 
@@ -1079,8 +1082,8 @@ Key: `renderToStaticSVG(frameType, props)` where frameType is `"xy"` | `"ordinal
1079
1082
 
1080
1083
  ```jsx
1081
1084
  import { useRef } from "react"
1082
- import { Scatterplot } from "semiotic/ai"
1083
- import { exportChart } from "semiotic"
1085
+ import { Scatterplot } from "semiotic/xy"
1086
+ import { exportChart } from "semiotic/utils"
1084
1087
 
1085
1088
  const containerRef = useRef<HTMLDivElement>(null)
1086
1089
 
@@ -1129,7 +1132,8 @@ Key: `exportChart(wrapperDiv, { format, filename, scale, background })`. It quer
1129
1132
  ### ThemeProvider (React context)
1130
1133
 
1131
1134
  ```jsx
1132
- import { ThemeProvider, DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semiotic"
1135
+ import { ThemeProvider } from "semiotic/themes/react"
1136
+ import { DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semiotic/themes"
1133
1137
 
1134
1138
  // Preset dark theme
1135
1139
  <ThemeProvider theme="dark">
@@ -1195,12 +1199,13 @@ import { ThemeProvider, DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semioti
1195
1199
  ### onClick on BarChart
1196
1200
 
1197
1201
  ```jsx
1198
- import { BarChart } from "semiotic/ai"
1202
+ import { BarChart } from "semiotic/ordinal"
1199
1203
 
1200
1204
  <BarChart
1201
1205
  data={salesData}
1202
1206
  categoryAccessor="region"
1203
1207
  valueAccessor="revenue"
1208
+ styleRules={[{ when: true, style: { cursor: "pointer" } }]}
1204
1209
  onClick={(datum, { x, y }) => {
1205
1210
  console.log(`Clicked ${datum.region}: $${datum.revenue}`)
1206
1211
  setSelectedRegion(datum.region)
@@ -1208,7 +1213,7 @@ import { BarChart } from "semiotic/ai"
1208
1213
  />
1209
1214
  ```
1210
1215
 
1211
- Key props: `onClick` receives the original datum and pixel coordinates. Works on all chart types.
1216
+ Key props: `onClick` receives the original datum and pixel coordinates. Works on all chart types. `cursor` only changes pointer presentation; the explicit interaction API supplies behavior, and an actionable chart still needs an accessible activation path.
1212
1217
 
1213
1218
  ---
1214
1219
 
@@ -1217,7 +1222,8 @@ Key props: `onClick` receives the original datum and pixel coordinates. Works on
1217
1222
  ### Synced crosshair across time-series charts
1218
1223
 
1219
1224
  ```jsx
1220
- import { LineChart, LinkedCharts } from "semiotic/ai"
1225
+ import { LineChart } from "semiotic/xy"
1226
+ import { LinkedCharts } from "semiotic/ai"
1221
1227
 
1222
1228
  <LinkedCharts>
1223
1229
  <LineChart
@@ -1244,7 +1250,7 @@ Key props: `linkedHover` with `mode: "x-position"` broadcasts the hovered X valu
1244
1250
  ### Truncated category labels
1245
1251
 
1246
1252
  ```jsx
1247
- import { BarChart } from "semiotic/ai"
1253
+ import { BarChart } from "semiotic/ordinal"
1248
1254
 
1249
1255
  <BarChart
1250
1256
  data={data}
@@ -1264,7 +1270,7 @@ Key props: `categoryFormat` receives each tick label and returns a formatted str
1264
1270
  ### Threshold + category highlight on BarChart
1265
1271
 
1266
1272
  ```jsx
1267
- import { BarChart } from "semiotic/ai"
1273
+ import { BarChart } from "semiotic/ordinal"
1268
1274
 
1269
1275
  <BarChart
1270
1276
  data={quarterlyData}
@@ -1,40 +1,47 @@
1
- # Semiotic — AI Assistant Guide
1
+ # Semiotic — Complete AI Reference
2
+
3
+ This is an on-demand encyclopedia, not a system prompt. Start with
4
+ `ai/system-prompt.md` and the exact component schema, search this file for the
5
+ relevant chart or behavior, and load only that section. Validate generated
6
+ configurations with `prepareChart`, `npx semiotic-ai --doctor`, or the MCP
7
+ diagnostic tools; when possible, confirm a non-empty render with evidence.
2
8
 
3
9
  ## Quick Start
4
10
  - Install: `npm install semiotic`
5
11
  <!-- semiotic-bundle-sizes:start -->
6
12
  <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
7
- - **Use sub-path imports** — `semiotic/xy` (146KB gz), `semiotic/ordinal` (122KB gz), `semiotic/network` (146KB gz), `semiotic/geo` (104KB gz), `semiotic/realtime` (155KB gz), `semiotic/realtime/core` (146KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (226KB gz), `semiotic/server/node` (226KB gz), `semiotic/server/edge` (241KB gz), `semiotic/utils` (86KB gz), `semiotic/utils/core` (84KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (90KB gz), `semiotic/recipes/core` (89KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (8KB gz), `semiotic/physics` (161KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (507KB gz), `semiotic/ai/core` (81KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (4KB gz). Full `semiotic` is 410KB gz.
13
+ - **Use sub-path imports** — `semiotic/xy` (154KB gz), `semiotic/ordinal` (129KB gz), `semiotic/network` (150KB gz), `semiotic/geo` (110KB gz), `semiotic/realtime` (165KB gz), `semiotic/realtime/core` (164KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (197KB gz), `semiotic/server/node` (197KB gz), `semiotic/server/edge` (202KB gz), `semiotic/utils` (93KB gz), `semiotic/utils/core` (86KB gz), `semiotic/utils/react` (7KB gz), `semiotic/recipes` (94KB gz), `semiotic/recipes/core` (86KB gz), `semiotic/recipes/react` (7KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (165KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (522KB gz), `semiotic/ai/core` (88KB gz), `semiotic/controls` (11KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 335KB gz.
8
14
  <!-- semiotic-bundle-sizes:end -->
9
- - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
15
+ - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y|--evaluate]` · MCP: `npx semiotic-mcp`
10
16
 
11
17
  ## Architecture
12
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`.
13
19
 
14
20
  ## Common Props (chart HOCs only)
15
- `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), `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; 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" — 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; canvases repaint on browser zoom / display-density changes).
16
22
 
17
23
  This list is not global. Plain value components do not inherit chart-HOC props and must be
18
24
  validated against their own schema. In particular, `BigNumber` uses `label`, `description`, and
19
25
  `summary`; it does not accept `title` or `accessibleTable`.
20
26
 
21
- **Primitive styling** (`color`/`stroke`/`strokeWidth`/`opacity`): apply to any shape the chart draws. Precedence: top-level prop > `frameProps.*Style` fn return > HOC base > theme. Use CSS vars (`stroke="var(--semiotic-border)"`) for cascade-overridable theming. Per-datum: use `frameProps.pieceStyle`/`pointStyle`/`lineStyle` fn form.
27
+ **Primitive styling** (`color`/`stroke`/`strokeWidth`/`opacity`): apply to any shape the chart draws. Precedence: top-level prop > `frameProps.*Style` fn return > HOC base > theme. Use CSS vars (`stroke="var(--semiotic-border)"`) for cascade-overridable theming. Per-datum: use `frameProps.pieceStyle`/`pointStyle`/`lineStyle`/`nodeStyle`/`edgeStyle` fn form. These retained mark styles also accept `cursor` (for example `nodeStyle={() => ({ cursor: "pointer" })}`), with canvas/SVG/static parity. Cursor is presentation only; pair it with the chart/frame click or observation API so pointer and keyboard behavior remain explicit.
22
28
 
23
29
  `onClick` receives `(datum, { x, y })`. `onObservation` receives `{ type, datum?, x?, y?, timestamp, chartType, chartId }`.
30
+ `ObservationReadout` renders an inline live-region description from those events. Pass `chartId` inside `LinkedCharts` to subscribe to the observation store, or pass the latest event through `observation`; its render function receives the unwrapped user datum. `observedDatum(event)` exposes the same normalization without rendering UI.
24
31
 
25
32
  ## XY Charts (`semiotic/xy`)
26
33
 
27
- **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
34
+ **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` ("linear"|"log"|"time"), `yScaleType` ("linear"|"log"|"symlog"), `styleRules` (per-series), `tooltip="multi"` for hover-anywhere
28
35
  **AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `semanticGradient` (`{stops: [{offset: 0–1, color?, opacity?}]}`; offset follows the resolved y-domain), `semanticLine` (true with semanticGradient; false keeps the normal stroke/lineGradient), `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
29
36
  **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`.
30
- **BumpChart** — Ranking-over-x. Each x-column ranks series by `yAccessor`; rank is vertical position. `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy` ("series"), `rankDirection` ("descending"|"ascending"), `ribbon` (false — encode magnitude as true perpendicular-offset ribbon width instead of fixed-width lines; line↔ribbon share centerline geometry so `animate` tweens width only), `curve` ("smooth"|"linear"), `ribbonSizeRange` ([4,28]), `samplesPerSegment` (12), `lineWidth` (3), `highlightTop` (color only the N best series by mean rank; the rest share `neutralColor`), `neutralColor`, `styleRules` (per-series; resolve against each series' first observation), `showPoints`, `showLabels` (true|"start"|"end"|"both"), `hoverHighlight`, `annotations` (x may use original x values incl. `Date`). Wraps XYCustomChart.
37
+ **BumpChart** — Ranking-over-x. Each x-column ranks series by `yAccessor`; rank is vertical position. `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy` ("series"), `rankDirection` ("descending"|"ascending"), `ribbon` (false — encode magnitude as true perpendicular-offset ribbon width instead of fixed-width lines; line↔ribbon share centerline geometry so `animate` tweens width only), `curve` ("smooth"|"linear"), `ribbonSizeRange` ([4,28]), `samplesPerSegment` (12), `lineWidth` (3), `highlightTop` (color only the N best series by mean rank; the rest share `neutralColor`), `neutralColor`, `styleRules` (per-series; resolve against each series' first observation), `showPoints`, `showLabels` (true|"start"|"end"|"both"|"auto"; endpoint collisions are shed deterministically), `labelPriorityAccessor` / `maxLabels` (prioritize and cap labels under `showLabels="auto"`), `hoverHighlight`, `annotations` (x may use original x values incl. `Date`). Wraps XYCustomChart.
31
38
  **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.
32
39
  **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)
33
40
  **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
34
41
  **ConnectedScatterplot** — + `orderAccessor`, `regression`
35
42
  **QuadrantChart** — Scatterplot + `quadrants`, `xCenter`, `yCenter`
36
43
  **MultiAxisLineChart** — Dual Y-axis. `series` (`[{yAccessor, label?, color?, format?, extent?}]`). Falls back to multi-line if ≠ 2 series.
37
- **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
44
+ **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `customColorScale`, `showValues`, `cellBorderColor`
38
45
  **ScatterplotMatrix** — `fields` (numeric field names)
39
46
  **MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart.
40
47
  **CandlestickChart** — `xAccessor`, `highAccessor` (req), `lowAccessor` (req), `openAccessor`+`closeAccessor` (optional → OHLC; high/low only → range). `candlestickStyle` ({upColor, downColor, wickColor, rangeColor, bodyWidth, wickWidth}). Honors `mode`.
@@ -59,7 +66,7 @@ validated against their own schema. In particular, `BigNumber` uses `label`, `de
59
66
 
60
67
  All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
61
68
 
62
- **`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/UnitPileChart/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`.
69
+ **`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/UnitPileChart/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 may include `cursor` plus the normal fill/stroke/opacity fields; `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`.
63
70
 
64
71
  ## Network Charts (`semiotic/network`)
65
72
 
@@ -128,7 +135,13 @@ Helpers exported: `buildFormatter`, `formatSignedDelta`, `formatDeltaPercent`, `
128
135
 
129
136
  Push API: `ref.current.push({time, value})`. All pushed data must include a time field.
130
137
 
131
- **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**, **Streaming Sankey** (StreamNetworkFrame + `showParticles`).
138
+ **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`).
139
+
140
+ All five realtime wrappers accept a top-level `cursor` as a presentation-only default for retained marks; `RealtimeSwarmChart.pointStyle` can override it per datum. Pair actionable cursors with explicit click or observation behavior.
141
+
142
+ `RealtimeLineChart` supports `eventTime={{ lateness, latePolicy? }}` for bounded out-of-order input. Type its ref as `RealtimeLineChartHandle` and call `ref.current.flush()` when the source ends so events still inside the grace window are released in event-time order. A flush commits an ordering boundary: later newer events buffer normally, while events older than the flushed frontier follow `latePolicy`. Changing the event-time config or `timeAccessor` live drains the old tail before the new interpretation begins.
143
+
144
+ With `aggregate`, changing only `stat`/`band`/`sigma` reuses accumulated windows. Changing `window`/`size`/`hop`/`gap`/`retain`, `timeAccessor`, or `valueAccessor` starts a structurally new accumulator: controlled `data` is replayed under the new definition, while push-only history resets because aggregation intentionally retains window statistics rather than every raw event.
132
145
 
133
146
  Encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely.
134
147
 
@@ -168,7 +181,7 @@ Layout signature differs by family:
168
181
  - **`htmlMarks`** (network only): `NetworkHtmlMark[]` = `{ id, x, y, width, height, content: ReactNode }`, positioned in the **same plot space as `sceneNodes`** and rendered into one real-DOM layer the framework places **above the canvas and SVG `overlays`** (stack: canvas → `overlays` → `htmlMarks`). Reach for it over an SVG `<foreignObject>` when a mark is **text-heavy/rich and dims or animates on hover** — a real `<div>` composites `opacity`/`transform`/`visibility` changes instead of re-rasterizing text (the `foreignObject` stall on large graphs). Framework owns the margin (and future zoom/pan) transform so marks stay pixel-aligned; each mark is its own element, keyed by `id` (position-only re-runs reposition without remounting). `pointer-events: none` by default — keep a transparent hit-rect `sceneNode` per mark so canvas hit-testing/`onObservation` stays authoritative. Mark `content` can read `useCustomLayoutSelection()` to dim on shared selection without a relayout. Additive: omit it and no extra DOM renders. Class hooks: `.semiotic-network-html-marks` (layer) / `.semiotic-network-html-mark` (each).
169
182
 
170
183
  **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:
171
- - **`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}`. 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.
184
+ - **`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.
172
185
  - **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).
173
186
  - **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).
174
187
  - **2D vector kit**: `addPoints`/`subtractPoints`/`scalePoint`/`pointMagnitude`/`normalizePoint` — the point math any hand-built radial or network layout re-derives (an edge offset normal to its tangent, a spoke, a leader line). Operates on the shared `Point`, composes with the radial + edge kits.
@@ -219,7 +232,7 @@ HOC charts render SVG automatically in server environments. For standalone gener
219
232
  import { renderChart, renderChartWithEvidence, renderToImage, renderToAnimatedGif, renderDashboard } from "semiotic/server"
220
233
 
221
234
  const svg = renderChart("BarChart", { data, categoryAccessor, valueAccessor, theme: "tufte", showLegend, showGrid, annotations })
222
- const { svg: svg2, evidence } = renderChartWithEvidence("BarChart", { data, categoryAccessor, valueAccessor }) // evidence: { markCount, markCountByType, empty, xDomain?, yDomain?, categories?, nodeCount?, edgeCount?, annotationCount, ariaLabel, warnings } — ground truth from the rendered scene; check `evidence.empty`/`markCount` instead of parsing SVG. MCP renderChart returns the same block.
235
+ const { svg: svg2, evidence } = renderChartWithEvidence("BarChart", { data, categoryAccessor, valueAccessor }) // evidence: { markCount, markCountByType, empty, semanticStatus, semanticDiagnostics, xDomain?, yDomain?, categories?, nodeCount?, edgeCount?, annotationCount, ariaLabel, warnings } — ground truth from the rendered scene; check paint status (`empty`/`markCount`) separately from capability-owned semantic viability (`meaningful` | `degraded` | `degenerate` | `not-assessed`). MCP renderChart returns the same block.
223
236
  const png = await renderToImage("LineChart", { ... }, { format: "png", scale: 2 }) // requires sharp
224
237
  const gif = await renderToAnimatedGif("line", data, { xAccessor, yAccessor, theme: "dark" }, { fps: 12, transitionFrames: 4, decay: { type: "linear" } }) // requires sharp + gifenc
225
238
  const dashboard = renderDashboard([{ component: "BarChart", props }, { component: "PieChart", colSpan: 2, props }], { title, theme, layout: { columns: 2 } })
@@ -239,6 +252,8 @@ All HOCs accept `annotations`. Coordinates use data field names.
239
252
 
240
253
  **Positioning**: `widget`, `label`, `callout`, `callout-circle`, `callout-rect`, `text`, `bracket`
241
254
  **Reference lines**: `y-threshold` (`value`, `label`, `color`, `labelPosition`), `x-threshold`, `band` (`y0`, `y1` — a `null`/omitted bound extends to the axis min/max on that side, e.g. `y1: null` shades "at least `y0`"), `x-band` (`x0`, `x1`, `fill`, `fillOpacity` — full-height vertical region for eras/phases; a `null`/omitted bound likewise extends to the domain edge; only skipped when the axis has no scale at all)
255
+
256
+ **Serializable chart-adjacent text**: `frame-text` anchors text to the resolved plot rectangle rather than a data scale, so it renders identically in live charts and `renderChart` SVG. Use `position` (`"top-left"|"top-center"|"top-right"|"middle-left"|"center"|"middle-right"|"bottom-left"|"bottom-center"|"bottom-right"`) plus pixel `dx`/`dy`; `label` and `text` are aliases. Example endpoint labels below a compact bar: `annotations={[{ type: "frame-text", text: "0", position: "bottom-left", dy: 16 }, { type: "frame-text", text: "100", position: "bottom-right", dy: 16 }]}`. Reserve enough margin for outward offsets. Prefer this over post-processing SVG strings or estimating the data-area transform.
242
257
  **Ordinal**: `category-highlight`
243
258
  **Enclosures**: `enclose`, `rect-enclose`, `highlight`
244
259
  **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.
@@ -255,7 +270,7 @@ All HOCs accept `annotations`. Coordinates use data field names.
255
270
 
256
271
  ## Theming
257
272
 
258
- CSS custom properties: `--semiotic-{bg, text, text-secondary, border, grid, primary, secondary, surface, success, danger, warning, error, info, focus, font-family, annotation-color, legend-font-size, title-font-size, tick-font-family, tick-font-size (12px), axis-label-font-size (12px), tooltip-{bg, text, radius, font-size, shadow}}`.
273
+ CSS custom properties: `--semiotic-{bg, text, text-secondary, border, grid, primary, secondary, surface, success, danger, warning, error, info, focus, font-family, annotation-color, legend-font-size, legend-font-family, legend-font-weight, title-font-size, title-font-family, title-font-weight, tick-font-family, tick-font-size (12px), axis-label-font-size (12px), tooltip-{bg, text, radius, font-size, shadow}}`.
259
274
 
260
275
  ```jsx
261
276
  <ThemeProvider theme="tufte"> {/* named preset */}
@@ -264,7 +279,7 @@ CSS custom properties: `--semiotic-{bg, text, text-secondary, border, grid, prim
264
279
 
265
280
  **Color priority** (with `colorBy`): CategoryColorProvider/LinkedCharts map > `colorScheme` > ThemeProvider `colors.categorical` > `"category10"`. `colorScheme` accepts a named scheme (`"tableau10"`), an array, or a `{category: color}` **object map** for exact per-category colors (no array ordering to keep in sync).
266
281
  Presets: `light`, `dark`, `high-contrast`, `pastels`(-dark), `bi-tool`(-dark), `italian`(-dark), `tufte`(-dark), `journalist`(-dark), `playful`(-dark), `carbon`(-dark).
267
- Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveThemePreset(name)`.
282
+ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `designTokensToTheme(tokens)`, `resolveThemePreset(name)`. Native `semiotic.*` tokens round-trip title/legend size, family, and weight along with the base typography and color roles.
268
283
 
269
284
  **Semantic status roles** (every preset): `colors.success/danger/warning/error/info` + `secondary`/`surface`. Each emits as `--semiotic-{role}`. Use for status-driven charts: `<Waterfall positiveColor="var(--semiotic-success)" negativeColor="var(--semiotic-danger)" />`, `<Swimlane color="var(--semiotic-warning)" />`, status annotations.
270
285
 
@@ -276,7 +291,7 @@ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveTh
276
291
 
277
292
  ## AI Features
278
293
 
279
- Surface APIs: `onObservation`/`useChartObserver`, `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX`, `validateProps`, `diagnoseConfig` (includes `tokenEncoding` warnings when present), `suggestTokenEncoding`/`diagnoseTokenEncoding`, `auditAccessibility`/`accessibilityCaveats` + `describeChart` + `buildNavigationTree`/`AccessibleNavTree`/`useNavigationSync` + `buildReaderGrounding` (a11y audit + descriptions + structured navigation + bidirectional sync + agent-reader grounding — see Accessibility), `exportChart(div, { format })`, `npx semiotic-ai --doctor`/`--audit-a11y`.
294
+ Surface APIs: `onObservation`/`useChartObserver`, `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX`, `validateProps`, `diagnoseConfig` (includes `tokenEncoding` warnings when present), `evaluateChart`/`formatEvaluateChart` (one ranked data → deception → accessibility evaluation), `suggestTokenEncoding`/`diagnoseTokenEncoding`, `auditAccessibility`/`accessibilityCaveats` + `describeChart` + `buildNavigationTree`/`AccessibleNavTree`/`useNavigationSync` + `buildReaderGrounding` (a11y audit + descriptions + structured navigation + bidirectional sync + agent-reader grounding — see Accessibility), `exportChart(div, { format })`, `npx semiotic-ai --doctor`/`--audit-a11y`/`--evaluate`.
280
295
 
281
296
  ### Conversational Interrogation (`semiotic/ai`)
282
297
  Headless "chat with the chart" hook. Library ships no UI — BYO chat surface.
@@ -289,13 +304,15 @@ Headless "chat with the chart" hook. Library ships no UI — BYO chat surface.
289
304
 
290
305
  ### Chart Capability Layer (`semiotic/ai`)
291
306
  Heuristic chart-suggestion engine — no LLM required. Charts ship capability descriptors next to TSX files; engine ranks against a profiled dataset by intent.
292
- - **`profileData(data, { rawInput?, seriesField? })`** → `ChartDataProfile`: per-role candidate fields (x/y/series/category/size/time), distinct counts, monotonicity, structure detection.
293
- - **`suggestCharts(data, { intent?, allow?, deny?, maxResults?, includeVariants?, minScore?, audience? })`** → ranked `Suggestion[]` with `{ component, family, importPath, variant?, score, intentScores, rubric, reasons, caveats, props }`. `props` is spreadable directly. **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.
294
- - **`scoreChart(component, data, { intent?, variantKey? })`** → evaluate a specific chart for a dataset.
307
+ - **`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`.
308
+ - **`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.
309
+ - **`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.
310
+ - **`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.
311
+ - **`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.
295
312
  - **`useChartSuggestions(data, options)`** → memoized React hook returning `{ suggestions, profile }`.
296
313
  - **`registerChartCapability(capability)`** / **`unregisterChartCapability(name)`** — runtime registration for custom charts.
297
- - **Intent taxonomy** (13 built-in): `trend`, `compare-series`, `compare-categories`, `rank`, `part-to-whole`, `distribution`, `correlation`, `flow`, `hierarchy`, `geo`, `outlier-detection`, `composition-over-time`, `change-detection`. Extend via `registerIntent`.
298
- - **Capability authoring**: `Foo.capability.ts` next to `Foo.tsx`, append to registry in `src/components/ai/chartCapabilities.ts`. Declares `family`, `rubric` (familiarity/accuracy/precision 1-5), `fits(profile)` gate, `intentScores`, optional `variants` with `intentDeltas`, `buildProps(profile, variant)`.
314
+ - **Intent taxonomy** (13 built-in): `trend`, `compare-series`, `compare-categories`, `rank`, `part-to-whole`, `distribution`, `correlation`, `flow`, `hierarchy`, `geo`, `outlier-detection`, `composition-over-time`, `change-detection`. Extend via `registerIntent`. A registered descriptor may declare `composes` plus optional `weights`; requested custom scores are blended from existing capability scores without changing no-intent/default rankings. `inferIntent(query, { mode: "schema", fields?, minimumConfidence? })` opts into whole-token field signals and typed data-shape signals; natural-language prose remains the default mode.
315
+ - **Capability authoring**: `Foo.capability.ts` next to `Foo.tsx`, append to registry in `src/components/ai/chartCapabilities.ts`. Declares `family`, `rubric` (familiarity/accuracy/precision 1-5), `fits(profile)` gate, `intentScores`, optional `variants` with `intentDeltas`, `buildProps(profile, variant)`, and (for novel quantitative prop names or direct computed values) `fieldPolicy.measureAccessorProps` / `fieldPolicy.measureFields`. `semanticViability(props, evidence)` optionally reports stable warning/error diagnostics after paint; errors make render evidence `degenerate` even though `status` remains `ok`.
299
316
  - **Variants** encode that settings change what a chart is good for (e.g. StackedAreaChart's `streamgraph` variant boosts trend, penalizes part-to-whole).
300
317
  - **Interrogation tie-in**: pass `includeSuggestions: true` to `useChartInterrogation` and the ranked list lands in `context.suggestions` for the LLM.
301
318
  - **MCP tool**: `suggestCharts(data, intent?)`.
@@ -352,7 +369,9 @@ Interface for proposing/scoring variants beyond `capability.variants`. The built
352
369
  These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.
353
370
 
354
371
  - **Accessible chart text uses direct chart props** (`accessibility.description-props`): High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.
355
- Agent action: Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. For generated L1–L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.
372
+ Agent action: Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. If a consumer-owned role=img wraps the chart, use accessibleTable: { portalTarget: "element-id" } and render that target outside the image. For generated L1–L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.
373
+ - **Cursor styling does not create behavior** (`interaction.cursor-is-presentation-only`): Cursor values in realtime props, retained mark styles, styleRules, and custom hit targets change pointer presentation only. They do not install click handlers, keyboard activation, observations, or accessibility semantics.
374
+ Agent action: Use an actionable cursor only when the application separately supplies documented click or observation behavior and an accessible activation path. Treat cursor in serialized/static output as visual metadata, never as proof that a mark is interactive.
356
375
  - **Data required by usage mode** (`props.data-required-by-usage-mode`): Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.
357
376
  Agent action: Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.
358
377
  - **Categorical color precedence** (`color.category-precedence`): When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.
@@ -392,6 +411,8 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
392
411
 
393
412
  **Chartability audit**: `auditAccessibility(component, props, { inChartContainer?, describe?, navigable? })` (from `semiotic/ai` or `semiotic/utils`) grades a config against Chartability (POUR-CAF) — credits built-ins, flags author-actionable gaps, marks un-checkable items `manual` (not a false pass). `formatAccessibilityAudit(result)` renders the report. Surfaced as `npx semiotic-ai --audit-a11y` (non-zero exit on critical fail → CI gate) + the `auditAccessibility` MCP tool. Returns `{ ok, summary, findings[] }`; each finding has `{ id, principle, heuristic, critical, status: "pass"|"fail"|"warn"|"manual"|"not-applicable", message, fix }`. NOT a pass/fail cert — pair with manual NVDA/JAWS/VoiceOver testing.
394
413
 
414
+ **Unified chart evaluation**: `evaluateChart(component, props, data?, { dataAudit?, inChartContainer?, describe?, navigable?, render?, notificationMax? })` (from `semiotic/ai`, `semiotic/ai/core`, or `semiotic/utils`) composes `auditData` → configuration/representation diagnoses → `auditAccessibility` into `{ validation, data, deception, accessibility, evidence?, ok, summary, findings, notifications }`. `findings` are ranked by severity (`error`, `warning`, `manual`) and stage; `formatEvaluateChart(result)` produces a compact report. Inject a `RenderFn` when server render evidence is available to turn empty scenes and renderer warnings into findings. Surfaced as the `evaluateChart` MCP tool and `npx semiotic-ai --evaluate`; it is static analysis, so manual assistive-technology testing remains required.
415
+
395
416
  **Chart descriptions**: `describeChart(component, props, { levels?, locale?, capability?, audience? })` (from `semiotic/ai` or `semiotic/utils`) generates a layered natural-language description (Lundgard L1 encoding / L2 statistics / L3 trend) → `{ text, levels: {l1?,l2?,l3?,l4?}, annotations? }`. Richest for XY/bar/part-to-whole/distribution; degrades to L1 for network/hierarchy/geo/value. **Annotations**: when `props.annotations` is present, the result carries an `annotations` sentence ("The author has marked 2 features…") and it *leads* `text` ahead of L1–L3 — an author-placed note is intent in its purest form. Provenance-aware: an `authorKind`/`source` of `agent`/`ai`/`watcher` qualifies it ("an AI-suggested callout"). Absent when no annotations, so un-annotated callers are unchanged. **L4 (intent)**: pass a `capability` (a chart's descriptor or a resolved `{ family, intentScores }`) and `describeChart` emits the illocutionary *communicative-act* sentence ("This is an alerting chart; the peak at March is the point to investigate") — opt-in, default output stays L1–L3. Helpers: `resolveCommunicativeAct(component, capability)`, `communicativeActForIntent(intent)`, type `CommunicativeAct`. **Full-accessibility decoration (title, caption, description, navigation, data download) is the opt-in `ChartContainer` layer — not baked into the bare chart.** `<ChartContainer describe chartConfig={{component, props}}>` renders an sr-only L1–L3 description (`describe={{ visible:true }}` to show it, `{ levels }` for verbosity). The audit's `assistive.features-described` passes when `describe` is on.
396
417
 
397
418
  **Agent-reader grounding**: `buildReaderGrounding(component, props, { capability?, audience?, includeStructure? })` (from `semiotic/ai` or `semiotic/utils`) → `{ description (L1–L3), intent (act + L4 sentence), structure (nav tree), text }` — the single payload an LLM reads to interpret a chart faithfully (the reader-side complement to a capability descriptor). MCP: `groundChart` tool.
@@ -406,7 +427,7 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
406
427
  - **Tooltip datum shape**: HOC tooltips get raw data. Frame `tooltipContent` gets wrapped — use `d.data`.
407
428
  - **Tooltip format cascade**: `valueFormat`/`xFormat`/`yFormat` flow to default tooltip (axis + tooltip read identically). Custom `tooltip` fully overrides — re-pass via `Tooltip({format})` / `MultiLineTooltip({fields:[{format}]})`. Bespoke-tooltip charts (Histogram, FunnelChart, LikertChart, GaugeChart) don't participate; customize via `tooltip`.
408
429
  - **`tooltip="multi"`** / **`tooltip={{ mode: "multi", content? }}`**: multi-series hover-anywhere for LineChart, AreaChart, StackedAreaChart, DifferenceChart (wires `tooltipMode:"multi"`). 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). Legacy escape hatch: `tooltip={fn}` + `frameProps={{ tooltipMode: "multi" }}`.
409
- - **Legend**: "bottom" expands margin ~80px. 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.
430
+ - **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).
410
431
  - **Horizontal bars**: need wider left margin (`margin={{ left: 120 }}`).
411
432
  - **Log scale**: domain min clamped to 1e-6. **`xScaleType: "time"`**: creates `scaleTime`; required for landmark ticks with timestamps.
412
433
  - **`barPadding`**: pixel value (40/60 default). Reduce for small charts.