semiotic 3.1.2 → 3.2.1

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

@@ -0,0 +1,43 @@
+/**
+ * OrdinalBrushOverlay — d3-brush SVG overlay for ordinal frames.
+ *
+ * Renders a transparent SVG positioned above the canvas. Brushes along the
+ * r-axis (value axis) only: horizontal projection → brushX, vertical → brushY.
+ *
+ * Key design decisions:
+ *   - Outer SVG has pointerEvents:"none", inner brush-g has "all", so
+ *     axes/legends rendered underneath remain clickable.
+ *   - d3-brush lifecycle (useEffect) depends on [width, height, isHorizontal]
+ *     only — NOT scales. Scales are read from a ref to avoid brush teardown
+ *     mid-drag (scales change every render due to new object identity).
+ *   - A separate useEffect repositions the brush when scales change (streaming).
+ *
+ * Consumed by: StreamOrdinalFrame (rendered when brush prop is set).
+ * Wired by: useOrdinalBrush hook in HOC charts.
+ */
+import * as React from "react";
+import type { OrdinalScales } from "./ordinalTypes";
+interface OrdinalBrushOverlayProps {
+    width: number;
+    height: number;
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: OrdinalScales | null;
+    onBrush: (extent: {
+        r: [number, number];
+    } | null) => void;
+}
+/**
+ * SVG brush overlay for ordinal frames.
+ * Brushes along the r-axis (value axis) only.
+ * In horizontal projection, r maps to x-pixels → uses brushX.
+ * In vertical projection, r maps to y-pixels → uses brushY.
+ */
+export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): React.JSX.Element;
+export {};

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

@@ -1,3 +1,19 @@
+/**
+ * OrdinalPipelineStore — stateful pipeline for ordinal chart data.
+ *
+ * Owns: data ingestion (RingBuffer), scale computation (o-band + r-linear),
+ * value domain logic (per-lane sums for swimlane, zero-inclusion for bars),
+ * and scene layout delegation to ordinalSceneBuilders/*.
+ *
+ * Key design decisions:
+ *   - Swimlane domain uses per-lane sums, not individual values, because
+ *     stacked bars within a lane must fit within the lane's total range.
+ *   - Zero-inclusion for bar/swimlane is skipped when explicit rExtent is
+ *     set (either end non-null), enabling zoom/brush without domain override.
+ *   - Scene builders are pure functions; this store coordinates them.
+ *
+ * Consumed by: StreamOrdinalFrame (sole consumer).
+ */
 import { type ScaleLinear } from "d3-scale";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset } from "./types";

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

@@ -16,9 +16,10 @@ interface OrdinalSVGOverlayProps {
     };
     scales: OrdinalScales | null;
     showAxes?: boolean;
+    showCategoryTicks?: boolean;
     oLabel?: string;
     rLabel?: string;
-    oFormat?: (d: string) => string;
+    oFormat?: (d: string, index?: number) => string;
     rFormat?: (d: number) => string;
     showGrid?: boolean;
     title?: string | ReactNode;

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

@@ -106,6 +106,8 @@ export declare class PipelineStore {
     /** Separate group→color map for resolveGroupColor (insertion-order based, never invalidates _colorMapCache) */
     private _groupColorMap;
     private _barCategoryCache;
+    /** Sorted bin boundary values from the last bar scene build (for data-driven brush snapping) */
+    private _binBoundaries;
     /** Cache stacked area cumulative sums to skip recalculation when buffer hasn't changed */
     private _stackExtentCache;
     /** Monotonic counter incremented on each ingest — used as part of cache keys */
@@ -119,6 +121,8 @@ export declare class PipelineStore {
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
+    /** True when the x accessor returns Date objects (auto-detected on first data ingestion) */
+    xIsDate: boolean;
     private _quadtree;
     private static readonly QUADTREE_THRESHOLD;
     constructor(config: PipelineConfig);
@@ -147,60 +151,14 @@ export declare class PipelineStore {
      */
     private remapScene;
     private buildSceneNodes;
-    private buildLineScene;
-    private buildAreaScene;
-    private buildStackedAreaScene;
-    private buildPointScene;
-    private buildHeatmapScene;
-    /**
-     * Streaming heatmap: discretize continuous x/y into a grid and aggregate.
-     */
-    private buildStreamingHeatmapScene;
-    private buildBarScene;
-    private buildSwarmScene;
-    private buildWaterfallScene;
-    private buildCandlestickScene;
-    private buildBoundsForGroup;
     private resolveBoundsStyle;
-    /**
-     * Compute decay opacity for a datum at `bufferIndex` out of `bufferSize` items.
-     * Index 0 = oldest, bufferSize-1 = newest. Returns 0–1.
-     */
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
-    /**
-     * Apply decay opacity to a list of discrete scene nodes.
-     * Uses the datum's index in the buffer data array.
-     */
     private applyDecay;
-    /**
-     * Compute pulse intensity for a datum inserted at `insertTime`.
-     * Returns 0–1 (1 = just inserted, 0 = pulse expired).
-     */
-    private computePulseIntensity;
-    /**
-     * Apply pulse glow to discrete scene nodes.
-     */
     private applyPulse;
-    /**
-     * Returns true if there are active pulse animations that need continuous rendering.
-     */
     get hasActivePulses(): boolean;
-    /**
-     * Snapshot current scene node positions before rebuild.
-     */
+    private get transitionContext();
     private snapshotPositions;
-    /**
-     * Get a stable identity key for a scene node.
-     */
-    private getNodeIdentity;
-    /**
-     * After scene rebuild, set up transition from old to new positions.
-     * Detects entering nodes (new, no prev match) and exiting nodes (prev, no new match).
-     */
     private startTransition;
-    /**
-     * Advance the transition animation. Returns true if still animating.
-     */
     advanceTransition(now: number): boolean;
     private groupData;
     /**
@@ -223,6 +181,8 @@ export declare class PipelineStore {
      */
     private getBufferArray;
     getData(): Record<string, any>[];
+    /** Returns sorted bin boundary values from the last bar scene build. Persists until clear() or the next bar scene build. */
+    getBinBoundaries(): number[];
     getExtents(): {
         x: [number, number];
         y: [number, number];

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

@@ -7,7 +7,7 @@ export interface AxisConfig {
     orient: "left" | "right" | "top" | "bottom";
     label?: string;
     ticks?: number;
-    tickFormat?: (d: any) => string;
+    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     baseline?: boolean | "under";
     jaggedBase?: boolean;
     /** Highlight ticks at time boundaries (new month, year, etc.) with semibold text.
@@ -30,7 +30,9 @@ interface SVGOverlayProps {
     axes?: AxisConfig[];
     xLabel?: string;
     yLabel?: string;
-    xFormat?: (d: any) => string;
+    /** Label for the right Y axis (dual-axis charts) */
+    yLabelRight?: string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     yFormat?: (d: any) => string;
     showGrid?: boolean;
     title?: string | ReactNode;
@@ -73,6 +75,10 @@ interface SVGOverlayProps {
     curve?: string;
     /** When true, grid lines and axis baselines are skipped (rendered by SVGUnderlay instead) */
     underlayRendered?: boolean;
+    /** Name of the linked crosshair store entry to read */
+    linkedCrosshairName?: string;
+    /** Source chart ID — crosshair line is suppressed on the source to avoid double rendering */
+    linkedCrosshairSourceId?: string;
     children?: ReactNode;
 }
 interface SVGUnderlayProps {
@@ -90,7 +96,7 @@ interface SVGUnderlayProps {
     showAxes?: boolean;
     axes?: AxisConfig[];
     showGrid?: boolean;
-    xFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     yFormat?: (d: any) => string;
 }
 export declare function SVGUnderlay(props: SVGUnderlayProps): React.JSX.Element | null;

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

@@ -1,10 +1,15 @@
 import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
 export declare function buildLineNode(data: Record<string, any>[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, style: Style, group?: string): LineSceneNode;
 export declare function buildAreaNode(data: Record<string, any>[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Record<string, any>) => number): AreaSceneNode;
+/** Per-group-per-x stacked top values, keyed by group then x */
+export type StackedTops = Map<string, Map<number, number>>;
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Record<string, any>[];
-}[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, styleFn: (group: string, sampleDatum?: Record<string, any>) => Style, normalize?: boolean, curve?: CurveType): AreaSceneNode[];
+}[], scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, styleFn: (group: string, sampleDatum?: Record<string, any>) => Style, normalize?: boolean, curve?: CurveType): {
+    nodes: AreaSceneNode[];
+    stackedTops: StackedTops;
+};
 export declare function buildPointNode(datum: Record<string, any>, scales: StreamScales, xGet: (d: Record<string, any>) => number, yGet: (d: Record<string, any>) => number, r: number, style: Style, pointId?: string): PointSceneNode | null;
 export declare function buildRectNode(x: number, y: number, w: number, h: number, style: Style, datum: any, group?: string): RectSceneNode;
 export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: any, options?: {

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

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

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

@@ -1,3 +1,17 @@
+/**
+ * Compare two accessor specs for equivalence.
+ * - Same reference: always equivalent (`===`)
+ * - String accessors: exact string match
+ * - Function accessors: `.toString()` comparison (catches inline arrow functions
+ *   like `d => d.value` that are recreated on every render but have identical source)
+ * - Mismatched types or undefined vs defined: not equivalent
+ *
+ * **Known limitation**: `.toString()` compares source text, not closure bindings.
+ * Two functions with identical source but different captured variables will appear
+ * equivalent. For closures that depend on changing values, use `useCallback` with
+ * the variable in the dependency array so the reference changes when behavior changes.
+ */
+export declare function accessorsEquivalent(a: string | ((...args: any[]) => any) | undefined, b: string | ((...args: any[]) => any) | undefined): boolean;
 export declare function resolveAccessor<T>(accessor: string | ((d: T) => number) | undefined, fallback: string): (d: T) => number;
 export declare function resolveRawAccessor<T>(accessor: string | ((d: T) => any) | undefined, fallback: string): (d: T) => any;
 export declare function resolveStringAccessor<T>(accessor: string | ((d: T) => string) | undefined, fallback?: string): ((d: T) => string) | undefined;

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

@@ -161,8 +161,12 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     showAxes?: boolean;
-    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    /** 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 */
+    description?: string;
+    /** Accessible summary rendered as a screen-reader-only note */
+    summary?: string;
 }
 export interface StreamGeoFrameHandle {
     push(datum: Record<string, any>): void;

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

@@ -1,36 +1,112 @@
 /**
  * Keyboard navigation utilities for Stream Frames.
  *
- * Extracts navigable data points from the scene graph, sorts them
- * spatially, and provides an index-based iteration API for arrow-key
- * navigation. Reuses the existing hover/tooltip system — keyboard
- * focus sets the same HoverData state that mouse hover does.
+ * Supports two navigation modes:
+ * - **Flat**: ArrowRight/Left and ArrowUp/Down both advance linearly (geo, simple charts)
+ * - **Graph**: ArrowRight/Left navigates within a series/group, ArrowUp/Down switches
+ *   between series/groups at a similar position (XY lines, stacked bars, networks)
+ *
+ * Reuses the existing hover/tooltip system — keyboard focus sets the same
+ * HoverData state that mouse hover does.
  */
 import type { HoverData } from "../realtime/types";
 export interface NavPoint {
     x: number;
     y: number;
     datum: any;
+    /** Shape hint for focus ring rendering */
+    shape?: "circle" | "rect" | "wedge";
+    /** Width of rect-shaped elements (bars, sankey nodes) */
+    w?: number;
+    /** Height of rect-shaped elements */
+    h?: number;
+    /** Group identifier for graph navigation (series name, category, node id) */
+    group?: string;
+    /** Index in NavGraph.flat — set by buildNavGraph for O(1) lookup */
+    _flatIndex?: number;
+    /** Index within its group — set by buildNavGraph for O(1) resolvePosition */
+    _groupIndex?: number;
+}
+/**
+ * A navigation graph that organizes NavPoints into groups (series/categories)
+ * and positions within each group, enabling 2D keyboard navigation.
+ *
+ * ArrowRight/Left = next/prev within the current group (e.g. along a line series)
+ * ArrowUp/Down = switch to the nearest point in an adjacent group (e.g. switch series)
+ */
+export interface NavGraph {
+    /** All points in flat order (for PageUp/Down, Home/End) */
+    flat: NavPoint[];
+    /** Group names in stable order */
+    groups: string[];
+    /** Points per group, in position order */
+    byGroup: Map<string, NavPoint[]>;
+    /** Precomputed node id → flat index lookup (for network navigation) */
+    idToIdx: Map<string, number>;
 }
+export interface NavPosition {
+    /** Index into NavGraph.flat */
+    flatIndex: number;
+    /** Current group name */
+    group: string;
+    /** Index within the current group */
+    indexInGroup: number;
+}
+/**
+ * Build a navigation graph from grouped NavPoints.
+ * Points within each group are sorted by x then y.
+ * Groups are sorted by their first-point y position (top to bottom).
+ */
+export declare function buildNavGraph(points: NavPoint[]): NavGraph;
+/**
+ * Resolve the current NavPosition from a flat index.
+ * Clamps to valid range if the index is stale (e.g. scene changed between key presses).
+ */
+export declare function resolvePosition(graph: NavGraph, flatIndex: number): NavPosition;
+/**
+ * Compute the next navigation position given a key press and current position.
+ * Returns the flat index into graph.flat, -1 to clear, or null for unhandled keys.
+ */
+export declare function nextGraphIndex(key: string, pos: NavPosition, graph: NavGraph): number | null;
 /**
  * Extract navigable data points from XY scene nodes.
- * Points/rects yield one point each. Lines/areas yield their path points
- * paired with the underlying data. Sorted left-to-right by x.
+ * Lines/areas carry a `group` field identifying the series.
+ * ArrowRight/Left = within series, ArrowUp/Down = switch series.
  */
 export declare function extractXYNavPoints(scene: any[]): NavPoint[];
 /**
  * Extract navigable points from ordinal scene nodes.
- * Sorted left-to-right (horizontal) or top-to-bottom (vertical).
+ * Bars use `node.group` (stack/group key) falling back to `datum.category`.
+ * ArrowRight/Left = across categories, ArrowUp/Down = within stacked segments.
  */
 export declare function extractOrdinalNavPoints(scene: any[]): NavPoint[];
 /**
  * Extract navigable points from network scene nodes.
- * Node-only (edges are not individually navigable).
+ * Each node's group is its own id, enabling neighbor traversal via edges.
  */
 export declare function extractNetworkNavPoints(scene: any[]): NavPoint[];
+/**
+ * Network-specific navigation: spatial arrow keys + edge following.
+ *
+ * ArrowRight/Left/Up/Down: move to the nearest node in that direction.
+ * Enter: follow an edge to a connected neighbor of the current node.
+ * PageUp/Down, Home/End, Escape: flat navigation.
+ *
+ * Returns the flat index of the target node, -1 to clear, or null for unhandled keys.
+ */
+export declare function nextNetworkIndex(key: string, pos: NavPosition, graph: NavGraph, edges: any[], neighborIndexRef: {
+    current: number;
+}): number | null;
+/**
+ * Extract navigable points from geo scene nodes.
+ * Flat navigation only (no meaningful grouping for geo).
+ */
+export declare function extractGeoNavPoints(scene: any[]): NavPoint[];
 /**
  * Compute the next focus index given a key and current index.
- * Returns -1 to clear focus.
+ * Returns -1 to clear focus. Returns null for unhandled keys.
+ *
+ * Used by Geo frame (flat navigation) and as fallback.
  */
 export declare function nextIndex(key: string, current: number, total: number): number | null;
 /**

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

@@ -0,0 +1,35 @@
+/**
+ * Scene builders for hierarchy layouts (tree, treemap, circlepack).
+ *
+ * Converts RealtimeNode/Edge arrays (positioned by d3-hierarchy) into
+ * NetworkSceneNode/Edge arrays for canvas rendering.
+ *
+ * Three builder functions, one per visual form:
+ *   buildTreeScene    — circle nodes + curved edges (tree/cluster)
+ *   buildRectScene    — rect nodes, no edges (treemap/partition)
+ *   buildCircleScene  — circle nodes, no edges (circlepack)
+ *
+ * Dependencies: hierarchyUtils (palette, contrast, label resolution)
+ * Consumed by: hierarchyLayoutPlugin.ts (buildScene dispatcher)
+ */
+import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge } from "../networkTypes";
+export declare function buildTreeScene(nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>, edgeStyleFn: (d: any) => Record<string, any>): {
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    labels: NetworkLabel[];
+};
+export declare function buildRectScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>): {
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    labels: NetworkLabel[];
+};
+export declare function buildCircleScene(nodes: RealtimeNode[], config: NetworkPipelineConfig, size: [number, number], nodeStyleFn: (d: any) => Record<string, any>): {
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    labels: NetworkLabel[];
+};
+/**
+ * Generate a cubic bezier path string for a tree/cluster edge.
+ * Uses different curve strategies based on tree orientation.
+ */
+export declare function generateTreeEdgePath(sx: number, sy: number, tx: number, ty: number, orientation: string): string;

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

@@ -0,0 +1,25 @@
+/**
+ * Shared utilities for hierarchy layout plugins.
+ *
+ * CSS color parsing, contrast text, depth palette, and accessor resolution
+ * used across tree, treemap, and circlepack scene builders.
+ *
+ * Consumed by: hierarchyLayoutPlugin.ts, hierarchySceneBuilders.ts
+ */
+import type { NetworkPipelineConfig } from "../networkTypes";
+/** Depth-based color palette shared across all hierarchy scene builders */
+export declare const DEPTH_PALETTE: string[];
+/**
+ * Parse a CSS color string (hex or rgb/rgba) into [r, g, b].
+ * Falls back to mid-gray if the format is unrecognized.
+ */
+export declare function parseColor(color: string): [number, number, number];
+/**
+ * Return a high-contrast text color (white or near-black) for the given background.
+ * Uses perceived luminance (ITU-R BT.601).
+ */
+export declare function contrastTextColor(bgColor: string): string;
+export declare function resolveChildrenAccessor(accessor: string | ((d: any) => any[]) | undefined): ((d: any) => any[]) | undefined;
+export declare function resolveNodeId(d: any, config: NetworkPipelineConfig, index: number): string;
+export declare function resolveLabelFn(nodeLabel: string | ((d: any) => string) | undefined): ((d: any) => string) | null;
+export declare function resolveDefaultNodeSize(nodeSize: number | string | ((d: any) => number) | undefined): number;

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

@@ -54,6 +54,8 @@ export interface RealtimeEdge {
     circularPathData?: any;
     bezier?: BezierCache;
     data?: Record<string, any>;
+    /** Unique key for this edge (supports parallel edges between same node pair) */
+    _edgeKey?: string;
 }
 export interface BezierPoint {
     x: number;
@@ -438,8 +440,12 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     orbitEccentricity?: number | ((node: any) => number);
     orbitShowRings?: boolean;
     orbitAnimated?: boolean;
-    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    /** 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 */
+    description?: string;
+    /** Accessible summary rendered as a screen-reader-only note */
+    summary?: string;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;

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

@@ -0,0 +1,27 @@
+import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
+import type { OrdinalSceneContext } from "./types";
+/**
+ * Bar-funnel scene builder (vertical orientation).
+ *
+ * Renders funnel data as vertical bars — one per step on the x-axis.
+ * Each bar is stacked: solid bottom = retained value, hatched top = dropoff
+ * from the previous step. The first step has no dropoff (100% solid).
+ *
+ * Multi-category: bars are grouped side-by-side within each step,
+ * each with its own retained + dropoff stack.
+ *
+ * The rScale (y-axis) is set by the pipeline based on the data's max value.
+ * Bars are sized proportionally via scales.r so the first step fills the
+ * available height and subsequent steps shrink relative to it.
+ *
+ * Metadata on each rect datum (used by barFunnelLabelRenderer):
+ *  - __barFunnelValue: numeric value for this bar
+ *  - __barFunnelPercent: percent of this category's first-step value
+ *  - __barFunnelIsFirstStep: true for step index 0
+ *  - __barFunnelIsDropoff: true for the dropoff portion (hatched)
+ *  - __barFunnelStep: step name
+ *  - __barFunnelDropoffValue: the dropoff amount
+ *  - __barFunnelCategory: category key (for multi-category)
+ *  - __barFunnelLabelX/Y: position for the floating label
+ */
+export declare function buildBarFunnelScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -0,0 +1,26 @@
+import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
+import type { OrdinalSceneContext } from "./types";
+/**
+ * Funnel scene builder.
+ *
+ * Steps run top-to-bottom. Each step is a horizontal row whose bar width is
+ * proportional to its value. Multiple categories mirror around the center axis:
+ * with 2 categories, one extends right and the other extends left.
+ *
+ * Produces:
+ *  - RectSceneNode for each bar (step × category)
+ *  - TrapezoidSceneNode for each connector between consecutive steps
+ *
+ * Label metadata on each rect datum (used by funnelLabelRenderer):
+ *  - __funnelStepLabel: step name (only on first category rect per row)
+ *  - __funnelValue: numeric value for this bar
+ *  - __funnelPercent: percent of this category's first-step value
+ *  - __funnelIsFirstStep: true for step index 0 (suppresses "100%")
+ *  - __funnelStepLabelX/Y: center position for step name
+ *  - __funnelValueLabelX/Y: center position for value label
+ *  - __funnelBarW: pixel width of this bar (for min-size suppression)
+ *
+ * NOTE: FunnelChart HOC uses projection="horizontal" so the ordinal band
+ * scale maps to layout.height (y-axis). col.x = y-position, col.width = band height.
+ */
+export declare function buildFunnelScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];

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

@@ -0,0 +1,12 @@
+import type { OrdinalSceneNode, OrdinalLayout } from "../ordinalTypes";
+import type { OrdinalSceneContext } from "./types";
+/**
+ * Swimlane scene builder.
+ *
+ * Each category (oAccessor) defines a horizontal lane.
+ * Items within a lane are stacked left-to-right (or bottom-to-top in vertical),
+ * colored by subcategory (stackBy/colorBy). Unlike a standard stacked bar,
+ * multiple items with the same subcategory can appear in the same lane —
+ * they simply stack sequentially.
+ */
+export declare function buildSwimlaneScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): OrdinalSceneNode[];