semiotic 3.0.1 → 3.1.0

package/ai/examples.md

@@ -111,6 +111,125 @@ const data = [
 
 Key props: `valueAccessor`, `colorScheme` ("blues"|"reds"|"greens"|"viridis"), `showValues`
 
+### Heatmap with Gradient Legend
+
+```jsx
+import { Heatmap } from "semiotic/ai"
+
+<Heatmap
+  data={data}
+  xAccessor="hour"
+  yAccessor="day"
+  valueAccessor="count"
+  colorScheme="viridis"
+  showLegend
+  legendPosition="right"
+/>
+```
+
+Key props: `showLegend` enables gradient legend, `legendPosition` ("right"|"left"|"top"|"bottom")
+
+### AreaChart
+
+```jsx
+import { AreaChart } from "semiotic/ai"
+
+const data = [
+  { month: 1, revenue: 4200 },
+  { month: 2, revenue: 5800 },
+  { month: 3, revenue: 5200 },
+  { month: 4, revenue: 7100 },
+  { month: 5, revenue: 6800 },
+  { month: 6, revenue: 7500 }
+]
+
+<AreaChart
+  data={data}
+  xAccessor="month"
+  yAccessor="revenue"
+  gradientFill
+  xLabel="Month"
+  yLabel="Revenue ($)"
+/>
+```
+
+Key props: `areaBy` (group into multiple areas), `y0Accessor` (band/ribbon), `gradientFill`, `areaOpacity` (0.7)
+
+### AreaChart — Percentile Band with Main Line
+
+**IMPORTANT**: `showLine` on AreaChart only draws the TOP edge of the area (the `yAccessor` line). To render a separate main line (e.g., p50 median), you must layer two charts.
+
+```jsx
+import { AreaChart, LineChart } from "semiotic/ai"
+
+const data = [
+  { x: 0, p5: 10, p50: 25, p95: 45 },
+  { x: 1, p5: 12, p50: 28, p95: 50 },
+  { x: 2, p5: 11, p50: 30, p95: 52 },
+  { x: 3, p5: 14, p50: 32, p95: 55 },
+  { x: 4, p5: 13, p50: 35, p95: 58 },
+  { x: 5, p5: 15, p50: 37, p95: 62 },
+]
+
+// Band (p5–p95) + main line (p50): two separate charts layered
+<div style={{ position: "relative" }}>
+  <AreaChart
+    data={data}
+    xAccessor="x"
+    yAccessor="p95"
+    y0Accessor="p5"
+    showLine={false}
+    areaOpacity={0.3}
+    gradientFill
+    width={600}
+    height={400}
+  />
+  <div style={{ position: "absolute", top: 0, left: 0 }}>
+    <LineChart
+      data={data}
+      xAccessor="x"
+      yAccessor="p50"
+      lineWidth={2}
+      width={600}
+      height={400}
+    />
+  </div>
+</div>
+```
+
+Key props: `y0Accessor` defines band bottom, `yAccessor` defines band top, `showLine={false}` hides the top edge stroke. Layer a `LineChart` on top for the main metric.
+
+### StackedAreaChart
+
+```jsx
+import { StackedAreaChart } from "semiotic/ai"
+
+// IMPORTANT: Use a flat array with an areaBy field for grouping.
+// Do NOT use lineBy or lineDataAccessor — those are LineChart props.
+const data = [
+  { month: 1, value: 20, category: "Product" },
+  { month: 2, value: 25, category: "Product" },
+  { month: 3, value: 30, category: "Product" },
+  { month: 1, value: 15, category: "Service" },
+  { month: 2, value: 12, category: "Service" },
+  { month: 3, value: 18, category: "Service" },
+  { month: 1, value: 8, category: "Consulting" },
+  { month: 2, value: 10, category: "Consulting" },
+  { month: 3, value: 7, category: "Consulting" }
+]
+
+<StackedAreaChart
+  data={data}
+  xAccessor="month"
+  yAccessor="value"
+  areaBy="category"
+  colorBy="category"
+  showLegend
+/>
+```
+
+Key props: **`areaBy`** (required — groups flat data into stacked areas), `colorBy`, `normalize` (100% stacked). Data must be a flat array, not pre-grouped objects.
+
 ### ConnectedScatterplot
 
 ```jsx
@@ -452,11 +571,11 @@ Key props: `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`,
 import { ForceDirectedGraph } from "semiotic/ai"
 
 const nodes = [
-  { id: "Alice", team: "Engineering" },
-  { id: "Bob", team: "Engineering" },
-  { id: "Carol", team: "Design" },
-  { id: "Dave", team: "Design" },
-  { id: "Eve", team: "Product" }
+  { id: "Alice", team: "Engineering", influence: 10 },
+  { id: "Bob", team: "Engineering", influence: 6 },
+  { id: "Carol", team: "Design", influence: 8 },
+  { id: "Dave", team: "Design", influence: 4 },
+  { id: "Eve", team: "Product", influence: 12 }
 ]
 
 const edges = [
@@ -472,12 +591,51 @@ const edges = [
   nodes={nodes}
   edges={edges}
   colorBy="team"
-  nodeSize={10}
+  nodeSize="influence"
+  nodeSizeRange={[5, 25]}
   showLabels
+  showLegend
+  edgeOpacity={0.4}
+  tooltip={(d) => <div><strong>{d.data.id}</strong><br/>Team: {d.data.team}</div>}
 />
 ```
 
-Key props: **`nodes`** and **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`
+Key props: **`nodes`** and **`edges`** (both required), `nodeIDAccessor` (default "id"), `sourceAccessor` (default "source"), `targetAccessor` (default "target"), `colorBy`, `nodeSize` (number, string field name, or function), `nodeSizeRange`, `showLabels`, `showLegend`, `tooltip`
+
+**Note**: Always use `ForceDirectedGraph` (not `StreamNetworkFrame`) unless you need sophisticated control it doesn't expose. `StreamNetworkFrame` is a low-level escape hatch whose callbacks receive internal `RealtimeNode` wrappers — access your data via `.data` (e.g., `nodeStyle={(d) => ({ fill: d.data?.color })}`). HOC components like `ForceDirectedGraph` handle this automatically.
+
+### ForceDirectedGraph with custom click/hover
+
+```jsx
+import { useState } from "react"
+import { ForceDirectedGraph } from "semiotic/ai"
+
+const [selected, setSelected] = useState(null)
+
+<ForceDirectedGraph
+  nodes={nodes}
+  edges={edges}
+  colorBy="team"
+  nodeSize="influence"
+  nodeSizeRange={[5, 25]}
+  showLabels
+  width={800}
+  height={600}
+  frameProps={{
+    customClickBehavior: (d) => {
+      // d is { type: "node"|"edge", data: <your raw node/edge>, x, y } or null
+      if (d?.type === "node") setSelected(d.data)
+    },
+    customHoverBehavior: (d) => {
+      // same shape as click — d.data is your original object
+      if (d?.type === "node") console.log("Hovering:", d.data.id)
+    },
+    background: "#1a1a2e",
+  }}
+/>
+```
+
+Key props: `frameProps` passes through to the underlying `StreamNetworkFrame` for advanced control (custom click/hover, background, annotations). Callback `d.data` is always your original node/edge object.
 
 ### SankeyDiagram
 
@@ -531,7 +689,98 @@ Key props: **`edges`** (required), shows bidirectional relationships in a circle
 
 ## Realtime — Push API via Ref
 
-### Streaming Sankey (StreamNetworkFrame)
+### RealtimeLineChart
+
+```jsx
+import { useRef, useEffect } from "react"
+import { RealtimeLineChart } from "semiotic/ai"
+
+const chartRef = useRef()
+
+// Push data — MUST include a time field
+useEffect(() => {
+  const interval = setInterval(() => {
+    chartRef.current?.push({ time: Date.now(), value: Math.random() * 100 })
+  }, 500)
+  return () => clearInterval(interval)
+}, [])
+
+<RealtimeLineChart
+  ref={chartRef}
+  size={[600, 300]}
+  timeAccessor="time"
+  valueAccessor="value"
+  windowSize={120}
+  stroke="#76b7b2"
+/>
+```
+
+Key props: `timeAccessor`, `valueAccessor`, `windowSize`, `stroke`, `strokeWidth`
+
+### RealtimeHistogram
+
+```jsx
+import { useRef, useEffect } from "react"
+import { RealtimeHistogram } from "semiotic/ai"
+
+const chartRef = useRef()
+
+// IMPORTANT: Include time field even though this shows a distribution — it's used for windowing
+useEffect(() => {
+  const interval = setInterval(() => {
+    chartRef.current?.push({
+      time: Date.now(),
+      value: Math.random() * 1000
+    })
+  }, 200)
+  return () => clearInterval(interval)
+}, [])
+
+<RealtimeHistogram
+  ref={chartRef}
+  size={[400, 250]}
+  timeAccessor="time"
+  valueAccessor="value"
+  binSize={100}
+/>
+```
+
+Key props: **`binSize`** (required), `timeAccessor` ("time"), `valueAccessor` ("value"). Without a time field in your data, the chart renders blank.
+
+### RealtimeHeatmap
+
+```jsx
+import { useRef, useEffect } from "react"
+import { RealtimeHeatmap } from "semiotic/ai"
+
+const chartRef = useRef()
+
+// IMPORTANT: Data must have fields matching timeAccessor and valueAccessor (defaults: "time" and "value")
+useEffect(() => {
+  const interval = setInterval(() => {
+    chartRef.current?.push({
+      time: Date.now(),
+      value: Math.random() * 500
+    })
+  }, 100)
+  return () => clearInterval(interval)
+}, [])
+
+<RealtimeHeatmap
+  ref={chartRef}
+  size={[400, 250]}
+  timeAccessor="time"
+  valueAccessor="value"
+  heatmapXBins={30}
+  heatmapYBins={10}
+/>
+```
+
+Key props: `timeAccessor` ("time"), `valueAccessor` ("value"), `heatmapXBins`, `heatmapYBins`. Both accessors must match your data fields or the chart renders blank.
+
+### Streaming Sankey with Particles (StreamNetworkFrame)
+
+Use `StreamNetworkFrame` only when you need low-level control that HOC charts don't expose. For most cases, use `ForceDirectedGraph`, `SankeyDiagram`, or `ChordDiagram` instead.
 
 ```jsx
 import { useRef, useEffect } from "react"
@@ -539,18 +788,18 @@ import { StreamNetworkFrame } from "semiotic"
 
 const chartRef = useRef()
 
-// Push edges at any frequency
 useEffect(() => {
-  const edges = [
-    { source: "Salary", target: "Budget", value: 5000 },
-    { source: "Freelance", target: "Budget", value: 1500 },
+  // Push individual edges — NOT a full snapshot.
+  // Each push adds one edge event to the streaming sankey.
+  chartRef.current.push({ source: "Salary", target: "Budget", value: 5000 })
+  chartRef.current.push({ source: "Freelance", target: "Budget", value: 1500 })
+
+  // Or batch multiple edges at once:
+  chartRef.current.pushMany([
     { source: "Budget", target: "Rent", value: 2000 },
     { source: "Budget", target: "Food", value: 800 },
-    { source: "Budget", target: "Savings", value: 1500 }
-  ]
-  for (const edge of edges) {
-    chartRef.current.push(edge)
-  }
+    { source: "Budget", target: "Savings", value: 1500 },
+  ])
 }, [])
 
 <StreamNetworkFrame
@@ -558,7 +807,98 @@ useEffect(() => {
   chartType="sankey"
   size={[800, 400]}
   edgeOpacity={0.4}
+  showParticles={true}
+  particleStyle={{
+    radius: 2,
+    opacity: 0.8,
+    speedMultiplier: 1.5,
+    maxPerEdge: 4,
+    colorBy: "source"
+  }}
 />
 ```
 
-Key props: push via ref (`push`, `pushMany`, `clear`), `chartType="sankey"`, uses `StreamNetworkFrame` from `semiotic`
+Key props: `chartType="sankey"`, `showParticles` (boolean — enables animated particles flowing along edges), `particleStyle` (`{ radius, opacity, speedMultiplier, maxPerEdge, colorBy }`), push via ref (`push` for single edge, `pushMany` for batch, `clear` to reset)
+
+### Streaming any chart type via Stream Frames
+
+The Realtime* HOCs are convenience wrappers. For streaming versions of scatter, stacked area, bar, or any other chart, use the corresponding Stream Frame with `runtimeMode="streaming"`:
+
+```jsx
+import { useRef } from "react"
+import { StreamXYFrame } from "semiotic/xy"
+
+const chartRef = useRef()
+
+// Push data via ref — same push API as Realtime* HOCs
+chartRef.current?.push({ time: Date.now(), size: 42, category: "A" })
+
+<StreamXYFrame
+  ref={chartRef}
+  chartType="scatter"
+  runtimeMode="streaming"
+  xAccessor="time"
+  yAccessor="size"
+  colorAccessor="category"
+  size={[600, 300]}
+  margin={{ top: 10, bottom: 30, left: 40, right: 10 }}
+/>
+```
+
+Available Stream Frames: `StreamXYFrame` (line, area, stackedArea, scatter), `StreamOrdinalFrame` (bar, grouped bar), `StreamNetworkFrame` (sankey, force, chord)
+
+---
+
+## Server-Side Rendering
+
+### renderToStaticSVG (Node.js)
+
+```ts
+// IMPORTANT: frameType is "xy" | "ordinal" | "network" — NOT a component name like "BarChart"
+import { renderOrdinalToStaticSVG } from "semiotic/server"
+
+const data = [
+  { category: "Q1", value: 120 },
+  { category: "Q2", value: 148 },
+  { category: "Q3", value: 135 },
+  { category: "Q4", value: 162 },
+]
+
+const svg: string = renderOrdinalToStaticSVG({
+  data,
+  categoryAccessor: "category",
+  valueAccessor: "value",
+  width: 600,
+  height: 400,
+})
+
+// Or use the generic function:
+import { renderToStaticSVG } from "semiotic/server"
+const svg2 = renderToStaticSVG("ordinal", { data, categoryAccessor: "category", valueAccessor: "value" })
+```
+
+Key: `renderToStaticSVG(frameType, props)` where frameType is `"xy"` | `"ordinal"` | `"network"`. Type-specific shortcuts: `renderXYToStaticSVG`, `renderOrdinalToStaticSVG`, `renderNetworkToStaticSVG`.
+
+---
+
+## Export
+
+### exportChart (browser)
+
+```jsx
+import { useRef } from "react"
+import { Scatterplot } from "semiotic/ai"
+import { exportChart } from "semiotic"
+
+const containerRef = useRef<HTMLDivElement>(null)
+
+// Pass the WRAPPER DIV, not the SVG element — exportChart finds canvas+SVG internally
+<div ref={containerRef}>
+  <Scatterplot data={data} xAccessor="x" yAccessor="y" width={600} height={400} />
+</div>
+<button onClick={() => exportChart(containerRef.current!, { format: "png" })}>
+  Download PNG
+</button>
+```
+
+Key: `exportChart(wrapperDiv, { format, filename, scale, background })`. It queries the wrapper for canvas and SVG elements internally. Default format: PNG with 2x scale.

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -294,6 +294,57 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "QuadrantChart",
+        "description": "Scatterplot divided into four labeled, colored quadrants by center lines. Use for BCG matrices, priority matrices, and any 2x2 strategic framework.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Array of data objects"
+            },
+            "xAccessor": { "type": "string", "default": "x" },
+            "yAccessor": { "type": "string", "default": "y" },
+            "xCenter": { "type": "number", "description": "X-coordinate of the vertical center line. Defaults to midpoint of x domain." },
+            "yCenter": { "type": "number", "description": "Y-coordinate of the horizontal center line. Defaults to midpoint of y domain." },
+            "quadrants": {
+              "type": "object",
+              "description": "Configuration for the four quadrants: { topRight, topLeft, bottomRight, bottomLeft }, each with { label, color, opacity? }",
+              "properties": {
+                "topRight": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "topLeft": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "bottomRight": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "bottomLeft": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] }
+              },
+              "required": ["topRight", "topLeft", "bottomRight", "bottomLeft"]
+            },
+            "showQuadrantLabels": { "type": "boolean", "default": true },
+            "quadrantLabelSize": { "type": "number", "default": 12 },
+            "colorBy": { "type": "string", "description": "Key to determine point color" },
+            "colorScheme": { "type": ["string", "array"], "default": "category10" },
+            "sizeBy": { "type": "string", "description": "Key for variable point sizing" },
+            "sizeRange": { "type": "array", "items": { "type": "number" }, "default": [3, 15] },
+            "pointRadius": { "type": "number", "default": 5 },
+            "pointOpacity": { "type": "number", "default": 0.8 },
+            "xLabel": { "type": "string" },
+            "yLabel": { "type": "string" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 400 },
+            "enableHover": { "type": "boolean", "default": true },
+            "showLegend": { "type": "boolean" },
+            "showGrid": { "type": "boolean", "default": false },
+            "margin": { "type": "object" },
+            "className": { "type": "string" }
+          },
+          "required": ["quadrants"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {
@@ -377,7 +428,18 @@
             "height": { "type": "number", "default": 400 },
             "enableHover": { "type": "boolean", "default": true },
             "margin": { "type": "object" },
-            "className": { "type": "string" }
+            "className": { "type": "string" },
+            "showLegend": {
+              "type": "boolean",
+              "description": "Show a gradient color legend",
+              "default": false
+            },
+            "legendPosition": {
+              "type": "string",
+              "enum": ["right", "left", "top", "bottom"],
+              "description": "Position of the gradient legend",
+              "default": "right"
+            }
           },
           "required": ["data"]
         }

package/ai/system-prompt.md

@@ -5,7 +5,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`
 - **AreaChart** — `xAccessor`, `yAccessor`, `areaBy`, `areaOpacity`
-- **StackedAreaChart** — `xAccessor`, `yAccessor`, `areaBy` (required), `normalize`
+- **StackedAreaChart** — `xAccessor`, `yAccessor`, **`areaBy`** (required, groups flat data into stacked areas), `colorBy`, `normalize`. Data must be a flat array. Do NOT use `lineBy` or `lineDataAccessor`.
 - **Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`
 - **BubbleChart** — `xAccessor`, `yAccessor`, **`sizeBy`** (required), `sizeRange`
 - **ConnectedScatterplot** — `xAccessor`, `yAccessor`, `orderAccessor` (sequencing field), `pointRadius`
@@ -15,30 +15,68 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **GroupedBarChart** — `categoryAccessor`, `valueAccessor`, **`groupBy`** (required)
 - **SwarmPlot** — `categoryAccessor`, `valueAccessor`, `pointRadius`
 - **BoxPlot** — `categoryAccessor`, `valueAccessor`, `showOutliers`
-- **Histogram** — `categoryAccessor`, `valueAccessor`, `bins` (default 25), `relative`
+- **Histogram** — `categoryAccessor` (optional, defaults to `"category"` — omit for single-group), `valueAccessor`, `bins` (default 25), `relative`
 - **ViolinPlot** — `categoryAccessor`, `valueAccessor`, `bins`, `curve`, `showIQR`
 - **DotPlot** — `categoryAccessor`, `valueAccessor`, `sort`, `dotRadius`
 - **PieChart** — `categoryAccessor`, `valueAccessor`
-- **DonutChart** — `categoryAccessor`, `valueAccessor`, `innerRadius`, `centerContent`
+- **DonutChart** — `categoryAccessor`, `valueAccessor`, `innerRadius`, `centerContent` (ReactNode, e.g. `<div>50%</div>`)
 
 ## Hierarchical Data (`data: { children: [...] }`)
 - **TreeDiagram** — `childrenAccessor`, `nodeIdAccessor`, `layout` ("tree"|"cluster"|"partition"), `orientation`
 - **Treemap** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
 - **CirclePack** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
-- **OrbitDiagram** — `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`
+- **OrbitDiagram** — animated radial/orbital hierarchy (use this, not TreeDiagram, for animated orbiting nodes). `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`. For static radial trees use `TreeDiagram layout="radial"`.
 
 ## Network Data (`nodes: object[]`, `edges: object[]`)
-- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`
+- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize` (number|string|fn), `nodeSizeRange`, `edgeWidth`, `edgeOpacity`, `iterations`, `forceStrength`, `showLabels`, `nodeLabel`, `tooltip`, `showLegend`
 - **SankeyDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 - **ChordDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 
+**Important**: Always use these HOC components for network charts unless you need sophisticated control they don't expose. `StreamNetworkFrame` is a low-level escape hatch — its callbacks receive internal wrapper objects (`RealtimeNode`), not your raw data.
+
 ## Realtime (ref-based push API, canvas)
-- **RealtimeLineChart** — `ref.current.push(datum)`, `timeAccessor`, `valueAccessor`, `windowSize`
-- **RealtimeHistogram** — **`binSize`** (required), `timeAccessor`, `valueAccessor`
-- **RealtimeSwarmChart** — `timeAccessor`, `valueAccessor`, `categoryAccessor`
-- **RealtimeWaterfallChart** — `timeAccessor`, `valueAccessor`, `positiveColor`, `negativeColor`
-- **RealtimeHeatmap** — `timeAccessor`, `valueAccessor`, `heatmapXBins`, `heatmapYBins`, `aggregation`
-- **StreamNetworkFrame** (`chartType="sankey"`) — `ref.current.push({ source, target, value })`, `sourceAccessor`, `targetAccessor`, `valueAccessor` (import from `semiotic`)
+
+**IMPORTANT**: All pushed data must include a time field (default: `"time"`). Set `timeAccessor` if your field is named differently. Without a valid time field, charts silently render blank.
+
+Sizing: all Realtime HOCs accept both `size={[600, 400]}` (tuple) and `width={600} height={400}`.
+
+- **RealtimeLineChart** — `ref.current.push(datum)`, **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `windowSize`
+- **RealtimeHistogram** — **`binSize`** (required), **`timeAccessor`** ("time"), **`valueAccessor`** ("value"). Time field required even though this is a distribution — it's used for windowing.
+- **RealtimeSwarmChart** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `categoryAccessor`
+- **RealtimeWaterfallChart** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `positiveColor`, `negativeColor`
+- **RealtimeHeatmap** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `heatmapXBins`, `heatmapYBins`, `aggregation`. Both must match your data fields.
+- **StreamNetworkFrame** (`chartType="sankey"`) — push **individual edges**: `ref.current.push({ source, target, value })`. Use `ref.current.pushMany([...edges])` for batches. Do NOT push full edge snapshots. Props: `sourceAccessor`, `targetAccessor`, `valueAccessor`, `showParticles` (boolean), `particleStyle` (`{ radius, opacity, speedMultiplier, maxPerEdge, colorBy }`) (import from `semiotic`)
+
+Pushed data shape: `{ time: Date.now(), value: 42 }` for line/waterfall/heatmap, add `category` for histogram/swarm.
+
+### Push API on HOC charts
+Many HOC charts support the push API via `forwardRef`. **Omit the `data` prop** (do NOT pass `data={[]}`) and push imperatively:
+```jsx
+const chartRef = useRef()
+chartRef.current.push({ x: 1, y: 2 })
+<Scatterplot ref={chartRef} xAccessor="x" yAccessor="y" />
+```
+Methods: `push(datum)`, `pushMany(data)`, `clear()`, `getData()`. Streaming-specific props (`windowSize`, `decay`, `pulse`) go in `frameProps`. Supported: XY charts, ordinal charts, network charts (ForceDirectedGraph, SankeyDiagram, ChordDiagram), ProportionalSymbolMap, DistanceCartogram. Not supported: hierarchy charts (TreeDiagram, Treemap, CirclePack, OrbitDiagram), ChoroplethMap, FlowMap, ScatterplotMatrix.
+
+For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdinalFrame`, `StreamNetworkFrame`) with `runtimeMode="streaming"` and ref-based push.
+
+## ChartContainer
+- **ChartContainer** — wrapper with title, subtitle, status indicator, toolbar. `title`, `subtitle`, `height` (default **400** — always set this to match your chart height), `width` ("100%"), `status` ("live"|"stale"|"error"), `loading`, `error`, `actions`, `style`
+- When using with `size={[w, h]}`, set `height={h}` on the container or you'll get extra whitespace.
 
 ## Common Props (all components)
-`width`, `height`, `margin`, `title`, `colorBy`, `colorScheme`, `enableHover`, `tooltip`, `showLegend`, `className`, `frameProps`
+`width`, `height`, `margin`, `title`, `colorBy`, `colorScheme`, `enableHover`, `tooltip`, `showLegend`, `className`, `frameProps`, `onObservation`, `emphasis` ("primary"|"secondary")
+
+### tooltip
+`true` (default) | `false` | `(datum) => ReactNode` (function receives your raw data) | config `{ fields?, title?, format?, style? }`
+
+### onObservation
+Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selection", datum: <your data>, x, y, timestamp, chartType, chartId }`. The `datum` field is your original data object. Hover-end/click-end events omit `datum`.
+
+### emphasis
+`emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
+
+## Key Patterns
+- **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
+- **SSR**: `renderToStaticSVG("ordinal", props)` or `renderOrdinalToStaticSVG(props)` from `semiotic/server`. Frame type is `"xy"` | `"ordinal"` | `"network"` (NOT component name).
+- **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/components/Legend.d.ts

@@ -1,3 +1,9 @@
 import * as React from "react";
-import { LegendProps } from "./types/legendTypes";
+import { LegendProps, GradientLegendConfig } from "./types/legendTypes";
+/** Gradient legend for continuous/sequential color scales */
+export declare function GradientLegend({ config, orientation, width, }: {
+    config: GradientLegendConfig;
+    orientation?: "vertical" | "horizontal";
+    width?: number;
+}): React.JSX.Element;
 export default function Legend(props: LegendProps): React.JSX.Element;

package/dist/components/charts/geo/ChoroplethMap.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
+import { type AreasProp } from "../../geo/useReferenceAreas";
+export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** GeoJSON features or a reference string ("world-110m", "world-50m", "land-110m", "land-50m") */
+    areas: AreasProp;
+    /** Accessor for the numeric value to encode as color */
+    valueAccessor: ChartAccessor<TDatum, number>;
+    /** Sequential color scheme @default "blues" */
+    colorScheme?: string;
+    /** Geographic projection @default "equalEarth" */
+    projection?: ProjectionProp;
+    /** Show graticule grid lines */
+    graticule?: boolean | import("../../stream/geoTypes").GraticuleConfig;
+    /** Tooltip config */
+    tooltip?: TooltipProp;
+    /** Show legend @default true */
+    showLegend?: boolean;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
+    zoomable?: boolean;
+    /** [minZoom, maxZoom] @default [1, 8] */
+    zoomExtent?: [number, number];
+    /** Zoom change callback */
+    onZoom?: StreamGeoFrameProps["onZoom"];
+    /**
+     * When true, drag gestures rotate the projection (globe spinning)
+     * instead of panning. Defaults to true for orthographic projection.
+     */
+    dragRotate?: boolean;
+    /** Raster tile URL template or function. Enables tile basemap (Mercator only). */
+    tileURL?: string | ((z: number, x: number, y: number, dpr: number) => string);
+    /** Attribution text for tile provider */
+    tileAttribution?: string;
+    /** Max cached tiles @default 256 */
+    tileCacheSize?: number;
+    /** Fill opacity for area polygons. Useful for layering over tile basemaps. @default 1 */
+    areaOpacity?: number;
+    /** Annotations */
+    annotations?: Record<string, any>[];
+    /** Passthrough to StreamGeoFrame */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "projection">>;
+}
+export declare function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element | null;
+export declare namespace ChoroplethMap {
+    var displayName: string;
+}