semiotic 3.6.0 → 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";
@@ -67,40 +70,60 @@ export type { SerializedSelections, SerializedSelection, SerializedFieldSelectio
 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 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 type { DataSummary, FieldSummary, FieldType, NumericFieldSummary, DateFieldSummary, CategoricalFieldSummary, UnknownFieldSummary, SummarizeOptions, } 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, scoreChart, explainCapabilityFit } from "./ai/suggestCharts";
-export type { SuggestChartsOptions, RejectedCapability, ExplainCapabilityFitResult, } from "./ai/suggestCharts";
+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, } from "./ai/audienceProfile";
-export type { AudienceProfile, AudienceTarget, AudienceBiasResult, } from "./ai/audienceProfile";
-export { executivePersona, analystPersona, dataScientistPersona, BUILT_IN_AUDIENCES, } from "./ai/audiences";
+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 { 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 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 type { RepairResult, RepairOkResult, RepairAlternativeResult, RepairUnknownResult, RepairOptions } from "./ai/repairChartConfig";
 export { runQualityScorecard } from "./ai/qualityScorecard";
-export type { ScorecardFixture, ScorecardReport, PerCapabilityScore, PerFixtureScore, } 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, Suggestion, } from "./ai/chartCapabilityTypes";
+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.d.ts

@@ -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/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;

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

@@ -5,6 +5,7 @@ import type { LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -518,6 +519,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
     chartId?: string;
     onTopologyChange?: (nodes: RealtimeNode[], edges: RealtimeEdge[]) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];

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

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
@@ -381,6 +382,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     tooltipContent?: (d: HoverData) => ReactNode;
     customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {

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

@@ -5,6 +5,7 @@ import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/l
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { CoercibleNumber } from "./accessorUtils";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
 export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
@@ -635,6 +636,7 @@ export interface StreamXYFrameProps<T = Datum> {
     /** Accessor for unique point IDs used by point-anchored annotations */
     pointIdAccessor?: string | ((d: T) => string);
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {