semiotic 3.1.2 → 3.2.1

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

@@ -3,7 +3,7 @@ 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 { LegendGroup } from "../types/legendTypes";
-export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline";
+export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane";
 export interface OrdinalScales {
     o: ScaleBand<string>;
     r: ScaleLinear<number, number>;
@@ -102,9 +102,18 @@ export interface ConnectorSceneNode {
     group?: string;
     _targetOpacity?: number;
 }
+export interface TrapezoidSceneNode {
+    type: "trapezoid";
+    /** Four corners: [top-left, top-right, bottom-right, bottom-left] */
+    points: [number, number][];
+    style: Style;
+    datum: any;
+    category?: string;
+    _targetOpacity?: number;
+}
 export type { Style, PointSceneNode, RectSceneNode } from "./types";
 import type { PointSceneNode, RectSceneNode } from "./types";
-export type OrdinalSceneNode = RectSceneNode | PointSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode;
+export type OrdinalSceneNode = RectSceneNode | PointSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
 export interface OrdinalColumn {
     name: string;
     x: number;
@@ -144,6 +153,8 @@ export interface OrdinalPipelineConfig {
     showOutliers?: boolean;
     showIQR?: boolean;
     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);
@@ -189,6 +200,8 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     showOutliers?: boolean;
     showIQR?: boolean;
     amplitude?: number;
+    connectorOpacity?: number;
+    showLabels?: boolean;
     rExtent?: [number?, number?];
     oExtent?: string[];
     extentPadding?: number;
@@ -203,9 +216,10 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     colorScheme?: string | string[];
     barColors?: Record<string, string>;
     showAxes?: boolean;
+    showCategoryTicks?: boolean;
     oLabel?: string;
     rLabel?: string;
-    oFormat?: (d: string) => string;
+    oFormat?: (d: string, index?: number) => string;
     rFormat?: (d: number | string) => string;
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
@@ -234,12 +248,24 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     className?: string;
     background?: string;
     centerContent?: ReactNode;
+    /** Brush configuration. "r" brushes the value axis. */
+    brush?: boolean | "r" | {
+        dimension?: "r";
+    };
+    /** Callback when brush selection changes. Extent is in data coordinates, or null when cleared. */
+    onBrush?: (extent: {
+        r: [number, number];
+    } | null) => void;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
     staleness?: StalenessConfig;
-    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
+    /** Accessible description overriding the auto-generated aria-label on the chart container */
+    description?: string;
+    /** Accessible summary rendered as a screen-reader-only note */
+    summary?: string;
 }
 export interface StreamOrdinalFrameHandle<T = Record<string, any>> {
     push(datum: T): void;

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

@@ -0,0 +1,20 @@
+/**
+ * Decay encoding for XY pipeline scene nodes.
+ *
+ * Applies age-based opacity fade to scene nodes — linear, exponential, or step.
+ * Per-vertex decay for line/area nodes, uniform for discrete nodes (point, rect, etc.).
+ *
+ * Dependencies: types (SceneNode, DecayConfig)
+ * Consumed by: PipelineStore.computeScene (after scene build, before transitions)
+ */
+import type { SceneNode, DecayConfig } from "./types";
+/**
+ * Compute decay opacity for a datum at `bufferIndex` out of `bufferSize` items.
+ * Index 0 = oldest, bufferSize-1 = newest. Returns 0–1.
+ */
+export declare function computeDecayOpacity(decay: DecayConfig, bufferIndex: number, bufferSize: number): number;
+/**
+ * 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;

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

@@ -0,0 +1,24 @@
+/**
+ * Pulse encoding for XY pipeline scene nodes.
+ *
+ * Applies time-based glow to recently-inserted data points. Intensity fades
+ * from 1 (just inserted) to 0 (pulse expired) over a configurable duration.
+ *
+ * Dependencies: types (SceneNode, PulseConfig), RingBuffer (timestamp buffer)
+ * Consumed by: PipelineStore.computeScene (after decay, before transitions)
+ */
+import type { SceneNode, PulseConfig } from "./types";
+import type { RingBuffer } from "../realtime/RingBuffer";
+/**
+ * Compute pulse intensity for a datum inserted at `insertTime`.
+ * Returns 0–1 (1 = just inserted, 0 = pulse expired).
+ */
+export declare function computePulseIntensity(pulse: PulseConfig, insertTime: number, now: number): number;
+/**
+ * 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;
+/**
+ * Check whether there are active pulse animations needing continuous rendering.
+ */
+export declare function hasActivePulses(pulse: PulseConfig, timestampBuffer: RingBuffer<number> | null): boolean;

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

@@ -0,0 +1,59 @@
+/**
+ * Transition animation for XY pipeline scene nodes.
+ *
+ * Handles identity-based enter/update/exit transitions:
+ *   - snapshotPositions: captures current scene state before rebuild
+ *   - getNodeIdentity: stable key generation per node type
+ *   - startTransition: sets up interpolation from old→new positions
+ *   - advanceTransition: per-frame tick with easing
+ *
+ * Dependencies: pipelineTransitionUtils (lerp, easing, ActiveTransition)
+ * Consumed by: PipelineStore.computeScene (after decay/pulse)
+ */
+import type { SceneNode, TransitionConfig } from "./types";
+import type { ActiveTransition } from "./pipelineTransitionUtils";
+export type PrevPosition = {
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    r?: number;
+    opacity?: number;
+};
+export type PrevPath = {
+    topPath?: [number, number][];
+    bottomPath?: [number, number][];
+    path?: [number, number][];
+    opacity?: number;
+};
+/** 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;
+}
+/**
+ * Get a stable identity key for a scene node.
+ */
+export declare function getNodeIdentity(ctx: TransitionContext, node: SceneNode, index: number): string | null;
+/**
+ * Snapshot current scene node positions before rebuild.
+ */
+export declare function snapshotPositions(ctx: TransitionContext, scene: SceneNode[], prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): void;
+export interface TransitionState {
+    scene: SceneNode[];
+    exitNodes: SceneNode[];
+    activeTransition: ActiveTransition | null;
+}
+/**
+ * After scene rebuild, set up transition from old to new positions.
+ * Detects entering nodes (new, no prev match) and exiting nodes (prev, no new match).
+ * Mutates scene and exitNodes in place. Returns updated state.
+ */
+export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): TransitionState;
+/**
+ * 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;

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

@@ -0,0 +1,12 @@
+import type { OrdinalLayout, OrdinalScales, OrdinalSceneNode } from "../ordinalTypes";
+export declare const barFunnelHatchRenderer: (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], _scales: OrdinalScales, _layout: OrdinalLayout) => void;
+/**
+ * Canvas renderer for bar-funnel labels.
+ *
+ * Draws a floating label above each bar (or bar group) showing:
+ *  - Bold percentage (of first step)
+ *  - Raw value below it
+ *
+ * Labels appear on a white rounded-rect background (matching the reference images).
+ */
+export declare const barFunnelLabelRenderer: (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], _scales: OrdinalScales, _layout: OrdinalLayout) => void;

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

@@ -1,7 +1,8 @@
 import type { StreamRendererFn } from "./types";
 /**
  * Canvas point renderer.
- * Renders PointSceneNode as circles. Used for Scatterplot, BubbleChart, and SwarmChart.
+ * Renders PointSceneNode as circles. Used by Scatterplot, BubbleChart, SwarmChart,
+ * and showPoints on LineChart, AreaChart, and StackedAreaChart.
  * Supports pulse glow effect via _pulseIntensity/_pulseColor fields.
  */
 export declare const pointCanvasRenderer: StreamRendererFn;

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

@@ -0,0 +1,15 @@
+import type { OrdinalLayout, OrdinalScales, OrdinalSceneNode } from "../ordinalTypes";
+/**
+ * Canvas renderer for trapezoid (funnel connector) nodes.
+ * Draws filled quadrilaterals connecting consecutive funnel steps.
+ */
+export declare const trapezoidCanvasRenderer: (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], _scales: OrdinalScales, _layout: OrdinalLayout) => void;
+/**
+ * Canvas renderer for funnel labels.
+ *
+ * Renders white text with dark outline (matching reference images):
+ *  - Step name: bold, centered at row top, shown once per step
+ *  - Value (percent): bold, centered in each bar. Suppressed if text overflows bar.
+ *    First step suppresses "(100%)" since it's always 100%.
+ */
+export declare const funnelLabelRenderer: (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], _scales: OrdinalScales, _layout: OrdinalLayout) => void;

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

@@ -0,0 +1,10 @@
+import type { SceneNode } from "./types";
+/**
+ * Extract a display color from a scene node's style.
+ * For lines/areas, prefers stroke (the visible line color).
+ * For points/rects, prefers fill.
+ * For heatcells, reads the top-level `fill` field (style is optional).
+ * For candlesticks, uses `upColor`/`downColor` based on direction.
+ * Returns null if no color can be resolved (e.g. CanvasPattern fill with no stroke).
+ */
+export declare function resolveNodeColor(node: SceneNode | null): string | null;

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

@@ -61,7 +61,8 @@ export interface Style {
     strokeWidth?: number;
     strokeDasharray?: string;
     strokeLinecap?: "butt" | "round" | "square";
-    fill?: string;
+    /** Fill color or CanvasPattern (e.g. from createHatchPattern) */
+    fill?: string | CanvasPattern;
     fillOpacity?: number;
     opacity?: number;
     /** For icon/isotype bars: an image to stamp instead of filling */
@@ -91,6 +92,8 @@ export interface LineSceneNode {
     _decayOpacities?: number[];
     /** Animation target opacity (set during enter/exit transitions) */
     _targetOpacity?: number;
+    /** Captured start opacity for linear interpolation (avoids compounding from per-tick mutation) */
+    _startOpacity?: number;
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
     /** Previous path coordinates for interpolation during transitions */
@@ -122,6 +125,8 @@ export interface AreaSceneNode {
     _decayOpacities?: number[];
     /** Animation target opacity (set during enter/exit transitions) */
     _targetOpacity?: number;
+    /** Captured start opacity for linear interpolation (avoids compounding from per-tick mutation) */
+    _startOpacity?: number;
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
     /** Previous top path coordinates for interpolation during transitions */
@@ -342,13 +347,15 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
         orient: "left" | "right" | "top" | "bottom";
         label?: string;
         ticks?: number;
-        tickFormat?: (d: any) => string;
+        tickFormat?: (d: any, index?: number, allTicks?: number[]) => string;
         baseline?: boolean | "under";
         jaggedBase?: boolean;
     }>;
     xLabel?: string;
     yLabel?: string;
-    xFormat?: (d: any) => string;
+    /** Label for the right Y axis (dual-axis charts) */
+    yLabelRight?: string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     yFormat?: (d: any) => string;
     tickFormatTime?: (value: number) => string;
     tickFormatValue?: (value: number) => string;
@@ -360,6 +367,12 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     brush?: {
         /** Which dimension(s) to brush: "x", "y", or "xy" (default "xy") */
         dimension?: "x" | "y" | "xy";
+        /** Snap mode: "continuous" (default) for pixel-precise, "bin" to snap to bin boundaries */
+        snap?: "continuous" | "bin";
+        /** Actual bin boundary values for data-driven snapping (overrides uniform grid math) */
+        binBoundaries?: number[];
+        /** When true, snap during drag (not just on release). Default false. */
+        snapDuring?: boolean;
     };
     /** Callback when brush selection changes. Called with data-space extent, or null when cleared. */
     onBrush?: (extent: {
@@ -391,6 +404,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     foregroundGraphics?: ReactNode;
     /** Canvas renderers executed before the chart-type renderers (e.g. connecting lines under points) */
     canvasPreRenderers?: CanvasRendererFn[];
+    /** SVG pre-renderers for SSR — SVG equivalent of canvasPreRenderers, rendered under data marks */
+    svgPreRenderers?: SVGPreRendererFn[];
     title?: string | ReactNode;
     categoryAccessor?: string | ((d: T) => string);
     /** Configurable opacity decay for older data points */
@@ -413,8 +428,16 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     showValues?: boolean;
     /** Format function for heatmap cell value labels */
     heatmapValueFormat?: (v: number) => string;
-    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
+    /** Accessible description overriding the auto-generated aria-label on the chart container */
+    description?: string;
+    /** Accessible summary rendered as a screen-reader-only note */
+    summary?: string;
+    /** Name of the linked crosshair store entry — enables coordinate-based crosshair rendering */
+    linkedCrosshairName?: string;
+    /** Source chart ID — crosshair is suppressed on the source chart to avoid double rendering */
+    linkedCrosshairSourceId?: string;
 }
 export interface StreamXYFrameHandle<T = Record<string, any>> {
     push(datum: T): void;
@@ -428,4 +451,6 @@ export interface StreamXYFrameHandle<T = Record<string, any>> {
     } | null;
 }
 export type CanvasRendererFn = (ctx: CanvasRenderingContext2D, nodes: SceneNode[], scales: StreamScales, layout: StreamLayout) => void;
+/** SVG equivalent of CanvasRendererFn — returns React elements for SSR/SVG rendering */
+export type SVGPreRendererFn = (nodes: SceneNode[], scales: StreamScales, layout: StreamLayout) => ReactNode;
 export type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode };

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

@@ -0,0 +1,11 @@
+/** Safari 14 fallback for MediaQueryList listener registration */
+export declare function addMqlListener(mql: MediaQueryList, handler: (e: MediaQueryListEvent) => void): () => void;
+/**
+ * SSR-safe hook that returns true when the user prefers reduced motion.
+ * Initializes from matchMedia synchronously to avoid a flash of animation.
+ */
+export declare function useReducedMotion(): boolean;
+/**
+ * SSR-safe hook that returns true when forced-colors or high-contrast mode is active.
+ */
+export declare function useHighContrast(): boolean;

package/dist/components/stream/xySceneBuilders/areaScene.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Area and stacked area scene builders.
+ *
+ * buildAreaScene — single/multi-group areas with gradient fill and curve support.
+ * buildStackedAreaScene — stable-order stacking with optional normalization.
+ *
+ * Dependencies: SceneGraph (buildAreaNode, buildStackedAreaNodes)
+ * Consumed by: PipelineStore.buildSceneNodes (chartTypes "area", "stackedarea")
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildStackedAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/barScene.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Realtime histogram bar scene builder.
+ *
+ * Builds binned bars with optional category stacking. Maintains stable
+ * category order via barColors keys + alphabetical fallback to prevent
+ * flicker when bins partially exit the sliding window.
+ *
+ * Dependencies: BinAccumulator (computeBins), SceneGraph (buildRectNode)
+ * Consumed by: PipelineStore.buildSceneNodes (chartType "bar")
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export interface BarSceneResult {
+    nodes: SceneNode[];
+    /** Sorted bin boundary values (edges of all bins) for data-driven brush snapping */
+    binBoundaries: number[];
+}
+export declare function buildBarScene(ctx: XYSceneContext, data: Record<string, any>[]): BarSceneResult;

package/dist/components/stream/xySceneBuilders/boundsScene.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bounds scene builder — produces an AreaSceneNode for confidence bands/envelopes.
+ *
+ * Consumed by: lineScene (renders bounds behind lines)
+ */
+import type { AreaSceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildBoundsForGroup(ctx: XYSceneContext, data: Record<string, any>[], group: string): AreaSceneNode | null;

package/dist/components/stream/xySceneBuilders/candlestickScene.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Candlestick (OHLC) scene builder.
+ *
+ * Renders open-high-low-close bars with auto-width sizing based on data spacing.
+ *
+ * Consumed by: PipelineStore.buildSceneNodes (chartType "candlestick")
+ */
+import type { SceneNode, StreamLayout } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildCandlestickScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/emitPointNodes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared helper for emitting PointSceneNodes from grouped data.
+ *
+ * Used by line, area, and stacked area scene builders when the HOC's
+ * `showPoints` prop is active (i.e., `ctx.config.pointStyle` is set).
+ * Handles group color fallback for push API mode and pointId passthrough.
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function emitPointNodes(ctx: XYSceneContext, groups: {
+    key: string;
+    data: Record<string, any>[];
+}[], nodes: SceneNode[], yGetOverride?: (d: Record<string, any>) => number): void;

package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts

@@ -0,0 +1,3 @@
+import type { SceneNode, StreamLayout } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildHeatmapScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/lineScene.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Line scene builder — produces LineSceneNode[] from grouped data.
+ *
+ * Handles: color thresholds from annotations, bounds/envelope areas,
+ * and curve type attachment for canvas interpolation.
+ *
+ * Dependencies: SceneGraph (buildLineNode), boundsScene (buildBoundsForGroup)
+ * Consumed by: PipelineStore.buildSceneNodes (chartType "line")
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildLineScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Point/scatter/bubble scene builder.
+ *
+ * Handles: size scaling from sizeAccessor, color mapping from colorAccessor,
+ * and pointId attachment for hit testing.
+ *
+ * Dependencies: SceneGraph (buildPointNode)
+ * Consumed by: PipelineStore.buildSceneNodes (chartTypes "scatter", "bubble")
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildPointScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/swarmScene.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Realtime swarm chart scene builder.
+ *
+ * Simple point scatter with category-based coloring from barColors config.
+ *
+ * Consumed by: PipelineStore.buildSceneNodes (chartType "swarm")
+ */
+import type { SceneNode } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildSwarmScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];

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

@@ -0,0 +1,93 @@
+/**
+ * XYSceneContext — shared context passed to all XY scene builder functions.
+ *
+ * Mirrors the ordinal pattern (OrdinalSceneContext in ordinalSceneBuilders/).
+ * Scene builders are pure functions that receive this context instead of
+ * accessing PipelineStore instance fields directly.
+ */
+import type { StreamScales, Style, CurveType } from "../types";
+export interface XYSceneContext {
+    scales: StreamScales;
+    config: XYSceneConfig;
+    getX: (d: any) => number;
+    getY: (d: any) => number;
+    getY0?: (d: any) => number | null;
+    getSize?: (d: any) => number;
+    getColor?: (d: any) => string;
+    getGroup?: (d: any) => string;
+    getCategory?: (d: any) => string;
+    getPointId?: (d: any) => string;
+    getBounds?: (d: any) => number | null;
+    getOpen?: (d: any) => number;
+    getHigh?: (d: any) => number;
+    getLow?: (d: any) => number;
+    getClose?: (d: any) => number;
+    /** Style resolvers — delegate to PipelineStore's cached color management */
+    resolveLineStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
+    resolveAreaStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
+    resolveBoundsStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
+    resolveColorMap: (data: Record<string, any>[]) => Map<string, string>;
+    resolveGroupColor: (group: string) => string | null;
+    /** Group data by lineBy/colorBy accessor */
+    groupData: (data: Record<string, any>[]) => {
+        key: string;
+        data: Record<string, any>[];
+    }[];
+    /** Instance-scoped mutable cache for bar category ordering (prevents cross-instance leaks) */
+    barCategoryCache?: {
+        key: string;
+        order: string[];
+    } | null;
+}
+/** Subset of PipelineConfig fields that scene builders need */
+export interface XYSceneConfig {
+    chartType: string;
+    curve?: CurveType;
+    colorScheme?: string | string[];
+    normalize?: boolean;
+    gradientFill?: boolean | {
+        topOpacity?: number;
+        bottomOpacity?: number;
+    };
+    annotations?: Record<string, any>[];
+    pointStyle?: (d: any) => Style & {
+        r?: number;
+    };
+    sizeRange?: [number, number];
+    xAccessor?: string | ((d: any) => any);
+    yAccessor?: string | ((d: any) => any);
+    valueAccessor?: string | ((d: any) => any);
+    heatmapAggregation?: "count" | "sum" | "mean";
+    heatmapXBins?: number;
+    heatmapYBins?: number;
+    showValues?: boolean;
+    heatmapValueFormat?: (v: number) => string;
+    binSize?: number;
+    barColors?: Record<string, string>;
+    swarmStyle?: {
+        radius?: number;
+        fill?: string;
+        opacity?: number;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+    waterfallStyle?: {
+        positiveColor?: string;
+        negativeColor?: string;
+        gap?: number;
+        stroke?: string;
+        strokeWidth?: number;
+        connectorStroke?: string;
+        connectorWidth?: number;
+    };
+    candlestickStyle?: {
+        upColor?: string;
+        downColor?: string;
+        wickColor?: string;
+        wickWidth?: number;
+        bodyWidth?: number;
+    };
+    boundsStyle?: Style | ((d: any, group: string) => Style);
+    lineStyle?: Style | ((d: any, group: string) => Style);
+    areaStyle?: (d: any) => Style;
+}

package/dist/components/stream/xySceneBuilders/waterfallScene.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Waterfall chart scene builder.
+ *
+ * Builds cumulative delta bars from time-series data. Each bar's base starts
+ * where the previous bar ended. Positive/negative deltas get distinct colors.
+ *
+ * Dependencies: SceneGraph (buildRectNode)
+ * Consumed by: PipelineStore.buildSceneNodes (chartType "waterfall")
+ */
+import type { SceneNode, StreamLayout } from "../types";
+import type { XYSceneContext } from "./types";
+export declare function buildWaterfallScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];