semiotic 3.8.0 → 3.8.2

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
@@ -11,6 +11,9 @@ import type { MarginType } from "../types/marginType";
 import type { GeoCustomLayout } from "./geoCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -69,7 +72,7 @@ export interface GeoLineSceneNode {
 export type GeoSceneNode = GeoAreaSceneNode | PointSceneNode | GlyphSceneNode | GeoLineSceneNode;
 export interface GeoScales {
     projection: GeoProjection;
-    geoPath: GeoPath<any, GeoPermissibleObjects>;
+    geoPath: GeoPath<void, GeoPermissibleObjects>;
     projectedPoint: (lon: number, lat: number) => [number, number] | null;
     invertedPoint: (px: number, py: number) => [number, number] | null;
 }
@@ -77,19 +80,20 @@ export interface GeoPipelineConfig {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
     /**
-     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
-     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
-     * almost always a pixel mistake and collapses the projection off-canvas.
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
      * @default 0
      */
-    fitPadding?: number;
+    fitPadding?: number | null;
     xAccessor?: string | ((d: Datum) => number);
     yAccessor?: string | ((d: Datum) => number);
     lineDataAccessor?: string | ((d: Datum) => Datum[]);
     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: Datum) => Style);
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
@@ -103,6 +107,10 @@ export interface GeoPipelineConfig {
     themeDiverging?: string;
     graticule?: boolean | GraticuleConfig;
     projectionTransform?: DistanceCartogramConfig;
+    /** Maximum retained points and lines after the store enters streaming mode. @default 500 */
+    windowSize?: number;
+    /** Logical clock used for Geo pulse and transition work. */
+    clock?: import("./FrameRuntime").FrameClock;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
@@ -125,12 +133,13 @@ export interface StreamGeoFrameProps<T = Datum> {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
     /**
-     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
-     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
-     * almost always a pixel mistake and collapses the projection off-canvas.
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
      * @default 0
      */
-    fitPadding?: number;
+    fitPadding?: number | null;
     areas?: GeoJSON.Feature[];
     points?: T[];
     lines?: T[];
@@ -190,7 +199,11 @@ export interface StreamGeoFrameProps<T = Datum> {
     className?: string;
     background?: string;
     runtimeMode?: "bounded" | "streaming";
-    areaStyle?: Style | ((d: Datum) => Style);
+    /** Maximum retained points and lines after imperative streaming begins. @default 500 */
+    windowSize?: number;
+    /** Optional scene paint backend. Exact projected geometry remains interactive. */
+    renderMode?: SceneRenderMode<GeoSceneNode>;
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
@@ -214,9 +227,17 @@ export interface StreamGeoFrameProps<T = Datum> {
      * @default false
      */
     allowTooltipOverflow?: boolean;
-    customClickBehavior?: (d: HoverData | null) => void;
-    customHoverBehavior?: (d: HoverData | null) => void;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    /** Structured interaction observations, including semantic focus/activate. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier included in observation events. */
+    chartId?: string;
     annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     decay?: DecayConfig;
     pulse?: PulseConfig;
@@ -226,6 +247,18 @@ export interface StreamGeoFrameProps<T = Datum> {
      *  Set `{ intro: false }` to disable the intro animation. */
     animate?: AnimateProp;
     staleness?: StalenessConfig;
+    /** Optional rAF seam for deterministic host scheduling. */
+    frameScheduler?: import("./useFrame").FrameScheduler;
+    /** Monotonic wall-clock seam for deterministic replay, tests, or evidence capture. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Injectable random source for frame-local stochastic work. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed. Ignored when `random` is supplied. */
+    seed?: number;
+    /** Freeze logical animation time and cancel queued work while paused. */
+    paused?: boolean;
+    /** Freeze logical animation time while the page is hidden. Defaults to true for Geo frames. */
+    suspendWhenHidden?: boolean;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
@@ -271,7 +304,7 @@ export interface StreamGeoFrameHandle {
     getLines(): Datum[];
     clear(): void;
     getProjection(): GeoProjection | null;
-    getGeoPath(): GeoPath<any, GeoPermissibleObjects> | null;
+    getGeoPath(): GeoPath<void, GeoPermissibleObjects> | null;
     /** Get cartogram layout info (center position, max cost, radius) */
     getCartogramLayout(): {
         cx: number;

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

@@ -27,11 +27,11 @@ export declare function getHitRadius(nodeRadius: number | undefined, maxDistance
  * Convert a value to a Date if possible. Returns null for non-date values.
  * Treats numbers > 1e9 as millisecond timestamps.
  */
-export declare function toDate(value: any): Date | null;
+export declare function toDate(value: Date | number | string | null | undefined): Date | null;
 /**
  * Detect whether a tick marks a time boundary (new month or year) compared to the previous tick.
  */
-export declare function isTimeLandmark(value: any, prevValue: any): boolean;
+export declare function isTimeLandmark(value: Date | number | string | null | undefined, prevValue: Date | number | string | null | undefined): boolean;
 /**
  * Normalize an angle to the [0, 2π) range.
  */

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

@@ -7,6 +7,8 @@
  * property flattening that are handled at the call site.
  */
 import type { HoverData } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export type RawHoverDatum = Datum | Datum[] | null;
 /**
  * Minimal shape a Stream Frame's internal hover handler needs from a pointer
  * event. React.MouseEvent satisfies this structurally, as does the plain
@@ -22,7 +24,7 @@ export interface HoverPointerCoords {
 }
 export declare const TOUCH_HIT_RADIUS = 24;
 export declare function getPointerHitRadius(baseRadius: number, pointerType?: string): number;
-export declare function normalizeHoverDatum(rawDatum: any): any;
+export declare function normalizeHoverDatum(rawDatum: RawHoverDatum): Datum | null;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * The raw datum is preserved as `hover.data` for tooltip / callback
@@ -30,4 +32,4 @@ export declare function normalizeHoverDatum(rawDatum: any): any;
  * relevant to a specific frame family — `category`, `stats`,
  * `nodeOrEdge`, `xValue`, etc. — is layered in via `extra`.
  */
-export declare function buildHoverData(rawDatum: any, x: number, y: number, extra?: Partial<HoverData>): HoverData;
+export declare function buildHoverData(rawDatum: RawHoverDatum, x: number, y: number, extra?: Partial<HoverData>): HoverData;

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

@@ -17,6 +17,7 @@ export interface FrameForceWorkerRequest {
         chartType: "force";
         iterations?: number;
         forceStrength?: number;
+        seed?: number;
     };
     size: [number, number];
 }

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

@@ -20,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: Datum) => any[]) | undefined): ((d: Datum) => any[]) | undefined;
-export declare function resolveNodeId(d: any, config: NetworkPipelineConfig, index: number): string;
+export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => Datum[]) | undefined): ((d: Datum) => Datum[]) | undefined;
+export declare function resolveNodeId(d: Datum, config: NetworkPipelineConfig, index: number): string;
 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/networkCustomLayoutRunner.d.ts

@@ -0,0 +1,23 @@
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkPipelineConfig, RealtimeEdge, RealtimeNode } from "./networkTypes";
+interface NetworkCustomLayoutRunInput {
+    config: NetworkPipelineConfig;
+    customLayout: NonNullable<NetworkPipelineConfig["customNetworkLayout"]>;
+    size: [number, number];
+    nodes: RealtimeNode[];
+    edges: RealtimeEdge[];
+    previousResult: NetworkLayoutResult | null;
+    revision: number;
+}
+export type NetworkCustomLayoutRunResult = {
+    kind: "success";
+    result: NetworkLayoutResult;
+} | {
+    kind: "failure";
+    diagnostic: CustomLayoutFailureDiagnostic;
+    preservedLastGoodScene: boolean;
+};
+/** Runs user-provided network layout code behind the common failure boundary. */
+export declare function runNetworkCustomLayout({ config, customLayout, size, nodes, edges, previousResult, revision }: NetworkCustomLayoutRunInput): NetworkCustomLayoutRunResult;
+export {};

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

@@ -0,0 +1,15 @@
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
+import type { Style } from "./types";
+export declare function snapshotNetworkCustomStyles(nodes: NetworkSceneNode[], edges: NetworkSceneEdge[]): WeakMap<object, Style>;
+interface NetworkRestyleInput {
+    nodes: NetworkSceneNode[];
+    edges: NetworkSceneEdge[];
+    restyle: NetworkLayoutResult["restyle"];
+    restyleEdge: NetworkLayoutResult["restyleEdge"];
+    baseStyles: WeakMap<object, Style>;
+    selection: CustomLayoutSelection | null;
+}
+export declare function restyleNetworkCustomScene({ nodes, edges, restyle, restyleEdge, baseStyles, selection }: NetworkRestyleInput): boolean;
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * Whether the network paint loop needs another animation frame.
+ *
+ * Particles are continuous only for sankey and custom layouts; pulse and
+ * pipeline animations apply to every chart type.
+ */
+export declare function shouldContinueNetworkAnimation(chartType: string, hasCustomNetworkLayout: boolean, showParticles: boolean, hasPulse: boolean, isStoreAnimating: boolean): boolean;

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

@@ -0,0 +1,39 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { EdgePush, RealtimeEdge, RealtimeNode } from "./networkTypes";
+import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+/** Imperative API exposed by `StreamNetworkFrame` refs. */
+export interface StreamNetworkFrameHandle {
+    push(edge: EdgePush): void;
+    pushMany(edges: EdgePush[]): void;
+    /** Remove a node by ID. Also removes connected edges. */
+    removeNode(id: string): boolean;
+    /** 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: Datum) => Datum): Datum | null;
+    /** Update all edges between source+target. Returns array of previous data. */
+    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
+    clear(): void;
+    getTopology(): {
+        nodes: RealtimeNode[];
+        edges: RealtimeEdge[];
+    };
+    getTopologyDiff(): {
+        addedNodes: string[];
+        removedNodes: string[];
+        addedEdges: string[];
+        removedEdges: string[];
+    };
+    relayout(): void;
+    getTension(): number;
+    /** The most recent custom layout result (sceneNodes/sceneEdges/overlays as
+     *  returned by `customNetworkLayout`) - host readback so pages that need the
+     *  computed placement do not re-run the layout. Null before the first layout
+     *  or when no custom layout is configured. A failed retry retains the prior
+     *  good result; inspect `getLayoutFailure()` to distinguish recovery. */
+    getCustomLayout(): NetworkLayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by a successful layout,
+     * removing the custom layout, or `clear()`. */
+    getLayoutFailure(): CustomLayoutFailureDiagnostic | null;
+}

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

@@ -0,0 +1,15 @@
+import { type SemanticClickBehavior, type SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { HoverData } from "../realtime/types";
+import type { OnObservationCallback } from "../store/ObservationStore";
+interface NetworkObservationBehaviorOptions {
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+}
+/** Adds the standard observation vocabulary to the network behavior callbacks. */
+export declare function useNetworkObservationBehaviors({ customHoverBehavior: customHoverBehaviorProp, customClickBehavior: customClickBehaviorProp, onObservation, chartId }: NetworkObservationBehaviorOptions): {
+    customHoverBehavior: SemanticHoverBehavior<HoverData>;
+    customClickBehavior: SemanticClickBehavior<HoverData>;
+};
+export {};

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

@@ -1,21 +1,30 @@
 import type { NetworkPipelineStore } from "./NetworkPipelineStore";
-import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge } from "./networkTypes";
+import type { SceneRevisionDiagnostics } from "./sceneRevisionDiagnostics";
+import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge, NetworkSceneNode, NetworkSceneEdge } from "./networkTypes";
 import type { MarginType } from "../types/marginType";
-import type { DecayConfig, PulseConfig, StalenessConfig } from "./types";
+import type { DecayConfig, PulseConfig, StalenessConfig, SceneRenderMode } from "./types";
 export interface NetworkFramePaintContext {
     canvas: HTMLCanvasElement;
     store: NetworkPipelineStore;
+    sceneRevisionDiagnostics?: SceneRevisionDiagnostics;
     size: [number, number];
     margin: MarginType;
     adjustedWidth: number;
     adjustedHeight: number;
     background?: string;
+    renderMode?: SceneRenderMode<NetworkSceneNode | NetworkSceneEdge>;
+    /** Skip opaque canvas fill when an SVG backgroundGraphics layer is present. */
+    hasBackgroundGraphics?: boolean;
     dirtyRef: {
         current: boolean;
     };
     lastFrameTimeRef: {
         current: number;
     };
+    /** FrameRuntime logical timestamp for this paint. */
+    now: number;
+    /** FrameRuntime random source for particle placement/spawn sampling. */
+    random: () => number;
     reducedMotion: boolean;
     showParticles: boolean;
     isContinuous: boolean;

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

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+import type { AnnotationContext, HoverData } from "../realtime/types";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { OnObservationCallback } from "../store/ObservationStore";
+/** Interaction and annotation callbacks shared by every network chart layout. */
+export interface StreamNetworkInteractionProps<Node, Edge> {
+    enableHover?: boolean;
+    tooltipContent?: (d: HoverData) => ReactNode;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    /** Observation callback — emits hover/click events to the ObservationStore and this callback. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier for observation filtering. */
+    chartId?: string;
+    onTopologyChange?: (nodes: Node[], edges: Edge[]) => void;
+    annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
+}

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

@@ -5,7 +5,7 @@
 import type { SemioticTheme } from "../store/ThemeStore";
 import type { NetworkPipelineConfig } from "./networkTypes";
 import type { StreamNetworkFrameProps } from "./networkTypes";
-export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "nodeStyle" | "edgeStyle" | "nodeLabel" | "showLabels" | "labelMode" | "colorBy" | "colorScheme" | "edgeColorBy" | "edgeOpacity" | "colorByDepth" | "nodeSize" | "nodeSizeRange" | "decay" | "pulse" | "transition" | "staleness" | "thresholds" | "orbitMode" | "orbitSize" | "orbitSpeed" | "orbitRevolution" | "orbitRevolutionStyle" | "orbitEccentricity" | "orbitShowRings" | "orbitAnimated" | "customNetworkLayout" | "onLayoutError" | "layoutConfig"> & {
+export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "nodeStyle" | "edgeStyle" | "nodeLabel" | "showLabels" | "labelMode" | "colorBy" | "colorScheme" | "edgeColorBy" | "edgeOpacity" | "colorByDepth" | "nodeSize" | "nodeSizeRange" | "decay" | "pulse" | "transition" | "staleness" | "thresholds" | "orbitMode" | "orbitSize" | "orbitSpeed" | "orbitRevolution" | "orbitRevolutionStyle" | "orbitEccentricity" | "orbitShowRings" | "orbitAnimated" | "clock" | "random" | "seed" | "customNetworkLayout" | "onLayoutError" | "layoutConfig"> & {
     tensionConfig: NetworkPipelineConfig["tensionConfig"];
     showParticles: boolean;
     particleStyle: NetworkPipelineConfig["particleStyle"];
@@ -14,7 +14,7 @@ export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartT
 };
 export declare function buildNetworkPipelineConfig(sources: NetworkPipelineConfigSources): NetworkPipelineConfig;
 /** Fields that force re-ingest / re-layout when changed. */
-export type NetworkLayoutConfigSignature = Pick<NetworkPipelineConfigSources, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "tensionConfig" | "customNetworkLayout"> & {
+export type NetworkLayoutConfigSignature = Pick<NetworkPipelineConfigSources, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "random" | "seed" | "tensionConfig" | "customNetworkLayout"> & {
     orbitMode?: NetworkPipelineConfigSources["orbitMode"];
     orbitSize?: NetworkPipelineConfigSources["orbitSize"];
     orbitEccentricity?: NetworkPipelineConfigSources["orbitEccentricity"];

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

@@ -0,0 +1,38 @@
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/**
+ * The retained topology is unchanged by most config updates. The distinction
+ * is public here because callers must not mistake a config patch for a new
+ * ingest: only accessor/chart-type patches need the retained raw graph
+ * re-derived before the declared layout work runs.
+ */
+export type NetworkRetainedDataEffect = "preserve" | "rebuild";
+export interface NetworkConfigPatchDependency {
+    readonly retainedData: NetworkRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Network's config dependency table. It is deliberately key-level rather
+ * than a single conservative fallback so an integration can inspect whether
+ * a patch rebuilds retained topology, relays out marks, repaints styles, or
+ * only changes future work. Unknown future keys retain the safe layout
+ * fallback below until they receive an explicit entry.
+ */
+export declare const NETWORK_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, NetworkConfigPatchDependency>>;
+export interface NetworkConfigPatchClassification {
+    readonly retainedData: NetworkRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyNetworkConfigPatch(keys: readonly string[]): NetworkConfigPatchClassification;
+type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
+/** Result bookkeeping and explicit config-patch dependency policy for Network. */
+export declare class NetworkPipelineUpdateResults {
+    private tracker;
+    get last(): UpdateResult;
+    subscribe(listener: () => void): () => void;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[]): UpdateResult;
+}
+export {};

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

@@ -1,13 +1,17 @@
 import type { ReactNode } from "react";
-import type { OnObservationCallback } from "../store/ObservationStore";
-import type { HoverData, AnnotationContext } from "../realtime/types";
+import type { HoverData } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+type NetworkDatumComparator = {
+    bivarianceHack(a: Datum, b: Datum): number;
+}["bivarianceHack"];
+type NetworkGroupComparator = (a: number, b: number) => number;
 import type { LegendGroup, LegendLayout } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum, SceneAccessibilityMetadata } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { Datum } from "../charts/shared/datumTypes";
-import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { NetworkSymbolName } from "./symbolPath";
 import type { GlyphDef } from "./glyphDef";
+import type { StreamNetworkFrameHandle } from "./networkFrameHandleTypes";
+import type { StreamNetworkInteractionProps } from "./networkInteractionTypes";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -184,6 +188,8 @@ export interface RealtimeNetworkFrameProps {
     tensionConfig?: Partial<TensionConfig>;
     showParticles?: boolean;
     particleStyle?: ParticleStyle;
+    /** Optional scene paint backend. Exact node and edge geometry remains interactive. */
+    renderMode?: SceneRenderMode<NetworkSceneNode | NetworkSceneEdge>;
     colorBy?: string | ((d: RealtimeNode) => string);
     colorScheme?: string | string[] | Record<string, string>;
     edgeColorBy?: "source" | "target" | ((d: RealtimeEdge) => string);
@@ -445,6 +451,12 @@ export interface ThresholdAlertConfig {
 }
 export interface NetworkPipelineConfig {
     chartType: NetworkChartType;
+    /** Frame-owned logical clock for ingest, live encodings, and transitions. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Frame-local random source used by synchronous force layout. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic seed, including the force-worker protocol. */
+    seed?: number;
     nodeIDAccessor?: string | ((d: Datum) => string);
     sourceAccessor?: string | ((d: Datum) => string);
     targetAccessor?: string | ((d: Datum) => string);
@@ -457,14 +469,14 @@ export interface NetworkPipelineConfig {
     nodeAlign?: "justify" | "left" | "right" | "center";
     nodePaddingRatio?: number;
     nodeWidth?: number;
-    edgeSort?: (a: unknown, b: unknown) => number;
+    edgeSort?: NetworkDatumComparator;
     iterations?: number;
     forceStrength?: number;
     /** @internal Skip simulation after worker-computed positions are applied. */
     __skipForceSimulation?: boolean;
     padAngle?: number;
     groupWidth?: number;
-    sortGroups?: (a: unknown, b: unknown) => number;
+    sortGroups?: NetworkGroupComparator;
     treeOrientation?: "vertical" | "horizontal" | "radial";
     edgeType?: "line" | "curve";
     padding?: number;
@@ -541,7 +553,7 @@ export interface NetworkPipelineConfig {
      *  `buildScene` (re-emitting dimmed marks) without a re-ingest or re-layout. */
     layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
-export interface StreamNetworkFrameProps<T = Datum> {
+export interface StreamNetworkFrameProps<T = Datum> extends StreamNetworkInteractionProps<RealtimeNode, RealtimeEdge> {
     chartType: NetworkChartType;
     nodes?: T[];
     edges?: T[] | T;
@@ -570,8 +582,10 @@ export interface StreamNetworkFrameProps<T = Datum> {
     onLayoutStateChange?: (state: "pending" | "ready" | "error") => void;
     padAngle?: number;
     groupWidth?: number;
-    sortGroups?: (a: unknown, b: unknown) => number;
-    edgeSort?: (a: unknown, b: unknown) => number;
+    sortGroups?: NetworkGroupComparator;
+    edgeSort?: NetworkDatumComparator;
+    /** Optional scene paint backend. Exact node and edge geometry remains interactive. */
+    renderMode?: SceneRenderMode<NetworkSceneNode | NetworkSceneEdge>;
     treeOrientation?: "vertical" | "horizontal" | "radial";
     edgeType?: "line" | "curve";
     padding?: number;
@@ -602,18 +616,6 @@ export interface StreamNetworkFrameProps<T = Datum> {
     };
     className?: string;
     background?: string;
-    enableHover?: boolean;
-    tooltipContent?: (d: HoverData) => ReactNode;
-    customHoverBehavior?: (d: HoverData | null) => void;
-    customClickBehavior?: (d: HoverData | 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?: Datum[];
-    autoPlaceAnnotations?: AutoPlaceAnnotations;
-    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
     };
@@ -638,6 +640,18 @@ export interface StreamNetworkFrameProps<T = Datum> {
      *  Set `{ intro: false }` to disable the intro animation. */
     animate?: AnimateProp;
     staleness?: StalenessConfig;
+    /** Optional rAF seam for deterministic host scheduling. */
+    frameScheduler?: import("./useFrame").FrameScheduler;
+    /** Monotonic wall-clock seam used to derive logical frame time. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Injectable random source for force layout and particles. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed. Ignored when `random` is supplied. */
+    seed?: number;
+    /** Freeze logical animation time and cancel queued work while paused. */
+    paused?: boolean;
+    /** Freeze logical animation time while the document is hidden. Defaults to true. */
+    suspendWhenHidden?: boolean;
     thresholds?: ThresholdAlertConfig;
     orbitMode?: "flat" | "solar" | "atomic" | number[];
     orbitSize?: number | ((node: Datum) => number);
@@ -666,38 +680,5 @@ export interface StreamNetworkFrameProps<T = Datum> {
      *  `selection` / `linkedHover` wiring; render-only (no re-ingest on change). */
     layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
-export interface StreamNetworkFrameHandle {
-    push(edge: EdgePush): void;
-    pushMany(edges: EdgePush[]): void;
-    /** Remove a node by ID. Also removes connected edges. */
-    removeNode(id: string): boolean;
-    /** 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: Datum) => Datum): Datum | null;
-    /** Update all edges between source+target. Returns array of previous data. */
-    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
-    clear(): void;
-    getTopology(): {
-        nodes: RealtimeNode[];
-        edges: RealtimeEdge[];
-    };
-    getTopologyDiff(): {
-        addedNodes: string[];
-        removedNodes: string[];
-        addedEdges: string[];
-        removedEdges: string[];
-    };
-    relayout(): void;
-    getTension(): number;
-    /** The most recent custom layout result (sceneNodes/sceneEdges/overlays as
-     *  returned by `customNetworkLayout`) — host readback so pages that need the
-     *  computed placement don't re-run the layout. Null before the first layout
-     *  or when no custom layout is configured. A failed retry retains the prior
-     *  good result; inspect `getLayoutFailure()` to distinguish recovery. */
-    getCustomLayout(): import("./networkCustomLayout").NetworkLayoutResult | null;
-    /** The latest custom-layout failure, if any. Cleared by a successful layout,
-     * removing the custom layout, or `clear()`. */
-    getLayoutFailure(): import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
-}
+export type { StreamNetworkFrameHandle } from "./networkFrameHandleTypes";
 export type NetworkRendererFn = (ctx: CanvasRenderingContext2D, nodes: NetworkSceneNode[], edges: NetworkSceneEdge[], size: [number, number]) => void;

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

@@ -2,6 +2,6 @@
  * Chart-type → canvas renderer dispatch for StreamOrdinalFrame.
  * Connectors are always included when the chart type builds them into the scene.
  */
-import type { OrdinalChartType } from "./ordinalTypes";
-export type OrdinalAnyRendererFn = (ctx: CanvasRenderingContext2D, nodes: any[], scales: any, layout: any) => void;
+import type { OrdinalChartType, OrdinalRendererFn } from "./ordinalTypes";
+export type OrdinalAnyRendererFn = OrdinalRendererFn;
 export declare const ORDINAL_CANVAS_RENDERERS: Record<OrdinalChartType, OrdinalAnyRendererFn[]>;

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

@@ -1,9 +1,28 @@
-import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/** Whether a config patch re-derives retained ordinal data resources. */
+export type OrdinalRetainedDataEffect = "preserve" | "rebuild";
+export interface OrdinalConfigPatchDependency {
+    readonly retainedData: OrdinalRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Ordinal's key-level patch policy. Category/value/order accessors re-derive
+ * retained categorical state. Layout, style, and future-only controls expose
+ * distinct revision effects instead of the previous blanket scene rebuild.
+ */
+export declare const ORDINAL_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, OrdinalConfigPatchDependency>>;
+export interface OrdinalConfigPatchClassification {
+    readonly retainedData: OrdinalRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyOrdinalConfigPatch(keys: readonly string[]): OrdinalConfigPatchClassification;
 type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
 /** Result bookkeeping and invalidation policy for the Ordinal store pilot. */
 export declare class OrdinalPipelineUpdateResults {
     private tracker;
     get last(): UpdateResult;
+    subscribe(listener: () => void): () => void;
     recordData(kind: DataChangeKind, count?: number): UpdateResult;
     recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
     recordRestyle(hasCustomRestyle: boolean): UpdateResult;