semiotic 3.3.1 → 3.4.0

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

@@ -1,3 +1,5 @@
+/** Apply accessibility flags to a resolved theme. Shared by ThemeStore and server themeResolver. */
+export declare function applyThemeAccessibility(theme: SemioticTheme): SemioticTheme;
 export interface SemioticTheme {
     mode: "light" | "dark" | "auto";
     colors: {

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

@@ -13,11 +13,16 @@ export interface HitResult {
  * Dispatches to type-specific hit testers for optimal performance.
  *
  * When a quadtree spatial index is provided (for scatter/bubble charts with
- * many points), point hit testing uses O(log n) quadtree.find() instead of
- * iterating all nodes. Non-point node types (line, rect, area, etc.) still
+ * many points), point hit testing routes through `findHitPointInQuadtree`,
+ * which visits every candidate within the widened search radius (using
+ * `maxPointRadius` so variable-size points like BubbleChart can't hide
+ * behind a nearer non-hit). The visit is authoritative — when it returns
+ * null, no point hit exists and the linear point loop is skipped.
+ *
+ * Non-point node types (line, rect, area, heatcell, candlestick) still
  * use the linear scan.
  */
-export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null): HitResult | null;
+export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): HitResult | null;
 /**
  * Find all line/area nodes at a given X pixel coordinate.
  * For each node, interpolates the Y value at px using the path data.

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

@@ -32,6 +32,23 @@ export declare class DataSourceAdapter<T = Record<string, any>> {
      * animation frames (bounded: false so they append without clearing).
      */
     setBoundedData(data: T[]): void;
+    /**
+     * Replace the buffer contents without clearing category insertion-order
+     * memory. Intended for aggregator HOCs (e.g. LikertChart) that re-derive
+     * a full dataset from streaming input on every push — the transport is
+     * wholesale replacement, but the user perceives it as a live stream
+     * where categories should stay put across updates.
+     *
+     * Small datasets (≤ chunkThreshold) emit a single synchronous
+     * changeset — the common aggregator case. Larger datasets fall
+     * through to progressive chunking so an unexpectedly-huge replacement
+     * doesn't block the main thread. Only the first chunk carries
+     * `preserveCategoryOrder: true` (it's the one that resets the
+     * buffer and seeds the category Set); subsequent chunks are plain
+     * append-only streaming changesets, which preserve order anyway via
+     * the streaming-mode branch.
+     */
+    setReplacementData(data: T[]): void;
     /**
      * Flush all buffered push data as a single changeset.
      * Called automatically via microtask after push()/pushMany().

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

@@ -16,4 +16,4 @@ export interface GeoHitResult {
  * The `hitCtx` parameter is a shared offscreen canvas context used for
  * isPointInPath checks without polluting the visible canvas.
  */
-export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode>): GeoHitResult | null;
+export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): GeoHitResult | null;

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

@@ -1,12 +1,18 @@
 import type { ZoomTransform } from "d3-zoom";
+import { type Quadtree } from "d3-quadtree";
 import type { GeoPipelineConfig, GeoScales, GeoSceneNode } from "./geoTypes";
-import type { StreamLayout } from "./types";
+import type { PointSceneNode, StreamLayout } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 export declare class GeoPipelineStore {
     config: GeoPipelineConfig;
     scene: GeoSceneNode[];
     scales: GeoScales | null;
     version: number;
+    private static readonly QUADTREE_THRESHOLD;
+    private _quadtree;
+    /** Largest visual point radius in the current scene; used to widen quadtree
+     *  hit-test radius when points are larger than the default maxDistance. */
+    private _maxPointRadius;
     private projection;
     private geoPath;
     private baseScale;
@@ -28,6 +34,7 @@ export declare class GeoPipelineStore {
     private timestampBuffer;
     activeTransition: ActiveTransition | null;
     private prevPositions;
+    private _hasRenderedOnce;
     constructor(config: GeoPipelineConfig);
     updateConfig(config: Partial<GeoPipelineConfig>): void;
     setAreas(features: GeoJSON.Feature[]): void;
@@ -76,6 +83,17 @@ export declare class GeoPipelineStore {
         translate: [number, number];
     };
     getPoints(): Record<string, any>[];
+    /**
+     * Build (or clear) the quadtree spatial index for point scene nodes.
+     * Only built when the point count exceeds QUADTREE_THRESHOLD; below that
+     * a linear scan is faster than indexing overhead. Also tracks the largest
+     * point radius so the hit tester can widen its query when symbols are big.
+     */
+    private rebuildQuadtree;
+    /** Quadtree spatial index for point hit testing, or null when below threshold. */
+    get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     private buildSceneNodes;
     private applyCartogramTransform;
     private applyDecay;

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

@@ -22,6 +22,11 @@ export declare class NetworkPipelineStore {
     private config;
     private tensionConfig;
     transition: ActiveTransition | null;
+    private _hasRenderedOnce;
+    /** Snapshot of node positions from before bounded re-ingestion cleared the maps */
+    private _boundedPrevSnapshot;
+    /** Snapshot of edge positions from before bounded re-ingestion cleared the maps */
+    private _boundedEdgeSnapshot;
     lastIngestTime: number;
     private nodeTimestamps;
     private edgeTimestamps;

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

@@ -1,4 +1,6 @@
 import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PointSceneNode } from "./types";
+import type { Quadtree } from "d3-quadtree";
 export interface OrdinalHitResult {
     datum: any;
     x: number;
@@ -7,4 +9,4 @@ export interface OrdinalHitResult {
     category?: string;
     stats?: import("./ordinalTypes").DistributionStats;
 }
-export declare function findNearestOrdinalNode(scene: OrdinalSceneNode[], px: number, py: number, maxDistance?: number): OrdinalHitResult | null;
+export declare function findNearestOrdinalNode(scene: OrdinalSceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): OrdinalHitResult | null;

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

@@ -15,8 +15,9 @@
  * Consumed by: StreamOrdinalFrame (sole consumer).
  */
 import { type ScaleLinear } from "d3-scale";
+import { type Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
-import type { Changeset } from "./types";
+import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 export declare class OrdinalPipelineStore {
     private buffer;
@@ -52,6 +53,17 @@ export declare class OrdinalPipelineStore {
     scene: OrdinalSceneNode[];
     columns: Record<string, OrdinalColumn>;
     version: number;
+    /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
+    private _dataVersion;
+    private static readonly QUADTREE_THRESHOLD;
+    private _pointQuadtree;
+    /** Largest visual point radius in the current scene. */
+    private _maxPointRadius;
+    /** Cached datum→index map for applyDecay/applyPulse. Keyed by `_dataVersion`. */
+    private _datumIndexCache;
+    /** Cached category→indices map for applyPulse wedge path. Keyed by `_dataVersion`. */
+    private _categoryIndexCache;
+    private _hasRenderedOnce;
     constructor(config: OrdinalPipelineConfig);
     ingest(changeset: Changeset): boolean;
     private pushValueExtent;
@@ -69,9 +81,34 @@ export declare class OrdinalPipelineStore {
     private getColorFromScheme;
     private resolveSummaryStyle;
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
+    /**
+     * Build (or return cached) datum→buffer-index map. Cached against
+     * `_dataVersion` so the per-frame applyDecay/applyPulse calls don't
+     * rebuild it during animation when the buffer hasn't changed.
+     */
+    private getDatumIndexMap;
+    /**
+     * Build (or return cached) category→[indices] map used by applyPulse for
+     * wedge nodes. Cached against `_dataVersion` so the per-wedge inner loop
+     * collapses from O(data) to O(matches-for-this-category).
+     */
+    private getCategoryIndexMap;
+    /**
+     * Build (or clear) a quadtree spatial index for point scene nodes.
+     * Useful for swarm plots — other ordinal types (bar/wedge/box/violin) are
+     * not indexed because they're typically few in number or already O(1) hit
+     * tests via bbox checks.
+     */
+    private rebuildPointQuadtree;
+    /** Quadtree spatial index for point hit testing, or null when below threshold. */
+    get pointQuadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     private applyDecay;
     private applyPulse;
     get hasActivePulses(): boolean;
+    /** Synthesize a zero-state prevPositionMap for animated intro (first render). */
+    private synthesizeIntroPositions;
     /** Build a stable identity key for a scene node based on its content, not array index */
     private getNodeKey;
     private snapshotPositions;

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

@@ -4,10 +4,14 @@ import type { Particle, RealtimeEdge } from "./networkTypes";
  *
  * Pre-allocates a fixed-size array to avoid GC pressure.
  * Particles travel along bezier paths within link bands.
+ *
+ * `_freeIndices` is a stack of currently-free slot indices. Spawn pops; step
+ * pushes when a particle expires. This makes spawn O(1) instead of O(capacity).
  */
 export declare class ParticlePool {
     particles: Particle[];
     private capacity;
+    private _freeIndices;
     constructor(capacity: number);
     /**
      * Spawn a new particle on the given edge.

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

@@ -76,11 +76,15 @@ export interface PipelineConfig {
         strokeWidth?: number;
     };
     colorScheme?: string | string[];
+    /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
+    themeCategorical?: string[];
     barColors?: Record<string, string>;
     annotations?: Record<string, any>[];
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render (points scale up, lines/areas clip from left, rects grow from baseline) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
@@ -111,6 +115,7 @@ export declare class PipelineStore {
     private getPointId;
     private timestampBuffer;
     activeTransition: ActiveTransition | null;
+    private _hasRenderedOnce;
     private prevPositionMap;
     /** Previous line/area path arrays for path interpolation */
     private prevPathMap;
@@ -140,6 +145,10 @@ export declare class PipelineStore {
     /** True when the x accessor returns Date objects (auto-detected on first data ingestion) */
     xIsDate: boolean;
     private _quadtree;
+    /** Largest visual point radius in the current scene. The hit tester uses
+     *  this to widen its quadtree query so points with big radii (bubble) don't
+     *  fall outside the search region. */
+    private _maxPointRadius;
     private static readonly QUADTREE_THRESHOLD;
     constructor(config: PipelineConfig);
     /**
@@ -161,6 +170,8 @@ export declare class PipelineStore {
      * Returns null when chart type is not scatter/bubble or point count is below threshold.
      */
     get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     /**
      * Remap existing scene node coordinates for a new layout size.
      * Proportionally scales all pixel coordinates without rebuilding from data.
@@ -174,13 +185,17 @@ export declare class PipelineStore {
     get hasActivePulses(): boolean;
     private get transitionContext();
     private snapshotPositions;
+    /** Synthesize a zero-state prevPositionMap/prevPathMap for animated intro (first render). */
+    private synthesizeIntroPositions;
     private startTransition;
     advanceTransition(now: number): boolean;
     private groupData;
     /**
      * Resolve a category→color map from data using the colorAccessor.
-     * Caches the result in _colorMapCache keyed by sorted category set —
-     * only rebuilds when the set of categories changes.
+     * Caches the result in _colorMapCache keyed by `_ingestVersion` (fast path)
+     * and a sorted-category fingerprint (so palette/scheme changes still
+     * invalidate). Multiple scene builders within one frame skip the data scan
+     * entirely after the first call.
      */
     private resolveColorMap;
     private resolveLineStyle;

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

@@ -1,4 +1,21 @@
 import * as React from "react";
 import type { StreamXYFrameProps, StreamXYFrameHandle } from "./types";
+/**
+ * Append a 2-char hex alpha to an existing CSS color, returning a valid
+ * CSS color string. The naive `${color}${alpha}` concatenation only works
+ * when `color` is a 6-char `#rrggbb`; shorthand `#rgb` produces the
+ * invalid 5-char `#rgbXX`, which `ctx.strokeStyle`/`fillStyle` silently
+ * rejects (falling back to `#000000` — black, invisible on dark themes).
+ * The /cookbook/marginal-graphics crosshair invisibility was caused
+ * precisely by `--semiotic-text-secondary: "#aaa"` hitting this path.
+ *
+ * Handles:
+ *   • 3-char hex (`#abc`) → expanded to 6-char then concatenated
+ *   • 6-char hex (`#aabbcc`) → concatenated directly
+ *   • `rgb(...)` → repacked as `rgba(..., a)` with numeric alpha
+ * Any other form (named colors, hsl(), oklch(), etc.) falls back to the
+ * raw color without alpha — degrades gracefully.
+ */
+export declare function withAlpha(color: string, alphaHex: string): string;
 declare const StreamXYFrame: React.ForwardRefExoticComponent<StreamXYFrameProps<Record<string, any>> & React.RefAttributes<StreamXYFrameHandle<Record<string, any>>>>;
 export default StreamXYFrame;

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

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, PointSceneNode, LineSceneNode } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
@@ -75,6 +76,8 @@ export interface GeoPipelineConfig {
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render */
+    introAnimation?: boolean;
     annotations?: Record<string, any>[];
     pointIdAccessor?: string | ((d: any) => string);
 }
@@ -146,6 +149,10 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;

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

@@ -7,6 +7,18 @@
  * property flattening that are handled at the call site.
  */
 import type { HoverData } from "../realtime/types";
+/**
+ * Minimal shape a Stream Frame's internal hover handler needs from a pointer
+ * event. React.MouseEvent satisfies this structurally, as does the plain
+ * `{clientX, clientY}` object the rAF-coalescing path synthesizes. Using this
+ * narrower type on `hoverHandlerRef` (instead of `React.MouseEvent`) prevents
+ * downstream code from reading event fields — `currentTarget`, `target`,
+ * `preventDefault` — that wouldn't survive the coalescing cast.
+ */
+export interface HoverPointerCoords {
+    clientX: number;
+    clientY: number;
+}
 /**
  * Spread raw datum properties onto HoverData if it's a non-null,
  * non-array object. Class instances (Date, etc.) are included —

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

@@ -2,7 +2,8 @@ import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
 import type { LegendGroup } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, StalenessConfig } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -52,6 +53,8 @@ export interface RealtimeEdge {
     _targetY0?: number;
     _targetY1?: number;
     _targetSankeyWidth?: number;
+    /** Set during intro animation to allow edge interpolation from width 0 */
+    _introFromZero?: boolean;
     direction?: string;
     circular?: boolean;
     circularPathData?: any;
@@ -208,6 +211,9 @@ export interface NetworkBezierEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    /** Lazily-built Path2D for hit testing; invalidated when pathD changes. */
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Ribbon edge — used by chord */
 export interface NetworkRibbonEdge {
@@ -217,6 +223,8 @@ export interface NetworkRibbonEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Curved edge — used by tree, cluster */
 export interface NetworkCurvedEdge {
@@ -226,6 +234,8 @@ export interface NetworkCurvedEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
@@ -328,6 +338,9 @@ export interface NetworkPipelineConfig {
     nodeSizeRange?: [number, number];
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Whether to animate elements on first render (nodes scale up, edges fade in) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     /** Ring arrangement mode: "flat" (all children in one ring), "solar" (one per ring),
@@ -447,6 +460,11 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     backgroundGraphics?: ReactNode;
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     orbitMode?: "flat" | "solar" | "atomic" | number[];

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

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup } from "../types/legendTypes";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane";
 export interface OrdinalScales {
@@ -28,6 +29,8 @@ export interface WedgeSceneNode {
     _pulseColor?: string;
     _pulseGlowRadius?: number;
     _targetOpacity?: number;
+    _targetStartAngle?: number;
+    _targetEndAngle?: number;
     _transitionKey?: string;
 }
 export interface BoxplotSceneNode {
@@ -153,15 +156,17 @@ export interface OrdinalPipelineConfig {
     windowMode: WindowMode;
     extentPadding: number;
     projection: "vertical" | "horizontal" | "radial";
-    oAccessor?: string | ((d: any) => string);
-    rAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
+    categoryAccessor?: string | ((d: any) => string);
+    valueAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
     colorAccessor?: string | ((d: any) => string);
     stackBy?: string | ((d: any) => string);
     groupBy?: string | ((d: any) => string);
-    multiAxis?: boolean;
     timeAccessor?: string | ((d: any) => number);
-    valueAccessor?: string | ((d: any) => number);
-    categoryAccessor?: string | ((d: any) => string);
+    /** @deprecated Use categoryAccessor */
+    oAccessor?: string | ((d: any) => string);
+    /** @deprecated Use valueAccessor */
+    rAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
+    multiAxis?: boolean;
     rExtent?: [number?, number?];
     oExtent?: string[];
     barPadding?: number;
@@ -182,34 +187,41 @@ export interface OrdinalPipelineConfig {
     amplitude?: number;
     connectorOpacity?: number;
     showLabels?: boolean;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     connectorAccessor?: string | ((d: any) => string);
     connectorStyle?: Style | ((d: any) => Style);
     dynamicColumnWidth?: string | ((data: any[]) => number);
     pieceStyle?: (d: any, category?: string) => Style;
     summaryStyle?: (d: any, category?: string) => Style;
     colorScheme?: string | string[];
+    themeCategorical?: string[];
     barColors?: Record<string, string>;
     /** ID accessor for remove() — extracts a unique identifier from each datum */
     dataIdAccessor?: string | ((d: any) => string);
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
 }
 export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     chartType: OrdinalChartType;
     runtimeMode?: "bounded" | "streaming";
     data?: T[];
-    oAccessor?: string | ((d: T) => string);
-    rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    /** Category field — the ordinal dimension (replaces oAccessor) */
+    categoryAccessor?: string | ((d: T) => string);
+    /** Value field — the quantitative dimension (replaces rAccessor). Can be array for multiAxis. */
+    valueAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
     colorAccessor?: string | ((d: T) => string);
     stackBy?: string | ((d: T) => string);
     groupBy?: string | ((d: T) => string);
-    multiAxis?: boolean;
     timeAccessor?: string | ((d: T) => number);
-    valueAccessor?: string | ((d: T) => number);
-    categoryAccessor?: string | ((d: T) => string);
+    /** @deprecated Use categoryAccessor instead */
+    oAccessor?: string | ((d: T) => string);
+    /** @deprecated Use valueAccessor instead */
+    rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    multiAxis?: boolean;
     projection?: "vertical" | "horizontal" | "radial";
     size?: [number, number];
     responsiveWidth?: boolean;
@@ -238,7 +250,7 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     rExtent?: [number?, number?];
     oExtent?: string[];
     extentPadding?: number;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     arrowOfTime?: ArrowOfTime;
     windowMode?: WindowMode;
     windowSize?: number;
@@ -256,9 +268,21 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     barColors?: Record<string, string>;
     showAxes?: boolean;
     showCategoryTicks?: boolean;
+    /** Category axis label */
+    categoryLabel?: string;
+    /** Value axis label */
+    valueLabel?: string;
+    /** Category tick formatter */
+    categoryFormat?: (d: string, index?: number) => string | ReactNode;
+    /** Value tick formatter */
+    valueFormat?: (d: number | string) => string;
+    /** @deprecated Use categoryLabel */
     oLabel?: string;
+    /** @deprecated Use valueLabel */
     rLabel?: string;
+    /** @deprecated Use categoryFormat */
     oFormat?: (d: string, index?: number) => string | ReactNode;
+    /** @deprecated Use valueFormat */
     rFormat?: (d: number | string) => string;
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
@@ -298,6 +322,10 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
@@ -309,6 +337,19 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
 export interface StreamOrdinalFrameHandle<T = Record<string, any>> {
     push(datum: T): void;
     pushMany(data: T[]): void;
+    /** Replace all data. Unlike `clear() + pushMany()`, `replace()` preserves
+     *  the previous scene's position snapshot so data-change transitions fire.
+     *  Use when you need to swap in a full new dataset (e.g. re-aggregated
+     *  values from streaming input) and want the bars/points/etc. to animate
+     *  between the old and new positions.
+     *
+     *  Note: for datasets within the DataSourceAdapter chunk threshold (the
+     *  common case for aggregator HOCs like LikertChart) the replacement
+     *  lands in a single changeset. Larger datasets fall through to the
+     *  progressive-chunked path used by the `data` prop — the first chunk
+     *  resets + seeds the buffer, subsequent chunks append on successive
+     *  animation frames, so replacement is not instantaneous for large N. */
+    replace(data: T[]): void;
     /** Remove data items by ID. Requires dataIdAccessor. */
     remove(id: string | string[]): T[];
     /** Update data items by ID in place. Requires dataIdAccessor. Returns previous values. */

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

@@ -40,3 +40,24 @@ export declare function lerp(from: number, to: number, t: number): number;
  * Get the current timestamp in a way that works both in browser and Node.
  */
 export declare function now(): number;
+/** The animate prop type accepted by all HOCs and Stream Frames.
+ *  Single source of truth — re-exported by types.ts, ordinalTypes.ts, networkTypes.ts, geoTypes.ts. */
+export type AnimateProp = boolean | {
+    duration?: number;
+    easing?: "linear" | "ease-out";
+    intro?: boolean;
+};
+/**
+ * Resolve the declarative `animate` prop into a concrete TransitionConfig.
+ * Used by all 4 Stream Frames. `animate` takes precedence over `transitionProp`.
+ */
+export declare function resolveAnimateConfig(animate: AnimateProp | undefined, transitionProp: {
+    duration?: number;
+    easing?: "ease-out" | "linear";
+} | undefined): {
+    transition: {
+        duration?: number;
+        easing?: "ease-out" | "linear";
+    } | undefined;
+    introEnabled: boolean;
+};

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

@@ -0,0 +1,22 @@
+import type { Quadtree } from "d3-quadtree";
+export interface QuadtreeHit<T> {
+    node: T;
+    distance: number;
+}
+/**
+ * Find the closest point whose own hit radius contains the cursor.
+ *
+ * Uses `quadtree.visit()` to enumerate every candidate within the widened
+ * search radius (maxDistance extended by the largest point radius in the
+ * scene). `quadtree.find()` alone is insufficient because it returns the
+ * nearest candidate by center-to-center distance — a farther point with a
+ * much larger visual radius can still be a valid hit that `find()` would
+ * hide.
+ *
+ * `T` must expose `x`, `y`, and `r` — the standard `PointSceneNode` shape.
+ */
+export declare function findHitPointInQuadtree<T extends {
+    x: number;
+    y: number;
+    r: number;
+}>(qt: Quadtree<T>, px: number, py: number, maxDistance: number, maxPointRadius: number): QuadtreeHit<T> | null;

package/dist/components/stream/renderers/resolveCSSColor.d.ts

@@ -5,13 +5,30 @@
  * reads the computed value from the canvas element. Otherwise returns
  * the input unchanged.
  *
- * Per-canvas cache avoids repeated getComputedStyle calls within a single
- * paint cycle. The cache is cleared on theme changes via clearCSSColorCache(),
- * which each Stream Frame calls in its theme-change useEffect.
+ * Per-canvas cache avoids repeated `getComputedStyle` calls. Cached entries
+ * are tagged with a global version counter that's bumped whenever a theme
+ * change is detected — either through `clearCSSColorCache()` (called by
+ * Stream Frames on `currentTheme` change) or via the global observer below
+ * (catches external class toggles on `<html>` and `prefers-color-scheme`
+ * media-query changes that bypass React).
  */
 export declare function resolveCSSColor(ctx: CanvasRenderingContext2D, value: string | undefined): string | undefined;
 /**
- * Clear the per-canvas CSS variable cache. Called by Stream Frames
- * when the theme changes so the next paint reads fresh computed values.
+ * Invalidate the CSS variable cache. Stream Frames call this from their
+ * `currentTheme` `useEffect` so the next paint reads fresh computed values.
+ *
+ * The `canvas` argument is accepted for backward compatibility but ignored —
+ * invalidation is global because theme changes are global.
+ */
+export declare function clearCSSColorCache(_canvas?: HTMLCanvasElement): void;
+/**
+ * Test-only: reset all cache state, including disconnecting any installed
+ * observer/matchMedia listeners. Required for test isolation — without it,
+ * observers accumulate across files and bump `currentVersion` more than once
+ * per real DOM mutation.
+ *
+ * `currentVersion` is *incremented* (not reset to zero) so any WeakMap entries
+ * that survive from a previous test can't accidentally be re-validated by a
+ * version collision.
  */
-export declare function clearCSSColorCache(canvas: HTMLCanvasElement): void;
+export declare function _resetCSSColorCacheForTest(): void;