semiotic 3.5.4 → 3.7.0

package/dist/components/recipes/annotationLayout.d.ts

@@ -0,0 +1,93 @@
+import type { AnnotationContext } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+import { type AnnotationDensityConfig } from "./annotationDensity";
+export interface AnnotationLayoutConfig {
+    /** Distance from the anchor for the first candidate ring. */
+    defaultOffset?: number;
+    /** Gap around note boxes when testing note-note collisions. */
+    notePadding?: number;
+    /** Gap around point marks when testing note-mark collisions. */
+    markPadding?: number;
+    /** Gap from the plot edge, used as a cheap axis-occlusion proxy. */
+    edgePadding?: number;
+    /** Preserve annotations that already declare either dx or dy. Default true. */
+    preserveManualOffsets?: boolean;
+    /** Use a curved connector when auto-placement has to route far from the target. */
+    routeLongConnectors?: boolean;
+    /** Distance threshold for routeLongConnectors. */
+    connectorThreshold?: number;
+    /**
+     * M3 — amount & density management. When set, after placement the lowest-
+     * priority note-like annotations are shed so the plot is not over-crowded
+     * (`true` uses the area-derived default budget; an object tunes it). Reference
+     * lines, bands and overlays are never shed. Off by default.
+     */
+    density?: boolean | AnnotationDensityConfig;
+    /**
+     * M3 — progressive disclosure. When `true`, notes shed by `density` (M3) or
+     * the `responsive` breakpoint (M5) are kept in the output tagged
+     * `_annotationDeferred` (hidden by default, revealed on chart hover/focus)
+     * instead of dropped. The persistent set is always rendered, so a non-hover
+     * reader still sees the core notes. No effect unless a shedding pass is on.
+     */
+    progressiveDisclosure?: boolean;
+    /**
+     * M4 — redundant-cue default (Rahman et al.'s "Association"). A colored
+     * `text` note is the one note type that never draws a connector, so it ties
+     * to its target by color alone — invisible to a color-blind or non-visual
+     * reader. When `true`, an offset colored `text` note is flagged
+     * `_redundantConnector` so the renderer adds a faint leader line from the
+     * anchor to the text: a spatial cue, not another color. Off by default.
+     */
+    redundantCues?: boolean;
+    /**
+     * M5 — responsive annotation behavior. As the plot narrows past `minWidth`
+     * (default 480px), `secondary`-emphasis notes are shed by *importance* — a
+     * complement to `density`'s count budget. Pass `true` for the default
+     * breakpoint or `{ minWidth }` to tune it. With `progressiveDisclosure`,
+     * shed notes are deferred (revealable) rather than dropped. Primary and
+     * unmarked notes are always kept. Off by default.
+     */
+    responsive?: boolean | {
+        minWidth?: number;
+    };
+    /**
+     * M5 — cohesion mode (Rahman et al.'s "Cohesion"). `"blended"` lets notes
+     * adopt the chart's visual language (mark colors / chart typography — the
+     * default look); `"layer"` presents them as a distinct editorial layer
+     * (annotation-color, italic editorial type). Stamped onto note-like
+     * annotations that don't set their own `cohesion`; a per-annotation
+     * `cohesion` always wins. Off (inherit) by default.
+     */
+    cohesion?: AnnotationCohesion;
+    /**
+     * M6 — audience adaptation. An `AudienceProfile` (structurally, anything with
+     * a `familiarity` map) biases annotation *amount*: a low-familiarity audience
+     * keeps more notes (orienting context), an expert audience fewer. It scales
+     * the `density` budget, so it only takes effect when `density` is engaged.
+     */
+    audience?: AnnotationAudience;
+}
+export type AnnotationCohesion = "blended" | "layer";
+/** Structural subset of `AudienceProfile` the annotation layer reads — anything
+ *  with a per-chart `familiarity` map satisfies it, so a real `AudienceProfile`
+ *  can be passed directly without coupling `recipes` to the `ai` module. */
+export interface AnnotationAudience {
+    name?: string;
+    familiarity?: Partial<Record<string, number>>;
+}
+export type AutoPlaceAnnotationsConfig = AnnotationLayoutConfig;
+export type AutoPlaceAnnotations = boolean | AutoPlaceAnnotationsConfig;
+export interface AnnotationLayoutOptions extends AnnotationLayoutConfig {
+    annotations: ReadonlyArray<Datum>;
+    context: AnnotationContext;
+}
+/**
+ * Pure annotation placement recipe.
+ *
+ * It clones note-like annotations that do not already declare `dx`/`dy`, picks
+ * an adjacent candidate offset, and leaves every other annotation untouched.
+ * The pass is deterministic and geometry-only; renderers still own the actual
+ * SVG/HTML annotation drawing.
+ */
+export declare function annotationLayout(options: AnnotationLayoutOptions): Datum[];

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

@@ -41,6 +41,7 @@ export { RealtimeHistogram, TemporalHistogram } from "./charts/realtime/Realtime
 export { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 export { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 export { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
+export { BigNumber } from "./charts/value/BigNumber";
 export { TooltipProvider } from "./store/TooltipStore";
 export { MultiLineTooltip } from "./Tooltip/Tooltip";
 export { ThemeProvider, useTheme } from "./ThemeProvider";
@@ -59,6 +60,8 @@ export { validateProps } from "./charts/shared/validateProps";
 export type { ValidationResult } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
 export type { Diagnosis, DiagnosisResult } from "./charts/shared/diagnoseConfig";
+export { auditAccessibility, formatAccessibilityAudit, accessibilityCaveats } from "./charts/shared/auditAccessibility";
+export type { A11yPrinciple, A11yStatus, A11yFinding, AccessibilityAuditResult, AuditAccessibilityOptions } from "./charts/shared/auditAccessibility";
 export type { AnomalyConfig, ForecastConfig } from "./charts/shared/statisticalOverlays";
 export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from "./export/chartConfig";
 export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";
@@ -66,6 +69,61 @@ export { serializeSelections, deserializeSelections } from "./export/selectionSe
 export type { SerializedSelections, SerializedSelection, SerializedFieldSelection } from "./export/selectionSerializer";
 export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
+export { useChartInterrogation } from "./store/useChartInterrogation";
+export type { UseChartInterrogationOptions, UseChartInterrogationResult, InterrogationContext, InterrogationFocus, InterrogationResult, InterrogationQuery, InterrogationMessage } from "./store/useChartInterrogation";
+export { useChartFocus } from "./store/useChartFocus";
+export type { UseChartFocusOptions } from "./store/useChartFocus";
+export { summarizeData } from "./data/DataSummarizer";
+export { describeChart, resolveCommunicativeAct, communicativeActForIntent } from "./ai/describeChart";
+export type { DescribeChartResult, DescribeChartOptions, DescribeLevel, CommunicativeAct, DescribeCapabilityContext } from "./ai/describeChart";
+export { buildReaderGrounding } from "./ai/readerGrounding";
+export type { ChartReaderGrounding, ChartReaderGroundingOptions, ChartReaderGroundingIntent } from "./ai/readerGrounding";
+export { buildNavigationTree, flattenVisible, countNodes } from "./ai/navigationTree";
+export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
+export { AccessibleNavTree } from "./AccessibleNavTree";
+export type { AccessibleNavTreeProps } from "./AccessibleNavTree";
+export { useNavigationSync } from "./ai/useNavigationSync";
+export type { UseNavigationSyncOptions, UseNavigationSyncResult } from "./ai/useNavigationSync";
+export type { DataSummary, FieldSummary, FieldType, NumericFieldSummary, DateFieldSummary, CategoricalFieldSummary, UnknownFieldSummary, SummarizeOptions } from "./data/DataSummarizer";
+export { profileData } from "./ai/profileData";
+export type { ProfileDataOptions } from "./ai/profileData";
+export { suggestCharts, suggestChartsGrouped, scoreChart, explainCapabilityFit } from "./ai/suggestCharts";
+export type { SuggestChartsOptions, RejectedCapability, ExplainCapabilityFitResult } from "./ai/suggestCharts";
+export { DEFAULT_SCALE_THRESHOLDS, applyScaleBias, classifyRowBand, classifyCardinalityBand, classifyFieldBand, compareBands, computeEffectiveScale, resolveRowsToNumber, resolveCardinalityToNumber, scaleHints } from "./ai/dataScaleProfile";
+export type { DataScaleProfile, DataQualityProfile, ScaleBand, CardinalityBand, FieldBand, ScaleThresholds, ChartScalePreference, EffectiveScale, ScaleBiasResult, ScaleFitFn, ScaleFitResult, QualityFitFn, ScaleHintInput } from "./ai/dataScaleProfile";
+export { inferIntent } from "./ai/inferIntent";
+export type { InferIntentResult } from "./ai/inferIntent";
+export { suggestDashboard } from "./ai/suggestDashboard";
+export type { DashboardPanel, DashboardSuggestion, SuggestDashboardOptions } from "./ai/suggestDashboard";
+export { applyAudienceBias, effectiveFamiliarity, stretchFamiliarityCeiling, receivabilityBias } from "./ai/audienceProfile";
+export type { AudienceProfile, AudienceTarget, AudienceBiasResult, ReceptionModality, ReceivabilitySignal } from "./ai/audienceProfile";
+export { executivePersona, analystPersona, dataScientistPersona, BUILT_IN_AUDIENCES } from "./ai/audiences";
+export { suggestStretchCharts } from "./ai/suggestStretchCharts";
+export type { StretchSuggestion, SuggestStretchChartsOptions } from "./ai/suggestStretchCharts";
+export { suggestStreamCharts, registerStreamChartCapability, unregisterStreamChartCapability, getStreamCapabilities } from "./ai/suggestStreamCharts";
+export type { SuggestStreamChartsOptions } from "./ai/suggestStreamCharts";
+export type { StreamSchema, StreamFieldSchema, StreamFieldKind, StreamChartCapability, StreamIntentScorer, StreamSuggestion } from "./ai/streamingTypes";
+export { diffProfile } from "./ai/diffProfile";
+export type { ProfileDiff, FieldTypeChange, PrimaryRoleChange, PrimaryRole } from "./ai/diffProfile";
+export { repairChartConfig } from "./ai/repairChartConfig";
+export type { RepairResult, RepairOkResult, RepairAlternativeResult, RepairUnknownResult, RepairOptions } from "./ai/repairChartConfig";
+export { runQualityScorecard } from "./ai/qualityScorecard";
+export type { ScorecardFixture, ScorecardReport, PerCapabilityScore, PerFixtureScore } from "./ai/qualityScorecard";
+export { CANONICAL_FIXTURES } from "./ai/qualityFixtures";
+export { useChartSuggestions } from "./ai/useChartSuggestions";
+export type { UseChartSuggestionsOptions, UseChartSuggestionsResult } from "./ai/useChartSuggestions";
+export { getCapabilities, getCapability, registerChartCapability, unregisterChartCapability, LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability } from "./ai/chartCapabilities";
+export type { ChartCapability, ChartDataProfile, ChartFamily, ChartImportPath, ChartRubric, ChartVariant, FieldCandidate, FieldKind, FitResult, IntentScorer, ScaledSuggestionGroups, Suggestion, SuggestionScaleRange } from "./ai/chartCapabilityTypes";
+export { listIntents, getIntent, registerIntent, BUILT_IN_INTENT_IDS } from "./ai/intents";
+export type { BuiltInIntentId, IntentId, IntentDescriptor } from "./ai/intents";
+export { proposeVariant, evaluateVariantProposal, registerVariantDiscovery, getRegisteredVariantDiscovery, clearVariantDiscovery } from "./ai/variantDiscovery";
+export type { VariantProposal, VariantProposalSource, VariantScore, VariantRejectionReason, VariantDiscoveryContext, EvaluateVariantProposalOptions, ProposeVariantFn, EvaluateVariantProposalFn } from "./ai/variantDiscovery";
+export { withProvenance, withCurrentProvenance, currentTimestamp, computeAnnotationFreshness, applyAnnotationLifecycle, applyAnnotationStatus, filterAnnotationsByStatus, annotationFreshnessFor, bandFromAge, DEFAULT_LIFECYCLE_THRESHOLDS } from "./ai/annotationProvenance";
+export type { AnnotationProvenance, AnnotationSource, AnnotationActorKind, AnnotationBasis, AnnotationLifecycle, AnnotationFreshness, AnnotationStatus, AnnotationAnchor, Annotated, ComputeAnnotationFreshnessOptions, AnnotationLifecycleTreatment, ApplyAnnotationLifecycleOptions, AnnotationStatusTreatment, AnnotationStatusVisibility, LifecycleBand, LifecycleBandThresholds } from "./ai/annotationProvenance";
+export { useConversationArc, summarizeArc } from "./ai/useConversationArc";
+export type { UseConversationArcOptions, UseConversationArcResult, ConversationArcSummary } from "./ai/useConversationArc";
+export { enableConversationArc, disableConversationArc, getConversationArcStore, subscribeToConversationArcChange, registerConversationArcSink, createLocalStorageConversationArcSink, createIndexedDBConversationArcSink, createWebhookConversationArcSink, loadConversationArc, replayConversationArc, recordAudienceChange, recordAnnotationStatusChange } from "./ai/conversationArc";
+export type { ConversationArcEvent, ConversationArcEventType, ConversationArcEventInput, ConversationArcStore, ConversationArcListener, ConversationArcSink, ConversationArcStorageLike, EnableConversationArcOptions, LoadConversationArcOptions, LocalStorageConversationArcSinkOptions, IndexedDBConversationArcSinkOptions, ConversationArcWebhookFetch, WebhookConversationArcSinkOptions, SuggestionShownEvent, SuggestionChosenEvent, AudienceSetEvent, ChartRenderedEvent, ChartEditedEvent, ChartReplacedEvent, ChartExportedEvent, ChartAbandonedEvent, InterrogationAskedEvent, InterrogationAnsweredEvent, NavNodeFocusedEvent, NavBranchExpandedEvent, AnnotationStatusChangedEvent } from "./ai/conversationArc";
 export { useChartObserver } from "./store/useObservation";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
 export type { ChartObservation, OnObservationCallback, HoverObservation, HoverEndObservation, BrushObservation, BrushEndObservation, SelectionObservation, SelectionEndObservation, ClickObservation, ClickEndObservation } from "./store/ObservationStore";

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

@@ -22,3 +22,5 @@ export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType } from ".
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType } from "./stream/networkTypes";
 export { useStreamStatus } from "./charts/shared/useStreamStatus";
 export type { StreamStatus, StreamStatusOptions, StreamStatusResult, } from "./charts/shared/useStreamStatus";
+export { bandFromAge, DEFAULT_LIFECYCLE_THRESHOLDS } from "./realtime/lifecycleBands";
+export type { LifecycleBand, LifecycleBandThresholds } from "./realtime/lifecycleBands";

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

@@ -19,6 +19,10 @@ export { bulletLayout } from "./recipes/bullet";
 export type { BulletConfig } from "./recipes/bullet";
 export { parallelCoordinatesLayout } from "./recipes/parallelCoordinates";
 export type { ParallelCoordinatesConfig } from "./recipes/parallelCoordinates";
+export { annotationLayout } from "./recipes/annotationLayout";
+export type { AnnotationLayoutConfig, AnnotationLayoutOptions, AutoPlaceAnnotations, AutoPlaceAnnotationsConfig, AnnotationCohesion, AnnotationAudience, } from "./recipes/annotationLayout";
+export { annotationDensity, annotationBudget, DEFAULT_AREA_PER_ANNOTATION } from "./recipes/annotationDensity";
+export type { AnnotationDensityConfig, AnnotationDensityOptions, AnnotationDensityResult, } from "./recipes/annotationDensity";
 export type { CustomLayout, LayoutContext, LayoutResult, } from "./stream/customLayout";
 export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
 export type { OrdinalCustomLayout, OrdinalLayoutContext, OrdinalLayoutResult, } from "./stream/ordinalCustomLayout";

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

@@ -17,6 +17,14 @@ export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export { validateProps } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
+export { auditAccessibility, formatAccessibilityAudit, accessibilityCaveats } from "./charts/shared/auditAccessibility";
+export { describeChart, resolveCommunicativeAct, communicativeActForIntent } from "./ai/describeChart";
+export type { DescribeChartResult, DescribeChartOptions, DescribeLevel, CommunicativeAct, DescribeCapabilityContext } from "./ai/describeChart";
+export { buildNavigationTree, flattenVisible, countNodes } from "./ai/navigationTree";
+export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
+export { buildReaderGrounding } from "./ai/readerGrounding";
+export type { ChartReaderGrounding, ChartReaderGroundingOptions, ChartReaderGroundingIntent } from "./ai/readerGrounding";
+export type { A11yPrinciple, A11yStatus, A11yFinding, AccessibilityAuditResult, AuditAccessibilityOptions } from "./charts/shared/auditAccessibility";
 export { getHitRadius } from "./stream/hitTestUtils";
 export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from "./export/chartConfig";
 export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";

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

@@ -0,0 +1,55 @@
+/**
+ * semiotic/value — Focal-value visualizations.
+ *
+ * Charts that render *one* number rather than a coordinate space. At
+ * row counts of 1–3, a chart is usually the wrong abstraction — the
+ * scale-aware suggestion engine routes those datasets here.
+ *
+ * v1 ships `BigNumber` as a plain React component. The component is
+ * deliberately chart-dependency-free: consumers compose their own
+ * Semiotic chart (or any ReactNode) into the `trendSlot` (wide /
+ * rectangular charts, e.g. LineChart / AreaChart in sparkline mode) or
+ * `chartSlot` (square charts, e.g. DonutChart / PieChart / Scatterplot
+ * / Treemap). The slot context exposes the resolved threshold colour
+ * + sentiment + push buffer so embedded charts can theme-link.
+ *
+ * @example
+ * ```tsx
+ * import { BigNumber } from "semiotic/value"
+ * import { LineChart }  from "semiotic/xy"
+ * import { DonutChart } from "semiotic/ordinal"
+ *
+ * <BigNumber
+ *   value={1284900}
+ *   label="Q3 Revenue"
+ *   format="currency"
+ *   comparison={{ value: 980000, label: "vs Q2" }}
+ *   target={{ value: 1500000, label: "Q3 plan" }}
+ *   thresholds={[
+ *     { at: -Infinity, level: "danger"  },
+ *     { at: 1_000_000, level: "warning" },
+ *     { at: 1_300_000, level: "success" },
+ *   ]}
+ *   trendSlot={(ctx) => (
+ *     <LineChart
+ *       data={recentMonths.map((y, x) => ({ x, y }))}
+ *       xAccessor="x" yAccessor="y"
+ *       mode="sparkline"
+ *       width={260} height={32}
+ *       color={ctx.color}
+ *     />
+ *   )}
+ *   chartSlot={(ctx) => (
+ *     <DonutChart
+ *       data={revenueByRegion}
+ *       categoryAccessor="region" valueAccessor="revenue"
+ *       width={120} height={120}
+ *     />
+ *   )}
+ * />
+ * ```
+ */
+export { BigNumber, default as BigNumberDefault } from "./charts/value/BigNumber";
+export type { BigNumberProps, BigNumberHandle, BigNumberMode, BigNumberLevel, BigNumberDirection, BigNumberSentiment, BigNumberFormat, BigNumberThreshold, BigNumberComparison, BigNumberTarget, BigNumberPushInput, BigNumberSlot, BigNumberSlotContext } from "./charts/value/types";
+export { buildFormatter, formatSignedDelta, formatDeltaPercent, formatDuration } from "./charts/value/formatting";
+export { resolveThreshold, colorForLevel, buildSparklinePath } from "./charts/value/thresholdSparkline";

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

@@ -28,7 +28,7 @@ export type { ScatterplotProps } from "./charts/xy/Scatterplot";
 export type { ConnectedScatterplotProps } from "./charts/xy/ConnectedScatterplot";
 export type { BubbleChartProps } from "./charts/xy/BubbleChart";
 export type { HeatmapProps } from "./charts/xy/Heatmap";
-export type { QuadrantChartProps } from "./charts/xy/QuadrantChart";
+export type { QuadrantChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle } from "./charts/xy/QuadrantChart";
 export type { MultiAxisLineChartProps } from "./charts/xy/MultiAxisLineChart";
 export type { CandlestickChartProps } from "./charts/xy/CandlestickChart";
 export type { XYCustomChartProps } from "./charts/custom/XYCustomChart";

package/dist/components/semiotic.d.ts

@@ -25,7 +25,7 @@ import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
 export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, DifferenceChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, ProcessSankey, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
 export type { LegendLayout } from "./types/legendTypes";
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, SemanticGradientStop, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, SemanticGradientStop, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
 export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn, XYFrameAxisConfig, BandConfig } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";
@@ -44,6 +44,12 @@ export { COLOR_BLIND_SAFE_CATEGORICAL } from "./store/ThemeStore";
 export { themeToCSS, themeToTokens, resolveThemePreset, THEME_PRESETS, CARBON_CATEGORICAL_14, CARBON_ALERT } from "./semiotic-themes";
 export type { ThemePresetName } from "./semiotic-themes";
 export type { ChartErrorBoundaryProps } from "./ChartErrorBoundary";
+export { AccessibleNavTree } from "./AccessibleNavTree";
+export type { AccessibleNavTreeProps } from "./AccessibleNavTree";
+export { buildNavigationTree } from "./ai/navigationTree";
+export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
+export { useNavigationSync } from "./ai/useNavigationSync";
+export type { UseNavigationSyncOptions, UseNavigationSyncResult } from "./ai/useNavigationSync";
 export type { ChartContainerProps, ChartContainerHandle } from "./ChartContainer";
 export type { ChartGridProps } from "./ChartGrid";
 export type { CategoryColorMap, CategoryColorProviderProps } from "./CategoryColors";
@@ -62,3 +68,4 @@ export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps, TemporalHi
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";
 export type { RealtimeWaterfallChartProps } from "./charts/realtime/RealtimeWaterfallChart";
 export type { RealtimeHeatmapProps } from "./charts/realtime/RealtimeHeatmap";
+export type { AnnotationProvenance, AnnotationSource, AnnotationActorKind, AnnotationBasis, AnnotationLifecycle, AnnotationFreshness, AnnotationStatus, AnnotationAnchor, Annotated, } from "./ai/annotationProvenance";

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

@@ -7,6 +7,7 @@ import type { Datum } from "../charts/shared/datumTypes";
  */
 import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 interface AnnotationScales {
     x?: (v: any) => number;
     y?: (v: any) => number;
@@ -30,6 +31,7 @@ interface AnnotationLayout {
 }
 export interface StaticAnnotationConfig {
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     scales: AnnotationScales;
     layout: AnnotationLayout;
     theme: SemioticTheme;

package/dist/components/store/useChartFocus.d.ts

@@ -0,0 +1,43 @@
+import type { ChartObservation } from "./ObservationStore";
+import type { InterrogationFocus } from "./useChartInterrogation";
+export interface UseChartFocusOptions {
+    /** Limit attention to a specific chart instance. Required when the page has more than one. */
+    chartId?: string;
+    /**
+     * Which observation types count as "focused." Default is hover + click +
+     * selection — anything that signals user attention. Set to ["click"] for
+     * sticky-focus UIs where hover doesn't change the AI's reference point.
+     */
+    types?: ChartObservation["type"][];
+}
+/**
+ * Convenience hook: returns the latest `InterrogationFocus` for use with
+ * `useChartInterrogation`'s `focus` option. Internally subscribes to the
+ * observation store and converts the latest matching observation into the
+ * focus shape.
+ *
+ * Pair with `<Chart onObservation={…} chartId="myChart" />` and an
+ * `<ObservationProvider>` ancestor.
+ *
+ * Returns `null` when no qualifying observation has fired yet.
+ *
+ * @example
+ * function ChartWithChat({ data }) {
+ *   const focus = useChartFocus({ chartId: "sales" })
+ *   const { ask, history, annotations } = useChartInterrogation({
+ *     data,
+ *     focus,                    // ← latest hovered/clicked datum threads in
+ *     onQuery: async (q, ctx) => {
+ *       // ctx.focus is the same `focus` value passed above
+ *       return askLLM({ question: q, focus: ctx.focus, summary: ctx.summary })
+ *     },
+ *   })
+ *   return (
+ *     <>
+ *       <LineChart data={data} chartId="sales" annotations={annotations} />
+ *       <YourChatUI history={history} onAsk={ask} />
+ *     </>
+ *   )
+ * }
+ */
+export declare function useChartFocus(options?: UseChartFocusOptions): InterrogationFocus | null;

package/dist/components/store/useChartInterrogation.d.ts

@@ -0,0 +1,141 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type DataSummary } from "../data/DataSummarizer";
+import type { ChartDataProfile, Suggestion } from "../ai/chartCapabilityTypes";
+import type { IntentId } from "../ai/intents";
+/**
+ * Identifies a single point of interest on the chart — typically the datum
+ * the user is currently hovering, clicked, or otherwise focused on. When
+ * provided, the LLM gets the explicit signal that the user is asking
+ * "about *this specific point*" rather than the chart at large.
+ */
+export interface InterrogationFocus {
+    /** The row the user is focused on. */
+    datum: Datum;
+    /** Pixel x coordinate, when known. Useful for anchoring response annotations. */
+    x?: number;
+    /** Pixel y coordinate, when known. */
+    y?: number;
+    /** Optional source label — "hover" / "click" / "selection". Surfaces in the LLM prompt. */
+    source?: "hover" | "click" | "selection" | "manual";
+}
+export interface InterrogationContext {
+    /** The data extracted from the chart (or whatever caller passed in). */
+    data: ReadonlyArray<Datum>;
+    /** Statistical summary, ready to send to an LLM. */
+    summary: DataSummary;
+    /** Shape profile — present when `includeProfile` or `includeSuggestions` is enabled. */
+    profile?: ChartDataProfile;
+    /** Heuristic chart suggestions — present when `includeSuggestions` is enabled. */
+    suggestions?: ReadonlyArray<Suggestion>;
+    /** Optional caller-supplied chart component name (e.g. "LineChart"). */
+    componentName?: string;
+    /** Optional caller-supplied chart props (accessor names, scales, etc.). */
+    props?: Record<string, unknown>;
+    /**
+     * The current focused datum — what the user is interactively pointing at.
+     * Lets the LLM tailor responses to a specific point ("why is *this* one
+     * higher than the rest?") and to anchor visual responses (callouts,
+     * comments) back at the same coordinates.
+     */
+    focus?: InterrogationFocus;
+}
+export interface InterrogationResult {
+    /** Natural-language answer to display to the user. */
+    answer: string;
+    /** Optional Semiotic annotations to overlay on the chart. */
+    annotations?: ReadonlyArray<Datum>;
+}
+export type InterrogationQuery = (query: string, context: InterrogationContext) => Promise<InterrogationResult>;
+export interface InterrogationMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface UseChartInterrogationOptions {
+    /** Data backing the chart. Use whatever shape the chart consumes (rows, nodes, etc.). */
+    data: ReadonlyArray<Datum> | null | undefined;
+    /** Async handler — typically calls your LLM with the query + summary. */
+    onQuery: InterrogationQuery;
+    /** Annotations to seed the merged set (e.g. existing chart annotations). */
+    initialAnnotations?: ReadonlyArray<Datum>;
+    /** Optional context passed through to onQuery for richer prompts. */
+    componentName?: string;
+    /** Optional context passed through to onQuery. */
+    props?: Record<string, unknown>;
+    /**
+     * Include the shape `profile` in the interrogation context. Required to let an LLM
+     * reason about candidate axes, distinct counts, hierarchy/network/geo detection, etc.
+     */
+    includeProfile?: boolean;
+    /**
+     * Include heuristic chart `suggestions` in the interrogation context. Implies `includeProfile`.
+     * Lets an LLM answer "would another chart show this better?" without re-deriving rules.
+     */
+    includeSuggestions?: boolean;
+    /** When `includeSuggestions` is true, rank by this intent. */
+    suggestionsIntent?: IntentId | IntentId[];
+    /** When `includeSuggestions` is true, cap the suggestion list. Default 5. */
+    suggestionsMax?: number;
+    /**
+     * The point on the chart the user is currently focused on. Forwarded to
+     * onQuery so an LLM can answer "about this specific datum" rather than
+     * "about the chart in general." Typically wired from a chart's
+     * `onObservation` callback or the convenience `useChartFocus` hook.
+     */
+    focus?: InterrogationFocus | null;
+}
+export interface UseChartInterrogationResult {
+    /** Ask a question. Updates history, annotations, loading, and error. */
+    ask: (query: string) => Promise<void>;
+    /**
+     * Append an AI-initiated message to the transcript without a user query.
+     *
+     * Use for proactive narration — a streaming watcher that detected an
+     * anomaly, a background analysis that surfaced an insight, an LLM that
+     * decided to volunteer information mid-session. Synchronous; no `onQuery`
+     * call. Annotations merge into the chart's `annotations` array like
+     * any other AI response.
+     *
+     * @example
+     * announce({
+     *   text: "Spike detected at 14:32 — 3.2σ above rolling mean.",
+     *   annotations: [{ type: "callout", ts: now, value: 850, note: "Slow query?" }],
+     * })
+     */
+    announce: (message: {
+        text: string;
+        annotations?: ReadonlyArray<Datum>;
+    }) => void;
+    /** Conversation history, oldest first. */
+    history: ReadonlyArray<InterrogationMessage>;
+    /** Statistical summary of the data — memoized, safe to pass to a prompt. */
+    summary: DataSummary;
+    /** Merged annotations: initial + latest AI response. Pass to the chart's `annotations` prop. */
+    annotations: ReadonlyArray<Datum>;
+    /** True while onQuery is in flight. */
+    loading: boolean;
+    /** Last error from onQuery, if any. */
+    error: Error | null;
+    /** Clear history, AI annotations, and error. */
+    reset: () => void;
+}
+/**
+ * Headless interrogation hook — a sibling to `useChartObserver`.
+ *
+ * Generates an LLM-friendly statistical summary of your chart's data, runs queries through
+ * a caller-supplied `onQuery`, and merges any annotations the response returns so the chart
+ * can highlight what the model is talking about.
+ *
+ * The hook owns no UI. Render whatever input/transcript surface fits your product.
+ *
+ * @example
+ * const { ask, history, annotations, loading } = useChartInterrogation({
+ *   data,
+ *   onQuery: async (q, ctx) => {
+ *     const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ q, summary: ctx.summary }) })
+ *     return res.json()
+ *   },
+ * })
+ *
+ * <LineChart data={data} annotations={annotations} ... />
+ */
+export declare function useChartInterrogation(options: UseChartInterrogationOptions): UseChartInterrogationResult;

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

@@ -13,6 +13,14 @@ export declare function computeCanvasAriaLabel(scene: AnySceneNode[] | null | un
  * Compute an aria-label for network charts from scene nodes and edges.
  */
 export declare function computeNetworkAriaLabel(nodeCount: number, edgeCount: number, chartType: string): string;
+interface DataRow {
+    label: string;
+    values: Record<string, string | number>;
+}
+/** Extract a flat list of typed rows from scene nodes, surfacing the raw datum
+ *  fields (not pixel coordinates). Defensively handles missing/malformed data —
+ *  never throws. Exported for direct testing. */
+export declare function extractAllRows(scene: AnySceneNode[]): DataRow[];
 interface AccessibleDataTableProps {
     scene: AnySceneNode[];
     chartType: string;
@@ -24,7 +32,8 @@ interface AccessibleDataTableProps {
 /**
  * JIT accessible data summary. Renders a lightweight sr-only button by default.
  * On activation (or when ChartContainer's dataSummary action is toggled),
- * computes a statistical summary (.describe()-style) and shows 5 sample rows.
+ * 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;
 interface NetworkAccessibleDataTableProps {

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

@@ -2,6 +2,8 @@ import type { Datum } from "../charts/shared/datumTypes";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { AnnotationContext } from "../realtime/types";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -12,6 +14,13 @@ type AnnotationAnchorNode = {
     cy?: number;
     w?: number;
     h?: number;
+    /** Circle nodes (NetworkCircleNode, force/tree/orbit marks) carry an explicit radius. */
+    r?: number;
+    /** Arc nodes (chord, radial) carry an outer radius. */
+    outerR?: number;
+};
+type NetworkAnnotationContext = AnnotationContext & {
+    sceneNodes?: AnnotationAnchorNode[];
 };
 export interface NetworkSVGOverlayProps {
     width: number;
@@ -50,11 +59,8 @@ export interface NetworkSVGOverlayProps {
     sceneNodes?: AnnotationAnchorNode[];
     /** Annotations */
     annotations?: Datum[];
-    svgAnnotationRules?: (annotation: Datum, index: number, context: {
-        width: number;
-        height: number;
-        sceneNodes?: AnnotationAnchorNode[];
-    }) => ReactNode;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: NetworkAnnotationContext) => ReactNode;
     annotationFrame?: number;
 }
 /**

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

@@ -4,6 +4,7 @@ import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import { type AxisExtentMode } from "../charts/shared/axisExtent";
 interface OrdinalSVGOverlayProps {
     width: number;
@@ -52,6 +53,7 @@ interface OrdinalSVGOverlayProps {
     legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;

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

@@ -3,6 +3,7 @@ import type { StreamScales, MarginalGraphicsConfig, XYFrameAxisConfig } from "./
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type AxisConfig = XYFrameAxisConfig;
 interface SVGOverlayProps {
     width: number;
@@ -57,6 +58,7 @@ interface SVGOverlayProps {
     xValues?: number[];
     yValues?: number[];
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;

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

@@ -6,6 +6,7 @@ import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -94,6 +95,7 @@ export interface GeoPipelineConfig {
     /** Whether to animate elements on first render */
     introAnimation?: boolean;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     pointIdAccessor?: string | ((d: Datum) => string);
     /** ID accessor on line data — required for `removeLine` by id. */
     lineIdAccessor?: string | ((d: Datum) => string);
@@ -174,6 +176,7 @@ export interface StreamGeoFrameProps<T = Datum> {
     customClickBehavior?: (d: HoverData | null) => void;
     customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;