semiotic 3.5.4 → 3.7.0

package/dist/components/charts/value/types.d.ts

@@ -0,0 +1,292 @@
+/**
+ * BigNumber and (forward-looking) SingleValueFrame types.
+ *
+ * BigNumber ships today as a plain React component under
+ * `semiotic/value`. The type vocabulary here is intentionally a bit
+ * broader than the v1 component uses — it sketches the contract a
+ * future `SingleValueFrame`  would own,
+ * so adopters can write against types that survive the migration.
+ */
+import type * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Layout mode — chrome envelope around the focal value.
+ *
+ * - `tile` — dashboard cell. Label + value + comparison/target row + optional sparkline.
+ * - `presentation` — large centered value for a slide or hero card.
+ * - `inline` — value + optional delta indicator, no card chrome; flows in prose.
+ * - `thumbnail` — value only, no chrome, fixed-height. For embedding in dense grids.
+ */
+export type BigNumberMode = "tile" | "presentation" | "inline" | "thumbnail";
+/**
+ * Status level mapped to a semantic CSS variable
+ * (`--semiotic-success`, `--semiotic-warning`, `--semiotic-danger`,
+ * `--semiotic-info`, falls through to `--semiotic-text` for `neutral`).
+ */
+export type BigNumberLevel = "success" | "warning" | "danger" | "info" | "neutral";
+/**
+ * Whether a higher value is "better" semantically. Drives the
+ * sentiment of a delta — a `+5` delta is positive sentiment under
+ * "higher-is-better", negative under "lower-is-better", neutral when
+ * the direction isn't loaded.
+ */
+export type BigNumberDirection = "higher-is-better" | "lower-is-better" | "neutral";
+/**
+ * Resolved sentiment for a delta or value-vs-target. Controls whether
+ * a delta renders in success-coloured or danger-coloured ink.
+ * `"auto"` lets the component infer from `direction` + the sign of the delta.
+ */
+export type BigNumberSentiment = "auto" | "positive" | "negative" | "neutral";
+/**
+ * Number-format shortcut. `(value) => string` lets you plug in d3-format,
+ * Intl.NumberFormat, or any custom formatter.
+ *
+ * Built-in shortcuts read locale + currency + precision off the props:
+ *
+ * - `"number"`   — Intl.NumberFormat with grouping.
+ * - `"currency"` — currency style; needs `currency` prop (default USD).
+ * - `"percent"`  — multiplies × 100, suffixes "%".
+ * - `"compact"`  — Intl compact notation: 1.2M, 3.4K.
+ * - `"duration"` — formats a millisecond duration as `1h 23m 4s`.
+ */
+export type BigNumberFormat = "number" | "currency" | "percent" | "compact" | "duration" | ((value: number) => string);
+/**
+ * Threshold zone — a lower bound + status level. Zones must be sorted
+ * ascending by `at` and resolved by "highest `at` ≤ value".
+ *
+ * @example
+ * ```ts
+ * thresholds={[
+ *   { at: -Infinity, level: "danger" },
+ *   { at: 50,        level: "warning" },
+ *   { at: 80,        level: "success" },
+ * ]}
+ * ```
+ */
+export interface BigNumberThreshold {
+    /** Lower bound (inclusive) for this zone. `-Infinity` covers everything below. */
+    at: number;
+    /** Status level. Maps to a semantic CSS variable on the value text. */
+    level: BigNumberLevel;
+    /** Explicit colour override; otherwise `var(--semiotic-{level})`. */
+    color?: string;
+    /** Optional label surfaced in tooltips, the ARIA sentence, and capability output. */
+    label?: string;
+}
+/**
+ * Comparison value (vs. prior period, vs. last quarter, etc.). The
+ * delta is derived as `value - comparison.value` unless `delta` is set
+ * explicitly on the parent.
+ */
+export interface BigNumberComparison {
+    /** Prior-period value used to compute the delta. */
+    value: number;
+    /** Descriptor — e.g. `"vs last quarter"`. */
+    label?: string;
+    /** Inherit `format`/`locale`/`currency` if omitted. */
+    format?: BigNumberFormat;
+    /** Whether higher is better. Defaults to the top-level `direction`. */
+    direction?: BigNumberDirection;
+}
+/**
+ * Target / goal value. Renders as `… of {target.value}` with optional
+ * progress framing (the value's distance to target).
+ */
+export interface BigNumberTarget {
+    /** Goal value. */
+    value: number;
+    /** Descriptor — e.g. `"of Q3 target"`. */
+    label?: string;
+    /** Inherit `format`/`locale`/`currency` if omitted. */
+    format?: BigNumberFormat;
+    /** Whether higher is better. Defaults to the top-level `direction`. */
+    direction?: BigNumberDirection;
+}
+/** Imperative ref handle for streaming/push usage. */
+export interface BigNumberHandle {
+    /** Append a new datapoint; updates the focal value + extends the trend. */
+    push(input: number | BigNumberPushInput): void;
+    /** Append many in one pass. */
+    pushMany(inputs: ReadonlyArray<number | BigNumberPushInput>): void;
+    /** Reset trend buffer and focal value. */
+    clear(): void;
+    /** Current focal value. Returns the most-recently-pushed value when the
+     *  push API has been used; otherwise falls back to the `value` prop. Returns
+     *  `null` only when no push has landed AND the prop value is not finite. */
+    getValue(): number | null;
+    /** Trend buffer snapshot (most-recent-last). */
+    getData(): ReadonlyArray<BigNumberPushInput>;
+}
+export interface BigNumberPushInput {
+    value: number;
+    time?: number | Date;
+    /** Override the comparison value at this tick. */
+    comparison?: number;
+}
+/**
+ * Render slots — drop-ins for any slot in the layout. ReactNode form
+ * is rendered as-is; the function form receives the resolved context
+ * so the slot can read formatted strings without re-deriving them.
+ */
+export interface BigNumberSlotContext {
+    value: number | null;
+    formattedValue: string;
+    level: BigNumberLevel;
+    /** Resolved colour for the focal value, ready to drop into a `color` /
+     *  `stroke` / `fill` prop on an embedded Semiotic chart so its marks
+     *  match the BigNumber's threshold level. Either a hex / rgb string
+     *  or a `var(--semiotic-{level})` reference. */
+    color: string;
+    delta: number | null;
+    deltaFormatted: string | null;
+    /** Formatted percent change string (e.g. `"+20%"`), or null when undefined. */
+    deltaPercent: string | null;
+    sentiment: "positive" | "negative" | "neutral";
+    isStale: boolean;
+    /** Live push-API buffer (most-recent-last). Useful when a slot chart
+     *  should redraw on every ingest — read from this in the function
+     *  form so the chart re-renders alongside the focal value. */
+    pushBuffer: ReadonlyArray<BigNumberPushInput>;
+}
+export type BigNumberSlot = React.ReactNode | ((ctx: BigNumberSlotContext) => React.ReactNode);
+/**
+ * The full prop surface. Intentionally broad — every block here maps
+ * to a documented `SingleValueFrame` capability so users targeting
+ * the v1 component can roll forward unchanged when (if) the frame ships.
+ *
+ * Does NOT extend `BaseChartProps` because most of those (axisExtent,
+ * pointIdAccessor, linkedHover, linkedBrush, hoverHighlight, ...) are
+ * irrelevant for a single value. The contract is documented per-prop.
+ */
+export interface BigNumberProps<_TDatum extends Datum = Datum> {
+    /** The number this card exists to display. `null` / `undefined` / `NaN`
+     *  routes the card into its empty state (see `emptyContent`); this lets
+     *  consumers pass `data?.revenue` style optional values without a
+     *  conditional. */
+    value: number | null | undefined;
+    /** Top-line descriptor — e.g. `"Q3 Revenue"`. Rendered above the value. */
+    label?: string;
+    /** Secondary descriptor, smaller, below the label. */
+    caption?: string;
+    /** Format the focal value. Default `"number"`. */
+    format?: BigNumberFormat;
+    /** BCP-47 locale tag for built-in formats. Default `"en-US"`. */
+    locale?: string;
+    /** ISO 4217 code; required for `format: "currency"`. Default `"USD"`. */
+    currency?: string;
+    /** `Intl.NumberFormat` `maximumFractionDigits`. Default 0 for compact, 2 for currency, 0 elsewhere. */
+    precision?: number;
+    /** Prepend to the formatted value. */
+    prefix?: string;
+    /** Append to the formatted value. */
+    suffix?: string;
+    /** Unit label rendered after the value as small text — e.g. `"USD"`, `"req/s"`. */
+    unit?: string;
+    /** Comparison value (vs prior period). Drives delta if `delta` is not explicit. */
+    comparison?: BigNumberComparison;
+    /** Goal value; renders alongside the comparison row. */
+    target?: BigNumberTarget;
+    /** Explicit delta override; bypasses comparison.value subtraction. */
+    delta?: number;
+    /** Format the delta; defaults to `format` (inherits currency/locale). */
+    deltaFormat?: BigNumberFormat;
+    /** Also render the percent change next to the absolute delta. Default true when a comparison is present. */
+    showDeltaPercent?: boolean;
+    /** Default direction for sentiment inference. Per-comparison/target wins. */
+    direction?: BigNumberDirection;
+    /** Force sentiment classification. `"auto"` infers from `direction` + sign. Default `"auto"`. */
+    sentiment?: BigNumberSentiment;
+    /** Threshold zones — ordered ascending by `at`. Defines the level
+     *  applied to the value text via a semantic CSS variable. */
+    thresholds?: ReadonlyArray<BigNumberThreshold>;
+    /** Cap the push buffer surfaced via `getData()` / `slotCtx.pushBuffer`. Default 60. */
+    windowSize?: number;
+    /** Layout mode. Default `"tile"`. */
+    mode?: BigNumberMode;
+    /** Horizontal alignment within the card. Default `"start"` for tile,
+     *  `"center"` for presentation / thumbnail, `"inherit"` for inline. */
+    align?: "start" | "center" | "end";
+    /** Reserve width. Default 280 (tile), 540 (presentation), unset (inline/thumbnail). */
+    width?: number | string;
+    /** Reserve height. Default 184 (tile), 320 (presentation), unset (inline/thumbnail). */
+    height?: number | string;
+    /** Inner padding; number or `{top, right, bottom, left}`. */
+    padding?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** Visual emphasis hint — dashboards can use this to span columns. */
+    emphasis?: "primary" | "secondary";
+    /** Override the value text colour. CSS variables work. */
+    color?: string;
+    /** Card background. CSS variables work; transparent by default in inline/thumbnail. */
+    background?: string;
+    /** Border colour. Defaults to `--semiotic-border`. */
+    borderColor?: string;
+    /** Border radius (px or any CSS length). Defaults to theme `--semiotic-border-radius`. */
+    borderRadius?: number | string;
+    /** Optional class for the outer container. */
+    className?: string;
+    /** Optional inline style — composed with the layout defaults. */
+    style?: React.CSSProperties;
+    /** Tween between value changes. `true` = 300ms ease-out + intro. */
+    animate?: boolean | {
+        duration?: number;
+        easing?: "linear" | "ease-out";
+        intro?: boolean;
+    };
+    /** Mark the card stale (dimmed) when no push occurs for this many ms. */
+    stalenessThreshold?: number;
+    /** Custom stale label appended to the ARIA sentence. Default `"stale"`. */
+    staleLabel?: string;
+    /** Replace the entire header (label + caption) slot. */
+    headerSlot?: BigNumberSlot;
+    /** Replace the focal value slot. */
+    valueSlot?: BigNumberSlot;
+    /** Replace the delta / comparison / target row. */
+    deltaSlot?: BigNumberSlot;
+    /** **Wide / rectangular** chart embedded beneath the value — e.g. a
+     *  `LineChart` / `AreaChart` in `mode="sparkline"`. The card stays
+     *  full-width and stacks the chart at full card width under the delta
+     *  row. */
+    trendSlot?: BigNumberSlot;
+    /** **Square** chart embedded beside the value — e.g. a `DonutChart` /
+     *  `PieChart` / `Scatterplot` / `Treemap`. When set, the card splits
+     *  into a left column (header + value + delta) and a right column
+     *  (the square chart). Compose with `trendSlot` to get both
+     *  (square chart on the right, wide trend along the bottom). */
+    chartSlot?: BigNumberSlot;
+    /** Reserved pixel size (square) for `chartSlot`. Defaults are
+     *  mode-keyed for sparkline scale — 44 px for `tile`, 80 px for
+     *  `presentation` — so the embedded chart reads as a corner
+     *  decoration. Pass a larger value for a hero-style anchor. */
+    chartSize?: number;
+    /** Free-form footer below the trend. */
+    footerSlot?: BigNumberSlot;
+    /** Card click. */
+    onClick?: (datum: {
+        value: number;
+        level: BigNumberLevel;
+        delta: number | null;
+    }, event: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Generic observation hook — fires on click today; future SingleValueFrame work
+     *  may extend this to value-update / hover events. */
+    onObservation?: import("../../store/ObservationStore").OnObservationCallback;
+    /** Identifier surfaced on every observation event. */
+    chartId?: string;
+    /** Override the auto-generated aria-label sentence. */
+    description?: string;
+    /** Sr-only supplement appended below the auto sentence. */
+    summary?: string;
+    /** Loading skeleton overlay. */
+    loading?: boolean;
+    /** Replace the default skeleton; `false` suppresses it entirely. */
+    loadingContent?: React.ReactNode | false;
+    /** Empty-state placeholder rendered when `value` is `null`/`undefined`/`NaN`. */
+    emptyContent?: React.ReactNode | false;
+}

package/dist/components/charts/xy/AreaChart.capability.d.ts

@@ -0,0 +1,10 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * AreaChart is treated as a strictly single-series chart. Multi-series areas
+ * are an occlusion nightmare — when the data has 2+ series we subselect the
+ * leading series (largest cumulative y) and surface a caveat so the reader
+ * knows they're looking at one slice, not the whole dataset. For full multi-
+ * series comparison the engine routes callers to LineChart; for two-series
+ * comparison, to DifferenceChart.
+ */
+export declare const AreaChartCapability: ChartCapability;

package/dist/components/charts/xy/BubbleChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BubbleChartCapability: ChartCapability;

package/dist/components/charts/xy/CandlestickChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const CandlestickChartCapability: ChartCapability;

package/dist/components/charts/xy/ConnectedScatterplot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ConnectedScatterplotCapability: ChartCapability;

package/dist/components/charts/xy/DifferenceChart.capability.d.ts

@@ -0,0 +1,8 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * DifferenceChart's native shape is two series. When the input has 2+ series
+ * we subselect the top two by total y and pivot them into the wide form the
+ * chart expects — same "narrow the dataset to make the chart honest" pattern
+ * AreaChart uses for its single-series fallback.
+ */
+export declare const DifferenceChartCapability: ChartCapability;

package/dist/components/charts/xy/Heatmap.capability.d.ts

@@ -0,0 +1,9 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * Heatmap is a matrix: categorical × categorical (or temporal × categorical),
+ * with a numeric encoded as color. Without two genuine discrete dimensions
+ * for the axes, a heatmap of raw rows is sparse and unreadable. Tuned in
+ * Phase 2.1 after the scorecard surfaced Heatmap winning unsuitable
+ * compare-categories rankings.
+ */
+export declare const HeatmapCapability: ChartCapability;

package/dist/components/charts/xy/LineChart.capability.d.ts

@@ -0,0 +1,9 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * LineChart capability — declares what data shapes LineChart serves well,
+ * what intents it answers, and what variants change those answers.
+ *
+ * Read alongside `LineChart.tsx`; this file is what makes the chart
+ * "self-aware" for suggestion and interrogation flows.
+ */
+export declare const LineChartCapability: ChartCapability;

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

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const MinimapChartCapability: ChartCapability;

package/dist/components/charts/xy/MultiAxisLineChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const MultiAxisLineChartCapability: ChartCapability;

package/dist/components/charts/xy/QuadrantChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const QuadrantChartCapability: ChartCapability;

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

@@ -30,6 +30,9 @@ export interface QuadrantsConfig {
     bottomRight: QuadrantConfig;
     bottomLeft: QuadrantConfig;
 }
+export type QuadrantsConfigOverride = {
+    [TQuadrant in keyof QuadrantsConfig]?: Partial<QuadrantsConfig[TQuadrant]>;
+};
 /**
  * Centerline style configuration
  */
@@ -55,8 +58,8 @@ export interface QuadrantChartProps<TDatum extends Datum = Datum> extends BaseCh
     xCenter?: number;
     /** Y-coordinate of the horizontal center line. Defaults to midpoint of y domain. */
     yCenter?: number;
-    /** Quadrant configuration: labels and colors for each of the four quadrants */
-    quadrants: QuadrantsConfig;
+    /** Optional quadrant overrides. Omitted quadrants and quadrant fields fall back to built-in defaults. */
+    quadrants?: QuadrantsConfigOverride;
     /** Style for the center lines */
     centerlineStyle?: CenterlineStyle;
     /** Show quadrant labels @default true */

package/dist/components/charts/xy/QuadrantChart.defaults.d.ts

@@ -0,0 +1,2 @@
+import type { QuadrantsConfig } from "./QuadrantChart";
+export declare const DEFAULT_QUADRANTS: QuadrantsConfig;

package/dist/components/charts/xy/Scatterplot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ScatterplotCapability: ChartCapability;

package/dist/components/charts/xy/StackedAreaChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const StackedAreaChartCapability: ChartCapability;

package/dist/components/data/DataSummarizer.d.ts

@@ -0,0 +1,45 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type FieldType = "numeric" | "categorical" | "date" | "unknown";
+export interface NumericFieldSummary {
+    type: "numeric";
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+}
+export interface DateFieldSummary {
+    type: "date";
+    min: string;
+    max: string;
+}
+export interface CategoricalFieldSummary {
+    type: "categorical";
+    distinctCount: number;
+    topValues: ReadonlyArray<{
+        value: string;
+        count: number;
+    }>;
+    distinctValues?: ReadonlyArray<string>;
+}
+export interface UnknownFieldSummary {
+    type: "unknown";
+}
+export type FieldSummary = NumericFieldSummary | DateFieldSummary | CategoricalFieldSummary | UnknownFieldSummary;
+export interface DataSummary {
+    rowCount: number;
+    fields: Record<string, FieldSummary>;
+    sample: ReadonlyArray<Datum>;
+}
+export interface SummarizeOptions {
+    maxDistinct?: number;
+    sampleSize?: number;
+    /** Scan up to this many rows when discovering field keys (handles ragged rows). */
+    keyScanRows?: number;
+}
+/**
+ * Summarize a dataset for an LLM. Returns row count, per-field statistics, and a small sample.
+ *
+ * Designed so a model can answer questions about ranges, peaks, distributions, and categories
+ * without seeing the full dataset.
+ */
+export declare function summarizeData(data: ReadonlyArray<Datum> | null | undefined, options?: SummarizeOptions): DataSummary;

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;