semiotic 3.7.5 → 3.8.1

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

@@ -1,12 +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 } 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;
@@ -52,6 +57,8 @@ export interface RealtimeNode {
     __hierarchyNode?: unknown;
     /** @internal Circle-pack layout radius. Set by `hierarchyLayoutPlugin`. */
     __radius?: number;
+    /** @internal Pre-resolved force-layout radius used by worker snapshots. */
+    __forceRadius?: number;
     /**
      * @internal Chord-layout extension. Carries the start/end angles
      * for the arc segment representing this node, computed by
@@ -181,8 +188,10 @@ 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[];
+    colorScheme?: string | string[] | Record<string, string>;
     edgeColorBy?: "source" | "target" | ((d: RealtimeEdge) => string);
     edgeOpacity?: number;
     nodeLabel?: string | ((d: RealtimeNode) => string);
@@ -205,6 +214,8 @@ export interface NetworkCircleNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -221,6 +232,8 @@ export interface NetworkRectNode {
     h: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -242,6 +255,8 @@ export interface NetworkArcNode {
     endAngle: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     _pulseIntensity?: number;
@@ -268,6 +283,47 @@ export interface NetworkSymbolNode {
     rotation?: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
+    id?: string;
+    label?: string;
+    depth?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}
+/**
+ * Glyph node — the composite-pictogram channel for network scenes: a
+ * multi-part `GlyphDef` stamped at (cx, cy) with per-node `color`/`accent`
+ * paints and optional partial fill. The network sibling of the XY/ordinal/geo
+ * `GlyphSceneNode`.
+ */
+export interface NetworkGlyphNode {
+    type: "glyph";
+    cx: number;
+    cy: number;
+    /** Rendered height in px — width follows the definition's viewBox aspect. */
+    size: number;
+    /** The multi-part pictogram definition to stamp. */
+    glyph: GlyphDef;
+    /** Primary paint for parts declaring `"color"`. Falls back to `style.fill`. */
+    color?: string;
+    /** Accent paint for parts declaring `"accent"`. */
+    accent?: string;
+    /** Partial fill 0–1. @default 1 */
+    fraction?: number;
+    /** Where the partial fill begins, 0–1. @default 0 */
+    fractionStart?: number;
+    /** Partial-fill axis. @default "horizontal" */
+    fractionDirection?: "horizontal" | "vertical";
+    /** Ghost paint drawn at full extent beneath a partial fill. */
+    ghostColor?: string;
+    /** Rotation in radians about (cx, cy). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -333,7 +389,7 @@ export interface NetworkCurvedEdge {
     _cachedPath2D?: Path2D;
     _cachedPath2DSource?: string;
 }
-export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode;
+export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode | NetworkGlyphNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
 /** Label data for the SVG overlay */
 export interface NetworkLabel {
@@ -395,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);
@@ -407,12 +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;
@@ -426,7 +490,7 @@ export interface NetworkPipelineConfig {
     showLabels?: boolean;
     labelMode?: "leaf" | "parent" | "all";
     colorBy?: string | ((d: Datum) => string | number);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, 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. */
@@ -479,6 +543,8 @@ export interface NetworkPipelineConfig {
     /** When provided, replaces both layout dispatch and scene building.
      *  Receives raw nodes/edges and returns positioned scene primitives. */
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** Called when `customNetworkLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared-selection predicate, surfaced to a custom layout as
@@ -487,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;
@@ -508,10 +574,18 @@ export interface StreamNetworkFrameProps<T = Datum> {
     nodeWidth?: number;
     iterations?: number;
     forceStrength?: number;
+    /** Execute force layout synchronously, in a worker, or choose by graph cost. */
+    layoutExecution?: "auto" | "worker" | "sync";
+    /** Content displayed while an internally-managed worker layout is pending. */
+    layoutLoadingContent?: ReactNode | false;
+    /** Receives internally-managed force-layout lifecycle changes. */
+    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;
@@ -522,7 +596,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
     nodeStyle?: (d: Datum) => Datum;
     edgeStyle?: (d: Datum) => Datum;
     colorBy?: string | ((d: Datum) => string | number);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     edgeOpacity?: number;
     colorByDepth?: boolean;
@@ -542,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[];
     };
@@ -578,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);
@@ -597,6 +671,8 @@ export interface StreamNetworkFrameProps<T = Datum> {
      *  Receives raw nodes/edges + dimensions/theme, returns positioned scene
      *  primitives. See `semiotic/recipes` for reference layouts (flextree, dagre). */
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** Called when `customNetworkLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared-selection predicate, surfaced to a custom layout as
@@ -604,29 +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;
-}
+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

@@ -0,0 +1,7 @@
+/**
+ * Chart-type → canvas renderer dispatch for StreamOrdinalFrame.
+ * Connectors are always included when the chart type builds them into the scene.
+ */
+import type { OrdinalChartType, OrdinalRendererFn } from "./ordinalTypes";
+export type OrdinalAnyRendererFn = OrdinalRendererFn;
+export declare const ORDINAL_CANVAS_RENDERERS: Record<OrdinalChartType, OrdinalAnyRendererFn[]>;

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

@@ -0,0 +1,5 @@
+import type { Datum } from "../charts/shared/datumTypes";
+type CategoryAccessor = string | ((datum: Datum) => string) | undefined;
+/** Build the source-data category index used by aggregate pulse marks. */
+export declare function buildOrdinalCategoryIndex(data: readonly Datum[], categoryAccessor: CategoryAccessor): Map<string, number[]>;
+export {};

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

@@ -0,0 +1,10 @@
+/**
+ * Default ordinal hover tooltip for StreamOrdinalFrame.
+ * Uses shared `defaultTooltipStyle` for theme CSS-var consistency.
+ */
+import * as React from "react";
+import type { HoverData } from "./ordinalTypes";
+declare function DefaultOrdinalTooltip({ hover }: {
+    hover: HoverData;
+}): React.JSX.Element | null;
+export { DefaultOrdinalTooltip };

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

@@ -0,0 +1,38 @@
+/**
+ * Pure ordinal domain + column projection helpers for OrdinalPipelineStore.
+ */
+import type { ScaleBand } from "d3-scale";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { OrdinalColumn, OrdinalLayout, OrdinalPipelineConfig } from "./ordinalTypes";
+export interface OrdinalValueDomainInput {
+    data: Datum[];
+    chartType: OrdinalPipelineConfig["chartType"];
+    projection?: OrdinalPipelineConfig["projection"];
+    normalize?: boolean;
+    rExtent?: OrdinalPipelineConfig["rExtent"];
+    extentPadding?: number;
+    baselinePadding?: boolean;
+    axisExtent?: OrdinalPipelineConfig["axisExtent"];
+    getO: (d: Datum) => string;
+    getR: (d: Datum) => number;
+    getStack?: (d: Datum) => string;
+    /** IncrementalExtent-style [min, max]; Infinity/-Infinity when empty. */
+    rawRExtent: [number, number];
+}
+/**
+ * Compute the ordinal value (r) domain from data + chart type rules.
+ * Pure: no store mutation; callers supply accessors and raw extent.
+ */
+export declare function computeOrdinalValueDomain(input: OrdinalValueDomainInput): [number, number];
+export interface BuildOrdinalColumnsInput {
+    data: Datum[];
+    oExtent: string[];
+    oScale: ScaleBand<string>;
+    projection: string;
+    layout: OrdinalLayout;
+    dynamicColumnWidth?: OrdinalPipelineConfig["dynamicColumnWidth"];
+    getO: (d: Datum) => string;
+    getR: (d: Datum) => number;
+}
+/** Project band scale + data into per-category column geometry. */
+export declare function buildOrdinalColumns(input: BuildOrdinalColumnsInput): Record<string, OrdinalColumn>;

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

@@ -0,0 +1,31 @@
+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;
+    recordConfig(keys: readonly string[]): UpdateResult;
+}
+export {};

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

@@ -0,0 +1,10 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { RingBuffer } from "../realtime/RingBuffer";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PulseConfig } from "./types";
+/**
+ * Apply pulse-derived fields to ordinal scene nodes without rebuilding their
+ * layout. Wedges aggregate their category's source data; other supported
+ * nodes map directly to one source datum.
+ */
+export declare function applyOrdinalPulse(pulse: PulseConfig, nodes: OrdinalSceneNode[], timestampBuffer: RingBuffer<number>, datumIndex: ReadonlyMap<Datum, number>, getCategoryIndices: (category: string) => number[] | undefined, now: number): boolean;

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

@@ -0,0 +1,3 @@
+import type { RingBuffer } from "../realtime/RingBuffer";
+/** Keep a pulse timestamp ring aligned with the retained ordinal data. */
+export declare function syncOrdinalPulseTimestampBuffer<T>(pulseEnabled: boolean, buffer: RingBuffer<T>, timestamps: RingBuffer<number> | null, timestamp: number): RingBuffer<number> | null;

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

@@ -0,0 +1,5 @@
+/**
+ * chartType → pure scene builder dispatch for OrdinalPipelineStore.
+ */
+import type { SceneBuilderFn } from "./types";
+export declare const ORDINAL_SCENE_BUILDERS: Record<string, SceneBuilderFn>;

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/ordinalSpatialIndex.d.ts

@@ -0,0 +1,9 @@
+import { type Quadtree } from "d3-quadtree";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PointSceneNode } from "./types";
+export interface OrdinalPointSpatialIndex {
+    readonly maxRadius: number;
+    readonly quadtree: Quadtree<PointSceneNode> | null;
+}
+/** Build the optional point-hit index for large ordinal point scenes. */
+export declare function buildOrdinalPointSpatialIndex(scene: readonly OrdinalSceneNode[]): OrdinalPointSpatialIndex;

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 } 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>;
@@ -54,6 +57,8 @@ export interface WedgeSceneNode {
     };
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -163,9 +168,9 @@ export interface TrapezoidSceneNode {
     _targetOpacity?: number;
     _transitionKey?: string;
 }
-export type { Style, PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
-import type { PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
-export type OrdinalSceneNode = RectSceneNode | PointSceneNode | SymbolSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
+export type { Style, PointSceneNode, RectSceneNode, SymbolSceneNode, GlyphSceneNode } from "./types";
+import type { PointSceneNode, RectSceneNode, SymbolSceneNode, GlyphSceneNode } from "./types";
+export type OrdinalSceneNode = RectSceneNode | PointSceneNode | SymbolSceneNode | GlyphSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
 export interface OrdinalColumn {
     name: string;
     x: number;
@@ -205,6 +210,13 @@ export interface OrdinalPipelineConfig {
     oAccessor?: string | ((d: Datum) => string);
     /** @deprecated Use valueAccessor */
     rAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
+    /**
+     * Escape hatch for a *stable* function accessor whose captured semantics
+     * change without its identity changing. Accessor equality is identity-based,
+     * so such a change is otherwise invisible. Bump this number to force the
+     * store to re-resolve accessors, rebuild the category domain, and reset value
+     * extents. Prefer changing the accessor identity where you can. */
+    accessorRevision?: number;
     multiAxis?: boolean;
     rExtent?: [number?, number?];
     oExtent?: string[];
@@ -254,7 +266,7 @@ export interface OrdinalPipelineConfig {
     dynamicColumnWidth?: string | ((data: Datum[]) => number);
     pieceStyle?: (d: Datum, category?: string) => Style;
     summaryStyle?: (d: Datum, category?: string) => Style;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     themeCategorical?: string[];
     /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
     themeSemantic?: ThemeSemanticColors;
@@ -271,10 +283,14 @@ 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. */
     customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
+    /** Called when `customLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved margin — passed through so OrdinalLayoutContext.dimensions.margin
@@ -304,6 +320,12 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     oAccessor?: string | ((d: T) => string);
     /** @deprecated Use valueAccessor instead */
     rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    /**
+     * Force category/value re-derivation when a stable accessor's external
+     * semantics changed without a new function identity. Prefer changing the
+     * accessor reference where possible.
+     */
+    accessorRevision?: number;
     multiAxis?: boolean;
     projection?: "vertical" | "horizontal" | "radial";
     size?: [number, number];
@@ -367,9 +389,11 @@ 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[];
+    colorScheme?: string | string[] | Record<string, string>;
     barColors?: Record<string, string>;
     showAxes?: boolean;
     showCategoryTicks?: boolean;
@@ -392,8 +416,17 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
-    customHoverBehavior?: (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;
@@ -416,8 +449,12 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */
     onCategoriesChange?: (categories: string[]) => void;
-    backgroundGraphics?: ReactNode;
-    foregroundGraphics?: ReactNode;
+    /** SVG behind the canvas. Function form receives `{ size, margin, scales }`
+     *  with the frame's resolved `{o, r, projection}` scales (null pre-layout). */
+    backgroundGraphics?: FrameGraphicsProp<OrdinalScales>;
+    /** SVG on top (in the overlay). Function form receives `{ size, margin, scales }`
+     *  with the frame's resolved `{o, r, projection}` scales (null pre-layout). */
+    foregroundGraphics?: FrameGraphicsProp<OrdinalScales>;
     title?: string | ReactNode;
     className?: string;
     background?: string;
@@ -438,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 */
@@ -450,6 +499,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
      *  `semiotic/recipes` for reference layouts (marimekko, parallel
      *  coordinates, bullet). */
     customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
+    /** Called when `customLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared selection projected into `OrdinalLayoutContext.selection`.
@@ -480,6 +531,14 @@ export interface StreamOrdinalFrameHandle<T = Datum> {
     clear(): void;
     getData(): T[];
     getScales(): OrdinalScales | null;
+    /** The most recent custom layout result — 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("./ordinalCustomLayout").OrdinalLayoutResult | 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 interface OrdinalLayout {
     width: number;

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

@@ -0,0 +1,31 @@
+/**
+ * Shared paint-gate helpers for Stream Frame render loops.
+ *
+ * Frames differ in scene types, but the decision "should this rAF clear and
+ * redraw the data canvas?" is the same shape everywhere: dirty/scene rebuild,
+ * transition, continuous animation, particles, live encodings.
+ */
+export interface DataPaintNeedsInput {
+    /** Prop/layout dirty or scene rebuilt this frame. */
+    dirtyOrRebuilt: boolean;
+    /** Transition animation is advancing. */
+    transitioning: boolean;
+    /** Layout animation tick (orbit, force step, etc.). */
+    animationTicked?: boolean;
+    /** Particles / continuous mode wants a frame. */
+    continuous?: boolean;
+    /** Pulse / decay / threshold / topology-diff encodings are live. */
+    liveEncoding?: boolean;
+    /** Family-specific force (rotation applied, zoom, etc.). */
+    forced?: boolean;
+}
+/**
+ * True when the data canvas should clear and redraw this frame.
+ * Interaction-only or annotation-only rAF retries should leave data alone.
+ */
+export declare function needsDataCanvasPaint(input: DataPaintNeedsInput): boolean;
+/**
+ * True when an interaction overlay canvas should clear/draw.
+ * Pass `hadContentLastFrame` so a hover-end still gets one clear.
+ */
+export declare function needsInteractionCanvasPaint(active: boolean, hadContentLastFrame: boolean): boolean;

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

@@ -0,0 +1,5 @@
+/** FIFO capacity-queue controller: stateful region service riding StreamPhysicsFrame's live heartbeat. */
+import type { PhysicsController } from "./PhysicsControllers";
+import type { CapacityQueueControllerOptions } from "./CapacityQueueTypes";
+/** FIFO region service with visit evidence, overflow staging, and live metrics. */
+export declare function createCapacityQueueController(options: CapacityQueueControllerOptions): PhysicsController;