semiotic 3.5.4 → 3.7.0

package/ai/dist/mcp-server.js

@@ -6890,7 +6890,7 @@ var require_dist = __commonJS({
 var require_componentMetadata = __commonJS({
   "ai/componentMetadata.cjs"(exports2, module2) {
     "use strict";
-    var CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime"];
+    var CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "value"];
     var COMPONENTS_BY_CATEGORY = {
       xy: [
         "LineChart",
@@ -6947,6 +6947,9 @@ var require_componentMetadata = __commonJS({
         "RealtimeSwarmChart",
         "RealtimeWaterfallChart",
         "RealtimeHeatmap"
+      ],
+      value: [
+        "BigNumber"
       ]
     };
     var COMPONENT_TO_CATEGORY = /* @__PURE__ */ new Map();
@@ -6972,11 +6975,12 @@ var require_componentMetadata = __commonJS({
       const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name;
       const category = categoryForComponent(name);
       const isPushOnly = category === "realtime" && name.startsWith("Realtime");
+      const isValueCategory = category === "value";
       return {
         name,
         category,
         importPath: importPathForCategory(category),
-        renderable: !isPushOnly,
+        renderable: !isPushOnly && !isValueCategory,
         description: typeof entryOrName === "string" ? void 0 : entryOrName.description
       };
     }
@@ -32643,6 +32647,22 @@ ${contracts}` : msg}` }] };
     isError: true
   };
 }
+async function auditAccessibilityHandler(args) {
+  const component = args.component;
+  const props = args.props ?? {};
+  if (!component) {
+    return {
+      content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+      isError: true
+    };
+  }
+  const result = (0, import_ai3.auditAccessibility)(component, props, { inChartContainer: args.inChartContainer === true, describe: args.describe === true, navigable: args.navigable === true });
+  return {
+    content: [{ type: "text", text: (0, import_ai3.formatAccessibilityAudit)(result) }],
+    // Only block on provable critical failures; warnings/manual items are advisory.
+    isError: !result.ok
+  };
+}
 async function reportIssueHandler(args) {
   const title = args.title;
   const body = args.body;
@@ -32743,6 +32763,287 @@ Dark-mode presets: ${THEME_PRESET_NAMES.filter((n) => n.includes("dark")).join("
     content: [{ type: "text", text: usage.join("\n") }]
   };
 }
+function profileInputFromVariantArgs(args) {
+  const props = args.props ?? {};
+  if (Array.isArray(args.data)) {
+    return { data: args.data };
+  }
+  if (Array.isArray(props.data)) {
+    return { data: props.data };
+  }
+  if (Array.isArray(props.nodes) && (Array.isArray(props.edges) || Array.isArray(props.links))) {
+    return {
+      data: [],
+      rawInput: {
+        nodes: props.nodes,
+        edges: props.edges ?? props.links
+      }
+    };
+  }
+  if (props.data && typeof props.data === "object" && !Array.isArray(props.data)) {
+    return { data: [], rawInput: props.data };
+  }
+  return { data: [] };
+}
+function buildVariantProposalProps(proposal, profile, audience) {
+  if (proposal.buildProps) return proposal.buildProps(profile, audience);
+  const capability = (0, import_ai3.getCapability)(proposal.baseComponent);
+  const variant = proposal.variantKey ? capability?.variants?.find((v) => v.key === proposal.variantKey) : void 0;
+  return capability ? capability.buildProps(profile, variant) : {};
+}
+async function proposeChartVariantsHandler(args) {
+  const { component, intent, maxResults, audience } = args;
+  const capability = (0, import_ai3.getCapability)(component);
+  if (!capability) {
+    return {
+      content: [{ type: "text", text: `No chart capability registered for "${component}". Call suggestCharts first to pick from known capability components.` }],
+      isError: true
+    };
+  }
+  const { data, rawInput } = profileInputFromVariantArgs(args);
+  const profile = (0, import_ai3.profileData)(data, { rawInput });
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const fitReason = capability.fits(profile);
+  const proposals = (0, import_ai3.proposeVariant)(component, capability, {
+    profile,
+    audience,
+    intent: intentArg,
+    existingVariants: capability.variants
+  });
+  const ranked = proposals.map((proposal) => {
+    const score = (0, import_ai3.evaluateVariantProposal)(proposal, profile, audience, {
+      intent: intentArg,
+      baselineComponent: component
+    });
+    const { buildProps: _buildProps, ...proposalMeta } = proposal;
+    return {
+      proposal: proposalMeta,
+      score,
+      props: buildVariantProposalProps(proposal, profile, audience)
+    };
+  }).sort((a, b) => {
+    if (b.score.fit !== a.score.fit) return b.score.fit - a.score.fit;
+    if (a.score.risk !== b.score.risk) return a.score.risk - b.score.risk;
+    return b.score.novelty - a.score.novelty;
+  }).slice(0, maxResults ?? 8);
+  const lines = [
+    `${ranked.length} variant proposal${ranked.length === 1 ? "" : "s"} for ${component}${intentArg ? ` (intent: ${intentArg.join(", ")})` : ""}:`,
+    ...fitReason ? [`Base chart fit warning: ${fitReason}`] : [],
+    "",
+    ...ranked.map((entry, i) => {
+      const label = entry.proposal.label ?? entry.proposal.variantKey ?? entry.proposal.id;
+      const tags = entry.proposal.tags?.length ? ` [${entry.proposal.tags.join(", ")}]` : "";
+      const reasons = entry.score.reasons.length ? `
+   ${entry.score.reasons.join("; ")}` : "";
+      return `${i + 1}. ${entry.proposal.baseComponent} / ${label}${tags} (fit ${entry.score.fit.toFixed(1)}/5, novelty ${entry.score.novelty.toFixed(2)}, risk ${entry.score.risk.toFixed(2)})${reasons}`;
+    })
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: {
+      component,
+      profile: {
+        rowCount: profile.rowCount,
+        primary: profile.primary,
+        categoryCount: profile.categoryCount ?? null,
+        seriesCount: profile.seriesCount ?? null,
+        hasHierarchy: profile.hasHierarchy,
+        hasNetwork: profile.hasNetwork,
+        hasGeo: profile.hasGeo
+      },
+      fitReason,
+      proposals: ranked
+    }
+  };
+}
+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 } };
+}
+async function groundChartHandler(args) {
+  const component = args.component;
+  const props = args.props ?? {};
+  if (!component) {
+    return {
+      content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+      isError: true
+    };
+  }
+  const capability = (0, import_ai3.getCapability)(component);
+  const grounding = (0, import_ai3.buildReaderGrounding)(component, props, { capability });
+  const nodeCount = grounding.structure ? (0, import_ai3.countNodes)(grounding.structure) : 0;
+  const lines = [
+    `Reader grounding for ${component} \u2014 the payload an agent reads to interpret this chart without seeing it:`,
+    "",
+    `L1\u2013L3 (description): ${grounding.description.text}`,
+    grounding.intent ? `L4 (intent \xB7 ${grounding.intent.act}): ${grounding.intent.sentence}` : "L4 (intent): not resolved (no capability for this component).",
+    "",
+    `Structure: ${nodeCount} navigable node(s) (chart \u2192 axes/series \u2192 datum) in structuredContent.structure.`,
+    "",
+    "Combined text:",
+    grounding.text
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: grounding
+  };
+}
 function createServer2() {
   const srv = new McpServer({
     name: "semiotic",
@@ -32822,7 +33123,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.",
@@ -32909,6 +33210,18 @@ function createServer2() {
     },
     diagnoseConfigHandler
   );
+  srv.tool(
+    "auditAccessibility",
+    "Audit a Semiotic chart configuration against the Chartability (POUR-CAF) accessibility framework \u2014 Perceivable, Operable, Understandable, Robust, Compromising, Assistive, Flexible. Statically grades the config (no DOM/AT): credits the built-ins every HOC ships (keyboard nav, focus ring, skip link, screen-reader data table, reduced-motion + forced-colors, shareable state), flags author-actionable gaps (missing title/description/summary, low contrast, small text, color-only encoding, undescribed trends, data density), and routes everything that needs real assistive-technology testing to a 'manual' item. Returns a per-principle report with the 14 critical heuristics marked. Pass inChartContainer=true to credit data-download/share affordances. Pair with manual NVDA/JAWS/VoiceOver testing \u2014 Chartability is not a pass/fail certification.",
+    {
+      component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x', title: '...' }."),
+      inChartContainer: external_exports3.boolean().optional().describe("True if the chart is (or will be) wrapped in a ChartContainer exposing data-download/copy-config actions."),
+      describe: external_exports3.boolean().optional().describe("True if ChartContainer's describe option (auto-generated L1\u2013L3 description via describeChart) is enabled \u2014 passes the 'features described' heuristic."),
+      navigable: external_exports3.boolean().optional().describe("True if ChartContainer's navigable option (structured navigation tree via buildNavigationTree) is enabled \u2014 passes the 'navigable structure' heuristic.")
+    },
+    auditAccessibilityHandler
+  );
   srv.tool(
     "reportIssue",
     "Generate a GitHub issue URL for Semiotic bug reports or feature requests. Returns a URL the user can open to submit. For rendering bugs, include the component name, props summary, and any diagnoseConfig output in the body.",
@@ -32927,6 +33240,143 @@ 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(
+    "groundChart",
+    "Build the agent-reader grounding payload for a Semiotic chart: the layered L1\u2013L3 natural-language description, the L4 communicative-act sentence (what the chart is asking the reader to do \u2014 'this is an alerting chart; the spike warrants a closer look'), and a structured navigation tree (chart \u2192 axes/series \u2192 datum). This is the documented thing an LLM reads to interpret a chart faithfully without seeing the pixels \u2014 the reader-side complement to a capability descriptor. The L4 act is resolved from the chart's registered capability. Returns prose plus the full structured payload (description/intent/structure/text).",
+    {
+      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")
+    },
+    groundChartHandler
+  );
+  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(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel \u2014 see suggestCharts.")
+      }).describe("Audience profile \u2014 familiarity, targets, exposure level, reception modality."),
+      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(
+    "proposeChartVariants",
+    "Propose and score chart variants for a selected Semiotic component. Uses the capability registry plus heuristic variant discovery: registered variants, conservative transforms, and same-intent cross-family alternatives. Returns ranked proposals with fit/novelty/risk scores, rationale, and ready-to-use props. Use after suggestCharts when an agent wants to actively explore variants rather than stop at the first chart recommendation.",
+    {
+      component: external_exports3.string().describe("Base chart component to vary, e.g. 'LineChart', 'BarChart', or 'BoxPlot'."),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Existing chart props. If props.data is present it is profiled; network/hierarchy/geo object data can be passed here as raw input."),
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).optional().describe("Row data to profile. Overrides props.data when present."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent(s), e.g. trend, distribution, rank, compare-categories, composition-over-time."),
+      maxResults: external_exports3.number().int().min(1).max(20).optional().describe("Cap on proposals returned (default 8)."),
+      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(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel \u2014 see suggestCharts.")
+      }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
+    },
+    proposeChartVariantsHandler
+  );
+  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."),
+      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(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel. A non-visual value down-ranks charts the audience can't receive in that channel (e.g. a many-slice pie for a screen reader) and adds receivability caveats.")
+      }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
+    },
+    suggestChartsHandler
+  );
   return srv;
 }
 var cliArgs = process.argv.slice(2);
@@ -32973,7 +33423,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, proposeChartVariants, suggestStreamCharts, suggestDashboard, suggestStretchCharts, repairChartConfig, renderChart, interrogateChart, groundChart, diagnoseConfig, auditAccessibility, reportIssue, applyTheme");
       console.error("Resources: semiotic://schema, semiotic://components, semiotic://behavior-contracts, semiotic://system-prompt, semiotic://examples");
     });
   } else {

package/ai/examples.md

@@ -1181,3 +1181,101 @@ import { BarChart } from "semiotic/ai"
 ```
 
 Key props: `y-threshold` works on vertical ordinal charts. `category-highlight` highlights a category column. `labelPosition` controls label placement.
+
+---
+
+## Value Charts — One Number Is The Visualization
+
+### BigNumber (KPI tile — comparison + target + threshold zones)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue"
+  caption="Year-to-date bookings"
+  format="currency"
+  precision={0}
+  comparison={{ value: 980000, label: "vs Q2" }}
+  target={{ value: 1500000, label: "Q3 plan" }}
+  thresholds={[
+    { at: -Infinity, level: "danger"  },
+    { at: 1000000,   level: "warning" },
+    { at: 1300000,   level: "success" },
+  ]}
+/>
+```
+
+Key props: `value` (the one number), `format` ("number"|"currency"|"percent"|"compact"|"duration"|fn), `comparison` derives a delta with auto-sentiment, `target` renders "X% of goal", `thresholds` map value to a semantic theme role (`--semiotic-{success|warning|danger|info}`). Suppress chrome via `mode="thumbnail"` for dense grids or `mode="inline"` for prose. Stream via `ref.current.push({ value, time })` — pair with `stalenessThreshold` to dim the card when updates stop.
+
+### BigNumber with a Semiotic chart embedded via `trendSlot` (wide / rectangular)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+import { LineChart } from "semiotic/xy"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue"
+  format="currency"
+  comparison={{ value: 980000, label: "vs Q2" }}
+  trendSlot={(ctx) => (
+    <LineChart
+      data={[820000, 870000, 920000, 1010000, 1120000, 1284900].map((y, x) => ({ x, y }))}
+      xAccessor="x"
+      yAccessor="y"
+      mode="sparkline"
+      width={260}
+      height={32}
+      color={ctx.color}
+    />
+  )}
+/>
+```
+
+Key props: BigNumber ships NO built-in chart renderer. `trendSlot` accepts any ReactNode (or `(ctx) => ReactNode`); pass a `LineChart`/`AreaChart` in `mode="sparkline"` for wide / rectangular charts. The slot context exposes `ctx.color` (resolved threshold colour) so the embedded chart picks up the BigNumber's level for cohesive theming.
+
+### BigNumber with a square Semiotic chart via `chartSlot`
+
+```jsx
+import { BigNumber } from "semiotic/value"
+import { DonutChart } from "semiotic/ordinal"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue by region"
+  format="currency"
+  chartSlot={
+    <DonutChart
+      data={[
+        { region: "NA",   revenue: 540000 },
+        { region: "EU",   revenue: 420000 },
+        { region: "APAC", revenue: 324900 },
+      ]}
+      categoryAccessor="region"
+      valueAccessor="revenue"
+      width={120}
+      height={120}
+      innerRadius={32}
+    />
+  }
+/>
+```
+
+Key props: `chartSlot` is the square-aspect counterpart to `trendSlot`. The card splits horizontally — text content on the left, square chart on the right (DonutChart / PieChart / Scatterplot / Treemap / CirclePack). Pass both `trendSlot` and `chartSlot` to get the square chart on the right and the wide sparkline at the bottom.
+
+### BigNumber (inverted direction — lower is better)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+
+<BigNumber
+  value={486}
+  label="P99 latency"
+  suffix=" ms"
+  comparison={{ value: 410, label: "vs last week", direction: "lower-is-better" }}
+/>
+```
+
+Key props: `direction: "lower-is-better"` flips sentiment colouring — a value that went UP now reads as negative (danger). Same pattern for error rate, churn, complaint count, etc.