semiotic 3.8.4 → 3.8.6

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

@@ -1,9 +1,9 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
-import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
+import type { AnnotationContext, HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
@@ -33,8 +33,15 @@ export interface DistanceCartogramConfig {
     center: string;
     centerAccessor?: string | ((d: Datum) => string);
     costAccessor: string | ((d: Datum) => number);
+    /** Interpolation from fitted geography (0) to the cost layout (1). Values are clamped to [0, 1]. */
     strength?: number;
     lineMode?: "straight" | "fractional";
+    /**
+     * Layout encoding for cost-from-center:
+     * - `"radial"` (default): polar cartogram — distance ∝ cost, bearing from geography
+     * - `"strip"`: 1D Langren-style number line — x ∝ cost, y collapsed (sparkline)
+     */
+    layout?: "radial" | "strip";
 }
 export interface GeoAreaSceneNode {
     type: "geoarea";
@@ -239,6 +246,14 @@ export interface StreamGeoFrameProps<T = Datum> {
     /** Observe activation of widget annotations without replacing widget behavior. */
     onAnnotationActivate?: OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
+    /**
+     * Custom SVG annotation renderer — same contract as XY/ordinal
+     * `svgAnnotationRules`. Called before the built-in geo annotation rules;
+     * return `null`/`undefined` to fall through. Geo pre-projects
+     * `coordinates: [lon, lat]` to pixel `x`/`y` before this runs so a single
+     * rule body works on canvas CSR and `renderChart` SSR.
+     */
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
@@ -262,11 +277,7 @@ export interface StreamGeoFrameProps<T = Datum> {
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
-    legend?: ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend?: LegendValue;
     legendPosition?: "right" | "left" | "top" | "bottom";
     legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {
@@ -305,12 +316,13 @@ export interface StreamGeoFrameHandle {
     clear(): void;
     getProjection(): GeoProjection | null;
     getGeoPath(): GeoPath<void, GeoPermissibleObjects> | null;
-    /** Get cartogram layout info (center position, max cost, radius) */
+    /** Get cartogram layout info (center position, max cost, radius / strip length) */
     getCartogramLayout(): {
         cx: number;
         cy: number;
         maxCost: number;
         availableRadius: number;
+        layout?: "radial" | "strip";
     } | null;
     /** Get current zoom level (1 = default) */
     getZoom(): number;

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

@@ -1,11 +1,7 @@
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../types/legendTypes";
 export interface LegendRenderConfig {
-    legend: ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend: LegendValue;
     totalWidth: number;
     totalHeight: number;
     margin: {

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

@@ -4,7 +4,11 @@ import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
 import type { NetworkLayoutResult } from "./networkCustomLayout";
 /** Imperative API exposed by `StreamNetworkFrame` refs. */
 export interface StreamNetworkFrameHandle {
+    /** Ingest one edge immediately and coalesce its expensive layout with other
+     * pushes at the next animation frame. Geometry getters commit first. */
     push(edge: EdgePush): void;
+    /** Ingest and lay out an explicit edge batch synchronously, absorbing any
+     * layout pending from prior single-edge pushes. */
     pushMany(edges: EdgePush[]): void;
     /** Remove a node by ID. Also removes connected edges. */
     removeNode(id: string): boolean;

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

@@ -5,11 +5,12 @@ import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
 import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+import type { GradientConfig, GradientInput } from "../charts/shared/gradient";
 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>;
@@ -223,20 +224,8 @@ export interface OrdinalPipelineConfig {
     barPadding?: number;
     /** Rounded top corner radius for bar charts. Only the end away from the baseline is rounded. For stacked bars, only the topmost segment gets rounded. */
     roundedTop?: number;
-    /** Gradient fill for bar rects. `{ topOpacity, bottomOpacity }` fades the
-     *  resolved fill color from tip (opposite the baseline) to base; `{ colorStops }`
-     *  renders a multi-color gradient along the same axis. Direction follows the
-     *  bar's orientation (tip → base). Same shape as AreaChart.gradientFill
-     *  sans the `boolean` case — the HOC resolves `true` to default opacities. */
-    gradientFill?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill for bar rects. Offset 0 is the tip; offset 1 is the base. */
+    gradientFill?: GradientConfig;
     /** 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
@@ -339,17 +328,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     };
     barPadding?: number;
     roundedTop?: number;
-    /** Gradient fill for bar rects. Same shape as AreaChart.gradientFill sans
-     *  the boolean case — resolve booleans at the HOC layer. */
-    gradientFill?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill for bar rects. Offset 0 is the tip; offset 1 is the base. */
+    gradientFill?: GradientInput;
     /** Swimlane "track" fill — see OrdinalPipelineConfig.trackFill */
     trackFill?: string | {
         color: string;
@@ -430,11 +410,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
-    legend?: ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend?: LegendValue;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

package/dist/components/stream/physics/PhysicsKernel.d.ts

@@ -201,6 +201,7 @@ export declare class PhysicsKernelWorld {
     private resolveStaticCollision;
     private updateSensors;
     private updateSleeping;
+    private contactOpposesGravity;
     private wake;
     /** Uses the deterministic PRNG for future jittered spawn helpers. */
     nextRandom(): number;

package/dist/components/stream/physics/PhysicsSVGOverlay.d.ts

@@ -6,7 +6,7 @@
 import type { Datum } from "../../charts/shared/datumTypes";
 import * as React from "react";
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../../types/legendTypes";
 import { type AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 import type { AnnotationContext } from "../../realtime/types";
 import type { PhysicsBodyState } from "./PhysicsKernel";
@@ -31,11 +31,7 @@ export interface PhysicsSVGOverlayProps {
         left: number;
     };
     title?: string | ReactNode;
-    legend?: ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend?: LegendValue;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

package/dist/components/stream/physics/PhysicsSettledSVG.d.ts

@@ -1,3 +1,7 @@
+import * as React from "react";
+import type { Style } from "../types";
+import type { FrameGraphicsProp, FrameMargin } from "../useFrame";
+import type { PhysicsBodyState } from "./PhysicsKernel";
 import type { PhysicsSettledEvidence } from "./PhysicsEvidence";
 import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
 import { type PhysicsSettledScene, type PhysicsSettledSceneOptions } from "./PhysicsSettledScene";
@@ -7,8 +11,12 @@ export interface PhysicsSettledSVGOptions extends PhysicsSettledSceneOptions {
     title?: string;
     description?: string;
     background?: string;
+    backgroundGraphics?: FrameGraphicsProp;
     className?: string;
+    foregroundGraphics?: FrameGraphicsProp;
     idPrefix?: string;
+    margin?: Partial<FrameMargin>;
+    renderBodySVG?: (body: PhysicsBodyState, style: Style, index: number, idPrefix: string) => React.ReactNode | undefined;
 }
 export interface PhysicsSettledSVGRender {
     svg: string;

package/dist/components/stream/physics/StreamPhysicsTypes.d.ts

@@ -10,7 +10,7 @@ import type { Datum } from "../../charts/shared/datumTypes";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 import type { AnnotationContext } from "../../realtime/types";
-import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../../types/legendTypes";
 import type { FocusRingProps } from "../FocusRing";
 import type { PhysicsBodyState, PhysicsColliderBodyFilter, PhysicsColliderShape } from "./PhysicsKernel";
 import type { PhysicsPipelineConfig, PhysicsPipelineControlSurface, PhysicsPipelineStore, PhysicsPipelineTickResult, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions, PhysicsSimulationState, PhysicsObservationEvent } from "./PhysicsPipelineStore";
@@ -245,11 +245,7 @@ export interface StreamPhysicsFrameProps {
     onAnnotationActivate?: import("../../charts/shared/annotationActivation").OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode;
-    legend?: React.ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend?: LegendValue;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

@@ -8,6 +8,7 @@ import type { CoercibleNumber } from "./accessorUtils";
 import type { CustomLayout } from "./customLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { MarginType } from "../types/marginType";
+import type { GradientConfig } from "../charts/shared/gradient";
 export interface PipelineConfig {
     chartType: StreamChartType;
     runtimeMode?: "streaming" | "bounded";
@@ -76,22 +77,13 @@ export interface PipelineConfig {
     boundsStyle?: Style | ((d: Datum, group?: string) => Style);
     y0Accessor?: string | ((d: Datum) => CoercibleNumber);
     band?: BandConfig | BandConfig[];
-    gradientFill?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    gradientFill?: GradientConfig;
     areaGroups?: Set<string>;
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    lineGradient?: GradientConfig;
+    semanticLineStops?: Array<{
+        offset: number;
+        color: string;
+    }>;
     lineStyle?: Style | ((d: Datum, group?: string) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;

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

@@ -1,50 +1,12 @@
-/**
- * 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.
- */
+/** Shared canvas primitives for fills, strokes, curves, and gradients. */
 import type { CurveType } from "../types";
+import type { GradientConfig } from "../../charts/shared/gradient";
 import { type HatchFill } from "../../charts/shared/hatchFill";
 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;
 /**
@@ -52,15 +14,10 @@ export declare function resolveCurveFactory(curve: CurveType | undefined): Curve
  * 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`.
+ *     resolve via the canvas DOM ancestor's computed style.
  *   - `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 | HatchFill | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
 /**
@@ -77,30 +34,13 @@ export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: s
  */
 export declare function coerceCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined): string | CanvasPattern | undefined;
 /**
- * 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).
+ * Build a linear gradient from a normalized gradient config. Stops without a
+ * color inherit the resolved mark color.
  *
  * 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.
+ * vertically).
  */
-export declare function buildColorStopGradient(ctx: CanvasRenderingContext2D, strokeGradient: ColorStopGradient, x0: number, y0: number, x1: number, y1: number): CanvasGradient | null;
-export {};
+export declare function buildLinearFillGradient(ctx: CanvasRenderingContext2D, fillGradient: GradientConfig, baseFill: string, x0: number, y0: number, x1: number, y1: number): CanvasGradient | null;
+/** Build a linear stroke gradient along the caller-provided axis. */
+export declare function buildColorStopGradient(ctx: CanvasRenderingContext2D, strokeGradient: GradientConfig, baseStroke: string, x0: number, y0: number, x1: number, y1: number): CanvasGradient | null;

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

@@ -1,13 +1,6 @@
 /**
- * Per-corner radius utilities shared between the canvas (`barCanvasRenderer`)
- * and SVG (`SceneToSVG`) paint paths.
- *
- * Both paths previously carried the same `hasAnyCornerRadius` predicate
- * and the same `min(radius, w/2, h/2)` clamp inline. Splitting them by
- * renderer left two near-identical implementations that drifted in
- * comments more than once; centralizing here keeps the swimlane rounding
- * contract — and any future per-corner shape (cards, tab corners,
- * partial-stack rounding) — in one place.
+ * Per-corner radius geometry shared between the canvas
+ * (`barCanvasRenderer`) and SVG (`SceneToSVG`) paint paths.
  *
  * The actual path-tracing primitives (canvas `arcTo` vs SVG `A`) stay in
  * each renderer because their output formats differ — this module owns

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

@@ -0,0 +1,12 @@
+import type { LineColorThreshold } from "../types";
+export interface ThresholdLineSegment {
+    color: string;
+    path: [number, number][];
+}
+export declare function resolveThresholdColor(value: number, thresholds: LineColorThreshold[], baseColor: string): string;
+/**
+ * Split a value-bearing polyline wherever it crosses a color threshold.
+ * Adjacent intervals with the same resolved color are merged so canvas and
+ * SVG can paint identical hard-edged bands with a minimal number of paths.
+ */
+export declare function buildThresholdLineSegments(path: [number, number][], rawValues: number[], thresholds: LineColorThreshold[], baseColor: string): ThresholdLineSegment[];

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

@@ -9,6 +9,7 @@ import type { DefaultArcObject } from "d3-shape";
 import { type HatchFill } from "../charts/shared/hatchFill";
 import type { GlyphDef } from "./glyphDef";
 import type { RectSceneNode, Style, SymbolSceneNode } from "./types";
+import type { GradientStop } from "../charts/shared/gradient";
 /**
  * Sentinel arg for d3-shape arc generators that have all four
  * accessors set to constants. The generator's call signature requires
@@ -49,14 +50,11 @@ export declare function glyphNodeToSVG(g: {
     pointId?: string;
     _decayOpacity?: number;
 }, x: number, y: number, key: string): React.ReactNode;
-export declare function colorStopElements(colorStops: Array<{
-    offset: number;
-    color: string;
-}>): React.ReactElement[] | null;
+export declare function colorStopElements(stops: GradientStop[], baseColor: string): React.ReactElement[] | null;
 /**
  * Build `<defs><linearGradient>` for a bar's fillGradient, mirroring the
  * tip→base direction the canvas renderer uses (inferred from roundedEdge).
- * Returns null when the config can't resolve (e.g. colorStops < 2), so the
+ * Returns null when the config has fewer than two usable stops, so the
  * caller falls back to a solid fill — same parity with the canvas path.
  *
  * Using `gradientUnits="userSpaceOnUse"` with absolute coords keeps each bar's

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

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { HatchFill } from "../charts/shared/hatchFill";
+import type { ColorGradientInput, GradientConfig, GradientInput } from "../charts/shared/gradient";
 import type { CoercibleNumber } from "./accessorUtils";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
@@ -147,12 +148,7 @@ export interface LineSceneNode {
     accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     /** Horizontal gradient for the line stroke */
-    strokeGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    strokeGradient?: GradientConfig;
     /** Curve interpolation type (default: linear / straight segments) */
     curve?: CurveType;
     /** Per-vertex decay opacities (oldest→newest = minOpacity→1.0). Set by PipelineStore.applyDecay. */
@@ -174,6 +170,20 @@ export interface AreaSceneNode {
     type: "area";
     topPath: [number, number][];
     bottomPath: [number, number][];
+    /** Raw y-values corresponding to each top-path point (for threshold coloring) */
+    rawValues?: number[];
+    /** Threshold-based colors for the area's top-edge stroke */
+    colorThresholds?: LineColorThreshold[];
+    /**
+     * Plot-relative horizontal clips for value-colored top strokes. Each band
+     * redraws the complete top path, preserving its configured curve exactly.
+     * An omitted color means the area's normal stroke color.
+     */
+    strokeColorBands?: Array<{
+        y: number;
+        height: number;
+        color?: string;
+    }>;
     style: Style;
     datum: SeriesDatum;
     accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
@@ -187,23 +197,10 @@ export interface AreaSceneNode {
         width: number;
         height: number;
     };
-    /** Gradient fill: opacity-based (topOpacity/bottomOpacity) or multi-color (colorStops) */
-    fillGradient?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill from top edge to baseline. */
+    fillGradient?: GradientConfig;
     /** Horizontal gradient for the line stroke */
-    strokeGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    strokeGradient?: GradientConfig;
     /** When false, skip hit testing (used for decorative bounds areas) */
     interactive?: boolean;
     /** Pulse intensity 0–1 (set when aggregated group value changes) */
@@ -384,15 +381,7 @@ export interface RectSceneNode {
     };
     /** Gradient fill — same shape as the area-scene version. Runs tip → base
      *  along the bar axis (inferred from `roundedEdge`). */
-    fillGradient?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    fillGradient?: GradientConfig;
     style: Style;
     datum: SceneDatum;
     accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
@@ -641,27 +630,18 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
      * Use for percentile bands, confidence ribbons, or any band/ribbon chart.
      */
     y0Accessor?: string | ((d: T) => number);
+    /** Gradient fill for area charts. Offset 0 is the top edge; offset 1 is the baseline. */
+    gradientFill?: GradientInput;
+    /** Horizontal gradient for line strokes. Offset 0 is left; offset 1 is right. */
+    lineGradient?: ColorGradientInput;
     /**
-     * Gradient fill for area charts. The fill fades from topOpacity at the line
-     * to bottomOpacity at the baseline. Set to `true` for default (0.8 → 0.05)
-     * or `{ topOpacity, bottomOpacity }` for custom values.
+     * Internal value-anchored color stops for an area's top-edge stroke.
+     * Offsets are resolved against the final y-domain by the scene builder.
      */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
-    /** Horizontal gradient for line strokes. Applied to all lines/area top-strokes. */
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    semanticLineStops?: Array<{
+        offset: number;
+        color: string;
+    }>;
     /** Series names (matching lineBy/colorBy group keys) that render as filled areas in "mixed" chartType */
     areaGroups?: string[];
     /**
@@ -777,11 +757,7 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
-    legend?: ReactNode | {
-        legendGroups: LegendGroup[];
-    } | {
-        gradient: GradientLegendConfig;
-    };
+    legend?: LegendValue;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

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

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

@@ -11,6 +11,7 @@ import type { AreaGradientConfig } from "./areaGradient";
 import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
 import type { SymbolName } from "../symbolPath";
 import type { ResolvedRibbon } from "./ribbonScene";
+import type { GradientConfig } from "../../charts/shared/gradient";
 export interface XYSceneContext {
     scales: StreamScales;
     config: XYSceneConfig;
@@ -61,12 +62,11 @@ export interface XYSceneConfig {
     stackOrder?: "key" | "input" | "insideOut" | "asc" | "desc";
     gradientFill?: AreaGradientConfig;
     areaGroups?: Set<string>;
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    lineGradient?: GradientConfig;
+    semanticLineStops?: Array<{
+        offset: number;
+        color: string;
+    }>;
     annotations?: Datum[];
     pointStyle?: (d: Datum) => Style & {
         r?: number;