semiotic 3.4.2 → 3.5.1

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

@@ -4,10 +4,24 @@ export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet:
 export declare function buildAreaNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Datum) => number): AreaSceneNode;
 /** Per-group-per-x stacked top values, keyed by group then x */
 export type StackedTops = Map<string, Map<number, number>>;
+export type StackBaseline = "zero" | "wiggle" | "silhouette";
+/**
+ * Compute per-x stack baseline offsets. Shared between scene rendering
+ * (`buildStackedAreaNodes`) and extent computation (`PipelineStore`) so
+ * both see the same y-bounds — without this, the wiggle offset's
+ * accumulated drift can exceed `±total/2` and clip against a too-small
+ * y-domain.
+ *
+ * Inputs:
+ *   xValues   — sorted unique x values
+ *   groupKeys — group keys in stacking order (same order both callers use)
+ *   valueAt   — (groupKey, x) → group's value at x (0 if absent)
+ */
+export declare function computeStackOffsets(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number, baseline: StackBaseline): Map<number, number>;
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Datum[];
-}[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, styleFn: (group: string, sampleDatum?: Datum) => Style, normalize?: boolean, curve?: CurveType): {
+}[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, styleFn: (group: string, sampleDatum?: Datum) => Style, normalize?: boolean, curve?: CurveType, baseline?: StackBaseline): {
     nodes: AreaSceneNode[];
     stackedTops: StackedTops;
 };

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

@@ -9,7 +9,7 @@ import type { SceneNode } from "./types";
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel } from "./networkTypes";
 import type { OrdinalSceneNode } from "./ordinalTypes";
 import type { GeoSceneNode } from "./geoTypes";
-export declare function xySceneNodeToSVG(node: SceneNode, i: number): React.ReactNode;
+export declare function xySceneNodeToSVG(node: SceneNode, i: number, idPrefix?: string): React.ReactNode;
 export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
 export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
 export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;

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

@@ -0,0 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type CategoryDomainAccessor<T = Datum> = string | ((d: T) => unknown);
+export declare function extractCategoryDomain<T extends Datum>(data: T[], accessor: CategoryDomainAccessor<T> | undefined): string[];
+export declare function sameCategoryDomain(a: readonly string[], b: readonly string[]): boolean;

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

@@ -0,0 +1,15 @@
+import * as React from "react";
+/**
+ * Compose a stack of overlay ReactNodes into a single fragment, dropping
+ * null/undefined sources. Each frame paints its `resolvedForeground`
+ * (axes, legends, annotations, react overlay) and may layer additional
+ * sources on top — currently `customLayoutOverlays` from recipe-managed
+ * chrome, with brush UIs and recipe-owned legends planned. Centralising
+ * the merge here keeps SSR and client branches in sync and gives future
+ * overlay sources one obvious place to plug in.
+ *
+ * Returns the single non-null source as-is when only one is present
+ * (avoids an unnecessary fragment); returns `null` when every source is
+ * absent so callers can skip the overlay subtree entirely.
+ */
+export declare function composeOverlays(...sources: Array<React.ReactNode | null | undefined>): React.ReactNode;

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

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { MarginType } from "../types/marginType";
+import type { SceneNode, StreamScales, Style, ThemeSemanticColors } from "./types";
+/**
+ * customLayout — escape hatch for bespoke chart geometry.
+ *
+ * A customLayout function receives the same context the built-in scene
+ * builders use (scales, theme, resolvers, dimensions) and returns scene
+ * nodes. The frame still owns hit testing, transitions, decay, theme
+ * cascade, and SSR — the layout owns geometry only.
+ *
+ * Surface is intentionally narrow. Resist adding fields until a real
+ * recipe demands them.
+ */
+export type CustomLayout<C extends object = Record<string, unknown>> = (ctx: LayoutContext<C>) => LayoutResult;
+/**
+ * Context handed to every customLayout invocation. Six fields:
+ * data, scales, dimensions, theme, resolveColor, config.
+ *
+ * `resolveColor` is the contract that makes user layouts theme-aware —
+ * always prefer it over hardcoded color literals. `--doctor` flags
+ * layouts that emit nodes with literal hex/rgb fills.
+ */
+export interface LayoutContext<C extends object = Record<string, unknown>> {
+    /** Buffered, post-filter data the frame is currently drawing. */
+    data: Datum[];
+    /** Scales constructed by the frame from the resolved x/y domains. */
+    scales: StreamScales;
+    /**
+     * Plot-area geometry. All scene-node coordinates are plot-relative —
+     * the canvas/SVG group already lives inside `margin.left`/`margin.top`,
+     * so `width`/`height` describe the plot rect (same as `plot.width`/
+     * `plot.height`). Read `margin` if you need the outer canvas size.
+     */
+    dimensions: {
+        width: number;
+        height: number;
+        margin: MarginType;
+        plot: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** Theme-resolved semantic colors + categorical palette. */
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    /**
+     * Resolves a color for a given group/category, honoring
+     * CategoryColorProvider → colorScheme → theme cascade. Always prefer
+     * this over hardcoded literals.
+     */
+    resolveColor: (group: string, datum?: Datum) => string;
+    /** User-supplied config blob threaded through `layoutConfig`. */
+    config: C;
+}
+export interface LayoutResult {
+    /** Scene nodes to render. Get hit testing, transitions, decay, SSR for free. */
+    nodes?: SceneNode[];
+    /** SVG overlays composited above the canvas (labels, annotations). */
+    overlays?: ReactNode;
+}
+/**
+ * Note on extents: customLayout v1 does not return extents. Layouts that
+ * need to drive axis domains (e.g. horizon banding a continuous series)
+ * should pass `xExtent` / `yExtent` props on the chart — those flow into
+ * scale construction *before* the layout runs, so the layout sees correct
+ * scales. Layouts that don't use scales (waffle, calendar, treemap) can
+ * ignore extents entirely.
+ */
+/** Convenience helper: build a Style object that defers fill/stroke to the theme. */
+export declare function themedStyle(color: string, overrides?: Style): Style;

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

@@ -0,0 +1,29 @@
+import { STREAMING_PALETTE } from "../charts/shared/colorUtils";
+import { schemeCategory10 } from "../charts/shared/colorPalettes";
+/**
+ * Shared palette resolution for the network and ordinal customLayout
+ * escape hatches. XY's customLayout uses `PipelineStore.resolveGroupColor`
+ * (richer cascade with CategoryColorProvider integration) so it doesn't
+ * call this helper.
+ *
+ * Precedence:
+ *   1. Explicit `colorScheme` array — used as-is.
+ *   2. Named scheme string (e.g. "tableau10") — looked up in
+ *      `COLOR_SCHEMES`. Unknown names fall through.
+ *   3. Theme categorical (when non-empty).
+ *   4. The provided fallback palette.
+ *
+ * @param colorScheme   `colorScheme` from the chart's pipeline config
+ * @param themeCategorical  `themeCategorical` from theme resolution
+ * @param fallback      Palette to use when nothing else matches.
+ *                      Network passes `schemeCategory10`; ordinal passes
+ *                      `STREAMING_PALETTE`. Caller's choice.
+ */
+export declare function resolveCustomLayoutPalette(colorScheme: string | string[] | undefined, themeCategorical: string[] | undefined, fallback: readonly string[]): readonly string[];
+/**
+ * Build a stable hash → palette index resolver. Used by the network and
+ * ordinal customLayout contexts so the same key always returns the same
+ * color for the lifetime of the closure.
+ */
+export declare function buildResolveColor(palette: readonly string[]): (key: string) => string;
+export { schemeCategory10, STREAMING_PALETTE };

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

@@ -155,6 +155,15 @@ export interface StreamGeoFrameProps<T = Datum> {
     };
     lineStyle?: Style | ((d: Datum, group?: string) => Style);
     colorScheme?: string | string[];
+    /**
+     * Categorical color field. For ChoroplethMap reads from area `properties`
+     * (or top-level fallback); for ProportionalSymbolMap reads from each point.
+     * Server-side legend auto-build groups by this field when `showLegend` is
+     * set and no explicit `legend` prop is provided. The function form accepts
+     * either the point datum `T` or a GeoJSON Feature so choropleth callers can
+     * write `(f) => f.properties.region` without a cast.
+     */
+    colorBy?: string | ((d: T | GeoJSON.Feature) => string);
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
@@ -186,6 +195,10 @@ export interface StreamGeoFrameProps<T = Datum> {
     }) => void;
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
+    /** 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. */
+    onCategoriesChange?: (categories: string[]) => void;
     showAxes?: boolean;
     /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;

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

@@ -1,4 +1,3 @@
-import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Shared hover data utilities for stream frames.
  *
@@ -20,16 +19,11 @@ export interface HoverPointerCoords {
     clientX: number;
     clientY: number;
 }
-/**
- * Spread raw datum properties onto HoverData if it's a non-null,
- * non-array object. Class instances (Date, etc.) are included —
- * this matches the historical behavior where all datum fields are
- * accessible directly on the hover object (d.fieldName).
- */
-export declare function spreadDatum(rawDatum: any): Datum;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
- * Spreads plain-object datum properties for backwards compatibility
- * (consumers can access d.fieldName directly in addition to d.data.fieldName).
+ * The raw datum is preserved as `hover.data` for tooltip / callback
+ * consumers; pixel coordinates land on `x` / `y`. Anything else
+ * relevant to a specific frame family — `category`, `stats`,
+ * `nodeOrEdge`, `xValue`, etc. — is layered in via `extra`.
  */
 export declare function buildHoverData(rawDatum: any, x: number, y: number, extra?: Partial<HoverData>): HoverData;

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

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge } from "./networkTypes";
+import type { ThemeSemanticColors } from "./types";
+/**
+ * customLayout escape hatch for `StreamNetworkFrame`.
+ *
+ * A network layout is a pure function: given raw nodes/edges plus the
+ * frame's dimensions/theme, return positioned scene primitives — circles,
+ * rects, lines, beziers — and optional labels/overlays. The frame still
+ * owns hit testing, decay, accessibility, and SSR.
+ *
+ * Mirrors the XY `CustomLayout` pattern. Reach for it when the catalog
+ * (force, sankey, chord, tree, treemap, circle-pack, orbit) doesn't fit
+ * — e.g. `d3-flextree`, `dagre`, custom radial layouts.
+ */
+export type NetworkCustomLayout<C extends object = Record<string, unknown>> = (ctx: NetworkLayoutContext<C>) => NetworkLayoutResult;
+export interface NetworkLayoutContext<C extends object = Record<string, unknown>> {
+    /** Raw nodes from the data prop / push API. May or may not have positions. */
+    nodes: RealtimeNode[];
+    /** Raw edges. Source/target may be id strings or node references. */
+    edges: RealtimeEdge[];
+    /**
+     * Plot-area geometry. All scene-node coordinates are plot-relative —
+     * the canvas/SVG group already lives inside `margin.left`/`margin.top`.
+     */
+    dimensions: {
+        width: number;
+        height: number;
+        plot: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** Theme-resolved semantic + categorical colors. */
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    /**
+     * Resolves a stable color for a given key (typically a node id or
+     * category) by hashing into the frame-resolved categorical palette.
+     * The palette comes from `colorScheme` (array or named d3 scheme like
+     * `"tableau10"` / `"set3"`), then the active theme's `categorical`,
+     * then a fallback. The same key always returns the same color for the
+     * lifetime of this store.
+     *
+     * Note: this does *not* honor `CategoryColorProvider` — network charts
+     * don't currently thread that into the pipeline. If you need
+     * cross-chart category color sync, pass a matching `colorScheme` to
+     * each chart instead.
+     */
+    resolveColor: (key: string) => string;
+    /** User-supplied config blob threaded through `layoutConfig`. */
+    config: C;
+}
+export interface NetworkLayoutResult {
+    /** Positioned scene primitives. Circles, rects, or arcs. */
+    sceneNodes?: NetworkSceneNode[];
+    /** Positioned edges. Lines, beziers, ribbons, or curved. */
+    sceneEdges?: NetworkSceneEdge[];
+    /** Optional labels placed at arbitrary plot-relative positions. */
+    labels?: NetworkLabel[];
+    /** SVG overlays composited above the canvas. */
+    overlays?: ReactNode;
+}

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

@@ -40,6 +40,29 @@ export interface RealtimeNode {
     _pulseIntensity?: number;
     _pulseColor?: string;
     _pulseGlowRadius?: number;
+    /**
+     * @internal Hierarchy-layout-only extension fields. Set by
+     * `hierarchyLayoutPlugin` / `orbitLayoutPlugin` during layout and
+     * read by `hierarchySceneBuilders`. Typed `unknown` because the d3
+     * `HierarchyNode` shape is layout-specific (rectangular, circular,
+     * point) — consumers narrow with the structural fields they need.
+     */
+    __hierarchyNode?: unknown;
+    /** @internal Circle-pack layout radius. Set by `hierarchyLayoutPlugin`. */
+    __radius?: number;
+    /**
+     * @internal Chord-layout extension. Carries the start/end angles
+     * for the arc segment representing this node, computed by
+     * `chordLayoutPlugin` and read by its `buildScene`. Concretely
+     * typed (unlike `__hierarchyNode`) because chord is the only
+     * layout that writes this field, so the shape is fixed — no
+     * narrowing-at-read needed. `__` prefix matches the convention
+     * used by `__hierarchyNode` / `__radius` on this same interface.
+     */
+    __arcData?: {
+        startAngle: number;
+        endAngle: number;
+    };
 }
 export interface RealtimeEdge {
     source: RealtimeNode | string;
@@ -69,6 +92,17 @@ export interface RealtimeEdge {
     /** @internal Circular sankey layout fields */
     _circularWidth?: number;
     _circularStub?: boolean;
+    /**
+     * @internal Chord-layout extension. Carries the d3-chord-generated
+     * source/target arc spans for this edge, set by `chordLayoutPlugin`
+     * during `computeLayout` and read by its `buildScene`. Typed
+     * `unknown` because the d3 `Chord` interface lives in `d3-chord`
+     * and importing the type here would couple `networkTypes` to that
+     * dep — consumers narrow at the read site. `__` prefix matches the
+     * `_circularWidth` / `_circularStub` internal-field convention on
+     * this same interface.
+     */
+    __chordData?: unknown;
 }
 export interface BezierPoint {
     x: number;
@@ -402,6 +436,11 @@ export interface NetworkPipelineConfig {
         x: number;
         y: number;
     }>;
+    /** When provided, replaces both layout dispatch and scene building.
+     *  Receives raw nodes/edges and returns positioned scene primitives. */
+    customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
+    layoutConfig?: object;
 }
 export interface StreamNetworkFrameProps<T = Datum> {
     chartType: NetworkChartType;
@@ -507,6 +546,12 @@ export interface StreamNetworkFrameProps<T = Datum> {
     description?: string;
     /** Accessible summary rendered as a screen-reader-only note */
     summary?: string;
+    /** Replaces network layout + scene dispatch with a user-supplied function.
+     *  Receives raw nodes/edges + dimensions/theme, returns positioned scene
+     *  primitives. See `semiotic/recipes` for reference layouts (flextree, dagre). */
+    customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
+    layoutConfig?: object;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;

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

@@ -0,0 +1,84 @@
+import type { ReactNode } from "react";
+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";
+/**
+ * customLayout escape hatch for `StreamOrdinalFrame`.
+ *
+ * Mirrors the XY `CustomLayout` and network `NetworkCustomLayout` patterns.
+ * Reach for it when the catalog (bar, swarm, pie, box, ...) doesn't fit:
+ * marimekko, parallel coordinates, bullet charts, fan charts, slope graphs
+ * and similar are all natural ordinal customLayouts.
+ *
+ * The frame still owns hit testing, transitions, decay, theme cascade,
+ * and SSR — the layout owns geometry only. Emit standard scene nodes
+ * (`rect`, `point`, `wedge`, `boxplot`, `violin`, `connector`, `trapezoid`)
+ * and the frame handles the rest.
+ */
+export type OrdinalCustomLayout<C extends object = Record<string, unknown>> = (ctx: OrdinalLayoutContext<C>) => OrdinalLayoutResult;
+export interface OrdinalLayoutContext<C extends object = Record<string, unknown>> {
+    /** Buffered, post-filter data the frame is currently drawing. */
+    data: Datum[];
+    /**
+     * Frame-built scales. `o` is the band scale over categories
+     * (insertion-ordered by default; flip via `oSort`). `r` is the linear
+     * value scale. Their domains/ranges respect `oExtent`/`rExtent` if you
+     * passed them on the chart.
+     */
+    scales: {
+        o: ScaleBand<string>;
+        r: ScaleLinear<number, number>;
+        projection: OrdinalScales["projection"];
+    };
+    /**
+     * Plot-area geometry. The canvas/SVG group is already translated by
+     * the frame, so scene-node coordinates are *plot-local* — but the
+     * origin depends on `scales.projection`:
+     *
+     *   - `vertical` / `horizontal`: origin is the **top-left** of the
+     *     plot rect. `plot = { x: 0, y: 0, width, height }`.
+     *   - `radial`: origin is the **center** of the plot rect. The frame
+     *     translates the context to `(margin.left + width/2, margin.top
+     *     + height/2)` so radial layouts emit coordinates around 0,0.
+     *     `plot = { x: -width/2, y: -height/2, width, height }` — the
+     *     top-left of the visible plot rect lives at `(plot.x, plot.y)`
+     *     in your coord space.
+     *
+     * In both cases `plot.width` and `plot.height` describe the plot rect.
+     * Read `margin` if you need the outer canvas size.
+     */
+    dimensions: {
+        width: number;
+        height: number;
+        margin: MarginType;
+        plot: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** Theme-resolved semantic + categorical colors. */
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    /**
+     * Resolves a stable color for a given key (typically a category
+     * label) from the frame's categorical palette. Palette precedence:
+     * explicit `colorScheme` (array or named d3 scheme like `"tableau10"`)
+     * → theme categorical → fallback. The same key always returns the
+     * same color for the lifetime of this store.
+     */
+    resolveColor: (key: string) => string;
+    /** User-supplied config blob threaded through `layoutConfig`. */
+    config: C;
+}
+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;
+}

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

@@ -5,7 +5,7 @@ import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, Sta
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup } 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";
+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>;
     r: ScaleLinear<number, number>;
@@ -187,6 +187,14 @@ export interface OrdinalPipelineConfig {
             color: string;
         }>;
     };
+    /** Swimlane "track" fill — a rect drawn behind each lane spanning the
+     *  full value-axis range, sized to the lane's bandwidth. Used to make
+     *  budget/progress lanes read as filled vs. empty. Pass a color (CSS
+     *  var supported) or `{ color, opacity }`. Honored by `chartType="swimlane"` only. */
+    trackFill?: string | {
+        color: string;
+        opacity?: number;
+    };
     /** When true, adds padding below the 0 baseline. When false (default), bars are flush with the axis line. */
     baselinePadding?: boolean;
     innerRadius?: number;
@@ -225,6 +233,15 @@ export interface OrdinalPipelineConfig {
     /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
     introAnimation?: boolean;
     staleness?: StalenessConfig;
+    /** 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;
+    /** 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;
 }
 export interface StreamOrdinalFrameProps<T = Datum> {
     chartType: OrdinalChartType;
@@ -266,6 +283,11 @@ export interface StreamOrdinalFrameProps<T = Datum> {
             color: string;
         }>;
     };
+    /** Swimlane "track" fill — see OrdinalPipelineConfig.trackFill */
+    trackFill?: string | {
+        color: string;
+        opacity?: number;
+    };
     baselinePadding?: boolean;
     innerRadius?: number;
     cornerRadius?: number;
@@ -336,6 +358,10 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    /** 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. */
+    onCategoriesChange?: (categories: string[]) => void;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
@@ -364,6 +390,14 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     description?: string;
     /** Accessible summary rendered as a screen-reader-only note */
     summary?: string;
+    /** Replaces ordinal scene dispatch with a user-supplied function.
+     *  Receives an OrdinalLayoutContext (scales, dimensions, theme,
+     *  resolveColor), returns scene nodes + optional overlays. See
+     *  `semiotic/recipes` for reference layouts (marimekko, parallel
+     *  coordinates, bullet). */
+    customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
+    /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
+    layoutConfig?: object;
 }
 export interface StreamOrdinalFrameHandle<T = Datum> {
     push(datum: T): void;

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

@@ -7,6 +7,14 @@ export declare const barFunnelHatchRenderer: (ctx: CanvasRenderingContext2D, nod
  *  - Bold percentage (of first step)
  *  - Raw value below it
  *
- * Labels appear on a white rounded-rect background (matching the reference images).
+ * Light/dark mode is decided per-frame from the luminance of the
+ * resolved `--semiotic-text` value: if body text is light, we're in
+ * dark mode and pair a dark surface with light text; otherwise light
+ * mode (white surface, dark text). Pairing the background to whatever
+ * text color the consumer's theme actually emits is more robust than
+ * sourcing both from independent CSS variables — many sites set
+ * `--semiotic-text` and `--semiotic-bg` without setting
+ * `--semiotic-tooltip-bg`, which would otherwise leave the label box
+ * stuck on its fallback regardless of theme.
  */
 export declare const barFunnelLabelRenderer: (ctx: CanvasRenderingContext2D, nodes: OrdinalSceneNode[], _scales: OrdinalScales, _layout: OrdinalLayout) => void;

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

@@ -0,0 +1,92 @@
+/**
+ * Shared canvas-rendering primitives used by `bar`/`area`/`line`/`point`
+ * renderers (and any future mark renderer that paints a fill, a stroke,
+ * or a linear gradient).
+ *
+ * These are extractions, not abstractions: every function in this module
+ * was inline-duplicated across two or more renderers in byte-identical
+ * (or near-identical) form. Centralizing them eliminates drift at the
+ * "what does the canvas seam look like for a stream renderer" boundary
+ * and keeps each renderer focused on its mark-specific path tracing.
+ *
+ * Anything genuinely chart-shape-specific — `buildBarGradient`'s
+ * tip-vs-base coordinate computation from `node.roundedEdge`, the
+ * area's strip-decay path, the line's threshold-color crossing logic —
+ * stays in the renderer that owns the mark. The helpers here are the
+ * mechanical bits that recur regardless of the shape being painted.
+ */
+import type { CurveType } from "../types";
+import type { CurveFactory } from "d3-shape";
+/**
+ * Structural shapes for the gradient configs the helpers accept. Kept
+ * local rather than exported from `types.ts` because today's scene-node
+ * interfaces (`AreaSceneNode`, `RectSceneNode`, `LineSceneNode`) declare
+ * the same shapes inline. TS structural typing means a caller passing
+ * `node.fillGradient` satisfies these types without an explicit cast.
+ */
+type ColorStop = {
+    offset: number;
+    color: string;
+};
+export type ColorStopGradient = {
+    colorStops: ColorStop[];
+};
+export type OpacityGradient = {
+    topOpacity: number;
+    bottomOpacity: number;
+};
+export type FillGradient = ColorStopGradient | OpacityGradient;
+/**
+ * Map a `CurveType` string to a d3-shape curve factory. Returns `null`
+ * for `"linear"` and `undefined` so callers can branch on a single
+ * "use linear fallback" sentinel instead of a separate has-curve check.
+ *
+ * Identical implementations previously lived in `areaCanvasRenderer.ts`
+ * and `lineCanvasRenderer.ts` — every new curve token had to be added
+ * to both switches in lockstep.
+ */
+export declare function resolveCurveFactory(curve: CurveType | undefined): CurveFactory | null;
+/**
+ * Resolve a node's `style.fill` (or `style.stroke`) to something the
+ * canvas can accept as `fillStyle` / `strokeStyle`:
+ *
+ *   - Strings go through `resolveCSSColor` so `var(...)` references
+ *     resolve via the canvas DOM ancestor's computed style. Without
+ *     this, canvas silently rejects CSS-variable strings and falls
+ *     back to `#000000`.
+ *   - `CanvasPattern` values pass through untouched.
+ *   - `null` / `undefined` returns the caller-provided fallback.
+ *
+ * The previous inline form was
+ * `(typeof X === "string" ? resolveCSSColor(ctx, X) : X) || fallback`,
+ * repeated once per renderer per fill/stroke site.
+ */
+export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+/**
+ * Build a linear gradient from a `FillGradient` config. Returns `null`
+ * when the gradient cannot be constructed (fewer than two valid color
+ * stops in the `colorStops` form, or a non-finite opacity in the
+ * `topOpacity` form).
+ *
+ * The renderer is responsible for choosing the gradient axis (a bar
+ * runs tip→base along its value axis; an area runs minTop→maxBottom
+ * vertically). The opacity-form path color-normalizes through the
+ * canvas via `parseCanvasColor` so named colors (`steelblue`), hsl(),
+ * etc. all produce gradients that match the mark's actual fill.
+ *
+ * Replaces `buildBarGradient` (bar) and the inline gradient block in
+ * `areaCanvasRenderer` — both implemented the same two-shape switch
+ * with the same offset-clamping and the same parseCanvasColor flow.
+ */
+export declare function buildLinearFillGradient(ctx: CanvasRenderingContext2D, fillGradient: FillGradient, baseFill: string, x0: number, y0: number, x1: number, y1: number): CanvasGradient | null;
+/**
+ * Build a linear gradient from a `ColorStopGradient` (the stroke-side
+ * shape — only the `colorStops` form, no opacity variant). Returns
+ * `null` when there aren't enough valid stops to render a gradient.
+ *
+ * Caller picks the axis. Identical patterns previously lived inline in
+ * `areaCanvasRenderer`'s top-stroke branch and `lineCanvasRenderer`'s
+ * stroke branch.
+ */
+export declare function buildColorStopGradient(ctx: CanvasRenderingContext2D, strokeGradient: ColorStopGradient, x0: number, y0: number, x1: number, y1: number): CanvasGradient | null;
+export {};

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

@@ -0,0 +1,9 @@
+import type { CurveFactory } from "d3-shape";
+/**
+ * Sample a d3-shape curve through `points` into a dense polyline.
+ *
+ * Returns the same `points` array unchanged when `curveFactory` is
+ * null — caller should treat that as the linear case (no resampling
+ * needed).
+ */
+export declare function sampleCurvePath(points: ReadonlyArray<readonly [number, number]>, curveFactory: CurveFactory | null, samplesPerSegment?: number): [number, number][];