semiotic 3.4.1 → 3.5.0

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

@@ -1,11 +1,11 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./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 { 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>;
@@ -24,7 +24,7 @@ export interface WedgeSceneNode {
     /** Corner radius for rounded wedge arcs (d3-shape arc.cornerRadius) */
     cornerRadius?: number;
     style: Style;
-    datum: any;
+    datum: SceneDatum;
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -50,13 +50,13 @@ export interface BoxplotSceneNode {
     maxPos: number;
     stats: DistributionStats;
     style: Style;
-    datum: any;
+    datum: Datum;
     category?: string;
     outliers?: {
         px: number;
         py: number;
         value: number;
-        datum: any;
+        datum: Datum;
     }[];
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -98,7 +98,7 @@ export interface ViolinSceneNode {
     /** Pre-computed distribution statistics for tooltips */
     stats?: DistributionStats;
     style: Style;
-    datum: any;
+    datum: Datum;
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -113,7 +113,7 @@ export interface ConnectorSceneNode {
     x2: number;
     y2: number;
     style: Style;
-    datum: any;
+    datum: Datum;
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -126,7 +126,7 @@ export interface TrapezoidSceneNode {
     /** Four corners: [top-left, top-right, bottom-right, bottom-left] */
     points: [number, number][];
     style: Style;
-    datum: any;
+    datum: Datum;
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -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;
@@ -205,9 +213,9 @@ export interface OrdinalPipelineConfig {
     oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     connectorAccessor?: string | ((d: Datum) => string);
     connectorStyle?: Style | ((d: Datum) => Style);
-    dynamicColumnWidth?: string | ((data: any[]) => number);
-    pieceStyle?: (d: any, category?: string) => Style;
-    summaryStyle?: (d: any, category?: string) => Style;
+    dynamicColumnWidth?: string | ((data: Datum[]) => number);
+    pieceStyle?: (d: Datum, category?: string) => Style;
+    summaryStyle?: (d: Datum, category?: string) => Style;
     colorScheme?: string | string[];
     themeCategorical?: string[];
     /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
@@ -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;
@@ -293,8 +315,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     rTickValues?: number[];
     /** Align first tick label to start and last tick label to end. Default false. */
     tickLabelEdgeAlign?: boolean;
-    pieceStyle?: (d: any, category?: string) => Style;
-    summaryStyle?: (d: any, category?: string) => Style;
+    pieceStyle?: (d: Datum, category?: string) => Style;
+    summaryStyle?: (d: Datum, category?: string) => Style;
     colorScheme?: string | string[];
     barColors?: Record<string, string>;
     showAxes?: boolean;
@@ -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

@@ -1,8 +1,12 @@
 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 { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
+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);
 export interface ThemeSemanticColors {
     primary?: string;
     secondary?: string;
@@ -70,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;
@@ -100,7 +104,7 @@ export interface LineSceneNode {
     /** Threshold-based color segments */
     colorThresholds?: LineColorThreshold[];
     style: Style;
-    datum: any;
+    datum: SeriesDatum;
     group?: string;
     /** Horizontal gradient for the line stroke */
     strokeGradient?: {
@@ -131,8 +135,16 @@ export interface AreaSceneNode {
     topPath: [number, number][];
     bottomPath: [number, number][];
     style: Style;
-    datum: any;
+    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;
@@ -183,7 +195,7 @@ export interface PointSceneNode {
     y: number;
     r: number;
     style: Style;
-    datum: any;
+    datum: SceneDatum;
     /** Optional unique identifier for point-anchored annotations */
     pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active) */
@@ -227,7 +239,7 @@ export interface RectSceneNode {
         }>;
     };
     style: Style;
-    datum: any;
+    datum: SceneDatum;
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -249,7 +261,7 @@ export interface HeatcellSceneNode {
     w: number;
     h: number;
     fill: string;
-    datum: any;
+    datum: SceneDatum;
     /** Optional style object (used for decay/transition opacity on heatmap cells) */
     style?: Style;
     /** Numeric cell value (for canvas text rendering when showValues is enabled) */
@@ -286,7 +298,7 @@ export interface CandlestickSceneNode {
     isUp: boolean;
     /** Range/dumbbell mode — no body, endpoint dots instead */
     isRange?: boolean;
-    datum: any;
+    datum: SceneDatum;
     /** Optional style object (used during transition opacity animations) */
     style?: Style;
     _pulseIntensity?: number;
@@ -360,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.
@@ -446,7 +479,7 @@ export interface StreamXYFrameProps<T = Datum> {
         orient: "left" | "right" | "top" | "bottom";
         label?: string;
         ticks?: number;
-        tickFormat?: (d: any, index?: number, allTicks?: number[]) => string;
+        tickFormat?: AxisTickFormat;
         baseline?: boolean | "under";
         jaggedBase?: boolean;
     }>;
@@ -489,9 +522,9 @@ export interface StreamXYFrameProps<T = Datum> {
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {
-        legendGroups: any[];
+        legendGroups: LegendGroup[];
     } | {
-        gradient: import("../types/legendTypes").GradientLegendConfig;
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -502,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) */
@@ -546,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;