semiotic 3.5.4 → 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` (69KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (189KB gz). Full `semiotic` is 188KB 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).
@@ -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` | **69 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **63 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `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` | **90 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
+| `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` | **189 KB** | All 41 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **188 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/dist/mcp-server.js

@@ -32743,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",
@@ -32822,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.",
@@ -32927,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);
@@ -32973,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/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.5.4",
+  "version": "3.6.0",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -880,7 +880,29 @@
             },
             "quadrants": {
               "type": "object",
-              "description": "Configuration for the four quadrants: { topRight, topLeft, bottomRight, bottomLeft }, each with { label, color, opacity? }"
+              "description": "Optional configuration overrides for the four quadrants: { topRight, topLeft, bottomRight, bottomLeft }, each with partial { label, color, opacity }. Omitted quadrants and fields use built-in defaults.",
+              "default": {
+                "topLeft": {
+                  "label": "Low / High",
+                  "color": "#E9C46A",
+                  "opacity": 0.08
+                },
+                "topRight": {
+                  "label": "High / High",
+                  "color": "#2A9D8F",
+                  "opacity": 0.08
+                },
+                "bottomLeft": {
+                  "label": "Low / Low",
+                  "color": "#E76F51",
+                  "opacity": 0.08
+                },
+                "bottomRight": {
+                  "label": "High / Low",
+                  "color": "#86BBD8",
+                  "opacity": 0.08
+                }
+              }
             },
             "showQuadrantLabels": {
               "type": "boolean",
@@ -913,9 +935,7 @@
               "default": 0.8
             }
           },
-          "required": [
-            "quadrants"
-          ]
+          "required": []
         }
       }
     },
@@ -2160,7 +2180,14 @@
             },
             "levels": {
               "type": "array",
-              "description": "Ordered response labels, most negative to most positive (required). Odd count = center is neutral."
+              "description": "Ordered response labels, most negative to most positive. Defaults to a 5-point Very Low to Very High scale. Odd count = center is neutral.",
+              "default": [
+                "Very Low",
+                "Low",
+                "Neutral",
+                "High",
+                "Very High"
+              ]
             },
             "categoryAccessor": {
               "type": [
@@ -2206,9 +2233,7 @@
               "default": 20
             }
           },
-          "required": [
-            "levels"
-          ]
+          "required": []
         }
       }
     },

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- 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` (69KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (189KB gz). Full `semiotic` is 188KB 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 -->
 
 ## Flat Array Data (`data: object[]`)

package/dist/components/ai/audienceProfile.d.ts

@@ -0,0 +1,90 @@
+import type { ChartRubric } from "./chartCapabilityTypes";
+/**
+ * A serializable description of who's reading the charts and what the
+ * organization is trying to grow.
+ *
+ * Semiotic does not measure familiarity — it consumes measurements. Orgs
+ * produce an AudienceProfile through whatever channel makes sense (surveys,
+ * telemetry, manager judgment, training records) and pass it to the
+ * suggestion APIs. The library applies the bias and returns rankings that
+ * reflect the audience instead of a generic data-literate baseline.
+ *
+ * Strategy memo: docs/strategy/audience-profiles.md
+ */
+export interface AudienceProfile {
+    /**
+     * Display name. Surfaced in suggestion `reasons[]` when a target fires so
+     * users can see whose policy is influencing the ranking.
+     */
+    name?: string;
+    /**
+     * Per-chart familiarity override (1..5). Replaces the descriptor's
+     * `rubric.familiarity`. Charts not listed fall back to the descriptor.
+     *
+     * @example
+     * familiarity: { BarChart: 5, LineChart: 5, PieChart: 4, BoxPlot: 2 }
+     */
+    familiarity?: Partial<Record<string, number>>;
+    /**
+     * Adoption targets — which charts the org is trying to grow or reduce.
+     * The engine applies a meaningful score bias (±1..3 depending on weight)
+     * so growth targets win close calls and decrease targets fall back unless
+     * they're the only fit.
+     *
+     * @example
+     * targets: {
+     *   PieChart: { direction: "decrease", weight: 1 },
+     *   BoxPlot:  { direction: "increase", weight: 2,
+     *               reason: "we want the team reading distributions, not means" }
+     * }
+     */
+    targets?: Partial<Record<string, AudienceTarget>>;
+    /**
+     * Controls visibility of stretch picks (unfamiliar-but-relevant charts).
+     *   0 — never surface stretches; familiar-only rankings
+     *   1 — surface in a separate `stretchSuggestions` list (default when audience set)
+     *   2 — same as 1 but lowers the familiarity threshold (≤4) for what counts as stretch,
+     *       widening the menu
+     */
+    exposureLevel?: 0 | 1 | 2;
+}
+export interface AudienceTarget {
+    direction: "increase" | "decrease";
+    /** 1..3 — controls bias magnitude. Default 1. */
+    weight?: number;
+    /** Human-readable rationale. Surfaces in suggestion.reasons when the target fires. */
+    reason?: string;
+}
+export interface AudienceBiasResult {
+    /** Composite score after audience adjustments. Unclamped — can range outside 0..5. */
+    score: number;
+    /** Effective rubric for the chart after audience overrides. */
+    rubric: ChartRubric;
+    /** Reason string to append to the suggestion when a target fired. */
+    appliedReason?: string;
+}
+/**
+ * Apply an AudienceProfile's bias to a chart's composite score and rubric.
+ * Pure function — used by both `suggestCharts` and `suggestStretchCharts`.
+ *
+ * Two terms compose additively:
+ *   • Familiarity bias: (audienceFamiliarity − 3) × 0.5
+ *     — Range ±1.0. At familiarity 5 we add 1.0; at 1 we subtract 1.0.
+ *   • Target bias: ±1.0 × weight
+ *     — Range ±3.0 for weight=3. Strong enough to reorder rankings,
+ *       not so strong that it overrides chart correctness for the data shape.
+ *
+ * Score is left unclamped so internal sorting reflects the magnitude of bias.
+ */
+export declare function applyAudienceBias(baseScore: number, baseRubric: ChartRubric, component: string, audience: AudienceProfile | undefined): AudienceBiasResult;
+/**
+ * Resolve the effective familiarity for a chart under an audience. Used by
+ * the stretch surface to decide whether a chart qualifies as "unfamiliar."
+ */
+export declare function effectiveFamiliarity(component: string, defaultFamiliarity: number, audience: AudienceProfile | undefined): number;
+/**
+ * Familiarity threshold for what counts as a "stretch" pick under this audience.
+ * Tighter for exposureLevel 1, wider for 2. Returns the highest familiarity a
+ * chart can have and still appear in the stretch surface.
+ */
+export declare function stretchFamiliarityCeiling(audience: AudienceProfile | undefined): number;