semiotic 3.0.0 → 3.0.1

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- Import: `semiotic`, `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`
+- Import: `semiotic`, `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`, `semiotic/server`
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 - Every HOC has a built-in error boundary (never blanks the page) and dev-mode validation warnings
@@ -12,11 +12,11 @@
 - Every HOC accepts `frameProps` to pass through. TypeScript `strict: true`.
 
 ## Common Props (all HOCs)
-`title`, `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `enableHover` (true), `tooltip`, `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `chartId`
+`title`, `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `enableHover` (true), `tooltip`, `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `emphasis` ("primary"|"secondary")
 
 ## XY Charts (`semiotic/xy`)
 
-**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea`, `areaOpacity` (0.3), `anomaly` (AnomalyConfig), `forecast` (ForecastConfig)
+**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea`, `areaOpacity` (0.3), `anomaly` (AnomalyConfig), `forecast` (ForecastConfig), `directLabel` (boolean|{position,fontSize}), `gapStrategy` ("break"|"interpolate"|"zero")
 
 **AreaChart** — LineChart props + `areaBy`, `y0Accessor` (band/ribbon), `gradientFill` (boolean|{topOpacity,bottomOpacity}), `areaOpacity` (0.7), `showLine` (true)
 
@@ -51,6 +51,7 @@
 **TreeDiagram** — `data` (root), `layout`, `orientation`, `childrenAccessor`, `colorBy`, `colorByDepth`, `edgeStyle`
 **Treemap** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `showLabels`, `labelMode`
 **CirclePack** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `circleOpacity`
+**OrbitDiagram** — `data` (root), `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed` (0.25), `revolution`, `eccentricity`, `orbitSize`, `nodeRadius`, `showRings`, `showLabels`, `animated` (true), `colorBy`, `colorByDepth`, `annotations` (widget annotations anchor by nodeId)
 
 ## Realtime Charts (`semiotic/realtime`)
 
@@ -67,14 +68,14 @@ Realtime encoding: `decay`, `pulse`, `transition`, `staleness` — compose freel
 
 ## Coordinated Views
 
-**LinkedCharts** — wraps charts. Props: `selections` (resolution: "union"|"intersect"|"crossfilter")
+**LinkedCharts** — wraps charts. Props: `selections` (resolution: "union"|"intersect"|"crossfilter"), `showLegend` (auto when CategoryColorProvider present), `legendPosition` ("top"|"bottom"), `legendInteraction` ("highlight"|"isolate"|"none"), `legendSelectionName` (selection name for legend-driven cross-highlighting), `legendField` (data field for legend selections)
 **CategoryColorProvider** — stable category→color mapping. Props: `colors` (map) or `categories` + `colorScheme`
 Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
 **ScatterplotMatrix** — `data`, `fields`, `colorBy`, `cellSize`, `hoverMode`, `brushMode`
 
 ## Layout & Composition
 
-**ChartGrid** — CSS Grid layout. `columns` (number|"auto"), `minCellWidth` (300), `gap` (16)
+**ChartGrid** — CSS Grid layout. `columns` (number|"auto"), `minCellWidth` (300), `gap` (16). Children with `emphasis="primary"` span two columns.
 **ContextLayout** — primary + context panel. `context` (ReactNode), `position`, `contextSize` (250)
 
 ## Key Patterns
@@ -108,16 +109,28 @@ ref.current.push({ time: Date.now(), value: 42 })
 <RealtimeLineChart ref={ref} timeAccessor="time" valueAccessor="value" />
 ```
 
+## Annotations
+- `type: "widget"` — place any React element at data coordinates. Works on all frame types. XY/ordinal use data coordinates (`x`/`y` or field names). Network/orbit use `nodeId`. Default: info emoji. Renders as HTML overlay (not SVG) so popups/threads overflow freely.
+```jsx
+annotations={[{ type: "widget", month: 4, revenue: 32, dy: -4, content: <MyAlertButton /> }]}
+// OrbitDiagram: annotations={[{ type: "widget", nodeId: "Pipeline", content: <Alert /> }]}
+```
+
+## Server-Side Rendering
+- All HOC charts and Stream Frames render SVG automatically in server environments (no window/document)
+- `renderToStaticSVG()`, `renderXYToStaticSVG()`, `renderOrdinalToStaticSVG()`, `renderNetworkToStaticSVG()` — standalone SVG generation from `semiotic/server`
+- Works with Next.js App Router, Remix, Astro — same component on server and client
+
 ## AI Features
 - `onObservation` — structured events (hover, click, brush, selection) on all HOCs
 - `useChartObserver` — aggregates observations across LinkedCharts
 - `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX` — chart state serialization
 - `DetailsPanel` — click-driven detail panel inside `ChartContainer`
-- `validateProps(componentName, props)` — prop validation
+- `validateProps(componentName, props)` — prop validation with Levenshtein typo suggestions
+- `diagnoseConfig(componentName, props)` — anti-pattern detector (12 checks: empty data, bad dimensions, missing accessors, margin overflow, etc.)
 - `ChartErrorBoundary` — error boundary
-- `exportChart(el, { format: "png"|"svg" })` — browser export
-- `renderToStaticSVG()` — server-side SVG (from `semiotic/server`)
-- `npx semiotic-ai --doctor` — validate component + props JSON from CLI
+- `exportChart(el, { format: "png"|"svg" })` — browser export (default: PNG, composites canvas + SVG layers)
+- `npx semiotic-ai --doctor` — validate component + props JSON from CLI (uses both validateProps and diagnoseConfig)
 
 ## Differentiators
-Network viz, streaming canvas, realtime encoding, coordinated views, statistical summaries, AI hooks, chart serialization, global theming, keyboard navigation
+Network viz, streaming canvas, realtime encoding, coordinated views, statistical summaries, AI hooks, chart serialization, global theming, keyboard navigation, interactive legends (highlight/isolate), direct labeling, gap handling, empty/loading states, landmark tick labels, LinkedCharts unified legend

package/README.md

@@ -4,10 +4,11 @@
 [![npm version](https://img.shields.io/npm/v/semiotic.svg)](https://www.npmjs.com/package/semiotic)
 [![TypeScript](https://img.shields.io/badge/TypeScript-built--in-blue.svg)](https://www.typescriptlang.org/)
 
-A React data visualization library for charts, networks, and beyond.
+A React data visualization library designed for AI-assisted development.
 
-Simple charts in 5 lines. Force-directed graphs, Sankey diagrams, treemaps,
-and chord diagrams when you need them. Full D3-level control when you want it.
+Simple charts in 5 lines. Network graphs, streaming data, and coordinated
+dashboards when you need them. Structured schemas and an MCP server so
+AI coding assistants generate correct chart code on the first try.
 
 ```jsx
 import { LineChart } from "semiotic"
@@ -21,31 +22,46 @@ import { LineChart } from "semiotic"
 
 ## Why Semiotic
 
-Most React charting libraries give you bar charts, line charts, and pie charts.
-Semiotic gives you those too — but it's built for the projects where those
-aren't enough.
+Semiotic is a data visualization library for React that combines broad chart
+coverage with first-class AI tooling. It handles the chart types that most
+libraries skip — network graphs, streaming data, statistical distributions,
+coordinated views — and ships with machine-readable schemas so LLMs can
+generate correct code without examples.
 
-### When you need more than standard charts
+### Built for AI-assisted development
 
-**Network visualization.** Show how things connect — org charts,
-dependency graphs, budget flows, taxonomies. Semiotic has force-directed
-graphs, Sankey diagrams, chord diagrams, tree layouts, treemaps, and circle
-packing as React components with the same prop API as LineChart.
+Semiotic ships with everything an AI coding assistant needs to generate
+correct visualizations without trial and error:
 
-**Streaming data.** Monitor live systems — server metrics, sensor feeds,
-financial tickers. Semiotic's realtime charts render on canvas at 60fps with
-a ref-based push API. Old data fades out (decay), new data flashes in
-(pulse), and stale feeds are flagged automatically.
+- **`semiotic/ai`** — a single import with all 28 chart components, optimized for LLM code generation
+- **`ai/schema.json`** — machine-readable prop schemas for every component
+- **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
+- **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
+- **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with 12 checks and actionable fixes
+- **`CLAUDE.md`** — instruction files auto-synced for Claude, Cursor, Copilot, Windsurf, and Cline
+- **`llms.txt`** — machine-readable documentation following the emerging standard
 
-**Coordinated dashboards.** Hover one chart, highlight matching data in
-others. Brush a scatterplot, filter a bar chart. Semiotic's `LinkedCharts`
-and `ScatterplotMatrix` provide crossfilter coordination that other libraries
-leave you to build from scratch.
+Every chart includes a built-in error boundary and dev-mode validation
+warnings with typo suggestions, so AI-generated code fails gracefully with
+actionable diagnostics instead of a blank screen.
 
-**Statistical summaries.** Box plots, violin plots, swarm plots, ridgeline
-plots, histograms — the distribution charts that data scientists need and
-most charting libraries skip. Add marginal distribution graphics (histogram,
-violin, ridgeline, boxplot) to scatterplot margins with a single prop.
+### Beyond standard charts
+
+**Network visualization.** Force-directed graphs, Sankey diagrams, chord
+diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all
+as React components with the same prop API as LineChart.
+
+**Streaming data.** Realtime charts render on canvas at 60fps with a
+ref-based push API. Built-in decay, pulse, and staleness encoding for
+monitoring dashboards.
+
+**Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
+brush cross-filtering, and selection synchronization across any combination
+of chart types — zero wiring.
+
+**Statistical summaries.** Box plots, violin plots, swarm plots, histograms,
+LOESS smoothing, forecast with confidence envelopes, and anomaly detection.
+Marginal distribution graphics on scatterplot axes with a single prop.
 
 ### Start simple, go deep
 
@@ -57,6 +73,13 @@ violin, ridgeline, boxplot) to scatterplot margins with a single prop.
 Every Chart component accepts a `frameProps` prop to access the underlying
 Frame API without leaving the simpler interface.
 
+### Serialization and interop
+
+Charts serialize to JSON and back: `toConfig`, `fromConfig`, `toURL`,
+`copyConfig`, `configToJSX`. Have Vega-Lite specs? `fromVegaLite(spec)`
+translates them to Semiotic configs — works with `configToJSX()` for
+full round-trip from notebooks and AI-generated specs.
+
 ### When to use something else
 
 Need a standard bar or line chart for a dashboard you'll never need to
@@ -69,40 +92,10 @@ Semiotic is for projects that outgrow those libraries — when you need
 network graphs alongside time series, streaming data alongside static
 snapshots, or coordinated views across chart types.
 
-### Bundle size comparison
-
-| Library | Packed | Unpacked | What you get |
-|---|---|---|---|
-| Victory | 393 KB | 2.3 MB | Charts only |
-| Lightweight Charts | 586 KB | 3.0 MB | Financial charts only |
-| **Semiotic** | **668 KB** | **2.5 MB** | **Charts + networks + streaming + coordination** |
-| Recharts | 1.4 MB | 6.4 MB | Charts only |
-| Chart.js | 1.6 MB | 6.2 MB | Charts only, no React |
-| ApexCharts | 1.8 MB | 8.4 MB | Charts only |
-| ECharts | 11.4 MB | 57.6 MB | Everything, no React |
-
-**AI-ready.** Semiotic ships with structured schemas (`ai/schema.json`), an
-`import from "semiotic/ai"` entry point, and an MCP server — all designed for
-LLM code generation. AI coding assistants can generate correct Semiotic code on
-the first try. Run `npx semiotic-ai --help` for CLI options, `npx semiotic-ai --doctor`
-to validate props from the command line, or add `semiotic-mcp` to your MCP client
-config for tool-based chart rendering. Every HOC chart includes a built-in error
-boundary and dev-mode validation warnings with actionable fix suggestions.
-
-**Vega-Lite compatible.** Have existing Vega-Lite specs? `fromVegaLite(spec)`
-translates them to Semiotic chart configs — instant onboarding from notebooks,
-dashboards, or AI-generated specs. Composes with `configToJSX()`,
-`copyConfig()`, and `toURL()` for full round-trip interop.
-
-**Streaming system models.** Turn a streaming Sankey into a live system monitor:
-click-to-inspect `DetailsPanel`, particle speed proportional to edge throughput,
-threshold alerting with animated glow, and automatic topology diffing that
-highlights new services as they appear. Visualization as product navigation.
-
 ## Install
 
 ```bash
-npm install semiotic@3.0.0
+npm install semiotic
 ```
 
 Requires React 18.1+ or React 19.
@@ -215,9 +208,9 @@ import { LineChart, BarChart } from "semiotic"
 
 | Category | Components |
 |---|---|
-| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `BubbleChart` `Heatmap` |
+| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` |
 | **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `DotPlot` `PieChart` `DonutChart` |
-| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` |
+| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
 | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
 | **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
 | **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
@@ -257,9 +250,9 @@ for color, size, aggregation, and binning.
 Import only what you need:
 
 ```jsx
-import { LineChart } from "semiotic/xy"                 // 123 KB
-import { BarChart } from "semiotic/ordinal"              // 118 KB
-import { ForceDirectedGraph } from "semiotic/network"    // 127 KB
+import { LineChart } from "semiotic/xy"                 // 124 KB
+import { BarChart } from "semiotic/ordinal"              // 100 KB
+import { ForceDirectedGraph } from "semiotic/network"    // 104 KB
 import { LineChart } from "semiotic/ai"                  // HOC-only surface for AI generation
 ```
 
@@ -283,7 +276,19 @@ interface Sale { month: number; revenue: number }
 
 ## Server-Side Rendering
 
-Static SVG generation for Node.js (email, OG images, PDF):
+All chart components render SVG automatically in server environments — no
+special imports or configuration needed:
+
+```jsx
+// Works in Next.js App Router, Remix, Astro — same component, same props
+import { LineChart } from "semiotic"
+
+// Server: renders <svg> with path/circle/rect elements
+// Client: renders <canvas> with SVG overlay for axes
+<LineChart data={data} xAccessor="date" yAccessor="value" />
+```
+
+For standalone SVG generation (email, OG images, PDF), use the server entry point:
 
 ```js
 import { renderToStaticSVG } from "semiotic/server"
@@ -296,14 +301,12 @@ const svg = renderToStaticSVG("xy", {
 })
 ```
 
-Works with Next.js App Router, Remix, and Astro via `"use client"` directives.
-
 ## Documentation
 
 [Interactive docs and examples](https://semiotic.nteract.io)
 
 - [Getting Started](https://semiotic.nteract.io/getting-started)
-- [Charts](https://semiotic.nteract.io/charts) — all 27 chart types with live examples
+- [Charts](https://semiotic.nteract.io/charts) — all 28 chart types with live examples
 - [Frames](https://semiotic.nteract.io/frames) — full Frame API reference
 - [Features](https://semiotic.nteract.io/features) — axes, annotations, tooltips, styling, Vega-Lite translator
 - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes

package/ai/cli.js

@@ -54,46 +54,59 @@ if (flag === "--doctor") {
       process.exit(1)
     }
 
-    // Load validateProps from dist
+    // Load diagnoseConfig from dist (falls back to validateProps)
     const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
-    let validateProps
+    let diagnoseConfig, validateProps
     try {
       const mod = require(distPath)
+      diagnoseConfig = mod.diagnoseConfig
       validateProps = mod.validateProps
     } catch (e) {
       console.error("Could not load semiotic/ai dist. Run 'npm run dist' first.")
       process.exit(1)
     }
 
-    if (!validateProps) {
-      console.error("validateProps not found in semiotic/ai exports.")
+    if (!diagnoseConfig && !validateProps) {
+      console.error("diagnoseConfig/validateProps not found in semiotic/ai exports.")
       process.exit(1)
     }
 
-    const result = validateProps(component, props)
-    if (result.valid) {
-      console.log(`✓ ${component}: props are valid.`)
-      // Additional data shape checks
+    if (diagnoseConfig) {
+      // Use the full anti-pattern detector
+      const result = diagnoseConfig(component, props)
+
+      // Show data shape summary
       if (props.data && Array.isArray(props.data) && props.data.length > 0) {
         const sample = props.data[0]
         console.log(`  Data shape: ${props.data.length} items, keys: [${Object.keys(sample).join(", ")}]`)
-        if (props.xAccessor && typeof props.xAccessor === "string" && !(props.xAccessor in sample)) {
-          console.log(`  ⚠ xAccessor "${props.xAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
-        }
-        if (props.yAccessor && typeof props.yAccessor === "string" && !(props.yAccessor in sample)) {
-          console.log(`  ⚠ yAccessor "${props.yAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
-        }
-        if (props.categoryAccessor && typeof props.categoryAccessor === "string" && !(props.categoryAccessor in sample)) {
-          console.log(`  ⚠ categoryAccessor "${props.categoryAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+      }
+
+      if (result.ok && result.diagnoses.length === 0) {
+        console.log(`✓ ${component}: configuration looks good.`)
+      } else if (result.ok) {
+        console.log(`✓ ${component}: configuration OK with warnings:`)
+        for (const d of result.diagnoses) {
+          console.log(`  ⚠ [${d.code}] ${d.message}`)
+          if (d.fix) console.log(`    Fix: ${d.fix}`)
         }
-        if (props.valueAccessor && typeof props.valueAccessor === "string" && !(props.valueAccessor in sample)) {
-          console.log(`  ⚠ valueAccessor "${props.valueAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+      } else {
+        console.log(`✗ ${component}: issues detected.`)
+        for (const d of result.diagnoses) {
+          const icon = d.severity === "error" ? "✗" : "⚠"
+          console.log(`  ${icon} [${d.code}] ${d.message}`)
+          if (d.fix) console.log(`    Fix: ${d.fix}`)
         }
       }
     } else {
-      console.log(`✗ ${component}: validation failed.`)
-      for (const err of result.errors) {
-        console.log(`  • ${err}`)
+      // Fallback to validateProps only
+      const result = validateProps(component, props)
+      if (result.valid) {
+        console.log(`✓ ${component}: props are valid.`)
+      } else {
+        console.log(`✗ ${component}: validation failed.`)
+        for (const err of result.errors) {
+          console.log(`  • ${err}`)
+        }
       }
     }
   } catch (err) {

package/ai/dist/componentRegistry.js

@@ -9,6 +9,7 @@ exports.COMPONENT_REGISTRY = {
     Scatterplot: { component: ai_1.Scatterplot, category: "xy" },
     BubbleChart: { component: ai_1.BubbleChart, category: "xy" },
     Heatmap: { component: ai_1.Heatmap, category: "xy" },
+    ConnectedScatterplot: { component: ai_1.ConnectedScatterplot, category: "xy" },
     BarChart: { component: ai_1.BarChart, category: "ordinal" },
     StackedBarChart: { component: ai_1.StackedBarChart, category: "ordinal" },
     GroupedBarChart: { component: ai_1.GroupedBarChart, category: "ordinal" },
@@ -23,4 +24,5 @@ exports.COMPONENT_REGISTRY = {
     TreeDiagram: { component: ai_1.TreeDiagram, category: "network" },
     Treemap: { component: ai_1.Treemap, category: "network" },
     CirclePack: { component: ai_1.CirclePack, category: "network" },
+    OrbitDiagram: { component: ai_1.OrbitDiagram, category: "network" },
 };

package/ai/dist/mcp-server.js

@@ -57,6 +57,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const renderHOCToSVG_1 = require("./renderHOCToSVG");
 const componentRegistry_1 = require("./componentRegistry");
+const ai_1 = require("semiotic/ai");
 // Load schema.json for tool definitions
 const schemaPath = path.resolve(__dirname, "../schema.json");
 const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
@@ -88,6 +89,59 @@ for (const toolDef of schema.tools) {
         };
     });
 }
+// ── Generic renderChart tool ─────────────────────────────────────────────
+// Accepts { component, props } — closes the agent feedback loop by letting
+// an LLM render any chart type in a single tool call.
+server.tool("renderChart", "Render any Semiotic chart to static SVG. Pass { component: 'LineChart', props: { data: [...], ... } }. Returns SVG string or validation errors.", {}, async (args) => {
+    const component = args.component;
+    const props = (args.props || args);
+    if (!component) {
+        return {
+            content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+            isError: true,
+        };
+    }
+    const result = (0, renderHOCToSVG_1.renderHOCToSVG)(component, props);
+    if (result.error) {
+        return {
+            content: [{ type: "text", text: result.error }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: result.svg }],
+    };
+});
+// ── diagnoseConfig tool ──────────────────────────────────────────────────
+// Anti-pattern detector: checks for common failure modes and returns
+// actionable fix instructions.
+server.tool("diagnoseConfig", "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, etc). Pass { component: 'LineChart', props: { ... } }. Returns structured diagnoses with fix instructions.", {}, async (args) => {
+    const component = args.component;
+    const props = (args.props || args);
+    if (!component) {
+        return {
+            content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+            isError: true,
+        };
+    }
+    const result = (0, ai_1.diagnoseConfig)(component, props);
+    if (result.ok) {
+        const warnings = result.diagnoses.filter(d => d.severity === "warning");
+        const msg = warnings.length > 0
+            ? `Configuration looks good with ${warnings.length} warning(s):\n${warnings.map(w => `⚠ [${w.code}] ${w.message}\n  Fix: ${w.fix}`).join("\n")}`
+            : `✓ Configuration looks good — no issues detected.`;
+        return { content: [{ type: "text", text: msg }] };
+    }
+    const lines = result.diagnoses.map(d => {
+        const icon = d.severity === "error" ? "✗" : "⚠";
+        const fixLine = d.fix ? `\n  Fix: ${d.fix}` : "";
+        return `${icon} [${d.code}] ${d.message}${fixLine}`;
+    });
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: true,
+    };
+});
 // Start the server
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();

package/ai/examples.md

@@ -111,6 +111,32 @@ const data = [
 
 Key props: `valueAccessor`, `colorScheme` ("blues"|"reds"|"greens"|"viridis"), `showValues`
 
+### ConnectedScatterplot
+
+```jsx
+import { ConnectedScatterplot } from "semiotic/ai"
+
+const data = [
+  { year: 2018, unemployment: 3.9, inflation: 2.4 },
+  { year: 2019, unemployment: 3.7, inflation: 1.8 },
+  { year: 2020, unemployment: 8.1, inflation: 1.2 },
+  { year: 2021, unemployment: 5.4, inflation: 4.7 },
+  { year: 2022, unemployment: 3.6, inflation: 8.0 },
+  { year: 2023, unemployment: 3.6, inflation: 4.1 }
+]
+
+<ConnectedScatterplot
+  data={data}
+  xAccessor="unemployment"
+  yAccessor="inflation"
+  orderAccessor="year"
+  xLabel="Unemployment Rate (%)"
+  yLabel="Inflation Rate (%)"
+/>
+```
+
+Key props: `orderAccessor` sequences points along the path, Viridis gradient from start→end
+
 ---
 
 ## Flat Array — Ordinal Charts
@@ -369,6 +395,55 @@ Key props: `valueAccessor` controls circle size, nested circles for hierarchy
 
 ---
 
+### OrbitDiagram
+
+```jsx
+import { OrbitDiagram } from "semiotic/ai"
+
+const pipeline = {
+  name: "ML Pipeline",
+  children: [
+    {
+      name: "Data Ingestion",
+      children: [
+        { name: "API Feed" },
+        { name: "CSV Upload" },
+        { name: "DB Connector" }
+      ]
+    },
+    {
+      name: "Processing",
+      children: [
+        { name: "Clean" },
+        { name: "Feature Eng" },
+        { name: "Normalize" }
+      ]
+    },
+    {
+      name: "Model",
+      children: [
+        { name: "Train" },
+        { name: "Evaluate" },
+        { name: "Deploy" }
+      ]
+    }
+  ]
+}
+
+<OrbitDiagram
+  data={pipeline}
+  childrenAccessor="children"
+  nodeIdAccessor="name"
+  orbitMode="solar"
+  showLabels
+  colorByDepth
+/>
+```
+
+Key props: `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`, `showRings`
+
+---
+
 ## Network Data — Nodes + Edges Arrays
 
 ### ForceDirectedGraph

package/ai/schema.json

@@ -383,6 +383,40 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "ConnectedScatterplot",
+        "description": "Scatterplot where points are connected in order, showing trajectories through 2D space. Viridis-colored start→end, white halo under lines.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Array of data objects"
+            },
+            "xAccessor": { "type": "string", "description": "Key for x-axis values", "default": "x" },
+            "yAccessor": { "type": "string", "description": "Key for y-axis values", "default": "y" },
+            "orderAccessor": { "type": "string", "description": "Key for point ordering (number or Date field)" },
+            "orderLabel": { "type": "string", "description": "Label for the ordering metric in tooltips" },
+            "pointRadius": { "type": "number", "description": "Point radius", "default": 4 },
+            "pointIdAccessor": { "type": "string", "description": "Accessor for unique point IDs, used by point-anchored annotations" },
+            "annotations": { "type": "array", "description": "Annotation objects to render on the chart" },
+            "colorBy": { "type": "string", "description": "Key to determine color encoding" },
+            "colorScheme": { "type": ["string", "array"], "description": "Named d3 color scheme or array of color strings" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 400 },
+            "enableHover": { "type": "boolean", "default": true },
+            "showGrid": { "type": "boolean", "default": false },
+            "margin": { "type": "object" },
+            "className": { "type": "string" }
+          },
+          "required": ["data"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {
@@ -1126,6 +1160,43 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "OrbitDiagram",
+        "description": "Animated orbital diagram showing hierarchical data as nodes orbiting a center. Supports flat, solar, atomic, and custom ring arrangements.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "Hierarchical root object with children: { name: 'root', children: [...] }"
+            },
+            "childrenAccessor": { "type": "string", "description": "Key to access children from each datum", "default": "children" },
+            "nodeIdAccessor": { "type": "string", "description": "Key to identify each node", "default": "name" },
+            "colorBy": { "type": "string", "description": "Field or function for node color" },
+            "colorScheme": { "type": ["string", "array"], "description": "Color scheme", "default": "category10" },
+            "colorByDepth": { "type": "boolean", "description": "Color by hierarchy depth", "default": false },
+            "orbitMode": { "type": ["string", "array"], "description": "Ring arrangement: 'flat', 'solar', 'atomic', or number[]", "default": "flat" },
+            "orbitSize": { "type": "number", "description": "Ring size divisor per depth", "default": 2.95 },
+            "speed": { "type": "number", "description": "Orbit speed in degrees per frame", "default": 0.25 },
+            "eccentricity": { "type": "number", "description": "Vertical squash for elliptical orbits (1 = circle)", "default": 1 },
+            "showRings": { "type": "boolean", "description": "Show orbital ring paths", "default": true },
+            "nodeRadius": { "type": "number", "description": "Node radius", "default": 6 },
+            "showLabels": { "type": "boolean", "description": "Show node labels", "default": false },
+            "animated": { "type": "boolean", "description": "Enable animation", "default": true },
+            "annotations": { "type": "array", "description": "Annotations anchored by nodeId" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 600 },
+            "enableHover": { "type": "boolean", "default": true },
+            "margin": { "type": "object" },
+            "className": { "type": "string" }
+          },
+          "required": ["data"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {

package/ai/system-prompt.md

@@ -8,6 +8,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **StackedAreaChart** — `xAccessor`, `yAccessor`, `areaBy` (required), `normalize`
 - **Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`
 - **BubbleChart** — `xAccessor`, `yAccessor`, **`sizeBy`** (required), `sizeRange`
+- **ConnectedScatterplot** — `xAccessor`, `yAccessor`, `orderAccessor` (sequencing field), `pointRadius`
 - **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme` ("blues"|"reds"|"greens"|"viridis")
 - **BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `sort`
 - **StackedBarChart** — `categoryAccessor`, `valueAccessor`, **`stackBy`** (required), `normalize`
@@ -24,6 +25,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **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`
 
 ## Network Data (`nodes: object[]`, `edges: object[]`)
 - **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`
@@ -35,6 +37,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **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`)
 
 ## Common Props (all components)