semiotic 3.4.2 → 3.5.0

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][];

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

@@ -74,7 +74,7 @@ export interface MarginalGraphicsConfig {
     left?: MarginalConfig | MarginalType;
     right?: MarginalConfig | MarginalType;
 }
-export type StreamChartType = "line" | "area" | "stackedarea" | "mixed" | "scatter" | "bubble" | "heatmap" | "bar" | "swarm" | "waterfall" | "candlestick";
+export type StreamChartType = "line" | "area" | "stackedarea" | "mixed" | "scatter" | "bubble" | "heatmap" | "bar" | "swarm" | "waterfall" | "candlestick" | "custom";
 export type RuntimeMode = "bounded" | "streaming";
 export interface Style {
     stroke?: string;
@@ -137,6 +137,14 @@ export interface AreaSceneNode {
     style: Style;
     datum: SeriesDatum;
     group?: string;
+    /** Clip the area to this rect (in plot-relative pixels). Used by horizon
+     *  charts to band a single series into N slices. */
+    clipRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
     /** Gradient fill: opacity-based (topOpacity/bottomOpacity) or multi-color (colorStops) */
     fillGradient?: {
         topOpacity: number;
@@ -364,6 +372,27 @@ export interface StreamXYFrameProps<T = Datum> {
     lineDataAccessor?: string;
     curve?: CurveType;
     normalize?: boolean;
+    /**
+     * Stacked area baseline. Only consulted by stackedarea chartType.
+     * - "zero" (default): standard stack from y=0
+     * - "wiggle": Byron–Wattenberg streamgraph offset (minimizes wiggle)
+     * - "silhouette": center the stack symmetrically around y=0
+     *
+     * Mutually exclusive with `normalize`: when `normalize` is `true`, the
+     * stack is forced to a `"zero"` baseline (any other value is ignored)
+     * because normalization assumes a fixed `[0, 1]` y-domain.
+     */
+    baseline?: "zero" | "wiggle" | "silhouette";
+    /**
+     * Stack order — controls which series sits at the top, middle, or bottom.
+     * - "key" (default): alphabetical by group key
+     * - "insideOut": largest-total series in the middle, smaller alternating
+     *   above/below. Combined with `baseline: "wiggle"` or `"silhouette"`,
+     *   produces the canonical streamgraph look where a "central anchor"
+     *   layer sits across y=0 and other layers stack outward.
+     * - "asc" / "desc": by total ascending / descending
+     */
+    stackOrder?: "key" | "insideOut" | "asc" | "desc";
     /**
      * Accessor returning a symmetric uncertainty offset per datum.
      * When set, an uncertainty band is drawn ± this offset from the line.
@@ -506,6 +535,10 @@ export interface StreamXYFrameProps<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;
     /** SVG elements rendered behind the canvas (in pixel space) */
     backgroundGraphics?: ReactNode;
     /** SVG elements rendered on top of everything (in SVG overlay) */
@@ -550,6 +583,16 @@ export interface StreamXYFrameProps<T = Datum> {
     linkedCrosshairName?: string;
     /** Source chart ID — crosshair is suppressed on the source chart to avoid double rendering */
     linkedCrosshairSourceId?: string;
+    /** Replaces chart-type scene dispatch with a user-supplied layout function.
+     *  Receives a LayoutContext (scales, dimensions, theme, resolveColor) and
+     *  returns SceneNode[] + optional overlays. See `semiotic/recipes` for
+     *  reference layouts (waffle, calendar, horizon). */
+    customLayout?: import("./customLayout").CustomLayout;
+    /** User-supplied config blob threaded through to LayoutContext.config.
+     *  Typed as `object` so caller-defined interfaces (without an index
+     *  signature) flow through without casts; layouts narrow via their
+     *  own `CustomLayout<TConfig>` parameterization. */
+    layoutConfig?: object;
 }
 export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;

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

@@ -0,0 +1,89 @@
+import type { MutableRefObject, RefObject } from "react";
+/**
+ * Returns `false` on the server (no effect fires there) and during the
+ * first client render after hydration; `true` from the first
+ * post-commit re-render onward.
+ */
+export declare function useHydration(): boolean;
+/**
+ * Returns `true` when this component instance was mounted via SSR
+ * hydration (i.e. there was server-rendered HTML to hydrate from), and
+ * `false` when it was mounted via pure client-side rendering (no SSR).
+ *
+ * The trick: `useSyncExternalStore`'s `getServerSnapshot` callback is
+ * called *only* during hydration of server-rendered content — never
+ * during a fresh CSR mount. Returning different values from the two
+ * snapshots lets us read the hydration mode on the very first render,
+ * then we capture it into a ref so it survives later renders.
+ *
+ * Stream Frames use this to decide whether to skip the intro animation
+ * on the canvas's first paint: when SSR has already shown the chart in
+ * its final state, re-animating from blank when the canvas takes over
+ * looks like a regression. CSR mounts keep their intro animation
+ * because the SVG branch's output never actually paints (it's
+ * overwritten by the canvas branch within the same paint frame, before
+ * the browser commits a frame).
+ */
+export declare function useWasHydratingFromSSR(): boolean;
+/**
+ * Shared post-hydration lifecycle for every Stream Frame.
+ *
+ * Three things happen on every commit-after-hydration:
+ *
+ * 1. If we just rehydrated from SSR, cancel the intro animation that
+ *    the SVG-branch's `computeScene` installed (the server already
+ *    painted the chart in its final state — re-animating from blank
+ *    on the canvas takeover is a visual regression).
+ * 2. Mark the scene dirty so the canvas-paint pipeline rebuilds.
+ * 3. **Paint the canvas synchronously** via `renderFnRef.current()`.
+ *
+ * Step 3 is the timing-critical bit. The hook fires inside an
+ * isomorphic layout effect — `useLayoutEffect` on the client (runs
+ * synchronously after commit but before the browser paints),
+ * `useEffect` on the server (no-op, since SSR doesn't paint). If we
+ * deferred the paint to a `requestAnimationFrame` (the standard
+ * `scheduleRender()` route), the rAF callback wouldn't fire until
+ * the *next* frame — meaning the browser would paint *frame N* with
+ * the canvas in DOM but blank, then *frame N+1* with the canvas
+ * actually drawn. Synchronous paint inside the layout effect makes
+ * frame N's paint already include the canvas content; no flash.
+ *
+ * Each frame supplies its own `cleanup` for unmount work that's
+ * frame-specific (XY/Ordinal clear the streaming adapter; Geo clears
+ * its tile cache; Network has no extra cleanup).
+ */
+export interface HydrationLifecycleOptions {
+    hydrated: boolean;
+    wasHydratingFromSSR: boolean;
+    /**
+     * Ref to the frame's pipeline store. The store optionally implements
+     * `cancelIntroAnimation()`; the hook calls it when the SVG → canvas
+     * swap fires after SSR rehydration. (Currently every shipped store
+     * implements the method, but the optional shape lets a custom store
+     * opt out.)
+     */
+    storeRef: RefObject<{
+        cancelIntroAnimation?: () => void;
+    } | null>;
+    /**
+     * Mutable dirty flag the renderer reads on its next paint. The hook
+     * sets it to true on every commit so the post-hydration paint
+     * rebuilds the scene from scratch.
+     */
+    dirtyRef: MutableRefObject<boolean>;
+    /**
+     * Ref to the frame's render closure (assigned by `useFrame` /
+     * the frame body). The hook calls this synchronously to paint
+     * within the same frame as the SVG → canvas swap commit, avoiding
+     * the one-frame blank-canvas flicker that an rAF-deferred paint
+     * would produce.
+     */
+    renderFnRef: MutableRefObject<() => void>;
+    /**
+     * Optional unmount cleanup. Frame-specific work the hook can't
+     * generalize — e.g. clearing the streaming `DataSourceAdapter`
+     * (XY/Ordinal) or the geo tile cache.
+     */
+    cleanup?: () => void;
+}
+export declare function useHydrationLifecycle(opts: HydrationLifecycleOptions): void;

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

@@ -0,0 +1 @@
+export declare function useStableShallow<T>(value: T): T;

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

@@ -46,6 +46,10 @@ export interface XYSceneConfig {
     curve?: CurveType;
     colorScheme?: string | string[];
     normalize?: boolean;
+    /** Stacked area baseline. "zero" (default), "wiggle" (streamgraph), "silhouette" (centered). */
+    baseline?: "zero" | "wiggle" | "silhouette";
+    /** Stack order — see PipelineConfig.stackOrder. */
+    stackOrder?: "key" | "insideOut" | "asc" | "desc";
     gradientFill?: boolean | {
         topOpacity?: number;
         bottomOpacity?: number;