semiotic 3.8.5 → 3.8.7

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

@@ -49,8 +49,17 @@ export declare class PhysicsPipelineStore {
     materializeDueSpawns(): string[];
     clear(): void;
     tick(deltaSeconds: number): PhysicsPipelineTickResult;
+    /** Steps-only settle. Kernel/sensor transitions are stepped but not observed. */
     settle(maxSteps?: number): number;
     settleWithObservations(maxSteps?: number): PhysicsPipelineTickResult;
+    /** Bind this store to the shared settle loop (see physicsPipelineSettle). */
+    private settleHost;
+    /**
+     * One settle implementation for both entry points, so "run to completion"
+     * can't mean two different things. `observe` adds kernel/sensor observation
+     * and the collected tick result; the stepping itself is identical.
+     */
+    private runSettle;
     readBodies(out?: PhysicsBodyState[]): PhysicsBodyState[];
     readSediment(): PhysicsSedimentBinSnapshot[];
     bodyBudgetStatus(): PhysicsBodyBudgetDecision;

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/PhysicsSettledScene.d.ts

@@ -8,6 +8,11 @@ export interface PhysicsSettledSceneOptions {
     projectionRows?: PhysicsSettledProjectionRow[];
     bodyStyle?: Style | ((body: PhysicsBodyState) => Style);
     getBodyLabel?: (body: PhysicsBodyState) => string | undefined;
+    /**
+     * Total bodies the chart claims entered. Enables the settled ledger check
+     * (see {@link PhysicsSettledEvidence.ledger}); omitted means no ledger.
+     */
+    charge?: number;
 }
 export interface PhysicsSettledScene {
     snapshot: PhysicsPipelineSnapshot;

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/physics/physicsFramePipelineConfig.d.ts

@@ -0,0 +1,19 @@
+import type { Datum } from "../../charts/shared/datumTypes";
+import type { PhysicsObservationEvent, PhysicsPipelineConfig } from "./PhysicsPipelineStore";
+import type { StreamPhysicsRegionEffect } from "./StreamPhysicsTypes";
+interface PhysicsFramePipelineConfigOptions {
+    annotations?: Datum[];
+    chartId?: string;
+    chartType: string;
+    config?: PhysicsPipelineConfig;
+    onRegionObservation: (event: PhysicsObservationEvent) => void;
+    regionEffects: StreamPhysicsRegionEffect[];
+    seed?: number;
+    size: [number, number];
+}
+/**
+ * Adds frame-owned annotation/region colliders and observation wiring without
+ * mutating the caller's pipeline configuration.
+ */
+export declare function resolvePhysicsFramePipelineConfig({ annotations, chartId, chartType, config, onRegionObservation, regionEffects, seed, size }: PhysicsFramePipelineConfigOptions): PhysicsPipelineConfig | undefined;
+export {};

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

@@ -0,0 +1,52 @@
+/**
+ * The shared "run this simulation to completion" loop behind both of
+ * `PhysicsPipelineStore`'s settle entry points.
+ *
+ * Settling has to mean *the simulation reached its end state*, and that includes
+ * admitting every arrival the queue still owes. Advancing simulated time per
+ * step and re-checking due spawns inside the loop is what lets paced spawns
+ * (`initialSpawnPacing`, per-datum `spawnAt`) and elapsed-time event tapes
+ * finish on the reduced-motion / snapshot path instead of freezing at the first
+ * spawn instant. Both entry points run this one loop so they cannot drift apart.
+ */
+import type { PhysicsBodyBudgetDecision } from "./PhysicsBodyBudget";
+import type { PhysicsKernelEvent } from "./PhysicsKernel";
+import type { PhysicsPipelineEvictionResult } from "./physicsPipelineHelpers";
+import type { PhysicsObservationEvent } from "./PhysicsPipelineTypes";
+/**
+ * The slice of store behavior the loop drives. Passed explicitly (rather than
+ * reaching into the store) so the loop stays independently testable.
+ */
+export interface PhysicsSettleHost {
+    fixedDt: number;
+    queueSize: () => number;
+    atRest: () => boolean;
+    /** Advance simulated time; this is what makes time-driven consumers progress. */
+    advanceTime: (seconds: number) => void;
+    spawnDue: (spawned: string[], observations?: PhysicsObservationEvent[]) => void;
+    observeBodyBudget: (observations?: PhysicsObservationEvent[]) => PhysicsBodyBudgetDecision;
+    evictOverflow: (observations?: PhysicsObservationEvent[]) => PhysicsPipelineEvictionResult;
+    step: (deltaSeconds: number) => void;
+    /** Drain buffered kernel events for this step. */
+    drainEvents: () => PhysicsKernelEvent[];
+    observeKernelEvents: (events: PhysicsKernelEvent[], observations?: PhysicsObservationEvent[]) => void;
+    observeSensorTransitions: (observations?: PhysicsObservationEvent[]) => void;
+    refreshQuiescence: (deltaSeconds: number, spawnedCount: number) => void;
+}
+/**
+ * Collectors for the run. Only `spawned` is required — the cheap `settle()` path
+ * discards the rest, while `settleWithObservations()` collects everything.
+ * Omitting `events` also suppresses observation of kernel/sensor transitions.
+ */
+export interface PhysicsSettleSink {
+    spawned: string[];
+    evicted?: string[];
+    sedimented?: string[];
+    events?: PhysicsKernelEvent[];
+    observations?: PhysicsObservationEvent[];
+}
+export interface PhysicsSettleRun {
+    steps: number;
+    budget?: PhysicsBodyBudgetDecision;
+}
+export declare function runPhysicsSettleSteps(host: PhysicsSettleHost, maxSteps: number, sink: PhysicsSettleSink): PhysicsSettleRun;

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

@@ -29,6 +29,29 @@ export declare function regionRuntimeEffectsRequireSync(regionEffects: readonly
 export declare function applyActiveRegionEffects(controls: PhysicsPipelineControlSurface, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, dtSeconds: number): boolean;
 export declare function resolveBodyForceVector(force: StreamPhysicsBodyForce | undefined, context: StreamPhysicsBodyForceContext): StreamPhysicsRegionVector | null;
 export declare function applyBodyForces(controls: PhysicsPipelineControlSurface, bodyForces: StreamPhysicsBodyForce | undefined, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, simulationState: PhysicsSimulationState, dtSeconds: number): boolean;
+export interface PhysicsPostTickOutcome {
+    regionEffectsApplied: boolean;
+    bodyForcesApplied: boolean;
+    snapshot: ReturnType<PhysicsPipelineStore["snapshot"]>;
+    result: PhysicsPipelineTickResult;
+}
+/**
+ * How many settle → `onTick` → settle passes the reduced-motion path runs before
+ * giving up. Event-tape charts spawn bodies from `onTick`, so one pass is never
+ * enough; a small bound keeps a controller that always reports work from
+ * blocking the main thread.
+ */
+export declare const REDUCED_MOTION_SETTLE_PASSES = 4;
+/**
+ * The reduced-motion / snapshot render pass.
+ *
+ * Reduced motion never schedules a second frame, so any work a settle hands to
+ * `onTick` — an event tape spawning gate bodies, a capacity controller
+ * releasing queued items — would be enqueued and never simulated. Settle
+ * repeatedly while the store still reports pending work so the scene reaches
+ * the same end state an animated run would.
+ */
+export declare function runPhysicsReducedMotionPasses(store: PhysicsPipelineStore, postTick: (result: PhysicsPipelineTickResult) => Omit<PhysicsPostTickOutcome, "result">, maxPasses?: number): PhysicsPostTickOutcome;
 /**
  * Shared post-tick pipeline: region forces → body forces → controllers → onTick.
  * Used by the main RAF path and the worker-fallback path (DRY + one snapshot).

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) */
@@ -238,6 +235,8 @@ export interface PointSceneNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    /** Whether this point participates in hit testing and spatial indexing. Set to false for decorative points. @default true */
+    interactive?: boolean;
     accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
     accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional unique identifier for point-anchored annotations */
@@ -384,15 +383,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 +632,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 +759,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;

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

@@ -25,11 +25,16 @@ export interface GradientLegendConfig {
 }
 export interface CategoricalLegendConfig {
     legendGroups: LegendGroup[];
+    /** Gap in pixels between the legend and the plot/side gutter. Default: 10. */
+    legendDistance?: number;
 }
-/** Public legend slot accepted by stream frames and legend-aware chart HOCs. */
-export type LegendValue = ReactNode | CategoricalLegendConfig | {
+export interface GradientLegendValue {
     gradient: GradientLegendConfig;
-};
+    /** Gap in pixels between the legend and the plot/side gutter. Default: 10. */
+    legendDistance?: number;
+}
+/** Public legend slot accepted by stream frames and legend-aware chart HOCs. */
+export type LegendValue = ReactNode | CategoricalLegendConfig | GradientLegendValue;
 /**
  * Compose inferred and caller-supplied legends without discarding either
  * categorical domain. Configured groups are appended in argument order, so
@@ -41,9 +46,7 @@ export declare function composeLegendConfigs(...values: Array<LegendValue | null
 /** Type guard: categorical legend config */
 export declare function isLegendConfig(value: unknown): value is CategoricalLegendConfig;
 /** Type guard: gradient legend config */
-export declare function isGradientLegendConfig(value: unknown): value is {
-    gradient: GradientLegendConfig;
-};
+export declare function isGradientLegendConfig(value: unknown): value is GradientLegendValue;
 export interface LegendLayout {
     /** Horizontal alignment for top/bottom legends within the plot width */
     align?: "start" | "center" | "end" | "left" | "right";
@@ -57,6 +60,28 @@ export interface LegendLayout {
     rowHeight?: number;
     /** Override the alignment width used for top/bottom legends */
     maxWidth?: number;
+    /**
+     * Space between the plot and a left/right legend reserved for adjacent
+     * chart chrome such as axis ticks and an axis title. Ignored for top/bottom
+     * legends — see `axisGutter`. The legend is placed outside this gutter.
+     */
+    sideGutter?: number;
+    /**
+     * The top/bottom counterpart of `sideGutter`: space between the plot and a
+     * top/bottom legend reserved for that side's axis chrome (tick labels and
+     * an axis title).
+     *
+     * **Auto-measurement is bottom-axis only.** A bottom legend defaults to the
+     * measured chrome of the axis actually drawn, so it clears the tick labels
+     * instead of overdrawing them, and resolves to 0 when the chart has no
+     * bottom axis. Top axes are opt-in (`frameProps.axes` with
+     * `orient: "top"`), so a *top* legend defaults to 0 and needs this set
+     * explicitly to clear a top axis.
+     *
+     * Set explicitly to override either side, or `0` to opt out and anchor the
+     * legend directly to the plot edge.
+     */
+    axisGutter?: number;
 }
 export interface LegendProps {
     legendGroups?: LegendGroup[];