semiotic 3.5.1 → 3.5.3

package/dist/components/charts/shared/useXYLineStyle.d.ts

@@ -0,0 +1,69 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult, SelectionStyleConfig } from "./selectionUtils";
+export interface XYLineStyleOptions {
+    /**
+     * Base stroke width. The top-level `strokeWidth` override below
+     * wins via `mergeShapeStyle` when both are supplied.
+     * @default 2
+     */
+    lineWidth?: number;
+    /** Color accessor (string field name or function). */
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    /** Resolved categorical color scale (typically from useChartSetup). */
+    colorScale?: ((v: string) => string);
+    /** Static color used as the fallback stroke when `colorBy` is unset. */
+    color?: string;
+    /** Custom stroke resolver. Wins over `colorBy`/`colorScale`/`color`.
+     *  Receives the datum and the optional `group` key the frame
+     *  passes through `resolveLineStyle`. */
+    resolveStroke?: (d: Datum, group?: string) => string;
+    /** When `true`, every line fills. When a `string[]`, only series
+     *  whose `group` key appears in the array fill. When omitted/false,
+     *  no fill is set on the style. */
+    fillArea?: boolean | string[];
+    /** Fill opacity used when `fillArea` triggers a fill. @default 0.3 */
+    areaOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Selection hook result from `useChartSelection`/`useChartSetup`.
+     *  Pass `null`/`undefined` to skip dimming entirely (MinimapChart's
+     *  overview line and main line both skip selection wrapping). */
+    effectiveSelectionHook?: SelectionHookResult | null;
+    /** Resolved selection style config (matched/unmatched style overrides). */
+    resolvedSelection?: SelectionStyleConfig;
+}
+/**
+ * Returns a memoized `lineStyle` callback that the XY frame's
+ * `resolveLineStyle` invokes with `(datum, group?)`.
+ *
+ * @example
+ * ```tsx
+ * // LineChart's recipe collapses to a single hook call:
+ * const lineStyle = useXYLineStyle({
+ *   lineWidth, colorBy, colorScale, color, fillArea, areaOpacity,
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook, resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // MultiAxisLineChart hands in a series-aware resolver:
+ * const lineStyle = useXYLineStyle({
+ *   lineWidth,
+ *   resolveStroke: (d) => seriesColorMap.get(d[SERIES_FIELD]) || seriesColors[0],
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // MinimapChart's overview line: thin stroke, no selection, no primitives.
+ * const overviewLineStyle = useXYLineStyle({ lineWidth: 1, colorBy, colorScale })
+ * ```
+ */
+export declare function useXYLineStyle(options: XYLineStyleOptions): (d: Datum, group?: string) => Datum;

package/dist/components/charts/shared/useXYPointStyle.d.ts

@@ -0,0 +1,87 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult } from "./selectionUtils";
+export interface XYPointStyleOptions {
+    /** colorBy accessor — string field name or function. */
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    /** Resolved categorical color scale (typically from useChartSetup). */
+    colorScale: ((v: string) => string) | undefined;
+    /** Top-level uniform `color` prop. Used as the fallback fill when
+     *  `colorBy` is unset. */
+    color?: string;
+    /**
+     * Fixed point radius. When `radiusFn` is supplied, that wins
+     * (per-datum sizing for BubbleChart / Scatterplot's `sizeBy`).
+     * @default 5
+     */
+    pointRadius?: number;
+    /** Per-datum radius resolver (e.g. wraps `getSize(d, sizeBy, …)`).
+     *  Ignored when undefined; HOCs with no `sizeBy` should pass it
+     *  unset and rely on `pointRadius`. */
+    radiusFn?: (d: Datum) => number;
+    /** Default fillOpacity. Charts override this through their own
+     *  prop name (`pointOpacity`, `bubbleOpacity`). @default 1 */
+    fillOpacity?: number;
+    /**
+     * Fallback fill resolver invoked when `colorBy` is unset. Used by
+     * QuadrantChart to pick a color from the quadrant the point lands
+     * in. When omitted, fallback is `color || DEFAULT_COLOR` (the
+     * standard Scatterplot/BubbleChart behavior).
+     */
+    fallbackFill?: (d: Datum) => string;
+    /**
+     * Static or per-datum extra style applied BEFORE color resolution
+     * and primitive overlay. Use for shape-constant defaults
+     * (BubbleChart's `{ stroke: bubbleStrokeColor, strokeWidth: 1 }`).
+     * If extras supply a `fill`, the standard color resolution is
+     * skipped — same bypass as `useOrdinalPieceStyle`. Lets
+     * ConnectedScatterplot drop in its viridis-by-order fill.
+     */
+    baseStyleExtras?: Record<string, string | number | undefined> | ((d: Datum) => Record<string, string | number | undefined>);
+    /** Top-level primitive props — applied last via `mergeShapeStyle`. */
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Selection hook output (typically `setup.effectiveSelectionHook`). */
+    effectiveSelectionHook: SelectionHookResult | null | undefined;
+    /** Resolved selection config (typically `setup.resolvedSelection`). */
+    resolvedSelection: import("./types").SelectionConfig | undefined;
+    /**
+     * For ConnectedScatterplot-style charts whose color depends on the
+     * point's position in an ordered sequence, the resolver may need
+     * the point's parent line. Defaults to identity (`d => d`).
+     * Same hook BarChart's `parentLine` cascade uses.
+     */
+    colorDatumAccessor?: (d: Datum) => Datum;
+}
+/**
+ * Build a memoized `pointStyle` function for an XY HOC.
+ *
+ * @example
+ * ```tsx
+ * // Scatterplot — sizeBy-driven radius, standard color fallback
+ * const pointStyle = useXYPointStyle({
+ *   colorBy, colorScale: setup.colorScale,
+ *   color, pointRadius, fillOpacity: pointOpacity,
+ *   radiusFn: sizeBy ? (d) => getSize(d, sizeBy, sizeRange, sizeDomain) : undefined,
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // QuadrantChart — bespoke fallback fill from quadrant lookup
+ * const pointStyle = useXYPointStyle({
+ *   colorBy, colorScale: setup.colorScale, color,
+ *   pointRadius, fillOpacity: pointOpacity,
+ *   radiusFn: sizeBy ? (d) => getSize(d, sizeBy, sizeRange, sizeDomain) : undefined,
+ *   fallbackFill: (d) => quadrantColor(d, getXValue, getYValue, xCenter, yCenter, quadrants),
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ */
+export declare function useXYPointStyle(options: XYPointStyleOptions): (d: Datum) => Record<string, string | number | undefined>;

package/dist/components/charts/shared/withChartWrapper.d.ts

@@ -27,10 +27,17 @@ export declare function SafeRender({ componentName, width, height, children }: S
  */
 export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
 /**
- * Renders a shimmer/skeleton loading placeholder.
- * Returns null when loading is false.
+ * Renders a loading placeholder while `loading` is true.
+ *
+ * When `loadingContent` is provided, it replaces the default shimmer
+ * skeleton — wrapped in the same sized container so the chart still
+ * occupies the slot it would when rendered. Pass `false` to suppress
+ * the skeleton entirely (the early-return becomes null and the chart's
+ * own loading UI takes over).
+ *
+ * Returns null when `loading` is falsy.
  */
-export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number): React.ReactElement | null;
+export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number, loadingContent?: React.ReactNode | false): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
 export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
 /** Warn if data looks like the wrong shape for this chart type */

package/dist/components/charts/xy/AreaChart.d.ts

@@ -1,10 +1,11 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
  * AreaChart component props
  */
@@ -22,7 +23,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -159,6 +160,39 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /**
+     * Forecast overlay — extends the area with a tagged training /
+     * observed / forecast region and (optionally) a confidence
+     * envelope. Same shape as LineChart's `forecast` prop. Pair with
+     * `anomaly` for combined anomaly + forecast visualization.
+     *
+     * @example
+     * ```tsx
+     * <AreaChart data={obs} xAccessor="t" yAccessor="value"
+     *            forecast={{ trainEnd: 80, steps: 10, color: "#6366f1" }} />
+     * ```
+     */
+    forecast?: ForecastConfig;
+    /**
+     * Anomaly overlay — adds a ±σ band and per-point anomaly dots.
+     * Standalone (without forecast) gives raw anomaly detection.
+     *
+     * @example
+     * ```tsx
+     * <AreaChart data={obs} anomaly={{ threshold: 2 }} />
+     * ```
+     */
+    anomaly?: AnomalyConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the area fill. Distinct from
+     * `y0Accessor` (which replaces the area's baseline) — `band` is a
+     * decorative envelope painted beneath the area, driven by independent
+     * `y0Accessor` / `y1Accessor` per band. Pass an array for fan charts.
+     *
+     * The hovered datum gets `band: { y0, y1 }` and `bands: [...]` for
+     * tooltip access. See the LineChart docs for full ergonomics.
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
      * that side data-derived. Useful for pinning a time axis to a known

package/dist/components/charts/xy/BubbleChart.d.ts

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BubbleChart component props
  */
@@ -110,6 +111,14 @@ export interface BubbleChartProps<TDatum extends Datum = Datum> extends BaseChar
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /**
+     * Overlay a regression line on the bubbles. Accepts `true` (linear
+     * with default styling), a method name (`"linear"` | `"polynomial"`
+     * | `"loess"`), or a full `RegressionConfig`. Sugar over the `trend`
+     * annotation — drop into the `annotations` array directly for richer
+     * setups.
+     */
+    regression?: RegressionProp;
     /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
     xExtent?: [number | undefined, number | undefined] | [number];
     /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */

package/dist/components/charts/xy/ConnectedScatterplot.d.ts

@@ -5,6 +5,8 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode } from "../shared/hooks";
+import { type RegressionProp } from "../shared/regressionUtils";
+import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
  * ConnectedScatterplot component props
  */
@@ -37,6 +39,20 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
     legendInteraction?: LegendInteractionMode;
     /** Annotation objects to render on the chart */
     annotations?: Datum[];
+    /**
+     * Overlay a regression line under the connected path. Accepts
+     * `true`, a method name (`"linear"` | `"polynomial"` | `"loess"`),
+     * or a full `RegressionConfig`. Sugar over the `trend` annotation.
+     */
+    regression?: RegressionProp;
+    /**
+     * Forecast overlay — same shape as LineChart's `forecast` prop.
+     * Adds tagged future points + envelope annotations to the
+     * connected path.
+     */
+    forecast?: ForecastConfig;
+    /** Anomaly overlay — adds a ±σ band + anomaly dot annotations. */
+    anomaly?: AnomalyConfig;
     /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
     xExtent?: [number | undefined, number | undefined] | [number];
     /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */

package/dist/components/charts/xy/DifferenceChart.d.ts

@@ -0,0 +1,172 @@
+import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
+import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * DifferenceChart props
+ */
+export interface DifferenceChartProps<TDatum extends Datum = Datum> extends BaseChartProps, AxisConfig {
+    /** Array of `{x, a, b}` data points. Omit for push API mode. */
+    data?: TDatum[];
+    /** Accessor for the x value. Default `"x"`. */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Accessor for series A. Default `"a"`. */
+    seriesAAccessor?: ChartAccessor<TDatum, number>;
+    /** Accessor for series B. Default `"b"`. */
+    seriesBAccessor?: ChartAccessor<TDatum, number>;
+    /** Display label for series A (legend + tooltip). Default `"A"`. */
+    seriesALabel?: string;
+    /** Display label for series B. Default `"B"`. */
+    seriesBLabel?: string;
+    /** Fill color when series A is above series B. Default `"var(--semiotic-danger, #dc2626)"`. */
+    seriesAColor?: string;
+    /** Fill color when series B is above series A. Default `"var(--semiotic-info, #2563eb)"`. */
+    seriesBColor?: string;
+    /** Show the A and B series as overlay lines on top of the filled difference. Default `true`. */
+    showLines?: boolean;
+    /** Line stroke width when `showLines` is true. Default `1.5`. */
+    lineWidth?: number;
+    /** Show data points on the overlay lines. Default `false`. */
+    showPoints?: boolean;
+    /** Point radius when `showPoints` is true. Default `3`. */
+    pointRadius?: number;
+    /** Curve interpolation for both the area boundary and overlay lines. Default `"linear"`. */
+    curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
+    /** Fill opacity for the difference region. Default `0.6`. */
+    areaOpacity?: number;
+    /** Gradient fill across each segment, same shape as AreaChart.gradientFill. */
+    gradientFill?: boolean | {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
+    /** Enable hover annotations. */
+    enableHover?: boolean;
+    /** Show grid lines. Default `false`. */
+    showGrid?: boolean;
+    /** Show legend. Default `true`. */
+    showLegend?: boolean;
+    /** Legend interaction mode. */
+    legendInteraction?: LegendInteractionMode;
+    /** Legend position. */
+    legendPosition?: LegendPosition;
+    /** Tooltip config. */
+    tooltip?: TooltipProp;
+    /** Annotation objects. */
+    annotations?: Datum[];
+    /** Fixed x domain. */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /** Fixed y domain. */
+    yExtent?: [number | undefined, number | undefined] | [number];
+    /** Stable ID accessor for push-mode `remove()` / `update()`. */
+    pointIdAccessor?: string | ((d: Datum) => string);
+    /** Maximum number of raw rows kept in the push buffer. When exceeded,
+     *  oldest rows are evicted FIFO (sliding window). Default: unbounded.
+     *  Recommended for long-running streams so the per-render segment
+     *  recomputation stays bounded. */
+    windowSize?: number;
+    /** Pass-through StreamXYFrame props. */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
+}
+/**
+ * Crossover-segmented record used by the area pipeline. One row per
+ * vertex along either the upper or lower boundary; `__diffSegment` is a
+ * group key per segment so the area scene builder produces one polygon
+ * per id with the correct fill color.
+ */
+interface SegmentRow {
+    __x: number;
+    /** Upper boundary y value (max of A, B). The area pipeline reads this. */
+    __y: number;
+    /** Lower boundary y value (min of A, B) — picked up as per-datum y0. */
+    __y0: number;
+    /** Segment id. Format: `"seg-<index>-<winner>"`. */
+    __diffSegment: string;
+    /** Which series is on top in this segment ("A" or "B"). Drives fill. */
+    __diffWinner: "A" | "B";
+    /** Original A value at this x (or interpolated at crossovers). */
+    __valA: number;
+    /** Original B value at this x (or interpolated at crossovers). */
+    __valB: number;
+    /** Original datum (for tooltip lookup at non-crossover vertices). */
+    __sourceDatum?: Datum;
+}
+/**
+ * Walk sorted data, splitting at each A↔B crossover. Inserts an
+ * interpolated vertex on BOTH sides of every crossover so adjacent
+ * segments meet at a zero-width point (no jagged edges).
+ *
+ * Non-finite rows are skipped; the algorithm tracks the most recent
+ * VALID non-tie row (not the index neighbor) for crossover detection,
+ * so a non-finite gap doesn't drop a crossover that straddles it.
+ *
+ * Tie rows (a === b) are handled distinctly from non-tie rows:
+ *
+ *   - When a tie row sits BETWEEN two non-tie rows with the SAME
+ *     winner, the tie is emitted in that winner's segment as a
+ *     zero-width vertex.
+ *   - When a tie row sits between non-tie rows with DIFFERENT winners,
+ *     the FIRST tie of the run becomes the crossover vertex. The old
+ *     segment closes at the tie's x, the new segment opens at the same
+ *     point, and any subsequent tie rows (multi-tie runs) carry into
+ *     the new segment as zero-width vertices.
+ *
+ * This preserves the data's actual zero-difference point: if the user
+ * supplied a tie row explicitly, the fill switches color exactly at
+ * that x rather than at a linear-interpolated x that ignored the tie.
+ *
+ * Exported for direct unit-testing — the area pipeline depends on the
+ * exact crossover-vertex shape produced here.
+ */
+export declare function computeDifferenceSegments<TDatum extends Datum>(raw: TDatum[], getX: (d: TDatum) => number, getA: (d: TDatum) => number, getB: (d: TDatum) => number): SegmentRow[];
+/**
+ * DifferenceChart — fills the area between two series with a color
+ * that switches based on which series is higher at each x. Crossover
+ * points are interpolated so segments meet cleanly. Both series can
+ * optionally be drawn as overlay lines on top of the fill.
+ *
+ * Classic uses: temperature anomaly (actual vs. normal), forecast
+ * accuracy (actual vs. predicted), budget variance, A/B comparison.
+ *
+ * @example
+ * ```tsx
+ * <DifferenceChart
+ *   data={[
+ *     { date: 1, actual: 50, forecast: 45 },
+ *     { date: 2, actual: 52, forecast: 60 },
+ *     { date: 3, actual: 70, forecast: 58 },
+ *   ]}
+ *   xAccessor="date"
+ *   seriesAAccessor="actual"
+ *   seriesBAccessor="forecast"
+ *   seriesALabel="Actual"
+ *   seriesBLabel="Forecast"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Streaming via push API — omit `data`, push raw {x, a, b} rows.
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ * useEffect(() => {
+ *   const id = setInterval(() => {
+ *     const t = Date.now()
+ *     ref.current?.push({ x: t, a: 50 + Math.random() * 10, b: 50 + Math.random() * 10 })
+ *   }, 500)
+ *   return () => clearInterval(id)
+ * }, [])
+ * return <DifferenceChart ref={ref} xAccessor="x" seriesAAccessor="a" seriesBAccessor="b" />
+ * ```
+ */
+export declare const DifferenceChart: {
+    <TDatum extends Datum = Datum>(props: DifferenceChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export {};

package/dist/components/charts/xy/LineChart.d.ts

@@ -1,6 +1,6 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -29,7 +29,7 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -181,6 +181,30 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * envelope around the extrapolated forecast region.
      */
     forecast?: ForecastConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the line. Differs from
+     * `forecast`/`anomaly` (computed envelopes around a series) by being
+     * pure data passthrough — provide `y0Accessor` / `y1Accessor` and the
+     * band is drawn between them at each x.
+     *
+     * Pass an array for percentile fans (e.g. p25/p75 on top of p10/p90).
+     * Each band participates in y-extent auto-derivation, so a tall band
+     * can never get clipped. The hovered datum is enriched with
+     * `band: { y0, y1 }` (first band) and `bands: [...]` (all bands) so
+     * tooltip functions can read the envelope without re-running the
+     * accessors.
+     *
+     * @example
+     * ```tsx
+     * <LineChart
+     *   data={[{ time, average, min, max }, ...]}
+     *   xAccessor="time"
+     *   yAccessor="average"
+     *   band={{ y0Accessor: "min", y1Accessor: "max" }}
+     * />
+     * ```
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
      * that side data-derived.

package/dist/components/charts/xy/Scatterplot.d.ts

@@ -5,6 +5,8 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type RegressionProp } from "../shared/regressionUtils";
+import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
  * Scatterplot component props
  */
@@ -12,9 +14,13 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     /** Array of data points. Each point should have x and y properties. */
     data?: TDatum[];
     /** Field name or function to access x values @default "x" */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /** Field name or function to access y values @default "y" */
     yAccessor?: ChartAccessor<TDatum, number>;
+    /** X scale type @default "linear" */
+    xScaleType?: "linear" | "log" | "time";
+    /** Y scale type @default "linear" */
+    yScaleType?: "linear" | "log";
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data or custom colors array @default "category10" */
@@ -45,6 +51,38 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     legendPosition?: LegendPosition;
     /** Annotation objects to render on the chart */
     annotations?: Datum[];
+    /**
+     * Overlay a regression line on the scatter. Accepts:
+     * - `true` — linear regression with default styling
+     * - `"linear"` | `"polynomial"` | `"loess"` — pick a method
+     * - `RegressionConfig` — full control (method, bandwidth, order,
+     *   color, strokeWidth, strokeDasharray, label)
+     *
+     * Sugar over `annotations={[{ type: "trend", … }]}` — for richer
+     * setups (multiple regression lines, custom anchoring) drop into
+     * the annotations array directly.
+     *
+     * @example
+     * ```tsx
+     * <Scatterplot data={d} xAccessor="x" yAccessor="y" regression />
+     * <Scatterplot data={d} xAccessor="x" yAccessor="y" regression="loess" />
+     * <Scatterplot data={d} xAccessor="x" yAccessor="y"
+     *   regression={{ method: "polynomial", order: 3, color: "#ef4444", label: "Cubic" }} />
+     * ```
+     */
+    regression?: RegressionProp;
+    /**
+     * Forecast overlay — extends the scatter with tagged future
+     * points + (optional) confidence-envelope annotations. Same shape
+     * as LineChart's `forecast` prop.
+     */
+    forecast?: ForecastConfig;
+    /**
+     * Anomaly overlay — adds a ±σ band annotation and per-point
+     * anomaly dots. Standalone (without forecast) gives raw anomaly
+     * detection on the scatter.
+     */
+    anomaly?: AnomalyConfig;
     /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
     xExtent?: [number | undefined, number | undefined] | [number];
     /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */

package/dist/components/geometry/ribbonGeometry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared ribbon geometry — emits both the SVG path-D string and the
+ * centerline cubic-bezier cache for a sankey-style band.
+ *
+ * Both SankeyDiagram (via `areaLink` in `./sankeyLinks`) and
+ * ProcessSankey (via the HOC's ribbon-spec construction) need to
+ * draw the same M-C-L-C-Z trapezoid-cap-with-bezier-sides shape and
+ * provide a matching 4-point centerline bezier for the particle
+ * pool. The two charts compute their inputs differently — Sankey
+ * reads (x0/x1/y0/y1, sankeyWidth) from the d3-sankey layout while
+ * ProcessSankey computes (sx, sTop, sBot, tx, tTop, tBot, cp1X, cp2X)
+ * from its temporal attachment math — but the *emission* is shared.
+ *
+ * For Sankey:  cp1X = xi(curvature), cp2X = xi(1-curvature) (smooth
+ *              S-curve, symmetric around the midpoint).
+ * For ProcessSankey: cp1X = cp2X = cx where `cx` depends on
+ *              `ribbonLane` ("source"/"target"/"both") — concentrates
+ *              the bend at a chosen x position.
+ */
+import type { BezierCache } from "../stream/networkTypes";
+export interface RibbonGeometryInput {
+    /** Source x coordinate. */
+    sx: number;
+    /** Source band top (y at source end, smaller y). */
+    sTop: number;
+    /** Source band bottom (y at source end, larger y). */
+    sBot: number;
+    /** Target x coordinate. */
+    tx: number;
+    /** Target band top. */
+    tTop: number;
+    /** Target band bottom. */
+    tBot: number;
+    /** x of the near-source bezier control point. The top curve uses
+     *  `(cp1X, sTop)` as its first control point and the bottom curve
+     *  uses `(cp1X, sBot)` as its last (mirrored). */
+    cp1X: number;
+    /** x of the near-target bezier control point. The top curve uses
+     *  `(cp2X, tTop)` as its second control point and the bottom curve
+     *  uses `(cp2X, tBot)` as its first (mirrored). */
+    cp2X: number;
+}
+export interface RibbonGeometryOutput {
+    /** Closed SVG path describing the visible ribbon band. */
+    pathD: string;
+    /** Centerline cubic for the particle pool. Matches the shape
+     *  `NetworkPipelineStore.buildStandardBezier` produces for sankey
+     *  edges, so both ribbon kinds drive the shared particle
+     *  pipeline identically. */
+    bezier: BezierCache;
+}
+/**
+ * Build both the visible-ribbon path-D and the centerline bezier
+ * cache from a single set of geometric inputs.
+ *
+ * @example
+ * ```ts
+ * // SankeyDiagram (smooth curvature-based S-curve):
+ * const xi = interpolateNumber(source.x1, target.x0)
+ * buildRibbonGeometry({
+ *   sx: source.x1, tx: target.x0,
+ *   sTop: edge.y0 - edge.sankeyWidth / 2,
+ *   sBot: edge.y0 + edge.sankeyWidth / 2,
+ *   tTop: edge.y1 - edge.sankeyWidth / 2,
+ *   tBot: edge.y1 + edge.sankeyWidth / 2,
+ *   cp1X: xi(0.5),  cp2X: xi(0.5),  // curvature defaults to 0.5
+ * })
+ *
+ * // ProcessSankey (lane-aware bend):
+ * const cx = ribbonLane === "source" ? sx + (tx - sx) * 0.85
+ *          : ribbonLane === "target" ? sx + (tx - sx) * 0.15
+ *          : (sx + tx) / 2
+ * buildRibbonGeometry({ sx, sTop, sBot, tx, tTop, tBot, cp1X: cx, cp2X: cx })
+ * ```
+ */
+export declare function buildRibbonGeometry(input: RibbonGeometryInput): RibbonGeometryOutput;

package/dist/components/semiotic-ai.d.ts

@@ -1,5 +1,6 @@
 export { LineChart } from "./charts/xy/LineChart";
 export { AreaChart } from "./charts/xy/AreaChart";
+export { DifferenceChart } from "./charts/xy/DifferenceChart";
 export { StackedAreaChart } from "./charts/xy/StackedAreaChart";
 export { Scatterplot } from "./charts/xy/Scatterplot";
 export { ConnectedScatterplot } from "./charts/xy/ConnectedScatterplot";
@@ -30,6 +31,7 @@ export { SwimlaneChart } from "./charts/ordinal/SwimlaneChart";
 export { ForceDirectedGraph } from "./charts/network/ForceDirectedGraph";
 export { ChordDiagram } from "./charts/network/ChordDiagram";
 export { SankeyDiagram } from "./charts/network/SankeyDiagram";
+export { ProcessSankey } from "./charts/network/ProcessSankey";
 export { TreeDiagram } from "./charts/network/TreeDiagram";
 export { Treemap } from "./charts/network/Treemap";
 export { CirclePack } from "./charts/network/CirclePack";