semiotic 3.9.0 → 3.9.2

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 (331) hide show
  1. package/README.md +102 -90
  2. package/agent-skill/semiotic-charts/SKILL.md +14 -10
  3. package/ai/componentMetadata.cjs +13 -3
  4. package/ai/dist/mcp-server.js +140 -36407
  5. package/ai/examples.md +109 -6
  6. package/ai/reference.md +55 -18
  7. package/ai/schema.json +5964 -1190
  8. package/ai/surface-manifest.json +51 -7
  9. package/ai/system-prompt.md +16 -3
  10. package/dist/c-3SCUN5HI.min.js +1 -0
  11. package/dist/c-3VVKFA4M.min.js +1 -0
  12. package/dist/c-43TJZS3F.min.js +1 -0
  13. package/dist/c-4DTZPSUD.min.js +1 -0
  14. package/dist/c-4ES5367Y.min.js +1 -0
  15. package/dist/c-54IRWOGM.min.js +1 -0
  16. package/dist/c-5D2S4RMI.min.js +1 -0
  17. package/dist/c-5JWCTX3G.min.js +1 -0
  18. package/dist/c-6CMMSN6N.min.js +1 -0
  19. package/dist/c-6HRB2L7H.min.js +1 -0
  20. package/dist/c-7W4SV36A.min.js +1 -0
  21. package/dist/c-A4WRGZFX.min.js +1 -0
  22. package/dist/c-AG7WWVIH.min.js +1 -0
  23. package/dist/c-AH6J4MTN.min.js +1 -0
  24. package/dist/c-ALYR5LKK.min.js +1 -0
  25. package/dist/c-BYDPC44I.min.js +1 -0
  26. package/dist/c-CFFIU2MW.min.js +1 -0
  27. package/dist/c-CGNHBHCE.min.js +1 -0
  28. package/dist/c-CJYSXIFV.min.js +1 -0
  29. package/dist/c-CKLIFCGN.min.js +1 -0
  30. package/dist/c-CZF7MV67.min.js +1 -0
  31. package/dist/c-D53OKBSY.min.js +1 -0
  32. package/dist/c-DBQ2V7CH.min.js +1 -0
  33. package/dist/c-DPMVAUAW.min.js +1 -0
  34. package/dist/c-ECJCKLYY.min.js +1 -0
  35. package/dist/c-EGATGOWJ.min.js +1 -0
  36. package/dist/c-EGR6VYBW.min.js +1 -0
  37. package/dist/c-ENF72HU5.min.js +1 -0
  38. package/dist/c-ESNR43AN.min.js +1 -0
  39. package/dist/c-F3LIKINL.min.js +1 -0
  40. package/dist/c-F5ZB5GJ6.min.js +1 -0
  41. package/dist/c-G3VYMHKE.min.js +1 -0
  42. package/dist/c-GR6MOEQC.min.js +1 -0
  43. package/dist/c-GSVCN34B.min.js +1 -0
  44. package/dist/c-GYOQCEFP.min.js +1 -0
  45. package/dist/c-H3DNMTCC.min.js +1 -0
  46. package/dist/c-I6J3FEZE.min.js +1 -0
  47. package/dist/c-IGH6MGJ5.min.js +1 -0
  48. package/dist/c-II2EEAJN.min.js +1 -0
  49. package/dist/c-J6M4JHRS.min.js +1 -0
  50. package/dist/c-JM3MGLQV.min.js +1 -0
  51. package/dist/c-KM3N7F7R.min.js +1 -0
  52. package/dist/c-LF5BZFNC.min.js +1 -0
  53. package/dist/c-LKBSGFQC.min.js +1 -0
  54. package/dist/c-NDJADPIF.min.js +1 -0
  55. package/dist/c-NVPQCIL5.min.js +1 -0
  56. package/dist/c-OFWJBEE5.min.js +1 -0
  57. package/dist/c-OYFHP5F5.min.js +1 -0
  58. package/dist/c-PGKQGGQ2.min.js +1 -0
  59. package/dist/c-Q2IPZ3MU.min.js +1 -0
  60. package/dist/c-QKHMBE2E.min.js +1 -0
  61. package/dist/c-QMVM3AY6.min.js +1 -0
  62. package/dist/c-QSGWX53A.min.js +1 -0
  63. package/dist/c-RJKEKZOO.min.js +1 -0
  64. package/dist/c-SFDIIU5G.min.js +1 -0
  65. package/dist/c-SRTBCRVE.min.js +1 -0
  66. package/dist/c-T6UAIKBH.min.js +1 -0
  67. package/dist/c-TMCTEVVW.min.js +1 -0
  68. package/dist/c-TMOSJLT3.min.js +1 -0
  69. package/dist/c-U6ESPM7V.min.js +1 -0
  70. package/dist/c-UC5PTTFI.min.js +1 -0
  71. package/dist/c-VGKUEZBC.min.js +1 -0
  72. package/dist/c-VN2HG5BS.min.js +1 -0
  73. package/dist/{c-J5G56TUH.min.js → c-VPZDY5Q4.min.js} +1 -1
  74. package/dist/c-VRXUB2F2.min.js +1 -0
  75. package/dist/c-VUBQNQJH.min.js +1 -0
  76. package/dist/c-VUH4PGZY.min.js +1 -0
  77. package/dist/c-XDRV7RKW.min.js +1 -0
  78. package/dist/c-YGZHURXZ.min.js +1 -0
  79. package/dist/components/Annotation.d.ts +1 -1
  80. package/dist/components/access/chartAccessCapabilities.generated.d.ts +14 -0
  81. package/dist/components/access/chartAccessContract.d.ts +90 -0
  82. package/dist/components/access/chartAccessContractFixtures.d.ts +11 -0
  83. package/dist/components/ai/aestheticProfileTypes.d.ts +35 -0
  84. package/dist/components/ai/annotationProvenance.d.ts +2 -7
  85. package/dist/components/ai/auditVisualHierarchy.d.ts +49 -0
  86. package/dist/components/ai/builtInChartRecipeLayouts.d.ts +2 -0
  87. package/dist/components/ai/builtInChartRecipePublic.d.ts +4 -0
  88. package/dist/components/ai/builtInChartRecipes.d.ts +26 -0
  89. package/dist/components/ai/chartCapabilities.d.ts +3 -1
  90. package/dist/components/ai/chartRecipeRegistry.d.ts +2 -1
  91. package/dist/components/ai/chartRecipes.d.ts +6 -0
  92. package/dist/components/ai/colorEvidence.d.ts +12 -0
  93. package/dist/components/ai/evaluateAesthetics.d.ts +47 -0
  94. package/dist/components/ai/geoNavigation.d.ts +4 -0
  95. package/dist/components/ai/hierarchyNavigation.d.ts +4 -0
  96. package/dist/components/ai/navigationTree.d.ts +7 -1
  97. package/dist/components/ai/qualityFixtures.d.ts +8 -0
  98. package/dist/components/ai/suggestionPropContracts.d.ts +1 -1
  99. package/dist/components/ai/useNavigationSync.d.ts +3 -3
  100. package/dist/components/charts/index.d.ts +4 -0
  101. package/dist/components/charts/network/ChordDiagram.d.ts +5 -1
  102. package/dist/components/charts/network/CirclePack.d.ts +8 -1
  103. package/dist/components/charts/network/OrbitDiagram.d.ts +9 -0
  104. package/dist/components/charts/network/TreeDiagram.d.ts +8 -1
  105. package/dist/components/charts/network/Treemap.d.ts +8 -1
  106. package/dist/components/charts/ordinal/BarChart.d.ts +6 -0
  107. package/dist/components/charts/ordinal/BoxPlot.d.ts +3 -0
  108. package/dist/components/charts/ordinal/DonutChart.d.ts +3 -0
  109. package/dist/components/charts/ordinal/DotPlot.d.ts +3 -0
  110. package/dist/components/charts/ordinal/FunnelChart.d.ts +3 -0
  111. package/dist/components/charts/ordinal/GaugeChart.d.ts +3 -0
  112. package/dist/components/charts/ordinal/Histogram.d.ts +3 -0
  113. package/dist/components/charts/ordinal/LikertChart.d.ts +3 -0
  114. package/dist/components/charts/ordinal/PieChart.d.ts +3 -0
  115. package/dist/components/charts/ordinal/RadarChart.capability.d.ts +2 -0
  116. package/dist/components/charts/ordinal/RadarChart.d.ts +75 -0
  117. package/dist/components/charts/ordinal/RidgelinePlot.d.ts +3 -0
  118. package/dist/components/charts/ordinal/SwarmPlot.d.ts +3 -0
  119. package/dist/components/charts/ordinal/SwimlaneChart.d.ts +3 -0
  120. package/dist/components/charts/ordinal/ViolinPlot.d.ts +3 -0
  121. package/dist/components/charts/physics/GauntletChart.d.ts +1 -5
  122. package/dist/components/charts/physics/chainReactionTypes.d.ts +3 -0
  123. package/dist/components/charts/physics/gauntletPhysics.d.ts +1 -0
  124. package/dist/components/charts/physics/physicsHocUtils.d.ts +7 -1
  125. package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +10 -1
  126. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +11 -1
  127. package/dist/components/charts/realtime/RealtimeLineChart.d.ts +14 -5
  128. package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +7 -1
  129. package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +7 -1
  130. package/dist/components/charts/realtime/aggregate.d.ts +12 -1
  131. package/dist/components/charts/realtime/realtimeChartRuntime.d.ts +4 -2
  132. package/dist/components/charts/realtime/realtimeStyleRules.d.ts +4 -0
  133. package/dist/components/charts/shared/annotationStatusFilter.d.ts +18 -0
  134. package/dist/components/charts/shared/chartDefinitionPilot.d.ts +5 -4
  135. package/dist/components/charts/shared/chartSpecCore.d.ts +2 -2
  136. package/dist/components/charts/shared/heatmapStyleRules.d.ts +13 -0
  137. package/dist/components/charts/shared/knownChartComponents.d.ts +1 -1
  138. package/dist/components/charts/shared/networkUtils.d.ts +14 -0
  139. package/dist/components/charts/shared/selectionUtils.d.ts +3 -1
  140. package/dist/components/charts/shared/types.d.ts +4 -2
  141. package/dist/components/charts/shared/useChartLegend.d.ts +2 -1
  142. package/dist/components/charts/shared/useLikertAggregation.d.ts +8 -2
  143. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +9 -5
  144. package/dist/components/charts/shared/useOrdinalPieceStyle.d.ts +1 -1
  145. package/dist/components/charts/shared/useXYBrush.d.ts +24 -0
  146. package/dist/components/charts/xy/Heatmap.d.ts +16 -0
  147. package/dist/components/charts/xy/LineChart.d.ts +9 -0
  148. package/dist/components/charts/xy/Scatterplot.d.ts +7 -0
  149. package/dist/components/charts/xy/WaterfallChart.capability.d.ts +2 -0
  150. package/dist/components/charts/xy/WaterfallChart.d.ts +68 -0
  151. package/dist/components/evidence/chartEvidenceEnvelope.d.ts +146 -0
  152. package/dist/components/evidence/evidenceGate.d.ts +28 -0
  153. package/dist/components/realtime/BinAccumulator.d.ts +5 -1
  154. package/dist/components/realtime/types.d.ts +16 -7
  155. package/dist/components/recipes/adjacencyFlow.d.ts +12 -0
  156. package/dist/components/recipes/adjacencyFlowAggregation.d.ts +72 -0
  157. package/dist/components/recipes/adjacencyFlowGeometry.d.ts +79 -0
  158. package/dist/components/recipes/lineageDag.d.ts +17 -0
  159. package/dist/components/recipes/lineageDagHulls.d.ts +22 -0
  160. package/dist/components/recipes/transitDiagram.d.ts +75 -0
  161. package/dist/components/recipes/transitDiagramGeometry.d.ts +47 -0
  162. package/dist/components/semiotic-access.d.ts +9 -0
  163. package/dist/components/semiotic-ai-audits.d.ts +17 -0
  164. package/dist/components/semiotic-ai-core.d.ts +9 -0
  165. package/dist/components/semiotic-ai.d.ts +5 -17
  166. package/dist/components/semiotic-evidence.d.ts +10 -0
  167. package/dist/components/semiotic-line.d.ts +9 -0
  168. package/dist/components/semiotic-network.d.ts +3 -0
  169. package/dist/components/semiotic-ordinal.d.ts +2 -0
  170. package/dist/components/semiotic-realtime-core.d.ts +3 -2
  171. package/dist/components/semiotic-recipes-core.d.ts +6 -0
  172. package/dist/components/semiotic-themes-core.d.ts +3 -0
  173. package/dist/components/semiotic-utils-core.d.ts +5 -0
  174. package/dist/components/semiotic-utils.d.ts +1 -1
  175. package/dist/components/semiotic-xy.d.ts +3 -0
  176. package/dist/components/semiotic.d.ts +9 -3
  177. package/dist/components/server/renderDashboard.d.ts +37 -0
  178. package/dist/components/server/renderEvidence.d.ts +27 -0
  179. package/dist/components/server/renderToStaticSVG.d.ts +2 -30
  180. package/dist/components/server/serverChartConfigShared.d.ts +13 -0
  181. package/dist/components/server/serverChartConfigs.d.ts +9 -0
  182. package/dist/components/server/serverChartConfigsComposite.d.ts +4 -0
  183. package/dist/components/server/serverChartConfigsCustom.d.ts +2 -0
  184. package/dist/components/server/serverChartConfigsGeo.d.ts +1 -0
  185. package/dist/components/server/serverChartConfigsOrdinal.d.ts +3 -2
  186. package/dist/components/server/serverChartConfigsXY.d.ts +1 -0
  187. package/dist/components/server/serverChartConfigsXYExtra.d.ts +3 -0
  188. package/dist/components/server/serverCompositeChainReaction.d.ts +3 -0
  189. package/dist/components/server/serverOrdinalGauge.d.ts +3 -0
  190. package/dist/components/server/serverOrdinalLikert.d.ts +2 -0
  191. package/dist/components/store/selectionProvenance.d.ts +8 -0
  192. package/dist/components/store/themeCore.d.ts +5 -1
  193. package/dist/components/stream/GeoPipelineStore.d.ts +1 -1
  194. package/dist/components/stream/MarginalGraphics.d.ts +3 -3
  195. package/dist/components/stream/MarginalGraphicsLazy.d.ts +22 -0
  196. package/dist/components/stream/NetworkPipelineStore.d.ts +2 -0
  197. package/dist/components/stream/OrdinalPipelineStore.d.ts +1 -1
  198. package/dist/components/stream/PipelineStore.d.ts +1 -1
  199. package/dist/components/stream/SceneToSVG.d.ts +1 -1
  200. package/dist/components/stream/canvasSetup.d.ts +8 -2
  201. package/dist/components/stream/customLayoutAttempt.d.ts +21 -0
  202. package/dist/components/stream/geoTypes.d.ts +1 -1
  203. package/dist/components/stream/isServerEnvironment.d.ts +6 -0
  204. package/dist/components/stream/layouts/forceLayoutNodeSize.d.ts +12 -0
  205. package/dist/components/stream/layouts/forceLayoutPlugin.d.ts +2 -9
  206. package/dist/components/stream/layouts/forceLayoutWorkerClient.d.ts +2 -21
  207. package/dist/components/stream/layouts/forceLayoutWorkerPolicy.d.ts +21 -0
  208. package/dist/components/stream/layouts/index.d.ts +6 -12
  209. package/dist/components/stream/layouts/missingPlugin.d.ts +7 -0
  210. package/dist/components/stream/layouts/registerBuiltIn.d.ts +1 -0
  211. package/dist/components/stream/layouts/registry.d.ts +12 -0
  212. package/dist/components/stream/marginalConfig.d.ts +3 -0
  213. package/dist/components/stream/networkCustomLayout.d.ts +7 -0
  214. package/dist/components/stream/networkCustomLayoutOutput.d.ts +13 -0
  215. package/dist/components/stream/networkCustomLayoutRunner.d.ts +1 -1
  216. package/dist/components/stream/networkTypes.d.ts +5 -1
  217. package/dist/components/stream/ordinalTypes.d.ts +1 -1
  218. package/dist/components/stream/physics/StreamPhysicsTypes.d.ts +1 -1
  219. package/dist/components/stream/pipelineDomainResolution.d.ts +6 -0
  220. package/dist/components/stream/renderers/pointCanvasRenderer.d.ts +4 -0
  221. package/dist/components/stream/renderers/resolveCSSColor.d.ts +4 -4
  222. package/dist/components/stream/types.d.ts +8 -1
  223. package/dist/components/stream/useEnsureCustomXYRenderers.d.ts +18 -0
  224. package/dist/components/stream/useMarginalValues.d.ts +13 -0
  225. package/dist/components/stream/xyCanvasRenderers.d.ts +4 -4
  226. package/dist/components/stream/xyPlugins/areaPlugin.d.ts +2 -0
  227. package/dist/components/stream/xyPlugins/barPlugin.d.ts +2 -0
  228. package/dist/components/stream/xyPlugins/candlestickPlugin.d.ts +2 -0
  229. package/dist/components/stream/xyPlugins/customPlugin.d.ts +6 -0
  230. package/dist/components/stream/xyPlugins/heatmapPlugin.d.ts +2 -0
  231. package/dist/components/stream/xyPlugins/lineFamily.d.ts +5 -0
  232. package/dist/components/stream/xyPlugins/linePlugin.d.ts +2 -0
  233. package/dist/components/stream/xyPlugins/missingPlugin.d.ts +7 -0
  234. package/dist/components/stream/xyPlugins/mixedPlugin.d.ts +2 -0
  235. package/dist/components/stream/xyPlugins/pointPlugin.d.ts +3 -0
  236. package/dist/components/stream/xyPlugins/registerBuiltIn.d.ts +1 -0
  237. package/dist/components/stream/xyPlugins/registry.d.ts +31 -0
  238. package/dist/components/stream/xyPlugins/stackedAreaPlugin.d.ts +2 -0
  239. package/dist/components/stream/xyPlugins/swarmPlugin.d.ts +2 -0
  240. package/dist/components/stream/xyPlugins/waterfallPlugin.d.ts +2 -0
  241. package/dist/forceLayoutWorker.js +1 -1
  242. package/dist/geo.min.js +1 -1
  243. package/dist/geo.module.min.js +1 -1
  244. package/dist/network.module.min.js +1 -1
  245. package/dist/ordinal.module.min.js +1 -1
  246. package/dist/physics.module.min.js +1 -1
  247. package/dist/rough.module.min.js +1 -1
  248. package/dist/semiotic-access.d.ts +9 -0
  249. package/dist/semiotic-access.min.js +2 -0
  250. package/dist/semiotic-access.module.min.js +2 -0
  251. package/dist/semiotic-ai-core.d.ts +9 -0
  252. package/dist/semiotic-ai-core.min.js +1 -1
  253. package/dist/semiotic-ai-core.module.min.js +1 -1
  254. package/dist/semiotic-ai.d.ts +5 -17
  255. package/dist/semiotic-ai.module.min.js +1 -1
  256. package/dist/semiotic-client-cjs-shared.min.js +1 -1
  257. package/dist/semiotic-client-shared.module.min.js +1 -1
  258. package/dist/semiotic-evidence.d.ts +10 -0
  259. package/dist/semiotic-evidence.min.js +1 -0
  260. package/dist/semiotic-evidence.module.min.js +1 -0
  261. package/dist/semiotic-experimental-auxiliary.module.min.js +1 -1
  262. package/dist/semiotic-experimental-node-auxiliary.module.min.js +1 -1
  263. package/dist/semiotic-experimental-react-shared.module.min.js +1 -1
  264. package/dist/semiotic-experimental-vacp.min.js +1 -1
  265. package/dist/semiotic-experimental-vacp.module.min.js +1 -1
  266. package/dist/semiotic-line.d.ts +9 -0
  267. package/dist/semiotic-line.min.js +2 -0
  268. package/dist/semiotic-line.module.min.js +2 -0
  269. package/dist/semiotic-network.d.ts +3 -0
  270. package/dist/semiotic-ordinal.d.ts +2 -0
  271. package/dist/semiotic-realtime-core.d.ts +3 -2
  272. package/dist/semiotic-realtime-core.module.min.js +1 -1
  273. package/dist/semiotic-recipes-core-cjs-base.min.js +1 -1
  274. package/dist/semiotic-recipes-core.d.ts +6 -0
  275. package/dist/semiotic-recipes-core.module.min.js +1 -1
  276. package/dist/semiotic-server-edge-node.module.min.js +1 -1
  277. package/dist/semiotic-server-edge.min.js +1 -1
  278. package/dist/semiotic-server-edge.module.min.js +1 -1
  279. package/dist/semiotic-server-node.min.js +1 -1
  280. package/dist/semiotic-server-node.module.min.js +1 -1
  281. package/dist/semiotic-themes-core.d.ts +3 -0
  282. package/dist/semiotic-themes-core.min.js +1 -1
  283. package/dist/semiotic-themes-core.module.min.js +1 -1
  284. package/dist/semiotic-themes.min.js +1 -1
  285. package/dist/semiotic-themes.module.min.js +1 -1
  286. package/dist/semiotic-utils-core.d.ts +5 -0
  287. package/dist/semiotic-utils-core.min.js +1 -1
  288. package/dist/semiotic-utils-core.module.min.js +1 -1
  289. package/dist/semiotic-utils.d.ts +1 -1
  290. package/dist/semiotic-utils.module.min.js +1 -1
  291. package/dist/semiotic-xy.d.ts +3 -0
  292. package/dist/semiotic.d.ts +9 -3
  293. package/dist/semiotic.module.min.js +1 -1
  294. package/dist/server.min.js +1 -1
  295. package/dist/server.module.min.js +1 -1
  296. package/dist/xy.module.min.js +1 -1
  297. package/package.json +39 -60
  298. package/dist/c-3KZD6AXJ.min.js +0 -1
  299. package/dist/c-4TWEX5HG.min.js +0 -1
  300. package/dist/c-5YCIX3VZ.min.js +0 -1
  301. package/dist/c-6FEKTA3U.min.js +0 -1
  302. package/dist/c-74HEEZGK.min.js +0 -1
  303. package/dist/c-BWNB6USU.min.js +0 -1
  304. package/dist/c-C25ENHIK.min.js +0 -1
  305. package/dist/c-CDR5AO3R.min.js +0 -1
  306. package/dist/c-E3JFRRMI.min.js +0 -1
  307. package/dist/c-EBFPQHHO.min.js +0 -1
  308. package/dist/c-GIKRQI4X.min.js +0 -1
  309. package/dist/c-GPYOFETM.min.js +0 -1
  310. package/dist/c-IDUHYYSI.min.js +0 -1
  311. package/dist/c-JAZ73J32.min.js +0 -1
  312. package/dist/c-KG3NXHAL.min.js +0 -1
  313. package/dist/c-KII3PLZE.min.js +0 -1
  314. package/dist/c-LIXGXMNS.min.js +0 -1
  315. package/dist/c-LVEY6D6B.min.js +0 -1
  316. package/dist/c-M4Y3BHFR.min.js +0 -1
  317. package/dist/c-MAIICR2Z.min.js +0 -1
  318. package/dist/c-MG5DM6VE.min.js +0 -1
  319. package/dist/c-O6U6K4CW.min.js +0 -1
  320. package/dist/c-OQ7M4AGV.min.js +0 -1
  321. package/dist/c-OXYMVK7Q.min.js +0 -1
  322. package/dist/c-QHF5YON3.min.js +0 -1
  323. package/dist/c-RR3GO5SW.min.js +0 -1
  324. package/dist/c-S2BXNNJN.min.js +0 -1
  325. package/dist/c-SUILCHWU.min.js +0 -1
  326. package/dist/c-US5ZFT6E.min.js +0 -1
  327. package/dist/c-UUKVD4WB.min.js +0 -1
  328. package/dist/c-WJCD5EUY.min.js +0 -1
  329. package/dist/c-YDAY2WFR.min.js +0 -1
  330. package/dist/c-ZOWWU34K.min.js +0 -1
  331. /package/dist/{c-COHXCW3Q.min.js → c-YZVRZGX2.min.js} +0 -0
package/ai/examples.md CHANGED
@@ -12,7 +12,7 @@ the schema is authoritative when prose drifts.
12
12
  ### LineChart (single line)
13
13
 
14
14
  ```jsx
15
- import { LineChart } from "semiotic/xy"
15
+ import { LineChart } from "semiotic/line"
16
16
 
17
17
  const data = [
18
18
  { month: "Jan", revenue: 4200 },
@@ -37,7 +37,7 @@ Key props: `xAccessor`, `yAccessor`, `curve`, `showPoints`, `fillArea`
37
37
  ### LineChart (multi-line)
38
38
 
39
39
  ```jsx
40
- import { LineChart } from "semiotic/xy"
40
+ import { LineChart } from "semiotic/line"
41
41
 
42
42
  const data = [
43
43
  { quarter: 1, sales: 120, region: "East" },
@@ -67,7 +67,7 @@ instead of forcing the value through a single field name. This is especially
67
67
  useful for multi-line data with a different metric per series.
68
68
 
69
69
  ```jsx
70
- import { LineChart } from "semiotic/xy"
70
+ import { LineChart } from "semiotic/line"
71
71
 
72
72
  const data = [
73
73
  { timestamp: 1, metricLabel: "valueA", valueA: 12, valueB: 60 },
@@ -160,6 +160,30 @@ import { Heatmap } from "semiotic/xy"
160
160
 
161
161
  Key props: `showLegend` enables gradient legend, `legendPosition` ("right"|"left"|"top"|"bottom")
162
162
 
163
+ ### WaterfallChart
164
+
165
+ ```jsx
166
+ import { WaterfallChart } from "semiotic/xy"
167
+
168
+ const data = [
169
+ { step: "Opening", value: 120 },
170
+ { step: "New sales", value: 45 },
171
+ { step: "Returns", value: -18 },
172
+ { step: "Discounts", value: -12 },
173
+ { step: "Other", value: 8 }
174
+ ]
175
+
176
+ <WaterfallChart
177
+ data={data}
178
+ xAccessor="step"
179
+ yAccessor="value"
180
+ xLabel="Step"
181
+ yLabel="Change"
182
+ />
183
+ ```
184
+
185
+ Key props: `yAccessor` is a **signed delta** per row, not a running total. Categorical `xAccessor` values are plotted by index. Use `RealtimeWaterfallChart` for a push-driven window.
186
+
163
187
  ### AreaChart
164
188
 
165
189
  ```jsx
@@ -502,7 +526,7 @@ const data = [
502
526
  />
503
527
  ```
504
528
 
505
- Key props: `bins` (default 25), `relative` (normalize per-category)
529
+ Key props: `bins` (default 25), `relative` (normalize per-category), `brush`
506
530
 
507
531
  ### ViolinPlot
508
532
 
@@ -533,6 +557,32 @@ const data = [
533
557
 
534
558
  Key props: `bins`, `curve` (default "catmullRom"), `showIQR` (default true)
535
559
 
560
+ ### RadarChart
561
+
562
+ ```jsx
563
+ import { RadarChart } from "semiotic/ordinal"
564
+
565
+ const data = [
566
+ { name: "Alpha", attribute: "speed", value: 80 },
567
+ { name: "Alpha", attribute: "power", value: 55 },
568
+ { name: "Alpha", attribute: "range", value: 40 },
569
+ { name: "Beta", attribute: "speed", value: 45 },
570
+ { name: "Beta", attribute: "power", value: 75 },
571
+ { name: "Beta", attribute: "range", value: 60 }
572
+ ]
573
+
574
+ <RadarChart
575
+ data={data}
576
+ categoryAccessor="attribute"
577
+ valueAccessor="value"
578
+ seriesAccessor="name"
579
+ colorBy="name"
580
+ showLegend
581
+ />
582
+ ```
583
+
584
+ Key props: `categoryAccessor` (radial axes), `valueAccessor` (magnitude), `seriesAccessor` (polygon identity). Use only when the axes are comparable magnitudes.
585
+
536
586
  ---
537
587
 
538
588
  ## Hierarchical Data — Single Root Object
@@ -1222,7 +1272,7 @@ Key props: `onClick` receives the original datum and pixel coordinates. Works on
1222
1272
  ### Synced crosshair across time-series charts
1223
1273
 
1224
1274
  ```jsx
1225
- import { LineChart } from "semiotic/xy"
1275
+ import { LineChart } from "semiotic/line"
1226
1276
  import { LinkedCharts } from "semiotic/ai"
1227
1277
 
1228
1278
  <LinkedCharts>
@@ -1289,6 +1339,59 @@ Key props: `y-threshold` works on vertical ordinal charts. `category-highlight`
1289
1339
 
1290
1340
  ## Recipe Layouts — Explicit Semantics Without Bespoke Geometry
1291
1341
 
1342
+ ### ParallelCoordinatesRecipe (schema-backed portable recipe)
1343
+
1344
+ ```jsx
1345
+ import { ChartRecipe } from "semiotic/ai"
1346
+
1347
+ const vehicles = [
1348
+ { id: "compact", mpg: 32, power: 88, weight: 2100, origin: "EU" },
1349
+ { id: "sedan", mpg: 25, power: 132, weight: 2900, origin: "US" },
1350
+ { id: "sport", mpg: 18, power: 280, weight: 2600, origin: "JP" },
1351
+ ]
1352
+
1353
+ <ChartRecipe
1354
+ recipeId="ParallelCoordinatesRecipe"
1355
+ data={vehicles}
1356
+ layoutConfig={{
1357
+ fields: ["mpg", "power", "weight"],
1358
+ colorBy: "origin",
1359
+ showPoints: true,
1360
+ }}
1361
+ title="Vehicle profiles"
1362
+ description="Vehicle profiles compared across independently scaled measures."
1363
+ summary="Power increases as fuel economy falls in this sample."
1364
+ accessibleTable
1365
+ />
1366
+ ```
1367
+
1368
+ The serialized/MCP/server component name is `ParallelCoordinatesRecipe` with
1369
+ the same props. The schema requires two to twelve unique numeric field names.
1370
+
1371
+ ### CalendarHeatmapRecipe (schema-backed portable recipe)
1372
+
1373
+ ```jsx
1374
+ import { ChartRecipe } from "semiotic/ai"
1375
+
1376
+ <ChartRecipe
1377
+ recipeId="CalendarHeatmapRecipe"
1378
+ data={[
1379
+ { date: "2026-01-01", count: 4 },
1380
+ { date: "2026-01-02", count: 9 },
1381
+ { date: "2026-01-03", count: 2 },
1382
+ ]}
1383
+ layoutConfig={{ dateAccessor: "date", valueAccessor: "count", year: 2026 }}
1384
+ title="Daily activity"
1385
+ description="Daily activity positioned by calendar week and weekday."
1386
+ summary="January 2 has the highest value in this sample."
1387
+ accessibleTable
1388
+ />
1389
+ ```
1390
+
1391
+ The serialized/MCP/server component name is `CalendarHeatmapRecipe`. Keep one
1392
+ calendar year per chart; use the raw layouts from `semiotic/recipes` when a
1393
+ local React callback or custom frame behavior is necessary.
1394
+
1292
1395
  ### Word Trails (source-aware color + progressive reveal)
1293
1396
 
1294
1397
  ```jsx
@@ -1749,7 +1852,7 @@ Key props: `value` (the focal number), `label` (the visible heading), `descripti
1749
1852
 
1750
1853
  ```jsx
1751
1854
  import { BigNumber } from "semiotic/value"
1752
- import { LineChart } from "semiotic/xy"
1855
+ import { LineChart } from "semiotic/line"
1753
1856
 
1754
1857
  <BigNumber
1755
1858
  value={1284900}
package/ai/reference.md CHANGED
@@ -10,7 +10,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
10
10
  - Install: `npm install semiotic`
11
11
  <!-- semiotic-bundle-sizes:start -->
12
12
  <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
13
- - **Use sub-path imports** — `semiotic/xy` (152KB gz), `semiotic/ordinal` (128KB gz), `semiotic/network` (149KB gz), `semiotic/geo` (109KB gz), `semiotic/realtime` (163KB gz), `semiotic/realtime/core` (162KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (195KB gz), `semiotic/server/node` (195KB gz), `semiotic/server/edge` (200KB 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` (6KB gz), `semiotic/themes/core` (6KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (164KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (520KB gz), `semiotic/ai/core` (87KB gz), `semiotic/controls` (11KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 334KB gz.
13
+ - **Use sub-path imports** — `semiotic/access` (35KB gz), `semiotic/evidence` (50KB gz), `semiotic/line` (135KB gz), `semiotic/xy` (166KB gz), `semiotic/ordinal` (130KB gz), `semiotic/network` (157KB gz), `semiotic/geo` (113KB gz), `semiotic/realtime` (162KB gz), `semiotic/realtime/core` (161KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (216KB gz), `semiotic/server/node` (216KB gz), `semiotic/server/edge` (222KB gz), `semiotic/utils` (103KB gz), `semiotic/utils/core` (95KB gz), `semiotic/utils/react` (7KB gz), `semiotic/recipes` (100KB gz), `semiotic/recipes/core` (92KB gz), `semiotic/recipes/react` (8KB gz), `semiotic/themes` (12KB gz), `semiotic/themes/core` (12KB gz), `semiotic/themes/react` (7KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (168KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (553KB gz), `semiotic/ai/core` (101KB gz), `semiotic/controls` (11KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 360KB gz.
14
14
  <!-- semiotic-bundle-sizes:end -->
15
15
  - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y|--evaluate]` · MCP: `npx semiotic-mcp`
16
16
 
@@ -18,7 +18,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
18
18
  HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless you need control they don't expose. Stream Frames pass `RealtimeNode`/`RealtimeEdge` wrappers in callbacks, not your data. Every HOC accepts `frameProps`, has an error boundary + dev-mode validation. TypeScript `strict: true`.
19
19
 
20
20
  ## Common Props (chart HOCs only)
21
- `title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke`, `strokeWidth`, `opacity`, `enableHover` (true), `tooltip` (boolean | "multi" | function | config), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading`, `loadingContent` (ReactNode; `false` suppresses), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations`, `accessibleTable` (true; use `{ portalTarget: "element-id" }` to portal its interactive UI outside a consumer-owned `role="img"`), `hoverHighlight` (requires `colorBy`), `hoverRadius` (30), `animate` (boolean | {duration?, easing?, intro?}), `axisExtent` ("nice"|"exact" — pins first/last tick to data min/max; XY x/y + ordinal value axis only; override per XY axis with `frameProps.axes[i].extent`), `maxDevicePixelRatio` (canvas backing-store cap; defaults 3 desktop / 2 coarse-pointer or narrow viewports; 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; very large canvases are further capped to an 8-megapixel, 16K-side backing-store budget; canvases repaint on browser zoom / display-density changes).
22
22
 
23
23
  This list is not global. Plain value components do not inherit chart-HOC props and must be
24
24
  validated against their own schema. In particular, `BigNumber` uses `label`, `description`, and
@@ -31,42 +31,44 @@ validated against their own schema. In particular, `BigNumber` uses `label`, `de
31
31
 
32
32
  ## XY Charts (`semiotic/xy`)
33
33
 
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
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), `brush` (x-axis overlay; also enabled by `linkedBrush`), `tooltip="multi"` for hover-anywhere
35
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"`
36
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`.
37
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.
38
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.
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)
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), `brush` (xy overlay; also enabled by `linkedBrush`)
40
40
  **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
41
41
  **ConnectedScatterplot** — + `orderAccessor`, `regression`
42
42
  **QuadrantChart** — Scatterplot + `quadrants`, `xCenter`, `yCenter`
43
43
  **MultiAxisLineChart** — Dual Y-axis. `series` (`[{yAccessor, label?, color?, format?, extent?}]`). Falls back to multi-line if ≠ 2 series.
44
- **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `customColorScale`, `showValues`, `cellBorderColor`
45
- **ScatterplotMatrix** — `fields` (numeric field names)
46
- **MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart.
44
+ **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `customColorScale`, `showValues`, `cellBorderColor`, `styleRules` (displayed cells; aggregate cells expose `count`, `sum`, `agg`, bin centers, and the displayed aggregate as `ctx.value`)
45
+ **ScatterplotMatrix** — `fields` (numeric field names). `renderChart()` emits one standalone composite SVG containing every off-diagonal scatter scene, diagonal distribution, field label, and categorical legend; interactive brushing/hover remains a browser affordance.
46
+ **MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart. `renderChart()` preserves both scenes and paints a supplied `brushExtent` into the overview, so the standalone snapshot retains the selected-detail/context relationship.
47
47
  **CandlestickChart** — `xAccessor`, `highAccessor` (req), `lowAccessor` (req), `openAccessor`+`closeAccessor` (optional → OHLC; high/low only → range). `candlestickStyle` ({upColor, downColor, wickColor, rangeColor, bodyWidth, wickWidth}). Honors `mode`.
48
+ **WaterfallChart** — cumulative signed steps as floating bars. `xAccessor` ("x"), `yAccessor` ("y" — each row is a **delta**, not a running total), `positiveColor`, `negativeColor`, `connectorStroke`, `connectorWidth`, `gap`. String/categorical x values are plotted by index. Live window: `RealtimeWaterfallChart`.
48
49
 
49
50
  ## Ordinal Charts (`semiotic/ordinal`)
50
51
 
51
- **BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`
52
+ **BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`, `brush` (value-axis overlay; `onBrush` / `linkedBrush`)
52
53
  **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order), `styleRules`
53
54
  **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default), `styleRules`
54
55
  **SwarmPlot** — `colorBy`, `sizeBy`, `symbolBy` (categorical field → glyph shape, like Scatterplot), `symbolMap`, `pointRadius`, `pointOpacity`
55
56
  **BoxPlot** — + `showOutliers`, `outlierRadius`
56
- **Histogram** — + `bins` (25), `relative`. Always horizontal.
57
+ **Histogram** — + `bins` (25), `relative`, `brush` (value-axis overlay; `onBrush` / `linkedBrush`). Always horizontal.
57
58
  **ViolinPlot** — + `bins`, `curve`, `showIQR`
58
59
  **RidgelinePlot** — + `bins`, `amplitude` (1.5)
59
60
  **DotPlot** — + `sort` ("auto"), `dotRadius`, `showGrid` (true default), `regression`
60
61
  **PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
61
62
  **DonutChart** — PieChart + `innerRadius` (60), `centerContent`
62
63
  **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor?`, `connectorOpacity`, `orientation`
64
+ **RadarChart** — multivariate comparison on a shared radial axis. Long-form rows: one observation per series × attribute. `categoryAccessor` ("attribute"), `valueAccessor` ("value"), `seriesAccessor` (defaults to `colorBy`), `pointRadius` (4), `valueExtent` (`[0, data-max]` default). Axes must be comparable magnitudes.
63
65
  **SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (req), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`, `roundedTop` (pixel radius on outer ends of each lane; middles stay square; single-segment lanes round all four)
64
66
  **LikertChart** — `categoryAccessor`, `valueAccessor`|`levelAccessor`+`countAccessor`, `levels?`, `orientation`, `colorScheme`
65
67
  **GaugeChart** — `value` (req), `min`, `max`, `thresholds`, `arcWidth`, `cornerRadius` (rounded segment ends), `sweep`, `fillZones`, `showNeedle`, `centerContent`
66
68
 
67
- All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
69
+ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true), `styleRules`. Raw-mark charts use `valueAccessor`; box/violin/ridgeline use the rendered category median and expose `n`/`min`/`q1`/`median`/`q3`/`max`/`mean`; Histogram uses displayed bin count and exposes `bin`/`count`/`range`/`category`; Pie/Donut use absolute wedge magnitude; Likert uses displayed signed percentage; Gauge rules see synthetic zone segments (`category`, proportional `value`, `_zone`, `_isFill`).
68
70
 
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`.
71
+ **`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: **all 16 ordinal HOCs**; **XY** LineChart/AreaChart/StackedAreaChart/BumpChart (per-series), Scatterplot/BubbleChart/QuadrantChart/ConnectedScatterplot (per-point), and Heatmap (displayed cells); **network** ForceDirectedGraph/SankeyDiagram/ProcessSankey/ChordDiagram plus Tree/Treemap/CirclePack/Orbit (authored nodes); **realtime** Line/Histogram/TemporalHistogram/Swarm/Waterfall/Heatmap; **geo** ChoroplethMap (features) plus ProportionalSymbolMap/DistanceCartogram (symbols); **physics** GaltonBoard/UnitPile/CollisionSwarm/EventDrop/PacketFlow (particles or packets). `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 are host-resolved: ordinal `{ value, category }`; XY `{ value(=y), x, y }`; node/feature/particle families `{ value, category }`; aggregate Heatmap/Histogram forms use the displayed aggregate and retain fields such as `count`, `sum`, `agg`, and `range`. A rule's style may include `cursor` plus 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. Precedence: top-level primitives > per-mark style fn (`pieceStyle`/`pointStyle`/`nodeStyle`) > `styleRules` > base `colorBy`/`color`/theme. Works through `renderChart`/MCP for every SSR-capable wired form (use declarative thresholds, not predicates, across JSON boundaries). Caveats: line/area rules resolve per-series, not per-vertex; MultiAxisLineChart, MinimapChart, CandlestickChart, DifferenceChart, WaterfallChart, and ScatterplotMatrix are not wired. Exported from `semiotic` + each family entry + `semiotic/utils`: `StyleRule`, `resolveStyleRules`, `matchesThreshold`, `makeRuleValueResolver`, `makeXYRuleContext`, `makeNodeRuleContext`, `composeStyleRules`, `HatchFill`, `isHatchFill`. See `/features/style-rules`.
70
72
 
71
73
  ## Network Charts (`semiotic/network`)
72
74
 
@@ -104,11 +106,11 @@ Process/arrival/distribution charts backed by `StreamPhysicsFrame`. The settled
104
106
  **ProcessFlowChart** — multi-body workflow lane. `data`, `stages` (required: `[{id, label?, force?, damping?, capacity?, pressure?, portal?, absorb?, share?}]`), `stageAccessor` ("stage"), `idAccessor`, `groupBy` (optional feature key; completion when all members hit an absorb stage), `groupLabelAccessor`, `workAccessor`, `radiusAccessor`, `ballRadius` (6), `colorBy`, `groupCompletion` ("allAbsorbed"|"none"), `groupAnchorAlong` (0.55), `showProjection` (true), `showChrome` (true — processChrome kit), `liveCapacity` (true — FIFO queues at `unitsPerSecond`), `onCapacityChange` (queue depth / processed), `bodyLimit` (soft stream budget + oldest eviction), `bodyMark` ("circle"|"halo"|"faceted"|"pill"|"diamond"|"square" or per-row `datum.__physicsMark`), `selection`, `settle`, `seed`, `size`, `paused`, `frameProps`. Settled projection is stage occupancy + capacity badges; use for review queues / triage / merge pipelines. Prefer **GauntletChart** for one compound plan with timed gate effects.
105
107
  **Stage geography kit** (`semiotic/physics` + `semiotic/recipes`) — `physicsStageGeography({size, flow ("down"|"right"), destinations (count | [{id,label}]), padding, chargeExtent, destinationExtent, projectionExtent, channelRatio})` → `{charge, apparatus, destinations: [{id,label,order,centerX,centerY,…}], projection}`. The shared **charge → apparatus → destinations** vocabulary every physics chart re-invented locally (Gauntlet `startX`/`socketX`/`graveyardX`, Crucible `chamber`/`mouth`/`outlets`, Galton bins and Pile tubes writing the *same* lane formula). Companions: `physicsStageColliders` (floor + one divider per interior boundary, so bodies land in the bin the data says), `physicsChargePoint` (spread a burst across the entry zone instead of co-locating it), `physicsDestination(geo, id)`, `describePhysicsStageGeography` (one-sentence reading protocol for a11y/agent grounding). Authoring vocabulary for a **new** chart or `PhysicsCustomChart` layout — shipped charts keep their own layouts; a test pins the builder to their lane math.
106
108
  **Terminal state (event-tape charts)** — a tape-driven physics chart's end state must be computable from authored inputs with no simulation, because that pure result is what reduced motion, SSR, snapshot export, and `describeChart` receive. `CrucibleChart`: `compileCruciblePlan(...)` → `plan.initialState`/`plan.terminalState`/`plan.terminalSpawns`. `ChainReactionChart`: `initialRuntime(machine, mode, currentTime, true)`. `GauntletChart`: **`resolveGauntletTerminalStates({projects, events, layout, positiveProperties, negativeProperties, viability?, outcome?})`** (also `resolveGauntletTerminalState` for one project) — folds the authored tape, mirroring the live tick's effect order. Caveat: with Gauntlet's `crashDetection` armed (default), physics can still override the outcome to `bad_design_crash`, which no pure fold can predict; the pure result is "what the plan earns on paper". Pass `crashDetection={false}` for a fully authored reading. **Design test for a new physics metaphor:** can you state its ledger in one sentence (else it's an animation), does its terminal state exist without simulating (else it's a movie), would a naive reader guess the reading protocol from the apparatus (else the name is wrong)?
107
- **Physics family contracts** (every physics HOC) — `seed` (deterministic; an explicit `frameProps.config.kernel.seed` still wins), `rerunMS` (settle → delay → deterministic replay; `null`/omitted = single run), `showProjection`, `paused`, and `selection` + `linkedHover`. `selection` accepts **either** a `{ name }` `SelectionConfig` — joining the shared selection store so physics bodies cross-highlight inside `LinkedCharts` like every other family — **or** a resolved `{ isActive, predicate }` `PhysicsBodySelection` body predicate as the escape hatch. The store's datum predicate is lifted over `body.datum`, so chrome bodies (walls, pegs, tubes) never match a data selection. Under `prefers-reduced-motion` the frame settles to the true end state in one pass: paced arrivals (`initialSpawnPacing`, per-datum `spawnAt`) are all admitted and elapsed-time event tapes run to completion, so the settled projection reports the outcome rather than the authored start.
109
+ **Physics family contracts** (every physics HOC) — `seed` (deterministic; an explicit `frameProps.config.kernel.seed` still wins), `rerunMS` (settle → delay → deterministic replay; `null`/omitted = single run), `onSimulationStateChange(state, previousState)` (public running/settled readiness without reaching into `frameProps.config`), `showProjection`, `paused`, and `selection` + `linkedHover`. `selection` accepts **either** a `{ name }` `SelectionConfig` — joining the shared selection store so physics bodies cross-highlight inside `LinkedCharts` like every other family — **or** a resolved `{ isActive, predicate }` `PhysicsBodySelection` body predicate as the escape hatch. The store's datum predicate is lifted over `body.datum`, so chrome bodies (walls, pegs, tubes) never match a data selection. Under `prefers-reduced-motion` the frame settles to the true end state in one pass: paced arrivals (`initialSpawnPacing`, per-datum `spawnAt`) are all admitted and elapsed-time event tapes run to completion, so the settled projection reports the outcome rather than the authored start.
108
110
  **Physics controllers** (`createCapacityQueueController`, `createPortalController`, `composePhysicsControllers`) — process plugins via `controllers`. Capacity `getSnapshot()` → queueDepth/processedCount; emit `physics-capacity-processed`. **processChrome** (`semiotic/physics` / `semiotic/recipes`) — stage bays, capacity badges, feature sockets (theme: `--semiotic-process-*`). `PhysicsCustomChart`: `layout()` may return `regionEffects`, `controllers`, `bodyForces`; `layoutConfig` hot path without re-enqueue. Guide: `/features/physics-process-guide`. Contracts: `PhysicsContracts.test.tsx`.
109
111
  **GauntletChart** — compound project core + tethered positive/negative property bodies + timed gate events. `positiveProperties`/`negativeProperties` (req), `gates`, `events`, `showChrome` (true), `showProjection` (true — viability/outcome strip), `showTethers` (true), `onStateChange`, `frameProps`. Bodies clamp inside walls (`clampGauntletPoint`). Not for multi-item factory floors (use ProcessFlowChart).
110
112
  **CrucibleChart** — bounded peer components undergo authored `phases` and `events`, form declared `products`, and settle into reason-labelled `outlets` with source lineage. The ledger/projection is authoritative; motion never infers classification, timing, membership, loss, or routing. `buildCrucibleProductEvents({productId, form, contributions?, complete})` is pure authoring sugar for `combine → contribute* → complete-product`; every source/relation id, event position, reason, and outlet remains caller-supplied. The ref handle's `replay()` atomically restarts the deterministic tape even mid-run (`reset()` restores-and-pauses; `rerunMS` repeats after settlement). `playbackRate` changes presentation only. No push/live-event API.
111
- **ChainReactionChart** — dependency chain reaction. `data`, `taskIDAccessor`, `labelAccessor`, `laneAccessor`, `dependencyAccessor` (all required — edges are never inferred), plus optional `startAccessor`/`endAccessor`/`progressAccessor`/`statusAccessor`/`completionTimeAccessor`/`blockerAccessor`/`milestoneAccessor`. Tasks place by workstream lane × dependency depth; a completed task releases one delivery ball per outgoing edge and a downstream task arms only once every prerequisite ball arrives, so a blocked task's *reach* is the reading. `mode` ("snapshot" derives the settled state at `currentTime` with no simulation | "replay" animates deliveries over that same derived state | "mechanical"), `insight` ("blocker-amplification" reports unfinished downstream tasks + affected lanes), `controls` (play/pause/step/reset/settle), `selectedTaskIDs`/`onSelectionChange`, `reducedMotion: "settle"`, `seed`. Ref handle: `play`/`pause`/`step`/`reset`/`settle`, `previewResolve(taskID)`/`clearPreview` (ask "what would resolving this blocker unlock?" without editing data), `completeTask`/`blockTask`/`unblockTask`, `getAmplification`, `getMachineState`. Task completion is always an explicit data event — the simulation delivers prerequisites, it never decides done. Documented `serverChartConfigs` exclusion: the settled reading is an authored overlay over zero bodies, so the HOC SSR path is the supported static snapshot.
113
+ **ChainReactionChart** — dependency chain reaction. `data`, `taskIDAccessor`, `labelAccessor`, `laneAccessor`, `dependencyAccessor` (all required — edges are never inferred), plus optional `startAccessor`/`endAccessor`/`progressAccessor`/`statusAccessor`/`completionTimeAccessor`/`blockerAccessor`/`milestoneAccessor`. Tasks place by workstream lane × dependency depth; a completed task releases one delivery ball per outgoing edge and a downstream task arms only once every prerequisite ball arrives, so a blocked task's *reach* is the reading. `mode` ("snapshot" derives the settled state at `currentTime` with no simulation | "replay" animates deliveries over that same derived state | "mechanical"), `insight` ("blocker-amplification" reports unfinished downstream tasks + affected lanes), `controls` (play/pause/step/reset/settle), `selectedTaskIDs`/`onSelectionChange`, `reducedMotion: "settle"`, `seed`. Ref handle: `play`/`pause`/`step`/`reset`/`settle`, `previewResolve(taskID)`/`clearPreview` (ask "what would resolving this blocker unlock?" without editing data), `completeTask`/`blockTask`/`unblockTask`, `getAmplification`, `getMachineState`. Task completion is always an explicit data event — the simulation delivers prerequisites, it never decides done. `renderChart()` emits the authored task/dependency projection at `currentTime`, including blocker reach and selection; it deliberately omits arbitrary in-flight delivery-ball positions because those are replay state, not the chart's ledger.
112
114
  **Pop (body-removal burst)** — every physics HOC ref is a `PhysicsFrameHandle` (extends the shared push handle) exposing **`popBodies(ids, options?)`** (`StreamPhysicsPopOptions` = `{ color?, durationMs?, radius? }`): removes the bodies and plays a burst — expanding ring + inner glow + radial sparks fading over `durationMs` (`drawPopAnimations`) — returning the removed ids. It reads as a *departure*, the physics/exit-emphasis counterpart to realtime **`pulse`**'s data-*arrival* glow (the same transient-emphasis metaphor on opposite ends of a datum's life). GauntletChart also fires it internally on gate-driven property removal; `/examples/nimby` (civic-value balloons) and `/examples/merge-pressure` (merge-risk traits) drive it that way.
113
115
 
114
116
  ## Value Charts (`semiotic/value`)
@@ -135,7 +137,7 @@ Helpers exported: `buildFormatter`, `formatSignedDelta`, `formatDeltaPercent`, `
135
137
 
136
138
  Push API: `ref.current.push({time, value})`. All pushed data must include a time field.
137
139
 
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`).
140
+ **RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`; **stacked** via `categoryAccessor` + `colors` — bars sum by category within each bin; **mirrored/diverging** via `direction="down"` flipping the value domain — pair two halves with a shared `timeExtent`/`valueExtent` for an up/down detail view, and overlay extra instances on the same extent for layered envelopes), **TemporalHistogram** (static sibling — same props minus `windowSize`/`windowMode`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap** (+ sequential `colorScheme`; use `colorScheme="custom"` with `customColorScale(value)` for a custom ramp), **Streaming Sankey** (StreamNetworkFrame + `showParticles`). All six named realtime chart forms expose `styleRules`; aggregate histogram/heatmap rules resolve against displayed bins/cells rather than arbitrary source rows.
139
141
 
140
142
  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
143
 
@@ -147,6 +149,7 @@ Encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely.
147
149
 
148
150
  ### Push API on HOC charts
149
151
  Most HOCs support push via `forwardRef`. **Omit** `data` — do NOT pass `data={[]}`.
152
+ TypeScript: `RealtimeFrameHandle<TDatum, TReadDatum = TDatum>` preserves the authored row through `push`, `pushMany`, `remove`, `update`, and `getData`; omitting parameters retains the loose 3.x `Datum` contract. RealtimeLineChart aggregate mode accepts source `TDatum` but materializes `AggregatedRealtimeDatum`, exposed through `RealtimeLineChartHandle<TDatum, AggregatedRealtimeDatum>`.
150
153
  ```jsx
151
154
  const ref = useRef()
152
155
  ref.current.push({ id: "p1", x: 1, y: 2 })
@@ -173,12 +176,44 @@ When the catalog doesn't fit, four HOCs take a layout function emitting scene pr
173
176
  - **`NetworkCustomChart`** (`semiotic/network`) — flextree, dagre, custom force/radial, packed-cluster beeswarm matrix
174
177
  - **`GeoCustomChart`** (`semiotic/geo`) — isometric landmark boards, custom geographic tessellations
175
178
 
179
+ ### Built-in portable recipes
180
+
181
+ `ParallelCoordinatesRecipe` and `CalendarHeatmapRecipe` are the first custom
182
+ forms promoted into the serialized catalog. They are discoverable through
183
+ `suggestCharts`, `getSchema`, the CLI/MCP schema index, and the server renderer.
184
+ Their component names are serialization and rendering identifiers; React uses
185
+ the generic host rather than one-off HOCs:
186
+
187
+ ```jsx
188
+ import { ChartRecipe } from "semiotic/ai"
189
+
190
+ <ChartRecipe
191
+ recipeId="ParallelCoordinatesRecipe"
192
+ data={rows}
193
+ layoutConfig={{ fields: ["mpg", "power", "weight"], colorBy: "origin" }}
194
+ title="Vehicle profiles"
195
+ description="Vehicle profiles across independently scaled measures."
196
+ summary="No vehicle dominates every measure."
197
+ accessibleTable
198
+ />
199
+ ```
200
+
201
+ The serialized equivalent is
202
+ `{ component: "ParallelCoordinatesRecipe", props: { data, layoutConfig,
203
+ title, description, summary, accessibleTable: true } }`; substitute
204
+ `CalendarHeatmapRecipe` with `layoutConfig: { dateAccessor, valueAccessor,
205
+ year? }` for the calendar form. Both names work with `renderChart` and
206
+ `renderChartWithEvidence`. Import the raw `parallelCoordinatesLayout` or
207
+ `calendarLayout` from `semiotic/recipes` only for React-only callbacks or
208
+ bespoke frame control. `semiotic/ai/core` exposes their manifests and discovery
209
+ metadata without importing the chart renderer or layouts.
210
+
176
211
  Layout signature differs by family:
177
212
  - **XY/Ordinal**: `layout: (ctx) => { nodes, overlays? }`. `ctx`: `data`, `scales` ({x,y} XY | {o,r,projection} ordinal), `dimensions` (plot rect — center-anchored for radial ordinal, top-left otherwise), `theme`, `resolveColor(key)`, `config`.
178
- - **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays?, htmlMarks? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc/**symbol**/**glyph** nodes; line/bezier/curved edges). The `symbol` node is the per-datum **shape** channel — a `d3-shape` glyph (`circle`/`square`/`triangle`/`diamond`/`star`/`cross`/`wye`/`chevron`, or a custom `path`) sized by `size` (area), rendered on canvas + SVG/SSR and hit-tested + keyboard-navigated as a unit. **The `symbol` mark is cross-pipeline**: XY and ordinal custom layouts emit it too (`{type:"symbol", x, y, size, symbolType}` — note `x`/`y`, vs the network variant's `cx`/`cy`), and Scatterplot/SwarmPlot expose it as the `symbolBy` encoding. One shared `symbolPath` implementation backs canvas/SVG/hit-test across all three families.
213
+ - **Network**: `layout: (ctx) => { backgrounds?, sceneNodes?, sceneEdges?, labels?, overlays?, htmlMarks? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). `backgrounds` is plot-space SVG painted below the canvas/static scene (for fitted regions and enclosures); `overlays` paints above it. Both are included in SSR/static SVG and do not add hit targets. Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc/**symbol**/**glyph** nodes; line/bezier/curved edges). The `symbol` node is the per-datum **shape** channel — a `d3-shape` glyph (`circle`/`square`/`triangle`/`diamond`/`star`/`cross`/`wye`/`chevron`, or a custom `path`) sized by `size` (area), rendered on canvas + SVG/SSR and hit-tested + keyboard-navigated as a unit. **The `symbol` mark is cross-pipeline**: XY and ordinal custom layouts emit it too (`{type:"symbol", x, y, size, symbolType}` — note `x`/`y`, vs the network variant's `cx`/`cy`), and Scatterplot/SwarmPlot expose it as the `symbolBy` encoding. One shared `symbolPath` implementation backs canvas/SVG/hit-test across all three families.
179
214
  - **The `glyph` node — composite pictograms (ALL FOUR families incl. geo)**: where `symbol` is one path, `glyph` stamps a multi-part vector pictogram — a `GlyphDef` (`{viewBox?, anchor?, parts: [{d, fill?, stroke?, strokeWidth?, opacity?}]}`) whose parts declare **role paints** (`"color"`/`"accent"`/literal) resolved per node (`color`/`accent` props), so one definition recolors per category like a pictogram plate reused in many inks. `{type:"glyph", x, y, size, glyph, color?, accent?, fraction?, fractionStart?, fractionDirection?, ghostColor?, rotation?, style, datum, pointId?}` (network variant uses `cx`/`cy` + `id`/`label`). `size` = rendered **height** px (width follows viewBox aspect); `anchor: [0.5, 1]` stands a sign's feet on a baseline/terrain. **Partial fills**: `fraction`/`fractionStart` clip a `[start, end]` window (horizontal or bottom-up vertical) with an optional full-extent `ghostColor` silhouette — the ISOTYPE partial-symbol convention, fed directly by `unitize`. Full pipeline citizen: canvas + SVG/SSR, hit-test + keyboard nav over the drawn bounds, `pointId`/`id` annotation anchoring, and enter/move/exit transition identity (which `symbol` lacks). Datum-less glyph nodes (`datum: null`) paint but don't hit-test/navigate — use one `hitTarget` per logical mark under a multi-sign tally. `<Glyph def size color …/>` (from `semiotic/recipes`) renders the same definition as React SVG for overlays/legends/decoration; `glyphPlacement`/`glyphExtent` expose its geometry for layout math.
180
215
  - **Geo**: `layout: (ctx) => { nodes?, overlays? }`. `ctx`: `areas`, `points`, `lines`, fitted `GeoScales`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection`. Emit `geoarea`/`point`/`line`/`glyph` nodes; use overlays for labels and sprites.
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).
216
+ - **`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: `backgrounds` → 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).
182
217
 
183
218
  **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:
184
219
  - **`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.
@@ -196,6 +231,8 @@ Layout signature differs by family:
196
231
 
197
232
  `semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `intervalLanesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`, `netEnsembleLayout`, `axisFixedForceLayout`, `packedClusterMatrix`, `isometricLandmarkLayout`, `forceLayout`, `arcLayout`, `adjacencyMatrix`, `circularLayout`). **Network-analysis kit** (`semiotic/recipes`, pure graph algorithms): `buildAdjacency`, `bfsDistances`, `shortestPath`, `egoNetwork`, `degree`/`betweenness`(Brandes)/`closeness`/`clustering` (+ `normalizeScores`), `analyzeNetEnsemble` (the headless net census — see `netEnsembleLayout` below), and `proximityProblem` — the "spatial problem" layout diagnostic that flags nodes drawn closer than their graph distance warrants. Pair with network charts to size by centrality, highlight an ego network on hover, trace a shortest path, or diagnose a misleading layout. `forceLayout(nodes, edges, {seed})` is a **seeded, deterministic** positioner returning normalized `{id:{x,y}}` for `NetworkCustomChart` (same seed ⇒ same layout; re-seed for a "re-run the layout" interaction); `forceLayoutAsync(nodes, edges, {execution?, workerThreshold?, signal?})` is its Promise sibling that runs large layouts in a short-lived module Web Worker (identical deterministic output; graceful sync fallback), and `useForceLayout(nodes, edges, options)` → `{positions, status, error}` is the React wrapper — SSR and first hydration stay synchronous for markup parity, client graph changes go async while previous positions stay visible, and settled positions are memoized by node/edge array identity + options so remounting the same module-constant graph is "ready" immediately (no loading flash). `arcLayout`/`adjacencyMatrix`/`circularLayout` (+ `orderByGroupDegree`, `arcPath`) are the classic physics-free network forms. `allocateCells` is the largest-remainder grid allocator behind `waffleLayout` (turn `{key, weight}[]` + a cell count into integer cells with no rounding drift; `minPerCategory` keeps small categories visible) — reusable for any feature-mix / proportional waffle. **`unitize(value, {unit, maxUnits?, minFraction?})` / `unitizeRange(value, rangeValue, opts)`** is the counting sibling: the pictogram/tally allocator (value → repeated unit signs with a fractional final sign — ISOTYPE: symbols repeat, they never grow). Returns `{units: [{index, fraction, start, end, value}], total, shown, overflow}` — `maxUnits` caps with an `overflow` flag, `minFraction` drops trailing slivers while `total` vs `shown` keeps the ledger honest; `unitizeRange` extends the tally to a projected/scenario endpoint (`rangeUnits` drawn hatched), sharing a mid-sign boundary exactly via `startFraction`. Feeds `glyph`-node `fraction`s directly (unit charts, sign stacks, arrow bundles; `allocateCells` divides fixed cells, `unitize` counts). **Tokenized reasoning helpers**: `generateTokens(input, tokenEncoding)` wraps `unitize` plus `actual`, `fixed-denominator`, `quantile`, `posterior-sample`/`sample`, and seeded `random-sample` strategies with explicit `tokenType` (`dot`/`icon`/`glyph`), `tokenSemantics` (`observed-unit`, `unitized-measure`, `risk-case`, `possible-outcome`, etc.), and `countStrategy`; `{ value, rangeValue }` yields `rangeTokens` for scenario/projection tallies. `layoutTokenGrid` places the resulting tokens for icon/glyph arrays; `normalizeTokenEncoding` keeps legacy `token`/`unit` aliases working while canonical configs use `icon`/`unitValue`; `diagnoseTokenEncoding`, `suggestTokenEncoding`, and `tokenTaskIntentToCapabilityIntents` expose IDID-style warnings, task-aware defaults, and a bridge to `suggestCharts` intents. Built-in token glyph names include `person`, `server`, `chip`, `bolt`, and `bus`. `intervalLanesLayout` (ordinal) packs concurrent `{start,end,lane}` records into stacked Gantt sub-tracks per lane with period bands + lane labels + a time axis — packing runs in rendered-pixel space and honors `minBarWidth` (2) so zero/short-duration events stay visible without overlapping same-track neighbors; `axisFixedForceLayout` (network) pins one axis from a field and settles the other (rect-aware collision). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `packedClusterMatrix` (network) bins records into a column×row matrix of **densely-packed beeswarm clusters** (deterministic self-contained packing, geometry cached) and emits **multi-channel glyphs** — hue (`colorAccessor`/`colorMap`), size (`sizeAccessor`, area), shade (`shadeAccessor`, CIELAB lightness), plus EITHER shape-encoding (`symbolAccessor`/`symbolMap` — the base mark becomes that shape) OR the **composite-glyph** model (`iconAccessor`/`iconMap` — base is a filled circle, only mapped values get a stroked inner icon). `rowMode:"banded"` (default) gives aligned global orbit-bands (row labels align, one enclosure spans the columns per band, columns vary in height) vs `"stacked"` (per-column cell heights ∝ count). `callouts:[{field,value,label}]` draws leader lines to named marks. `cellSizing:"proportional"` makes area ∝ count. **Recipe decoration kit** (exported from `semiotic/recipes`, for any custom-layout's `overlays`): `roundedEnclosure`/`boundsOf` (group/band borders), `bandLabel` (overflow-aware axis/band labels), `markCallout` (leader-line callout to a mark), `readField` (`node.data`-wrapper reader), `groupBy`, `dimFor` (the highlight/dim opacity rule — `{predicate?, highlight?, baseOpacity?, dimOpacity?, brighten?}`; `matchesHighlight` is its `{field,value}[]` matcher), `signatureKey`/`LayoutCache` (content-signature geometry cache so re-styling never re-runs an expensive layout — key by *content*, never by `ctx.nodes` identity), `legendGroupsFrom` (`{colorMap|keys, symbolMap?, sizeStops?}` → `LegendGroup[]` for `frameProps.legend`), `shade`/`makeShade`, `symbolPathString`/`symbolRadius`/`symbolExtent`/`SYMBOL_SEQUENCE`, and the small numeric/color one-liners every layout re-declares — `clamp`, `mean`, `withAlpha`, `nonNegativeFinite` (hex→`rgba()` so a hover-dim can ride a recipe's `resolveColor` callback). (`bandLabel`/`dimFor` are adopted by marimekko/bullet/parallelCoordinates/packedClusterMatrix.) `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip decoration in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`). `netEnsembleLayout` (network) is the complement — for **ensembles of disconnected/trivially-connected DAGs** (a "bag of little graphs" force layout scatters and dagre/flextree can't place). It splits into weakly-connected components, tests each for **directedness** (borrowing the mathematical *net*/directed-set idea: for a weakly-connected DAG, a single sink ⟹ everything converges to one limit; ≥2 sinks ⟹ it branches), fingerprints components with Weisfeiler–Leman refinement so **order-isomorphic motifs** group together, lays each out converging toward its sink(s) at the bottom, and arranges the ensemble as small multiples in motif bands (collapsing to one census glyph per component when cells get tiny). Config: `colorMode` (`"directedness"|"motif"|"category"`), `groupByMotif`, `sort`, `fingerprintRounds`, `minCellForFull`. `analyzeNetEnsemble(nodes, edges)` is the pure headless census (per-component `directed`/sink/source counts + motif classes) with no rendering. Demo + lay explanation at `/recipes/net-ensemble`.
198
233
 
234
+ For fitted lineage regions, set `lineageDagLayout`'s `hullGroupAccessor` (for example, `"subtopologyId"`). It emits one sorted, deterministic convex hull per present group through `NetworkLayoutResult.backgrounds`, behind edges/nodes in live and static SVG. Optional controls: `hullColors`, `hullPadding` (16), `hullRadius` (12), `hullFillOpacity` (0.08), `hullStrokeOpacity` (0.4), and `hullLabel`. Omitting `hullGroupAccessor` emits no background layer.
235
+
199
236
  `tokenLayer({input, encoding, options})` is the high-level tokenized-rendering helper for custom layouts: it runs `generateTokens`, applies row/column/grid/waffle/dotplot/bar-segment/quantile-strip placement (or `positionToken` for scale/map-driven placement), and returns ordinary dot/symbol/glyph scene nodes with `pointId`/transition identity. Use it for ISOTYPE, icon arrays, risk grids, quantile dotplots, strips, and hybrid token overlays; pass `includeRange` to render `rangeTokens`; drop down to `generateTokens` when a bespoke layout only needs records.
200
237
 
201
238
  **Decoration (labels/axes/legends): the recipe owns it.** Recipes emit own decoration via `overlays` return field (ReactNode painted on top). Built-in axes via `showAxes` on the HOC work for layouts respecting the standard scale. Recipe convention: `showXxx` boolean toggles, `xxxFormat` callbacks. Shipped recipes' toggles: marimekko `showCategoryLabels`, bullet `showLabels`+`showTicks`, parallelCoordinates `showAxes`, flextree/dagre `showLabels`, waffle/calendar none.
@@ -417,9 +454,9 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
417
454
 
418
455
  **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.
419
456
 
420
- **Structured navigation** (Olli/Data-Navigator model): `buildNavigationTree(component, props, { maxLeaves?, locale? })` (from `semiotic/ai` or `semiotic/utils`) → a `NavTreeNode` tree (chart → axis/series → datum), labels composed via describeChart. When `props.annotations` is present it appends an **Annotations** branch (`role: "annotation"`) so a reader encounters author notes during traversal — provenance + M7 editorial `status` surfaced inline, retracted and superseded notes skipped, added on every family (incl. root-only network/geo/hierarchy). `describeChart` also leads its text with an annotation sentence when annotations are present. `AccessibleNavTree` (from `semiotic` or `semiotic/ai`) renders it as a WAI-ARIA `tree` widget (arrows/Enter/Home/End, roving tabindex, `onActiveChange`, controlled `activeId` auto-expands to the node, `chartId` for telemetry), sr-only by default. With the conversation-arc store enabled it emits `nav-node-focused`/`nav-branch-expanded` reception events on genuine traversal (not on canvas-driven `activeId` changes). `<ChartContainer navigable chartConfig={...}>` mounts it (`navigable={{ visible?, maxLeaves? }}`). Audit's `compromising.navigable-structure` passes when `navigable` is on (incl. hierarchy charts). Audit options: `auditAccessibility(component, props, { inChartContainer?, describe?, navigable? })`.
457
+ **Structured navigation** (Olli/Data-Navigator model): `buildNavigationTree(component, props, { maxLeaves?, locale? })` (from `semiotic/ai` or `semiotic/utils`) → a `NavTreeNode` tree (chart → axis/series → datum), labels composed via describeChart. Complex families retain their reading structure: network nodes are grouped with link/flow branches; hierarchy parents announce direct children, total descendants, leaf counts, and leaf-value rollups (including zero/negative values); ChoroplethMap announces numeric coverage/range/average/total and then groups ranked regions into equal-width highest/middle/lowest thirds of the observed numeric range plus a no-value branch; other geo forms separate locations from routes. Empty thirds are omitted and all-equal metrics receive one explicit branch. Caps produce branch-local omission nodes rather than silently truncating. When `props.annotations` is present it appends an **Annotations** branch (`role: "annotation"`) so a reader encounters author notes during traversal — provenance + M7 editorial `status` surfaced inline, retracted and superseded notes skipped. `describeChart` also leads its text with an annotation sentence when annotations are present. `AccessibleNavTree` (from `semiotic` or `semiotic/ai`) renders it as a WAI-ARIA `tree` widget (arrows/Enter/Home/End, roving tabindex, `onActiveChange`, controlled `activeId` auto-expands to the node, `chartId` for telemetry), sr-only by default. With the conversation-arc store enabled it emits `nav-node-focused`/`nav-branch-expanded` reception events on genuine traversal (not on canvas-driven `activeId` changes). `<ChartContainer navigable chartConfig={...}>` mounts it (`navigable={{ visible?, maxLeaves? }}`). Audit's `compromising.navigable-structure` passes when `navigable` is on (incl. hierarchy charts). Audit options: `auditAccessibility(component, props, { inChartContainer?, describe?, navigable? })`.
421
458
 
422
- **Bidirectional sync**: `useNavigationSync({ tree, chartId?, matchFields?, selectionName?, annotations? })` (from `semiotic` or `semiotic/ai`) → `{ activeId, onActiveChange, selection, annotatedIds, focusAnnotation }`. Tree→canvas highlights the matching mark (field-value selection); canvas→tree maps the hovered/clicked datum back to its leaf. Rides the module-global selection + observation stores — **no provider needed**: give the chart `chartId` + `selection={sync.selection}`, give `AccessibleNavTree` `activeId`/`onActiveChange`. **Annotation anchors**: pass the chart's `annotations` and an anchored annotation (carrying the datum's `matchFields`) resolves to a nav leaf — `annotatedIds` are the leaf ids with a note; `focusAnnotation(annotation | index)` jumps the tree + canvas to the anchored point so a non-visual reader can reach an AI's anchored note.
459
+ **Bidirectional sync**: `useNavigationSync({ tree, chartId?, matchFields?, selectionName?, annotations? })` (from `semiotic` or `semiotic/ai`) → `{ activeId, onActiveChange, selection, annotatedIds, focusAnnotation }`. Tree→canvas highlights the matching mark (field-value selection); canvas→tree maps the hovered/clicked datum back to any semantic node carrying that authored datum, including hierarchy parents. GeoJSON `properties` are normalized to the direct-field shape emitted by StreamGeoFrame, so region sync works without nested-path configuration. Rides the module-global selection + observation stores — **no provider needed**: give the chart `chartId` + `selection={sync.selection}`, give `AccessibleNavTree` `activeId`/`onActiveChange`. **Annotation anchors**: pass the chart's `annotations` and an anchored annotation (carrying the datum's `matchFields`) resolves to a datum node — `annotatedIds` are the node ids with a note; `focusAnnotation(annotation | index)` jumps the tree + canvas to the anchored point so a non-visual reader can reach an AI's anchored note.
423
460
 
424
461
  ## Usage Notes
425
462