semiotic 3.7.0 → 3.7.2

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {

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` (90KB gz), `semiotic/ordinal` (74KB gz), `semiotic/network` (68KB gz), `semiotic/geo` (55KB gz), `semiotic/realtime` (95KB gz), `semiotic/server` (127KB gz), `semiotic/utils` (37KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (246KB gz). Full `semiotic` is 203KB gz.
+**Use sub-path imports** — `semiotic/xy` (90KB gz), `semiotic/ordinal` (74KB gz), `semiotic/network` (68KB gz), `semiotic/geo` (55KB gz), `semiotic/realtime` (95KB gz), `semiotic/server` (128KB gz), `semiotic/utils` (38KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (250KB gz). Full `semiotic` is 203KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
@@ -140,7 +140,7 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 
 ## Key Patterns
 - **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
-- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
+- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderChartWithEvidence()` returns `{ svg, evidence }` (mark counts by scene type, axis domains, empty flag, annotation count, accessible name) so agents can verify the render drew data marks. `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
 - **CLI**: `npx semiotic-ai --list` shows components/import paths/renderability; `npx semiotic-ai --schema GaugeChart` prints one component schema with metadata; `--doctor` validates props JSON and behavior contracts.
-- **MCP**: `npx semiotic-mcp` exposes tools (`getSchema`, `suggestChart`, `diagnoseConfig`, `renderChart`, `applyTheme`, `reportIssue`), resources (`semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`), and prompts (`build-semiotic-chart`, `debug-semiotic-chart`).
+- **MCP**: `npx semiotic-mcp` exposes schema, suggestion, diagnosis, accessibility, grounding, issue, theme, static render (`renderChart`), and ChatGPT Apps render (`renderInteractiveChart`) tools. Resources include `semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`, and the widget template `ui://semiotic/chart-widget.html`. Prompts: `build-semiotic-chart`, `debug-semiotic-chart`.
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/components/AccessibleNavTree.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 import { type NavTreeNode } from "./ai/navigationTree";
 export interface AccessibleNavTreeProps {
     tree: NavTreeNode;
@@ -22,4 +23,4 @@ export interface AccessibleNavTreeProps {
      */
     chartId?: string;
 }
-export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId }: AccessibleNavTreeProps): import("react/jsx-runtime").JSX.Element;
+export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId }: AccessibleNavTreeProps): React.JSX.Element;

package/dist/components/Annotation.d.ts

@@ -65,5 +65,5 @@ export interface AnnotationProps {
         [key: string]: unknown;
     };
 }
-export default function SemioticAnnotation(props: AnnotationProps): import("react/jsx-runtime").JSX.Element;
+export default function SemioticAnnotation(props: AnnotationProps): React.JSX.Element;
 export {};

package/dist/components/CategoryColors.d.ts

@@ -37,7 +37,7 @@ export interface CategoryColorProviderProps {
  * </CategoryColorProvider>
  * ```
  */
-export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
 export declare namespace CategoryColorProvider {
     var displayName: string;
 }

package/dist/components/ChartGrid.d.ts

@@ -33,7 +33,7 @@ export interface ChartGridProps {
  * </ChartGrid>
  * ```
  */
-export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
 export declare namespace ChartGrid {
     var displayName: string;
 }

package/dist/components/ContextLayout.d.ts

@@ -32,7 +32,7 @@ export interface ContextLayoutProps {
  * </ContextLayout>
  * ```
  */
-export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): import("react/jsx-runtime").JSX.Element;
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
 export declare namespace ContextLayout {
     var displayName: string;
 }

package/dist/components/DataSummaryContext.d.ts

@@ -6,7 +6,7 @@ interface DataSummaryState {
 }
 export declare function DataSummaryProvider({ children }: {
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export declare function useDataSummary(): DataSummaryState | null;
 export declare function useDataSummaryToggle(): (() => void) | null;
 export {};

package/dist/components/DetailsPanel.d.ts

@@ -32,7 +32,7 @@ export interface DetailsPanelProps {
     /** Inline style overrides */
     style?: React.CSSProperties;
 }
-export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): React.JSX.Element | null;
 export declare namespace DetailsPanel {
     var displayName: string;
 }

package/dist/components/Legend.d.ts

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

package/dist/components/LinkedCharts.d.ts

@@ -86,4 +86,4 @@ export declare function estimateLegendRowCount(labels: string[], width: number):
  * </LinkedCharts>
  * ```
  */
-export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): import("react/jsx-runtime").JSX.Element;
+export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): React.JSX.Element;

package/dist/components/ThemeProvider.d.ts

@@ -7,7 +7,7 @@ interface ThemeProviderProps {
     theme?: ThemePresetName | SemioticThemeUpdate;
     children: React.ReactNode;
 }
-declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): React.JSX.Element;
 declare function useTheme(): SemioticTheme;
 export { ThemeProviderWrapper as ThemeProvider, useTheme };
 export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME };

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -45,5 +45,5 @@ interface FlippingTooltipProps {
  *     guard, React throws `'NaN' is an invalid value for the 'top' css
  *     style property` and the entire frame stops rendering.
  */
-export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): React.JSX.Element | null;
 export {};

package/dist/components/Tooltip/Tooltip.d.ts

@@ -88,7 +88,7 @@ export declare const defaultTooltipStyle: React.CSSProperties;
  * />
  * ```
  */
-export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
+export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Create a multi-line tooltip that displays multiple fields
  *
@@ -131,7 +131,7 @@ export declare function Tooltip(config?: TooltipConfig): (data: Record<string, u
  * />
  * ```
  */
-export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
+export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Type for tooltip prop that chart components accept
  */

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

@@ -30,6 +30,8 @@ export interface PerCapabilityScore {
     rejectedOn: number;
     /** Number of fixtures where this capability appeared in the top-3 ranked suggestions. */
     inTopThreeOn: number;
+    /** Number of fixtures where this capability was the #1 ranked suggestion. */
+    topPickOn: number;
     /** Fixtures where the human expert picked this chart AND it was in top-3 ranking. */
     expertAgreementCount: number;
     /** Mean composite score across fixtures where it fit. */
@@ -58,6 +60,10 @@ export interface PerFixtureScore {
     rejectedCount: number;
     /** True if the top-3 ranking contained at least one expected component (when expected is provided). */
     expertAgreement: boolean | null;
+    /** True if the #1 ranked suggestion was an expected component — the strict
+     *  form of agreement. Reported alongside the lenient top-3 form so the
+     *  scorecard can't flatter itself with close-second behavior. */
+    topPickAgreement: boolean | null;
     /** Did the engine honor `expectsNoFit`? */
     noFitHonored: boolean | null;
 }
@@ -69,6 +75,11 @@ export interface ScorecardReport {
         capabilityCount: number;
         /** Fraction of expectation-bearing fixtures where the engine agreed with the expert. */
         expertAgreementRate: number;
+        /** Strict agreement: fraction of expectation-bearing fixtures where the
+         *  engine's #1 pick was an expert pick. Always reported next to the
+         *  lenient top-3 rate — the gap between the two is the honest measure of
+         *  how often the engine is merely "not completely wrong." */
+        top1AgreementRate: number;
         /** Average caveat coverage across all suggestions. */
         overallCaveatCoverage: number;
         /** Average variant utilization across all suggestions. */

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

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -138,7 +139,7 @@ export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseCh
  * `colorScheme`. For diverging data (positive/negative around zero), use
  * a diverging scheme name and pass `frameProps={{ colorDomain: [-max, max] }}`.
  */
-export declare function ChoroplethMap<TDatum extends Datum = Datum>(props: ChoroplethMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function ChoroplethMap<TDatum extends Datum = Datum>(props: ChoroplethMapProps<TDatum>): React.JSX.Element;
 export declare namespace ChoroplethMap {
     var displayName: string;
 }

package/dist/components/charts/network/CirclePack.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -63,7 +64,7 @@ export interface CirclePackProps<TNode extends Datum = Datum> extends BaseChartP
  * />
  * ```
  */
-export declare function CirclePack<TNode extends Datum = Datum>(props: CirclePackProps<TNode>): import("react/jsx-runtime").JSX.Element;
+export declare function CirclePack<TNode extends Datum = Datum>(props: CirclePackProps<TNode>): React.JSX.Element;
 export declare namespace CirclePack {
     var displayName: string;
 }

package/dist/components/charts/network/OrbitDiagram.d.ts

@@ -110,7 +110,7 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
  * />
  * ```
  */
-export declare function OrbitDiagram<TDatum extends Datum = Datum>(props: OrbitDiagramProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function OrbitDiagram<TDatum extends Datum = Datum>(props: OrbitDiagramProps<TDatum>): React.JSX.Element;
 export declare namespace OrbitDiagram {
     var displayName: string;
 }

package/dist/components/charts/network/TreeDiagram.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -65,7 +66,7 @@ export interface TreeDiagramProps<TNode extends Datum = Datum> extends BaseChart
  * />
  * ```
  */
-export declare function TreeDiagram<TNode extends Datum = Datum>(props: TreeDiagramProps<TNode>): import("react/jsx-runtime").JSX.Element;
+export declare function TreeDiagram<TNode extends Datum = Datum>(props: TreeDiagramProps<TNode>): React.JSX.Element;
 export declare namespace TreeDiagram {
     var displayName: string;
 }

package/dist/components/charts/network/Treemap.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -71,7 +72,7 @@ export interface TreemapProps<TNode extends Datum = Datum> extends BaseChartProp
  * />
  * ```
  */
-export declare function Treemap<TNode extends Datum = Datum>(props: TreemapProps<TNode>): import("react/jsx-runtime").JSX.Element;
+export declare function Treemap<TNode extends Datum = Datum>(props: TreemapProps<TNode>): React.JSX.Element;
 export declare namespace Treemap {
     var displayName: string;
 }

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -196,7 +196,7 @@ export interface TemporalHistogramProps<TDatum extends Datum = Datum> extends Om
  * bounded array rather than a ref-driven stream; the realtime push API is not
  * part of this public surface.
  */
-export declare function TemporalHistogram<TDatum extends Datum = Datum>(props: TemporalHistogramProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function TemporalHistogram<TDatum extends Datum = Datum>(props: TemporalHistogramProps<TDatum>): React.JSX.Element;
 export declare namespace TemporalHistogram {
     var displayName: string;
 }

package/dist/components/charts/shared/ChartError.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 export interface ChartErrorProps {
     /** Component name for the error message */
     componentName: string;
@@ -17,4 +18,4 @@ export interface ChartErrorProps {
  * Designed to be obvious in development but not alarming in production —
  * uses muted colors that adapt to light/dark backgrounds.
  */
-export default function ChartError({ componentName, message, diagnosticHint, width, height, }: ChartErrorProps): import("react/jsx-runtime").JSX.Element;
+export default function ChartError({ componentName, message, diagnosticHint, width, height, }: ChartErrorProps): React.JSX.Element;

package/dist/components/charts/shared/withChartWrapper.d.ts

@@ -20,7 +20,7 @@ interface SafeRenderProps {
  * map into every subpath import — it would add ~7KB gz to xy/ordinal/
  * network just to power a fallback that only fires when render throws.
  */
-export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): React.JSX.Element;
 /**
  * Renders a "No data available" placeholder when data is empty.
  * Returns null when data is present or emptyContent is `false`.

package/dist/components/charts/xy/MinimapChart.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
 import type { LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -128,7 +129,7 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
  * />
  * ```
  */
-export declare function MinimapChart<TDatum extends Datum = Datum>(props: MinimapChartProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function MinimapChart<TDatum extends Datum = Datum>(props: MinimapChartProps<TDatum>): React.JSX.Element;
 export declare namespace MinimapChart {
     var displayName: string;
 }

package/dist/components/charts/xy/ScatterplotMatrix.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends BaseChartProps {
@@ -81,7 +82,7 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
  * />
  * ```
  */
-export declare function ScatterplotMatrix<TDatum extends Datum = Datum>(props: ScatterplotMatrixProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function ScatterplotMatrix<TDatum extends Datum = Datum>(props: ScatterplotMatrixProps<TDatum>): React.JSX.Element;
 export declare namespace ScatterplotMatrix {
     var displayName: string;
 }

package/dist/components/semiotic-server.d.ts

@@ -1,4 +1,5 @@
-export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG, renderChart, renderToImage, renderDashboard, } from "./server/renderToStaticSVG";
+export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG, renderChart, renderChartWithEvidence, renderToImage, renderDashboard, } from "./server/renderToStaticSVG";
+export type { RenderEvidence } from "./server/renderEvidence";
 export type { RenderToImageOptions, DashboardChart, DashboardLayout, RenderDashboardOptions, } from "./server/renderToStaticSVG";
 export type { LegendLayout } from "./types/legendTypes";
 export { renderToAnimatedGif, generateFrameSVGs, generateFrameSequence } from "./server/animatedGif";

package/dist/components/server/renderEvidence.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Render evidence — machine-readable ground truth about what a server render
+ * actually produced, emitted from the same scene the SVG converter walks.
+ *
+ * The chart-reading literature's consistent failure mode is models
+ * hallucinating about what a chart contains — worst of all about what is
+ * *absent* from it. Render evidence is the artifact an agent can quote
+ * instead of trusting its eyes: did marks render, how many, of what kind,
+ * over what domains. It is computed during `renderChartWithEvidence`
+ * (`semiotic/server`) and returned alongside the SVG through the MCP
+ * `renderChart` tool, so repair loops can react to "this rendered zero data
+ * marks" without pixel inspection.
+ *
+ * Evidence reflects the *rendered scene*, never the input props — that is
+ * the point. A config can be valid and still render empty; evidence is how
+ * that difference becomes visible to a non-visual caller.
+ */
+export interface RenderEvidence {
+    /** HOC component name as passed to renderChart. */
+    component: string;
+    frameType: "xy" | "ordinal" | "network" | "geo";
+    /** "ok" when the scene produced data marks; "empty" when it did not. */
+    status: "ok" | "empty";
+    /** True when zero data marks rendered. */
+    empty: boolean;
+    /** Total data-mark scene nodes (grid/axes/legend chrome never counts). */
+    markCount: number;
+    /** Tally of scene nodes by their scene `type` (point, line, rect, …). */
+    markCountByType: Record<string, number>;
+    /** Outer SVG dimensions. */
+    width: number;
+    height: number;
+    /** Resolved numeric x-domain (XY frames; time domains in epoch ms). */
+    xDomain?: [number, number];
+    /** Resolved numeric y/value domain (XY + ordinal frames). */
+    yDomain?: [number, number];
+    /** Ordinal category domain, in render order. */
+    categories?: string[];
+    /** Network node / edge counts. */
+    nodeCount?: number;
+    edgeCount?: number;
+    /** Number of legend entries rendered (when a legend rendered). */
+    legendItems?: number;
+    /** Number of annotations supplied to the render. */
+    annotationCount: number;
+    /** The accessible name the SVG carries (description ?? title ?? generated). */
+    ariaLabel: string;
+    /** Stable warning codes (EMPTY_SCENE, NO_SCALES). */
+    warnings: string[];
+}
+/**
+ * Internal mutable slot threaded through the frame renderers. Only
+ * `renderChartWithEvidence` allocates one; the public string-returning
+ * render APIs pass nothing and pay nothing.
+ */
+export interface EvidenceSink {
+    evidence?: RenderEvidence;
+}
+/** Tally scene nodes by their `type` field. */
+export declare function tallyByType(nodes: ReadonlyArray<{
+    type?: string;
+}>): {
+    count: number;
+    byType: Record<string, number>;
+};
+/** Convert a d3 scale domain to a serializable [number, number], or undefined. */
+export declare function numericDomain(domain: ReadonlyArray<unknown> | undefined): [number, number] | undefined;
+interface BuildEvidenceInput {
+    frameType: RenderEvidence["frameType"];
+    width: number;
+    height: number;
+    marks: ReadonlyArray<{
+        type?: string;
+    }>;
+    /** Frame props type title/description as ReactNode; only string values
+     *  contribute to the accessible name (matching what wrapSVG emits as
+     *  <title>/<desc> text). */
+    title?: unknown;
+    description?: unknown;
+    annotations?: unknown;
+    xDomain?: [number, number];
+    yDomain?: [number, number];
+    categories?: string[];
+    nodeCount?: number;
+    edgeCount?: number;
+    legendItems?: number;
+    extraWarnings?: string[];
+}
+/** Assemble evidence from a computed scene. Component name is stamped later
+ *  by `renderChartWithEvidence`, which knows the HOC-level name. */
+export declare function buildEvidence(input: BuildEvidenceInput): RenderEvidence;
+export {};

package/dist/components/server/renderToStaticSVG.d.ts

@@ -20,6 +20,7 @@ import type { StreamXYFrameProps } from "../stream/types";
 import type { StreamNetworkFrameProps } from "../stream/networkTypes";
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
 import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import { type RenderEvidence } from "./renderEvidence";
 import { type ThemeInput } from "./themeResolver";
 import { CHART_CONFIGS } from "./serverChartConfigs";
 type FrameType = "xy" | "ordinal" | "network" | "geo";
@@ -60,7 +61,19 @@ interface RenderChartOptions {
  *
  * This is the primary API for AI/MCP workflows.
  */
-export declare function renderChart(component: ChartName, props: Datum, _options?: RenderChartOptions): string;
+export declare function renderChart(component: ChartName, props: Datum, options?: RenderChartOptions): string;
+/**
+ * Render a chart and return machine-readable evidence about what actually
+ * rendered — mark counts by scene type, resolved axis domains, emptiness,
+ * legend/annotation counts, and the accessible name. The evidence is computed
+ * from the same scene graph the SVG converter walks, so it is ground truth a
+ * non-visual caller (an agent repair loop, a CI assertion) can quote without
+ * pixel inspection. Exposed through the MCP `renderChart` tool response.
+ */
+export declare function renderChartWithEvidence(component: ChartName, props: Datum, options?: RenderChartOptions): {
+    svg: string;
+    evidence: RenderEvidence;
+};
 export interface RenderToImageOptions {
     /** Output format */
     format?: "png" | "jpeg";

package/dist/components/stream/AccessibleDataTable.d.ts

@@ -35,7 +35,7 @@ interface AccessibleDataTableProps {
  * computes a statistical summary (.describe()-style) and shows a sample of rows
  * (5 to start), pageable to the full dataset via "Show more".
  */
-export declare function AccessibleDataTable({ scene, chartType, tableId, chartTitle }: AccessibleDataTableProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AccessibleDataTable({ scene, chartType, tableId, chartTitle }: AccessibleDataTableProps): React.JSX.Element | null;
 interface NetworkAccessibleDataTableProps {
     nodes: Array<{
         datum?: any;
@@ -57,25 +57,25 @@ interface NetworkAccessibleDataTableProps {
 /**
  * JIT accessible data summary for network charts.
  */
-export declare function NetworkAccessibleDataTable({ nodes, edges, chartType, tableId, chartTitle }: NetworkAccessibleDataTableProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function NetworkAccessibleDataTable({ nodes, edges, chartType, tableId, chartTitle }: NetworkAccessibleDataTableProps): React.JSX.Element | null;
 /**
  * Screen-reader-only summary note for the chart.
  * Rendered as role="note" so assistive technology can discover it.
  */
 export declare function ScreenReaderSummary({ summary }: {
     summary?: string;
-}): import("react/jsx-runtime").JSX.Element | null;
+}): React.JSX.Element | null;
 /**
  * Screen-reader-only skip link to jump past chart canvas to the data table.
  * Only rendered when accessibleTable is enabled.
  */
 export declare function SkipToTableLink({ tableId }: {
     tableId: string;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 /**
  * Visually-hidden aria-live region that mirrors tooltip text for screen readers.
  */
 export declare function AriaLiveTooltip({ hoverPoint }: {
     hoverPoint: any;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export { SR_ONLY_STYLE };

package/dist/components/stream/FocusRing.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 /**
  * Shape-appropriate keyboard focus indicator for canvas-based charts.
  *
@@ -29,4 +30,4 @@ export interface FocusRingProps {
     /** Height of rect-shaped focus target */
     height?: number;
 }
-export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): React.JSX.Element | null;

package/dist/components/stream/MarginalGraphics.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { MarginalConfig, MarginalType } from "./types";
 export type MarginalOrient = "top" | "bottom" | "left" | "right";
@@ -15,4 +16,4 @@ export interface MarginalGraphicsProps {
 }
 /** Resolve a string shorthand or full config into a MarginalConfig */
 export declare function normalizeMarginalConfig(input: MarginalConfig | MarginalType): MarginalConfig;
-export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): React.JSX.Element | null;

package/dist/components/stream/NetworkCanvasHitTester.d.ts

@@ -1,4 +1,5 @@
-import type { NetworkSceneNode, NetworkSceneEdge } from "./networkTypes";
+import type { NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode } from "./networkTypes";
+import type { Quadtree } from "d3-quadtree";
 export interface NetworkHitResult {
     type: "node" | "edge";
     datum: any;
@@ -11,4 +12,4 @@ export interface NetworkHitResult {
  *
  * Checks nodes first (they're on top), then edges.
  */
-export declare function findNearestNetworkNode(sceneNodes: NetworkSceneNode[], sceneEdges: NetworkSceneEdge[], px: number, py: number, maxDistance?: number): NetworkHitResult | null;
+export declare function findNearestNetworkNode(sceneNodes: NetworkSceneNode[], sceneEdges: NetworkSceneEdge[], px: number, py: number, maxDistance?: number, nodeQuadtree?: Quadtree<NetworkCircleNode> | null, maxNodeRadius?: number): NetworkHitResult | null;

package/dist/components/stream/NetworkPipelineStore.d.ts

@@ -1,6 +1,7 @@
 import { ParticlePool } from "./ParticlePool";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
-import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
+import { type Quadtree } from "d3-quadtree";
+import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
 import type { Datum } from "../charts/shared/datumTypes";
 /**
  * NetworkPipelineStore — stateful store for the StreamNetworkFrame.
@@ -15,12 +16,28 @@ export declare class NetworkPipelineStore {
     nodes: Map<string, RealtimeNode>;
     edges: Map<string, RealtimeEdge>;
     tension: number;
+    /**
+     * Monotonic scene/layout-rebuild counter — Network's equivalent of the
+     * `version` field on the XY/Ordinal/Geo stores. Shared cross-store
+     * convention: bumps on every layout rebuild and on clear(); never resets to
+     * a prior value, so a consumer comparing against a last-seen value can
+     * always detect "something changed."
+     */
     layoutVersion: number;
     sceneNodes: NetworkSceneNode[];
     sceneEdges: NetworkSceneEdge[];
     labels: NetworkLabel[];
     /** Overlays returned from customNetworkLayout (consumed by StreamNetworkFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    private _nodeQuadtree;
+    private _maxNodeRadius;
+    /** Bumped whenever sceneNodes is rebuilt; keys the quadtree cache. */
+    private _sceneNodesRevision;
+    private _nodeQuadtreeRevision;
+    private static readonly QUADTREE_THRESHOLD;
+    private _nodesArrCache;
+    private _edgesArrCache;
+    private _arrCacheVersion;
     particlePool: ParticlePool | null;
     private config;
     private tensionConfig;
@@ -35,6 +52,8 @@ export declare class NetworkPipelineStore {
     private edgeTimestamps;
     /** Cached sorted node-timestamp entries for applyDecay(); null = needs rebuild */
     private _decaySortedNodes;
+    /** id→age-index map derived from _decaySortedNodes; rebuilt with it, not per frame. */
+    private _decayAgeMap;
     /** Node IDs added in the most recent layout */
     addedNodes: Set<string>;
     /** Node IDs removed in the most recent layout */
@@ -90,6 +109,32 @@ export declare class NetworkPipelineStore {
      * Build the scene graph from current layout positions.
      */
     buildScene(size: [number, number]): void;
+    /**
+     * Lazily (re)build the circle-node spatial index. Only built when the scene
+     * holds more than QUADTREE_THRESHOLD circle nodes (force/orbit graphs); for
+     * rect (sankey/treemap) and arc (chord) scenes — which carry far fewer marks
+     * and need area/angular hit logic — it stays null and the hit tester scans
+     * linearly. Always tracks `_maxNodeRadius` so the hit query can widen its
+     * search to cover the largest node.
+     */
+    private rebuildNodeQuadtree;
+    /**
+     * Circle-node spatial index for hit testing, or null when the scene is small
+     * or not circle-based. Rebuilt on demand only after the scene changed, so a
+     * settled graph indexes once and animation frames without a hover pay nothing.
+     */
+    get nodeQuadtree(): Quadtree<NetworkCircleNode> | null;
+    /** Largest circle-node radius in the current scene (widens the hit query). */
+    get maxNodeRadius(): number;
+    /**
+     * Per-frame-stable node/edge arrays (see field docs). Rebuilt only when
+     * layoutVersion changes — i.e. on a Map mutation, never on an animation tick.
+     */
+    private _ensureArrays;
+    /** Cached node array — safe only for read / position-mutate consumers. */
+    get nodesArray(): RealtimeNode[];
+    /** Cached edge array — safe only for read / position-mutate consumers. */
+    get edgesArray(): RealtimeEdge[];
     /** Whether the current layout plugin drives continuous animation (respects orbitAnimated config) */
     get isAnimating(): boolean;
     /**