semiotic 3.3.1 → 3.4.1

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

@@ -1,21 +1,22 @@
 import type { ScaleLinear } from "d3-scale";
 import type { OrdinalScales, OrdinalColumn, OrdinalPipelineConfig, OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { Style } from "../types";
+import type { Datum } from "../../charts/shared/datumTypes";
 export interface OrdinalSceneContext {
     scales: OrdinalScales;
     columns: Record<string, OrdinalColumn>;
     config: OrdinalPipelineConfig;
-    getR: (d: any) => number;
-    getStack?: (d: any) => string;
-    getGroup?: (d: any) => string;
-    getColor?: (d: any) => string;
-    getConnector?: (d: any) => string;
-    getO: (d: any) => string;
+    getR: (d: Datum) => number;
+    getStack?: (d: Datum) => string;
+    getGroup?: (d: Datum) => string;
+    getColor?: (d: Datum) => string;
+    getConnector?: (d: Datum) => string;
+    getO: (d: Datum) => string;
     multiScales: ScaleLinear<number, number>[];
-    rAccessors: ((d: any) => number)[];
+    rAccessors: ((d: Datum) => number)[];
     resolvePieceStyle: (d: any, category?: string) => Style;
     resolveSummaryStyle: (d: any, category?: string) => Style;
     /** For timeline: resolve rAccessor as [start, end] */
-    getRawRange: (d: any) => [number, number] | null;
+    getRawRange: (d: Datum) => [number, number] | null;
 }
 export type SceneBuilderFn = (ctx: OrdinalSceneContext, layout: OrdinalLayout) => OrdinalSceneNode[];

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

@@ -1,8 +1,10 @@
 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 { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup } from "../types/legendTypes";
+import type { Datum } from "../charts/shared/datumTypes";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane";
 export interface OrdinalScales {
     o: ScaleBand<string>;
@@ -28,6 +30,8 @@ export interface WedgeSceneNode {
     _pulseColor?: string;
     _pulseGlowRadius?: number;
     _targetOpacity?: number;
+    _targetStartAngle?: number;
+    _targetEndAngle?: number;
     _transitionKey?: string;
 }
 export interface BoxplotSceneNode {
@@ -140,7 +144,7 @@ export interface OrdinalColumn {
     width: number;
     middle: number;
     padding: number;
-    pieceData: Record<string, any>[];
+    pieceData: Datum[];
     /** For radial: proportion of total (0-1) */
     pct: number;
     /** For radial: cumulative start proportion */
@@ -153,20 +157,36 @@ 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)>;
-    colorAccessor?: string | ((d: any) => string);
-    stackBy?: string | ((d: any) => string);
-    groupBy?: string | ((d: any) => string);
+    categoryAccessor?: string | ((d: Datum) => string);
+    valueAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
+    colorAccessor?: string | ((d: Datum) => string);
+    stackBy?: string | ((d: Datum) => string);
+    groupBy?: string | ((d: Datum) => string);
+    timeAccessor?: string | ((d: Datum) => number);
+    /** @deprecated Use categoryAccessor */
+    oAccessor?: string | ((d: Datum) => string);
+    /** @deprecated Use valueAccessor */
+    rAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
     multiAxis?: boolean;
-    timeAccessor?: string | ((d: any) => number);
-    valueAccessor?: string | ((d: any) => number);
-    categoryAccessor?: string | ((d: any) => string);
     rExtent?: [number?, number?];
     oExtent?: string[];
     barPadding?: number;
     /** Rounded top corner radius for bar charts. Only the end away from the baseline is rounded. For stacked bars, only the topmost segment gets rounded. */
     roundedTop?: number;
+    /** Gradient fill for bar rects. `{ topOpacity, bottomOpacity }` fades the
+     *  resolved fill color from tip (opposite the baseline) to base; `{ colorStops }`
+     *  renders a multi-color gradient along the same axis. Direction follows the
+     *  bar's orientation (tip → base). Same shape as AreaChart.gradientFill
+     *  sans the `boolean` case — the HOC resolves `true` to default opacities. */
+    gradientFill?: {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     /** When true, adds padding below the 0 baseline. When false (default), bars are flush with the axis line. */
     baselinePadding?: boolean;
     innerRadius?: number;
@@ -182,34 +202,47 @@ export interface OrdinalPipelineConfig {
     amplitude?: number;
     connectorOpacity?: number;
     showLabels?: boolean;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
-    connectorAccessor?: string | ((d: any) => string);
-    connectorStyle?: Style | ((d: any) => Style);
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
+    connectorAccessor?: string | ((d: Datum) => string);
+    connectorStyle?: Style | ((d: Datum) => Style);
     dynamicColumnWidth?: string | ((data: any[]) => number);
     pieceStyle?: (d: any, category?: string) => Style;
     summaryStyle?: (d: any, category?: string) => Style;
     colorScheme?: string | string[];
+    themeCategorical?: string[];
+    /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name — fallback for magnitude encodings. */
+    themeSequential?: string;
+    /** Theme diverging scheme name — fallback for midpoint encodings (LikertChart). */
+    themeDiverging?: string;
     barColors?: Record<string, string>;
     /** ID accessor for remove() — extracts a unique identifier from each datum */
-    dataIdAccessor?: string | ((d: any) => string);
+    dataIdAccessor?: string | ((d: Datum) => 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>> {
+export interface StreamOrdinalFrameProps<T = Datum> {
     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;
@@ -222,6 +255,17 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     };
     barPadding?: number;
     roundedTop?: number;
+    /** Gradient fill for bar rects. Same shape as AreaChart.gradientFill sans
+     *  the boolean case — resolve booleans at the HOC layer. */
+    gradientFill?: {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     baselinePadding?: boolean;
     innerRadius?: number;
     cornerRadius?: number;
@@ -238,14 +282,13 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     rExtent?: [number?, number?];
     oExtent?: string[];
     extentPadding?: number;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
-    arrowOfTime?: ArrowOfTime;
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     windowMode?: WindowMode;
     windowSize?: number;
     connectorAccessor?: string | ((d: T) => string);
-    connectorStyle?: Style | ((d: any) => Style);
+    connectorStyle?: Style | ((d: Datum) => Style);
     /** ID accessor for remove()/update() — extracts a unique identifier from each datum */
-    dataIdAccessor?: string | ((d: any) => string);
+    dataIdAccessor?: string | ((d: Datum) => string);
     /** Custom tick values for the value (r) axis. Overrides the default d3 ticks. */
     rTickValues?: number[];
     /** Align first tick label to start and last tick label to end. Default false. */
@@ -256,16 +299,28 @@ 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;
     tooltipContent?: (d: HoverData) => ReactNode;
     customHoverBehavior?: (d: HoverData | null) => void;
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
@@ -298,6 +353,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;
@@ -306,9 +365,22 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     /** Accessible summary rendered as a screen-reader-only note */
     summary?: string;
 }
-export interface StreamOrdinalFrameHandle<T = Record<string, any>> {
+export interface StreamOrdinalFrameHandle<T = Datum> {
     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. */
@@ -322,4 +394,5 @@ export interface OrdinalLayout {
     height: number;
 }
 export type OrdinalRendererFn = (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], scales: OrdinalScales, layout: OrdinalLayout) => void;
-export type { HoverData, HoverAnnotationConfig, AnnotationContext, ArrowOfTime, WindowMode };
+export type { HoverData, HoverAnnotationConfig, AnnotationContext, WindowMode };
+export type { ArrowOfTime } from "../realtime/types";

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Shared decay encoding utilities for all pipeline stores.
  *
@@ -18,4 +19,4 @@ export declare function computeDecayOpacity(decay: DecayConfig, bufferIndex: num
  * Apply decay opacity to a list of scene nodes.
  * Uses the datum's index in the buffer data array.
  */
-export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Record<string, any>[]): void;
+export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[]): void;

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Pulse encoding for XY pipeline scene nodes.
  *
@@ -17,7 +18,7 @@ export declare function computePulseIntensity(pulse: PulseConfig, insertTime: nu
 /**
  * Apply pulse glow to scene nodes using insertion timestamps.
  */
-export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Record<string, any>[], timestampBuffer: RingBuffer<number>): void;
+export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>): void;
 /**
  * Check whether there are active pulse animations needing continuous rendering.
  */

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/pipelineTransitions.d.ts

@@ -12,6 +12,7 @@
  */
 import type { SceneNode, TransitionConfig } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { Datum } from "../charts/shared/datumTypes";
 export type PrevPosition = {
     x: number;
     y: number;
@@ -19,6 +20,10 @@ export type PrevPosition = {
     h?: number;
     r?: number;
     opacity?: number;
+    openY?: number;
+    closeY?: number;
+    highY?: number;
+    lowY?: number;
 };
 export type PrevPath = {
     topPath?: [number, number][];
@@ -29,12 +34,19 @@ export type PrevPath = {
 /** Context needed from PipelineStore for identity resolution */
 export interface TransitionContext {
     runtimeMode?: "streaming" | "bounded";
-    getX: (d: any) => number;
-    getY: (d: any) => number;
-    getCategory?: (d: any) => string;
+    getX: (d: Datum) => number;
+    getY: (d: Datum) => number;
+    getCategory?: (d: Datum) => string;
 }
 /**
  * Get a stable identity key for a scene node.
+ *
+ * Exit stubs (created during startTransition for scrolled-off nodes) have
+ * `datum: null` and carry their original identity on `_transitionKey`. If a
+ * new transition starts while exits are still in the scene, resolving their
+ * identity via the datum-less fallback (e.g. `c:${index}`) would reshuffle
+ * which exit matches which key on the next snapshot. Preferring the stored
+ * `_transitionKey` keeps exits stable across overlapping transitions.
  */
 export declare function getNodeIdentity(ctx: TransitionContext, node: SceneNode, index: number): string | null;
 /**
@@ -56,4 +68,4 @@ export declare function startTransition(ctx: TransitionContext, transition: Tran
  * Advance the transition animation. Returns true if still animating.
  * Mutates scene nodes in place.
  */
-export declare function advanceTransition(now: number, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): boolean;
+export declare function advanceTransition(now: number, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, _prevPathMap: Map<string, PrevPath>): 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/colorUtils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Color utilities shared across canvas renderers.
+ *
+ * Kept here (not in layouts/hierarchyUtils or a deeper shared module) so
+ * renderers don't reach into unrelated layers for primitive helpers.
+ */
+/**
+ * Resolve any valid CSS color string to an [r, g, b] tuple.
+ *
+ * Uses the canvas's own fillStyle round-trip to normalize first: assigning a
+ * CSS color to `ctx.fillStyle` and reading it back always yields `#rrggbb`
+ * or `rgba(r, g, b, a)`. That means named colors (`red`, `steelblue`), hsl(),
+ * and any other valid CSS form work the same as hex and rgb. Without the
+ * normalization pass a bare regex parser silently falls back on anything it
+ * doesn't match — gradients from named colors would render gray.
+ *
+ * The prior fillStyle is restored so this is callable from the middle of a
+ * draw without disturbing in-progress paint state.
+ */
+export declare function parseCanvasColor(ctx: CanvasRenderingContext2D, color: string): [number, number, number];

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;

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

@@ -1,6 +1,22 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export interface ThemeSemanticColors {
+    primary?: string;
+    secondary?: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+    text?: string;
+    textSecondary?: string;
+    border?: string;
+    grid?: string;
+    surface?: string;
+}
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
     /** Exponential: half-life in buffer positions (default: bufferSize/2) */
@@ -107,6 +123,8 @@ export interface LineSceneNode {
     _prevPath?: [number, number][];
     /** Target path coordinates for interpolation during transitions */
     _targetPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals line from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface AreaSceneNode {
     type: "area";
@@ -156,6 +174,8 @@ export interface AreaSceneNode {
     _prevBottomPath?: [number, number][];
     /** Target bottom path coordinates for interpolation during transitions */
     _targetBottomPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals area from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface PointSceneNode {
     type: "point";
@@ -189,8 +209,23 @@ export interface RectSceneNode {
     h: number;
     /** Rounded corner radius on the end away from the baseline */
     roundedTop?: number;
-    /** Which edge to round: "top"/"bottom" (vertical), "right"/"left" (horizontal) */
+    /** Which edge is the "tip" (opposite the baseline): "top"/"bottom" for
+     *  vertical orientation, "right"/"left" for horizontal. Used by the
+     *  renderer for rounded-corner placement AND gradient direction. Set by
+     *  bar scene builders unconditionally so gradients resolve without
+     *  requiring roundedTop. */
     roundedEdge?: "top" | "bottom" | "right" | "left";
+    /** Gradient fill — same shape as the area-scene version. Runs tip → base
+     *  along the bar axis (inferred from `roundedEdge`). */
+    fillGradient?: {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     style: Style;
     datum: any;
     group?: string;
@@ -263,6 +298,13 @@ export interface CandlestickSceneNode {
     _decayOpacity?: number;
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
+    /** Geometry targets — set during a transition so advanceTransition can lerp
+     *  toward them from the snapshotted prev position. Cleared on completion. */
+    _targetX?: number;
+    _targetOpenY?: number;
+    _targetCloseY?: number;
+    _targetHighY?: number;
+    _targetLowY?: number;
 }
 export interface CandlestickStyle {
     upColor?: string;
@@ -273,11 +315,20 @@ export interface CandlestickStyle {
     /** Single color for range/dumbbell mode (replaces up/down when no open/close provided) */
     rangeColor?: string;
 }
-export interface Changeset<T = Record<string, any>> {
+export interface Changeset<T = Datum> {
     inserts: T[];
     bounded: boolean;
     /** Hint: total dataset size when progressively chunking bounded data */
     totalSize?: number;
+    /** When true on a bounded changeset, the store replaces the buffer
+     *  contents but does NOT clear its category insertion-order memory
+     *  and marks itself as having received streaming-sourced data. Used
+     *  by aggregator HOCs (LikertChart, future density/bin charts) that
+     *  re-derive their full dataset from streaming input on every push —
+     *  the user perceives it as a stream even though the transport is
+     *  a wholesale replacement. Without this, re-aggregation would wipe
+     *  the category order and categories would shuffle on every tick. */
+    preserveCategoryOrder?: boolean;
 }
 /**
  * Note: when xScaleType="time", the x scale is a d3.scaleTime at runtime
@@ -293,7 +344,7 @@ export interface StreamLayout {
     height: number;
 }
 export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom" | "natural";
-export interface StreamXYFrameProps<T = Record<string, any>> {
+export interface StreamXYFrameProps<T = Datum> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
     data?: T[];
@@ -403,8 +454,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     yLabel?: string;
     /** Label for the right Y axis (dual-axis charts) */
     yLabelRight?: string;
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
-    yFormat?: (d: any) => string | ReactNode;
+    xFormat?: (d: number | Date | string, index?: number, allTicks?: number[]) => string | ReactNode;
+    yFormat?: (d: number | Date | string) => string | ReactNode;
     tickFormatTime?: (value: number) => string;
     tickFormatValue?: (value: number) => string;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
@@ -434,8 +485,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     } | null) => void;
     /** Accessor for unique point IDs used by point-anchored annotations */
     pointIdAccessor?: string | ((d: T) => string);
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {
         legendGroups: any[];
@@ -467,6 +518,10 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     pulse?: PulseConfig;
     /** Smooth position transitions on data change */
     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;
     /** Frame-level data liveness indicator */
     staleness?: StalenessConfig;
     /** Marginal distribution plots in axis margins (histogram, violin, ridgeline, boxplot) */
@@ -492,7 +547,7 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     /** Source chart ID — crosshair is suppressed on the source chart to avoid double rendering */
     linkedCrosshairSourceId?: string;
 }
-export interface StreamXYFrameHandle<T = Record<string, any>> {
+export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;
     pushMany(data: T[]): void;
     /** Remove data points by ID. Requires pointIdAccessor. */