semiotic 3.8.6 → 3.8.7

package/ai/dist/mcp-server.js

@@ -6956,12 +6956,13 @@ var require_componentMetadata = __commonJS({
       physics: [
         "GaltonBoardChart",
         "EventDropChart",
-        "PhysicsPileChart",
+        "UnitPileChart",
         "CollisionSwarmChart",
-        "PhysicalFlowChart",
+        "PacketFlowChart",
         "ProcessFlowChart",
         "GauntletChart",
-        "CrucibleChart"
+        "CrucibleChart",
+        "ChainReactionChart"
       ],
       value: [
         "BigNumber"
@@ -6991,12 +6992,11 @@ var require_componentMetadata = __commonJS({
       const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name;
       const category = categoryForComponent(name);
       const isPushOnly = category === "realtime" && name.startsWith("Realtime");
-      const isValueCategory = category === "value";
       return {
         name,
         category,
         importPath: importPathForCategory(category),
-        renderable: !isPushOnly && !isValueCategory,
+        renderable: !isPushOnly,
         description: typeof entryOrName === "string" ? void 0 : entryOrName.description
       };
     }
@@ -7519,7 +7519,7 @@ var require_behaviorContracts = __commonJS({
         required: ["value"],
         staticRequired: ["value"],
         pushRequired: [],
-        summary: "GaugeChart is value-only. thresholds, min, max, sweep, and arcWidth are optional."
+        summary: "GaugeChart is value-only. Its thresholds use { value, color, label? }; BigNumber thresholds use the distinct { at, level, color?, label? } vocabulary."
       },
       {
         component: "ForceDirectedGraph",
@@ -7557,7 +7557,16 @@ var require_behaviorContracts = __commonJS({
       "SankeyDiagram",
       "ChordDiagram",
       "ProportionalSymbolMap",
-      "DistanceCartogram"
+      "DistanceCartogram",
+      "GaltonBoardChart",
+      "EventDropChart",
+      "UnitPileChart",
+      "CollisionSwarmChart",
+      "PacketFlowChart",
+      "ProcessFlowChart",
+      "GauntletChart",
+      "CrucibleChart",
+      "ChainReactionChart"
     ];
     var STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema();
     var BEHAVIOR_CONTRACTS2 = [
@@ -7615,6 +7624,18 @@ var require_behaviorContracts = __commonJS({
         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: PUSH_MODE_COMPONENTS
+        },
+        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",
@@ -7634,6 +7655,66 @@ var require_behaviorContracts = __commonJS({
         appliesTo: {},
         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.",
         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."
+      },
+      {
+        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", "CollisionSwarmChart"]
+        },
+        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 UnitPile body.",
+        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} />'
       }
     ];
     function hasOwn(value, key) {
@@ -7687,6 +7768,7 @@ var require_behaviorContracts = __commonJS({
             lines.push(`    ${formatRequiredCombination(combo)}`);
           }
         }
+        if (contract.example) lines.push(`    Example: ${contract.example}`);
         lines.push(`    Action: ${contract.agentAction}`);
       }
       return lines.join("\n");
@@ -7709,6 +7791,9 @@ var require_behaviorContracts = __commonJS({
           const combos = contract.combinations.map(formatRequiredCombination).join(" ");
           lines.push(`  Required combinations: ${combos}`);
         }
+        if (!compact && contract.example) {
+          lines.push(`  Example: \`${contract.example}\``);
+        }
       }
       lines.push("", DOC_MARKER_END);
       return lines.join("\n");
@@ -33059,12 +33144,14 @@ var COMPONENT_REGISTRY = {
   DistanceCartogram: { component: import_geo.DistanceCartogram, category: "geo" },
   GaltonBoardChart: { component: import_ai.GaltonBoardChart, category: "physics" },
   EventDropChart: { component: import_ai.EventDropChart, category: "physics" },
-  PhysicsPileChart: { component: import_ai.PhysicsPileChart, category: "physics" },
+  UnitPileChart: { component: import_ai.UnitPileChart, category: "physics" },
   CollisionSwarmChart: { component: import_ai.CollisionSwarmChart, category: "physics" },
-  PhysicalFlowChart: { component: import_ai.PhysicalFlowChart, category: "physics" },
+  PacketFlowChart: { component: import_ai.PacketFlowChart, category: "physics" },
   ProcessFlowChart: { component: import_ai.ProcessFlowChart, category: "physics" },
   GauntletChart: { component: import_ai.GauntletChart, category: "physics" },
-  CrucibleChart: { component: import_ai.CrucibleChart, category: "physics" }
+  CrucibleChart: { component: import_ai.CrucibleChart, category: "physics" },
+  ChainReactionChart: { component: import_ai.ChainReactionChart, category: "physics" },
+  BigNumber: { component: import_ai.BigNumber, category: "value" }
 };
 
 // ai/renderHOCToSVG.tsx

package/ai/examples.md

@@ -57,6 +57,34 @@ const data = [
 
 Key props: `lineBy` groups flat array into separate lines, `colorBy` colors them
 
+### LineChart (dynamic value accessor)
+
+When each row identifies which numeric field to plot, use an accessor function
+instead of forcing the value through a single field name. This is especially
+useful for multi-line data with a different metric per series.
+
+```jsx
+import { LineChart } from "semiotic/ai"
+
+const data = [
+  { timestamp: 1, metricLabel: "valueA", valueA: 12, valueB: 60 },
+  { timestamp: 2, metricLabel: "valueA", valueA: 18, valueB: 55 },
+  { timestamp: 1, metricLabel: "valueB", valueA: 12, valueB: 60 },
+  { timestamp: 2, metricLabel: "valueB", valueA: 18, valueB: 55 }
+]
+
+<LineChart
+  data={data}
+  xAccessor="timestamp"
+  yAccessor={(d) => d[d.metricLabel]}
+  lineBy="metricLabel"
+  colorBy="metricLabel"
+/>
+```
+
+Key props: accessors accept a field-name string or a function. Prefer a string
+for a direct lookup; use a function for a computed or dynamic value.
+
 ### Scatterplot
 
 ```jsx
@@ -826,6 +854,33 @@ Key props: **`edges`** (required), shows bidirectional relationships in a circle
 
 ## Realtime — Push API via Ref
 
+### Serialized snapshot versus React push code
+
+When an MCP, SSR, or evaluation request asks for component/props JSON and also
+mentions future pushes, keep the supplied initial rows in the serialized
+snapshot. `pushRows`, `pushRequirement`, `ref`, and `method` are orchestration
+instructions, not chart props.
+
+```json
+{
+  "component": "LineChart",
+  "props": {
+    "data": [
+      { "week": 1, "users": 120 },
+      { "week": 2, "users": 138 }
+    ],
+    "xAccessor": "week",
+    "yAccessor": "users",
+    "xLabel": "Week",
+    "yLabel": "Active users"
+  }
+}
+```
+
+React push code has a different lifecycle: omit `data`, attach a ref, and push
+the initial or newly arrived rows from an effect. Formatter callbacks such as
+`xFormat` are JSX-only; serialized axis titles belong in `xLabel` and `yLabel`.
+
 ### RealtimeLineChart
 
 ```jsx
@@ -1306,6 +1361,40 @@ Key APIs: `WordTrailsWordInfo` gives `word`, `column`, `weight`, and `segment` p
 
 ---
 
+## Geographic Charts
+
+### ProportionalSymbolMap
+
+```jsx
+import { ProportionalSymbolMap } from "semiotic/geo"
+
+const incidents = [
+  { id: "a", city: "A", longitude: -122.4, latitude: 37.8, incidents: 18 },
+  { id: "b", city: "B", longitude: -74.0, latitude: 40.7, incidents: 31 },
+  { id: "c", city: "C", longitude: -87.6, latitude: 41.9, incidents: 12 },
+]
+
+<ProportionalSymbolMap
+  points={incidents}
+  xAccessor="longitude"
+  yAccessor="latitude"
+  sizeBy="incidents"
+  sizeRange={[5, 40]}
+  colorBy="city"
+  showLegend
+/>
+```
+
+The geographic wire vocabulary is deliberate: rows live in `points`,
+longitude and latitude use `xAccessor` and `yAccessor`, and symbol radius uses
+`sizeBy`. Do not substitute the generic `data` or `valueAccessor` names.
+
+For live React code, omit `points` and push source records through the ref:
+`ref.current?.push({ id, longitude, latitude, incidents })`. For a static JSON
+snapshot, keep all observed records in `points`.
+
+---
+
 ## Physics Charts — Motion With A Settled Projection
 
 ### GaltonBoardChart (distribution drop)
@@ -1352,12 +1441,12 @@ import { EventDropChart } from "semiotic/physics"
 
 Key props: `timeAccessor` assigns the event-time window, `arrivalAccessor` controls arrival replay, `windows.size` creates barriers, and `watermark.delay` sends late events to the late path.
 
-### PhysicsPileChart (unitized category piles)
+### UnitPileChart (unitized category piles)
 
 ```jsx
-import { PhysicsPileChart } from "semiotic/physics"
+import { UnitPileChart } from "semiotic/physics"
 
-<PhysicsPileChart
+<UnitPileChart
   data={[
     { category: "Orders", value: 18 },
     { category: "Queued", value: 11 },
@@ -1373,6 +1462,34 @@ import { PhysicsPileChart } from "semiotic/physics"
 
 Key props: `unitValue` controls how many simulated bodies appear. Increase it for large values so the settled piles remain readable and the frame budget stays bounded.
 
+For a live unit pile, the ref ingests the same source-row shape the static
+`data` prop uses:
+
+```jsx
+import { useEffect, useRef } from "react"
+import { UnitPileChart } from "semiotic/physics"
+
+const pileRef = useRef(null)
+
+useEffect(() => {
+  pileRef.current?.push({ id: "c", team: "Blue", value: 2 })
+}, [])
+
+<UnitPileChart
+  ref={pileRef}
+  categoryAccessor="team"
+  valueAccessor="value"
+  unitValue={1}
+  seed={42}
+  title="Queued work by team"
+/>
+```
+
+`pushRows` and `dataIdAccessor` are not physics chart props. Keep an `id` on
+source records when identity matters; the physics HOC retains it on the spawned
+bodies. For a static JSON proposal, append the incoming rows to `data` so the
+snapshot can render immediately.
+
 ### CollisionSwarmChart (axis-preserving collision layout)
 
 ```jsx
@@ -1397,12 +1514,12 @@ import { CollisionSwarmChart } from "semiotic/physics"
 Key props: `xAccessor` preserves the quantitative position, `groupAccessor` creates lanes, and collision settings separate overlapping records without losing the axis.
 
 
-### PhysicalFlowChart (packet flow over routes)
+### PacketFlowChart (packet flow over routes)
 
 ```jsx
-import { PhysicalFlowChart } from "semiotic/physics"
+import { PacketFlowChart } from "semiotic/physics"
 
-<PhysicalFlowChart
+<PacketFlowChart
   nodes={[
     { id: "Inbound", x: 0.08, y: 0.5 },
     { id: "Queue", x: 0.45, y: 0.32 },
@@ -1449,6 +1566,36 @@ import { ProcessFlowChart } from "semiotic/physics"
 
 Key props: `stages` declare force / capacity / absorb behavior, `groupBy` forms feature sockets that complete when every member is absorbed, and `liveCapacity` installs FIFO queue controllers for capacitated stages. Prefer ProcessFlowChart for many independent work items; use GauntletChart for one compound project degraded by gates.
 
+### ChainReactionChart (dependency reach and blockers)
+
+```jsx
+import { ChainReactionChart } from "semiotic/physics"
+
+const releaseTasks = [
+  { id: "brief", title: "Brief", lane: "Product", dependsOn: [], status: "done", completedAt: 1 },
+  { id: "privacy", title: "Privacy review", lane: "Product", dependsOn: ["brief"], status: "blocked", blocker: "Legal review" },
+  { id: "schema", title: "Schema", lane: "Data", dependsOn: ["privacy"], status: "waiting" },
+  { id: "ingest", title: "Ingest", lane: "Data", dependsOn: ["schema"], status: "waiting" },
+]
+
+<ChainReactionChart
+  data={releaseTasks}
+  taskIDAccessor="id"
+  labelAccessor="title"
+  laneAccessor="lane"
+  dependencyAccessor="dependsOn"
+  statusAccessor="status"
+  completionTimeAccessor="completedAt"
+  blockerAccessor="blocker"
+  currentTime={10}
+  mode="snapshot"
+  insight="blocker-amplification"
+  size={[800, 420]}
+/>
+```
+
+Key props: `dependencyAccessor` must name explicit prerequisite ids — the chart never invents edges from a flat table. `statusAccessor` and `completionTimeAccessor` are authored task facts; delivery balls only enact satisfied prerequisites. Use `insight="blocker-amplification"` to expose how many unfinished downstream tasks and lanes each blocker reaches.
+
 ### GauntletChart (compound project through timed gates)
 
 ```jsx
@@ -1590,7 +1737,7 @@ import { BigNumber } from "semiotic/value"
 />
 ```
 
-Key props: `value` (the one number), `format` ("number"|"currency"|"percent"|"compact"|"duration"|fn), `comparison` derives a delta with auto-sentiment, `target` renders "X% of goal", `thresholds` map value to a semantic theme role (`--semiotic-{success|warning|danger|info}`). Suppress decoration via `mode="thumbnail"` for dense grids or `mode="inline"` for prose. Stream via `ref.current.push({ value, time })` — pair with `stalenessThreshold` to dim the card when updates stop.
+Key props: `value` (the focal number), `label` (the visible heading), `description` and `summary` (accessible text), `comparison`, `target`, and `thresholds`. BigNumber does not use chart-frame `title` or `accessibleTable` props. Built-in `format` values are `"number"`, `"currency"`, `"percent"`, `"compact"`, and `"duration"`; custom formatter functions are React-only. `"percent"` treats its input as a ratio, so `0.97` renders as 97%. For an existing 0–100 value such as 97, use `format="number"` with `suffix="%"`. Suppress decoration via `mode="thumbnail"` for dense grids or `mode="inline"` for prose. Stream via `ref.current.push({ value, time })` — pair with `stalenessThreshold` to dim the card when updates stop.
 
 ### BigNumber with a Semiotic chart embedded via `trendSlot` (wide / rectangular)