semiotic 3.8.0 → 3.8.1

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;

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

@@ -16,8 +16,8 @@ export interface OrdinalSceneContext {
     getO: (d: Datum) => string;
     multiScales: ScaleLinear<number, number>[];
     rAccessors: ((d: Datum) => number)[];
-    resolvePieceStyle: (d: any, category?: string) => Style;
-    resolveSummaryStyle: (d: any, category?: string) => Style;
+    resolvePieceStyle: (d: Datum | null, category?: string) => Style;
+    resolveSummaryStyle: (d: Datum | null, category?: string) => Style;
     /** For timeline: resolve rAccessor as [start, end] */
     getRawRange: (d: Datum) => [number, number] | null;
 }

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

@@ -3,10 +3,13 @@ import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
-import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata } from "./types";
+import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane" | "custom";
 export interface OrdinalScales {
     o: ScaleBand<string>;
@@ -280,6 +283,8 @@ export interface OrdinalPipelineConfig {
     /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
     introAnimation?: boolean;
     staleness?: StalenessConfig;
+    /** Frame-owned logical clock for ingest, pulse, staleness, and transitions. */
+    clock?: import("./FrameRuntime").FrameClock;
     /** When provided, replaces chart-type dispatch in scene building.
      *  Receives an OrdinalLayoutContext (scales, dimensions, theme,
      *  resolveColor) and returns scene nodes plus optional overlays. */
@@ -384,6 +389,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
      *  it's a band scale, not a continuous one. Ignored when explicit
      *  `rTickValues` are provided — caller has hand-picked positions. */
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
+    /** Optional scene paint backend. Exact scene geometry remains interactive. */
+    renderMode?: SceneRenderMode<OrdinalSceneNode>;
     pieceStyle?: (d: Datum, category?: string) => Style;
     summaryStyle?: (d: Datum, category?: string) => Style;
     colorScheme?: string | string[] | Record<string, string>;
@@ -409,9 +416,17 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
-    customHoverBehavior?: (d: HoverData | null) => void;
-    customClickBehavior?: (d: HoverData | null) => void;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<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;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
@@ -460,6 +475,18 @@ export interface StreamOrdinalFrameProps<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 frame-local random source. Ordinal rendering currently has no stochastic layout. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed for future ordinal stochastic work. */
+    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;
     /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
     /** Accessible description overriding the auto-generated aria-label on the chart container */

package/dist/components/stream/physics/PhysicsPipelineStore.d.ts

@@ -56,6 +56,8 @@ export declare class PhysicsPipelineStore {
     recordObservation(record: PhysicsObservationRecord): PhysicsObservationEvent;
     /** Most recent explicit update result for a revision-aware host or tool. */
     getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
     version(): number;
     setPaused(paused: boolean): void;
     setVisible(visible: boolean): void;

package/dist/components/stream/physics/PhysicsSVGOverlay.d.ts

@@ -10,6 +10,8 @@ import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../../type
 import { type AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 import type { AnnotationContext } from "../../realtime/types";
 import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../../charts/shared/annotationActivation";
 export type PhysicsAnnotationAnchorNode = {
     pointId?: string;
     x: number;
@@ -47,6 +49,10 @@ export interface PhysicsSVGOverlayProps {
     /** Live body anchors for pointId / bodyId annotations. */
     pointNodes?: PhysicsAnnotationAnchorNode[];
     annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Optional foreground SVG already composed into the frame stack. */

package/dist/components/stream/physics/StreamPhysicsTypes.d.ts

@@ -157,7 +157,7 @@ export type StreamPhysicsBodyForce = StreamPhysicsRegionVector | ((context: Stre
 export interface PhysicsHoverData {
     __semioticHoverData: true;
     body: PhysicsBodyState;
-    data: unknown;
+    data: Datum | PhysicsBodyState;
     id: string;
     type: "body";
     x: number;
@@ -183,6 +183,17 @@ export interface StreamPhysicsFrameProps {
      * deterministic clock for replayable tests or evidence capture.
      */
     clock?: () => number;
+    /**
+     * Host-level random seam for frame-local visual work. It deliberately does
+     * not replace the physics kernel's deterministic random source.
+     */
+    random?: () => number;
+    /**
+     * Serializable deterministic seed for frame-local work and, when
+     * `config.kernel.seed` is omitted, the built-in physics kernel. An explicit
+     * kernel seed always wins so existing simulation snapshots remain stable.
+     */
+    seed?: number;
     bodySemanticItemLimit?: number;
     bodySemanticItems?: boolean | PhysicsBodySemanticItemAccessor;
     bodySemanticUpdateMs?: number;
@@ -230,6 +241,8 @@ export interface StreamPhysicsFrameProps {
      * `physics: "barrier"|"sensor"` also feed colliders via PhysicsAnnotations.
      */
     annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: import("../../charts/shared/annotationActivation").OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode;
     legend?: React.ReactNode | {
@@ -257,11 +270,13 @@ export interface StreamPhysicsFrameProps {
      * Click on a body (or empty canvas when null). Prefer this over
      * `onBodyPointerDown` when you only need the Semiotic click contract.
      */
-    onClick?: (datum: unknown | null, event: {
-        x: number;
-        y: number;
-        body: PhysicsBodyState | null;
-    }) => void;
+    onClick?: {
+        bivarianceHack(datum: Datum | null, event: {
+            x: number;
+            y: number;
+            body: PhysicsBodyState | null;
+        }): void;
+    }["bivarianceHack"];
     onRegionEvent?: (event: StreamPhysicsRegionEvent) => void;
     onSimulationExecutionChange?: (state: StreamPhysicsExecutionState) => void;
     onBodyPointerDown?: (body: PhysicsBodyState | null, event: React.PointerEvent<HTMLCanvasElement>) => void;

package/dist/components/stream/physics/physicsFrameObservations.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationInputType, OnObservationCallback } from "../../store/ObservationStore";
+interface CurrentRef<T> {
+    current: T;
+}
+export type PhysicsFrameObservationType = "hover" | "hover-end" | "click" | "click-end" | "focus" | "activate";
+export interface PhysicsFrameObservationPayload {
+    datum?: unknown;
+    x?: number;
+    y?: number;
+    inputType?: ObservationInputType;
+}
+interface PhysicsFrameObservationOptions {
+    onObservationRef: CurrentRef<OnObservationCallback | undefined>;
+    chartIdRef: CurrentRef<string | undefined>;
+    wallClockRef: CurrentRef<() => number>;
+}
+/** Builds a stable emitter while reading the frame's latest callback and clock refs. */
+export declare function usePhysicsFrameObservationEmitter({ onObservationRef, chartIdRef, wallClockRef }: PhysicsFrameObservationOptions): (type: PhysicsFrameObservationType, payload?: PhysicsFrameObservationPayload) => void;
+export {};

package/dist/components/stream/physics/physicsFrameSetup.d.ts

@@ -0,0 +1,4 @@
+import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "./PhysicsPipelineStore";
+/** Create the retained simulation store and seed its initial queued bodies. */
+export declare function createPhysicsFrameStore(config: PhysicsPipelineConfig | undefined, initialSpawns: PhysicsQueuedSpawn[] | undefined, initialSpawnPacing: PhysicsSpawnPacingOptions | undefined): PhysicsPipelineStore;
+export declare function defaultPhysicsFrameClock(): number;

package/dist/components/stream/physics/physicsPipelineUpdateResults.d.ts

@@ -3,7 +3,25 @@ import type { PhysicsPipelineConfig } from "./PhysicsPipelineTypes";
 import type { Invalidation } from "../pipelineUpdateContract";
 export declare const PHYSICS_BODY_INVALIDATIONS: readonly Invalidation[];
 export declare const PHYSICS_MOTION_INVALIDATIONS: readonly Invalidation[];
-export declare const PHYSICS_CONFIG_INVALIDATIONS: readonly Invalidation[];
 export declare const PHYSICS_STATE_INVALIDATIONS: readonly Invalidation[];
+/** Whether a config patch rebuilds Physics' retained simulation resource. */
+export type PhysicsRetainedDataEffect = "preserve" | "rebuild";
+export interface PhysicsConfigPatchDependency {
+    readonly retainedData: PhysicsRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Physics config changes either rebuild the retained engine, affect the next
+ * simulated geometry, alter capacity presentation, or only change future
+ * stepping/observation behavior. This keeps direct store consumers from
+ * treating every physics option as a full scene-layout update.
+ */
+export declare const PHYSICS_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, PhysicsConfigPatchDependency>>;
+export interface PhysicsConfigPatchClassification {
+    readonly retainedData: PhysicsRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyPhysicsConfigPatch(keys: readonly string[]): PhysicsConfigPatchClassification;
 export declare function physicsKernelOptionsEqual(a: PhysicsKernelOptions | undefined, b: PhysicsKernelOptions | undefined): boolean;
 export declare function changedPhysicsConfigKeys(config: PhysicsPipelineConfig, previous: PhysicsPipelineConfig): string[];

package/dist/components/stream/physics/usePhysicsFrameLifecyclePolicy.d.ts

@@ -1,9 +1,11 @@
 import { type MutableRefObject, type RefObject } from "react";
+import type { FrameRuntime } from "../FrameRuntime";
 import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
 import type { PhysicsWorkerCommand } from "./PhysicsWorkerProtocol";
 export declare function isPhysicsDocumentVisible(): boolean;
 interface PhysicsFrameLifecyclePolicyInput {
     cancelRender: () => void;
+    frameRuntime: FrameRuntime;
     lastFrameTimeRef: MutableRefObject<number | null>;
     paused: boolean;
     postWorkerCommand: (command: PhysicsWorkerCommand, notifyTick?: boolean) => void;
@@ -12,5 +14,5 @@ interface PhysicsFrameLifecyclePolicyInput {
     suspendWhenHidden: boolean;
 }
 /** Keep pause and page-visibility scheduling policy consistent for physics frames. */
-export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
+export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, frameRuntime, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
 export {};

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

@@ -11,6 +11,8 @@ import type { MarginType } from "../types/marginType";
 export interface PipelineConfig {
     chartType: StreamChartType;
     runtimeMode?: "streaming" | "bounded";
+    /** Optional monotonic clock owned by a frame runtime or embedding host. */
+    clock?: () => number;
     windowSize: number;
     windowMode: WindowMode;
     arrowOfTime: ArrowOfTime;
@@ -71,7 +73,7 @@ export interface PipelineConfig {
     /** Internal: set by PipelineStore when open/close accessors are both missing */
     candlestickRangeMode?: boolean;
     boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
-    boundsStyle?: any;
+    boundsStyle?: Style | ((d: Datum, group?: string) => Style);
     y0Accessor?: string | ((d: Datum) => CoercibleNumber);
     band?: BandConfig | BandConfig[];
     gradientFill?: {
@@ -90,7 +92,7 @@ export interface PipelineConfig {
             color: string;
         }>;
     };
-    lineStyle?: any;
+    lineStyle?: Style | ((d: Datum, group?: string) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };

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

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Shared decay encoding utilities for all pipeline stores.
  *
@@ -37,4 +37,4 @@ export declare function buildDatumIndexMap(data: readonly Datum[]): Map<Datum, n
  *
  * @param indexMap Optional prebuilt datum→index map (see {@link buildDatumIndexMap}).
  */
-export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[], indexMap?: Map<any, number>): void;
+export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[], indexMap?: Map<DatumValue, number>): void;

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

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Pulse encoding for XY pipeline scene nodes.
  *
@@ -21,7 +21,7 @@ export declare function computePulseIntensity(pulse: PulseConfig, insertTime: nu
  * @param indexMap Optional prebuilt datum→index map so a scene pass that
  * also runs decay can share one O(n) walk of the buffer.
  */
-export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>, indexMap?: Map<any, number>, now?: number): boolean;
+export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>, indexMap?: Map<DatumValue, number>, now?: number): boolean;
 /**
  * Update the pulse-owned fields for a node that the pipeline has matched to
  * source data. Keeping this narrow is important for custom layouts: nodes

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

@@ -1,12 +1,33 @@
-import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/** Whether a config patch re-derives retained XY data resources. */
+export type XYRetainedDataEffect = "preserve" | "rebuild";
+export interface XYConfigPatchDependency {
+    readonly retainedData: XYRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * XY's explicit config-patch dependency table. Accessor and chart-mode
+ * changes re-derive retained data; scale/layout keys preserve data while
+ * rebuilding derived scene state; styling and overlays repaint their own
+ * layers. Mount-only and future-work keys intentionally have no immediate
+ * revision effect.
+ */
+export declare const XY_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, XYConfigPatchDependency>>;
+export interface XYConfigPatchClassification {
+    readonly retainedData: XYRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyXYConfigPatch(keys: readonly string[]): XYConfigPatchClassification;
 type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
 /** Result bookkeeping and invalidation policy for the XY PipelineStore pilot. */
 export declare class PipelineStoreUpdateResults {
     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[], requiresRebuild: boolean, extentAccessorChanged: boolean): UpdateResult;
+    recordConfig(keys: readonly string[]): UpdateResult;
 }
 export {};