semiotic 3.12.0 → 3.12.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 (256) hide show
  1. package/README.md +50 -46
  2. package/ai/artifact-surface-inventory.json +1 -1
  3. package/ai/behaviorContracts.cjs +1 -1
  4. package/ai/dist/diagnose-operation.js +3 -3
  5. package/ai/dist/mcp-server.js +1 -1
  6. package/ai/reference.md +15 -3
  7. package/ai/schema.json +908 -96
  8. package/ai/surface-manifest.json +1 -1
  9. package/ai/task-packets/compare-category-totals.json +5 -5
  10. package/ai/task-packets/compare-category-totals.md +2 -2
  11. package/ai/task-packets/correct-published-chart.json +5 -5
  12. package/ai/task-packets/correct-published-chart.md +2 -2
  13. package/ai/task-packets/index.json +6 -6
  14. package/ai/task-packets/update-live-chart.json +5 -5
  15. package/ai/task-packets/update-live-chart.md +2 -2
  16. package/dist/c-27DCB5T6.min.js +7 -7
  17. package/dist/c-2CKIGFD2.min.js +1 -1
  18. package/dist/c-3FATLOH4.min.js +1 -0
  19. package/dist/{c-STVM6CBI.min.js → c-4SCJKAWZ.min.js} +200 -200
  20. package/dist/c-5FUOKMH6.min.js +7 -0
  21. package/dist/c-AAIPWVQ5.min.js +6 -6
  22. package/dist/{c-2RG4WOVX.min.js → c-ALLF3Y77.min.js} +1 -1
  23. package/dist/{c-QMKQVCCZ.min.js → c-C5GXUHUO.min.js} +6 -6
  24. package/dist/c-C67QDKTU.min.js +34 -0
  25. package/dist/c-F76M77YC.min.js +1 -0
  26. package/dist/c-FEVXPKQH.min.js +1 -1
  27. package/dist/c-G42WVQO2.min.js +1 -0
  28. package/dist/c-G5A3YWTN.min.js +66 -0
  29. package/dist/c-H4HVKBU3.min.js +1 -0
  30. package/dist/c-HU3ASFKT.min.js +1 -0
  31. package/dist/c-I4FYCVJB.min.js +391 -0
  32. package/dist/{c-5L7JGWQW.min.js → c-IATPZOL7.min.js} +28 -28
  33. package/dist/c-IE5EBBP6.min.js +110 -0
  34. package/dist/c-IGONIKZL.min.js +1 -0
  35. package/dist/c-IKPM53JH.min.js +1 -0
  36. package/dist/c-IU4QZ7Y5.min.js +1 -1
  37. package/dist/{c-2ACLVPKF.min.js → c-K5VE57OI.min.js} +1 -1
  38. package/dist/c-KWJIBJ4R.min.js +1 -0
  39. package/dist/c-LIMFU6RD.min.js +1 -0
  40. package/dist/c-M4T43G76.min.js +1 -0
  41. package/dist/c-M7QUZZCE.min.js +1 -1
  42. package/dist/c-NVSINXE5.min.js +1 -0
  43. package/dist/{c-FAF6EV4E.min.js → c-NWRYV6ZF.min.js} +1 -1
  44. package/dist/c-O5GU2R5W.min.js +1 -0
  45. package/dist/c-OC7GNXGZ.min.js +1 -0
  46. package/dist/c-OV5F3DQP.min.js +1 -0
  47. package/dist/{c-5TAXHW7I.min.js → c-PJ5CAYAW.min.js} +1 -1
  48. package/dist/c-Q5LZRQGD.min.js +1 -0
  49. package/dist/c-QP3PXK3N.min.js +1 -0
  50. package/dist/c-SGZ7ZD2I.min.js +51 -0
  51. package/dist/c-SSKV5JPW.min.js +1 -1
  52. package/dist/c-THWTHWXU.min.js +37 -0
  53. package/dist/c-TRMNDRC4.min.js +41 -0
  54. package/dist/c-UP656CST.min.js +1 -1
  55. package/dist/c-USYOK5OX.min.js +1 -0
  56. package/dist/c-VI753KBO.min.js +1 -0
  57. package/dist/{c-TT4CTEBR.min.js → c-VLAAAFST.min.js} +1 -1
  58. package/dist/c-VSOQPII4.min.js +5 -5
  59. package/dist/c-WGDM4ZRP.min.js +26 -0
  60. package/dist/c-XCV7VUU3.min.js +87 -0
  61. package/dist/c-XGDZPYBI.min.js +1 -0
  62. package/dist/c-XI6CLZII.min.js +1 -0
  63. package/dist/{c-L4Q2YMXO.min.js → c-XLC7PKM7.min.js} +1 -1
  64. package/dist/{c-3YAGKCPU.min.js → c-YEB6Z35F.min.js} +1 -1
  65. package/dist/c-YWZBFG63.min.js +1 -0
  66. package/dist/c-ZMYO3NZU.min.js +2 -0
  67. package/dist/c-ZO36H5VH.min.js +48 -0
  68. package/dist/components/LinkedCharts.d.ts +6 -1
  69. package/dist/components/Tooltip/Tooltip.d.ts +11 -1
  70. package/dist/components/Tooltip/tooltipChrome.d.ts +8 -2
  71. package/dist/components/bundling/semioticVite.d.ts +24 -0
  72. package/dist/components/charts/physics/cruciblePhysics.d.ts +2 -2
  73. package/dist/components/charts/physics/gauntletPhysics.d.ts +2 -6
  74. package/dist/components/charts/physics/physicsHocUtils.d.ts +8 -1
  75. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +2 -0
  76. package/dist/components/charts/shared/chartSize.d.ts +58 -0
  77. package/dist/components/charts/shared/chartSizeDefaults.d.ts +189 -0
  78. package/dist/components/charts/shared/chartSizeDefaultsAtlas.d.ts +9 -0
  79. package/dist/components/charts/shared/chartSizeDefaultsNetwork.d.ts +29 -0
  80. package/dist/components/charts/shared/chartSizeDefaultsOrdinal.d.ts +13 -0
  81. package/dist/components/charts/shared/chartSizeDefaultsPhysics.d.ts +41 -0
  82. package/dist/components/charts/shared/chartSizeDefaultsValue.d.ts +19 -0
  83. package/dist/components/charts/shared/chartSizeDefaultsXY.d.ts +10 -0
  84. package/dist/components/charts/shared/networkPerspectiveWireSchema.d.ts +3 -0
  85. package/dist/components/charts/shared/useChartSetup.d.ts +3 -0
  86. package/dist/components/charts/shared/useCustomChartSetup.d.ts +4 -0
  87. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +2 -0
  88. package/dist/components/charts/shared/withChartWrapper.d.ts +6 -2
  89. package/dist/components/charts/value/BigNumber.d.ts +0 -8
  90. package/dist/components/charts/xy/minimapLayout.d.ts +10 -0
  91. package/dist/components/realtime/BinAccumulator.d.ts +5 -2
  92. package/dist/components/recipes/atlas/dependencyForestChartProps.d.ts +4 -4
  93. package/dist/components/recipes/atlas/flowCircuitChartProps.d.ts +177 -1
  94. package/dist/components/recipes/atlas/flowCircuitLayout.d.ts +3 -0
  95. package/dist/components/recipes/atlas/motifBraidChartProps.d.ts +2 -0
  96. package/dist/components/recipes/atlas/resolution/BoundaryLoomChart.d.ts +3 -0
  97. package/dist/components/recipes/atlas/resolution/ComponentCutaway.d.ts +16 -0
  98. package/dist/components/recipes/atlas/resolution/ResolutionAtlasChart.d.ts +3 -0
  99. package/dist/components/recipes/atlas/resolution/ResolutionGlyphs.d.ts +15 -0
  100. package/dist/components/recipes/atlas/resolution/ResolutionReader.d.ts +5 -0
  101. package/dist/components/recipes/atlas/resolution/appearance.d.ts +58 -0
  102. package/dist/components/recipes/atlas/resolution/boundaryLoomLayout.d.ts +4 -0
  103. package/dist/components/recipes/atlas/resolution/chartProps.d.ts +75 -0
  104. package/dist/components/recipes/atlas/resolution/componentCutawayLayout.d.ts +12 -0
  105. package/dist/components/recipes/atlas/resolution/cutawayContext.d.ts +23 -0
  106. package/dist/components/recipes/atlas/resolution/cutawayGraph.d.ts +4 -0
  107. package/dist/components/recipes/atlas/resolution/cycles.d.ts +7 -0
  108. package/dist/components/recipes/atlas/resolution/evidence.d.ts +43 -0
  109. package/dist/components/recipes/atlas/resolution/glyphs.d.ts +40 -0
  110. package/dist/components/recipes/atlas/resolution/identity.d.ts +4 -0
  111. package/dist/components/recipes/atlas/resolution/indexGraph.d.ts +32 -0
  112. package/dist/components/recipes/atlas/resolution/ownership.d.ts +25 -0
  113. package/dist/components/recipes/atlas/resolution/plan.d.ts +12 -0
  114. package/dist/components/recipes/atlas/resolution/ports.d.ts +44 -0
  115. package/dist/components/recipes/atlas/resolution/prepare.d.ts +4 -0
  116. package/dist/components/recipes/atlas/resolution/project.d.ts +70 -0
  117. package/dist/components/recipes/atlas/resolution/queries.d.ts +23 -0
  118. package/dist/components/recipes/atlas/resolution/resolutionAtlasLayout.d.ts +9 -0
  119. package/dist/components/recipes/atlas/resolution/rules.d.ts +14 -0
  120. package/dist/components/recipes/atlas/resolution/scene.d.ts +52 -0
  121. package/dist/components/recipes/atlas/resolution/selection.d.ts +3 -0
  122. package/dist/components/recipes/atlas/resolution/sets.d.ts +10 -0
  123. package/dist/components/recipes/atlas/resolution/types.d.ts +401 -0
  124. package/dist/components/recipes/atlas/resolution/validate.d.ts +4 -0
  125. package/dist/components/recipes/atlas/resolution/witnesses.d.ts +18 -0
  126. package/dist/components/recipes/atlas/resolution/worker.d.ts +34 -0
  127. package/dist/components/recipes/lineageDag.d.ts +4 -0
  128. package/dist/components/recipes/recipeUtils.d.ts +2 -0
  129. package/dist/components/recipes/transitDiagram.d.ts +2 -61
  130. package/dist/components/recipes/transitDiagramTypes.d.ts +65 -0
  131. package/dist/components/semiotic-ai.d.ts +2 -0
  132. package/dist/components/semiotic-experimental-network-resolution-react.d.ts +12 -0
  133. package/dist/components/semiotic-experimental-network-resolution.d.ts +13 -0
  134. package/dist/components/semiotic-geo.d.ts +1 -1
  135. package/dist/components/semiotic-network-perspective-core.d.ts +6 -0
  136. package/dist/components/semiotic-network.d.ts +1 -1
  137. package/dist/components/semiotic-ordinal.d.ts +1 -1
  138. package/dist/components/semiotic-physics.d.ts +1 -1
  139. package/dist/components/semiotic-realtime-core.d.ts +1 -1
  140. package/dist/components/semiotic-realtime-react.d.ts +2 -0
  141. package/dist/components/semiotic-utils-core.d.ts +3 -1
  142. package/dist/components/semiotic-vite.d.ts +2 -0
  143. package/dist/components/semiotic-xy.d.ts +3 -1
  144. package/dist/components/semiotic.d.ts +3 -1
  145. package/dist/components/server/renderToStaticSVG.d.ts +2 -1
  146. package/dist/components/server/serverChartConfigShared.d.ts +2 -0
  147. package/dist/components/store/LinkedCrosshairStore.d.ts +43 -11
  148. package/dist/components/store/themeCore.d.ts +2 -0
  149. package/dist/components/stream/frameKeyboardNavigation.d.ts +3 -1
  150. package/dist/components/stream/hoverUtils.d.ts +5 -0
  151. package/dist/components/stream/networkCustomLayout.d.ts +3 -0
  152. package/dist/components/stream/networkPerspective.d.ts +2 -0
  153. package/dist/components/stream/networkPerspectiveFit.d.ts +12 -1
  154. package/dist/components/stream/networkPerspectiveSolid.d.ts +1 -1
  155. package/dist/components/stream/networkSceneTypes.d.ts +4 -0
  156. package/dist/components/stream/networkTypes.d.ts +2 -0
  157. package/dist/components/stream/pipelineConfig.d.ts +2 -0
  158. package/dist/components/stream/pipelineDomainResolution.d.ts +4 -1
  159. package/dist/components/stream/types.d.ts +2 -0
  160. package/dist/components/stream/useFrame.d.ts +2 -0
  161. package/dist/components/stream/xySceneBuilders/types.d.ts +2 -0
  162. package/dist/controls.module.min.js +31 -31
  163. package/dist/geo.min.js +150 -150
  164. package/dist/geo.module.min.js +31 -31
  165. package/dist/network.module.min.js +1 -1
  166. package/dist/ordinal.module.min.js +1 -1
  167. package/dist/physics.module.min.js +1 -1
  168. package/dist/rough.module.min.js +1 -1
  169. package/dist/semiotic-ai-core.min.js +1 -1
  170. package/dist/semiotic-ai-core.module.min.js +1 -1
  171. package/dist/semiotic-ai.d.ts +2 -0
  172. package/dist/semiotic-ai.module.min.js +13 -13
  173. package/dist/semiotic-artifact-react.module.min.js +4 -4
  174. package/dist/semiotic-artifact.min.js +1 -1
  175. package/dist/semiotic-artifact.module.min.js +1 -1
  176. package/dist/semiotic-atlas-selection.module.min.js +1 -1
  177. package/dist/semiotic-atlas.module.min.js +10 -12
  178. package/dist/semiotic-client-cjs-shared.min.js +1078 -925
  179. package/dist/semiotic-client-glyph.module.min.js +2 -2
  180. package/dist/semiotic-client-shared.module.min.js +1 -1
  181. package/dist/semiotic-experimental-auxiliary.module.min.js +8 -9
  182. package/dist/semiotic-experimental-network-resolution-react.d.ts +12 -0
  183. package/dist/semiotic-experimental-network-resolution-react.min.js +2 -0
  184. package/dist/semiotic-experimental-network-resolution-react.module.min.js +89 -0
  185. package/dist/semiotic-experimental-network-resolution.d.ts +13 -0
  186. package/dist/semiotic-experimental-network-resolution.min.js +2 -0
  187. package/dist/semiotic-experimental-network-resolution.module.min.js +2 -0
  188. package/dist/semiotic-experimental-node-auxiliary.module.min.js +9 -10
  189. package/dist/semiotic-geo.d.ts +1 -1
  190. package/dist/semiotic-line.module.min.js +1 -1
  191. package/dist/semiotic-network-perspective-core.d.ts +6 -0
  192. package/dist/semiotic-network-perspective-core.min.js +1 -0
  193. package/dist/semiotic-network-perspective-core.module.min.js +1 -0
  194. package/dist/semiotic-network-perspective.module.min.js +1 -1
  195. package/dist/semiotic-network-placement.min.js +4 -0
  196. package/dist/semiotic-network-placement.module.min.js +4 -0
  197. package/dist/semiotic-network-zoom.module.min.js +1 -1
  198. package/dist/semiotic-network.d.ts +1 -1
  199. package/dist/semiotic-ordinal.d.ts +1 -1
  200. package/dist/semiotic-physics.d.ts +1 -1
  201. package/dist/semiotic-realtime-core.d.ts +1 -1
  202. package/dist/semiotic-realtime-core.module.min.js +1 -1
  203. package/dist/semiotic-realtime-react.d.ts +2 -0
  204. package/dist/semiotic-realtime-react.module.min.js +1 -1
  205. package/dist/semiotic-recipes-core-cjs-base.min.js +101 -106
  206. package/dist/semiotic-recipes-core.module.min.js +75 -76
  207. package/dist/semiotic-server-edge-node.module.min.js +391 -392
  208. package/dist/semiotic-server-edge.min.js +387 -388
  209. package/dist/semiotic-server-edge.module.min.js +371 -371
  210. package/dist/semiotic-server-node.min.js +387 -388
  211. package/dist/semiotic-server-node.module.min.js +1 -1
  212. package/dist/semiotic-utils-core.d.ts +3 -1
  213. package/dist/semiotic-utils-core.min.js +12 -11
  214. package/dist/semiotic-utils-core.module.min.js +12 -11
  215. package/dist/semiotic-value.module.min.js +4 -4
  216. package/dist/semiotic-vite.d.ts +2 -0
  217. package/dist/semiotic-vite.min.js +1 -0
  218. package/dist/semiotic-vite.module.min.js +1 -0
  219. package/dist/semiotic-xy.d.ts +3 -1
  220. package/dist/semiotic.d.ts +3 -1
  221. package/dist/semiotic.module.min.js +12 -12
  222. package/dist/server.min.js +387 -388
  223. package/dist/server.module.min.js +1 -1
  224. package/dist/xy.module.min.js +1 -1
  225. package/package.json +42 -13
  226. package/dist/c-2AB65V3L.min.js +0 -1
  227. package/dist/c-2U5JMOPN.min.js +0 -88
  228. package/dist/c-3DCTIRW4.min.js +0 -1
  229. package/dist/c-3OKFRTYM.min.js +0 -1
  230. package/dist/c-3VZHOPFW.min.js +0 -1
  231. package/dist/c-4ZSQIBC7.min.js +0 -1
  232. package/dist/c-5M4RUS7V.min.js +0 -34
  233. package/dist/c-6O5WWP7F.min.js +0 -1
  234. package/dist/c-73TOIYIW.min.js +0 -48
  235. package/dist/c-AE4M7BWH.min.js +0 -1
  236. package/dist/c-AEIK2NFW.min.js +0 -30
  237. package/dist/c-AFQSEIZ4.min.js +0 -4
  238. package/dist/c-BBX7DVVB.min.js +0 -51
  239. package/dist/c-CNYFCSG4.min.js +0 -5
  240. package/dist/c-E6QH2WYE.min.js +0 -1
  241. package/dist/c-GOMQWQJR.min.js +0 -1
  242. package/dist/c-GTYG4PDT.min.js +0 -1
  243. package/dist/c-H23GIKTK.min.js +0 -1
  244. package/dist/c-HQLUUSRJ.min.js +0 -1
  245. package/dist/c-HXUOFDSD.min.js +0 -64
  246. package/dist/c-L3LKYOLK.min.js +0 -1
  247. package/dist/c-MIKDFGKH.min.js +0 -1
  248. package/dist/c-OYSPTIAG.min.js +0 -1
  249. package/dist/c-PWPJNYQP.min.js +0 -1
  250. package/dist/c-QZ5SWKHC.min.js +0 -392
  251. package/dist/c-RXJH4IRX.min.js +0 -41
  252. package/dist/c-SN2D6QMH.min.js +0 -1
  253. package/dist/c-U5YGK6HL.min.js +0 -1
  254. package/dist/c-VIN5ASK2.min.js +0 -37
  255. package/dist/c-XZ3GASUJ.min.js +0 -1
  256. package/dist/c-ZLZZTH4I.min.js +0 -118
package/ai/reference.md CHANGED
@@ -10,7 +10,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
10
10
  - Install: `npm install semiotic`
11
11
  <!-- semiotic-bundle-sizes:start -->
12
12
  <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
13
- - **Use sub-path imports** — `semiotic/atlas` (300KB gz), `semiotic/atlas/core` (14KB gz), `semiotic/access` (29KB gz), `semiotic/evidence` (45KB gz), `semiotic/artifact` (123KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (143KB gz), `semiotic/xy` (182KB gz), `semiotic/ordinal` (135KB gz), `semiotic/network` (176KB gz), `semiotic/network/zoom` (182KB gz), `semiotic/network/perspective` (2KB gz), `semiotic/geo` (111KB gz), `semiotic/realtime` (209KB gz), `semiotic/realtime/core` (208KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (263KB gz), `semiotic/server/node` (263KB gz), `semiotic/server/edge` (271KB gz), `semiotic/utils` (104KB gz), `semiotic/utils/core` (96KB gz), `semiotic/utils/react` (8KB gz), `semiotic/recipes` (114KB gz), `semiotic/recipes/core` (112KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (11KB gz), `semiotic/themes/core` (11KB gz), `semiotic/themes/react` (7KB gz), `semiotic/data` (5KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (170KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (641KB gz), `semiotic/ai/core` (140KB gz), `semiotic/controls` (18KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (2KB gz). Full `semiotic` is 419KB gz.
13
+ - **Use sub-path imports** — `semiotic/atlas` (303KB gz), `semiotic/atlas/core` (14KB gz), `semiotic/access` (29KB gz), `semiotic/evidence` (45KB gz), `semiotic/artifact` (123KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (145KB gz), `semiotic/xy` (184KB gz), `semiotic/ordinal` (136KB gz), `semiotic/network` (178KB gz), `semiotic/network/zoom` (184KB gz), `semiotic/network/perspective` (2KB gz), `semiotic/network/perspective/core` (3KB gz), `semiotic/vite` (1KB gz), `semiotic/geo` (112KB gz), `semiotic/realtime` (211KB gz), `semiotic/realtime/core` (210KB gz), `semiotic/realtime/react` (2KB gz), `semiotic/server` (265KB gz), `semiotic/server/node` (265KB gz), `semiotic/server/edge` (274KB gz), `semiotic/utils` (107KB gz), `semiotic/utils/core` (98KB gz), `semiotic/utils/react` (8KB gz), `semiotic/recipes` (114KB gz), `semiotic/recipes/core` (113KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (11KB gz), `semiotic/themes/core` (11KB gz), `semiotic/themes/react` (8KB gz), `semiotic/data` (5KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (172KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (643KB gz), `semiotic/ai/core` (140KB gz), `semiotic/controls` (18KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (2KB gz). Full `semiotic` is 422KB 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
 
@@ -20,6 +20,9 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
20
20
  ## Common Props (chart HOCs only)
21
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
+ **Resolved chart size**: `resolveChartSize(chartName, props)` from `semiotic/utils` or `semiotic/utils/core` returns the same viewport dimensions the chart uses: mode defaults, chart-specific primary sizes, explicit dimensions, supported `size` aliases, and responsive rules. Supply `containerSize: { width, height }` for measured responsive axes; without it, responsive axes return their initial fallback. Minimap includes its overview, ScatterplotMatrix reports its field/cell grid (excluding outside title/legend), and BigNumber retains CSS sizes including undefined for auto-sized inline content. `emptyContent`/`loadingContent` reserve the resolved chart slot, follow responsive sizing, and stretch custom content across the available width while centering its text.
24
+
25
+
23
26
  This list is not global. Plain value components do not inherit chart-HOC props and must be
24
27
  validated against their own schema. In particular, `BigNumber` uses `label`, `description`, and
25
28
  `summary`; it does not accept `title` or `accessibleTable`.
@@ -92,6 +95,11 @@ ProcessSankey time values (`domain`, edge times, node lifetimes, and axis tick d
92
95
 
93
96
  All network (every HOC above, plus `NetworkCustomChart` and `StreamNetworkFrame`): `perspective` ("flat" default; see below).
94
97
 
98
+ Projection integration: import `NetworkPerspectiveGround`, `NetworkPerspectiveBillboard`, `resolveNetworkPerspective`, `createNetworkPerspectiveFrame`, `getNetworkPerspectiveSize`, and `useNetworkPerspective` from `semiotic/network/perspective/core` for a narrow entry point. `getNetworkPerspectiveSize(perspective, [groundWidth, groundHeight], bounds?)` returns the screen plot size at scale 1, including thickness and fit padding; add margins and keep the layout's ground dimensions fixed. Supply bounds for token radii, elevations and overhanging chrome that the helper cannot infer. `fit: "contain"` only shrinks and is required by this helper for projected views (it is the default); the helper throws `RangeError` for `fit: "none"` because origin-based placement cannot guarantee contained bounds. Flat sizing remains unchanged. `lineageDagLayout` accepts `showArrowheads: false` and `chromePlacement: "upright" | "ground"` (default upright); `transitDiagramLayout` accepts the same chrome placement and `stationBounds(info) => [left, right, top, bottom]` for custom glyph extents. Upright lineage cards participate in fitting automatically. `perspective.tokenRim: "flat"` merges token rim facets for lighter SVG; the default is `"faceted"`. SVG postprocessors can select `data-perspective-part` roles (`edge`, `edge-shadow`, `node-shadow`, `elevation-guide`, `slab-top`, `slab-face`, `token-top`, `token-rim`, `ground-grid`, `plate-top/face/outline`, `region-top/face/outline`); parse standard SVG path syntax rather than depending on spacing. Affine matrix coefficients retain at least eight decimals even with lower static coordinate precision.
99
+
100
+ All three `semiotic/atlas` readers accept `perspective`: MotifBraidChart, DependencyForestChart and FlowCircuitChart. Flow Circuit projects the same fixed apparatus and tape readings with a network renderer; `networkFrameProps` configures that projected frame, while `frameProps` configures its flat physics frame. Top-level `bodyId` annotations anchor to the same module in both views, including static SVG; an explicit `pointId` takes precedence. Use `semioticVite()` from `semiotic/vite` in Vite 7 builds to delete unreferenced Semiotic worker assets while preserving referenced external URLs. It recognizes standard worker filenames (optionally content-hashed); Vite 8 already avoids the unused assets.
101
+
102
+
95
103
  **Network perspective** (`perspective`) — parallel (axonometric/oblique) projection applied **after** layout. Layout coordinates and data semantics never change; switching perspectives rebuilds the scene, not the layout. The prop is `perspective`, not `projection` (geo charts use `projection` for d3 map projections). Presets: `"flat"` (default, identity), `"isometric"` (true 30°, depth ratio 0.577), `"pixel"` (2:1), `"dimetric"`, `"military"` (plan-oblique; ground shapes preserved), `"cabinet"` (oblique front view). Config object: `type` ("isometric"), `rotation`, `tilt` (1–90), `verticalScale`, `origin`, `fit` ("contain" default — scales down, never up, and centers; or "none"), `fitPadding` (12), `elevation`, `elevationScale` ("auto" maps the largest value to 48px), `elevationGuides`, `depthSort` (true), `thickness` (6 layout px; 0 draws flat pieces), `edgeShadow` (true | `{ color, opacity }`; needs thickness > 0), `marks` ("token"|"billboard"|"ground"|"extrude"|fn), `anchor` ("center"|"feet"), `glyph`, `glyphSize`, `extrude` (24), `extrudeScale`, `edges: { route: "layout"|"orthogonal"|"orthogonal-rounded", elevation: "surface" (default: ends attach to the plate/ground their node stands on)|"nodes"|"ground"|number }`, `labels: { mode: "upright"|"ground", axis: "x"|"y" }`, `ground: { grid, plate }`, `regions: [{ id, label, nodes, bounds, padding, fill, stroke, elevation, depth, labelColor }]`, `transition` (boolean | `{ duration }`, 600ms; reduced motion is instant). Every piece has thickness: point marks (circles, symbols) default to `"token"` — discs or symbols lying on the ground at their pixel size with a shaded rim; `marks: "billboard"` keeps them upright; pictogram glyphs always stand as billboards. Area marks (sankey/treemap/partition rects, chord arcs, CirclePack circles) lie on the ground as slabs with shaded side walls, and Treemap/CirclePack levels stack on their parent's top surface. Edges and bands are projected one thickness above the surface their nodes stand on and cast a soft shadow onto it (`edgeShadow: false` removes it). Plates and regions default to the same thickness. Node-anchored labels keep their screen offset; `labels.mode: "ground"` rotates text along a ground axis. `elevation` (field name, constant px, or React callback) is the one added data encoding, drawn with dashed drop lines and ground shadows. `marks: "extrude"` turns leaf rects (e.g. Treemap leaves) into shaded prisms; containers stay on the ground. `regions` draw plates (optionally raised/thick) under member node ids and seat those members on the plate top; regions are chrome (no hit test or tooltip). Hit testing, tooltips, keyboard focus, `pointId` annotations, the accessible table, the zoom camera (`viewTransform`), and SSR follow the projected marks. Custom layouts: `ctx.perspective` is the active config or null; returned `sceneNodes`/`sceneEdges`/`labels`/`htmlMarks` are projected automatically; an HTML mark whose `id` matches a scene node or its datum follows that node's elevation (the top surface for solid pieces), preserving its screen offset and dimensions; otherwise its center can anchor to a coincident node, with unmatched marks placed at piece height; `backgrounds`/`overlays` stay in plot space unless the layout result sets `perspective: "ground"` (all on the ground) or `"manual"` with per-element placement: `<NetworkPerspectiveGround z>` lays flat geometry on the ground (`z="top"` = piece height, where edges ride — use it for arrowheads), `<NetworkPerspectiveBillboard x y z onGround?>` moves upright content (node cards, badges, edge labels) with its anchor, or lays it flat at pixel size with `onGround`; unwrapped content (legends) stays flat; decorations that reach past the scene marks are declared in `perspectiveBounds` (ground boxes `{ x, y, width, height, z? }` or upright `{ x, y, extent: [left, right, top, bottom], z? }`) so the fit keeps them in the plot; both are identity on flat charts, and a dev warning fires once when a projected layout returns decorations with neither mode; overlay components call `useNetworkPerspective()` for the fitted frame (`project(x, y, z)`, `unproject`, `groundTransform`, `billboardTransform`, `thickness`). Built-in network recipes (lineageDag, dagre, mermaidDag — solid pieces under a perspective — netEnsemble, packedClusterMatrix, transitDiagram, adjacencyFlow, dependencyForest, GoFish) already place their decorations. Ground grid/plate, regions, orthogonal routing, and extrusion ("perspective extras") load on demand in browsers and repaint when ready; `renderToStaticSVG`/`renderChart`/MCP render them synchronously; call `preloadNetworkPerspectiveExtras()` before hydrating server-rendered charts that use them. `semiotic/network` also exports `resolveNetworkPerspective`, `createNetworkPerspectiveFrame`, `projectNetworkScene`, and the `NetworkPerspective*` types. Opt-in `semiotic/network/perspective`: `isometricGlyphs` (`box`, `server`, `database`, `cylinder`, `tile`, `cloud`, `pin`) for `perspective.glyph`, builders `isoBox`/`isoStack`/`isoCylinder`/`isoTile`/`isoCloud`/`isoPin` (glyphs follow the node color), and `PerspectiveToggle` (accessible radiogroup: `value`, `onChange`, `options`). JSON/MCP configs use the string or object form; function `elevation`/`extrude`/`marks` and `glyph`/`glyphSize` are React-only. Use it for categorical or topological positions (architecture diagrams, lineage/DAGs, org trees, matrices); avoid it when position encodes a measured quantity. It is a parallel projection on the existing canvas/SVG renderers, not 3D or WebGL. See `/features/perspective`.
96
104
 
97
105
  ## Geo Charts (`semiotic/geo`)
@@ -152,6 +160,8 @@ Push API: `ref.current.push({time, value})`. All pushed data must include a time
152
160
 
153
161
  **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.
154
162
 
163
+ Temporal histograms accept `binAlign="start"` (default) or `binAlign="center"`. Center uses a zero-anchored grid whose bins span `[timestamp - binSize/2, timestamp + binSize/2)`, so samples on grid timestamps sit at bar centers. Automatic centered extents include full first/last bins; explicit `timeExtent` remains authoritative and clips partial bins. Aggregation, stacking, bin hover data, selection coverage, and brush snapping use the same shifted boundaries.
164
+
155
165
  Temporal histograms support native `responsiveWidth` / `responsiveHeight` (definite parent height required), `showTimeAxis` / `showValueAxis`, and shared XY `axes` configs with `visible: false`. Hidden axes reserve no default margin; explicit margins win. Other XY HOCs use `frameProps.axes`. For mirrored histograms, use shared ascending time/value extents and side margins, hide the upper time axis, set the lower top margin to zero, and use `direction="down"` below. Match plot heights, allowing extra outer height for the lower time axis. Realtime downward orientation also follows pushed data.
156
166
 
157
167
  Histogram `linkedHover={{ name: "detail", mode: "field", fields: ["time", "category"] }}` emits bin fields or source-row values for absent bin fields. A LineChart with `selection={{ name: "detail" }}` dims nonmatching series, and `showPoints` dims nonmatching observations. Line field hover publishes the hovered row's fields; x-position crosshairs require explicit `mode: "x-position"`. Bin `onHover` receives `{ data: { binStart, binEnd, total, category? }, ... }` or null; `onObservation` emits standard hover/hover-end events. See the realtime histogram docs' linked/mirrored example.
@@ -366,7 +376,7 @@ or geo custom charts; a server renderer cannot read a browser's selection store.
366
376
  Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`. Works for `NetworkCustomChart` too — the resolved selection predicate is threaded into the custom layout as `ctx.selection`.
367
377
  **`useSelectionActions(name)`** — write-only access (`selectPoints`/`clear`) that does NOT subscribe to selection state, so a *container* can push a selection (e.g. from a hover handler) without re-rendering; only the leaf consumers reading the selection re-render. The provider-at-top / consumers-at-leaves pattern for interaction-heavy coordinated views.
368
378
  **Shared categories inside LinkedCharts:** generated colors keep charts without an explicit palette consistent. A child's `colorScheme` overrides those generated defaults; wrap in `CategoryColorProvider` to explicitly assign shared category colors above each child's palette. LinkedCharts builds its unified legend from resolved chart colors. If charts use different colors for the same category, it retains individual legends instead.
369
- **Linked crosshair**: `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}`. Click locks crosshair (dashed white); click/Escape unlocks.
379
+ **Linked crosshair**: `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}`. Click locks the crosshair; click/Escape unlocks. Read or update hover/lock state from tables via `useLinkedCrosshair("sync")` (exported from `semiotic/ai`, `semiotic/xy`, and `semiotic/realtime`): `{ position, setPosition }`, where position is `{ xValue, sourceId, locked? } | null`. `setPosition({ xValue, locked: true })` sets a lock; `setPosition(null)` clears it. Omitted sourceId means external ownership and displays on every linked chart. For controlled React state, pass `<LinkedCharts crosshair={{ name: "sync", position, onPositionChange: setPosition }}>`; null controls an inactive position, undefined retains internal state. Changes from charts and hooks request state through the callback; supplied props remain authoritative and do not emit echo callbacks. Internal hover is ignored while locked. LinkedCharts scopes names to its own dashboard; controlled positions remain owned by the parent when a chart unmounts.
370
380
  **Linked series highlight** (series↔bar cross-highlight): `linkedHover={{ name: "sync", mode: "series" }}` auto-resolves the chart's series-identity field (colorBy/lineBy/areaBy/stackBy/groupBy) and keys the linked selection off it — no hand-wired `fields`. Add `seriesField: "region"` to override (align charts whose series live under different prop names). Modes are exclusive: `mode` is `"field"` (default) | `"x-position"` (crosshair) | `"series"`.
371
381
  **CircularBrush** — accessible range brush over a **cyclical** domain (day-of-year, hour, compass): `value` ({start,end}) / `onChange` (value | updater) / `period` (365) / `radius` / `step`+`largeStep` / `formatValue` / `arcFill`/`stroke` / `onObservation`+`controlId`+`chartId`. Wrap-around ranges, pointer-capture drag, and full keyboard control (each handle + the range is a `role="slider"` with a visible focus ring, ←/→ nudges, Shift or PageUp/PageDown = `largeStep`, Home/End = first/last step). Pointer and keys snap to `step` (default 1 for an integer period ≥ 2, else `period / 100`), so fractional cycles such as a phase (`period: 1`) or half-hours (`period: 24, step: 0.5`) work; `aria-valuemax` is the last step before the wrap. `onObservation` receives `control-start`/`control-change`/`control-end` with `[start, end]` values (`controlType: "range-boundary"`). The radial counterpart to the linear `RealtimeHistogram` brush. **Control-surface contract**: it takes value/domain/geometry/`onChange` and never reaches into a chart — layer it over a chart sharing its coordinate space and feed `onChange` into your state (or the selection store). Built on the cyclical + radial kit.
372
382
  **LinearBrush** (`semiotic/controls` only) — accessible one-dimensional range brush for any track: controlled `value` or uncontrolled `defaultValue` (`[start, end] | null`), `onChange(value, meta)` on every change and `onChangeEnd(value, meta)` once per release or keyboard step (`meta`: `source`, `mode`, `changed`, `atDomainStart`/`atDomainEnd`). Map with `domain` or the chart's own `scale`; `orientation` "x"/"y" (minimum at the bottom); overlay a chart's plot with `inset` (its margins). Drag an end to resize, the selection to move, the background to create (`allowCreate`), click to clear (`clearOnBackgroundClick`); `minSpan`, `snap` to `step`, `resetOnDoubleClick`/`resetValue`, `emptySelection: "full-extent"` (handles at the domain ends when empty). Styling: `selectionStyle`/`activeSelectionStyle`, `maskStyle` (dim outside), `handleStyle`/`activeHandleStyle`, `renderHandle(ctx)` (HTML at the edge; `ctx.active`/`dragging`/`focused`), `showMoveHandle`. Labels: `showExtentLabels`, `showDomainLabels`, `formatValue` (a `\n` makes two lines; also `aria-valuetext`), flipping inward at `labelBounds`. A `role="group"` with three `role="slider"`s (start, range, end): arrows step, Shift/PageUp/PageDown `largeStep`, Home/End limits, Escape clears; emits `control-start`/`control-change`/`control-end` observations (`range-boundary`). Themed through the ThemeProvider CSS variables (`colors.selection`, else `primary`), no store; positions are fractions, so it is responsive and SSR-stable.
@@ -527,7 +537,7 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
527
537
  - **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.
528
538
  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.
529
539
  - **Tooltip behavior needs browser evidence** (`interaction.tooltip-content-and-verification`): Interactive charts keep useful tooltips unless omission is intentional. tooltip=false or an empty callback result (null/undefined, booleans, whitespace-only strings, empty arrays/fragments) suppresses the entire tooltip; numeric zero remains visible. Suppression is independent of hover observations and selection. Verify actual content and placement in a browser; do not silently disable tooltips to avoid a defect.
530
- Agent action: Use the documented callback shape: custom/network chart tooltip callbacks receive authored data, while frameProps.tooltipContent receives a hover wrapper (unwrapDatum once). Handle node and edge records separately. Prefer default/configured tooltips or TooltipRoot for custom chrome. Use markTooltipChrome(renderer) when a callback owns chrome through wrapper components; leave plain renderers unmarked. Wrapping libraries should call the exported hasTooltipContent on consumer results before adding elements. Hover a real mark and an edge when interactive; assert expected labels/values, one readable tooltip, no empty box or clipping after zoom/pan and resize, and disappearance on leave. Test tooltip=false and null-returning renderers without disabling enableHover when observations or selection are required. An inspector or a mount-only test does not establish tooltip behavior.
540
+ Agent action: Use the documented callback shape: custom/network chart tooltip callbacks receive authored data, while frameProps.tooltipContent receives a hover wrapper (unwrapDatum once). Handle node and edge records separately. Prefer default/configured tooltips or TooltipRoot for custom chrome. Use tooltip={{ content: renderer, chrome: "none" }} when consumer content owns chrome through wrapper components, or theme.tooltip.chrome: "none" for a shared policy. Config content receives authored data, with multi-series context when present. markTooltipChrome(renderer) remains supported; leave plain renderers unmarked. Wrapping libraries should call the exported hasTooltipContent on consumer results before adding elements. Hover a real mark and an edge when interactive; assert expected labels/values, one readable tooltip, no empty box or clipping after zoom/pan and resize, and disappearance on leave. Test tooltip=false and null-returning renderers without disabling enableHover when observations or selection are required. An inspector or a mount-only test does not establish tooltip behavior.
531
541
  - **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.
532
542
  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.
533
543
  - **Categorical color precedence** (`color.category-precedence`): When colorBy is set, explicit CategoryColorProvider mappings, including those inherited through LinkedCharts, win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback. Generated LinkedCharts colors do not override a child's colorScheme.
@@ -595,6 +605,8 @@ Chart live regions announce keyboard focus without announcing pointer hover acro
595
605
  - **Tooltip datum shape**: Custom/network chart `tooltip` callbacks get raw authored node/edge data (for example, `d.label`, not `d.data.label`). Frame `tooltipContent` gets a hover wrapper — use `unwrapDatum(hover)` once from `semiotic/utils` or `semiotic/recipes`, including the extra built-in network wrapper. Check the documented signature for legacy realtime callbacks. Handle nodes and edges separately.
596
606
  - **Tooltip suppression and verification**: `tooltip={false}` disables the whole tooltip; return `null` from a callback to omit a particular datum. Keep `enableHover` when observations or selection still need it. Custom content gets shared chrome; use `TooltipRoot` to own it explicitly, or `markTooltipChrome(renderer)` when a callback owns chrome through wrappers. Wrapping libraries should call `hasTooltipContent(result)` before adding elements; nullish values, booleans, whitespace-only strings, and recursively empty arrays/fragments suppress the tooltip. Do not substitute an inspector for expected hover behavior or silently disable tooltips. Browser-test actual values, bounds after zoom/pan/resize, dismissal, and absence of empty boxes. Static rendering and mount-only tests cannot verify this.
597
607
  - **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}]})`. FunnelChart and GaugeChart also apply `valueFormat` inside their bespoke default tooltips. Histogram and LikertChart keep their own tooltip formatting; customize those via `tooltip`. Formatters are React callbacks, not string-valued JSON props.
608
+ - **Tooltip chrome**: `tooltip={{ content: d => <ConsumerTooltip datum={d} />, chrome: "none" }}` explicitly leaves the visual surface to the consumer without marking/mutating the renderer. Config `content` receives authored data (or histogram bin data), including `allSeries`/`xValue` when present. Custom multi configs also accept `chrome`. Field configs (`{ fields, title, chrome }`) and `TooltipRoot chrome="none"` honor explicit policy. Set `<ThemeProvider theme={{ tooltip: { chrome: "none" } }}>` to apply the default to custom renderers across charts, including raw frame callbacks. An explicit chart chrome setting overrides the theme. Existing `markTooltipChrome`, element markers, and inline ownership detection remain supported. Empty content still suppresses the entire tooltip.
609
+
598
610
  - **`tooltip="multi"`** / **`tooltip={{ mode: "multi", content? }}`**: multi-series hover-anywhere for LineChart, AreaChart, StackedAreaChart, DifferenceChart (wires `tooltipMode:"multi"`). RealtimeHistogram/TemporalHistogram multi lists every stacked category in the hovered bin (anywhere in the column; empty bins show nothing); other realtime, ordinal, network, geo, and physics charts fall back to one datum. Built-in multi renderer when `content` is omitted. Custom multi: `tooltip={{ mode: "multi", content: (d) => … }}` — the function receives the unwrapped raw datum with hover-root `allSeries` / `xValue` re-attached (`{group, value, valuePx, color, datum}` entries; an ungrouped series has `group: ""`). In x-extent padding outside the data, rows and `xValue` snap to the first/last sample; keyboard focus gets the same rows. Legacy escape hatch: `tooltip={fn}` + `frameProps={{ tooltipMode: "multi" }}`.
599
611
  - **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).
600
612
  - **Horizontal bars**: need wider left margin (`margin={{ left: 120 }}`).