semiotic 3.7.4 → 3.8.0

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

@@ -2,10 +2,12 @@ import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
 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 } 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";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -51,6 +53,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,7 +185,7 @@ export interface RealtimeNetworkFrameProps {
     showParticles?: boolean;
     particleStyle?: ParticleStyle;
     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);
@@ -204,6 +208,8 @@ export interface NetworkCircleNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -220,6 +226,8 @@ export interface NetworkRectNode {
     h: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -241,12 +249,82 @@ export interface NetworkArcNode {
     endAngle: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
     _pulseGlowRadius?: number;
 }
+/**
+ * Symbol node — a glyph rendered from a `d3-shape` symbol path (or a custom
+ * path). The per-datum shape channel: recipes that encode a categorical field
+ * as marker shape (e.g. `packedClusterMatrix`) emit these. Hit-tests as a
+ * circle of the symbol's effective radius; renders on canvas and in SVG/SSR.
+ */
+export interface NetworkSymbolNode {
+    type: "symbol";
+    cx: number;
+    cy: number;
+    /** d3-symbol area in px² — drives the glyph's drawn size. */
+    size: number;
+    /** Named shape. Ignored when `path` is set. @default "circle" */
+    symbolType?: NetworkSymbolName;
+    /** Pre-built SVG path string, origin-centered — overrides `symbolType`. */
+    path?: 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;
+    _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;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}
 /** Line edge — used by force */
 export interface NetworkLineEdge {
     type: "line";
@@ -305,7 +383,7 @@ export interface NetworkCurvedEdge {
     _cachedPath2D?: Path2D;
     _cachedPath2DSource?: string;
 }
-export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode;
+export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode | NetworkGlyphNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
 /** Label data for the SVG overlay */
 export interface NetworkLabel {
@@ -382,6 +460,8 @@ export interface NetworkPipelineConfig {
     edgeSort?: (a: unknown, b: unknown) => number;
     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;
@@ -398,7 +478,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. */
@@ -451,6 +531,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
@@ -480,6 +562,12 @@ 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;
@@ -494,7 +582,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;
@@ -569,6 +657,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
@@ -600,5 +690,14 @@ export interface StreamNetworkFrameHandle {
     };
     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 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 } from "./ordinalTypes";
+export type OrdinalAnyRendererFn = (ctx: CanvasRenderingContext2D, nodes: any[], scales: any, layout: any) => void;
+export declare const ORDINAL_CANVAS_RENDERERS: Record<OrdinalChartType, OrdinalAnyRendererFn[]>;

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

@@ -3,7 +3,8 @@ import type { ScaleBand, ScaleLinear } from "d3-scale";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { MarginType } from "../types/marginType";
 import type { OrdinalSceneNode, OrdinalScales } from "./ordinalTypes";
-import type { ThemeSemanticColors } from "./types";
+import type { Style, ThemeSemanticColors } from "./types";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 /**
  * customLayout escape hatch for `StreamOrdinalFrame`.
  *
@@ -75,10 +76,25 @@ export interface OrdinalLayoutContext<C extends object = Record<string, unknown>
     resolveColor: (key: string) => string;
     /** User-supplied config blob threaded through `layoutConfig`. */
     config: C;
+    /**
+     * Shared-selection projection (from `selection` / `linkedHover`). `null` when
+     * unwired. For selection-driven styling without a relayout, use
+     * {@link OrdinalLayoutResult.restyle} (canvas) / `useCustomLayoutSelection`
+     * (overlays) rather than recomputing geometry here.
+     */
+    selection?: CustomLayoutSelection | null;
 }
 export interface OrdinalLayoutResult {
     /** Scene nodes to render. Get hit testing, transitions, decay, SSR for free. */
     nodes?: OrdinalSceneNode[];
     /** SVG overlays composited above the canvas (labels, axis lines, annotations). */
     overlays?: ReactNode;
+    /**
+     * **Per-frame restyle of canvas marks, without re-positioning.** When present,
+     * a selection/hover change re-applies styles to the existing scene nodes +
+     * repaints — no relayout, no quadtree rebuild. Return a style patch merged onto
+     * the node's *base* style. Providing it opts into the cheap selection path.
+     * Pairs with `useCustomLayoutSelection` for the `overlays`.
+     */
+    restyle?: (node: OrdinalSceneNode, selection: CustomLayoutSelection | null) => Partial<Style> | void;
 }

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,12 @@
+import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+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;
+    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

@@ -10,6 +10,8 @@ export interface OrdinalSceneContext {
     getStack?: (d: Datum) => string;
     getGroup?: (d: Datum) => string;
     getColor?: (d: Datum) => string;
+    /** Categorical accessor → glyph shape (swarm/dot symbolBy). */
+    getSymbol?: (d: Datum) => string;
     getConnector?: (d: Datum) => string;
     getO: (d: Datum) => string;
     multiScales: ScaleLinear<number, number>[];

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

@@ -2,7 +2,8 @@ import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
-import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
+import type { SymbolName } from "./symbolPath";
+import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
@@ -53,6 +54,8 @@ export interface WedgeSceneNode {
     };
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -162,9 +165,9 @@ export interface TrapezoidSceneNode {
     _targetOpacity?: number;
     _transitionKey?: string;
 }
-export type { Style, PointSceneNode, RectSceneNode } from "./types";
-import type { PointSceneNode, RectSceneNode } from "./types";
-export type OrdinalSceneNode = RectSceneNode | PointSceneNode | 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;
@@ -193,6 +196,10 @@ export interface OrdinalPipelineConfig {
     categoryAccessor?: string | ((d: Datum) => string);
     valueAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
     colorAccessor?: string | ((d: Datum) => string);
+    /** Categorical accessor → glyph shape (swarm/dot). Emits SymbolSceneNodes. */
+    symbolAccessor?: string | ((d: Datum) => string);
+    /** Explicit `{category → shape}` map; unmapped categories auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     stackBy?: string | ((d: Datum) => string);
     groupBy?: string | ((d: Datum) => string);
     timeAccessor?: string | ((d: Datum) => number);
@@ -200,6 +207,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[];
@@ -249,7 +263,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;
@@ -270,11 +284,16 @@ export interface OrdinalPipelineConfig {
      *  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
      *  reflects what the frame actually used. */
     layoutMargin?: import("../types/marginType").MarginType;
+    /** Resolved shared selection projected into OrdinalLayoutContext.selection.
+     *  Owned by a dedicated frame effect (kept off the rebuild path). */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamOrdinalFrameProps<T = Datum> {
     chartType: OrdinalChartType;
@@ -285,6 +304,10 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     /** Value field — the quantitative dimension (replaces rAccessor). Can be array for multiAxis. */
     valueAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
     colorAccessor?: string | ((d: T) => string);
+    /** Categorical accessor → glyph shape (swarm/dot). */
+    symbolAccessor?: string | ((d: T) => string);
+    /** Explicit `{category → shape}` map for `symbolAccessor`; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     stackBy?: string | ((d: T) => string);
     groupBy?: string | ((d: T) => string);
     timeAccessor?: string | ((d: T) => number);
@@ -292,6 +315,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];
@@ -357,7 +386,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
     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;
@@ -381,6 +410,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
     customHoverBehavior?: (d: HoverData | null) => void;
+    customClickBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
@@ -404,8 +434,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,8 +472,14 @@ 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`.
+     *  Kept off the rebuild path — restyles (if the layout returned `restyle`) or
+     *  rebuilds, never re-ingests. */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamOrdinalFrameHandle<T = Datum> {
     push(datum: T): void;
@@ -464,6 +504,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;