semiotic 3.5.2 → 3.5.4

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
-import type { LegendGroup } from "../types/legendTypes";
+import type { LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
@@ -262,9 +262,20 @@ export interface NetworkLineEdge {
 export interface NetworkBezierEdge {
     type: "bezier";
     pathD: string;
+    /** When false, the hit tester skips this edge. Used for
+     *  decorative scene-edges like ProcessSankey's gradient stubs —
+     *  they paint visually but shouldn't intercept hover. */
+    interactive?: boolean;
     bezierCache?: BezierCache;
     style: Style;
     datum: SceneDatum;
+    /** Internal gradient used by circular sankey stub bands. */
+    _gradient?: {
+        x0: number;
+        x1: number;
+        from: number;
+        to: number;
+    };
     _pulseIntensity?: number;
     _pulseColor?: string;
     /** Lazily-built Path2D for hit testing; invalidated when pathD changes. */
@@ -512,6 +523,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
         legendGroups: LegendGroup[];
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

@@ -3,7 +3,7 @@ import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { LegendGroup } from "../types/legendTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane" | "custom";
 export interface OrdinalScales {
@@ -21,8 +21,35 @@ export interface WedgeSceneNode {
     startAngle: number;
     /** End angle in radians, canvas convention */
     endAngle: number;
-    /** Corner radius for rounded wedge arcs (d3-shape arc.cornerRadius) */
+    /** Corner radius for rounded wedge arcs (d3-shape arc.cornerRadius).
+     *  When set on its own, rounds ALL FOUR corners (the d3-shape default).
+     *  Pair with `roundedEnds` to round only the gauge's outer endpoints —
+     *  the swimlane analogue for radial sectors: first wedge's start side
+     *  + last wedge's end side rounded, internal zone seams stay square. */
     cornerRadius?: number;
+    /** Selective per-end rounding. When omitted, `cornerRadius` rounds all
+     *  four corners. When provided, `cornerRadius` rounds ONLY the sides
+     *  marked `true` — `{ start: true }` rounds the wedge's startAngle
+     *  side (both inner and outer corners at that angle), `{ end: true }`
+     *  rounds the endAngle side. The gauge scene builder uses this to
+     *  paint outer endpoints rounded but internal zone seams square. */
+    roundedEnds?: {
+        start?: boolean;
+        end?: boolean;
+    };
+    /** Render the wedge's interior as N equal angular slices, each filled
+     *  with the corresponding color from `colors`. The wedge's own shape
+     *  (incl. `cornerRadius` + `roundedEnds`) is used as a clip mask so
+     *  only the slice geometry shows through the rounded outline. Used by
+     *  GaugeChart's gradient-fill mode: the band reads as one continuous
+     *  rounded arc with a gradient sampled along its length, without any
+     *  individual slice (which would be far too narrow to host its own
+     *  rounded corners) needing to round. Slices are an internal
+     *  rendering detail — they do not appear as separate scene nodes,
+     *  participate in hit testing, or transition independently. */
+    _gradientBand?: {
+        colors: string[];
+    };
     style: Style;
     datum: SceneDatum;
     category?: string;
@@ -359,7 +386,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
     } | {
-        gradient: import("../types/legendTypes").GradientLegendConfig;
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -370,6 +397,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** Accessor used to report the current legend category domain in push mode. */
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */

package/dist/components/stream/renderers/wedgePathBuilder.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Annular sector path builder with selective per-end corner rounding.
+ *
+ * d3-shape's `arc().cornerRadius()` rounds ALL FOUR corners of an
+ * annular sector uniformly — there's no built-in per-corner control.
+ * For gauges with multiple zones we want the gauge's OUTER endpoints
+ * rounded (the swimlane convention applied radially) but internal zone
+ * seams to stay square. This helper builds the path manually so each
+ * end can be opted in independently.
+ *
+ * The geometry mirrors d3's algorithm: a corner circle of radius `cr`
+ * is inscribed tangent to both walls (the outer/inner arc and the
+ * radial line at the relevant angle). The angular setback from the
+ * radial line is `asin(cr / (R ± cr))` — `R - cr` for outer corners
+ * (corner centers sit `cr` inward of the outer arc), `R + cr` for
+ * inner corners.
+ *
+ * Returned shape is an SVG path `d` attribute, equivalently consumable
+ * by Path2D in canvas. Coordinates are wedge-local (centered at
+ * origin); the renderer translates to `(cx, cy)`.
+ *
+ * Inputs use the **canvas angle convention** (0 = 3 o'clock, positive
+ * clockwise) — same as `WedgeSceneNode.startAngle/endAngle`. d3-shape
+ * uses 0 = 12 o'clock, so callers that pre-rotated by `+π/2` to call
+ * d3-arc should NOT pre-rotate when calling this helper.
+ */
+export interface AnnularPathOptions {
+    innerRadius: number;
+    outerRadius: number;
+    startAngle: number;
+    endAngle: number;
+    cornerRadius?: number;
+    /** Round the side at startAngle (both inner + outer corners there). */
+    roundStart?: boolean;
+    /** Round the side at endAngle (both inner + outer corners there). */
+    roundEnd?: boolean;
+}
+/**
+ * Build the SVG path for an annular sector with per-end rounding.
+ *
+ * When `cornerRadius` is 0 or unset, OR neither `roundStart` nor
+ * `roundEnd` is true, the result is a plain unrounded sector — same
+ * shape `drawWedgeManual` would emit. When both ends are rounded with
+ * a single cornerRadius value, the output matches what d3-arc would
+ * produce. The novel case is mixed rounding: e.g. `roundStart: true,
+ * roundEnd: false` rounds only the gauge's leading edge.
+ *
+ * Defensive clamps:
+ *   - `cornerRadius` is clamped to `(outerRadius - innerRadius) / 2`
+ *     so the corner circles can't cross the ring's centerline (which
+ *     would invert the inner radial line).
+ *   - If the angular sweep is too small to fit two corner radii
+ *     end-to-end on the requested side, that side falls back to
+ *     unrounded so the path stays well-formed.
+ */
+export declare function annularSectorPath(opts: AnnularPathOptions): string;
+/**
+ * Build the clip outline + slice paths for a gauge gradient band.
+ *
+ * The band is rendered as one rounded annular sector used as a clip
+ * mask, with N unrounded slice sectors painted inside. Each slice
+ * extends from its own start angle out to the band's full end angle,
+ * so adjacent colors overpaint each other's trailing edge — eliminates
+ * subpixel AA gaps between slices without an explicit overlap epsilon
+ * and means the staircase reveals one color per `sliceAngle` of arc.
+ *
+ * Canvas and SVG renderers both consume this: canvas builds Path2D
+ * objects from the strings, SVG drops them straight into `<path d="…"/>`.
+ */
+export interface GaugeGradientGeometryOptions {
+    innerRadius: number;
+    outerRadius: number;
+    startAngle: number;
+    endAngle: number;
+    cornerRadius?: number;
+    roundStart?: boolean;
+    roundEnd?: boolean;
+    colors: string[];
+}
+export interface GaugeGradientGeometry {
+    clipPath: string;
+    slices: {
+        d: string;
+        color: string;
+    }[];
+}
+export declare function buildGaugeGradientGeometry(opts: GaugeGradientGeometryOptions): GaugeGradientGeometry;

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

@@ -1,9 +1,10 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { CoercibleNumber } from "./accessorUtils";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
 export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
@@ -89,6 +90,10 @@ export interface Style {
     icon?: HTMLImageElement | HTMLCanvasElement;
     /** Padding between stamped icons */
     iconPadding?: number;
+    /** Optional radius when style callbacks drive point size directly. */
+    r?: number;
+    /** Internal geo line flag: fade line ends at projection clipping edges. */
+    _edgeFade?: boolean;
 }
 export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
@@ -369,6 +374,86 @@ export interface StreamLayout {
     height: number;
 }
 export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom" | "natural";
+/**
+ * Asymmetric min/max envelope drawn under lines/areas. Data-driven cousin
+ * of `boundsAccessor` (which takes a single symmetric ±offset). Use for
+ * throughput min/max ribbons, percentile bands (p5–p95), SLO ranges, and
+ * fan charts (pass an array of bands).
+ *
+ * Painted with the parent series color at 0.2 fillOpacity by default.
+ * Override with `style`. Non-interactive by default; participates in
+ * y-extent auto-derivation so it can't clip.
+ */
+export interface BandConfig<T = Datum> {
+    /** Bottom of the band — field name or accessor function. */
+    y0Accessor: string | ((d: T) => number);
+    /** Top of the band — field name or accessor function. */
+    y1Accessor: string | ((d: T) => number);
+    /**
+     * Style override. Defaults to the parent line/area color at 0.2
+     * fillOpacity, matching the `boundsStyle` cascade.
+     */
+    style?: Style | ((d: T, group?: string) => Style);
+    /**
+     * When the parent chart groups by `lineBy` / `colorBy`:
+     * - `true` (default): one band per group, colored to match the line
+     * - `false`: a single band drawn across the whole dataset (e.g. an
+     *   aggregate min/max across all series)
+     */
+    perSeries?: boolean;
+    /**
+     * Whether the band area participates in hit testing. Defaults to
+     * `false` — the band is decorative; hover/click pass through to the
+     * line on top. Independent of the `datum.band` enrichment, which
+     * happens whenever a band is configured.
+     */
+    interactive?: boolean;
+}
+/**
+ * Per-axis configuration object for an XY frame's `axes: []` array.
+ * Distinct from `AxisConfig` exported from the HOC layer (which is the
+ * chart-level `xLabel` / `yLabel` / `xFormat` / `yFormat` bundle) —
+ * this type describes one axis at a time and is what
+ * `frameProps.axes[i]` consumes.
+ *
+ * Re-exported under the legacy name `AxisConfig` from `SVGOverlay.tsx`
+ * for backwards-compatibility with internal callers; new code should
+ * import this name directly.
+ */
+export interface XYFrameAxisConfig {
+    orient: "left" | "right" | "top" | "bottom";
+    label?: string;
+    ticks?: number;
+    /** Per-axis tick label formatter. ReactNode return is supported and
+     *  renders inside a `<foreignObject>`. */
+    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
+    baseline?: boolean | "under";
+    jaggedBase?: boolean;
+    /** Explicit tick values. When provided, bypasses both d3's "nice"
+     *  generator and `axisExtent: "exact"` — the caller has hand-picked
+     *  the positions. Pixel-distance filtering downstream still drops
+     *  overlapping labels. Mirrors the ordinal frame's `rTickValues`. */
+    tickValues?: Array<number | Date>;
+    /** Grid line stroke style: `"dashed"` (6,4), `"dotted"` (2,4), or a
+     *  custom strokeDasharray string. Applied to grid lines extending
+     *  from ticks across the chart area. */
+    gridStyle?: "dashed" | "dotted" | string;
+    /** Always include the domain max as a tick, even if d3 omits it. */
+    includeMax?: boolean;
+    /** Auto-rotate labels 45° when horizontal spacing is too tight. */
+    autoRotate?: boolean;
+    /** Highlight ticks at time boundaries (new month, year, etc.) with
+     *  semibold text. `true` auto-detects Date boundaries. A function
+     *  receives (value, index) and returns true for landmark ticks. */
+    landmarkTicks?: boolean | ((value: any, index: number) => boolean);
+    /** Tick label anchoring strategy:
+     *  - `"middle"` (default): all tick labels centered on the tick mark
+     *  - `"edges"`: first tick label anchors to start, last to end,
+     *    middles stay centered. Pairs naturally with `axisExtent: "exact"`
+     *    — pins the domain to the data min/max AND keeps the extreme
+     *    labels from overflowing the plot. */
+    tickAnchor?: "middle" | "edges";
+}
 export interface StreamXYFrameProps<T = Datum> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
@@ -377,10 +462,10 @@ export interface StreamXYFrameProps<T = Datum> {
     chunkThreshold?: number;
     /** Number of items per progressive chunk (default 5000) */
     chunkSize?: number;
-    xAccessor?: string | ((d: T) => number);
-    yAccessor?: string | ((d: T) => number);
+    xAccessor?: string | ((d: T) => CoercibleNumber);
+    yAccessor?: string | ((d: T) => CoercibleNumber);
     colorAccessor?: string | ((d: T) => string);
-    sizeAccessor?: string | ((d: T) => number);
+    sizeAccessor?: string | ((d: T) => CoercibleNumber);
     groupAccessor?: string | ((d: T) => string);
     lineDataAccessor?: string;
     curve?: CurveType;
@@ -445,6 +530,19 @@ export interface StreamXYFrameProps<T = Datum> {
      * If omitted, defaults to the line color at 0.2 opacity.
      */
     boundsStyle?: Style | ((d: T, group?: string) => Style);
+    /**
+     * Asymmetric min/max band(s) drawn under the line/area. Differs from
+     * `boundsAccessor` (which is a symmetric ±offset) and from `y0Accessor`
+     * (which replaces the area baseline). A band is a decorative envelope
+     * — painted under the lines, above the grid, non-interactive by default
+     * — driven by per-point `y0`/`y1` accessors.
+     *
+     * Pass an array for multi-band fan charts (e.g. p25/p75 inside p10/p90).
+     * Outer bands first; inner bands stack on top.
+     *
+     * Participates in y-extent auto-derivation when `yExtent` is not pinned.
+     */
+    band?: BandConfig<T> | Array<BandConfig<T>>;
     openAccessor?: string | ((d: T) => number);
     highAccessor?: string | ((d: T) => number);
     lowAccessor?: string | ((d: T) => number);
@@ -488,18 +586,13 @@ export interface StreamXYFrameProps<T = Datum> {
     barColors?: Record<string, string>;
     colorScheme?: string | string[];
     showAxes?: boolean;
-    axes?: Array<{
-        orient: "left" | "right" | "top" | "bottom";
-        label?: string;
-        ticks?: number;
-        /** Explicit tick values. When provided, bypasses both d3's nice-tick
-         *  generator and `axisExtent`; pixel-distance filtering still drops
-         *  overlapping labels. Mirrors the ordinal frame's `rTickValues`. */
-        tickValues?: Array<number | Date>;
-        tickFormat?: AxisTickFormat;
-        baseline?: boolean | "under";
-        jaggedBase?: boolean;
-    }>;
+    /**
+     * Per-axis config array. See `XYFrameAxisConfig` for the full set of
+     * fields — covers `tickValues`, `tickFormat`, `tickAnchor`,
+     * `landmarkTicks`, `autoRotate`, `gridStyle`, `includeMax`,
+     * `baseline`, `jaggedBase`, `label`, and `ticks`.
+     */
+    axes?: XYFrameAxisConfig[];
     xLabel?: string;
     yLabel?: string;
     /** Label for the right Y axis (dual-axis charts) */
@@ -558,6 +651,7 @@ export interface StreamXYFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** Accessor used to report the current legend category domain in push mode. */
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */

package/dist/components/stream/xySceneBuilders/areaGradient.d.ts

@@ -0,0 +1,20 @@
+import type { AreaSceneNode } from "../types";
+type ResolvedAreaGradient = NonNullable<AreaSceneNode["fillGradient"]>;
+type OpacityGradient = {
+    topOpacity: number;
+    bottomOpacity: number;
+};
+type ColorStopGradient = {
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+};
+type OpacityGradientConfig = {
+    topOpacity?: number;
+    bottomOpacity?: number;
+};
+export type AreaGradientConfig = boolean | OpacityGradientConfig | ColorStopGradient;
+export declare const DEFAULT_AREA_GRADIENT: OpacityGradient;
+export declare function resolveAreaGradient(gradient: AreaGradientConfig | undefined): ResolvedAreaGradient | undefined;
+export {};

package/dist/components/stream/xySceneBuilders/barScene.d.ts

@@ -9,10 +9,10 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: BinAccumulator (computeBins), SceneGraph (buildRectNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "bar")
  */
-import type { SceneNode } from "../types";
+import type { RectSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
 export interface BarSceneResult {
-    nodes: SceneNode[];
+    nodes: RectSceneNode[];
     /** Sorted bin boundary values (edges of all bins) for data-driven brush snapping */
     binBoundaries: number[];
 }

package/dist/components/stream/xySceneBuilders/candlestickScene.d.ts

@@ -6,6 +6,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  *
  * Consumed by: PipelineStore.buildSceneNodes (chartType "candlestick")
  */
-import type { SceneNode, StreamLayout } from "../types";
+import type { CandlestickSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): SceneNode[];
+export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): CandlestickSceneNode[];

package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts

@@ -1,4 +1,4 @@
 import type { Datum } from "../../charts/shared/datumTypes";
-import type { SceneNode, StreamLayout } from "../types";
+import type { HeatcellSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];
+export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): HeatcellSceneNode[];

package/dist/components/stream/xySceneBuilders/lineScene.d.ts

@@ -2,10 +2,11 @@ import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Line scene builder — produces LineSceneNode[] from grouped data.
  *
- * Handles: color thresholds from annotations, bounds/envelope areas,
- * and curve type attachment for canvas interpolation.
+ * Handles: color thresholds from annotations, ribbon envelopes
+ * (boundsAccessor + band), and curve type attachment for canvas
+ * interpolation.
  *
- * Dependencies: SceneGraph (buildLineNode), boundsScene (buildBoundsForGroup)
+ * Dependencies: SceneGraph (buildLineNode), ribbonScene (buildRibbon*)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "line")
  */
 import type { SceneNode } from "../types";

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -8,6 +8,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: SceneGraph (buildPointNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartTypes "scatter", "bubble")
  */
-import type { SceneNode } from "../types";
+import type { PointSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];

package/dist/components/stream/xySceneBuilders/ribbonScene.d.ts

@@ -0,0 +1,107 @@
+import type { Datum } from "../../charts/shared/datumTypes";
+/**
+ * Ribbon scene builder — the unified primitive for painting a closed
+ * top/bottom envelope underneath a line/area, used by:
+ *
+ * - `boundsAccessor` (symmetric ±offset around `yAccessor`)
+ * - `band` (asymmetric `y0Accessor` / `y1Accessor` per BandConfig, with
+ *   multi-band fan support)
+ *
+ * Both public APIs normalize to `ResolvedRibbon[]` at the PipelineStore
+ * layer; the scene builders, y-extent expansion, and tooltip enrichment
+ * all read that single array.
+ *
+ * Consumed by: lineScene, areaScene, mixedScene (each renders ribbons
+ * before lines/areas so they sit underneath in z-order).
+ */
+import type { AreaSceneNode, Style } from "../types";
+import type { XYSceneContext } from "./types";
+/**
+ * One ribbon worth of geometry + style. The PipelineStore owns the
+ * normalization from `boundsAccessor` and `band` public props into this
+ * single internal shape.
+ */
+export interface ResolvedRibbon {
+    /**
+     * Origin of this ribbon:
+     * - `"bounds"`: produced by `boundsAccessor` (decorative-only)
+     * - `"band"`: produced by `band` (eligible for `datum.band` tooltip
+     *   enrichment in the hover handler)
+     */
+    kind: "bounds" | "band";
+    /**
+     * Top y-value for each datum. Return `NaN` to skip a datum entirely
+     * (gap behavior). Bounds resolves this from `y + offset` (collapsing
+     * to `y` when offset is non-finite, matching legacy behavior); band
+     * resolves it from `y1Accessor`.
+     */
+    getTop: (d: Datum) => number;
+    /**
+     * Bottom y-value for each datum. Same gap semantics as `getTop`.
+     */
+    getBottom: (d: Datum) => number;
+    /**
+     * Style override. When omitted, the scene builder falls back to
+     * `ctx.resolveBoundsStyle(group, sampleDatum)` — line color at 0.2
+     * fillOpacity. Functions get the first datum and group key.
+     */
+    style?: Style | ((d: Datum, group?: string) => Style);
+    /**
+     * `true` → one ribbon per group, colored to match each line.
+     * `false` → a single aggregate ribbon across the whole dataset.
+     * Bounds is always `true`. Band defaults to `true`; the public
+     * `BandConfig.perSeries: false` opt-out flips this.
+     */
+    perSeries: boolean;
+    /**
+     * Whether the ribbon area participates in hit testing. Bounds is
+     * always `false`. Band defaults to `false` but supports `interactive: true`.
+     */
+    interactive: boolean;
+}
+/**
+ * Build a single ribbon scene node for one slice of data.
+ *
+ * Iterates the data once, evaluates `getTop`/`getBottom` per datum, and
+ * collects coordinate pairs. Any datum with non-finite x, top, or bottom
+ * is skipped (gap semantics — equivalent to `gapStrategy: "break"`).
+ * Returns `null` when fewer than two valid points remain (a single
+ * point can't form a visible ribbon).
+ */
+export declare function buildRibbonForGroup(ctx: XYSceneContext, data: Datum[], group: string, ribbon: ResolvedRibbon): AreaSceneNode | null;
+/**
+ * Split ribbons by `perSeries` so the caller can dispatch correctly:
+ * per-series ribbons render once per group; aggregate ribbons render
+ * once across the full dataset.
+ */
+export declare function partitionRibbons(ribbons: ResolvedRibbon[] | undefined): {
+    perSeries: ResolvedRibbon[];
+    aggregate: ResolvedRibbon[];
+};
+/**
+ * Build all aggregate ribbons (perSeries=false) for the whole dataset.
+ * Each ribbon emits at most one AreaSceneNode under the synthetic
+ * group key `__ribbon_aggregate`.
+ */
+export declare function buildAggregateRibbons(ctx: XYSceneContext, data: Datum[], ribbons: ResolvedRibbon[]): AreaSceneNode[];
+/**
+ * Build all per-series ribbons for one grouped data slice. Each ribbon
+ * in the list emits at most one AreaSceneNode for the given group.
+ */
+export declare function buildPerSeriesRibbons(ctx: XYSceneContext, data: Datum[], group: string, ribbons: ResolvedRibbon[]): AreaSceneNode[];
+/**
+ * Enrich a hovered datum with band values so user tooltips can read
+ * `datum.band = { y0, y1 }` (first band) and `datum.bands = [...]`
+ * (all bands). Returns a shallow copy so the original data row is
+ * never mutated.
+ *
+ * Bounds-sourced ribbons (`kind: "bounds"`) are intentionally excluded
+ * — they're decorative, and the tooltip enrichment contract is
+ * band-only. Returns the input datum unchanged when no band-kind
+ * ribbons are configured or none produce finite values at this datum.
+ *
+ * Consumed by every code path that produces a `HoverData` in
+ * StreamXYFrame: pointer hover, multi-mode per-series datum, and
+ * keyboard navigation.
+ */
+export declare function enrichDatumWithBand(datum: Datum | null | undefined, ribbons: ResolvedRibbon[] | undefined): Datum;

package/dist/components/stream/xySceneBuilders/swarmScene.d.ts

@@ -6,6 +6,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  *
  * Consumed by: PipelineStore.buildSceneNodes (chartType "swarm")
  */
-import type { SceneNode } from "../types";
+import type { PointSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];

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

@@ -1,4 +1,5 @@
 import type { Datum } from "../../charts/shared/datumTypes";
+import type { AreaGradientConfig } from "./areaGradient";
 /**
  * XYSceneContext — shared context passed to all XY scene builder functions.
  *
@@ -7,6 +8,7 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * accessing PipelineStore instance fields directly.
  */
 import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
+import type { ResolvedRibbon } from "./ribbonScene";
 export interface XYSceneContext {
     scales: StreamScales;
     config: XYSceneConfig;
@@ -18,7 +20,10 @@ export interface XYSceneContext {
     getGroup?: (d: Datum) => string;
     getCategory?: (d: Datum) => string;
     getPointId?: (d: Datum) => string;
-    getBounds?: (d: Datum) => number | null;
+    /** Resolved ribbons — unified list from `boundsAccessor` + `band`. The
+     *  scene builders iterate this once instead of carrying two parallel
+     *  code paths. Empty when neither prop is set. */
+    ribbons?: ResolvedRibbon[];
     getOpen?: (d: Datum) => number;
     getHigh?: (d: Datum) => number;
     getLow?: (d: Datum) => number;
@@ -42,7 +47,7 @@ export interface XYSceneContext {
 }
 /** Subset of PipelineConfig fields that scene builders need */
 export interface XYSceneConfig {
-    chartType: string;
+    chartType?: string;
     curve?: CurveType;
     colorScheme?: string | string[];
     normalize?: boolean;
@@ -50,15 +55,7 @@ export interface XYSceneConfig {
     baseline?: "zero" | "wiggle" | "silhouette";
     /** Stack order — see PipelineConfig.stackOrder. */
     stackOrder?: "key" | "insideOut" | "asc" | "desc";
-    gradientFill?: boolean | {
-        topOpacity?: number;
-        bottomOpacity?: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    gradientFill?: AreaGradientConfig;
     areaGroups?: Set<string>;
     lineGradient?: {
         colorStops: Array<{
@@ -83,7 +80,7 @@ export interface XYSceneConfig {
     barColors?: Record<string, string>;
     /** Bar fill/stroke/strokeWidth/gap. Threaded through from RealtimeHistogram. */
     barStyle?: BarStyle;
-    themeSemantic?: ThemeSemanticColors;
+    themeSemantic?: Partial<ThemeSemanticColors>;
     /** Theme sequential scheme name — fallback when colorScheme is not set (heatmap). */
     themeSequential?: string;
     /** Theme diverging scheme name — fallback when colorScheme is not set. */

package/dist/components/stream/xySceneBuilders/waterfallScene.d.ts

@@ -8,6 +8,6 @@
  * Consumed by: PipelineStore.buildSceneNodes (chartType "waterfall")
  */
 import type { Datum } from "../../charts/shared/datumTypes";
-import type { SceneNode, StreamLayout } from "../types";
+import type { RectSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];
+export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): RectSceneNode[];

package/dist/components/types/legendTypes.d.ts

@@ -31,6 +31,20 @@ export declare function isLegendConfig(value: unknown): value is {
 export declare function isGradientLegendConfig(value: unknown): value is {
     gradient: GradientLegendConfig;
 };
+export interface LegendLayout {
+    /** Horizontal alignment for top/bottom legends within the plot width */
+    align?: "start" | "center" | "end" | "left" | "right";
+    /** Width/height of categorical swatches in pixels */
+    swatchSize?: number;
+    /** Gap between a swatch and its label in pixels */
+    labelGap?: number;
+    /** Gap between horizontal legend items in pixels */
+    itemGap?: number;
+    /** Vertical row height for stacked legend items in pixels */
+    rowHeight?: number;
+    /** Override the alignment width used for top/bottom legends */
+    maxWidth?: number;
+}
 export interface LegendProps {
     legendGroups?: LegendGroup[];
     customClickBehavior?: (item: LegendItem) => void;
@@ -46,4 +60,5 @@ export interface LegendProps {
     height?: number;
     orientation?: string;
     position?: "left" | "right";
+    legendLayout?: LegendLayout;
 }