@photonviz/core 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -83,6 +83,82 @@ interface Bounds {
 /** RGBA in 0..1. */
 type Color = readonly [number, number, number, number];
 
+type RGB = [number, number, number];
+/**
+ * Built-in continuous colormaps.
+ *
+ * Sequential (`viridis`, `plasma`, `inferno`, `magma`, `cividis`, `turbo`,
+ * `grayscale`) run low → high and are the default for magnitude data.
+ * Diverging (`coolwarm`, `RdBu`, `BrBG`, `spectral`) have a neutral midpoint —
+ * pair them with a domain centred on the reference value (see
+ * {@link symmetricDomain}). Cyclic (`twilight`) wraps, for phase / angle data.
+ *
+ * `viridis`, `cividis` and `turbo` stay legible with common colour-vision
+ * deficiencies; `RdBu` and `BrBG` are the CVD-safe diverging choices.
+ */
+type BuiltinColormapName = "viridis" | "plasma" | "inferno" | "magma" | "cividis" | "turbo" | "grayscale" | "coolwarm" | "RdBu" | "BrBG" | "spectral" | "twilight";
+/**
+ * A colormap name. Built-ins autocomplete; any other string resolves through the
+ * registry, so `registerColormap("brand", […])` makes `"brand"` usable anywhere a
+ * colormap is accepted. Unknown names fall back to `viridis`.
+ */
+type ColormapName = BuiltinColormapName | (string & {});
+/** A colormap given inline: a name, or anchor colours interpolated evenly. */
+type ColormapSpec = ColormapName | ReadonlyArray<RGB | string>;
+/** Which family a colormap belongs to — drives colorbar defaults and doc hints. */
+type ColormapKind = "sequential" | "diverging" | "cyclic";
+/**
+ * A colormapped layer's scale, surfaced to the plot so it can draw a colorbar.
+ * Returned by `Layer.colorInfo()` / `Layer3D.colorInfo()`.
+ */
+interface ColorInfo {
+    colormap: ColormapSpec;
+    /** The value range the colormap spans, after any auto-fit. */
+    domain: readonly [number, number];
+    /** Caption for the bar — usually the series name. */
+    label?: string;
+}
+/** Family of each built-in colormap. Custom ones default to `"sequential"`. */
+declare const COLORMAP_KIND: Record<BuiltinColormapName, ColormapKind>;
+/** Every registered colormap name (built-ins first, then anything registered). */
+declare function colormapNames(): string[];
+/**
+ * Register a custom colormap under `name`, so it can be used anywhere a
+ * colormap name is accepted — `plot.addHeatmap({ …, colormap: "brand" })`.
+ * Anchors are evenly spaced and linearly interpolated; pass `[r,g,b]` triples in
+ * 0..1 or CSS hex strings. Re-registering a name replaces it.
+ */
+declare function registerColormap(name: string, stops: ReadonlyArray<RGB | string>): void;
+/**
+ * The raw `256×3` (r,g,b in 0..1) lookup table for a colormap, cached per name.
+ * Hot loops (heatmap, colorBy, …) can index it directly — `j = ((clamp(t)*255)|0)*3`
+ * — to avoid a per-element closure call and tuple allocation.
+ */
+declare function colormapLUT(spec?: ColormapSpec): Float32Array;
+/**
+ * Returns a `(t in 0..1) => RGB` sampler (LUT-backed). Accepts a built-in or
+ * registered name, or inline anchor colours.
+ */
+declare function colormap(spec?: ColormapSpec): (t: number) => RGB;
+/**
+ * A sampler for a custom ramp given as anchor colours (evenly spaced, linearly
+ * interpolated). Accepts `[r,g,b]` triples in 0..1 or CSS hex strings.
+ */
+declare function colormapFromStops(stops: ReadonlyArray<RGB | string>): (t: number) => RGB;
+/** The reverse of a colormap — high values take the low end's colour. */
+declare function reverseColormap(spec?: ColormapSpec): (t: number) => RGB;
+/**
+ * Quantize a colormap into `steps` flat bands — useful when readers must match
+ * a colour back to a legend entry rather than judge a continuous shade.
+ */
+declare function discreteColormap(spec: ColormapSpec, steps: number): (t: number) => RGB;
+/**
+ * A domain centred on `center` (default 0) that covers `values` — what a
+ * diverging colormap needs so its neutral midpoint lands on the reference value
+ * instead of drifting with the data.
+ */
+declare function symmetricDomain(values: ArrayLike<number>, center?: number): [number, number];
+
 /**
  * Shared data→clip transform used by every layer's vertex shader.
  *
@@ -128,6 +204,11 @@ interface Layer {
         x: Range;
         y: Range;
     } | null;
+    /**
+     * Colormap + value range, when this layer maps values to colours — the plot
+     * uses it to draw a colorbar. `null`/absent for solid-coloured layers.
+     */
+    colorInfo?(): ColorInfo | null;
     draw(state: DrawState): void;
     dispose(): void;
 }
@@ -460,17 +541,6 @@ declare class OhlcLayer implements Layer {
     dispose(): void;
 }
 
-type RGB = [number, number, number];
-type ColormapName = "viridis" | "plasma" | "coolwarm" | "grayscale";
-/**
- * The raw `256×3` (r,g,b in 0..1) lookup table for a colormap, cached per name.
- * Hot loops (heatmap, colorBy, …) can index it directly — `j = ((clamp(t)*255)|0)*3`
- * — to avoid a per-element closure call and tuple allocation.
- */
-declare function colormapLUT(name?: ColormapName): Float32Array;
-/** Returns a `(t in 0..1) => RGB` sampler for the named colormap (LUT-backed). */
-declare function colormap(name?: ColormapName): (t: number) => RGB;
-
 interface ContourOptions {
     /** Row-major grid values, length `cols * rows` (row 0 at the bottom). */
     values: ArrayLike<number>;
@@ -484,7 +554,9 @@ interface ContourOptions {
     levels?: number[] | number;
     /** Single line color; if omitted, levels are colored by a colormap. */
     color?: string | Color;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
+    /** Series name — used as the colorbar caption. */
+    name?: string;
     /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
     renderType?: RenderType;
     yAxis?: string;
@@ -505,6 +577,9 @@ declare class ContourLayer implements Layer {
     private rows;
     private levelsOpt;
     private cmap;
+    private cmapName;
+    private cInfo;
+    private label?;
     private fixedColor;
     private usage;
     constructor(gl: WebGL2RenderingContext, opts: ContourOptions);
@@ -512,6 +587,7 @@ declare class ContourLayer implements Layer {
     private build;
     /** Replace the scalar field and recompute the iso lines (for streaming). */
     setData(values: ArrayLike<number>, cols?: number, rows?: number): void;
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -521,6 +597,7 @@ declare class ContourLayer implements Layer {
 }
 
 /** A per-point error, given as one value for all points or an array. */
+/** A per-point error array, or one value applied to every point. */
 type ErrInput = ArrayLike<number> | number;
 interface ErrorBarOptions {
     x: ArrayLike<number>;
@@ -671,9 +748,11 @@ interface HeatmapOptions {
         x: Range;
         y: Range;
     };
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Value range mapped to the colormap. Defaults to the data min/max. */
     domain?: Range;
+    /** Series name — used as the colorbar caption. */
+    name?: string;
     /** Bilinear filtering (default true) vs. hard cells. */
     smooth?: boolean;
     /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
@@ -696,11 +775,15 @@ declare class HeatmapLayer implements Layer {
     private fixedDomain;
     private cols;
     private rows;
+    private cmapName;
+    private cInfo;
+    private label?;
     constructor(gl: WebGL2RenderingContext, opts: HeatmapOptions);
     /** Bake a `cols*rows` value grid into the RGBA data texture via the colormap. */
     private uploadValues;
     /** Replace the value grid and re-bake the data texture (for streaming). */
     setData(values: ArrayLike<number>, cols?: number, rows?: number): void;
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -714,9 +797,11 @@ interface HexbinOptions {
     y: ArrayLike<number>;
     /** Hex radius in data units. Defaults to ~1/30 of the x-extent. */
     radius?: number;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Count range mapped to the colormap. Defaults to [1, maxCount]. */
     domain?: Range;
+    /** Series name — used as the colorbar caption. */
+    name?: string;
     /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
     renderType?: RenderType;
     yAxis?: string;
@@ -738,12 +823,16 @@ declare class HexbinLayer implements Layer {
     private cmap;
     private explicitRadius;
     private domain;
+    private cmapName;
+    private cInfo;
+    private label?;
     private usage;
     constructor(gl: WebGL2RenderingContext, opts: HexbinOptions);
     /** Bin the points into hex cells; sets radius, refs, bounds and cell count. */
     private build;
     /** Replace the point arrays, re-bin and re-upload the cells (for streaming). */
     setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -856,6 +945,12 @@ interface LineOptions {
      * Default 4.
      */
     miterLimit?: number;
+    /**
+     * Dash pattern in CSS pixels, alternating on/off lengths (Canvas
+     * `setLineDash` semantics) — e.g. `[6, 4]`. Up to 8 entries. Dashing turns
+     * decimation off, since a dashed line is a low-point-count annotation.
+     */
+    dash?: number[];
     /**
      * Min/max decimate very large series to ~2 points per pixel column when
      * zoomed out (preserves peaks). Requires monotonic x; auto-detected. Default true.
@@ -888,6 +983,10 @@ declare class LineLayer implements Layer {
     private joinStyle;
     private miterLimit;
     private decimateOn;
+    /** Dash pattern in CSS px (empty = solid) and its period. */
+    private dash;
+    private dashPeriod;
+    private distBuf;
     private monotonic;
     private gpuDec;
     private step?;
@@ -937,7 +1036,7 @@ interface PatchesOptions {
     /** Default fill for patches without their own `color`/`value`. */
     color?: string | Color;
     /** Color patches by `value` through this colormap (choropleth). */
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Value range mapped to [0,1] for the colormap. Defaults to the data min/max. */
     domain?: Range;
     /** Fill opacity, 0..1. Default 1. */
@@ -971,12 +1070,15 @@ declare class PatchesLayer implements Layer {
     private opacity;
     private cmap;
     private domainOpt;
+    private cmapName;
+    private cInfo;
     private usage;
     constructor(gl: WebGL2RenderingContext, opts: PatchesOptions);
     /** Triangulate the patches and recompute refs/bounds/vertexCount into position/color arrays. */
     private build;
     /** Replace the patches and re-upload (for streaming). */
     setData(patches: Patch[]): void;
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -991,7 +1093,7 @@ interface PieOptions {
     /** Explicit per-slice colors; falls back to `colormap`, then a default palette. */
     colors?: (string | Color)[];
     /** Color slices by index through this colormap instead of the palette. */
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Center in data space. Default `[0, 0]`. */
     center?: [number, number];
     /** Outer radius in data units. Default `1`. */
@@ -1063,7 +1165,7 @@ interface QuiverOptions {
     /** Color each arrow by a value (default: its magnitude) through a colormap. */
     colorBy?: {
         values?: ArrayLike<number>;
-        colormap?: ColormapName;
+        colormap?: ColormapSpec;
         domain?: Range;
     };
     /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
@@ -1089,6 +1191,8 @@ declare class QuiverLayer implements Layer {
     private useVertexColor;
     private explicitScale;
     private colorBy;
+    private cInfo;
+    private label?;
     private usage;
     private count;
     private xRef;
@@ -1101,6 +1205,7 @@ declare class QuiverLayer implements Layer {
     private build;
     /** Replace the data and re-upload (for streaming). */
     setData(x: ArrayLike<number>, y: ArrayLike<number>, u: ArrayLike<number>, v: ArrayLike<number>): void;
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -1117,6 +1222,16 @@ interface ScatterOptions {
     color?: string | Color;
     /** Marker diameter in CSS pixels. */
     size?: number;
+    /**
+     * Per-point diameter in CSS pixels — a bubble chart. Overrides {@link size}
+     * wherever it is `> 0`; entries of `0` fall back to the uniform size.
+     */
+    sizes?: ArrayLike<number>;
+    /**
+     * Explicit per-point colors. Overrides {@link color}; ignored when
+     * {@link colorBy} is set (that drives the same per-point buffer).
+     */
+    colors?: ReadonlyArray<string | Color>;
     /** Marker glyph. Default `"circle"`. */
     marker?: MarkerShape;
     name?: string;
@@ -1130,7 +1245,7 @@ interface ScatterOptions {
     /** Color each point by a value through a colormap. */
     colorBy?: {
         values: ArrayLike<number>;
-        colormap?: ColormapName;
+        colormap?: ColormapSpec;
         /** Value range mapped to [0,1]. Defaults to the data min/max. */
         domain?: Range;
     };
@@ -1149,10 +1264,13 @@ declare class ScatterLayer implements Layer {
     private uniforms;
     private count;
     private size;
+    /** Largest marker diameter in play, for the hover hit gate. */
+    private maxSize;
     private marker;
     private usage;
     private color;
     private useVertexColor;
+    private cInfo;
     private labels?;
     private xRef;
     private yRef;
@@ -1161,6 +1279,7 @@ declare class ScatterLayer implements Layer {
     private xBounds;
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: ScatterOptions);
+    colorInfo(): ColorInfo | null;
     bounds(): {
         x: Range;
         y: Range;
@@ -1399,6 +1518,40 @@ declare function downloadCanvas(canvas: HTMLCanvasElement, filename?: string, ty
 /** Copy a canvas to the clipboard as a PNG. Throws where the browser can't. */
 declare function copyCanvasToClipboard(canvas: HTMLCanvasElement): Promise<void>;
 
+interface ColorbarOptions {
+    /** Which side of the plot region the bar sits on. Default `"right"`. */
+    position?: "right" | "left";
+    /** Caption above the bar. Defaults to the layer's `name`. */
+    label?: string;
+    /** Bar thickness in px. Default 12. */
+    width?: number;
+    /** Fraction of the plot height the bar spans, 0..1. Default 0.72. */
+    heightFraction?: number;
+    /** Target number of tick labels. Default 5. */
+    ticks?: number;
+    /** Formats a tick value. Defaults to a compact 3-significant-digit formatter. */
+    format?: (value: number) => string;
+    textColor?: string;
+    borderColor?: string;
+    font?: string;
+}
+/** Resolved chrome colours, so the bar can match either plot theme. */
+interface ColorbarTheme {
+    text: string;
+    border: string;
+    font: string;
+}
+/**
+ * A CSS `linear-gradient` for a colormap. `to top` puts the domain minimum at
+ * the bottom, matching the tick labels drawn beside it.
+ */
+declare function colormapGradient(spec: ColormapSpec, stops?: number): string;
+/**
+ * Fill `host` with one bar per colour scale, stacked vertically inside
+ * `regionHeight` px. Hides the host when there is nothing to show.
+ */
+declare function renderColorbars(host: HTMLElement, infos: readonly ColorInfo[], opts: ColorbarOptions, theme: ColorbarTheme, regionHeight: number): void;
+
 interface AxisScaleOptions {
     type?: ScaleType;
     /** Fixed domain. If omitted, the axis autoscales to the data. */
@@ -1422,6 +1575,11 @@ interface LegendOptions {
     border?: string;
     textColor?: string;
     font?: string;
+    /**
+     * Click a legend entry to show/hide its series (axes re-fit to what is left).
+     * Entries are focusable and respond to Enter/Space. Default true.
+     */
+    interactive?: boolean;
 }
 interface YAxisOptions extends AxisConfig {
     type?: ScaleType;
@@ -1584,6 +1742,13 @@ interface PlotOptions {
     title?: string | PlotTitleOptions;
     /** Show a legend of named series. `true` uses defaults; pass an object to place/style it. */
     legend?: boolean | LegendOptions;
+    /**
+     * Show a colorbar for every layer that maps values to colours (heatmap,
+     * hexbin, contour, choropleth patches, `colorBy` scatter/quiver). Enabled by
+     * default — a colour scale nobody can read is not a scale. Pass `false` to
+     * suppress it, or an object to place/style it.
+     */
+    colorbar?: boolean | ColorbarOptions;
     margin?: Partial<Layout["margin"]>;
     /** Enable wheel-zoom and drag interaction. Default true. */
     interactive?: boolean;
@@ -1699,10 +1864,19 @@ declare class Plot {
     private title;
     private legend;
     private legendDiv;
+    private colorbar;
+    private colorbarDiv;
+    /** Ids of layers hidden via the legend / {@link setLayerVisible}. */
+    private hidden;
+    private visibilityCbs;
     constructor(container: HTMLElement, options?: PlotOptions);
     private makeCanvas;
     /** Margins grow to make room for extra y axes on each side. */
     private computeMargin;
+    /** Colour scales reported by the layers, in draw order. */
+    private colorInfos;
+    /** Rebuild + place the colorbar stack in the reserved side margin. */
+    private updateColorbars;
     private layout;
     /** Pixel x-position (and title x) for each y axis, by draw order per side. */
     private yAxisPositions;
@@ -1719,6 +1893,12 @@ declare class Plot {
     add<T extends Layer>(layer: T): T;
     /** The shared WebGL2 context, for constructing custom layers. */
     get context(): WebGL2RenderingContext;
+    /**
+     * The container this plot renders into (already `position: relative`), for
+     * custom overlays — a chart-specific tooltip, a colorbar, a caption. Append
+     * absolutely-positioned children with `zIndex >= 3` to sit above the canvases.
+     */
+    get element(): HTMLElement;
     /**
      * Convert a client (screen) coordinate to data space — the shared x and the
      * primary y. Returns null if the point is outside the plot region. Useful for
@@ -1883,6 +2063,14 @@ declare class Plot {
     render(): void;
     /** Named series that can appear in the legend: any layer exposing name + colorCss. */
     private legendEntries;
+    /** Whether a layer is currently drawn (hidden layers also drop out of autoscale). */
+    isLayerVisible(layer: Layer): boolean;
+    /** Show or hide a layer, re-fitting the auto axes to what remains visible. */
+    setLayerVisible(layer: Layer, visible: boolean): void;
+    /** Flip a layer's visibility. Returns the new state. */
+    toggleLayer(layer: Layer): boolean;
+    /** Subscribe to show/hide changes (legend clicks included). Returns an unsubscribe fn. */
+    onVisibilityChange(cb: (layer: Layer, visible: boolean) => void): () => void;
     /** Rebuild and position the legend overlay (or hide it). */
     private updateLegend;
     /** Draw all annotations, projected through the scales and clipped to the region. */
@@ -2125,12 +2313,7 @@ interface Bounds3 {
     y: Range;
     z: Range;
 }
-/** A colormapped layer's scale, surfaced to {@link Plot3D} for a colorbar. */
-interface ColorInfo {
-    colormap: ColormapName;
-    domain: Range;
-    label?: string;
-}
+
 /** A drawable in the 3D scene. Positions are in world space; Plot3D supplies the MVP. */
 interface Layer3D {
     readonly id: string;
@@ -2166,7 +2349,7 @@ interface Bar3DOptions {
     /** Color bars via a colormap (over `values`, default the heights). */
     colorBy?: {
         values?: ArrayLike<number>;
-        colormap?: ColormapName;
+        colormap?: ColormapSpec;
         domain?: Range;
     };
     name?: string;
@@ -2211,6 +2394,77 @@ declare class Bar3DLayer implements Layer3D {
     dispose(): void;
 }
 
+/** One axis-aligned cuboid: a center plus a full size on each axis. */
+interface Box3D {
+    /** Center (world space). */
+    x: number;
+    y: number;
+    z: number;
+    /** Full size along x / y / z. */
+    w: number;
+    h: number;
+    d: number;
+    /** Fill color; falls back to the layer default. */
+    color?: string | Color;
+    /** Hover tooltip text for this box. */
+    label?: string;
+}
+interface Boxes3DOptions {
+    boxes: Box3D[];
+    /** Default fill for boxes without their own `color`. */
+    color?: string | Color;
+    /**
+     * Fill opacity 0..1. Default 1. Values below 1 blend without depth sorting,
+     * so overlapping translucent boxes can composite out of order.
+     */
+    opacity?: number;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/**
+ * Independently sized, lit cuboids drawn as one instanced call — voxels,
+ * bounding boxes, 3D waterfalls, and the layer blocks of a model diagram.
+ * Unlike {@link Bar3DLayer} every box carries its own center and 3-axis size.
+ */
+declare class Boxes3DLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    readonly colorCss: string;
+    private gl;
+    private program;
+    private vao;
+    private buffers;
+    private instBuf;
+    private uniforms;
+    private count;
+    private b3;
+    private positions;
+    private labels;
+    private base;
+    private opacity;
+    private usage;
+    private lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: Boxes3DOptions);
+    /** Pack the instance attributes, recompute bounds/pick data, and upload. */
+    private build;
+    /** Replace every box. Call `plot.refresh()` afterwards to re-fit + redraw. */
+    setData(boxes: Box3D[]): void;
+    bounds3(): Bounds3 | null;
+    pickData(): {
+        positions: Float32Array<ArrayBuffer>;
+        label: (i: number) => string;
+    } | {
+        positions: Float32Array<ArrayBuffer>;
+        label?: undefined;
+    } | null;
+    /** Set the light direction (world space) and ambient term (0..1). */
+    setLight(dir: [number, number, number], ambient: number): void;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
 interface Contour3DOptions {
     /** Row-major height grid, length `cols * rows`. */
     values: ArrayLike<number>;
@@ -2223,7 +2477,7 @@ interface Contour3DOptions {
     levels?: number[] | number;
     /** Single line color; if omitted, levels are colored by a colormap. */
     color?: string | Color;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     name?: string;
     /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
     renderType?: RenderType;
@@ -2366,7 +2620,7 @@ interface PointCloudOptions {
     sizes?: ArrayLike<number>;
     colorBy?: {
         values: ArrayLike<number>;
-        colormap?: ColormapName;
+        colormap?: ColormapSpec;
         domain?: Range;
     };
     /** Per-point tooltip text (parallel to x/y/z). */
@@ -2422,7 +2676,7 @@ interface Quiver3DOptions {
     color?: string | Color;
     /** Color arrows by magnitude via a colormap. */
     colorBy?: {
-        colormap?: ColormapName;
+        colormap?: ColormapSpec;
         domain?: Range;
     };
     /** Arrowhead length as a fraction of the arrow. Default 0.28. */
@@ -2472,7 +2726,7 @@ interface SurfaceOptions {
     /** World extent of the grid footprint. Defaults to unit indices. */
     extentX?: Range;
     extentZ?: Range;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Series name (colorbar label / legend). */
     name?: string;
     /** Render the grid as a wireframe (lines) instead of a lit filled surface. */
@@ -2528,7 +2782,7 @@ interface VolumeOptions {
         y: Range;
         z: Range;
     };
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Value range mapped to the colormap + opacity. Defaults to the data min/max. */
     domain?: Range;
     /** Overall opacity multiplier. Default 1. */
@@ -2603,9 +2857,43 @@ interface Plot3DOptions {
     downloadButton?: boolean;
     /** Draw grid lines on the back walls of the cube. Default true. */
     gridPlanes?: boolean;
+    /**
+     * How data extents map into the view cube. `"cube"` (default) stretches each
+     * axis independently to fill it — best for surfaces, where relative shape
+     * matters more than units. `"data"` uses one shared scale so proportions are
+     * preserved: a long, thin scene stays long and thin.
+     */
+    aspectMode?: "cube" | "data";
+    /** Draw the bounding box, tick marks and axis labels. Default true. */
+    showAxes?: boolean;
+    /**
+     * Camera projection. `"perspective"` (default) is the natural choice for
+     * surfaces and point clouds; `"orthographic"` removes the perspective divide,
+     * so a long scene keeps a constant scale end-to-end — the right pick for
+     * diagrams. `distance` then sets the visible half-height instead of the eye
+     * distance. Volume raymarching assumes perspective and ignores this.
+     */
+    projection?: "perspective" | "orthographic";
     /** Auto-orbit the camera: `true` for a default speed, or radians/frame. Default off. */
     autoRotate?: boolean | number;
 }
+/** A text label pinned to a point in *data* space, re-projected every frame. */
+interface Label3D {
+    x: number;
+    y: number;
+    z: number;
+    text: string;
+    color?: string;
+    /** CSS `font` shorthand. Default `"11px system-ui, sans-serif"`. */
+    font?: string;
+    /** Screen-space nudge in CSS px, applied after projection. */
+    dx?: number;
+    dy?: number;
+    /** Horizontal alignment about the projected point. Default `"center"`. */
+    align?: CanvasTextAlign;
+    /** Vertical alignment about the projected point. Default `"middle"`. */
+    baseline?: CanvasTextBaseline;
+}
 /** A 3D scatter/surface plot with an orbit camera, axis ticks, and lighting. */
 declare class Plot3D {
     private container;
@@ -2632,9 +2920,14 @@ declare class Plot3D {
     private tickBuf;
     private tickCount;
     private labels;
+    /** User labels anchored in data space (see {@link addLabel3D}). */
+    private dataLabels;
     /** Tick positions in cube space [-1,1], per axis, for the grid planes. */
     private tickCube;
     private gridPlanes;
+    private aspectMode;
+    private showAxes;
+    private projection;
     private gridVao;
     private gridBuf;
     /** Normalize params (world→cube: `cube = s*world + t`), for the volume camera. */
@@ -2670,6 +2963,8 @@ declare class Plot3D {
     addLine3D(opts: Line3DOptions): Line3DLayer;
     /** 3D bars (columns) on an x/z grid, lit and optionally colormapped. */
     addBar3D(opts: Bar3DOptions): Bar3DLayer;
+    /** Independently sized lit cuboids (voxels, bounding boxes, model layer blocks). */
+    addBoxes3D(opts: Boxes3DOptions): Boxes3DLayer;
     /** A 3D vector field (arrows), optionally colored by magnitude. */
     addQuiver3D(opts: Quiver3DOptions): Quiver3DLayer;
     /** 3D iso-height contour lines of a grid, stacked at their level heights. */
@@ -2678,6 +2973,14 @@ declare class Plot3D {
     addIsosurface(opts: IsosurfaceOptions): IsosurfaceLayer;
     /** Direct volume rendering (GPU raymarch) of a 3D scalar field. */
     addVolume(opts: VolumeOptions): VolumeLayer;
+    /**
+     * Pin a text label to a point in data space. It is re-projected every frame,
+     * so it tracks the point as the camera orbits. Returns a disposer that removes
+     * just this label.
+     */
+    addLabel3D(label: Label3D): () => void;
+    /** Remove every data-space label. */
+    clearLabels3D(): void;
     /** Update the light direction (azimuth/elevation, radians) and ambient (0..1). */
     setLight(params: {
         azimuth?: number;
@@ -2721,6 +3024,12 @@ declare class Plot3D {
     private updateLegend;
     /** DOM colorbar for the first colormapped layer (gradient + value range). */
     private updateColorbar;
+    /**
+     * Draw the user's data-space labels. Coordinates come out of the projection in
+     * device px; we scale the context by dpr instead so the caller's `font` string
+     * means CSS px, and outline each label so it stays readable over any fill.
+     */
+    private drawDataLabels;
     private drawLabels;
     private attachControls;
     private buildControls;
@@ -2835,6 +3144,126 @@ interface Density {
  */
 declare function kde(values: ArrayLike<number>, lo: number, hi: number, points?: number, bandwidth?: number): Density;
 
+/** Window (taper) applied to a frame before an FFT, to suppress spectral leakage. */
+type WindowName = "rectangular" | "hann" | "hamming" | "blackman" | "bartlett";
+/**
+ * Sample a window function over `n` points.
+ *
+ * `hann` is the sane default; `hamming` trades a touch of leakage for a lower
+ * first sidelobe; `blackman` suppresses sidelobes hardest at the cost of
+ * resolution; `bartlett` (triangular) is cheap; `rectangular` is no window at
+ * all — use it only when the frame already contains whole periods.
+ */
+declare function windowFunction(name: WindowName, n: number): Float64Array;
+/** A one-sided power spectral density estimate. */
+interface Psd {
+    /** Frequencies in Hz (or cycles/sample when `sampleRate` is 1). */
+    frequencies: Float64Array;
+    /** Power per bin, in units²/Hz. */
+    power: Float64Array;
+}
+interface WelchOptions {
+    /** Samples per segment (rounded down to a power of two). Default 256. */
+    segment?: number;
+    /** Overlap between segments, 0..1. Default 0.5. */
+    overlap?: number;
+    window?: WindowName;
+    sampleRate?: number;
+}
+/**
+ * Welch's method: average the periodograms of overlapping windowed segments.
+ * Trades frequency resolution for a far lower-variance estimate than a single
+ * FFT of the whole signal — the standard way to read a noisy spectrum.
+ */
+declare function welch(signal: ArrayLike<number>, opts?: WelchOptions): Psd;
+/**
+ * Savitzky–Golay smoothing: least-squares fit a polynomial over a sliding
+ * window. Unlike a moving average it preserves peak height and width, which is
+ * why spectroscopy and sensor pipelines reach for it.
+ *
+ * `window` must be odd (rounded up) and larger than `order`. Edges are handled
+ * by clamping to the nearest sample.
+ */
+declare function savitzkyGolay(values: ArrayLike<number>, window?: number, order?: number): Float64Array;
+/** A correlation sequence indexed by lag. */
+interface Correlation {
+    /** Lags, from `-maxLag` to `+maxLag`. */
+    lags: Int32Array;
+    /** Correlation at each lag. */
+    values: Float64Array;
+}
+/**
+ * Cross-correlation of two series over ±`maxLag`. `normalize` (default true)
+ * divides by the zero-lag autocorrelations, so the result is a correlation
+ * coefficient in −1..1 and the peak lag reads directly as "b lags a by k".
+ * Pass the same array twice for an autocorrelation.
+ */
+declare function crossCorrelate(a: ArrayLike<number>, b: ArrayLike<number>, maxLag?: number, normalize?: boolean): Correlation;
+
+/**
+ * Fits and summaries that turn a scatter into a claim: a trend line with a
+ * confidence band, a local-regression smoother, an ECDF, a correlation matrix.
+ * Pure — every function takes arrays and returns arrays.
+ */
+/** An ordinary-least-squares fit of `y = slope·x + intercept`. */
+interface LinearFit {
+    slope: number;
+    intercept: number;
+    /** Coefficient of determination, 0..1. */
+    r2: number;
+    /** Standard error of the residuals. */
+    stderr: number;
+    /** Points used (non-finite pairs are skipped). */
+    n: number;
+    /** Evaluate the fit at an x. */
+    predict(x: number): number;
+}
+/** Least-squares straight line through (x, y), skipping non-finite pairs. */
+declare function linearRegression(x: ArrayLike<number>, y: ArrayLike<number>): LinearFit;
+/** A smoothed curve sampled on a grid, optionally with a band around it. */
+interface Trend {
+    x: Float64Array;
+    y: Float64Array;
+    /** Lower/upper band, when the caller asked for one. */
+    lower?: Float64Array;
+    upper?: Float64Array;
+}
+/**
+ * Sample a linear fit across the data range, with an optional ±`k`·stderr band.
+ * `points` controls the resolution (2 is enough for the line itself).
+ */
+declare function linearTrend(x: ArrayLike<number>, y: ArrayLike<number>, opts?: {
+    points?: number;
+    band?: number;
+}): Trend;
+/**
+ * LOESS: locally-weighted linear regression with a tricube kernel. `bandwidth`
+ * is the fraction of points in each local neighbourhood (0..1, default 0.3) —
+ * larger is smoother. Returns the fit sampled on a sorted grid, so it can be
+ * drawn straight as a line.
+ */
+declare function loess(x: ArrayLike<number>, y: ArrayLike<number>, opts?: {
+    bandwidth?: number;
+    points?: number;
+}): Trend;
+/** The empirical CDF as a step function: sorted values against their cumulative proportion. */
+declare function ecdf(values: ArrayLike<number>): {
+    x: Float64Array;
+    y: Float64Array;
+};
+/** Standardize to zero mean and unit variance (population sd). Non-finite entries pass through. */
+declare function zscore(values: ArrayLike<number>): Float64Array;
+/** Pearson correlation of two equal-length series (0 when either is constant). */
+declare function correlation(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * Pearson correlation matrix of `columns`, row-major and `k×k`. Feed it straight
+ * to `addHeatmap` with a diverging colormap and `symmetricDomain`.
+ */
+declare function corrMatrix(columns: ReadonlyArray<ArrayLike<number>>): {
+    values: Float64Array;
+    size: number;
+};
+
 /** Map a layer's {@link RenderType} to a WebGL buffer-usage hint (default STATIC_DRAW). */
 declare function bufferUsage(gl: WebGL2RenderingContext, renderType?: RenderType): number;
 /** Compile + link a vertex/fragment program. */
@@ -2951,6 +3380,49 @@ interface FibLevel {
 /** Fibonacci retracement price levels between a `high` and `low` (standard ratios). */
 declare function fibRetracements(high: number, low: number, ratios?: number[]): FibLevel[];
 
+/**
+ * Commodity Channel Index: how far the typical price sits from its own moving
+ * average, scaled by mean deviation. ±100 is the conventional band.
+ */
+declare function cci(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>, period?: number): Float64Array;
+/**
+ * Money Flow Index — RSI weighted by volume, so a move on thin volume counts
+ * for less. 0..100, with 20/80 the usual oversold/overbought lines.
+ */
+declare function mfi(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>, volume: ArrayLike<number>, period?: number): Float64Array;
+/** Williams %R: where the close sits in the `period` high-low range, as −100..0. */
+declare function williamsR(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>, period?: number): Float64Array;
+/** Aroon: how recently the `period` high and low were set, plus their difference. */
+interface Aroon {
+    up: Float64Array;
+    down: Float64Array;
+    oscillator: Float64Array;
+}
+/**
+ * Aroon Up/Down — 100 means the extreme was set this bar, 0 means `period` bars
+ * ago. The oscillator (up − down) reads as trend strength and direction.
+ */
+declare function aroon(high: ArrayLike<number>, low: ArrayLike<number>, period?: number): Aroon;
+/** Donchian Channels: the rolling `period` high/low and their midline (turtle breakout bands). */
+declare function donchian(high: ArrayLike<number>, low: ArrayLike<number>, period?: number): Channel;
+/**
+ * Parabolic SAR — the trailing stop-and-reverse dots. `step` is the
+ * acceleration increment and `max` its ceiling (Wilder's 0.02 / 0.2).
+ */
+declare function parabolicSar(high: ArrayLike<number>, low: ArrayLike<number>, step?: number, max?: number): Float64Array;
+/** Classic floor-trader pivot levels for the next session. */
+interface PivotLevels {
+    pivot: number;
+    r1: number;
+    r2: number;
+    r3: number;
+    s1: number;
+    s2: number;
+    s3: number;
+}
+/** Pivot points from one session's high/low/close, for the session that follows. */
+declare function pivotPoints(high: number, low: number, close: number): PivotLevels;
+
 /**
  * Chart-type transforms: turn raw OHLC(V) into the geometry a specialist finance
  * chart needs. Each returns plain arrays you render with existing layers
@@ -3043,6 +3515,39 @@ interface DepthCurves {
  * returns cumulative-volume step curves ready for two step-area layers.
  */
 declare function depth(bids: ArrayLike<readonly [number, number]>, asks: ArrayLike<readonly [number, number]>): DepthCurves;
+/** One resampled bar, with the timestamp of the bucket it covers. */
+interface ResampledOhlc extends OhlcArrays {
+    /** Bucket start time (epoch ms). */
+    time: Float64Array;
+    /** Summed volume per bucket, when volume was supplied. */
+    volume?: Float64Array;
+}
+/**
+ * Roll bars up to a coarser timeframe — 1m candles into 1h, daily into weekly.
+ * Buckets are aligned to multiples of `bucketMs` from the epoch, so the same
+ * input always produces the same boundaries. Empty buckets are skipped rather
+ * than filled, which is what a market calendar wants.
+ */
+declare function resampleOhlc(time: ArrayLike<number>, ohlc: Ohlc, bucketMs: number, volume?: ArrayLike<number>): ResampledOhlc;
+/** An equity curve's underwater profile and its worst stretch. */
+interface Drawdown {
+    /** Fractional drawdown from the running peak at each point (≤ 0). */
+    values: Float64Array;
+    /** Running peak equity. */
+    peak: Float64Array;
+    /** The deepest drawdown (a negative fraction, e.g. −0.32 for −32%). */
+    maxDrawdown: number;
+    /** Index where the max drawdown bottomed, or −1. */
+    troughIndex: number;
+    /** Index of the peak that drawdown fell from, or −1. */
+    peakIndex: number;
+}
+/**
+ * The underwater curve of an equity series: how far below its running high-water
+ * mark the strategy sat at each point. Plot `values` as a filled area under zero
+ * — the standard companion to an equity curve.
+ */
+declare function drawdown(equity: ArrayLike<number>): Drawdown;
 
 /**
  * Convenience builders for specialist finance charts. Each takes a {@link Plot}
@@ -3133,6 +3638,32 @@ interface DepthHandle {
 }
 declare function addDepth(plot: Plot, opts: DepthOptions): DepthHandle;
 
+interface DrawdownOptions {
+    /** Equity / NAV series. */
+    equity: ArrayLike<number>;
+    /** X positions (epoch ms or bar indices). Defaults to `0..n-1`. */
+    x?: ArrayLike<number>;
+    /** Plot as percentages rather than fractions. Default true. */
+    percent?: boolean;
+    color?: string;
+    /** Mark the deepest point with a labelled annotation. Default true. */
+    markMax?: boolean;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+interface DrawdownHandle {
+    area: AreaLayer;
+    /** The computed underwater curve and its worst stretch. */
+    stats: Drawdown;
+}
+/**
+ * The underwater curve: how far below its running high-water mark an equity
+ * series sat, as a filled area hanging from zero. The companion pane to an
+ * equity curve — the number that decides whether a strategy is survivable.
+ */
+declare function addDrawdown(plot: Plot, opts: DrawdownOptions): DrawdownHandle;
+
 /**
  * A tiny dependency-free CSV parser + typed-array column access — the common
  * "load a CSV and plot a column" path. Handles quoted fields, escaped quotes
@@ -3247,6 +3778,91 @@ declare function calibrationCurve(scores: ArrayLike<number>, labels: ArrayLike<n
  * through untouched and don't advance the average.
  */
 declare function emaSmooth(values: ArrayLike<number>, weight?: number): Float64Array;
+/** Mean squared error. */
+declare function mse(yTrue: ArrayLike<number>, yPred: ArrayLike<number>): number;
+/** Root mean squared error — the error in the target's own units. */
+declare function rmse(yTrue: ArrayLike<number>, yPred: ArrayLike<number>): number;
+/** Mean absolute error — less swayed by outliers than {@link rmse}. */
+declare function mae(yTrue: ArrayLike<number>, yPred: ArrayLike<number>): number;
+/**
+ * Coefficient of determination: the fraction of variance the model explains.
+ * 1 is perfect, 0 matches predicting the mean, negative is worse than that.
+ */
+declare function r2(yTrue: ArrayLike<number>, yPred: ArrayLike<number>): number;
+/**
+ * Binary log loss (cross-entropy) of predicted probabilities. Probabilities are
+ * clipped away from 0/1 so a single confident mistake cannot return Infinity.
+ */
+declare function logLoss(probs: ArrayLike<number>, labels: ArrayLike<number>, eps?: number): number;
+/** Brier score: mean squared error of predicted probabilities. Lower is better. */
+declare function brierScore(probs: ArrayLike<number>, labels: ArrayLike<number>): number;
+/** Precision / recall / F1 / support for one class. */
+interface ClassScore {
+    label: number;
+    precision: number;
+    recall: number;
+    f1: number;
+    /** True instances of this class. */
+    support: number;
+}
+/** A scikit-learn style classification report. */
+interface ClassificationReport {
+    perClass: ClassScore[];
+    accuracy: number;
+    /** Unweighted mean over classes — every class counts the same. */
+    macro: {
+        precision: number;
+        recall: number;
+        f1: number;
+    };
+    /** Support-weighted mean — dominated by the common classes. */
+    weighted: {
+        precision: number;
+        recall: number;
+        f1: number;
+    };
+}
+/**
+ * Per-class precision, recall and F1 plus macro/weighted averages. A class the
+ * model never predicts scores 0 precision rather than NaN, so the macro average
+ * stays comparable across runs.
+ */
+declare function classificationReport(yTrue: ArrayLike<number>, yPred: ArrayLike<number>, classes?: number): ClassificationReport;
+/** Cumulative gain / lift as a function of the fraction of the population targeted. */
+interface LiftCurve {
+    /** Fraction of the population contacted, 0..1. */
+    fraction: Float64Array;
+    /** Fraction of all positives captured by then, 0..1 (the gain curve). */
+    gain: Float64Array;
+    /** gain ÷ fraction — how many times better than random. */
+    lift: Float64Array;
+    /** Positives in the data. */
+    positives: number;
+}
+/**
+ * Sort by descending score and walk down the list: the standard "if I contact
+ * the top X%, what share of the buyers do I get?" curve that marketing and
+ * churn models are judged on.
+ */
+declare function liftCurve(scores: ArrayLike<number>, labels: ArrayLike<number>): LiftCurve;
+/** One class's ROC curve in a one-vs-rest decomposition. */
+interface MulticlassRoc {
+    perClass: Array<{
+        label: number;
+        fpr: Float64Array;
+        tpr: Float64Array;
+        auc: number;
+    }>;
+    /** Unweighted mean of the per-class AUCs. */
+    macroAuc: number;
+    /** AUC of the pooled binarized problem — dominated by the common classes. */
+    microAuc: number;
+}
+/**
+ * One-vs-rest ROC for a multiclass problem. `scores` is row-major `n × classes`
+ * (a probability per class per sample), `labels` the true class index.
+ */
+declare function rocCurveOvR(scores: ArrayLike<number>, labels: ArrayLike<number>, classes: number): MulticlassRoc;
 
 /**
  * Pure, dependency-free dimensionality reduction for embedding projections.
@@ -3278,6 +3894,43 @@ declare function standardize(data: ArrayLike<number>, n: number, d: number): Flo
  */
 declare function pca(data: ArrayLike<number>, n: number, d: number, k?: number): PcaResult;
 
+/**
+ * Categorical (qualitative) colour palettes — the discrete counterpart to the
+ * continuous colormaps in `colormap.ts`. Series colours, class colours, treemap
+ * cells and chord groups all draw from here so a page stays visually coherent.
+ */
+/** Built-in qualitative palettes. */
+type BuiltinPaletteName = "tableau10" | "okabe-ito" | "set2" | "bright";
+/**
+ * A palette name. Built-ins autocomplete; any other string resolves through the
+ * registry, so `registerPalette("brand", […])` makes `"brand"` usable anywhere a
+ * palette is accepted. Unknown names fall back to {@link DEFAULT_PALETTE}.
+ */
+type PaletteName = BuiltinPaletteName | (string & {});
+/** A palette given inline: a registered name, or the colours themselves. */
+type PaletteSpec = PaletteName | readonly string[];
+/**
+ * Colour-vision-deficiency safety, roughly:
+ *  - `okabe-ito` — designed to be distinguishable with any common CVD (8 colours)
+ *  - `tableau10` — the default; good separation for ≤10 series
+ *  - `set2` — muted pastels, best for large filled areas
+ *  - `bright` — high-chroma, best on dark backgrounds
+ */
+declare const PALETTES: Record<string, readonly string[]>;
+/** The palette used when none is named. */
+declare const DEFAULT_PALETTE: readonly string[];
+/**
+ * Register a custom palette under `name`, so it can be used anywhere a palette
+ * name is accepted. Re-registering a name replaces it.
+ */
+declare function registerPalette(name: string, colors: readonly string[]): void;
+/** Every registered palette name (built-ins first, then anything registered). */
+declare function paletteNames(): string[];
+/** Resolve a palette spec to its colours — a name, or the colours themselves. */
+declare function palette(spec?: PaletteSpec): readonly string[];
+/** The `index`-th colour of a palette, cycling once the palette is exhausted. */
+declare function paletteColor(index: number, spec?: PaletteSpec): string;
+
 /**
  * Convenience builders for ML / deep-learning charts. Each takes a {@link Plot}
  * and composes existing layers (`addHeatmap`/`addLine`/`addScatter`/`addBar`/
@@ -3287,13 +3940,14 @@ declare function pca(data: ArrayLike<number>, n: number, d: number, k?: number):
  */
 
 /** tab10 categorical palette, cycled by class index. */
+/** Series/class colours for the ML builders. Aliases the shared {@link DEFAULT_PALETTE} (Tableau 10). */
 declare const ML_PALETTE: readonly string[];
 interface ConfusionMatrixOptions {
     yTrue: ArrayLike<number>;
     yPred: ArrayLike<number>;
     /** Number of classes; inferred from the labels when omitted. */
     classes?: number;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Shade by row-normalized recall instead of raw counts. Default false. */
     normalize?: boolean;
     /** Draw the value inside each cell. Default true. */
@@ -3366,8 +4020,8 @@ interface EmbeddingOptions {
     classNames?: string[];
     /** Continuous value per point → a single colormap series (ignored if `labels`). */
     colorBy?: ArrayLike<number>;
-    colormap?: ColormapName;
-    palette?: readonly string[];
+    colormap?: ColormapSpec;
+    palette?: PaletteSpec;
     size?: number;
     /** Per-point hover text (metadata). */
     text?: ArrayLike<string>;
@@ -3392,7 +4046,7 @@ interface DecisionBoundaryOptions {
         x: Range;
         y: Range;
     };
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     domain?: Range;
     /** Training points drawn over the field. */
     points?: {
@@ -3400,7 +4054,7 @@ interface DecisionBoundaryOptions {
         y: ArrayLike<number>;
         labels?: ArrayLike<number> | string[];
         classNames?: string[];
-        palette?: readonly string[];
+        palette?: PaletteSpec;
         size?: number;
     };
 }
@@ -3435,7 +4089,7 @@ interface ShapBeeswarmOptions {
     names: string[];
     /** Feature values (same shape) → point color via a diverging colormap. */
     featureValues?: number[][];
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     size?: number;
     /** Vertical spread of each feature band, 0..1. Default 0.8. */
     spread?: number;
@@ -3475,7 +4129,7 @@ interface AttentionMapOptions {
     /** Required with a flat `weights`. */
     queries?: number;
     keys?: number;
-    colormap?: ColormapName;
+    colormap?: ColormapSpec;
     /** Draw each weight in its cell (small maps only). Default false. */
     annotate?: boolean;
 }
@@ -3501,7 +4155,7 @@ interface TrainingCurvesOptions {
     /** Mark the best epoch of each series. */
     best?: "min" | "max";
     width?: number;
-    palette?: readonly string[];
+    palette?: PaletteSpec;
     renderType?: RenderType;
 }
 interface TrainingCurvesHandle {
@@ -3525,7 +4179,7 @@ interface RidgelineOptions {
     points?: number;
     /** Ridge overlap, 0 = touching, 1 = one full row of overlap. Default 1. */
     overlap?: number;
-    palette?: readonly string[];
+    palette?: PaletteSpec;
     /** Fill each ridge. Default true. */
     fill?: boolean;
     /** Shared x-range; inferred from the data when omitted. */
@@ -3551,6 +4205,502 @@ interface BeeswarmOptions {
  * local density. Pure — no RNG. Backs {@link addShapBeeswarm}.
  */
 declare function beeswarmLayout(x: ArrayLike<number>, opts?: BeeswarmOptions): number[];
+interface PredVsActualOptions {
+    yTrue: ArrayLike<number>;
+    yPred: ArrayLike<number>;
+    color?: string;
+    /** Colour of the y = x reference. */
+    referenceColor?: string;
+    size?: number;
+    name?: string;
+    renderType?: RenderType;
+}
+interface PredVsActualHandle {
+    points: ScatterLayer;
+    reference: LineLayer;
+    r2: number;
+}
+/**
+ * Predicted against actual, with the y = x line a perfect model would sit on.
+ * The gap between the cloud and that line *is* the error, which is why this
+ * reads better than a lone R² number.
+ */
+declare function addPredVsActual(plot: Plot, opts: PredVsActualOptions): PredVsActualHandle;
+interface ResidualsOptions {
+    yTrue: ArrayLike<number>;
+    yPred: ArrayLike<number>;
+    /** Plot residuals against `"predicted"` (default) or `"index"` (order in the data). */
+    against?: "predicted" | "index";
+    color?: string;
+    size?: number;
+    name?: string;
+    renderType?: RenderType;
+}
+interface ResidualsHandle {
+    points: ScatterLayer;
+    zero: LineLayer;
+    residuals: Float64Array;
+}
+/**
+ * Residuals (actual − predicted) against the prediction or the sample order,
+ * with a zero line. Structure here — a curve, a fan, a drift — means the model
+ * is missing something, which no single score will tell you.
+ */
+declare function addResiduals(plot: Plot, opts: ResidualsOptions): ResidualsHandle;
+interface LiftCurveOptions {
+    scores: ArrayLike<number>;
+    labels: ArrayLike<number>;
+    /** `"gain"` (default) plots cumulative gain; `"lift"` plots the ratio over random. */
+    mode?: "gain" | "lift";
+    color?: string;
+    /** Colour of the random-baseline reference. */
+    baselineColor?: string;
+    width?: number;
+    name?: string;
+    renderType?: RenderType;
+}
+interface LiftCurveHandle {
+    line: LineLayer;
+    baseline: LineLayer;
+    positives: number;
+}
+/**
+ * Cumulative gain (or lift) against the fraction of the population targeted,
+ * with the random baseline for reference — how a churn or marketing model is
+ * actually judged: "contact the top 20%, capture what share of the positives?"
+ */
+declare function addLiftCurve(plot: Plot, opts: LiftCurveOptions): LiftCurveHandle;
+interface LearningCurveOptions {
+    /** Training-set sizes the scores were measured at. */
+    sizes: ArrayLike<number>;
+    /** Mean training score per size. */
+    train: ArrayLike<number>;
+    /** Mean validation score per size. */
+    validation: ArrayLike<number>;
+    /** Optional ± spread per size (e.g. std across CV folds), drawn as bands. */
+    trainStd?: ArrayLike<number>;
+    validationStd?: ArrayLike<number>;
+    trainColor?: string;
+    validationColor?: string;
+    width?: number;
+    renderType?: RenderType;
+}
+interface LearningCurveHandle {
+    train: LineLayer;
+    validation: LineLayer;
+    bands: AreaLayer[];
+}
+/**
+ * Score against training-set size for train and validation, with optional
+ * cross-validation spread bands. A gap that stays wide means variance (get more
+ * data); two curves that meet low mean bias (get a bigger model).
+ */
+declare function addLearningCurve(plot: Plot, opts: LearningCurveOptions): LearningCurveHandle;
+
+/**
+ * Model-architecture graphs: a framework-agnostic description of a neural
+ * network's layers, adapters that build one from PyTorch / ONNX exports, and a
+ * layered-DAG layout shared by the 2D and 3D renderers (`ml/model-chart.ts`).
+ *
+ * Everything here is pure (array in → array out) and unit-tested; nothing
+ * touches WebGL or the DOM.
+ */
+
+/** One layer / op in a model graph. */
+interface ModelNode {
+    /** Unique id — a module path (`features.0`), an fx node name, or a tensor name. */
+    id: string;
+    /** Display name. Defaults to `id`. */
+    name?: string;
+    /** Layer or op class: `"Conv2d"`, `"Linear"`, `"ReLU"`, `"Add"`, … */
+    type: string;
+    /** Output tensor shape with the batch dim dropped, e.g. `[64, 112, 112]`. */
+    shape?: number[];
+    /** Trainable parameter count. */
+    params?: number;
+    /** Multiply-accumulates / FLOPs, if known. */
+    flops?: number;
+    /** Block or stage the layer belongs to (`"layer1"`, `"encoder.3"`, …). */
+    group?: string;
+}
+/** A directed connection (activation tensor) between two {@link ModelNode}s. */
+interface ModelEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+/** A model architecture as a directed acyclic graph of layers. */
+interface ModelGraph {
+    name?: string;
+    nodes: ModelNode[];
+    edges: ModelEdge[];
+}
+/** Coarse layer families, used to color a diagram consistently. */
+type LayerCategory = "input" | "conv" | "linear" | "norm" | "activation" | "pool" | "dropout" | "attention" | "embedding" | "recurrent" | "reshape" | "merge" | "output" | "other";
+/** Default category → color. Tuned to read on both dark and light backgrounds. */
+declare const LAYER_COLORS: Record<LayerCategory, string>;
+/** Classify a layer/op type string (`"Conv2d"`, `"aten::relu"`) into a family. */
+declare function layerCategory(type: string): LayerCategory;
+/** `9408` → `"9.4K"`, `2.5e7` → `"25M"`. Used for parameter / FLOP counts. */
+declare function formatCount(n: number): string;
+/** `[64, 112, 112]` → `"64×112×112"`; empty/absent → `""`. */
+declare function formatShape(shape?: number[]): string;
+/** A layer in a straight-line model; `id` is derived when omitted. */
+interface SequentialLayer extends Omit<ModelNode, "id"> {
+    id?: string;
+}
+/**
+ * Build a straight-line graph from an ordered layer list — the one-liner path
+ * from `model.named_modules()` / `torchinfo.summary()`. Consecutive layers are
+ * connected automatically.
+ */
+declare function sequentialModel(layers: SequentialLayer[], name?: string): ModelGraph;
+/**
+ * One node of a traced `torch.fx` graph. Produce it in Python with:
+ *
+ * ```python
+ * gm = torch.fx.symbolic_trace(model)
+ * [{"name": n.name, "op": n.op, "target": str(n.target),
+ *   "args": [a.name for a in n.all_input_nodes]} for n in gm.graph.nodes]
+ * ```
+ */
+interface TorchFxNode {
+    name: string;
+    /** `placeholder` | `call_module` | `call_function` | `call_method` | `get_attr` | `output`. */
+    op: string;
+    /** Module path or function name. */
+    target?: string;
+    /** Names of the input nodes (`[a.name for a in n.all_input_nodes]`). */
+    args?: string[];
+    /** `type(module).__name__` for `call_module` nodes — the nicest display type. */
+    moduleType?: string;
+    shape?: number[];
+    params?: number;
+    flops?: number;
+}
+/** Options shared by the graph adapters. */
+interface AdapterOptions {
+    name?: string;
+    /** fx ops to drop before building the graph. Default `["get_attr"]`. */
+    skipOps?: string[];
+}
+/** Build a {@link ModelGraph} from traced `torch.fx` nodes (keeps skip connections). */
+declare function modelGraphFromTorchFx(nodes: TorchFxNode[], opts?: AdapterOptions): ModelGraph;
+/** A node of an ONNX graph, as produced by `MessageToDict(model.graph)`. */
+interface OnnxNode {
+    name?: string;
+    opType: string;
+    input?: string[];
+    output?: string[];
+}
+/** An ONNX graph dict: `MessageToDict(onnx.load(path).graph)`. */
+interface OnnxGraph {
+    name?: string;
+    node: OnnxNode[];
+    input?: Array<{
+        name: string;
+    }>;
+    output?: Array<{
+        name: string;
+    }>;
+    /** Initializers (weights) — their names are excluded from the edge set. */
+    initializer?: Array<{
+        name: string;
+    }>;
+}
+/** ONNX adapter options: tensor shapes are supplied separately (shape inference is optional in ONNX). */
+interface OnnxAdapterOptions extends AdapterOptions {
+    /** Tensor name → shape (batch dim already dropped), for node output shapes. */
+    shapes?: Record<string, number[]>;
+    /** Tensor name → element count, to attribute weights to their consuming op. */
+    paramCounts?: Record<string, number>;
+}
+/**
+ * Build a {@link ModelGraph} from an ONNX graph dict — the framework-neutral
+ * path (works for models exported from PyTorch, TensorFlow, JAX, sklearn…).
+ * Edges are recovered by matching each node's inputs to the node that produced
+ * them; weights (initializers) are folded into the consuming node's `params`.
+ */
+declare function modelGraphFromOnnx(graph: OnnxGraph, opts?: OnnxAdapterOptions): ModelGraph;
+/** One layer of a Keras config (`json.loads(model.to_json())`). */
+interface KerasLayerConfig {
+    class_name: string;
+    name?: string;
+    config?: Record<string, unknown>;
+    /**
+     * Functional-API wiring. Keras 2 nests `[["conv1", 0, 0, {}]]` and Keras 3
+     * nests `keras_history` — both are handled by scanning for known layer names.
+     */
+    inbound_nodes?: unknown;
+}
+/** A Keras model config: `json.loads(model.to_json())`. */
+interface KerasModelConfig {
+    /** `"Sequential"` | `"Functional"` | `"Model"`. */
+    class_name?: string;
+    config?: {
+        name?: string;
+        layers?: KerasLayerConfig[];
+    };
+    /** Some exports hoist the layer list to the top level. */
+    layers?: KerasLayerConfig[];
+}
+/** Keras adapter options — output shapes come from `[l.output_shape for l in model.layers]`. */
+interface KerasAdapterOptions extends AdapterOptions {
+    /** Layer name → output shape (batch dim already dropped). */
+    shapes?: Record<string, number[]>;
+    /** Layer name → parameter count (`l.count_params()`). */
+    params?: Record<string, number>;
+}
+/**
+ * Build a {@link ModelGraph} from a TensorFlow / Keras model config. Sequential
+ * models chain in declaration order; functional models are wired from each
+ * layer's `inbound_nodes`, so multi-input and residual topologies survive.
+ */
+declare function modelGraphFromKeras(model: KerasModelConfig, opts?: KerasAdapterOptions): ModelGraph;
+/**
+ * A scikit-learn estimator as a tree of steps. Leaves are estimators; `steps`
+ * makes a composite — a `Pipeline` (`mode: "sequential"`) or a
+ * `FeatureUnion` / `ColumnTransformer` (`mode: "parallel"`).
+ */
+interface SklearnStep {
+    /** Step name (`"scaler"`, `"clf"`, …). */
+    name: string;
+    /** Estimator class: `"StandardScaler"`, `"RandomForestClassifier"`, … */
+    type: string;
+    /** Child steps of a composite estimator. */
+    steps?: SklearnStep[];
+    /** How the children combine. Default `"sequential"`. */
+    mode?: "sequential" | "parallel";
+    /** Output feature count / shape, if known. */
+    shape?: number[];
+    /** Fitted parameter count, if known. */
+    params?: number;
+    /** Columns a `ColumnTransformer` branch operates on (shown in the label). */
+    columns?: string[];
+}
+/**
+ * Build a {@link ModelGraph} from a scikit-learn `Pipeline` /
+ * `ColumnTransformer` / `FeatureUnion` tree: sequential steps chain, parallel
+ * branches fan out from the previous step and fan back in to the next one.
+ */
+declare function modelGraphFromSklearn(root: SklearnStep, opts?: AdapterOptions): ModelGraph;
+/** Options for {@link mlpModel}. */
+interface MlpOptions {
+    /** Activation inserted between dense layers. Default `"ReLU"`; `""` omits it. */
+    activation?: string;
+    /** Activation after the final layer (`"Softmax"`, `"Sigmoid"`, …). */
+    outputActivation?: string;
+    name?: string;
+}
+/**
+ * A dense feed-forward net from its layer sizes — the shape a scikit-learn
+ * `MLPClassifier` reports as `[n_features, *hidden_layer_sizes, n_outputs]`.
+ * Parameter counts are computed as `in × out + out`.
+ */
+declare function mlpModel(layerSizes: number[], opts?: MlpOptions): ModelGraph;
+interface ModelLayoutOptions {
+    /** Flow direction: `"vertical"` top→bottom (default) or `"horizontal"` left→right. */
+    direction?: "vertical" | "horizontal";
+    /** Box width in data units. Default 2.6. */
+    nodeWidth?: number;
+    /** Box height in data units. Default 0.9. */
+    nodeHeight?: number;
+    /** Gap between consecutive ranks. Default 0.7. */
+    rankGap?: number;
+    /** Gap between siblings inside a rank. Default 0.6. */
+    nodeGap?: number;
+    /**
+     * Scale the box across the flow (width when vertical, height when horizontal)
+     * by a metric, so heavy layers read as bigger. Default `"none"`.
+     */
+    sizeBy?: "none" | "params" | "flops";
+    /** Multiplier range applied when `sizeBy` is set. Default `[0.55, 1.5]`. */
+    sizeRange?: Range;
+    /** Barycenter passes used to reduce edge crossings. Default 4. */
+    sweeps?: number;
+}
+/** A laid-out layer box (center + size in data units). */
+interface ModelNodeBox {
+    node: ModelNode;
+    category: LayerCategory;
+    color: string;
+    /** Center. */
+    x: number;
+    y: number;
+    /** Full size. */
+    w: number;
+    h: number;
+    rank: number;
+    /** Position within the rank, left→right (or top→bottom when horizontal). */
+    order: number;
+}
+/** A routed connector: an orthogonal polyline from one box edge to another. */
+interface ModelEdgePath {
+    from: string;
+    to: string;
+    label?: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+interface ModelLayoutResult {
+    nodes: ModelNodeBox[];
+    edges: ModelEdgePath[];
+    extent: {
+        x: Range;
+        y: Range;
+    };
+    /** Depth of the DAG (number of ranks). */
+    ranks: number;
+}
+/**
+ * Lay a {@link ModelGraph} out as a layered DAG: longest-path ranks, barycenter
+ * ordering to reduce crossings, then orthogonal edge routing. Edges that skip
+ * more than one rank (residual connections) are routed through a bypass lane
+ * beside the boxes so they don't cut across them.
+ */
+declare function modelLayout(graph: ModelGraph, opts?: ModelLayoutOptions): ModelLayoutResult;
+interface ModelBoxSizing {
+    /** Compression applied to each tensor dim before scaling. Default `"log"`. */
+    sizeScale?: "log" | "sqrt" | "linear";
+    /** Thickness of the widest layer along the flow axis (channels). Default 0.9. */
+    maxThickness?: number;
+    /** Height / lateral depth of the largest feature-map face. Default 2.2. */
+    maxFace?: number;
+    /** Floor (world units) applied to every axis so singleton dims stay visible. Default 0.08. */
+    minSize?: number;
+}
+/** Size of one layer's cuboid: `[thickness (flow), height, depth (lateral)]`. */
+type BoxDims = [number, number, number];
+/**
+ * Cuboid dimensions for every node, normalized together so the largest layer on
+ * each axis hits its max — the classic "CNN funnel" where feature maps shrink
+ * while channel depth grows.
+ */
+declare function modelBoxDims(nodes: ModelNode[], opts?: ModelBoxSizing): BoxDims[];
+
+/**
+ * Model-architecture diagrams built on existing layers:
+ *
+ *  - {@link addModelGraph} — a flat Netron-style DAG on a 2D {@link Plot}
+ *    (rounded boxes + orthogonal connectors, colored by layer family).
+ *  - {@link addModelGraph3D} — the "CNN explainer" view on a {@link Plot3D}:
+ *    one cuboid per layer, sized from its output tensor shape, chained along the
+ *    flow axis.
+ *
+ * Both consume the same {@link ModelGraph} and the same {@link modelLayout}, so a
+ * PyTorch / ONNX export renders identically in either dimension.
+ */
+
+interface ModelGraphOptions extends ModelLayoutOptions {
+    graph: ModelGraph;
+    /** Per-category color overrides (merged over {@link LAYER_COLORS}). */
+    colors?: Partial<Record<LayerCategory, string>>;
+    /** Box corner radius in data units. Default 0.14. */
+    cornerRadius?: number;
+    /** Connector thickness in data units. Default 0.05. */
+    edgeWidth?: number;
+    edgeColor?: string;
+    /** Arrowhead length in data units; 0 hides them. Default 0.18. */
+    arrowSize?: number;
+    /** Box fill opacity, 0..1. Default 0.9. */
+    opacity?: number;
+    /** What to write inside each box. Default `"full"`. */
+    labels?: "none" | "name" | "full";
+    labelColor?: string;
+    labelFont?: string;
+    subLabelColor?: string;
+    subLabelFont?: string;
+    /** Attach a hover tooltip with the layer's shape + parameter count. Default true. */
+    tooltip?: boolean;
+    /** Palette for the tooltip chrome. Default `"dark"`. */
+    theme?: "light" | "dark";
+    /** Blank the axes — a diagram has no meaningful coordinates. Default true. */
+    hideAxes?: boolean;
+    /** Legend name for the box layer. Omitted by default (diagrams use their own key). */
+    name?: string;
+}
+interface ModelGraphHandle {
+    /** The computed layout — box centers, sizes, ranks and routed edge paths. */
+    layout: ModelLayoutResult;
+    /** Layer holding the layer boxes. */
+    nodes: PatchesLayer;
+    /** Layer holding the connectors (drawn beneath the boxes). */
+    edges: PatchesLayer;
+    /** The box containing a data-space point, or null. */
+    nodeAt(x: number, y: number): ModelNodeBox | null;
+    /** Remove the labels and tooltip this builder added (layers are yours to remove). */
+    destroy(): void;
+}
+/**
+ * Draw a model architecture as a flat layered graph. Boxes are colored by layer
+ * family, residual/skip connections route around the trunk, and each box shows
+ * its type, name and output shape.
+ *
+ * Pair it with `new Plot(el, { equalAspect: true, hover: false })` — the diagram
+ * is a schematic, so a square aspect and no series tooltip read best.
+ */
+declare function addModelGraph(plot: Plot, opts: ModelGraphOptions): ModelGraphHandle;
+interface ModelGraph3DOptions extends ModelLayoutOptions, ModelBoxSizing {
+    graph: ModelGraph;
+    /** Per-category color overrides (merged over {@link LAYER_COLORS}). */
+    colors?: Partial<Record<LayerCategory, string>>;
+    /** Clear space between consecutive layer blocks along the flow axis. Default 1.1. */
+    rankSpacing?: number;
+    /** Lateral offset between branches that share a rank. Default 3. */
+    branchSpacing?: number;
+    /** Draw connectors between blocks. Default true. */
+    connectors?: boolean;
+    connectorColor?: string;
+    /** Block opacity, 0..1. Default 1. */
+    opacity?: number;
+    /**
+     * Text pinned above each block: `"name"` (default) the layer name, `"type"`
+     * its class, `"full"` the name above and the output shape below, `"none"` to
+     * rely on the hover tooltip alone.
+     */
+    labels?: "none" | "name" | "type" | "full";
+    labelColor?: string;
+    labelFont?: string;
+    subLabelColor?: string;
+    subLabelFont?: string;
+    name?: string;
+}
+/** Where one layer's cuboid ended up, in world space. */
+interface ModelBlock {
+    node: ModelNode;
+    category: LayerCategory;
+    /** Center. */
+    x: number;
+    y: number;
+    z: number;
+    /** Full size: `w` along the flow axis, `h` up, `d` lateral. */
+    w: number;
+    h: number;
+    d: number;
+    rank: number;
+}
+interface ModelGraph3DHandle {
+    boxes: Boxes3DLayer;
+    /** One polyline per drawn connector (empty when `connectors: false`). */
+    connectors: Line3DLayer[];
+    blocks: ModelBlock[];
+    /** Remove the labels this builder pinned (the layers are yours to remove). */
+    destroy(): void;
+}
+/**
+ * Draw a model as a chain of cuboids sized from each layer's output tensor: the
+ * visible face is the last two dims (H×W) and the thickness is everything before
+ * them (channels) — so a CNN reads as feature maps shrinking while depth grows.
+ * Blocks flow along +x, branches spread along z, and hovering one shows its
+ * shape and parameter count.
+ *
+ * Build the plot with `new Plot3D(el, { aspectMode: "data", showAxes: false })`
+ * — the default cube fit would stretch a long chain until the blocks lose their
+ * proportions, and a diagram has no axes to label.
+ */
+declare function addModelGraph3D(plot: Plot3D, opts: ModelGraph3DOptions): ModelGraph3DHandle;
 
 /**
  * Squarified treemap — a pure layout plus a {@link Plot} builder that composes
@@ -3581,6 +4731,7 @@ interface TreemapExtent {
     y: [number, number];
 }
 /** tab10-ish default palette, cycled by index for items without a color. */
+/** Cell colours when an item has no explicit `color`. Aliases the shared {@link DEFAULT_PALETTE} (Tableau 10). */
 declare const TREEMAP_PALETTE: readonly string[];
 /**
  * Squarified treemap layout: sizes rects ∝ `value`, packing them into `extent`
@@ -3592,7 +4743,7 @@ interface TreemapOptions {
     items: TreemapItem[];
     extent?: TreemapExtent;
     /** Palette cycled by index for items lacking a `color`. Defaults to {@link TREEMAP_PALETTE}. */
-    colors?: string[];
+    colors?: PaletteSpec;
     opacity?: number;
     name?: string;
     renderType?: RenderType;
@@ -3638,6 +4789,7 @@ interface FunnelLayoutOptions {
     neck?: number;
 }
 /** tab10-ish default palette, cycled by index for stages without a color. */
+/** Stage colours when an item has no explicit `color`. Aliases the shared {@link DEFAULT_PALETTE} (Tableau 10). */
 declare const FUNNEL_PALETTE: readonly string[];
 /**
  * Funnel layout: centered trapezoids stacked top-to-bottom, each stage's top
@@ -3651,7 +4803,7 @@ interface FunnelOptions {
     height?: number;
     neck?: number;
     /** Palette cycled by index for stages lacking a `color`. Defaults to {@link FUNNEL_PALETTE}. */
-    colors?: string[];
+    colors?: PaletteSpec;
     opacity?: number;
     name?: string;
     renderType?: RenderType;
@@ -3884,6 +5036,7 @@ declare function addSankey(plot: Plot, opts: SankeyOptions): PatchesLayer;
  */
 
 /** tab10-ish default palette, cycled by group index. */
+/** Group colours when none are supplied. Aliases the shared {@link DEFAULT_PALETTE} (Tableau 10). */
 declare const CHORD_PALETTE: readonly string[];
 /** A laid-out group arc as a closed ring of `x`/`y` (thin annular sector). */
 interface ChordGroupArc {
@@ -3930,7 +5083,7 @@ interface ChordOptions {
     /** Outer radius. Default 1. */
     radius?: number;
     /** Palette cycled by group index. Defaults to {@link CHORD_PALETTE}. */
-    colors?: string[];
+    colors?: PaletteSpec;
     /** Ribbon fill opacity, 0..1. Default 0.65. */
     opacity?: number;
     name?: string;
@@ -3951,6 +5104,7 @@ declare function addChord(plot: Plot, opts: ChordOptions): PatchesLayer;
  */
 
 /** tab10-ish default palette, cycled by row index (or by `colorBy` band). */
+/** Line colours when rows are coloured by class. Aliases the shared {@link DEFAULT_PALETTE} (Tableau 10). */
 declare const PARALLEL_PALETTE: readonly string[];
 /** A laid-out axis: its dimension name, x position, and observed value range. */
 interface ParallelAxis {
@@ -4009,4 +5163,104 @@ declare function parseColor(input: string): [number, number, number, number];
 /** Normalized RGBA (0..1) back to a CSS `rgba(...)` string. */
 declare function toColorCss(c: readonly [number, number, number, number]): string;
 
-export { type Adx, type Annotation, AreaLayer, type AreaOptions, type AreaSeries, type AttentionMapHandle, type AttentionMapOptions, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, Bar3DLayer, type Bar3DOptions, BarLayer, type BarOptions, type BarSeries, type BeeswarmOptions, type BollingerBands, type BollingerHandle, type BollingerOptions, type Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, type Brick, CHORD_PALETTE, type CSVOptions, type CalibrationCurve, type CalibrationHandle, type CalibrationOptions, type Candle, type CandlestickData, CandlestickLayer, type CandlestickOptions, CategoricalScale, type Channel, type ChordGroupArc, type ChordLayoutOptions, type ChordLayoutResult, type ChordOptions, type ChordRibbon, type Color, type ColorInfo, type ColormapName, type ConfusionMatrix, type ConfusionMatrixHandle, type ConfusionMatrixOptions, Contour3DLayer, type Contour3DOptions, ContourLayer, type ContourOptions, type DecisionBoundaryHandle, type DecisionBoundaryOptions, type Density, type DepthCurves, type DepthHandle, type DepthOptions, type Dim, type DrawState, type DrawTool, type EmbeddingHandle, type EmbeddingOptions, ErrorBarLayer, type ErrorBarOptions, type ExportOptions, FUNNEL_PALETTE, type FeatureImportanceHandle, type FeatureImportanceOptions, type FibLevel, type ForceLayoutOptions, type FunnelItem, type FunnelLayoutOptions, type FunnelOptions, type FunnelStage, type GaugeLayoutOptions, type GaugeOptions, type GaugeThreshold, type GraphInput, GraphLayer, type GraphOptions, type GroupedBarOptions, HeatmapLayer, type HeatmapOptions, type HeikinAshiOptions, HexbinLayer, type HexbinOptions, type Histogram, type HoverReadoutRow, type Ichimoku, ImageLayer, type ImageOptions, type ImageSource, type InteractionMode, IsosurfaceLayer, type IsosurfaceOptions, type Layer, type Layer3D, type Layout, type LegendOptions, Line3DLayer, type Line3DOptions, LineLayer, type LineOptions, LinearScale, LogScale, ML_PALETTE, type Macd, type MarkerShape, type Ohlc, type OhlcArrays, type OhlcInput, OhlcLayer, type OhlcOptions, OrdinalTimeScale, PARALLEL_PALETTE, type ParallelAxis, type ParallelHandle, type ParallelLayoutResult, type ParallelLine, type ParallelOptions, type PartialDependenceHandle, type PartialDependenceOptions, type Patch, PatchesLayer, type PatchesOptions, type PcaResult, type PfColumn, type PickMode, PieLayer, type PieOptions, Plot, Plot3D, type Plot3DOptions, type PlotOptions, type PlotTitleOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, type PrCurve, type PrCurveHandle, type PrCurveOptions, Quiver3DLayer, type Quiver3DOptions, QuiverLayer, type QuiverOptions, type RGB, type Range, type RenderType, type RenkoOptions, type ResolvedAxisStyle, type RidgeGroup, type RidgelineHandle, type RidgelineOptions, type Ring, type RocCurve, type RocCurveHandle, type RocCurveOptions, type SankeyLayoutOptions, type SankeyLayoutResult, type SankeyLink, type SankeyNode, type SankeyNodeRect, type SankeyOptions, type SankeyRibbon, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type ShapBeeswarmHandle, type ShapBeeswarmOptions, type Spectrogram, type StackedAreaOptions, type StackedBarOptions, StemLayer, type StemOptions, type Stochastic, type SunburstArc, type SunburstLayoutOptions, type SunburstNode, type SunburstOptions, type SuperTrend, SurfaceLayer, type SurfaceOptions, TRANSFORM_GLSL, TRANSFORM_UNIFORMS, TREEMAP_PALETTE, type Table, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type TrainingCurvesHandle, type TrainingCurvesOptions, type TrainingSeries, type TreemapCell, type TreemapExtent, type TreemapItem, type TreemapOptions, VolumeLayer, type VolumeOptions, type VolumeProfile, type VolumeProfileOptions, type YAxisOptions, addAttentionMap, addBollinger, addCalibration, addChord, addConfusionMatrix, addDecisionBoundary, addDepth, addEmbedding, addFeatureImportance, addFunnel, addGauge, addHeikinAshi, addParallelCoordinates, addPartialDependence, addPrCurve, addRenko, addRidgeline, addRocCurve, addSankey, addShapBeeswarm, addSunburst, addTrainingCurves, addTreemap, addVolumeProfile, adx, atr, autoTicks, beeswarmLayout, bollinger, boxStats, bufferUsage, calibrationCurve, canvasToBlob, chordLayout, colormap, colormapLUT, confusionMatrix, copyCanvasToClipboard, createProgram, createToolbar, darkTheme, defaultFormat, depth, downloadCanvas, earcut, ema, emaSmooth, fft, fibRetracements, firstFinite, forceLayout, funnelLayout, gaugeLayout, heikinAshi, histogram, ichimoku, kde, keltner, lightTheme, lineBreak, linkX, lttb, macd, makeScale, marchingCubes, obv, parallelLayout, parseCSV, parseColor, pca, pointAndFigure, prCurve, quantileSorted, renko, resolveAxisStyle, resolveTicks, rocCurve, rollingStd, rsi, sankeyLayout, setTransformUniforms, sma, spectrogram, standardize, stochastic, sunburstLayout, superTrend, toColorCss, treemapLayout, trueRange, uniformLocations, volumeProfile, vwap, withMinorTicks, wma };
+/**
+ * Statistics chart builders — free functions that compose existing layers, the
+ * same shape as the finance / diagram / ML packs.
+ */
+
+interface RegressionOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    /** `"ols"` (default) fits a straight line; `"loess"` fits a local curve. */
+    method?: "ols" | "loess";
+    /**
+     * Shade ±`band`·standard-error around an OLS fit (2 ≈ 95%). Ignored for
+     * LOESS, which has no closed-form interval here. Default 0 (no band).
+     */
+    band?: number;
+    /** LOESS neighbourhood as a fraction of the points, 0..1. Default 0.3. */
+    bandwidth?: number;
+    /** Samples along the fitted curve. Default 2 for OLS, 100 for LOESS. */
+    points?: number;
+    color?: string;
+    bandColor?: string;
+    width?: number;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+interface RegressionHandle {
+    line: LineLayer;
+    band?: AreaLayer;
+    /** The OLS fit (slope/intercept/r²), or null for LOESS. */
+    fit: LinearFit | null;
+}
+/**
+ * A trend line over a scatter — least squares by default, with an optional
+ * confidence band, or a LOESS curve when the relationship is not linear. The
+ * series name carries r² so the chart states its own fit quality.
+ */
+declare function addRegression(plot: Plot, opts: RegressionOptions): RegressionHandle;
+interface EcdfOptions {
+    values: ArrayLike<number>;
+    color?: string;
+    width?: number;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+/**
+ * The empirical CDF as a step line: the most honest way to compare two
+ * distributions, since it involves no binning choice at all.
+ */
+declare function addEcdf(plot: Plot, opts: EcdfOptions): LineLayer;
+interface CorrMatrixOptions {
+    /** One array per variable. */
+    columns: ReadonlyArray<ArrayLike<number>>;
+    /** Variable names, used for the axis tick labels. */
+    names?: string[];
+    /** Defaults to a diverging map so ±1 read as opposites. */
+    colormap?: ColormapSpec;
+    /** Label the axes with `names`. Default true. */
+    labelAxes?: boolean;
+    name?: string;
+    yAxis?: string;
+}
+interface CorrMatrixHandle {
+    heatmap: HeatmapLayer;
+    /** Row-major `k×k` correlations. */
+    values: Float64Array;
+    size: number;
+}
+/**
+ * A correlation matrix as a heatmap, on a diverging colormap locked to ±1 so
+ * that zero is the neutral colour and sign is readable at a glance.
+ */
+declare function addCorrMatrix(plot: Plot, opts: CorrMatrixOptions): CorrMatrixHandle;
+interface PsdOptions {
+    signal: ArrayLike<number>;
+    sampleRate?: number;
+    /** Samples per Welch segment. Default 256. */
+    segment?: number;
+    overlap?: number;
+    window?: WindowName;
+    /** Plot power in dB (10·log10). Default true — spectra span decades. */
+    decibels?: boolean;
+    color?: string;
+    width?: number;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+interface PsdHandle {
+    line: LineLayer;
+    frequencies: Float64Array;
+    power: Float64Array;
+}
+/**
+ * Welch power spectral density as a line — averaged over overlapping windowed
+ * segments, so a noisy signal gives a readable spectrum instead of grass.
+ */
+declare function addPsd(plot: Plot, opts: PsdOptions): PsdHandle;
+
+export { type AdapterOptions, type Adx, type Annotation, AreaLayer, type AreaOptions, type AreaSeries, type Aroon, type AttentionMapHandle, type AttentionMapOptions, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, Bar3DLayer, type Bar3DOptions, BarLayer, type BarOptions, type BarSeries, type BeeswarmOptions, type BollingerBands, type BollingerHandle, type BollingerOptions, type Bounds, type Bounds3, type Box3D, type BoxDims, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, Boxes3DLayer, type Boxes3DOptions, type Brick, type BuiltinColormapName, type BuiltinPaletteName, CHORD_PALETTE, COLORMAP_KIND, type CSVOptions, type CalibrationCurve, type CalibrationHandle, type CalibrationOptions, type Candle, type CandlestickData, CandlestickLayer, type CandlestickOptions, CategoricalScale, type Channel, type ChordGroupArc, type ChordLayoutOptions, type ChordLayoutResult, type ChordOptions, type ChordRibbon, type ClassScore, type ClassificationReport, type Color, type ColorInfo, type ColorbarOptions, type ColorbarTheme, type ColormapKind, type ColormapName, type ColormapSpec, type ConfusionMatrix, type ConfusionMatrixHandle, type ConfusionMatrixOptions, Contour3DLayer, type Contour3DOptions, ContourLayer, type ContourOptions, type CorrMatrixHandle, type CorrMatrixOptions, type Correlation, DEFAULT_PALETTE, type DecisionBoundaryHandle, type DecisionBoundaryOptions, type Density, type DepthCurves, type DepthHandle, type DepthOptions, type Dim, type DrawState, type DrawTool, type Drawdown, type DrawdownHandle, type DrawdownOptions, type EcdfOptions, type EmbeddingHandle, type EmbeddingOptions, type ErrInput, type ErrorBarData, ErrorBarLayer, type ErrorBarOptions, type ExportOptions, FUNNEL_PALETTE, type FeatureImportanceHandle, type FeatureImportanceOptions, type FibLevel, type ForceLayoutOptions, type FunnelItem, type FunnelLayoutOptions, type FunnelOptions, type FunnelStage, type GaugeLayoutOptions, type GaugeOptions, type GaugeThreshold, type GraphData, type GraphInput, GraphLayer, type GraphOptions, type GroupedBarOptions, HeatmapLayer, type HeatmapOptions, type HeikinAshiOptions, HexbinLayer, type HexbinOptions, type Histogram, type HoverReadoutRow, type Ichimoku, ImageLayer, type ImageOptions, type ImageSource, type InteractionMode, IsosurfaceLayer, type IsosurfaceOptions, type KerasAdapterOptions, type KerasLayerConfig, type KerasModelConfig, LAYER_COLORS, type Label3D, type Layer, type Layer3D, type LayerCategory, type Layout, type LearningCurveHandle, type LearningCurveOptions, type LegendOptions, type LiftCurve, type LiftCurveHandle, type LiftCurveOptions, Line3DLayer, type Line3DOptions, type LineJoin, LineLayer, type LineOptions, type LinearFit, LinearScale, LogScale, ML_PALETTE, type Macd, type MarkerShape, type Mat4, type MlpOptions, type ModelBlock, type ModelBoxSizing, type ModelEdge, type ModelEdgePath, type ModelGraph, type ModelGraph3DHandle, type ModelGraph3DOptions, type ModelGraphHandle, type ModelGraphOptions, type ModelLayoutOptions, type ModelLayoutResult, type ModelNode, type ModelNodeBox, type MulticlassRoc, type Ohlc, type OhlcArrays, type OhlcInput, OhlcLayer, type OhlcOptions, type OnnxAdapterOptions, type OnnxGraph, type OnnxNode, OrdinalTimeScale, PALETTES, PARALLEL_PALETTE, type PaletteName, type PaletteSpec, type ParallelAxis, type ParallelHandle, type ParallelLayoutResult, type ParallelLine, type ParallelOptions, type PartialDependenceHandle, type PartialDependenceOptions, type Patch, PatchesLayer, type PatchesOptions, type PcaResult, type PfColumn, type PickMode, type Picked, PieLayer, type PieOptions, type PivotLevels, Plot, Plot3D, type Plot3DOptions, type PlotOptions, type PlotTitleOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, type PrCurve, type PrCurveHandle, type PrCurveOptions, type PredVsActualHandle, type PredVsActualOptions, type Psd, type PsdHandle, type PsdOptions, Quiver3DLayer, type Quiver3DOptions, QuiverLayer, type QuiverOptions, type RGB, type Range, type RegressionHandle, type RegressionOptions, type RenderType, type RenkoOptions, type ResampledOhlc, type ResidualsHandle, type ResidualsOptions, type ResolvedAxisStyle, type RidgeGroup, type RidgelineHandle, type RidgelineOptions, type Ring, type RocCurve, type RocCurveHandle, type RocCurveOptions, type SankeyLayoutOptions, type SankeyLayoutResult, type SankeyLink, type SankeyNode, type SankeyNodeRect, type SankeyOptions, type SankeyRibbon, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type SequentialLayer, type ShapBeeswarmHandle, type ShapBeeswarmOptions, type SklearnStep, type Spectrogram, type StackedAreaOptions, type StackedBarOptions, StemLayer, type StemOptions, type Stochastic, type SunburstArc, type SunburstLayoutOptions, type SunburstNode, type SunburstOptions, type SuperTrend, SurfaceLayer, type SurfaceOptions, TRANSFORM_GLSL, TRANSFORM_UNIFORMS, TREEMAP_PALETTE, type Table, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type TorchFxNode, type TrainingCurvesHandle, type TrainingCurvesOptions, type TrainingSeries, type TreemapCell, type TreemapExtent, type TreemapItem, type TreemapOptions, type Trend, VolumeLayer, type VolumeOptions, type VolumeProfile, type VolumeProfileOptions, type WelchOptions, type WindowName, type YAxisOptions, addAttentionMap, addBollinger, addCalibration, addChord, addConfusionMatrix, addCorrMatrix, addDecisionBoundary, addDepth, addDrawdown, addEcdf, addEmbedding, addFeatureImportance, addFunnel, addGauge, addHeikinAshi, addLearningCurve, addLiftCurve, addModelGraph, addModelGraph3D, addParallelCoordinates, addPartialDependence, addPrCurve, addPredVsActual, addPsd, addRegression, addRenko, addResiduals, addRidgeline, addRocCurve, addSankey, addShapBeeswarm, addSunburst, addTrainingCurves, addTreemap, addVolumeProfile, adx, aroon, atr, autoTicks, beeswarmLayout, bollinger, boxStats, brierScore, bufferUsage, calibrationCurve, canvasToBlob, cci, chordLayout, classificationReport, colormap, colormapFromStops, colormapGradient, colormapLUT, colormapNames, confusionMatrix, copyCanvasToClipboard, corrMatrix, correlation, createProgram, createToolbar, crossCorrelate, darkTheme, defaultFormat, depth, discreteColormap, donchian, downloadCanvas, drawdown, earcut, ecdf, ema, emaSmooth, fft, fibRetracements, firstFinite, forceLayout, formatCount, formatShape, funnelLayout, gaugeLayout, heikinAshi, histogram, ichimoku, kde, keltner, layerCategory, liftCurve, lightTheme, lineBreak, linearRegression, linearTrend, linkX, loess, logLoss, lttb, macd, mae, makeScale, marchingCubes, mfi, mlpModel, modelBoxDims, modelGraphFromKeras, modelGraphFromOnnx, modelGraphFromSklearn, modelGraphFromTorchFx, modelLayout, mse, obv, palette, paletteColor, paletteNames, parabolicSar, parallelLayout, parseCSV, parseColor, pca, pivotPoints, pointAndFigure, prCurve, quantileSorted, r2, registerColormap, registerPalette, renderColorbars, renko, resampleOhlc, resolveAxisStyle, resolveTicks, reverseColormap, rmse, rocCurve, rocCurveOvR, rollingStd, rsi, sankeyLayout, savitzkyGolay, sequentialModel, setTransformUniforms, sma, spectrogram, standardize, stochastic, sunburstLayout, superTrend, symmetricDomain, toColorCss, treemapLayout, trueRange, uniformLocations, volumeProfile, vwap, welch, williamsR, windowFunction, withMinorTicks, wma, zscore };