semiotic 3.0.1 → 3.1.0

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

@@ -1,5 +1,7 @@
+import { type Quadtree } from "d3-quadtree";
 import { RingBuffer } from "../realtime/RingBuffer";
-import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig } from "./types";
+import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType } from "./types";
+import type { ActiveTransition } from "./pipelineTransitionUtils";
 export interface PipelineConfig {
     chartType: StreamChartType;
     runtimeMode?: "streaming" | "bounded";
@@ -7,6 +9,7 @@ export interface PipelineConfig {
     windowMode: WindowMode;
     arrowOfTime: ArrowOfTime;
     extentPadding: number;
+    maxCapacity?: number;
     xAccessor?: string | ((d: any) => number);
     yAccessor?: string | ((d: any) => number);
     timeAccessor?: string | ((d: any) => number);
@@ -16,6 +19,8 @@ export interface PipelineConfig {
     groupAccessor?: string | ((d: any) => string);
     categoryAccessor?: string | ((d: any) => string);
     lineDataAccessor?: string;
+    xScaleType?: "linear" | "log";
+    yScaleType?: "linear" | "log";
     xExtent?: [number | undefined, number | undefined] | [number];
     yExtent?: [number | undefined, number | undefined] | [number];
     sizeRange?: [number, number];
@@ -64,7 +69,10 @@ export interface PipelineConfig {
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
     heatmapYBins?: number;
+    showValues?: boolean;
+    heatmapValueFormat?: (v: number) => string;
     pointIdAccessor?: string | ((d: any) => string);
+    curve?: CurveType;
 }
 export declare class PipelineStore {
     private buffer;
@@ -86,17 +94,33 @@ export declare class PipelineStore {
     private getClose;
     private getPointId;
     private timestampBuffer;
-    activeTransition: {
-        startTime: number;
-        duration: number;
-    } | null;
+    activeTransition: ActiveTransition | null;
     private prevPositionMap;
+    /** Previous line/area path arrays for path interpolation */
+    private prevPathMap;
+    /** Exit nodes awaiting fade-out removal */
+    exitNodes: SceneNode[];
     lastIngestTime: number;
+    /** Unified color map cache keyed by sorted category set — shared across point, swarm, etc. */
+    private _colorMapCache;
+    /** Separate group→color map for resolveGroupColor (insertion-order based, never invalidates _colorMapCache) */
+    private _groupColorMap;
+    private _barCategoryCache;
+    /** Cache stacked area cumulative sums to skip recalculation when buffer hasn't changed */
+    private _stackExtentCache;
+    /** Monotonic counter incremented on each ingest — used as part of cache keys */
+    private _ingestVersion;
+    /** Cached materialized array from buffer.toArray() — only rebuilt when buffer changes */
+    private _bufferArrayCache;
+    /** True when the buffer has been mutated since last toArray() call */
+    private _bufferDirty;
     private needsFullRebuild;
     private lastLayout;
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
+    private _quadtree;
+    private static readonly QUADTREE_THRESHOLD;
     constructor(config: PipelineConfig);
     /**
      * Process a changeset from DataSourceAdapter.
@@ -107,6 +131,16 @@ export declare class PipelineStore {
      * Recompute scales and scene graph for the current buffer contents.
      */
     computeScene(layout: StreamLayout): void;
+    /**
+     * Build or clear the quadtree spatial index for point scene nodes.
+     * Only built for scatter/bubble charts with >QUADTREE_THRESHOLD points.
+     */
+    private rebuildQuadtree;
+    /**
+     * Get the quadtree spatial index, if available.
+     * Returns null when chart type is not scatter/bubble or point count is below threshold.
+     */
+    get quadtree(): Quadtree<PointSceneNode> | null;
     /**
      * Remap existing scene node coordinates for a new layout size.
      * Proportionally scales all pixel coordinates without rebuilding from data.
@@ -161,6 +195,7 @@ export declare class PipelineStore {
     private getNodeIdentity;
     /**
      * 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).
      */
     private startTransition;
     /**
@@ -168,8 +203,25 @@ export declare class PipelineStore {
      */
     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.
+     */
+    private resolveColorMap;
     private resolveLineStyle;
     private resolveAreaStyle;
+    /** Resolve a group name to a color from the cached color map or a dedicated group palette.
+     *  First checks _colorMapCache (populated by resolveColorMap when colorAccessor is set).
+     *  Falls back to _groupColorMap (insertion-order, never mutates _colorMapCache). */
+    private resolveGroupColor;
+    /**
+     * Return a cached materialized array of the buffer contents.
+     * Only calls buffer.toArray() when the buffer has actually changed
+     * (new push, resize, or clear), avoiding per-frame allocation on
+     * transition ticks, hover redraws, and other non-data-changing renders.
+     */
+    private getBufferArray;
     getData(): Record<string, any>[];
     getExtents(): {
         x: [number, number];

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

@@ -2,7 +2,7 @@ import * as React from "react";
 import type { StreamScales, MarginalGraphicsConfig } from "./types";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
 export interface AxisConfig {
     orient: "left" | "right" | "top" | "bottom";
     label?: string;
@@ -36,6 +36,8 @@ interface SVGOverlayProps {
     title?: string | ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
     };
     /** Callback when hovering a legend item */
     legendHoverBehavior?: (item: {
@@ -49,6 +51,8 @@ interface SVGOverlayProps {
     legendHighlightedCategory?: string | null;
     /** Set of isolated category labels (for click isolation) */
     legendIsolatedCategories?: Set<string>;
+    /** Legend position relative to chart area */
+    legendPosition?: "right" | "left" | "top" | "bottom";
     foregroundGraphics?: ReactNode;
     marginalGraphics?: MarginalGraphicsConfig;
     xValues?: number[];
@@ -65,7 +69,30 @@ interface SVGOverlayProps {
         y: number;
         r: number;
     }[];
+    /** Curve interpolation type for envelope annotations */
+    curve?: string;
+    /** When true, grid lines and axis baselines are skipped (rendered by SVGUnderlay instead) */
+    underlayRendered?: boolean;
     children?: ReactNode;
 }
+interface SVGUnderlayProps {
+    width: number;
+    height: number;
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: StreamScales | null;
+    showAxes?: boolean;
+    axes?: AxisConfig[];
+    showGrid?: boolean;
+    xFormat?: (d: any) => string;
+    yFormat?: (d: any) => string;
+}
+export declare function SVGUnderlay(props: SVGUnderlayProps): React.JSX.Element | null;
 export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element | null;
 export {};

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

@@ -1,13 +1,17 @@
-import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales } from "./types";
+import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
 export declare function buildLineNode(data: Record<string, any>[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, style: Style, group?: string): LineSceneNode;
 export declare function buildAreaNode(data: Record<string, any>[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Record<string, any>) => number): AreaSceneNode;
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Record<string, any>[];
-}[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, styleFn: (group: string, sampleDatum?: Record<string, any>) => Style, normalize?: boolean): AreaSceneNode[];
+}[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, styleFn: (group: string, sampleDatum?: Record<string, any>) => Style, normalize?: boolean, curve?: CurveType): AreaSceneNode[];
 export declare function buildPointNode(datum: Record<string, any>, scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, r: number, style: Style, pointId?: string): PointSceneNode | null;
 export declare function buildRectNode(x: number, y: number, w: number, h: number, style: Style, datum: any, group?: string): RectSceneNode;
-export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: any): HeatcellSceneNode;
+export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: any, options?: {
+    value?: number;
+    showValues?: boolean;
+    valueFormat?: (v: number) => string;
+}): HeatcellSceneNode;
 export interface SceneGraphData {
     nodes: SceneNode[];
     version: number;

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

@@ -8,11 +8,13 @@ import * as React from "react";
 import type { SceneNode } from "./types";
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel } from "./networkTypes";
 import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { GeoSceneNode } from "./geoTypes";
 export declare function xySceneNodeToSVG(node: SceneNode, i: number): React.ReactNode;
 export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
 export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
 export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;
 export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number): React.ReactNode;
+export declare function geoSceneNodeToSVG(node: GeoSceneNode, i: number): React.ReactNode;
 /**
  * Returns true when running in a true server/Node.js context where
  * window and document are not available.

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

@@ -0,0 +1,4 @@
+import * as React from "react";
+import type { StreamGeoFrameProps, StreamGeoFrameHandle } from "./geoTypes";
+declare const StreamGeoFrame: React.ForwardRefExoticComponent<StreamGeoFrameProps<Record<string, any>> & React.RefAttributes<StreamGeoFrameHandle>>;
+export default StreamGeoFrame;

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

@@ -1,2 +1,3 @@
 export declare function resolveAccessor<T>(accessor: string | ((d: T) => number) | undefined, fallback: string): (d: T) => number;
+export declare function resolveRawAccessor<T>(accessor: string | ((d: T) => any) | undefined, fallback: string): (d: T) => any;
 export declare function resolveStringAccessor<T>(accessor: string | ((d: T) => string) | undefined, fallback?: string): ((d: T) => string) | undefined;

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

@@ -0,0 +1,26 @@
+/**
+ * Shared canvas setup utilities used by all Stream Frames.
+ *
+ * Eliminates duplicated DPR / sizing / transform logic across
+ * StreamXYFrame, StreamGeoFrame, StreamNetworkFrame, and StreamOrdinalFrame.
+ */
+export interface CanvasMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Set a canvas element's physical (pixel) and CSS (logical) dimensions,
+ * accounting for devicePixelRatio. Returns the 2D context ready for drawing
+ * with the DPR transform and margin translation already applied.
+ *
+ * After this call the context's coordinate space is:
+ *   (0, 0) = top-left of the chart area (inside margins)
+ *   (-margin.left, -margin.top) = top-left of the full canvas
+ */
+export declare function prepareCanvas(canvas: HTMLCanvasElement, size: [number, number], margin: CanvasMargin, dpr: number): CanvasRenderingContext2D | null;
+/**
+ * Get the current devicePixelRatio, defaulting to 1 in non-browser environments.
+ */
+export declare function getDevicePixelRatio(): number;

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

@@ -0,0 +1,186 @@
+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 { HoverAnnotationConfig } from "../realtime/types";
+import type { GeoParticleStyle } from "./GeoParticlePool";
+export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
+export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
+export interface ProjectionConfig {
+    type: ProjectionName;
+    rotate?: [number, number] | [number, number, number];
+    center?: [number, number];
+    parallels?: [number, number];
+}
+export interface GraticuleConfig {
+    step?: [number, number];
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    showLabels?: boolean;
+}
+export interface DistanceCartogramConfig {
+    center: string;
+    centerAccessor?: string | ((d: any) => string);
+    costAccessor: string | ((d: any) => number);
+    strength?: number;
+    lineMode?: "straight" | "fractional";
+}
+export interface GeoAreaSceneNode {
+    type: "geoarea";
+    /** Pre-computed SVG path string from d3.geoPath(projection)(feature) */
+    pathData: string;
+    /** Centroid in screen coords (for tooltip/annotation positioning) */
+    centroid: [number, number];
+    /** Bounding box in screen coords [[x0,y0],[x1,y1]] */
+    bounds: [[number, number], [number, number]];
+    /** Screen-space area in px² */
+    screenArea: number;
+    style: Style;
+    datum: any;
+    group?: string;
+    interactive?: boolean;
+    /** Lazily-cached Path2D parsed from pathData (avoids re-parsing on every hit test) */
+    _cachedPath2D?: Path2D;
+    _decayOpacity?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+}
+/** Union of all scene node types that GeoFrame produces */
+export type GeoSceneNode = GeoAreaSceneNode | PointSceneNode | LineSceneNode;
+export interface GeoScales {
+    projection: GeoProjection;
+    geoPath: GeoPath<any, GeoPermissibleObjects>;
+    projectedPoint: (lon: number, lat: number) => [number, number] | null;
+    invertedPoint: (px: number, py: number) => [number, number] | null;
+}
+export interface GeoPipelineConfig {
+    projection: ProjectionProp;
+    projectionExtent?: [[number, number], [number, number]];
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    xAccessor?: string | ((d: any) => number);
+    yAccessor?: string | ((d: any) => number);
+    lineDataAccessor?: string | ((d: any) => any[]);
+    lineType?: "geo" | "line";
+    /** Flow rendering style: "basic" (straight/great-circle), "offset" (bidirectional offset), "arc" (curved arcs) @default "basic" */
+    flowStyle?: "basic" | "offset" | "arc";
+    areaStyle?: Style | ((d: any) => Style);
+    pointStyle?: (d: any) => Style & {
+        r?: number;
+    };
+    lineStyle?: Style | ((d: any, group?: string) => Style);
+    colorScheme?: string | string[];
+    graticule?: boolean | GraticuleConfig;
+    projectionTransform?: DistanceCartogramConfig;
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    annotations?: Record<string, any>[];
+    pointIdAccessor?: string | ((d: any) => string);
+}
+export interface StreamGeoFrameProps<T = Record<string, any>> {
+    projection: ProjectionProp;
+    projectionExtent?: [[number, number], [number, number]];
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    areas?: GeoJSON.Feature[];
+    points?: T[];
+    lines?: T[];
+    xAccessor?: string | ((d: T) => number);
+    yAccessor?: string | ((d: T) => number);
+    lineDataAccessor?: string | ((d: T) => any[]);
+    pointIdAccessor?: string | ((d: T) => string);
+    lineType?: "geo" | "line";
+    /** Flow rendering style: "basic" (straight/great-circle), "offset" (bidirectional offset), "arc" (curved arcs) @default "basic" */
+    flowStyle?: "basic" | "offset" | "arc";
+    graticule?: boolean | GraticuleConfig;
+    zoomable?: boolean;
+    zoomExtent?: [number, number];
+    onZoom?: (state: {
+        projection: GeoProjection;
+        zoom: number;
+    }) => void;
+    /**
+     * When true, drag gestures rotate the projection (globe spinning)
+     * instead of panning. Defaults to true for orthographic projection.
+     * Scroll-wheel zoom still works normally.
+     */
+    dragRotate?: boolean;
+    projectionTransform?: DistanceCartogramConfig;
+    /** Show animated particles flowing along line paths */
+    showParticles?: boolean;
+    /** Particle appearance and behavior config */
+    particleStyle?: GeoParticleStyle;
+    /** Raster tile URL template or function. Enables tile basemap (Mercator only). */
+    tileURL?: string | ((z: number, x: number, y: number, dpr: number) => string);
+    /** Attribution text for tile provider (e.g., "© OpenStreetMap contributors") */
+    tileAttribution?: string;
+    /** Max cached tiles @default 256 */
+    tileCacheSize?: number;
+    size?: [number, number];
+    width?: number;
+    height?: number;
+    responsiveWidth?: boolean;
+    responsiveHeight?: boolean;
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    className?: string;
+    background?: string;
+    runtimeMode?: "bounded" | "streaming";
+    areaStyle?: Style | ((d: any) => Style);
+    pointStyle?: (d: any) => Style & {
+        r?: number;
+    };
+    lineStyle?: Style | ((d: any, group?: string) => Style);
+    colorScheme?: string | string[];
+    enableHover?: boolean;
+    hoverAnnotation?: boolean | HoverAnnotationConfig;
+    tooltipContent?: (d: any) => ReactNode;
+    customClickBehavior?: (d: any) => void;
+    customHoverBehavior?: (d: any) => void;
+    annotations?: Record<string, any>[];
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    staleness?: StalenessConfig;
+    backgroundGraphics?: ReactNode;
+    foregroundGraphics?: ReactNode;
+    title?: string | ReactNode;
+    legend?: any;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    legendHoverBehavior?: (item: {
+        label: string;
+    } | null) => void;
+    legendClickBehavior?: (item: {
+        label: string;
+    }) => void;
+    legendHighlightedCategory?: string | null;
+    legendIsolatedCategories?: Set<string>;
+    showAxes?: boolean;
+    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    accessibleTable?: boolean;
+}
+export interface StreamGeoFrameHandle {
+    push(datum: Record<string, any>): void;
+    pushMany(data: Record<string, any>[]): void;
+    clear(): void;
+    getProjection(): GeoProjection | null;
+    getGeoPath(): GeoPath<any, GeoPermissibleObjects> | null;
+    /** Get cartogram layout info (center position, max cost, radius) */
+    getCartogramLayout(): {
+        cx: number;
+        cy: number;
+        maxCost: number;
+        availableRadius: number;
+    } | null;
+    /** Get current zoom level (1 = default) */
+    getZoom(): number;
+    /** Animate back to initial view */
+    resetZoom(): void;
+    /** Get current data points */
+    getData(): Record<string, any>[];
+}

package/dist/components/stream/layouts/forceLayoutPlugin.d.ts

@@ -1,9 +1,2 @@
 import type { NetworkLayoutPlugin } from "../networkTypes";
-/**
- * Force-directed layout plugin — uses d3-force for physics-based node positioning.
- *
- * Produces circle scene nodes and line scene edges. Runs the force simulation
- * synchronously for a configurable number of iterations, using phyllotaxis
- * spiral for deterministic initial positions.
- */
 export declare const forceLayoutPlugin: NetworkLayoutPlugin;

package/dist/components/stream/layouts/index.d.ts

@@ -3,9 +3,10 @@ import { sankeyLayoutPlugin } from "./sankeyLayoutPlugin";
 import { forceLayoutPlugin } from "./forceLayoutPlugin";
 import { chordLayoutPlugin } from "./chordLayoutPlugin";
 import { hierarchyLayoutPlugin } from "./hierarchyLayoutPlugin";
+import { orbitLayoutPlugin } from "./orbitLayoutPlugin";
 /**
  * Registry mapping network chart types to their layout plugins.
  */
 export declare const networkLayoutRegistry: Record<string, NetworkLayoutPlugin>;
 export declare function getLayoutPlugin(chartType: NetworkChartType): NetworkLayoutPlugin | undefined;
-export { sankeyLayoutPlugin, forceLayoutPlugin, chordLayoutPlugin, hierarchyLayoutPlugin };
+export { sankeyLayoutPlugin, forceLayoutPlugin, chordLayoutPlugin, hierarchyLayoutPlugin, orbitLayoutPlugin };

package/dist/components/stream/layouts/orbitLayoutPlugin.d.ts

@@ -0,0 +1,2 @@
+import type { NetworkLayoutPlugin } from "../networkTypes";
+export declare const orbitLayoutPlugin: NetworkLayoutPlugin;

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

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+export interface LegendRenderConfig {
+    legend: ReactNode | {
+        legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
+    };
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    title?: string | ReactNode;
+    legendHoverBehavior?: (item: {
+        label: string;
+    } | null) => void;
+    legendClickBehavior?: (item: {
+        label: string;
+    }) => void;
+    legendHighlightedCategory?: string | null;
+    legendIsolatedCategories?: Set<string>;
+    legendInteraction?: string;
+}
+/**
+ * Renders a legend (categorical, gradient, or custom ReactNode) inside an SVG overlay.
+ * Computes position based on `legendPosition` and chart dimensions.
+ */
+export declare function renderLegendFromConfig(config: LegendRenderConfig): ReactNode;

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

@@ -124,7 +124,7 @@ export interface RealtimeNetworkFrameProps {
     background?: string;
     className?: string;
 }
-export type NetworkChartType = "force" | "sankey" | "chord" | "tree" | "cluster" | "treemap" | "circlepack" | "partition";
+export type NetworkChartType = "force" | "sankey" | "chord" | "tree" | "cluster" | "treemap" | "circlepack" | "orbit" | "partition";
 /** Circle node — used by force, tree, cluster, circlepack */
 export interface NetworkCircleNode {
     type: "circle";
@@ -240,6 +240,17 @@ export interface NetworkLayoutPlugin {
     supportsStreaming: boolean;
     /** Whether this layout uses hierarchical (tree) input instead of nodes+edges */
     hierarchical: boolean;
+    /**
+     * Whether this layout drives continuous animation (e.g. orbiting nodes).
+     * When true, StreamNetworkFrame keeps its RAF loop alive and calls `tick()` each frame.
+     */
+    supportsAnimation?: boolean;
+    /**
+     * Advance one animation frame. Called by StreamNetworkFrame on each RAF tick
+     * when `supportsAnimation` is true. Should mutate node positions in-place.
+     * Returns true if the scene needs a rebuild (always true for orbit animation).
+     */
+    tick?: (nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], deltaTime: number) => boolean;
 }
 /** Threshold alerting configuration for streaming network nodes */
 export interface ThresholdAlertConfig {
@@ -284,6 +295,7 @@ export interface NetworkPipelineConfig {
     edgeStyle?: (d: any) => Record<string, any>;
     nodeLabel?: string | ((d: any) => string);
     showLabels?: boolean;
+    labelMode?: "leaf" | "parent" | "all";
     colorBy?: string | ((d: any) => string | number);
     colorScheme?: string | string[];
     edgeColorBy?: "source" | "target" | "gradient" | ((d: any) => string);
@@ -295,6 +307,30 @@ export interface NetworkPipelineConfig {
     pulse?: PulseConfig;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
+    /** Ring arrangement mode: "flat" (all children in one ring), "solar" (one per ring),
+     *  "atomic" ([2,8] electron shell), or custom capacities. @default "flat" */
+    orbitMode?: "flat" | "solar" | "atomic" | number[];
+    /** Ring size divisor per depth. Larger = tighter orbits. @default 2.95 */
+    orbitSize?: number | ((node: any) => number);
+    /** Orbit speed multiplier (higher = faster rotation). @default 0.25 */
+    orbitSpeed?: number;
+    /** Per-node speed modifier. @default (node) => 1 / (node.depth + 1) */
+    orbitRevolution?: (node: any) => number;
+    /**
+     * Built-in revolution style presets:
+     * - "locked": children rotate with parent at decreasing speed (default)
+     * - "decay": each depth level progressively slower, independent of parent
+     * - "alternate": odd-depth rings reverse direction
+     * Ignored when `orbitRevolution` is provided.
+     * @default "locked"
+     */
+    orbitRevolutionStyle?: "locked" | "decay" | "alternate";
+    /** Vertical squash for elliptical orbits. 1 = circle. @default 1 */
+    orbitEccentricity?: number | ((node: any) => number);
+    /** Show orbital ring ellipses as foreground graphics. @default true */
+    orbitShowRings?: boolean;
+    /** Enable orbit animation. @default true */
+    orbitAnimated?: boolean;
 }
 export interface StreamNetworkFrameProps<T = Record<string, any>> {
     chartType: NetworkChartType;
@@ -337,6 +373,7 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     nodeSizeRange?: [number, number];
     nodeLabel?: string | ((d: any) => string);
     showLabels?: boolean;
+    labelMode?: "leaf" | "parent" | "all";
     size?: [number, number];
     responsiveWidth?: boolean;
     responsiveHeight?: boolean;
@@ -377,6 +414,7 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
     };
+    legendPosition?: "right" | "left" | "top" | "bottom";
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;
@@ -392,6 +430,16 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     pulse?: PulseConfig;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
+    orbitMode?: "flat" | "solar" | "atomic" | number[];
+    orbitSize?: number | ((node: any) => number);
+    orbitSpeed?: number;
+    orbitRevolution?: (node: any) => number;
+    orbitRevolutionStyle?: "locked" | "decay" | "alternate";
+    orbitEccentricity?: number | ((node: any) => number);
+    orbitShowRings?: boolean;
+    orbitAnimated?: boolean;
+    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    accessibleTable?: boolean;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;

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

@@ -24,6 +24,8 @@ export interface WedgeSceneNode {
     _pulseIntensity?: number;
     /** Pulse color */
     _pulseColor?: string;
+    /** Animation target opacity (set during enter/exit transitions) */
+    _targetOpacity?: number;
 }
 export interface BoxplotSceneNode {
     type: "boxplot";
@@ -49,6 +51,7 @@ export interface BoxplotSceneNode {
         value: number;
         datum: any;
     }[];
+    _targetOpacity?: number;
 }
 export interface DistributionStats {
     n: number;
@@ -86,6 +89,7 @@ export interface ViolinSceneNode {
     style: Style;
     datum: any;
     category?: string;
+    _targetOpacity?: number;
 }
 export interface ConnectorSceneNode {
     type: "connector";
@@ -96,6 +100,7 @@ export interface ConnectorSceneNode {
     style: Style;
     datum: any;
     group?: string;
+    _targetOpacity?: number;
 }
 export type { Style, PointSceneNode, RectSceneNode } from "./types";
 import type { PointSceneNode, RectSceneNode } from "./types";
@@ -211,6 +216,8 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     showGrid?: boolean;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
+    } | {
+        gradient: import("../types/legendTypes").GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -220,6 +227,7 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     }) => void;
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
@@ -230,6 +238,8 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     pulse?: PulseConfig;
     transition?: TransitionConfig;
     staleness?: StalenessConfig;
+    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    accessibleTable?: boolean;
 }
 export interface StreamOrdinalFrameHandle<T = Record<string, any>> {
     push(datum: T): void;