semiotic 3.10.2 → 3.10.4

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 (118) hide show
  1. package/README.md +21 -26
  2. package/ai/artifact-surface-inventory.json +1 -1
  3. package/ai/behaviorContracts.cjs +15 -5
  4. package/ai/behaviorContracts.d.cts +3 -0
  5. package/ai/cli.js +17 -166
  6. package/ai/componentMetadata.cjs +68 -15
  7. package/ai/componentMetadata.d.cts +3 -0
  8. package/ai/dist/diagnose-operation.js +3 -0
  9. package/ai/dist/mcp-server.js +59 -59
  10. package/ai/reference.md +6 -6
  11. package/ai/schema.json +1 -1
  12. package/ai/surface-manifest.json +1 -1
  13. package/ai/system-prompt.md +2 -2
  14. package/ai/task-packets/compare-category-totals.json +7 -7
  15. package/ai/task-packets/compare-category-totals.md +3 -3
  16. package/ai/task-packets/correct-published-chart.json +7 -7
  17. package/ai/task-packets/correct-published-chart.md +3 -3
  18. package/ai/task-packets/index.json +6 -6
  19. package/ai/task-packets/update-live-chart.json +7 -7
  20. package/ai/task-packets/update-live-chart.md +3 -3
  21. package/dist/c-2MHSD3TN.min.js +209 -0
  22. package/dist/{c-PZ3NEGNG.min.js → c-6XGGN5OS.min.js} +1 -1
  23. package/dist/{c-FDUQDCBC.min.js → c-CO4NDAD6.min.js} +23 -23
  24. package/dist/c-EK6XI2U7.min.js +26 -0
  25. package/dist/c-FMCUQ6JX.min.js +1 -0
  26. package/dist/{c-C4KIXUWU.min.js → c-GK263BF4.min.js} +1 -1
  27. package/dist/{c-TTKWXGAI.min.js → c-HNHKIMIV.min.js} +3 -3
  28. package/dist/c-IJCZGUG6.min.js +31 -0
  29. package/dist/{c-4XLHPQTP.min.js → c-JBWPJNTJ.min.js} +1 -1
  30. package/dist/{c-4MD53L2J.min.js → c-JC76YAHB.min.js} +28 -28
  31. package/dist/{c-VXIYF7V2.min.js → c-JOPGDP6N.min.js} +1 -1
  32. package/dist/c-KWP4QTCM.min.js +4 -0
  33. package/dist/c-LRV7PO45.min.js +393 -0
  34. package/dist/c-LVHJJUOF.min.js +1 -0
  35. package/dist/c-M43PK7K4.min.js +1 -0
  36. package/dist/c-NUBZ63VU.min.js +1 -0
  37. package/dist/{c-7ASK4WBF.min.js → c-PITYSOPK.min.js} +1 -1
  38. package/dist/{c-2TW5H5PD.min.js → c-QPO24R7Q.min.js} +1 -1
  39. package/dist/{c-SG2Y7EBY.min.js → c-RWHLEUX6.min.js} +1 -1
  40. package/dist/{c-4JKDJUYD.min.js → c-S746GRV4.min.js} +1 -1
  41. package/dist/{c-KGROWFT2.min.js → c-SAP5KY6R.min.js} +2 -2
  42. package/dist/c-UMGHCBH5.min.js +114 -0
  43. package/dist/c-UQBWSYKI.min.js +41 -0
  44. package/dist/{c-6ZU3QVLB.min.js → c-VEMCBQZZ.min.js} +33 -33
  45. package/dist/{c-IPYGNVN6.min.js → c-WD2RL76M.min.js} +45 -45
  46. package/dist/{c-PQOZPM4G.min.js → c-YL7HJL5J.min.js} +1 -1
  47. package/dist/c-Z6GRGS53.min.js +1 -0
  48. package/dist/components/CategoryColors.d.ts +7 -0
  49. package/dist/components/LinkedCharts.d.ts +2 -1
  50. package/dist/components/ai/chartClinic.d.ts +1 -1
  51. package/dist/components/ai/chartClinicMetadata.generated.d.ts +2 -2
  52. package/dist/components/charts/shared/{chartDefinitionPilot.d.ts → chartDefinition.d.ts} +30 -34
  53. package/dist/components/charts/shared/chartDefinitions.d.ts +10 -0
  54. package/dist/components/charts/shared/chartDefinitionsNetwork.d.ts +17 -0
  55. package/dist/components/charts/shared/chartDefinitionsOrdinal.d.ts +23 -0
  56. package/dist/components/charts/shared/chartDefinitionsPhysics.d.ts +17 -0
  57. package/dist/components/charts/shared/chartDefinitionsRealtime.d.ts +12 -0
  58. package/dist/components/charts/shared/chartDefinitionsXY.d.ts +26 -0
  59. package/dist/components/charts/shared/useChartSetup.d.ts +1 -1
  60. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +1 -1
  61. package/dist/components/data/transforms.d.ts +1 -0
  62. package/dist/components/server/serverChartConfigs.d.ts +36 -36
  63. package/dist/components/server/serverChartConfigsNetwork.generated.d.ts +17 -0
  64. package/dist/components/server/serverChartConfigsOrdinal.generated.d.ts +23 -0
  65. package/dist/components/server/serverChartConfigsPhysics.generated.d.ts +17 -0
  66. package/dist/components/server/serverChartConfigsRealtime.generated.d.ts +13 -0
  67. package/dist/components/server/serverChartConfigsXY.generated.d.ts +22 -0
  68. package/dist/components/stream/physics/PhysicsOptionalEngineAdapters.d.ts +5 -0
  69. package/dist/geo.min.js +3 -3
  70. package/dist/geo.module.min.js +10 -10
  71. package/dist/network.module.min.js +1 -1
  72. package/dist/ordinal.module.min.js +1 -1
  73. package/dist/physics-matter.min.js +4 -1
  74. package/dist/physics-matter.module.min.js +1 -1
  75. package/dist/physics-rapier.min.js +4 -1
  76. package/dist/physics-rapier.module.min.js +1 -1
  77. package/dist/physics.module.min.js +1 -1
  78. package/dist/physicsWorker.js +1 -1
  79. package/dist/semiotic-ai-core.min.js +3 -3
  80. package/dist/semiotic-ai-core.module.min.js +3 -3
  81. package/dist/semiotic-ai.module.min.js +7 -7
  82. package/dist/semiotic-artifact.min.js +1 -1
  83. package/dist/semiotic-artifact.module.min.js +1 -1
  84. package/dist/semiotic-atlas-selection.module.min.js +1 -1
  85. package/dist/semiotic-client-cjs-shared.min.js +903 -902
  86. package/dist/semiotic-data.min.js +1 -1
  87. package/dist/semiotic-data.module.min.js +1 -1
  88. package/dist/semiotic-experimental-auxiliary.module.min.js +3 -3
  89. package/dist/semiotic-experimental-node-auxiliary.module.min.js +3 -3
  90. package/dist/semiotic-experimental-vacp.module.min.js +1 -1
  91. package/dist/semiotic-line.module.min.js +1 -1
  92. package/dist/semiotic-realtime-core.module.min.js +1 -1
  93. package/dist/semiotic-recipes-core-cjs-base.min.js +1 -1
  94. package/dist/semiotic-recipes-core.module.min.js +13 -13
  95. package/dist/semiotic-server-edge-node.module.min.js +393 -391
  96. package/dist/semiotic-server-edge.min.js +393 -391
  97. package/dist/semiotic-server-edge.module.min.js +374 -372
  98. package/dist/semiotic-server-node.min.js +393 -391
  99. package/dist/semiotic-server-node.module.min.js +1 -1
  100. package/dist/semiotic-utils-core.min.js +1 -1
  101. package/dist/semiotic-utils-core.module.min.js +1 -1
  102. package/dist/semiotic.module.min.js +10 -10
  103. package/dist/server.min.js +393 -391
  104. package/dist/server.module.min.js +1 -1
  105. package/dist/xy.module.min.js +1 -1
  106. package/package.json +12 -8
  107. package/dist/c-3OFVBWQY.min.js +0 -1
  108. package/dist/c-6IVBV5NO.min.js +0 -1
  109. package/dist/c-72CBVNYX.min.js +0 -209
  110. package/dist/c-7LY46QUI.min.js +0 -41
  111. package/dist/c-AKLBQMQF.min.js +0 -391
  112. package/dist/c-F2GGJB2S.min.js +0 -31
  113. package/dist/c-G53AVC42.min.js +0 -113
  114. package/dist/c-HQ27AHMC.min.js +0 -1
  115. package/dist/c-IHWZ2C6D.min.js +0 -26
  116. package/dist/c-MOP2NGLH.min.js +0 -1
  117. package/dist/c-PKY4JFY5.min.js +0 -1
  118. package/dist/c-UBHICVSC.min.js +0 -1
package/README.md CHANGED
@@ -26,24 +26,19 @@ evidence scope; source availability does not establish installed or deployed par
26
26
  <img src="./docs/public/assets/img/semiotic-release-dashboard.svg" alt="Semiotic release dashboard showing chart count, bundle sizes, capability coverage, chart families, and documentation growth" width="100%">
27
27
  <!-- semiotic-readme-dashboard:end -->
28
28
 
29
- ## What's New in 3.10.2
29
+ ## What's New in 3.10.4
30
30
 
31
- 3.10.2 improves realtime aggregation, stream chart recommendations, server
32
- rendering, and line labels.
31
+ 3.10.4 improves consumer bundler compatibility, optional physics engine loading,
32
+ and AI chart-data validation.
33
33
 
34
- - Stream recommendations cover ordinal and value charts, with audience-aware
35
- dashboard layouts and explanations for excluded candidates.
36
- - Realtime charts support keyed changelogs, percentile and distinct-count
37
- aggregates, per-series line aggregation, and more controlled-data SSR paths.
38
- - Event-time queues, incremental aggregates, and smaller validation imports
39
- reduce repeated work and bundle overhead.
40
- - LineChart direct labels share measured placement across browser and server
41
- rendering; keyed path transitions preserve point identity during updates.
34
+ - Worker bundles and dynamic imports preserve the hints consumer bundlers need.
35
+ - Matter and Rapier optional peers use bundler-resolvable imports, and Rapier
36
+ initialization waits for its WASM runtime.
37
+ - AI validation distinguishes omitted push-mode data from invalid static data;
38
+ generated schemas retain nested constraints.
39
+ - A new compatibility gate checks packed installs in webpack, Rspack, and Vite.
42
40
 
43
- Stream suggestion callers should now destructure the result:
44
- `const { suggestions } = suggestStreamCharts(...)`.
45
-
46
- See [the changelog](CHANGELOG.md#3102---2026-09-18) for details.
41
+ See [the changelog](CHANGELOG.md#3104---2026-09-22) for details.
47
42
 
48
43
  ## Why Semiotic
49
44
 
@@ -416,7 +411,7 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
416
411
  | `semiotic/ordinal` | **128 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
417
412
  | `semiotic/network` | **148 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
418
413
  | `semiotic/geo` | **106 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
419
- | `semiotic/realtime` | **163 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
414
+ | `semiotic/realtime` | **164 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
420
415
  | `semiotic/realtime/core` | **162 KB** | Streaming chart types, HOCs, and buffer helpers |
421
416
  | `semiotic/realtime/react` | **1 KB** | Stream status and synced push hooks |
422
417
  | `semiotic/server` | **243 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
@@ -431,7 +426,7 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
431
426
  | `semiotic/themes` | **11 KB** | Theme presets only (tufte, carbon, etc.) |
432
427
  | `semiotic/themes/core` | **11 KB** | Theme presets and token helpers |
433
428
  | `semiotic/themes/react` | **6 KB** | ThemeProvider/useTheme and hooks |
434
- | `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
429
+ | `semiotic/data` | **4 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
435
430
  | `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
436
431
  | `semiotic/physics` | **164 KB** | GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart |
437
432
  | `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
@@ -465,9 +460,9 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
465
460
  | `import { MotifBraidChart } from "semiotic/atlas"` | browser | **159.5 KiB** |
466
461
  | `import { prepareNetworkAtlas } from "semiotic/atlas/core"` | browser | **6.2 KiB** |
467
462
  | `import { LineChart } from "semiotic"` | browser | **145.1 KiB** |
468
- | `import { LineChart } from "semiotic/xy"` | browser | **145.5 KiB** |
469
- | `import { LineChart } from "semiotic/line"` | browser | **145.3 KiB** |
470
- | `import { BarChart } from "semiotic/ordinal"` | browser | **133.1 KiB** |
463
+ | `import { LineChart } from "semiotic/xy"` | browser | **145.6 KiB** |
464
+ | `import { LineChart } from "semiotic/line"` | browser | **145.4 KiB** |
465
+ | `import { BarChart } from "semiotic/ordinal"` | browser | **133.2 KiB** |
471
466
  | `import { SankeyDiagram } from "semiotic/network"` | browser | **154.9 KiB** |
472
467
  | `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **147.9 KiB** |
473
468
  | `import { RingBuffer } from "semiotic/realtime/core"` | browser | **0.7 KiB** |
@@ -475,17 +470,17 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
475
470
  | `import { GaltonBoardChart } from "semiotic/physics"` | browser | **147.4 KiB** |
476
471
  | `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.2 KiB** |
477
472
  | `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** |
478
- | `import { renderChart } from "semiotic/server"` | node | **277.4 KiB** |
479
- | `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **142.2 KiB** |
480
- | `import { renderToImage } from "semiotic/server/node"` | node | **278.3 KiB** |
481
- | `import { suggestCharts } from "semiotic/ai"` | browser | **255.4 KiB** |
473
+ | `import { renderChart } from "semiotic/server"` | node | **277.7 KiB** |
474
+ | `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **141.0 KiB** |
475
+ | `import { renderToImage } from "semiotic/server/node"` | node | **278.5 KiB** |
476
+ | `import { suggestCharts } from "semiotic/ai"` | browser | **255.7 KiB** |
482
477
  | `import { suggestCharts } from "semiotic/ai/core"` | browser | **39.1 KiB** |
483
478
  | `import { buildArtifactContract } from "semiotic/artifact"` | browser | **13.0 KiB** |
484
479
  | `import { ArtifactInspector } from "semiotic/artifact/react"` | browser | **3.8 KiB** |
485
480
  | `import { createChartAccessContract } from "semiotic/access"` | browser | **27.0 KiB** |
486
481
  | `import { toEvidenceEnvelope } from "semiotic/evidence"` | browser | **42.3 KiB** |
487
482
  | `import { bin } from "semiotic/data"` | browser | **0.4 KiB** |
488
- | `import { ChoroplethMap } from "semiotic/geo"` | browser | **115.9 KiB** |
483
+ | `import { ChoroplethMap } from "semiotic/geo"` | browser | **116.0 KiB** |
489
484
  | `import { usePretextAnnotations } from "semiotic/text"` | browser | **1.5 KiB** |
490
485
  | `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.1 KiB** |
491
486
  | `import { resolveThemePreset } from "semiotic/themes"` | browser | **2.6 KiB** |
@@ -500,7 +495,7 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
500
495
  | `import { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** |
501
496
  | `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.3 KiB** |
502
497
 
503
- **Line-boundary interpretation:** the retained named import from `semiotic/line` emits 434.5 KiB raw versus 434.5 KiB from `semiotic/xy`; gzip differs by 0.2 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat `semiotic/line` as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.
498
+ **Line-boundary interpretation:** the retained named import from `semiotic/line` emits 434.7 KiB raw versus 434.7 KiB from `semiotic/xy`; gzip differs by 0.2 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat `semiotic/line` as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.
504
499
 
505
500
  <!-- semiotic-cold-consumer:end -->
506
501
 
@@ -107,7 +107,7 @@
107
107
  "src/components/store/selectionProvenance.ts"
108
108
  ],
109
109
  "inventoryVersion": 1,
110
- "repositoryVersion": "3.10.2",
110
+ "repositoryVersion": "3.10.4",
111
111
  "relations": [
112
112
  {
113
113
  "id": "claim-support",
@@ -113,7 +113,15 @@ const REQUIRED_COMBINATIONS = [
113
113
  },
114
114
  ]
115
115
 
116
+ // Charts covered by the common omitted-data/ref contract. This is not the
117
+ // complete push-capability inventory: FlowMap, ProcessSankey, and BigNumber
118
+ // have their own input surfaces rather than a generic data prop.
116
119
  const PUSH_MODE_COMPONENTS = [
120
+ "RealtimeLineChart",
121
+ "RealtimeHistogram",
122
+ "RealtimeSwarmChart",
123
+ "RealtimeWaterfallChart",
124
+ "RealtimeHeatmap",
117
125
  "LineChart",
118
126
  "AreaChart",
119
127
  "StackedAreaChart",
@@ -122,6 +130,8 @@ const PUSH_MODE_COMPONENTS = [
122
130
  "ConnectedScatterplot",
123
131
  "CandlestickChart",
124
132
  "MultiAxisLineChart",
133
+ "Heatmap",
134
+ "WaterfallChart",
125
135
  "QuadrantChart",
126
136
  "DifferenceChart",
127
137
  "BarChart",
@@ -137,6 +147,8 @@ const PUSH_MODE_COMPONENTS = [
137
147
  "DonutChart",
138
148
  "LikertChart",
139
149
  "SwimlaneChart",
150
+ "FunnelChart",
151
+ "RadarChart",
140
152
  "ForceDirectedGraph",
141
153
  "SankeyDiagram",
142
154
  "ChordDiagram",
@@ -149,8 +161,6 @@ const PUSH_MODE_COMPONENTS = [
149
161
  "PacketFlowChart",
150
162
  "ProcessFlowChart",
151
163
  "GauntletChart",
152
- "CrucibleChart",
153
- "ChainReactionChart",
154
164
  ]
155
165
 
156
166
  const STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema()
@@ -196,7 +206,7 @@ const BEHAVIOR_CONTRACTS = [
196
206
  appliesTo: {
197
207
  propsAny: ["colorBy", "colorScheme"],
198
208
  },
199
- summary: "When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.",
209
+ summary: "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.",
200
210
  agentAction: "Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution.",
201
211
  },
202
212
  {
@@ -251,8 +261,8 @@ const BEHAVIOR_CONTRACTS = [
251
261
  title: "renderChart uses static props only",
252
262
  severity: "warning",
253
263
  appliesTo: {},
254
- summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.",
255
- agentAction: "Use renderChart only with renderable HOC components and complete static data. For live behavior, return React code with a ref and do not promise MCP-rendered output.",
264
+ summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot, never future ref pushes. semiotic/server accepts bounded data for realtime charts; MCP rendering excludes the five live Realtime components but includes TemporalHistogram.",
265
+ agentAction: "Use complete static data for snapshots. For a Realtime component snapshot, use semiotic/server directly; for live behavior, return React code with a ref and do not promise MCP-rendered output.",
256
266
  },
257
267
  {
258
268
  id: "serialization.formatters-are-react-callbacks",
@@ -0,0 +1,3 @@
1
+ /** CommonJS metadata; consumers narrow to the contract they use. */
2
+ declare const behaviorContracts: unknown
3
+ export = behaviorContracts
package/ai/cli.js CHANGED
@@ -4,6 +4,8 @@
4
4
  const fs = require("fs")
5
5
  const path = require("path")
6
6
 
7
+ const { diagnoseChart } = require("./dist/diagnose-operation.js")
8
+
7
9
  const pkgRoot = path.resolve(__dirname, "..")
8
10
  const {
9
11
  CATEGORY_ORDER,
@@ -20,7 +22,6 @@ const {
20
22
  behaviorContractsFor,
21
23
  dataRequiredForUsageMode,
22
24
  formatDoctorBehaviorContracts,
23
- normalizeUsageMode
24
25
  } = require("./behaviorContracts.cjs")
25
26
 
26
27
  const FILES = {
@@ -144,136 +145,15 @@ function printSingleComponentSchema(componentName) {
144
145
  console.log(JSON.stringify(payload, null, 2))
145
146
  }
146
147
 
147
- // Both helpers are only called from `validatePropsWithSchema` below, which
148
- // filters `undefined` / `null` out of `value` before reaching them — so
149
- // neither guards null here. CodeQL flags the dead branches if they return.
150
-
151
- function schemaTypeMatches(value, expectedType) {
152
- const expectedTypes = Array.isArray(expectedType)
153
- ? expectedType
154
- : [expectedType]
155
- return expectedTypes.some((type) => {
156
- if (type === "array") return Array.isArray(value)
157
- if (type === "object")
158
- return typeof value === "object" && !Array.isArray(value)
159
- return typeof value === type
160
- })
161
- }
162
-
163
- function describeActualType(value) {
164
- if (Array.isArray(value)) return "array"
165
- return typeof value
166
- }
167
-
168
- function shouldSkipMissingRequiredProp(componentName, propName, usageMode) {
169
- return (
170
- propName === "data" && !dataRequiredForUsageMode(componentName, usageMode)
171
- )
172
- }
173
-
174
- function filterUsageModeErrors(componentName, errors, usageMode) {
175
- if (dataRequiredForUsageMode(componentName, usageMode)) return errors
176
- return errors.filter(
177
- (err) => err !== `"data" is required for ${componentName}.`
178
- )
179
- }
180
-
181
- function validatePropsWithSchema(componentName, props, usageMode = "static") {
182
- const schema = loadSchema()
183
- const component = findComponent(schema, componentName)
184
- if (!component) {
185
- const available = schemaEntries(schema)
186
- .map((entry) => entry.name)
187
- .sort()
188
- .join(", ")
189
- return {
190
- valid: false,
191
- errors: [
192
- `Unknown component "${componentName}". Available components: ${available}`
193
- ]
194
- }
195
- }
196
-
197
- const parameters = component.parameters || {}
198
- const properties = parameters.properties || {}
199
- const required = parameters.required || []
200
- const errors = []
201
-
202
- for (const propName of required) {
203
- if (shouldSkipMissingRequiredProp(component.name, propName, usageMode))
204
- continue
205
- if (props[propName] === undefined || props[propName] === null) {
206
- errors.push(`"${propName}" is required for ${component.name}.`)
207
- }
208
- }
209
-
210
- // Array-shape charts that declare a `data` schema prop need it in static
211
- // usage even when "data" isn't in `required` (those lists hold semantic
212
- // accessors). Without this, --doctor passed dataless static CandlestickChart /
213
- // MultiAxisLineChart / QuadrantChart / DifferenceChart / SwimlaneChart /
214
- // LikertChart configs that render blank. dataRequiredForUsageMode is true for
215
- // them in static and false in push, mirroring the MCP diagnoseConfig path.
216
- if (
217
- "data" in properties &&
218
- !required.includes("data") &&
219
- dataRequiredForUsageMode(component.name, usageMode) &&
220
- (props.data === undefined || props.data === null)
221
- ) {
222
- errors.push(`"data" is required for ${component.name}.`)
223
- }
224
-
225
- for (const [propName, value] of Object.entries(props)) {
226
- if (value === undefined || value === null) continue
227
- const propSchema = properties[propName]
228
- if (!propSchema) {
229
- errors.push(`Unknown prop "${propName}" for ${component.name}.`)
230
- continue
231
- }
232
-
233
- // Prefer the full runtime type surface (`x-semiotic-runtime-types`, e.g.
234
- // ["string","function"]) over the wire-only `type` ("string"), so a valid
235
- // function value for a prop like `colorBy`/`onBrush` is still accepted. The
236
- // wire `type` keyword is standards-valid JSON Schema and never lists
237
- // "function"; the runtime extension carries it. Falls back to `type` for
238
- // props with no runtime-only alternatives.
239
- const effectiveType =
240
- propSchema["x-semiotic-runtime-types"] || propSchema.type
241
- if (effectiveType && !schemaTypeMatches(value, effectiveType)) {
242
- const expected = Array.isArray(effectiveType)
243
- ? effectiveType.join(" | ")
244
- : effectiveType
245
- errors.push(
246
- `"${propName}" should be ${expected}, got ${describeActualType(value)}.`
247
- )
248
- }
249
-
250
- if (
251
- propSchema.enum &&
252
- typeof value === "string" &&
253
- !propSchema.enum.includes(value)
254
- ) {
255
- errors.push(
256
- `"${propName}" value "${value}" is not valid. Expected one of: ${propSchema.enum.join(", ")}.`
257
- )
258
- }
259
- }
260
-
261
- return {
262
- valid: errors.length === 0,
263
- errors
264
- }
265
- }
266
-
267
148
  // Returns true when the schema-only validation passed, so the caller can set
268
149
  // the process exit code (nonzero on failure — this is a CI gate).
269
- function printSchemaOnlyDoctorResult(component, props, usageMode) {
270
- const result = validatePropsWithSchema(component, props, usageMode)
150
+ function printSchemaOnlyDoctorResult(component, props, usageMode, result) {
271
151
  if (usageMode === "push") {
272
152
  console.log(
273
153
  ` Usage mode: push (data prop may be omitted; use a ref to push data)`
274
154
  )
275
155
  }
276
- if (result.valid) {
156
+ if (result.ok) {
277
157
  console.log(`✓ ${component}: schema-only validation passed.`)
278
158
  } else {
279
159
  console.log(`✗ ${component}: schema-only validation failed.`)
@@ -282,7 +162,7 @@ function printSchemaOnlyDoctorResult(component, props, usageMode) {
282
162
  }
283
163
  }
284
164
  printDoctorBehaviorContracts(component, props)
285
- return result.valid
165
+ return result.ok
286
166
  }
287
167
 
288
168
  function printDoctorBehaviorContracts(component, props) {
@@ -541,7 +421,6 @@ if (flag === "--doctor") {
541
421
  else console.error(msg)
542
422
  process.exit(1)
543
423
  }
544
- const usageMode = normalizeUsageMode(rawUsageMode)
545
424
 
546
425
  // Load diagnoseConfig from dist (falls back to validateProps, then schema.json)
547
426
  const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
@@ -557,44 +436,18 @@ if (flag === "--doctor") {
557
436
  // packaged schema so the CLI still catches basic agent mistakes.
558
437
  }
559
438
 
560
- // Tracks whether the doctor found any error-level problem. The process
561
- // MUST exit nonzero when this is false so CI/agents can gate on it.
562
- let ok
563
-
564
- if (!diagnoseConfig && !validateProps) {
565
- if (asJson) {
566
- const result = validatePropsWithSchema(component, props, usageMode)
567
- ok = result.valid
568
- console.log(
569
- JSON.stringify(
570
- {
571
- component,
572
- usageMode,
573
- mode: "schema-only",
574
- ok,
575
- errors: result.errors
576
- },
577
- null,
578
- 2
579
- )
580
- )
581
- } else {
582
- ok = printSchemaOnlyDoctorResult(component, props, usageMode)
583
- }
584
- } else if (diagnoseConfig) {
585
- // Use the full anti-pattern detector
586
- const result = diagnoseConfig(component, props)
587
- const diagnoses =
588
- usageMode === "push"
589
- ? result.diagnoses.filter(
590
- (d) =>
591
- d.code !== "VALIDATION" ||
592
- !shouldSkipMissingRequiredProp(component, "data", usageMode) ||
593
- d.message !== `"data" is required for ${component}.`
594
- )
595
- : result.diagnoses
596
- ok = diagnoses.every((d) => d.severity === "warning")
439
+ const report = diagnoseChart(
440
+ { component, props, usageMode: rawUsageMode },
441
+ { diagnoseConfig, validateProps },
442
+ loadSchema
443
+ )
444
+ const { usageMode, ok } = report
597
445
 
446
+ if (report.mode === "schema-only") {
447
+ if (asJson) console.log(JSON.stringify(report, null, 2))
448
+ else printSchemaOnlyDoctorResult(component, props, usageMode, report)
449
+ } else if (report.mode === "diagnose") {
450
+ const { diagnoses } = report
598
451
  if (asJson) {
599
452
  console.log(
600
453
  JSON.stringify(
@@ -638,9 +491,7 @@ if (flag === "--doctor") {
638
491
  }
639
492
  } else {
640
493
  // Fallback to validateProps only
641
- const result = validateProps(component, props)
642
- const errors = filterUsageModeErrors(component, result.errors, usageMode)
643
- ok = errors.length === 0
494
+ const { errors } = report
644
495
  if (asJson) {
645
496
  console.log(
646
497
  JSON.stringify(
@@ -3,34 +3,86 @@
3
3
  const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "physics", "value", "recipe"]
4
4
 
5
5
  const COMPONENTS_BY_CATEGORY = {
6
+ // BEGIN GENERATED XY CHARTS
6
7
  xy: [
7
- "LineChart", "BumpChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
8
- "MultiAxisLineChart", "CandlestickChart", "BubbleChart", "Heatmap",
9
- "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "WaterfallChart",
8
+ "LineChart",
9
+ "BumpChart",
10
+ "AreaChart",
11
+ "DifferenceChart",
12
+ "StackedAreaChart",
13
+ "Scatterplot",
14
+ "BubbleChart",
15
+ "Heatmap",
16
+ "QuadrantChart",
17
+ "MultiAxisLineChart",
18
+ "WaterfallChart",
19
+ "CandlestickChart",
20
+ "ConnectedScatterplot",
21
+ "ScatterplotMatrix",
22
+ "MinimapChart"
10
23
  ],
24
+ // END GENERATED XY CHARTS
25
+ // BEGIN GENERATED ORDINAL CHARTS
11
26
  ordinal: [
12
- "BarChart", "StackedBarChart", "LikertChart", "GroupedBarChart", "SwarmPlot",
13
- "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart",
14
- "DonutChart", "GaugeChart", "FunnelChart", "RadarChart", "SwimlaneChart",
27
+ "BarChart",
28
+ "StackedBarChart",
29
+ "GroupedBarChart",
30
+ "SwarmPlot",
31
+ "BoxPlot",
32
+ "Histogram",
33
+ "ViolinPlot",
34
+ "RidgelinePlot",
35
+ "DotPlot",
36
+ "PieChart",
37
+ "DonutChart",
38
+ "GaugeChart",
39
+ "FunnelChart",
40
+ "RadarChart",
41
+ "SwimlaneChart",
42
+ "LikertChart"
15
43
  ],
44
+ // END GENERATED ORDINAL CHARTS
45
+ // BEGIN GENERATED NETWORK CHARTS
16
46
  network: [
17
- "MotifBraidChart", "DependencyForestChart",
18
- "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram",
19
- "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram",
47
+ "MotifBraidChart",
48
+ "DependencyForestChart",
49
+ "ForceDirectedGraph",
50
+ "SankeyDiagram",
51
+ "ProcessSankey",
52
+ "ChordDiagram",
53
+ "TreeDiagram",
54
+ "Treemap",
55
+ "CirclePack",
56
+ "OrbitDiagram"
20
57
  ],
58
+ // END GENERATED NETWORK CHARTS
21
59
  geo: [
22
60
  "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram",
23
61
  ],
62
+ // BEGIN GENERATED REALTIME CHARTS
24
63
  realtime: [
25
- "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart",
26
- "RealtimeWaterfallChart", "RealtimeHeatmap",
64
+ "RealtimeLineChart",
65
+ "RealtimeHistogram",
66
+ "TemporalHistogram",
67
+ "RealtimeSwarmChart",
68
+ "RealtimeWaterfallChart",
69
+ "RealtimeHeatmap"
27
70
  ],
71
+ // END GENERATED REALTIME CHARTS
72
+ // BEGIN GENERATED PHYSICS CHARTS
28
73
  physics: [
29
74
  "FlowCircuitChart",
30
- "GaltonBoardChart", "EventDropChart", "UnitPileChart", "CollisionSwarmChart",
31
- "PacketFlowChart", "ProcessFlowChart", "GauntletChart", "CrucibleChart",
32
- "ChainReactionChart",
75
+ "GaltonBoardChart",
76
+ "EventDropChart",
77
+ "UnitPileChart",
78
+ "CollisionSwarmChart",
79
+ "PacketFlowChart",
80
+ "ProcessFlowChart",
81
+ "GauntletChart",
82
+ "CrucibleChart",
83
+ "ChainReactionChart"
33
84
  ],
85
+ // END GENERATED PHYSICS CHARTS
34
86
  value: [
35
87
  "BigNumber",
36
88
  ],
@@ -83,7 +135,8 @@ function schemaResourceUriForComponent(name) {
83
135
  function metadataForComponent(entryOrName) {
84
136
  const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name
85
137
  const category = categoryForComponent(name)
86
- // Realtime push-streaming charts are browser-only by design.
138
+ // MCP excludes the live Realtime charts. Their public server renderers
139
+ // separately accept bounded data snapshots.
87
140
  // TemporalHistogram is the static-data sibling living in the
88
141
  // "realtime" category for documentation grouping — it accepts a
89
142
  // bounded data array and is renderable through the SSR path like
@@ -0,0 +1,3 @@
1
+ /** CommonJS metadata; consumers narrow to the contract they use. */
2
+ declare const componentMetadata: unknown
3
+ export = componentMetadata
@@ -0,0 +1,3 @@
1
+ "use strict";var H=Object.create;var h=Object.defineProperty;var V=Object.getOwnPropertyDescriptor;var Y=Object.getOwnPropertyNames;var J=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var w=(e,t)=>()=>{try{return t||e((t={exports:{}}).exports,t),t.exports}catch(a){throw t=0,a}},W=(e,t)=>{for(var a in t)h(e,a,{get:t[a],enumerable:!0})},R=(e,t,a,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of Y(t))!K.call(e,o)&&o!==a&&h(e,o,{get:()=>t[o],enumerable:!(r=V(t,o))||r.enumerable});return e};var S=(e,t,a)=>(a=e!=null?H(J(e)):{},R(t||!e||!e.__esModule?h(a,"default",{value:e,enumerable:!0}):a,e)),X=e=>R(h({},"__esModule",{value:!0}),e);var O=w((Re,M)=>{"use strict";var P=require("path"),Q=require("fs"),k="<!-- semiotic-behavior-contracts:start -->",D="<!-- semiotic-behavior-contracts:end -->";function Z(){let e=[P.join(__dirname,"schema.json"),P.join(__dirname,"..","schema.json")];for(let t of e)try{let a=JSON.parse(Q.readFileSync(t,"utf8")),r=new Set;for(let o of a.tools||[])"data"in(o.function?.parameters?.properties||{})&&r.add(o.function.name);if(r.size>0)return r}catch{}return new Set}var g=[{component:"StackedAreaChart",required:["areaBy"],staticRequired:["data","areaBy"],pushRequired:["areaBy"],summary:"Stacked areas need a flat data array plus areaBy to identify the stacked series."},{component:"BubbleChart",required:["sizeBy"],staticRequired:["data","sizeBy"],pushRequired:["sizeBy"],summary:"Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size."},{component:"StackedBarChart",required:["stackBy"],staticRequired:["data","stackBy"],pushRequired:["stackBy"],summary:"Stacked bars need stackBy to split each category into stack segments."},{component:"GroupedBarChart",required:["groupBy"],staticRequired:["data","groupBy"],pushRequired:["groupBy"],summary:"Grouped bars need groupBy to split each category into side-by-side bars."},{component:"SwimlaneChart",required:["subcategoryAccessor"],staticRequired:["data","subcategoryAccessor"],pushRequired:["subcategoryAccessor"],summary:"Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided."},{component:"GaugeChart",required:["value"],staticRequired:["value"],pushRequired:[],summary:"GaugeChart is value-only. Its thresholds use { value, color, label? }; BigNumber thresholds use the distinct { at, level, color?, label? } vocabulary."},{component:"ForceDirectedGraph",required:["nodes","edges"],staticRequired:["nodes","edges"],pushRequired:["nodes","edges"],summary:"ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code."}],u=["RealtimeLineChart","RealtimeHistogram","RealtimeSwarmChart","RealtimeWaterfallChart","RealtimeHeatmap","LineChart","AreaChart","StackedAreaChart","Scatterplot","BubbleChart","ConnectedScatterplot","CandlestickChart","MultiAxisLineChart","Heatmap","WaterfallChart","QuadrantChart","DifferenceChart","BarChart","StackedBarChart","GroupedBarChart","SwarmPlot","BoxPlot","Histogram","ViolinPlot","RidgelinePlot","DotPlot","PieChart","DonutChart","LikertChart","SwimlaneChart","FunnelChart","RadarChart","ForceDirectedGraph","SankeyDiagram","ChordDiagram","ProportionalSymbolMap","DistanceCartogram","GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart","PacketFlowChart","ProcessFlowChart","GauntletChart"],x=Z(),C=[{id:"accessibility.description-props",category:"accessibility",title:"Accessible chart text uses direct chart props",severity:"warning",appliesTo:{},summary:"High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.",agentAction:'Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. If a consumer-owned role=img wraps the chart, use accessibleTable: { portalTarget: "element-id" } and render that target outside the image. For generated L1\u2013L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.'},{id:"interaction.cursor-is-presentation-only",category:"interaction",title:"Cursor styling does not create behavior",severity:"warning",appliesTo:{propsAny:["cursor"],propPathsAny:[["styleRules","*","style","cursor"]]},summary:"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.",agentAction:"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."},{id:"props.data-required-by-usage-mode",category:"required-props",title:"Data required by usage mode",severity:"error",appliesTo:{components:u},summary:"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.",agentAction:'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.'},{id:"color.category-precedence",category:"color",title:"Categorical color precedence",severity:"info",appliesTo:{propsAny:["colorBy","colorScheme"]},summary:"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.",agentAction:"Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution."},{id:"props.required-combinations",category:"required-props",title:"Required prop combinations",severity:"error",appliesTo:{components:g.map(e=>e.component)},summary:"Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.",agentAction:"Before returning code, check the selected component against the required combinations list. For push mode, omit data but keep semantic props such as areaBy, sizeBy, stackBy, and groupBy.",combinations:g},{id:"streaming.push-mode-data",category:"streaming",title:"Push mode omits data",severity:"warning",appliesTo:{components:u},summary:"HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.",agentAction:"For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later."},{id:"streaming.serialized-proposal-snapshot",category:"streaming",title:"Serialized proposals keep the initial snapshot",severity:"warning",appliesTo:{components:u},summary:"A JSON component/props proposal for MCP, SSR, or evaluation is a static snapshot even when the request mentions future pushes. Keep the supplied initial rows in the component's real data prop and do not invent pushRows, pushRequirement, ref, or method props.",agentAction:"Return renderable initial props in JSON. If the requested deliverable is React push code, separately omit the controlled data prop in JSX, attach a ref, and call the documented imperative method from an effect or event handler.",example:'JSON snapshot: { "component": "LineChart", "props": { "data": [{"week":1,"users":120}], "xAccessor":"week", "yAccessor":"users" } }. React push code instead omits data and calls ref.current?.push(row).'},{id:"streaming.ref-mutations-require-id-accessors",category:"streaming",title:"Ref mutations need stable IDs",severity:"warning",appliesTo:{components:u},summary:"push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.",agentAction:"When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field."},{id:"rendering.renderchart-static-props",category:"rendering",title:"renderChart uses static props only",severity:"warning",appliesTo:{},summary:"MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot, never future ref pushes. semiotic/server accepts bounded data for realtime charts; MCP rendering excludes the five live Realtime components but includes TemporalHistogram.",agentAction:"Use complete static data for snapshots. For a Realtime component snapshot, use semiotic/server directly; for live behavior, return React code with a ref and do not promise MCP-rendered output."},{id:"serialization.formatters-are-react-callbacks",category:"serialization",title:"Axis formatters are React callbacks",severity:"error",appliesTo:{propsAny:["xFormat","yFormat","categoryFormat","valueFormat"]},summary:"xFormat, yFormat, categoryFormat, and valueFormat are callback props, not d3 format strings or axis-title strings. They are intentionally absent from JSON/MCP schemas and string values fail validation.",agentAction:"In serialized props, omit formatter callbacks and use xLabel, yLabel, categoryLabel, or valueLabel for axis titles. In React JSX, pass a function such as xFormat={value => formatAxis(value)}.",example:'JSON: { "xLabel": "Payload (KB)", "yLabel": "Response time (ms)" }. React-only: xFormat={value => formatNumber(value, { maximumFractionDigits: 0 })}.'},{id:"value.bignumber-wire-contract",category:"value",title:"Value components do not inherit chart-HOC props",severity:"error",appliesTo:{components:["BigNumber"]},summary:"BigNumber is a value component, not a chart HOC, so it does not inherit the common chart-HOC prop list. It uses label as its visible heading and supports description and summary; title and accessibleTable are invalid. Its percent format expects a ratio such as 0.97 and renders it as 97%.",agentAction:'Validate BigNumber against its own prop schema and remove inherited chart-HOC props such as title and accessibleTable before returning a proposal. Use label, description, and summary for text. For a 97-of-100 KPI, either pass value={0.97} with format="percent" or pass value={97} with format="number" and suffix="%"; do not combine value={97} with format="percent".',example:'{ "component": "BigNumber", "props": { "value": 97, "label": "SLA attainment", "format": "number", "suffix": "%", "target": { "value": 99, "label": "target", "format": "number" } } }'},{id:"geo.proportional-symbol-wire-shape",category:"geo",title:"Proportional symbol maps use geographic props",severity:"error",appliesTo:{components:["ProportionalSymbolMap"]},summary:"ProportionalSymbolMap reads point rows from points, longitude from xAccessor (default lon), latitude from yAccessor (default lat), and radius from sizeBy. sizeRange is the two-number pixel-radius range.",agentAction:"Use points, xAccessor, yAccessor, and sizeBy. Do not rename points to data or sizeBy to valueAccessor merely because the map renders circles.",example:'{ "points": [{"city":"A","longitude":-122.4,"latitude":37.8,"incidents":18}], "xAccessor":"longitude", "yAccessor":"latitude", "sizeBy":"incidents", "sizeRange":[5,40] }'},{id:"physics.sample-and-mechanical-inputs",category:"physics",title:"Physics charts separate chart mode from simulation input",severity:"warning",appliesTo:{components:["GaltonBoardChart","UnitPileChart"]},summary:`Sample simulations use data plus the chart's accessors. Seeded no-data demonstrations use simulationMode="mechanical" (legacy mode="mechanical" remains accepted); mode otherwise carries chart display modes such as primary or sparkline.`,agentAction:"For observed Galton values pass data + valueAccessor. For unit piles pass data + categoryAccessor + valueAccessor. Use seed for reproducibility, bins for Galton columns, and unitValue for the amount represented by one full UnitPile circle; remainders use proportional area.",example:'{ "component": "GaltonBoardChart", "props": { "data": [{"id":"a","value":1}], "valueAccessor":"value", "bins":4, "seed":42 } }'},{id:"physics.push-uses-source-records",category:"physics",title:"Physics push methods ingest source records",severity:"error",appliesTo:{components:["GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart"]},summary:"Physics HOC refs push source records through the chart's accessors. pushRows and dataIdAccessor are not component props; stable source id fields are retained on spawned bodies without an invented accessor.",agentAction:"For React live code, call ref.current?.push(row) or pushMany(rows). For serialized snapshots, append the rows to data. Keep category/value/time accessors, but omit pushRows and dataIdAccessor.",example:'ref.current?.push({ id: "c", team: "Blue", value: 2 }); <UnitPileChart ref={ref} categoryAccessor="team" valueAccessor="value" unitValue={1} />'},{id:"physics.live-source-reconciliation",category:"physics",title:"Distribution physics charts update bodies and projections together",severity:"warning",appliesTo:{components:["GaltonBoardChart","UnitPileChart","CollisionSwarmChart","EventDropChart"]},summary:"Bodies, categories, domains, and totals update together without changing React keys. getData() returns source rows. New data replaces live rows; rerunMS restores the seed.",agentAction:"Omit data for push mode; data=[] stays empty and rejects pushes. Use stable IDs and remove for source edits; popBodies only removes marks. Set xExtent/valueExtent/timeExtent for stable domains.",example:'ref.current?.update("a", row => ({ ...row, value: 102 })); ref.current?.remove("b");'},{id:"physics.event-admission-history",category:"physics",title:"EventDrop distinguishes admission history from current closure",severity:"error",appliesTo:{components:["EventDropChart"]},summary:"Arrival order determines historical lateness with a delay/function watermark. Equal arrival times keep source order. A window is closed when its end is at or below the watermark; previously accepted events stay accepted as later events advance it. An explicit watermark.value instead tests one fixed policy.",agentAction:"Use watermark={{delay: n}} for arrival-ordered admission, or watermarkAtArrivalAccessor for recorded thresholds independent of current closure. Keep all times in the same units. The current board has solid lids: accepted history starts below them, late arrivals roll left. For a chronological demonstration, supply successive data/watermark states and coordinate source time with travel. timeScale does not replay lid changes. Source projection labels describe snapshot totals; readEventDropOccupancy(metadata, bodies) counts current containers and in-flight bodies independently of source flags.",example:'{ "data": [{"time":1,"arrivalTime":2,"admission":-3}], "watermarkAtArrivalAccessor":"admission", "watermark":{"value":100} }'}];function B(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function ee(e){return e&&typeof e=="object"&&!Array.isArray(e)?e:{}}function te(e,t){if(!t)return!e.appliesTo?.components;let a=e.appliesTo?.components;return!a||a.includes(t)}function ae(e,t){let a=e.appliesTo?.propsAny,r=e.appliesTo?.propPathsAny;return(!a||a.length===0)&&(!r||r.length===0)||a?.some(o=>B(t,o)&&t[o]!==void 0)?!0:r?.some(o=>y(t,o))??!1}function y(e,t){if(t.length===0)return e!==void 0;if(e===null||typeof e!="object")return!1;let[a,...r]=t;return a==="*"?Array.isArray(e)&&e.some(o=>y(o,r)):B(e,a)&&y(e[a],r)}function re({component:e,props:t}={}){let a=ee(t);return C.filter(r=>te(r,e)&&ae(r,a))}function T(e){return e==="push"?"push":"static"}function oe(e,t){return!(!x.has(e)||T(t)==="push"&&u.includes(e))}function se(e){return g.filter(t=>!e||t.component===e)}function q(e){let t=e.staticRequired||e.required,a=e.pushRequired||e.required.filter(o=>o!=="data"),r=a.length>0?a.join(" + "):"not supported";return`${e.component}: static ${t.join(" + ")}; push ${r}. ${e.summary}`}function ne(e){if(!e||e.length===0)return"";let t=["Behavior contracts:"];for(let a of e){if(t.push(` - [${a.id}] ${a.summary}`),a.combinations)for(let r of a.combinations)t.push(` ${q(r)}`);a.example&&t.push(` Example: ${a.example}`),t.push(` Action: ${a.agentAction}`)}return t.join(`
2
+ `)}function ie({compact:e=!1}={}){let t=[e?"## Behavior Contracts":"## AI Behavior Contracts","",k,"","These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.",""];for(let a of C){if(t.push(`- **${a.title}** (\`${a.id}\`): ${a.summary}`),e||t.push(` Agent action: ${a.agentAction}`),a.combinations){let r=a.combinations.map(q).join(" ");t.push(` Required combinations: ${r}`)}!e&&a.example&&t.push(` Example: \`${a.example}\``)}return t.push("",D),t.join(`
3
+ `)}M.exports={BEHAVIOR_CONTRACTS:C,DOC_MARKER_END:D,DOC_MARKER_START:k,PUSH_MODE_COMPONENTS:u,REQUIRED_COMBINATIONS:g,STATIC_DATA_COMPONENTS:x,behaviorContractsFor:re,dataRequiredForUsageMode:oe,formatBehaviorContractsMarkdown:ie,formatDoctorBehaviorContracts:ne,normalizeUsageMode:T,requiredCombinationsFor:se}});var L=w((Se,G)=>{"use strict";var F=["xy","ordinal","network","geo","realtime","physics","value","recipe"],E={xy:["LineChart","BumpChart","AreaChart","DifferenceChart","StackedAreaChart","Scatterplot","BubbleChart","Heatmap","QuadrantChart","MultiAxisLineChart","WaterfallChart","CandlestickChart","ConnectedScatterplot","ScatterplotMatrix","MinimapChart"],ordinal:["BarChart","StackedBarChart","GroupedBarChart","SwarmPlot","BoxPlot","Histogram","ViolinPlot","RidgelinePlot","DotPlot","PieChart","DonutChart","GaugeChart","FunnelChart","RadarChart","SwimlaneChart","LikertChart"],network:["MotifBraidChart","DependencyForestChart","ForceDirectedGraph","SankeyDiagram","ProcessSankey","ChordDiagram","TreeDiagram","Treemap","CirclePack","OrbitDiagram"],geo:["ChoroplethMap","ProportionalSymbolMap","FlowMap","DistanceCartogram"],realtime:["RealtimeLineChart","RealtimeHistogram","TemporalHistogram","RealtimeSwarmChart","RealtimeWaterfallChart","RealtimeHeatmap"],physics:["FlowCircuitChart","GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart","PacketFlowChart","ProcessFlowChart","GauntletChart","CrucibleChart","ChainReactionChart"],value:["BigNumber"],recipe:["ParallelCoordinatesRecipe","CalendarHeatmapRecipe"]},b=new Map;for(let[e,t]of Object.entries(E))for(let a of t)b.set(a,e);var ce={PhysicsCustomChart:"physics"};function v(e){return e.tools.map(t=>t.function)}function U(e){let t=b.get(e);if(!t)throw new Error(`No AI component metadata category for "${e}"`);return t}function de(e){return b.get(e)??ce[e]}function I(e){return e==="physics"?"semiotic/physics":e==="recipe"?"semiotic/ai":e==="geo"?"semiotic/geo":`semiotic/${e}`}function $(e){return`semiotic://schema/${encodeURIComponent(e)}`}function N(e){let t=typeof e=="string"?e:e.name,a=U(t),r=a==="realtime"&&t.startsWith("Realtime");return{name:t,category:a,importPath:["MotifBraidChart","DependencyForestChart","FlowCircuitChart"].includes(t)?"semiotic/atlas":I(a),schemaResourceUri:$(t),renderable:!r,requiresLiveData:r,description:typeof e=="string"?void 0:e.description}}function le(e,t){let a=v(e),r=a.find(n=>n.name===t);if(r)return r;let o=t.toLowerCase();return a.find(n=>n.name.toLowerCase()===o)}function pe(e){let t=v(e).map(N),a={};for(let r of F)a[r]=[];for(let r of t)a[r.category].push(r.name);for(let r of Object.values(a))r.sort();return{version:e.version,totalComponents:t.length,renderableComponents:t.filter(r=>r.renderable).length,browserOnlyComponents:t.filter(r=>!r.renderable).length,requiresLiveDataComponents:t.filter(r=>r.requiresLiveData).length,categories:a,components:t}}G.exports={CATEGORY_ORDER:F,COMPONENTS_BY_CATEGORY:E,categoryForComponent:U,categoryForAIExport:de,componentIndexFromSchema:pe,findComponent:le,importPathForCategory:I,metadataForComponent:N,schemaResourceUriForComponent:$,schemaEntries:v}});var Ae={};W(Ae,{diagnoseChart:()=>fe});module.exports=X(Ae);var z=S(O()),_=S(L()),{dataRequiredForUsageMode:A,normalizeUsageMode:ue}=z.default,{findComponent:me,schemaEntries:he,COMPONENTS_BY_CATEGORY:ge}=_.default;function fe(e,t,a){let{component:r,props:o}=e,n=ue(e.usageMode),m=ge.realtime.includes(r)&&(A(r,n)||o.data===null)&&o.data==null,p=`"data" is required for ${r}.`;if(t.diagnoseConfig){let i=t.diagnoseConfig(r,o),d=f(r,o,n)?i.diagnoses.filter(c=>c.code!=="VALIDATION"||c.message!==`"data" is required for ${r}.`):[...i.diagnoses];return m&&!d.some(({message:c})=>c===p)&&d.push({code:"VALIDATION",severity:"error",message:p,fix:"Provide bounded data for a static snapshot, or select push usage for React ref startup."}),{component:r,usageMode:n,mode:"diagnose",ok:d.every(({severity:c})=>c==="warning"),diagnoses:d}}let l=t.validateProps?"validate":"schema-only",s=t.validateProps?be(r,[...t.validateProps(r,o).errors],n,o):ve(r,o,n,a()).errors;return m&&!s.includes(p)&&s.push(p),A(r,"static")&&Array.isArray(o.data)&&o.data.length===0&&!s.includes(`${r}: No data provided. Pass a non-empty array to the data prop.`)&&s.push(`"data" must contain at least one observation for ${r}; an empty array is a static snapshot, not push startup.`),{component:r,usageMode:n,mode:l,ok:s.length===0,errors:s}}function ye(e,t){return(Array.isArray(t)?t:[t]).some(r=>r==="array"?Array.isArray(e):r==="object"?typeof e=="object"&&!Array.isArray(e):typeof e===r)}function Ce(e){return Array.isArray(e)?"array":typeof e}function f(e,t,a){return t.data===void 0&&!A(e,a)}function be(e,t,a,r){return f(e,r,a)?t.filter(o=>o!==`"data" is required for ${e}.`):t}function ve(e,t,a,r){let o=me(r,e);if(!o){let s=he(r).map(i=>i.name).sort().join(", ");return{valid:!1,errors:[`Unknown component "${e}". Available components: ${s}`]}}let n=o.parameters||{},m=n.properties||{},p=n.required||[],l=[];for(let s of p)s==="data"&&f(o.name,t,a)||(t[s]===void 0||t[s]===null)&&l.push(`"${s}" is required for ${o.name}.`);"data"in m&&!p.includes("data")&&!f(o.name,t,a)&&(t.data===void 0||t.data===null)&&l.push(`"data" is required for ${o.name}.`);for(let[s,i]of Object.entries(t)){if(i==null)continue;let d=m[s];if(!d){l.push(`Unknown prop "${s}" for ${o.name}.`);continue}let c=d["x-semiotic-runtime-types"]||d.type;if(c&&!ye(i,c)){let j=Array.isArray(c)?c.join(" | "):c;l.push(`"${s}" should be ${j}, got ${Ce(i)}.`)}d.enum&&typeof i=="string"&&!d.enum.includes(i)&&l.push(`"${s}" value "${i}" is not valid. Expected one of: ${d.enum.join(", ")}.`)}return{valid:l.length===0,errors:l}}0&&(module.exports={diagnoseChart});