semiotic 3.5.3 → 3.6.0

package/CLAUDE.md

@@ -4,7 +4,7 @@
 - Install: `npm install semiotic`
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-- **Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
+- **Use sub-path imports** — `semiotic/xy` (86KB gz), `semiotic/ordinal` (70KB gz), `semiotic/network` (64KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (91KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (211KB gz). Full `semiotic` is 190KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
@@ -30,7 +30,7 @@
 **Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `regression` (boolean | "linear" | "polynomial" | "loess" | RegressionConfig — sugar for a trend-annotation overlay; sits underneath user annotations)
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
 **ConnectedScatterplot** — + `orderAccessor`, `regression`
-**QuadrantChart** — Scatterplot + `quadrants` (required), `xCenter`, `yCenter`
+**QuadrantChart** — Scatterplot + optional `quadrants` overrides, `xCenter`, `yCenter`
 **MultiAxisLineChart** — Dual Y-axis. `series` (required: `[{ yAccessor, label?, color?, format?, extent? }]`). Falls back to multi-line if not 2 series.
 **Heatmap** — `data`, `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
 **ScatterplotMatrix** — `data`, `fields` (array of numeric field names for grid)
@@ -52,7 +52,7 @@
 **DonutChart** — PieChart + `innerRadius` (60), `centerContent`
 **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor` (optional), `connectorOpacity`, `orientation`
 **SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (required), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`, `roundedTop` (pixel radius applied to both outer ends of each lane — left+right for horizontal, top+bottom for vertical. Middle segments stay square so adjacent pieces butt against each other; single-segment lanes round all four corners.)
-**LikertChart** — `categoryAccessor`, `valueAccessor`|`levelAccessor`+`countAccessor`, `levels` (required), `orientation`, `colorScheme`
+**LikertChart** — `categoryAccessor`, `valueAccessor`|`levelAccessor`+`countAccessor`, optional `levels`, `orientation`, `colorScheme`
 **GaugeChart** — `value` (required), `min`, `max`, `thresholds`, `arcWidth`, `cornerRadius` (pixel radius for rounded segment ends — same semantics as DonutChart), `sweep`, `fillZones`, `showNeedle`, `centerContent`
 
 All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
@@ -84,7 +84,7 @@ Helpers: `resolveReferenceGeography("world-110m"|"world-50m")`, `mergeData(featu
 
 Push API: `ref.current.push({ time, value })`. All pushed data **must** include a time field.
 
-**RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap**, **Streaming Sankey** (StreamNetworkFrame + `showParticles`)
+**RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`), **TemporalHistogram** (static-data sibling of RealtimeHistogram — same props minus `windowSize`/`windowMode`; takes a bounded `data` array), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap**, **Streaming Sankey** (StreamNetworkFrame + `showParticles`)
 
 Encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely.
 
@@ -267,6 +267,64 @@ Canvas scene builders read CSS variables via `getComputedStyle` on the canvas DO
 ## AI Features
 `onObservation`/`useChartObserver`, `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX`, `validateProps(component, props)`, `diagnoseConfig(component, props)`, `exportChart(div, { format })`, `npx semiotic-ai --doctor`
 
+### Conversational Interrogation (`semiotic/ai`)
+Headless hook for "chat with the chart" interactions. The library ships no UI — bring your own chat surface.
+- **`useChartInterrogation({ data, onQuery, componentName?, props?, initialAnnotations? })`** → `{ ask(query), history, summary, annotations, loading, error, reset }`
+- **`onQuery: (query, context) => Promise<{ answer, annotations? }>`** — call your LLM here. `context` is `{ data, summary, componentName?, props? }`.
+- **`summary`**: LLM-friendly statistical summary (`rowCount`, per-field `{ min, max, mean, median }` for numerics, top-k for categoricals, ISO range for dates). Available before any ask().
+- **`annotations`**: Merged `initialAnnotations` + latest AI response. Wire to the chart's `annotations` prop for visual highlighting.
+- **`summarizeData(data, options?)`**: Standalone for server-side prompting or batch jobs.
+- **MCP Tool**: `interrogateChart(component, props, query)` returns the same statistical summary and AI-facing instructions.
+
+```jsx
+import { LineChart, useChartInterrogation } from "semiotic/ai"
+
+function InterrogatableChart({ data }) {
+  const { ask, history, annotations, loading } = useChartInterrogation({
+    data,
+    componentName: "LineChart",
+    props: { xAccessor: "month", yAccessor: "revenue" },
+    onQuery: async (query, { summary }) => {
+      const res = await myLLMCall(query, summary)
+      return { answer: res.text, annotations: res.highlights }
+    },
+  })
+  return (
+    <>
+      <LineChart data={data} xAccessor="month" yAccessor="revenue" annotations={annotations} />
+      <YourChatUI history={history} loading={loading} onAsk={ask} />
+    </>
+  )
+}
+```
+
+### Chart Capability Layer (`semiotic/ai`)
+Heuristic chart-suggestion engine. Charts ship capability descriptors next to their TSX files; the engine ranks them against a profiled dataset by intent. No LLM call required.
+
+- **`profileData(data, { rawInput?, seriesField? })`** → `ChartDataProfile` (extends `DataSummary`): candidate fields per role (x/y/series/category/size/time), distinct counts, monotonicity, structure detection (hierarchy/network/geo).
+- **`suggestCharts(data, { intent?, allow?, deny?, maxResults?, includeVariants?, minScore? })`** → ranked `Suggestion[]` with `{ component, family, importPath, variant?, score, intentScores, rubric, reasons, caveats, props }`. `props` is spreadable directly into the matching chart.
+- **`scoreChart(component, data, { intent?, variantKey? })`** → evaluate a specific chart for a dataset (does it fit, how well, why/why not).
+- **`useChartSuggestions(data, options)`** → memoized React hook returning `{ suggestions, profile }`.
+- **`registerChartCapability(capability)`** / **`unregisterChartCapability(name)`** — runtime registration for custom charts.
+- **Intent taxonomy**: 13 built-in intents (`trend`, `compare-series`, `compare-categories`, `rank`, `part-to-whole`, `distribution`, `correlation`, `flow`, `hierarchy`, `geo`, `outlier-detection`, `composition-over-time`, `change-detection`). Extend via `registerIntent(descriptor)`.
+- **Capability authoring**: create `Foo.capability.ts` next to `Foo.tsx`, then append to the registry in `src/components/ai/chartCapabilities.ts`. Each capability declares `family`, `rubric` (familiarity/accuracy/precision 1-5), `fits(profile)` gate, `intentScores`, optional `variants` with `intentDeltas`, and `buildProps(profile, variant)`.
+- **Variants encode that settings change what a chart is good for**: e.g. `StackedAreaChart`'s `streamgraph` variant boosts trend but penalizes part-to-whole.
+- **Interrogation tie-in**: pass `includeSuggestions: true` to `useChartInterrogation` and the same ranked list lands in `context.suggestions` for the LLM.
+- **MCP tool**: `suggestCharts(data, intent?)` returns the ranked list as structured content.
+
+```jsx
+import { useChartSuggestions, LineChart, BarChart, /* ... */ } from "semiotic/ai"
+
+const COMPONENT_MAP = { LineChart, BarChart, /* ... */ }
+function SuggestedChart({ data, intent }) {
+  const { suggestions } = useChartSuggestions(data, { intent })
+  const top = suggestions[0]
+  if (!top) return null
+  const Component = COMPONENT_MAP[top.component]
+  return <Component {...top.props} />
+}
+```
+
 
 ## AI Behavior Contracts
 

package/README.md

@@ -35,7 +35,7 @@ generate correct code without examples.
 Semiotic ships with everything an AI coding assistant needs to generate
 correct visualizations without trial and error:
 
-- **`semiotic/ai`** — a single import with 41 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
+- **`semiotic/ai`** — a single import with 42 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
 - **`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
@@ -287,18 +287,18 @@ Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **85 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **68 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **63 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **51 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **90 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
-| `semiotic/server` | **117 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/xy` | **86 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **70 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **64 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **52 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **91 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/server` | **122 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
 | `semiotic/utils` | **22 KB** | ThemeProvider, validators, serialization — no chart components |
 | `semiotic/recipes` | **5 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
 | `semiotic/themes` | **4 KB** | Theme presets only (tufte, carbon, etc.) |
 | `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
-| `semiotic/ai` | **188 KB** | All 41 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **186 KB** | Everything below (full bundle) |
+| `semiotic/ai` | **211 KB** | All 42 HOCs + validation — optimized for LLM code generation |
+| `semiotic` | **190 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -389,8 +389,14 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 | Tool | Description |
 |------|-------------|
 | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string or validation errors with fix suggestions. |
-| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 45 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
-| **`suggestChart`** | Recommend chart types for a data sample. Pass `{ data: [{...}, ...] }` with 1–5 sample objects. Optionally include `intent` (`"comparison"`, `"trend"`, `"distribution"`, `"relationship"`, `"composition"`, `"geographic"`, `"network"`, `"hierarchy"`). Returns ranked suggestions with example props. |
+| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 46 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
+| **`suggestChart`** | Legacy sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
+| **`suggestCharts`** | Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props. |
+| **`suggestStreamCharts`** | Recommend realtime charts from a stream schema, throughput, and retention hints. |
+| **`suggestDashboard`** | Build a multi-panel dashboard suggestion that covers distinct analytical intents. |
+| **`suggestStretchCharts`** | Recommend audience-literacy stretch picks from an `AudienceProfile`. |
+| **`repairChartConfig`** | Check whether a requested chart fits a dataset and return ranked alternatives when it does not. |
+| **`interrogateChart`** | Return a statistical summary and chart-aware context for answering natural-language questions with optional annotations. |
 | **`diagnoseConfig`** | Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes. |
 | **`reportIssue`** | Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass `{ title: "...", body: "...", labels: ["bug"] }`. Returns a URL the user can open to submit. |
 | **`applyTheme`** | List named theme presets or return ThemeProvider/CSS/token usage for a preset such as `{ name: "tufte" }`. |
@@ -401,6 +407,7 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 |----------|-------------|
 | **`semiotic://schema`** | Full machine-readable component schema JSON. |
 | **`semiotic://components`** | Component index showing renderable/browser-only status and MCP categories. |
+| **`semiotic://behavior-contracts`** | Agent-visible semantic rules for color precedence, required prop combinations, push refs, and renderability. |
 | **`semiotic://system-prompt`** | Compact AI instructions with import rules, chart props, SSR guidance, and pitfalls. |
 | **`semiotic://examples`** | Copy-paste chart examples by data shape. |
 
@@ -502,7 +509,7 @@ Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Cl
 
 Agent-facing API surface:
 
-- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (45 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
+- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (46 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
 - [**`semiotic.nteract.io/llms.txt`**](https://semiotic.nteract.io/llms.txt) + [**`/llms-full.txt`**](https://semiotic.nteract.io/llms-full.txt) — deployed at the docs site per the [llms.txt standard](https://llmstxt.org). Agents fetch the navigation map (`llms.txt`) or the full inlined docs (`llms-full.txt`) over HTTP; they're not part of the npm package itself.
 
 ## Documentation

package/ai/componentMetadata.cjs

@@ -21,7 +21,7 @@ const COMPONENTS_BY_CATEGORY = {
     "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram",
   ],
   realtime: [
-    "RealtimeLineChart", "RealtimeHistogram", "RealtimeSwarmChart",
+    "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart",
     "RealtimeWaterfallChart", "RealtimeHeatmap",
   ],
 }
@@ -52,11 +52,18 @@ function importPathForCategory(category) {
 function metadataForComponent(entryOrName) {
   const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name
   const category = categoryForComponent(name)
+  // Realtime push-streaming charts are browser-only by design.
+  // TemporalHistogram is the static-data sibling living in the
+  // "realtime" category for documentation grouping — it accepts a
+  // bounded data array and is renderable through the SSR path like
+  // any other static HOC. Matches the name-prefix exclusion the
+  // check-surface-parity script applies.
+  const isPushOnly = category === "realtime" && name.startsWith("Realtime")
   return {
     name,
     category,
     importPath: importPathForCategory(category),
-    renderable: category !== "realtime",
+    renderable: !isPushOnly,
     description: typeof entryOrName === "string" ? undefined : entryOrName.description,
   }
 }

package/ai/dist/mcp-server.js

@@ -6943,6 +6943,7 @@ var require_componentMetadata = __commonJS({
       realtime: [
         "RealtimeLineChart",
         "RealtimeHistogram",
+        "TemporalHistogram",
         "RealtimeSwarmChart",
         "RealtimeWaterfallChart",
         "RealtimeHeatmap"
@@ -6970,11 +6971,12 @@ var require_componentMetadata = __commonJS({
     function metadataForComponent2(entryOrName) {
       const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name;
       const category = categoryForComponent(name);
+      const isPushOnly = category === "realtime" && name.startsWith("Realtime");
       return {
         name,
         category,
         importPath: importPathForCategory(category),
-        renderable: category !== "realtime",
+        renderable: !isPushOnly,
         description: typeof entryOrName === "string" ? void 0 : entryOrName.description
       };
     }
@@ -32363,6 +32365,7 @@ var COMPONENT_REGISTRY = {
   QuadrantChart: { component: import_ai.QuadrantChart, category: "xy" },
   MultiAxisLineChart: { component: import_ai.MultiAxisLineChart, category: "xy" },
   CandlestickChart: { component: import_ai.CandlestickChart, category: "xy" },
+  TemporalHistogram: { component: import_ai.TemporalHistogram, category: "xy" },
   BarChart: { component: import_ai.BarChart, category: "ordinal" },
   StackedBarChart: { component: import_ai.StackedBarChart, category: "ordinal" },
   GroupedBarChart: { component: import_ai.GroupedBarChart, category: "ordinal" },
@@ -32740,6 +32743,166 @@ Dark-mode presets: ${THEME_PRESET_NAMES.filter((n) => n.includes("dark")).join("
     content: [{ type: "text", text: usage.join("\n") }]
   };
 }
+async function suggestChartsHandler(args) {
+  const { data, intent, maxResults, allow, deny, audience } = args;
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const suggestions = (0, import_ai3.suggestCharts)(data, {
+    intent: intentArg,
+    allow,
+    deny,
+    maxResults: maxResults ?? 8,
+    audience
+  });
+  const lines = [
+    `${suggestions.length} suggestion${suggestions.length === 1 ? "" : "s"} for ${data.length} rows${intentArg ? ` (intent: ${intentArg.join(", ")})` : ""}:`,
+    "",
+    ...suggestions.map((s, i) => {
+      const variantTag = s.variant ? ` / ${s.variant.label}` : "";
+      const reasons = s.reasons.length ? ` \u2014 ${s.reasons.join("; ")}` : "";
+      const caveats = s.caveats.length ? `
+   caveats: ${s.caveats.join("; ")}` : "";
+      return `${i + 1}. ${s.component}${variantTag} (score ${s.score.toFixed(1)}/5, familiarity ${s.rubric.familiarity}, accuracy ${s.rubric.accuracy})${reasons}${caveats}`;
+    })
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { suggestions }
+  };
+}
+async function suggestStreamChartsHandler(args) {
+  const { schema: schema2, intent, maxResults } = args;
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const suggestions = (0, import_ai3.suggestStreamCharts)(schema2, {
+    intent: intentArg,
+    maxResults: maxResults ?? 8
+  });
+  const lines = [
+    `${suggestions.length} stream chart suggestion${suggestions.length === 1 ? "" : "s"}${intentArg ? ` (intent: ${intentArg.join(", ")})` : ""}`,
+    ...schema2.throughput ? [`throughput: ${schema2.throughput}`] : [],
+    ...schema2.retention ? [`retention: ${schema2.retention}`] : [],
+    "",
+    ...suggestions.map((s, i) => {
+      const reasons = s.reasons.length ? ` \u2014 ${s.reasons.join("; ")}` : "";
+      const caveats = s.caveats.length ? `
+   caveats: ${s.caveats.join("; ")}` : "";
+      return `${i + 1}. ${s.component} (score ${s.score.toFixed(1)}/5)${reasons}${caveats}`;
+    })
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { suggestions, schema: schema2 }
+  };
+}
+async function suggestDashboardHandler(args) {
+  const { data, intents, maxPanels, diversifyByFamily, audience } = args;
+  const dashboard = (0, import_ai3.suggestDashboard)(data, {
+    intents,
+    maxPanels: maxPanels ?? 6,
+    diversifyByFamily: diversifyByFamily !== false,
+    audience
+  });
+  const lines = [];
+  lines.push(`Dashboard: ${dashboard.panels.length} panels covering ${dashboard.intentsCovered.join(", ") || "\u2014"}`);
+  if (dashboard.intentsMissing.length) {
+    lines.push(`Intents this data couldn't fill: ${dashboard.intentsMissing.join(", ")}`);
+  }
+  lines.push("");
+  for (let i = 0; i < dashboard.panels.length; i++) {
+    const { intent, suggestion } = dashboard.panels[i];
+    const variantTag = suggestion.variant ? ` / ${suggestion.variant.label}` : "";
+    lines.push(`${i + 1}. [${intent}] ${suggestion.component}${variantTag} (score ${suggestion.score.toFixed(1)}/5)`);
+    if (suggestion.reasons.length) lines.push(`   ${suggestion.reasons.join("; ")}`);
+  }
+  if (dashboard.stretchPanels.length > 0) {
+    lines.push("");
+    lines.push(`Stretch picks (audience-unfamiliar but fitting):`);
+    for (const stretch of dashboard.stretchPanels) {
+      const variantTag = stretch.suggestion.variant ? ` / ${stretch.suggestion.variant.label}` : "";
+      lines.push(`  ${stretch.suggestion.component}${variantTag} (familiarity ${stretch.familiarity}) \u2014 ${stretch.rationale}`);
+    }
+  }
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: dashboard
+  };
+}
+async function suggestStretchChartsHandler(args) {
+  const { data, audience, intent, maxResults } = args;
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const stretches = (0, import_ai3.suggestStretchCharts)(data, {
+    audience,
+    intent: intentArg,
+    maxResults: maxResults ?? 5
+  });
+  const lines = [
+    `${stretches.length} stretch pick${stretches.length === 1 ? "" : "s"} for "${audience.name ?? "audience"}":`,
+    "",
+    ...stretches.map((s, i) => {
+      const variantTag = s.suggestion.variant ? ` / ${s.suggestion.variant.label}` : "";
+      const replacing = s.replacing ? ` (could replace ${s.replacing})` : "";
+      return `${i + 1}. ${s.suggestion.component}${variantTag} (familiarity ${s.familiarity}/5)${replacing}
+   ${s.rationale}`;
+    })
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { stretches, audience: audience.name ?? null }
+  };
+}
+async function repairChartConfigHandler(args) {
+  const { component, data, intent, maxAlternatives } = args;
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const result = (0, import_ai3.repairChartConfig)(component, data, {
+    intent: intentArg,
+    maxAlternatives: maxAlternatives ?? 3
+  });
+  const lines = [];
+  if (result.status === "ok") {
+    lines.push(`\u2705 ${component} fits this dataset \u2014 no repair needed.`);
+  } else if (result.status === "alternative") {
+    lines.push(`\u26A0 ${component} doesn't fit: ${result.reason}`);
+    lines.push("");
+    lines.push(`Alternatives that fit${intentArg ? ` (ranked by intent: ${intentArg.join(", ")})` : ""}:`);
+    for (let i = 0; i < result.alternatives.length; i++) {
+      const s = result.alternatives[i];
+      const variantTag = s.variant ? ` / ${s.variant.label}` : "";
+      const reasons = s.reasons.length ? ` \u2014 ${s.reasons.join("; ")}` : "";
+      lines.push(`${i + 1}. ${s.component}${variantTag} (score ${s.score.toFixed(1)}/5)${reasons}`);
+    }
+  } else {
+    lines.push(`\u2753 No capability registered for "${component}". Closest matches:`);
+    for (let i = 0; i < result.alternatives.length; i++) {
+      const s = result.alternatives[i];
+      lines.push(`${i + 1}. ${s.component} (${s.family}, score ${s.score.toFixed(1)}/5)`);
+    }
+  }
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: result
+  };
+}
+async function interrogateChartHandler(args) {
+  const { component, props, query } = args;
+  const data = props.data || props.nodes || [];
+  const summary = (0, import_ai3.summarizeData)(data);
+  const content = [
+    { type: "text", text: `Statistical summary for ${component}:
+${JSON.stringify(summary, null, 2)}` }
+  ];
+  if (query) {
+    content.push({
+      type: "text",
+      text: `User Question: "${query}"
+
+Contextual instructions:
+1. Analyze the statistical summary to answer the question.
+2. Return a natural language response.
+3. Optionally suggest a JSON array of Semiotic annotations to visually highlight the answer on the chart (e.g. { type: "callout", x: "Mar", y: 1500, label: "Peak month" }).
+4. Use the accessor names from the provided props (e.g. xAccessor, yAccessor).`
+    });
+  }
+  return { content, structuredContent: { summary, component, props } };
+}
 function createServer2() {
   const srv = new McpServer({
     name: "semiotic",
@@ -32819,7 +32982,7 @@ function createServer2() {
       "Use this MCP workflow:",
       "1. Read semiotic://system-prompt for compact API rules and pitfalls.",
       "2. Read semiotic://behavior-contracts for semantic rules that schema shape alone cannot express.",
-      "3. If no component is specified, call suggestChart with 1-5 representative sample rows and the intent.",
+      "3. If no component is specified, call suggestCharts with representative rows and the intent.",
       "4. Call getSchema for the selected component before writing JSX or renderChart props.",
       '5. Call diagnoseConfig with usageMode="static" for renderChart/static data, or usageMode="push" for ref-based React code that intentionally omits data.',
       "6. Fix all diagnoseConfig errors before presenting code.",
@@ -32924,6 +33087,93 @@ function createServer2() {
     },
     applyThemeHandler
   );
+  srv.tool(
+    "interrogateChart",
+    "Conversational interrogation of a Semiotic chart. Extract a statistical summary and answer natural language questions about the data, trends, and outliers. Returns a summary and guidance for an AI to generate a textual answer and visual annotations.",
+    {
+      component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).describe("The full chart props including data"),
+      query: external_exports3.string().optional().describe("A natural language question about the chart data")
+    },
+    interrogateChartHandler
+  );
+  srv.tool(
+    "suggestStreamCharts",
+    "Recommend realtime/streaming Semiotic charts for a schema (not row data). Pass a schema describing field types plus optional throughput ('low'|'medium'|'high') and retention ('windowed'|'cumulative') hints; the engine ranks realtime charts (RealtimeLineChart, RealtimeHistogram, RealtimeHeatmap, RealtimeWaterfallChart, RealtimeSwarmChart, TemporalHistogram) by their fit. Use when the user is wiring up a live dashboard or monitoring view rather than visualizing a bounded dataset.",
+    {
+      schema: external_exports3.object({
+        fields: external_exports3.array(
+          external_exports3.object({
+            name: external_exports3.string(),
+            kind: external_exports3.enum(["numeric", "categorical", "date", "boolean"]),
+            role: external_exports3.enum(["x", "y", "value", "category", "series", "size"]).optional()
+          })
+        ),
+        throughput: external_exports3.enum(["low", "medium", "high"]).optional(),
+        retention: external_exports3.enum(["windowed", "cumulative"]).optional()
+      }).describe("Stream schema \u2014 fields plus throughput/retention hints. No row data."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent."),
+      maxResults: external_exports3.number().int().min(1).max(20).optional()
+    },
+    suggestStreamChartsHandler
+  );
+  srv.tool(
+    "suggestDashboard",
+    "Generate a dashboard of complementary chart panels for a dataset \u2014 each panel answers a distinct analytical intent (trend, rank, distribution, correlation, etc.) and the engine diversifies by chart family by default. Heuristic only; no LLM call. Use when the user asks 'show me this data' or 'build me a dashboard' rather than picking one chart.",
+    {
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).describe("Row data \u2014 array of objects."),
+      intents: external_exports3.array(external_exports3.string()).optional().describe("Intents to cover. Omit to let the engine pick based on the data shape."),
+      maxPanels: external_exports3.number().int().min(1).max(12).optional().describe("Maximum panels (default 6)."),
+      diversifyByFamily: external_exports3.boolean().optional().describe("Prefer not to repeat chart families across panels (default true).")
+    },
+    suggestDashboardHandler
+  );
+  srv.tool(
+    "suggestStretchCharts",
+    "Recommend literacy-growth chart picks for a dataset given an AudienceProfile. Returns charts the data supports but the audience is unfamiliar with (familiarity \u2264 3, or \u2264 4 at exposureLevel 2), each paired with the familiar chart it could substitute for and a rationale. Use when the consumer wants to gently expose users to less familiar but more analytically appropriate visualizations.",
+    {
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).describe("Row data."),
+      audience: external_exports3.object({
+        name: external_exports3.string().optional(),
+        familiarity: external_exports3.record(external_exports3.string(), external_exports3.number()).optional(),
+        targets: external_exports3.record(
+          external_exports3.string(),
+          external_exports3.object({
+            direction: external_exports3.enum(["increase", "decrease"]),
+            weight: external_exports3.number().int().min(1).max(3).optional(),
+            reason: external_exports3.string().optional()
+          })
+        ).optional(),
+        exposureLevel: external_exports3.union([external_exports3.literal(0), external_exports3.literal(1), external_exports3.literal(2)]).optional()
+      }).describe("Audience profile \u2014 familiarity, targets, exposure level."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional(),
+      maxResults: external_exports3.number().int().min(1).max(20).optional()
+    },
+    suggestStretchChartsHandler
+  );
+  srv.tool(
+    "repairChartConfig",
+    "Validate that a chart component is a sensible choice for a dataset, and if not, propose alternatives that fit. Use when a user asks for a specific chart and you want to confirm it's appropriate, or when you've drafted a config and want to verify it. Returns either ok (no change needed), alternative (chart doesn't fit; here are ranked replacements with rationale), or unknown (no capability registered).",
+    {
+      component: external_exports3.string().describe("Chart component name to validate, e.g. 'PieChart'"),
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).describe("Row data \u2014 array of objects."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("User intent \u2014 informs ranking of alternatives when the chart doesn't fit."),
+      maxAlternatives: external_exports3.number().int().min(1).max(10).optional().describe("Cap on alternatives returned (default 3).")
+    },
+    repairChartConfigHandler
+  );
+  srv.tool(
+    "suggestCharts",
+    "Recommend Semiotic charts for a dataset using heuristic capability descriptors. Each chart declares which data shapes it serves and which intents (trend, compare-categories, distribution, correlation, part-to-whole, etc.) it answers \u2014 the engine returns a ranked list with scores, reasons, caveats, and ready-to-use props. Heuristic only; no LLM call. Use the result as structured context when answering 'what chart should I use?' or generating chart code.",
+    {
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).describe("Row data \u2014 array of objects."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent. One of: trend, compare-series, compare-categories, rank, part-to-whole, distribution, correlation, flow, hierarchy, geo, outlier-detection, composition-over-time, change-detection. Custom intents accepted."),
+      maxResults: external_exports3.number().int().min(1).max(40).optional().describe("Cap on suggestions returned (default 8)."),
+      allow: external_exports3.array(external_exports3.string()).optional().describe("Restrict to these component names."),
+      deny: external_exports3.array(external_exports3.string()).optional().describe("Exclude these component names.")
+    },
+    suggestChartsHandler
+  );
   return srv;
 }
 var cliArgs = process.argv.slice(2);
@@ -32970,7 +33220,7 @@ async function main() {
     });
     httpServer.listen(port, () => {
       console.error(`Semiotic MCP server (HTTP) listening on http://localhost:${port}`);
-      console.error("Tools: getSchema, suggestChart, renderChart, diagnoseConfig, reportIssue, applyTheme");
+      console.error("Tools: getSchema, suggestChart, suggestCharts, suggestStreamCharts, suggestDashboard, suggestStretchCharts, repairChartConfig, renderChart, interrogateChart, diagnoseConfig, reportIssue, applyTheme");
       console.error("Resources: semiotic://schema, semiotic://components, semiotic://behavior-contracts, semiotic://system-prompt, semiotic://examples");
     });
   } else {

package/ai/examples.md

@@ -292,6 +292,33 @@ const data = [
 
 Key props: `orderAccessor` sequences points along the path, Viridis gradient from start→end
 
+### TemporalHistogram
+
+```jsx
+import { TemporalHistogram } from "semiotic/ai"
+
+// One row per event; the chart bins events into `binSize` time buckets.
+const events = [
+  { time: 1700000000000, value: 1, category: "errors" },
+  { time: 1700000005000, value: 1, category: "warnings" },
+  { time: 1700000007000, value: 1, category: "errors" },
+  { time: 1700000020000, value: 1, category: "info" },
+  { time: 1700000022000, value: 1, category: "info" },
+  { time: 1700000040000, value: 1, category: "errors" },
+  { time: 1700000045000, value: 1, category: "warnings" }
+]
+
+<TemporalHistogram
+  data={events}
+  binSize={15000}
+  categoryAccessor="category"
+  colors={{ errors: "#dc3545", warnings: "#fd7e14", info: "#007bff" }}
+  enableHover
+/>
+```
+
+Static-data sibling of `RealtimeHistogram` — accepts a bounded `data` array instead of a push-mode ref. Same props minus `windowSize` / `windowMode`. Use for backfilled or historical temporal histograms where the time range is fixed; reach for `RealtimeHistogram` when events arrive over time and you want a sliding window.
+
 ---
 
 ## Flat Array — Ordinal Charts