semiotic 3.6.0 → 3.7.0

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

@@ -5,6 +5,7 @@ import type { HoverData } from "../../realtime/types";
 import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 /**
  * The frames accept `tooltipContent: (d: HoverData) => ReactNode`,
  * which is a slightly wider parameter than the `TooltipContentFn`
@@ -48,6 +49,7 @@ export interface BaseMetadataProps {
      *  this to the frame. Bundling it here avoids a parallel helper
      *  + 22 separate adoption edits. */
     axisExtent?: import("./axisExtent").AxisExtentMode;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
 }
 export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMetadataProps;
 /**

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

@@ -3,6 +3,7 @@ import type { PartialMargin } from "../../types/marginType";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { Datum } from "./datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -25,8 +26,9 @@ export interface SelectionConfig {
 export type LinkedHoverProp = boolean | string | {
     name?: string;
     fields?: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    seriesField?: string;
 };
 /**
  * Linked brush config
@@ -128,6 +130,8 @@ export interface BaseChartProps {
     dataIdAccessor?: string | ((d: Datum) => string);
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
+    /** Opt into annotation placement assistance. Preserves authored dx/dy by default. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** Enable declarative bounded animation (enter/exit/update transitions + intro).
      * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
      * Set `{ intro: false }` to disable the animated intro on first render. */

package/dist/components/charts/value/BigNumber.capability.d.ts

@@ -0,0 +1,13 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * BigNumber capability descriptor.
+ *
+ * `fits()` accepts datasets that resolve to a single focal value:
+ *   - exactly one row with a numeric field, or
+ *   - any dataset where a `total` / `value` aggregation makes sense
+ *     and the suggestion engine has already declared the scale `tiny`.
+ *
+ * At tiny scale BigNumber is the catalog's "honest" answer: when you
+ * have one number, a chart is the wrong abstraction — show the number.
+ */
+export declare const BigNumberCapability: ChartCapability;

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

@@ -0,0 +1,14 @@
+/**
+ * BigNumber — the focal-value HOC behind `semiotic/value`.
+ *
+ * A plain React component (no Stream Frame underneath). This ships as a forward-looking React
+ * component that already honours the contracts a `SingleValueFrame`
+ * would inherit (format cascade, threshold zones via semantic theme
+ * roles, comparison anchoring, sentence-form ARIA, push API + staleness).
+ */
+import * as React from "react";
+import type { BigNumberHandle, BigNumberProps } from "./types";
+export declare const BigNumber: (props: BigNumberProps & {
+    ref?: React.ForwardedRef<BigNumberHandle>;
+}) => React.ReactElement | null;
+export default BigNumber;

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

@@ -0,0 +1,40 @@
+/**
+ * Number-format cascade for BigNumber.
+ *
+ * Resolves a `BigNumberFormat` shortcut (or custom fn) against the
+ * card's locale + currency + precision props and returns a memoizable
+ * formatter. All built-ins use `Intl.NumberFormat` so locale + grouping
+ * behave correctly without bundling a separate number-format library.
+ */
+import type { BigNumberFormat } from "./types";
+export interface FormatContext {
+    locale?: string;
+    currency?: string;
+    precision?: number;
+    notation?: Intl.NumberFormatOptions["notation"];
+}
+/**
+ * Build a `(value) => string` formatter from a shortcut + context.
+ * Custom-function shortcuts are returned as-is.
+ */
+export declare function buildFormatter(format: BigNumberFormat | undefined, ctx?: FormatContext): (value: number) => string;
+/**
+ * Format a millisecond duration as a short human string:
+ * `2h 14m`, `45s`, `12ms`. Useful for latency-style KPIs.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Decorate a formatted number with prefix/suffix. Empty strings are
+ * skipped without padding.
+ */
+export declare function decorate(formatted: string, prefix: string | undefined, suffix: string | undefined): string;
+/**
+ * Format a signed delta — always carry an explicit + on positive values
+ * so the sign-as-information stays legible. Zero renders as `"0"`
+ * unformatted-by-sign (no `+0`).
+ */
+export declare function formatSignedDelta(delta: number, formatter: (value: number) => string): string;
+/**
+ * Format a percent change. `from` of 0 yields `null` (undefined ratio).
+ */
+export declare function formatDeltaPercent(from: number, to: number, locale?: string, precision?: number): string | null;

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

@@ -0,0 +1,40 @@
+/**
+ * Threshold zone resolution + inline sparkline path builder for
+ * BigNumber. Lifted out so the component file stays focused on layout.
+ */
+import type { BigNumberLevel, BigNumberThreshold } from "./types";
+/**
+ * Resolve a numeric value against an ordered threshold list. Zones are
+ * tested by "highest `at` whose bound is ≤ value." `-Infinity` works
+ * as a "catch-all" lower zone.
+ *
+ * Returns `null` when no threshold fits (caller falls back to neutral).
+ */
+export declare function resolveThreshold(value: number, thresholds: ReadonlyArray<BigNumberThreshold> | undefined): BigNumberThreshold | null;
+/**
+ * Map a level + explicit-color override to a CSS color string. The
+ * neutral level falls through to `--semiotic-text` so the value reads
+ * as the regular text colour when no thresholds fire.
+ */
+export declare function colorForLevel(level: BigNumberLevel, explicit?: string): string;
+export interface SparklinePoint {
+    x: number;
+    y: number;
+}
+/**
+ * Build the SVG path string for a polyline sparkline. Maps values into
+ * a [0..width] × [0..height] box; auto-fits the y-domain by default.
+ *
+ * Empty / single-point input returns an empty string.
+ */
+export declare function buildSparklinePath(values: ReadonlyArray<number>, opts: {
+    width: number;
+    height: number;
+    padding?: number;
+    yMin?: number;
+    yMax?: number;
+}): {
+    line: string;
+    area: string;
+    points: SparklinePoint[];
+};

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