semiotic 3.0.0-beta.3 → 3.0.0-beta.4

package/dist/store/createStore.d.ts

@@ -1 +1,4 @@
-export declare function createStore(fn: any): ((selector: any) => any)[];
+import * as React from "react";
+export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<{
+    children: React.ReactNode;
+}>, <R>(selector: (state: T) => R) => R];

package/dist/store/useObservation.d.ts

@@ -0,0 +1,18 @@
+import type { ChartObservation } from "./ObservationStore";
+export interface UseChartObserverOptions {
+    /** Max observations to return (default 50) */
+    limit?: number;
+    /** Filter by observation type(s) */
+    types?: ChartObservation["type"][];
+    /** Filter by chart instance id */
+    chartId?: string;
+}
+export interface UseChartObserverResult {
+    /** Recent observations (newest last), filtered by options */
+    observations: ChartObservation[];
+    /** Latest observation matching the filter, or null */
+    latest: ChartObservation | null;
+    /** Clear all observations in the store */
+    clear: () => void;
+}
+export declare function useChartObserver(options?: UseChartObserverOptions): UseChartObserverResult;

package/dist/stream/MarginalGraphics.d.ts

@@ -16,4 +16,4 @@ export interface MarginalGraphicsProps {
 }
 /** Resolve a string shorthand or full config into a MarginalConfig */
 export declare function normalizeMarginalConfig(input: MarginalConfig | MarginalType): MarginalConfig;
-export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): React.JSX.Element;
+export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): React.JSX.Element | null;

package/dist/stream/NetworkPipelineStore.d.ts

@@ -24,6 +24,21 @@ export declare class NetworkPipelineStore {
         startTime: number;
         duration: number;
     } | null;
+    lastIngestTime: number;
+    private nodeTimestamps;
+    private edgeTimestamps;
+    /** Node IDs added in the most recent layout */
+    addedNodes: Set<string>;
+    /** Node IDs removed in the most recent layout */
+    removedNodes: Set<string>;
+    /** Edge keys added in the most recent layout */
+    addedEdges: Set<string>;
+    /** Edge keys removed in the most recent layout */
+    removedEdges: Set<string>;
+    /** Timestamp of last topology change */
+    lastTopologyChangeTime: number;
+    private previousNodeIds;
+    private previousEdgeKeys;
     constructor(config: NetworkPipelineConfig);
     updateConfig(config: NetworkPipelineConfig): void;
     /**
@@ -66,6 +81,35 @@ export declare class NetworkPipelineStore {
     private buildStandardBezier;
     private buildCircularBezier;
     rebuildAllBeziers(): void;
+    /**
+     * Apply pulse glow to scene nodes/edges based on their creation timestamps.
+     */
+    applyPulse(now: number): void;
+    /**
+     * Apply decay opacity to scene nodes based on topology age order.
+     * Older nodes (created earlier) are more faded.
+     */
+    applyDecay(): void;
+    /**
+     * Apply topology diff highlight — newly added nodes glow briefly.
+     * Duration: 2 seconds from lastTopologyChangeTime.
+     */
+    applyTopologyDiff(now: number): void;
+    /** Whether there is an active topology diff animation */
+    get hasActiveTopologyDiff(): boolean;
+    /**
+     * Apply threshold alerting to scene nodes.
+     * Overrides fill color and adds pulse for nodes exceeding thresholds.
+     */
+    applyThresholds(now: number): void;
+    /**
+     * Whether there are active threshold alerts on any node.
+     */
+    get hasActiveThresholds(): boolean;
+    /**
+     * Whether there are active pulse animations (recent ingests within pulse duration).
+     */
+    get hasActivePulses(): boolean;
     getLayoutData(): {
         nodes: RealtimeNode[];
         edges: RealtimeEdge[];

package/dist/stream/OrdinalCanvasHitTester.d.ts

@@ -5,5 +5,6 @@ export interface OrdinalHitResult {
     y: number;
     distance: number;
     category?: string;
+    stats?: import("./ordinalTypes").DistributionStats;
 }
 export declare function findNearestOrdinalNode(scene: OrdinalSceneNode[], px: number, py: number, maxDistance?: number): OrdinalHitResult | null;

package/dist/stream/OrdinalSVGOverlay.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
-import type { OrdinalScales, AnnotationContext } from "./ordinalTypes";
+import type { OrdinalScales } from "./ordinalTypes";
+import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup } from "../types/legendTypes";
 interface OrdinalSVGOverlayProps {
@@ -28,7 +29,10 @@ interface OrdinalSVGOverlayProps {
     annotations?: Record<string, any>[];
     svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
+    xAccessor?: string;
+    yAccessor?: string;
+    annotationData?: Record<string, any>[];
     children?: ReactNode;
 }
-export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): React.JSX.Element;
+export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): React.JSX.Element | null;
 export {};

package/dist/stream/ParticlePool.d.ts

@@ -17,8 +17,9 @@ export declare class ParticlePool {
     /**
      * Advance all active particles by deltaTime.
      * Recycles particles that have completed their journey (t >= 1).
+     * @param edgeSpeedMultipliers - optional per-edge speed scaling (for proportional flow rate)
      */
-    step(deltaTime: number, speed: number, edges: RealtimeEdge[]): void;
+    step(deltaTime: number, speed: number, edges: RealtimeEdge[], edgeSpeedMultipliers?: number[]): void;
     /** Count active particles for a specific edge index */
     countForEdge(edgeIndex: number): number;
     /** Deactivate all particles */

package/dist/stream/PipelineStore.d.ts

@@ -40,6 +40,15 @@ export interface PipelineConfig {
         stroke?: string;
         strokeWidth?: number;
     };
+    waterfallStyle?: {
+        positiveColor?: string;
+        negativeColor?: string;
+        connectorStroke?: string;
+        connectorWidth?: number;
+        gap?: number;
+        stroke?: string;
+        strokeWidth?: number;
+    };
     colorScheme?: string | string[];
     barColors?: Record<string, string>;
     annotations?: Record<string, any>[];
@@ -50,6 +59,7 @@ export interface PipelineConfig {
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
     heatmapYBins?: number;
+    pointIdAccessor?: string | ((d: any) => string);
 }
 export declare class PipelineStore {
     private buffer;
@@ -68,6 +78,7 @@ export declare class PipelineStore {
     private getHigh;
     private getLow;
     private getClose;
+    private getPointId;
     private timestampBuffer;
     activeTransition: {
         startTime: number;

package/dist/stream/SVGOverlay.d.ts

@@ -1,7 +1,16 @@
 import * as React from "react";
-import type { StreamScales, AnnotationContext, MarginalGraphicsConfig } from "./types";
+import type { StreamScales, MarginalGraphicsConfig } from "./types";
+import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup } from "../types/legendTypes";
+export interface AxisConfig {
+    orient: "left" | "right" | "top" | "bottom";
+    label?: string;
+    ticks?: number;
+    tickFormat?: (d: any) => string;
+    baseline?: boolean | "under";
+    jaggedBase?: boolean;
+}
 interface SVGOverlayProps {
     width: number;
     height: number;
@@ -15,6 +24,7 @@ interface SVGOverlayProps {
     };
     scales: StreamScales | null;
     showAxes?: boolean;
+    axes?: AxisConfig[];
     xLabel?: string;
     yLabel?: string;
     xFormat?: (d: any) => string;
@@ -31,7 +41,16 @@ interface SVGOverlayProps {
     annotations?: Record<string, any>[];
     svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
+    xAccessor?: string;
+    yAccessor?: string;
+    annotationData?: Record<string, any>[];
+    pointNodes?: {
+        pointId?: string;
+        x: number;
+        y: number;
+        r: number;
+    }[];
     children?: ReactNode;
 }
-export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element;
+export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element | null;
 export {};

package/dist/stream/SceneGraph.d.ts

@@ -5,7 +5,7 @@ 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[];
-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): PointSceneNode | null;
+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 interface SceneGraphData {

package/dist/stream/networkTypes.d.ts

@@ -1,7 +1,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 } from "./types";
+import type { Style, DecayConfig, PulseConfig, StalenessConfig } from "./types";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -81,6 +82,8 @@ export interface ParticleStyle {
     speedMultiplier?: number;
     maxPerEdge?: number;
     spawnRate?: number;
+    /** Scale particle speed proportional to edge value (higher value = faster). Default: false */
+    proportionalSpeed?: boolean;
 }
 export declare const DEFAULT_PARTICLE_STYLE: Required<Pick<ParticleStyle, "radius" | "opacity" | "speedMultiplier" | "maxPerEdge" | "spawnRate">>;
 export interface EdgePush {
@@ -133,6 +136,9 @@ export interface NetworkCircleNode {
     id?: string;
     label?: string;
     depth?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
 }
 /** Rect node — used by sankey, treemap, partition */
 export interface NetworkRectNode {
@@ -146,6 +152,9 @@ export interface NetworkRectNode {
     id?: string;
     label?: string;
     depth?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
 }
 /** Arc node — used by chord */
 export interface NetworkArcNode {
@@ -170,6 +179,8 @@ export interface NetworkLineEdge {
     y2: number;
     style: Style;
     datum: any;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
 }
 /** Bezier band edge — used by sankey */
 export interface NetworkBezierEdge {
@@ -178,6 +189,8 @@ export interface NetworkBezierEdge {
     bezierCache?: BezierCache;
     style: Style;
     datum: any;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
 }
 /** Ribbon edge — used by chord */
 export interface NetworkRibbonEdge {
@@ -228,6 +241,20 @@ export interface NetworkLayoutPlugin {
     /** Whether this layout uses hierarchical (tree) input instead of nodes+edges */
     hierarchical: boolean;
 }
+/** Threshold alerting configuration for streaming network nodes */
+export interface ThresholdAlertConfig {
+    /** Function that extracts the metric value from a node for threshold comparison */
+    metric: (node: RealtimeNode) => number;
+    /** Warning threshold — node enters "warning" state when metric >= this value */
+    warning?: number;
+    /** Critical threshold — node enters "critical" state when metric >= this value */
+    critical?: number;
+    /** Colors for threshold states */
+    warningColor?: string;
+    criticalColor?: string;
+    /** Whether to pulse nodes that cross a threshold. Default: true */
+    pulse?: boolean;
+}
 export interface NetworkPipelineConfig {
     chartType: NetworkChartType;
     nodeIDAccessor?: string | ((d: any) => string);
@@ -264,6 +291,10 @@ export interface NetworkPipelineConfig {
     colorByDepth?: boolean;
     nodeSize?: number | string | ((d: any) => number);
     nodeSizeRange?: [number, number];
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    staleness?: StalenessConfig;
+    thresholds?: ThresholdAlertConfig;
 }
 export interface StreamNetworkFrameProps<T = Record<string, any>> {
     chartType: NetworkChartType;
@@ -322,6 +353,22 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
         x: number;
         y: number;
     }) => ReactNode;
+    customHoverBehavior?: (d: {
+        type: "node" | "edge";
+        data: any;
+        x: number;
+        y: number;
+    } | null) => void;
+    customClickBehavior?: (d: {
+        type: "node" | "edge";
+        data: any;
+        x: number;
+        y: number;
+    } | null) => void;
+    /** Observation callback — emits hover/click events to the ObservationStore and this callback */
+    onObservation?: OnObservationCallback;
+    /** Chart instance identifier for observation filtering */
+    chartId?: string;
     onTopologyChange?: (nodes: RealtimeNode[], edges: RealtimeEdge[]) => void;
     annotations?: Record<string, any>[];
     svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
@@ -331,6 +378,10 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     title?: string | ReactNode;
     foregroundGraphics?: ReactNode;
     backgroundGraphics?: ReactNode;
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    staleness?: StalenessConfig;
+    thresholds?: ThresholdAlertConfig;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;
@@ -340,6 +391,12 @@ export interface StreamNetworkFrameHandle {
         nodes: RealtimeNode[];
         edges: RealtimeEdge[];
     };
+    getTopologyDiff(): {
+        addedNodes: string[];
+        removedNodes: string[];
+        addedEdges: string[];
+        removedEdges: string[];
+    };
     relayout(): void;
     getTension(): number;
 }

package/dist/stream/ordinalTypes.d.ts

@@ -52,6 +52,15 @@ export interface BoxplotSceneNode {
         datum: any;
     }[];
 }
+export interface DistributionStats {
+    n: number;
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    mean: number;
+}
 export interface ViolinSceneNode {
     type: "violin";
     /** Pre-computed SVG path string for Path2D */
@@ -71,7 +80,11 @@ export interface ViolinSceneNode {
         q1Pos: number;
         medianPos: number;
         q3Pos: number;
+        centerPos: number;
+        isVertical: boolean;
     };
+    /** Pre-computed distribution statistics for tooltips */
+    stats?: DistributionStats;
     style: Style;
     datum: any;
     category?: string;

package/dist/stream/types.d.ts

@@ -102,10 +102,14 @@ export interface PointSceneNode {
     r: number;
     style: Style;
     datum: any;
+    /** Optional unique identifier for point-anchored annotations */
+    pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active) */
     _pulseIntensity?: number;
     /** Pulse glow color */
     _pulseColor?: string;
+    /** Pulse glow radius in px (default: 4) */
+    _pulseGlowRadius?: number;
     /** Animation target fields (set during transitions) */
     _targetX?: number;
     _targetY?: number;
@@ -243,6 +247,14 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     barColors?: Record<string, string>;
     colorScheme?: string | string[];
     showAxes?: boolean;
+    axes?: Array<{
+        orient: "left" | "right" | "top" | "bottom";
+        label?: string;
+        ticks?: number;
+        tickFormat?: (d: any) => string;
+        baseline?: boolean | "under";
+        jaggedBase?: boolean;
+    }>;
     xLabel?: string;
     yLabel?: string;
     xFormat?: (d: any) => string;
@@ -263,6 +275,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
         x: [number, number];
         y: [number, number];
     } | 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;
     showGrid?: boolean;

package/dist/types/annotationTypes.d.ts

@@ -71,10 +71,20 @@ export interface AnnotationProps {
         note: {
             label?: string;
             title?: string;
+            wrap?: number;
+            orientation?: string;
+            align?: string;
+            noWrap?: boolean;
         };
         i?: number;
         fixedPosition?: boolean;
         label?: string;
+        connector?: any;
+        subject?: any;
+        color?: string;
+        className?: string;
+        disable?: string[];
+        [key: string]: any;
     };
 }
 type GlyphProps = {

package/dist/types/networkTypes.d.ts

@@ -1,6 +1,5 @@
 import { RenderPipelineType, DataAccessor } from "./generalTypes";
 import { GeneralFrameProps, GeneralFrameState } from "./generalTypes";
-import { NetworkLayoutMap } from "../processing/layouts/types";
 export interface NodeType {
     degree: number;
     inDegree: number;
@@ -171,5 +170,5 @@ export interface NetworkFrameProps<TNode = Record<string, any>, TEdge = Record<s
     renderOrder?: ReadonlyArray<"edges" | "nodes">;
     filterRenderedNodes?: (value?: NodeType, index?: number, array?: NodeType[]) => any;
     /** @internal Layout map for tree-shaking optimization. Do not use directly. */
-    _layoutMap?: NetworkLayoutMap;
+    _layoutMap?: Record<string, any>;
 }