semiotic 3.6.0 → 3.7.1

package/dist/components/realtime/lifecycleBands.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Named lifecycle bands. Shared by the annotation freshness surface
+ * today and available to other temporal-lifecycle policies that opt
+ * into banded classification.
+ */
+export type LifecycleBand = "fresh" | "aging" | "stale" | "expired";
+/**
+ * Multipliers of `ttlMs` that mark the upper edge of each band. The
+ * default schedule:
+ *
+ *   • `fresh`   — `age < 1.0 × ttl`
+ *   • `aging`   — `age < 1.5 × ttl`
+ *   • `stale`   — `age < 3.0 × ttl`
+ *   • `expired` — `age ≥ 3.0 × ttl`
+ *
+ * Override individual thresholds; missing entries fall back to the
+ * defaults. Setting a smaller value than the previous band's
+ * threshold is allowed but produces an unreachable band.
+ */
+export interface LifecycleBandThresholds {
+    /** Upper edge of the `fresh` band, as a multiple of `ttlMs`. Default `1.0`. */
+    fresh?: number;
+    /** Upper edge of the `aging` band, as a multiple of `ttlMs`. Default `1.5`. */
+    aging?: number;
+    /** Upper edge of the `stale` band, as a multiple of `ttlMs`. Default `3.0`. */
+    stale?: number;
+}
+export declare const DEFAULT_LIFECYCLE_THRESHOLDS: Required<LifecycleBandThresholds>;
+/**
+ * Classify an age into a named band given a TTL.
+ *
+ * Pure function. Edge cases:
+ *
+ * - **Negative age** (future-dated items): classifies as `fresh`.
+ * - **`NaN` age** (parse failure or `now - undefined`): classifies as
+ *   `fresh` — the safer default, since `expired` is filtered by the
+ *   visual treatment.
+ * - **`+Infinity` age**: classifies as `expired`. Monotonic in age —
+ *   "older than any finite TTL multiple" should be the oldest band.
+ * - **Non-finite / non-positive TTL**: classifies as `fresh`, since
+ *   there's no meaningful interval to age against. Callers that need
+ *   stricter handling should gate `ttlMs` before calling.
+ */
+export declare function bandFromAge(ageMs: number, ttlMs: number, thresholds?: LifecycleBandThresholds): LifecycleBand;

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

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { ScaleBand, ScaleLinear } from "d3-scale";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type ArrowOfTime = "up" | "down" | "left" | "right";
 export type WindowMode = "sliding" | "growing";
 export type ThresholdType = "greater" | "lesser";
@@ -11,15 +12,28 @@ export interface LineStyle {
     opacity?: number;
 }
 /**
- * Anchoring mode for streaming annotations.
- * - `"fixed"` (default): anchored to specific datum coordinates; disappears when out of view.
- * - `"latest"`: annotation attaches to the most recent datum in the buffer.
- *   On each frame, the annotation's position is re-resolved to the latest data point.
- *   Useful for "current value" labels.
- * - `"sticky"`: annotation stays at its last known pixel position after the target datum
- *   is evicted from the window. It freezes in place rather than disappearing.
+ * How an annotation's anchor is resolved across renders. Shared between
+ * the streaming runtime (which implements the resolution) and the
+ * `semiotic/ai` annotation lifecycle surface (which exposes the choice
+ * to authors via `lifecycle.anchor`).
+ *
+ * - `"fixed"` (default): anchored to specific datum coordinates;
+ *   disappears when out of view.
+ * - `"latest"`: annotation re-pins to the most recent datum each frame.
+ * - `"sticky"`: annotation stays at its last known pixel position
+ *   after the target datum scrolls off; uses `stickyPositionCache`
+ *   on `AnnotationContext`.
+ * - `"semantic"`: re-resolves via `provenance.stableId` when new data
+ *   arrives, falling back to the recorded coordinate if the anchor
+ *   can no longer be located.
  */
-export type AnnotationAnchorMode = "fixed" | "latest" | "sticky";
+export type AnnotationAnchor = "fixed" | "latest" | "sticky" | "semantic";
+/**
+ * @deprecated Use {@link AnnotationAnchor}. Kept as a back-compat alias
+ * because earlier 3.x releases shipped this name from the streaming
+ * surface; the `Mode` suffix added nothing semantically.
+ */
+export type AnnotationAnchorMode = AnnotationAnchor;
 export interface AnnotationContext {
     scales?: {
         x?: ScaleLinear<number, number>;
@@ -154,6 +168,7 @@ export interface RealtimeFrameProps {
     className?: string;
     lineStyle?: LineStyle;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;

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

@@ -0,0 +1,69 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * M3 — Amount & density management (Rahman et al.'s sixth consideration:
+ * "balance explanatory support against clutter").
+ *
+ * A pure, geometry-light pass that decides *which* note-like annotations should
+ * stay on screen when there are more than the plot area can carry without
+ * clutter. It does not move anything (that is M2's `annotationLayout`); it
+ * partitions notes into a persistent set and a deferred set by importance and
+ * freshness, with the lowest-priority notes shed first.
+ *
+ * Priority signals, reusing what M0/M1 already attach:
+ *   • `emphasis` (M1) — `"primary"` is the floor (never shed); `"secondary"`
+ *     ranks below an un-emphasised note.
+ *   • `provenance.confidence` (M0) — a small nudge so a higher-confidence note
+ *     outranks a lower-confidence one at the same emphasis.
+ *   • `lifecycle.freshness` (M0) — `fresh > aging > stale`; `expired` is shed
+ *     first.
+ *
+ * Only note types compete for the budget; reference lines, bands, enclosures
+ * and statistical overlays pass through untouched (they are not "clutter notes"
+ * in the paper's sense and a density cap shedding a threshold line would be
+ * surprising).
+ *
+ * The persistent set is the floor and is never empty when any note exists — the
+ * paper's "keep the core message persistent; hover is not guaranteed."
+ */
+/** Plot area (px²) allotted per note before the budget tightens. */
+export declare const DEFAULT_AREA_PER_ANNOTATION = 20000;
+export interface AnnotationDensityConfig {
+    /**
+     * Hard cap on simultaneously-persistent notes. When set, overrides the
+     * `width`×`height`-derived budget.
+     */
+    maxAnnotations?: number;
+    /**
+     * Plot area (px²) allotted per note when deriving the budget from the chart
+     * dimensions. Larger ⇒ fewer notes. Default {@link DEFAULT_AREA_PER_ANNOTATION}.
+     */
+    areaPerAnnotation?: number;
+    /** Minimum notes kept regardless of budget. Default 1. */
+    minVisible?: number;
+}
+export interface AnnotationDensityOptions extends AnnotationDensityConfig {
+    annotations: ReadonlyArray<Datum>;
+    /** Plot width in px (used to derive the budget when `maxAnnotations` is unset). */
+    width: number;
+    /** Plot height in px. */
+    height: number;
+}
+export interface AnnotationDensityResult {
+    /** Notes kept on screen plus every non-note annotation, in author order. */
+    visible: Datum[];
+    /** Notes shed by the budget, in author order. Empty when nothing is shed. */
+    deferred: Datum[];
+    /** The note budget that produced this partition. */
+    budget: number;
+}
+/**
+ * Derive the note budget for a plot. Exported so the clutter diagnostic
+ * (`diagnoseConfig`) and the runtime pass agree on the same threshold.
+ */
+export declare function annotationBudget(width: number, height: number, config?: AnnotationDensityConfig): number;
+/**
+ * Partition annotations into a persistent (visible) set and a deferred set
+ * given a note budget. Pure and deterministic; preserves author order within
+ * each returned array.
+ */
+export declare function annotationDensity(options: AnnotationDensityOptions): AnnotationDensityResult;

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