semiotic 3.3.1 → 3.4.1

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

@@ -1,4 +1,4 @@
-import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
 import type { StreamScales, MarginalGraphicsConfig } from "./types";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
@@ -38,8 +38,8 @@ interface SVGOverlayProps {
     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;
     showGrid?: boolean;
     title?: string | ReactNode;
     legend?: ReactNode | {
@@ -65,12 +65,12 @@ interface SVGOverlayProps {
     marginalGraphics?: MarginalGraphicsConfig;
     xValues?: number[];
     yValues?: number[];
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;
     yAccessor?: string;
-    annotationData?: Record<string, any>[];
+    annotationData?: Datum[];
     pointNodes?: {
         pointId?: string;
         x: number;
@@ -102,9 +102,9 @@ interface SVGUnderlayProps {
     showAxes?: boolean;
     axes?: AxisConfig[];
     showGrid?: boolean;
-    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;
 }
-export declare function SVGUnderlay(props: SVGUnderlayProps): React.JSX.Element | null;
-export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element | null;
+export declare function SVGUnderlay(props: SVGUnderlayProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function SVGOverlay(props: SVGOverlayProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

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

@@ -1,16 +1,17 @@
 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;
+import type { Datum } from "../charts/shared/datumTypes";
+export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, style: Style, group?: string): LineSceneNode;
+export declare function buildAreaNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Datum) => number): AreaSceneNode;
 /** Per-group-per-x stacked top values, keyed by group then x */
 export type StackedTops = Map<string, Map<number, number>>;
 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, curve?: CurveType): {
+    data: Datum[];
+}[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, styleFn: (group: string, sampleDatum?: Datum) => Style, normalize?: boolean, curve?: CurveType): {
     nodes: AreaSceneNode[];
     stackedTops: StackedTops;
 };
-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 buildPointNode(datum: Datum, scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => 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, options?: {
     value?: number;

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

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

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

@@ -1,4 +1,5 @@
+import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamNetworkFrameProps, StreamNetworkFrameHandle } from "./networkTypes";
-declare const StreamNetworkFrame: React.ForwardRefExoticComponent<StreamNetworkFrameProps<Record<string, any>> & React.RefAttributes<StreamNetworkFrameHandle>>;
+declare const StreamNetworkFrame: React.ForwardRefExoticComponent<StreamNetworkFrameProps<Datum> & React.RefAttributes<StreamNetworkFrameHandle>>;
 export default StreamNetworkFrame;

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

@@ -1,4 +1,5 @@
+import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle } from "./ordinalTypes";
-declare const StreamOrdinalFrame: React.ForwardRefExoticComponent<StreamOrdinalFrameProps<Record<string, any>> & React.RefAttributes<StreamOrdinalFrameHandle<Record<string, any>>>>;
+declare const StreamOrdinalFrame: React.ForwardRefExoticComponent<StreamOrdinalFrameProps<Datum> & React.RefAttributes<StreamOrdinalFrameHandle<Datum>>>;
 export default StreamOrdinalFrame;

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

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

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

@@ -1,23 +1,3 @@
-/**
- * XYBrushOverlay — d3-brush SVG overlay for XY frames.
- *
- * Renders a transparent SVG positioned above the canvas. Supports x, y, and
- * xy brush dimensions, bin snapping, and streaming brush tracking (shrinks/
- * clears the brush as data scrolls past the selected range).
- *
- * Key design decisions:
- *   - d3-brush lifecycle depends on [width, height, dimension, snap, binSize, snapDuring]
- *     only — scales and binBoundaries are read from refs to avoid teardown mid-drag.
- *   - Data-driven snapping (binBoundaries) uses binary search to snap to actual bin
- *     edges. Falls back to uniform grid math (binSize) when no boundaries are provided.
- *   - Bin snapping applies on "end" events by default. Set snapDuring=true to also
- *     snap during drag (the "brush" event).
- *   - Streaming tracking guards against y-only dimension (no x-domain to track).
- *   - isProgrammaticMoveRef prevents re-entrant brush events from .move() calls.
- *
- * Consumed by: StreamXYFrame (rendered when brush prop is set).
- */
-import * as React from "react";
 import type { StreamScales } from "./types";
 export interface XYBrushOverlayProps {
     width: number;
@@ -44,4 +24,4 @@ export interface XYBrushOverlayProps {
     snapDuring?: boolean;
     streaming?: boolean;
 }
-export declare function XYBrushOverlay({ width, height, totalWidth, totalHeight, margin, dimension, scales, onBrush, binSize, snap, binBoundaries, snapDuring, streaming }: XYBrushOverlayProps): React.JSX.Element;
+export declare function XYBrushOverlay({ width, height, totalWidth, totalHeight, margin, dimension, scales, onBrush, binSize, snap, binBoundaries, snapDuring, streaming }: XYBrushOverlayProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,13 +1,4 @@
-/**
- * Dev-mode helper that warns when user callbacks access properties that exist
- * on `.data` but not on the RealtimeNode/RealtimeEdge wrapper.
- *
- * Common pitfall:
- *   nodeStyle={(d) => ({ fill: d.category })}     // undefined!
- *   nodeStyle={(d) => ({ fill: d.data?.category })} // correct
- *
- * In production, this is a no-op passthrough.
- */
+import type { Datum } from "../charts/shared/datumTypes";
 export declare function wrapWithDataHint<T extends {
-    data?: Record<string, any>;
+    data?: Datum;
 }>(datum: T, callbackName: string): T;

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

@@ -1,8 +1,10 @@
 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 { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, PointSceneNode, LineSceneNode, ThemeSemanticColors } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
+import type { Datum } from "../charts/shared/datumTypes";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -20,8 +22,8 @@ export interface GraticuleConfig {
 }
 export interface DistanceCartogramConfig {
     center: string;
-    centerAccessor?: string | ((d: any) => string);
-    costAccessor: string | ((d: any) => number);
+    centerAccessor?: string | ((d: Datum) => string);
+    costAccessor: string | ((d: Datum) => number);
     strength?: number;
     lineMode?: "straight" | "fractional";
 }
@@ -58,27 +60,35 @@ export interface GeoPipelineConfig {
     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[]);
+    xAccessor?: string | ((d: Datum) => number);
+    yAccessor?: string | ((d: Datum) => number);
+    lineDataAccessor?: string | ((d: Datum) => 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 & {
+    areaStyle?: Style | ((d: Datum) => Style);
+    pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     lineStyle?: Style | ((d: any, group?: string) => Style);
     colorScheme?: string | string[];
+    /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name — fallback for ChoroplethMap when colorScheme is not set. */
+    themeSequential?: string;
+    /** Theme diverging scheme name — available for geo consumers that need midpoint encodings. */
+    themeDiverging?: string;
     graticule?: boolean | GraticuleConfig;
     projectionTransform?: DistanceCartogramConfig;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
-    annotations?: Record<string, any>[];
-    pointIdAccessor?: string | ((d: any) => string);
+    /** Whether to animate elements on first render */
+    introAnimation?: boolean;
+    annotations?: Datum[];
+    pointIdAccessor?: string | ((d: Datum) => string);
 }
-export interface StreamGeoFrameProps<T = Record<string, any>> {
+export interface StreamGeoFrameProps<T = Datum> {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
     /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
@@ -131,8 +141,8 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     className?: string;
     background?: string;
     runtimeMode?: "bounded" | "streaming";
-    areaStyle?: Style | ((d: any) => Style);
-    pointStyle?: (d: any) => Style & {
+    areaStyle?: Style | ((d: Datum) => Style);
+    pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     lineStyle?: Style | ((d: any, group?: string) => Style);
@@ -142,10 +152,14 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     tooltipContent?: (d: HoverData) => ReactNode;
     customClickBehavior?: (d: HoverData | null) => void;
     customHoverBehavior?: (d: HoverData | null) => void;
-    annotations?: Record<string, any>[];
+    annotations?: Datum[];
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
@@ -169,10 +183,10 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     summary?: string;
 }
 export interface StreamGeoFrameHandle {
-    push(datum: Record<string, any>): void;
-    pushMany(data: Record<string, any>[]): void;
+    push(datum: Datum): void;
+    pushMany(data: Datum[]): void;
     /** Remove points by ID. Requires pointIdAccessor. */
-    removePoint(id: string | string[]): Record<string, any>[];
+    removePoint(id: string | string[]): Datum[];
     clear(): void;
     getProjection(): GeoProjection | null;
     getGeoPath(): GeoPath<any, GeoPermissibleObjects> | null;
@@ -188,5 +202,5 @@ export interface StreamGeoFrameHandle {
     /** Animate back to initial view */
     resetZoom(): void;
     /** Get current data points */
-    getData(): Record<string, any>[];
+    getData(): Datum[];
 }

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Shared hover data utilities for stream frames.
  *
@@ -7,13 +8,25 @@
  * property flattening that are handled at the call site.
  */
 import type { HoverData } from "../realtime/types";
+/**
+ * Minimal shape a Stream Frame's internal hover handler needs from a pointer
+ * event. React.MouseEvent satisfies this structurally, as does the plain
+ * `{clientX, clientY}` object the rAF-coalescing path synthesizes. Using this
+ * narrower type on `hoverHandlerRef` (instead of `React.MouseEvent`) prevents
+ * downstream code from reading event fields — `currentTarget`, `target`,
+ * `preventDefault` — that wouldn't survive the coalescing cast.
+ */
+export interface HoverPointerCoords {
+    clientX: number;
+    clientY: number;
+}
 /**
  * Spread raw datum properties onto HoverData if it's a non-null,
  * non-array object. Class instances (Date, etc.) are included —
  * this matches the historical behavior where all datum fields are
  * accessible directly on the hover object (d.fieldName).
  */
-export declare function spreadDatum(rawDatum: any): Record<string, any>;
+export declare function spreadDatum(rawDatum: any): Datum;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * Spreads plain-object datum properties for backwards compatibility

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

@@ -13,17 +13,18 @@
  * Consumed by: hierarchyLayoutPlugin.ts (buildScene dispatcher)
  */
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge } from "../networkTypes";
-export declare function buildTreeScene(nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>, edgeStyleFn: (d: any) => Record<string, any>): {
+import type { Style } from "../types";
+export declare function buildTreeScene(nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: RealtimeNode) => Style, edgeStyleFn: (d: RealtimeEdge) => Style): {
     sceneNodes: NetworkSceneNode[];
     sceneEdges: NetworkSceneEdge[];
     labels: NetworkLabel[];
 };
-export declare function buildRectScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>): {
+export declare function buildRectScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: RealtimeNode) => Style): {
     sceneNodes: NetworkSceneNode[];
     sceneEdges: NetworkSceneEdge[];
     labels: NetworkLabel[];
 };
-export declare function buildCircleScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>): {
+export declare function buildCircleScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: RealtimeNode) => Style): {
     sceneNodes: NetworkSceneNode[];
     sceneEdges: NetworkSceneEdge[];
     labels: NetworkLabel[];

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

@@ -7,6 +7,7 @@
  * Consumed by: hierarchyLayoutPlugin.ts, hierarchySceneBuilders.ts
  */
 import type { NetworkPipelineConfig } from "../networkTypes";
+import type { Datum } from "../../charts/shared/datumTypes";
 /** Depth-based color palette shared across all hierarchy scene builders */
 export declare const DEPTH_PALETTE: string[];
 /**
@@ -19,7 +20,7 @@ export declare function parseColor(color: string): [number, number, number];
  * Uses perceived luminance (ITU-R BT.601).
  */
 export declare function contrastTextColor(bgColor: string): string;
-export declare function resolveChildrenAccessor(accessor: string | ((d: any) => any[]) | undefined): ((d: any) => any[]) | undefined;
+export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => any[]) | undefined): ((d: Datum) => any[]) | undefined;
 export declare function resolveNodeId(d: any, config: NetworkPipelineConfig, index: number): string;
-export declare function resolveLabelFn(nodeLabel: string | ((d: any) => string) | undefined): ((d: any) => string) | null;
-export declare function resolveDefaultNodeSize(nodeSize: number | string | ((d: any) => number) | undefined): number;
+export declare function resolveLabelFn(nodeLabel: string | ((d: Datum) => string) | undefined): ((d: Datum) => string) | null;
+export declare function resolveDefaultNodeSize(nodeSize: number | string | ((d: Datum) => number) | undefined): number;

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

@@ -2,7 +2,9 @@ import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
 import type { LegendGroup } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, StalenessConfig } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
+import type { Datum } from "../charts/shared/datumTypes";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -31,7 +33,7 @@ export interface RealtimeNode {
     _targetY1?: number;
     value: number;
     depth?: number;
-    data?: Record<string, any>;
+    data?: Datum;
     createdByFrame?: boolean;
     sourceLinks?: RealtimeEdge[];
     targetLinks?: RealtimeEdge[];
@@ -52,11 +54,13 @@ export interface RealtimeEdge {
     _targetY0?: number;
     _targetY1?: number;
     _targetSankeyWidth?: number;
+    /** Set during intro animation to allow edge interpolation from width 0 */
+    _introFromZero?: boolean;
     direction?: string;
     circular?: boolean;
     circularPathData?: any;
     bezier?: BezierCache;
-    data?: Record<string, any>;
+    data?: Datum;
     /** Unique key for this edge (supports parallel edges between same node pair) */
     _edgeKey?: string;
     _pulseIntensity?: number;
@@ -208,6 +212,9 @@ export interface NetworkBezierEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    /** Lazily-built Path2D for hit testing; invalidated when pathD changes. */
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Ribbon edge — used by chord */
 export interface NetworkRibbonEdge {
@@ -217,6 +224,8 @@ export interface NetworkRibbonEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Curved edge — used by tree, cluster */
 export interface NetworkCurvedEdge {
@@ -226,6 +235,8 @@ export interface NetworkCurvedEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
@@ -289,14 +300,14 @@ export interface ThresholdAlertConfig {
 }
 export interface NetworkPipelineConfig {
     chartType: NetworkChartType;
-    nodeIDAccessor?: string | ((d: any) => string);
-    sourceAccessor?: string | ((d: any) => string);
-    targetAccessor?: string | ((d: any) => string);
-    valueAccessor?: string | ((d: any) => number);
+    nodeIDAccessor?: string | ((d: Datum) => string);
+    sourceAccessor?: string | ((d: Datum) => string);
+    targetAccessor?: string | ((d: Datum) => string);
+    valueAccessor?: string | ((d: Datum) => number);
     /** Edge ID accessor for removeEdge(edgeId) — enables single-ID edge removal */
-    edgeIdAccessor?: string | ((d: any) => string);
-    childrenAccessor?: string | ((d: any) => any[]);
-    hierarchySum?: string | ((d: any) => number);
+    edgeIdAccessor?: string | ((d: Datum) => string);
+    childrenAccessor?: string | ((d: Datum) => any[]);
+    hierarchySum?: string | ((d: Datum) => number);
     orientation?: "horizontal" | "vertical";
     nodeAlign?: "justify" | "left" | "right" | "center";
     nodePaddingRatio?: number;
@@ -314,20 +325,27 @@ export interface NetworkPipelineConfig {
     tensionConfig?: TensionConfig;
     showParticles?: boolean;
     particleStyle?: ParticleStyle;
-    nodeStyle?: (d: any) => Record<string, any>;
-    edgeStyle?: (d: any) => Record<string, any>;
-    nodeLabel?: string | ((d: any) => string);
+    nodeStyle?: (d: Datum) => Datum;
+    edgeStyle?: (d: Datum) => Datum;
+    nodeLabel?: string | ((d: Datum) => string);
     showLabels?: boolean;
     labelMode?: "leaf" | "parent" | "all";
-    colorBy?: string | ((d: any) => string | number);
+    colorBy?: string | ((d: Datum) => string | number);
     colorScheme?: string | string[];
-    edgeColorBy?: "source" | "target" | "gradient" | ((d: any) => string);
+    /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
+    themeCategorical?: string[];
+    /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
+    themeSemantic?: ThemeSemanticColors;
+    edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     edgeOpacity?: number;
     colorByDepth?: boolean;
-    nodeSize?: number | string | ((d: any) => number);
+    nodeSize?: number | string | ((d: Datum) => number);
     nodeSizeRange?: [number, number];
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Whether to animate elements on first render (nodes scale up, edges fade in) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     /** Ring arrangement mode: "flat" (all children in one ring), "solar" (one per ring),
@@ -364,7 +382,7 @@ export interface NetworkPipelineConfig {
         y: number;
     }>;
 }
-export interface StreamNetworkFrameProps<T = Record<string, any>> {
+export interface StreamNetworkFrameProps<T = Datum> {
     chartType: NetworkChartType;
     nodes?: T[];
     edges?: T[] | T;
@@ -376,7 +394,7 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     targetAccessor?: string | ((d: T) => string);
     valueAccessor?: string | ((d: T) => number);
     /** Edge ID accessor for removeEdge(edgeId) single-ID removal */
-    edgeIdAccessor?: string | ((d: any) => string);
+    edgeIdAccessor?: string | ((d: Datum) => string);
     childrenAccessor?: string | ((d: T) => T[]);
     hierarchySum?: string | ((d: T) => number);
     orientation?: "horizontal" | "vertical";
@@ -396,16 +414,16 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     tensionConfig?: Partial<TensionConfig>;
     showParticles?: boolean;
     particleStyle?: ParticleStyle;
-    nodeStyle?: (d: any) => Record<string, any>;
-    edgeStyle?: (d: any) => Record<string, any>;
-    colorBy?: string | ((d: any) => string | number);
+    nodeStyle?: (d: Datum) => Datum;
+    edgeStyle?: (d: Datum) => Datum;
+    colorBy?: string | ((d: Datum) => string | number);
     colorScheme?: string | string[];
-    edgeColorBy?: "source" | "target" | "gradient" | ((d: any) => string);
+    edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     edgeOpacity?: number;
     colorByDepth?: boolean;
-    nodeSize?: number | string | ((d: any) => number);
+    nodeSize?: number | string | ((d: Datum) => number);
     nodeSizeRange?: [number, number];
-    nodeLabel?: string | ((d: any) => string);
+    nodeLabel?: string | ((d: Datum) => string);
     showLabels?: boolean;
     labelMode?: "leaf" | "parent" | "all";
     size?: [number, number];
@@ -428,8 +446,8 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     /** 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;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
     };
@@ -447,6 +465,11 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     backgroundGraphics?: ReactNode;
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     orbitMode?: "flat" | "solar" | "atomic" | number[];
@@ -472,9 +495,9 @@ export interface StreamNetworkFrameHandle {
     /** Remove edges by source+target, or by edge ID when edgeIdAccessor is configured. */
     removeEdge(sourceIdOrEdgeId: string, targetId?: string): boolean;
     /** Update a node's data by ID. Returns previous data. */
-    updateNode(id: string, updater: (data: Record<string, any>) => Record<string, any>): Record<string, any> | null;
+    updateNode(id: string, updater: (data: Datum) => Datum): Datum | null;
     /** Update all edges between source+target. Returns array of previous data. */
-    updateEdge(sourceId: string, targetId: string, updater: (data: Record<string, any>) => Record<string, any>): Record<string, any>[];
+    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
     clear(): void;
     getTopology(): {
         nodes: RealtimeNode[];

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

@@ -24,4 +24,4 @@ import type { OrdinalSceneContext } from "./types";
  *  - __barFunnelCategory: category key (for multi-category)
  *  - __barFunnelLabelX/Y: position for the floating label
  */
-export declare function buildBarFunnelScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildBarFunnelScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -1,4 +1,4 @@
 import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { OrdinalSceneContext } from "./types";
-export declare function buildBarScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
-export declare function buildClusterBarScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildBarScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildClusterBarScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -1,3 +1,3 @@
 import type { ConnectorSceneNode, OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { OrdinalSceneContext } from "./types";
-export declare function buildConnectors(ctx: OrdinalSceneContext, pieceNodes: OrdinalSceneNode[], layout: OrdinalLayout): ConnectorSceneNode[];
+export declare function buildConnectors(ctx: OrdinalSceneContext, pieceNodes: OrdinalSceneNode[], _layout: OrdinalLayout): ConnectorSceneNode[];

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

@@ -1,4 +1,4 @@
 import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { OrdinalSceneContext } from "./types";
-export declare function buildPointScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
-export declare function buildSwarmScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildPointScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildSwarmScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -1,6 +1,6 @@
 import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { OrdinalSceneContext } from "./types";
-export declare function buildBoxplotScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
-export declare function buildViolinScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
-export declare function buildHistogramScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
-export declare function buildRidgelineScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildBoxplotScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildViolinScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildHistogramScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildRidgelineScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -9,4 +9,4 @@ import type { OrdinalSceneContext } from "./types";
  * multiple items with the same subcategory can appear in the same lane —
  * they simply stack sequentially.
  */
-export declare function buildSwimlaneScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildSwimlaneScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -1,3 +1,3 @@
 import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
 import type { OrdinalSceneContext } from "./types";
-export declare function buildTimelineScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];
+export declare function buildTimelineScene(ctx: OrdinalSceneContext, _layout: OrdinalLayout): OrdinalSceneNode[];