@photonviz/core 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -22,6 +22,42 @@ interface AxisConfig {
     minorTicks?: boolean | number;
     /** Axis title, drawn along the axis. */
     title?: string;
+    /** Draw the axis line. Default true. */
+    showAxisLine?: boolean;
+    /** Axis line color. Default: the per-axis `color`, else `theme.axis`. */
+    axisLineColor?: string;
+    /** Axis line width in px. Default 1. */
+    axisLineWidth?: number;
+    /** Draw tick marks. Default true. */
+    showTicks?: boolean;
+    /** Tick mark color. Default: the per-axis `color`, else `theme.axis`. */
+    tickColor?: string;
+    /** Major tick length in px. Default 5 (minor ticks are 3). */
+    tickLength?: number;
+    /** Tick mark line width in px. Default 1. */
+    tickWidth?: number;
+    /** Tick label color. Default: the per-axis `color`, else `theme.text`. */
+    labelColor?: string;
+    /** Tick label font (CSS `font` shorthand). Default `theme.font`. */
+    labelFont?: string;
+    /** Rotate tick labels by this many degrees. Default 0. */
+    labelRotation?: number;
+    /** Gap in px between a tick and its label. Default 3. */
+    labelStandoff?: number;
+    /** Axis title color. Default: the per-axis `color`, else `theme.text`. */
+    titleColor?: string;
+    /** Axis title font (CSS `font` shorthand). Default `theme.font`. */
+    titleFont?: string;
+    /** Draw grid lines for this axis. Default true. */
+    showGrid?: boolean;
+    /** Major grid line color. Default `theme.grid`. */
+    gridColor?: string;
+    /** Grid line width in px. Default 1. */
+    gridWidth?: number;
+    /** Grid line dash pattern (Canvas `setLineDash`). Default solid. */
+    gridDash?: number[];
+    /** Minor grid line color. Default `theme.gridMinor`. */
+    gridMinorColor?: string;
 }
 type Dim = "x" | "y";
 /**
@@ -32,6 +68,13 @@ type Dim = "x" | "y";
  *  - `box-y`  drag selects a y-range only (full width band) — Y-only zoom
  */
 type InteractionMode = "pan" | "box" | "box-x" | "box-y";
+/**
+ * How a layer expects its data to change, mapped to a WebGL buffer-usage hint:
+ * `"static"` → `STATIC_DRAW` (upload once), `"dynamic"` → `DYNAMIC_DRAW` (stream
+ * via `setData`). Purely a performance hint — `setData` works either way. Default
+ * `"static"`. Set `"dynamic"` on layers you update every frame.
+ */
+type RenderType = "static" | "dynamic";
 type Range = readonly [number, number];
 interface Bounds {
     x: Range;
@@ -95,6 +138,8 @@ interface AreaOptions {
     /** Lower edge(s). Number or per-point array — pass cumulative to stack. */
     base?: number | ArrayLike<number>;
     color?: string | Color;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
@@ -110,6 +155,7 @@ declare class AreaLayer implements Layer {
     private uniforms;
     private vertexCount;
     private color;
+    private usage;
     private xRef;
     private yRef;
     private xBounds;
@@ -136,7 +182,20 @@ interface BarOptions {
     width?: number;
     /** Shift bars by this many data units (use for grouped bars). */
     offset?: number;
+    /**
+     * `"v"` (default) draws vertical bars: `x` positions along the x axis, `y`
+     * values along the y axis. `"h"` draws horizontal bars: `x` positions along the
+     * **y** axis, `y` values along the **x** axis, `width` is the bar thickness.
+     */
+    orientation?: "v" | "h";
     color?: string | Color;
+    /**
+     * Per-bar colors (overrides {@link color}). Handy for tinting each bar — e.g.
+     * volume bars green/red by the candle's direction. Length should match `x`.
+     */
+    colors?: Array<string | Color>;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
@@ -152,16 +211,21 @@ declare class BarLayer implements Layer {
     private uniforms;
     private count;
     private color;
+    private colorsInput?;
+    private usage;
     private barWidth;
     private offset;
+    private orientation;
     private xRef;
     private yRef;
     private xBounds;
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: BarOptions);
+    /** Per-bar color array (each bar uses its `colors[i]` or falls back to `color`). */
+    private buildColors;
     private buildRects;
-    /** Replace bar values and re-upload (for streaming). */
-    setData(x: ArrayLike<number>, y: ArrayLike<number>, base?: number | ArrayLike<number>): void;
+    /** Replace bar values (and optionally per-bar colors) and re-upload for streaming. */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, base?: number | ArrayLike<number>, colors?: Array<string | Color>): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -185,6 +249,8 @@ interface BoxOptions {
     box?: boolean;
     /** Draw a violin (KDE) shape behind/instead of the box (default false). */
     violin?: boolean;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     yAxis?: string;
 }
 declare class BoxLayer implements Layer {
@@ -204,7 +270,15 @@ declare class BoxLayer implements Layer {
     private lineCount;
     private pointStart;
     private pointCount;
+    private width;
+    private showBox;
+    private showViolin;
+    private usage;
     constructor(gl: WebGL2RenderingContext, opts: BoxOptions);
+    /** Build box/whisker/violin geometry from the groups; sets refs, bounds and draw ranges. */
+    private build;
+    /** Replace the box groups and rebuild the geometry (for streaming). */
+    setData(groups: BoxGroup[], width?: number): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -228,9 +302,29 @@ interface CandlestickOptions {
     downColor?: string | Color;
     /** Wick thickness in CSS px. Default 1.5. */
     wickWidth?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
+/** The OHLC of a single candle — used by {@link CandlestickLayer.updateLast}/`appendCandle`. */
+interface Candle {
+    x: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+}
+/** New OHLC arrays for {@link CandlestickLayer.setData} (colors/width stay fixed). */
+interface CandlestickData {
+    x: ArrayLike<number>;
+    open: ArrayLike<number>;
+    high: ArrayLike<number>;
+    low: ArrayLike<number>;
+    close: ArrayLike<number>;
+    /** Optional new body width; keeps the previous width if omitted. */
+    width?: number;
+}
 declare class CandlestickLayer implements Layer {
     readonly id: string;
     readonly name: string;
@@ -244,12 +338,120 @@ declare class CandlestickLayer implements Layer {
     private uBody;
     private uWick;
     private wickWidth;
+    private usage;
+    private up;
+    private down;
+    /** Body width in data units (median-derived unless the user fixed it). */
+    private bodyWidth;
+    private explicitWidth;
+    private xs;
+    private os;
+    private hs;
+    private ls;
+    private cs;
+    private rects;
+    private wicks;
+    private colors;
     private count;
     private xRef;
     private yRef;
     private xBounds;
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: CandlestickOptions);
+    /** Copy the incoming OHLC arrays into the retained plain arrays. */
+    private ingest;
+    /** Write candle `i`'s body rect, wick segment and up/down color into the arrays. */
+    private emitCandle;
+    /** Recompute width/refs/bounds and refill the vertex arrays from the retained OHLC. */
+    private rebuild;
+    /** Re-upload all three per-candle buffers (after a full rebuild). */
+    private upload;
+    /** Replace every candle and re-upload (for streaming a whole new window). */
+    setData(data: CandlestickData): void;
+    /**
+     * Append one new candle (grows the series). Prefer {@link updateLast} for the
+     * in-progress candle and `appendCandle` only when a bar closes and a new one opens.
+     */
+    appendCandle(c: Candle): void;
+    /**
+     * Update the most recent candle in place — the cheap hot path for a live
+     * (forming) bar. Only that candle's 12 floats are re-uploaded; bounds are
+     * extended (never shrunk) to include it. No-op when the series is empty.
+     */
+    updateLast(c: Candle): void;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+/**
+ * An OHLC bar chart — the western cousin of the candlestick. Each period is a
+ * vertical low→high line with a left tick at the open and a right tick at the
+ * close, colored up/down by direction. Streams like {@link CandlestickLayer}.
+ */
+interface OhlcOptions {
+    /** Bar positions (data space — e.g. epoch ms on a time axis). */
+    x: ArrayLike<number>;
+    open: ArrayLike<number>;
+    high: ArrayLike<number>;
+    low: ArrayLike<number>;
+    close: ArrayLike<number>;
+    /** Total tick span in data units (each open/close tick is half of this). Default 70% of median spacing. */
+    width?: number;
+    /** Close ≥ open color. Default green. */
+    upColor?: string | Color;
+    /** Close < open color. Default red. */
+    downColor?: string | Color;
+    /** Line thickness in CSS px. Default 1.5. */
+    lineWidth?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+    name?: string;
+    yAxis?: string;
+}
+declare class OhlcLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffers;
+    private uniforms;
+    private lineWidth;
+    private usage;
+    private up;
+    private down;
+    private barWidth;
+    private explicitWidth;
+    private xs;
+    private os;
+    private hs;
+    private ls;
+    private cs;
+    private segs;
+    private colors;
+    private count;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    constructor(gl: WebGL2RenderingContext, opts: OhlcOptions);
+    private ingest;
+    /** Write bar `i`'s three segments (+ colors) at instance base `i * SEGS_PER_BAR`. */
+    private emitBar;
+    private rebuild;
+    private upload;
+    /** Replace every bar and re-upload (for streaming a whole new window). */
+    setData(data: CandlestickData): void;
+    /** Append one new bar (grows the series). */
+    appendCandle(c: Candle): void;
+    /** Update the most recent bar in place — the cheap hot path for a live bar. */
+    updateLast(c: Candle): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -260,7 +462,13 @@ declare class CandlestickLayer implements Layer {
 
 type RGB = [number, number, number];
 type ColormapName = "viridis" | "plasma" | "coolwarm" | "grayscale";
-/** Returns a `(t in 0..1) => RGB` sampler for the named colormap. */
+/**
+ * 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 {
@@ -277,6 +485,8 @@ interface ContourOptions {
     /** Single line color; if omitted, levels are colored by a colormap. */
     color?: string | Color;
     colormap?: ColormapName;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     yAxis?: string;
 }
 declare class ContourLayer implements Layer {
@@ -291,7 +501,17 @@ declare class ContourLayer implements Layer {
     private xRef;
     private yRef;
     private ext;
+    private cols;
+    private rows;
+    private levelsOpt;
+    private cmap;
+    private fixedColor;
+    private usage;
     constructor(gl: WebGL2RenderingContext, opts: ContourOptions);
+    /** Marching-squares the scalar field into iso-line segments; sets vertexCount. */
+    private build;
+    /** Replace the scalar field and recompute the iso lines (for streaming). */
+    setData(values: ArrayLike<number>, cols?: number, rows?: number): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -323,9 +543,20 @@ interface ErrorBarOptions {
     band?: boolean;
     /** Band fill opacity. Default 0.2. */
     bandOpacity?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
+/** New positions/errors for {@link ErrorBarLayer.setData} (styling stays fixed). */
+interface ErrorBarData {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    yerr?: ErrInput;
+    yerrLow?: ErrInput;
+    yerrHigh?: ErrInput;
+    xerr?: ErrInput;
+}
 declare class ErrorBarLayer implements Layer {
     readonly id: string;
     readonly name: string;
@@ -346,6 +577,7 @@ declare class ErrorBarLayer implements Layer {
     private bandOpacity;
     private showWhiskers;
     private showBand;
+    private usage;
     private segCount;
     private capCount;
     private bandVerts;
@@ -354,6 +586,73 @@ declare class ErrorBarLayer implements Layer {
     private xBounds;
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: ErrorBarOptions);
+    /** Recompute refs/bounds/counts and the whisker/cap/band vertex arrays from new data. */
+    private build;
+    /** Replace the data and re-upload (for streaming). */
+    setData(data: ErrorBarData): void;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface GraphOptions {
+    /** Node positions (data space). */
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    /** Edges as index pairs into the node arrays. */
+    edges: ReadonlyArray<readonly [number, number]>;
+    nodeColor?: string | Color;
+    /** Node diameter in CSS pixels. Default 10. */
+    nodeSize?: number;
+    edgeColor?: string | Color;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+    name?: string;
+    yAxis?: string;
+}
+/** New nodes/edges for {@link GraphLayer.setData} (colors/size stay fixed). */
+interface GraphData {
+    /** Node positions. Omit both to run a force layout from `edges`. */
+    x?: ArrayLike<number>;
+    y?: ArrayLike<number>;
+    edges: ReadonlyArray<readonly [number, number]>;
+    /** Node count for the force layout when `x`/`y` are omitted. Defaults to max edge index + 1. */
+    nodeCount?: number;
+}
+/** A node-link graph: edges as line segments, nodes as round points. */
+declare class GraphLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private progs;
+    private nodeVao;
+    private edgeVao;
+    private buffers;
+    private edgeUniforms;
+    private nodeUniforms;
+    private nodeCount;
+    private edgeVerts;
+    private nodeColor;
+    private edgeColor;
+    private nodeSize;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    private usage;
+    constructor(gl: WebGL2RenderingContext, opts: GraphOptions);
+    /** Build node/edge vertex arrays from positions + edges; sets counts, refs and bounds. */
+    private build;
+    /**
+     * Replace nodes and edges (for streaming). When `x`/`y` are omitted, node
+     * positions are recomputed with the package's force layout from the edges.
+     */
+    setData(data: GraphData): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -377,6 +676,8 @@ interface HeatmapOptions {
     domain?: Range;
     /** Bilinear filtering (default true) vs. hard cells. */
     smooth?: boolean;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     yAxis?: string;
 }
 declare class HeatmapLayer implements Layer {
@@ -391,7 +692,15 @@ declare class HeatmapLayer implements Layer {
     private xRef;
     private yRef;
     private ext;
+    private lut;
+    private fixedDomain;
+    private cols;
+    private rows;
     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;
     bounds(): {
         x: Range;
         y: Range;
@@ -408,6 +717,8 @@ interface HexbinOptions {
     colormap?: ColormapName;
     /** Count range mapped to the colormap. Defaults to [1, maxCount]. */
     domain?: Range;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     yAxis?: string;
 }
 declare class HexbinLayer implements Layer {
@@ -424,7 +735,15 @@ declare class HexbinLayer implements Layer {
     private yRef;
     private xBounds;
     private yBounds;
+    private cmap;
+    private explicitRadius;
+    private domain;
+    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;
     bounds(): {
         x: Range;
         y: Range;
@@ -433,6 +752,65 @@ declare class HexbinLayer implements Layer {
     dispose(): void;
 }
 
+/** Anything `texImage2D` accepts, or a URL string the layer loads itself. */
+type ImageSource = TexImageSource | string;
+interface ImageOptions {
+    /** A decoded bitmap/canvas/ImageData, or a URL to load (CORS-enabled). */
+    source: ImageSource;
+    /** Data-space rectangle the image spans. */
+    extent: {
+        x: Range;
+        y: Range;
+    };
+    /** Bilinear filtering (default) vs. nearest. */
+    smooth?: boolean;
+    /** Overall opacity 0..1. Default 1. */
+    opacity?: number;
+    /** Called after an async (URL) image finishes loading — wire to `plot.requestRender`. */
+    onLoad?: () => void;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+    name?: string;
+    yAxis?: string;
+}
+/**
+ * An RGBA image (Bokeh `image_rgba` / `image_url`) drawn as a textured quad over
+ * a data-space extent — reuses the heatmap quad path. A `string` source is loaded
+ * asynchronously; pass `onLoad` (→ `plot.requestRender`) so the plot redraws once
+ * the pixels arrive.
+ */
+declare class ImageLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss = "#94a3b8";
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private texture;
+    private uniforms;
+    private xRef;
+    private yRef;
+    private ext;
+    private opacity;
+    private smooth;
+    private ready;
+    private img;
+    constructor(gl: WebGL2RenderingContext, opts: ImageOptions);
+    /** Point the texture at a new source: load a URL async, or upload a bitmap now. */
+    private setSource;
+    /** Replace the image source and re-upload the texture (for streaming). */
+    setData(source: ImageSource, onLoad?: () => void): void;
+    private upload;
+    bounds(): {
+        x: Range;
+        y: Range;
+    };
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
 /**
  * Shared hover-picking used by point/series layers (line, scatter, stem).
  *
@@ -483,6 +861,8 @@ interface LineOptions {
      * zoomed out (preserves peaks). Requires monotonic x; auto-detected. Default true.
      */
     decimate?: boolean;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 declare class LineLayer implements Layer {
     readonly id: string;
@@ -511,6 +891,7 @@ declare class LineLayer implements Layer {
     private monotonic;
     private gpuDec;
     private step?;
+    private usage;
     private xRef;
     private yRef;
     private xs;
@@ -540,6 +921,131 @@ declare class LineLayer implements Layer {
     dispose(): void;
 }
 
+/** One filled polygon: a ring of `x`/`y`, with optional holes. */
+interface Patch {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    /** Vertex indices where each hole ring starts (mapbox-earcut convention). */
+    holes?: number[];
+    /** Explicit fill color (overrides the layer default / colormap). */
+    color?: string | Color;
+    /** Value used to color this patch via the layer `colormap` (choropleth). */
+    value?: number;
+}
+interface PatchesOptions {
+    patches: Patch[];
+    /** Default fill for patches without their own `color`/`value`. */
+    color?: string | Color;
+    /** Color patches by `value` through this colormap (choropleth). */
+    colormap?: ColormapName;
+    /** Value range mapped to [0,1] for the colormap. Defaults to the data min/max. */
+    domain?: Range;
+    /** Fill opacity, 0..1. Default 1. */
+    opacity?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+    name?: string;
+    yAxis?: string;
+}
+/**
+ * Filled polygons (Bokeh `patches`). Each ring is triangulated once on the CPU
+ * with ear-clipping (holes supported), then rendered as a static per-vertex-color
+ * triangle soup — only the transform uniforms change per frame.
+ */
+declare class PatchesLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffers;
+    private uniforms;
+    private vertexCount;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    private defRgba;
+    private opacity;
+    private cmap;
+    private domainOpt;
+    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;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface PieOptions {
+    /** Slice magnitudes (need not sum to 1 — they are normalized). */
+    values: ArrayLike<number>;
+    /** 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;
+    /** Center in data space. Default `[0, 0]`. */
+    center?: [number, number];
+    /** Outer radius in data units. Default `1`. */
+    radius?: number;
+    /** Inner radius (> 0 makes a donut). Default `0`. */
+    innerRadius?: number;
+    /** Angle of the first slice edge, radians. Default `Math.PI / 2` (12 o'clock). */
+    startAngle?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+    name?: string;
+    yAxis?: string;
+}
+/**
+ * A pie / donut chart drawn as a per-vertex-color triangle soup (wedges as fans,
+ * or quad strips when a donut). Reuses the shared solid-fill program. Slices sweep
+ * clockwise from `startAngle`. Set the plot's `equalAspect` so it stays circular.
+ */
+declare class PieLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffers;
+    private uniforms;
+    private vertexCount;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    private cx;
+    private cy;
+    private R;
+    private rIn;
+    private start;
+    private colorsOpt;
+    private cmap;
+    private usage;
+    constructor(gl: WebGL2RenderingContext, opts: PieOptions);
+    /** Recompute vertexCount and the position/color triangle soup from new slice values. */
+    private build;
+    /** Replace the slice values and re-upload (for streaming). */
+    setData(values: ArrayLike<number>): void;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
 interface QuiverOptions {
     /** Arrow anchor positions (data space). */
     x: ArrayLike<number>;
@@ -560,6 +1066,8 @@ interface QuiverOptions {
         colormap?: ColormapName;
         domain?: Range;
     };
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
@@ -579,6 +1087,9 @@ declare class QuiverLayer implements Layer {
     private width;
     private headSize;
     private useVertexColor;
+    private explicitScale;
+    private colorBy;
+    private usage;
     private count;
     private xRef;
     private yRef;
@@ -586,6 +1097,10 @@ declare class QuiverLayer implements Layer {
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: QuiverOptions);
     private bindInstanceAttribs;
+    /** Recompute count/refs/bounds and the arrow+color arrays from new x/y/u/v. */
+    private build;
+    /** Replace the data and re-upload (for streaming). */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, u: ArrayLike<number>, v: ArrayLike<number>): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -594,12 +1109,16 @@ declare class QuiverLayer implements Layer {
     dispose(): void;
 }
 
+/** Marker glyph shape for a scatter series. */
+type MarkerShape = "circle" | "square" | "triangle" | "diamond" | "cross" | "plus";
 interface ScatterOptions {
     x: ArrayLike<number>;
     y: ArrayLike<number>;
     color?: string | Color;
     /** Marker diameter in CSS pixels. */
     size?: number;
+    /** Marker glyph. Default `"circle"`. */
+    marker?: MarkerShape;
     name?: string;
     yAxis?: string;
     /**
@@ -615,6 +1134,8 @@ interface ScatterOptions {
         /** Value range mapped to [0,1]. Defaults to the data min/max. */
         domain?: Range;
     };
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 declare class ScatterLayer implements Layer {
     readonly id: string;
@@ -628,6 +1149,8 @@ declare class ScatterLayer implements Layer {
     private uniforms;
     private count;
     private size;
+    private marker;
+    private usage;
     private color;
     private useVertexColor;
     private labels?;
@@ -661,6 +1184,8 @@ interface StemOptions {
     width?: number;
     /** Tip marker diameter in CSS px (0 hides). Default 6. */
     markerSize?: number;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
     name?: string;
     yAxis?: string;
 }
@@ -680,6 +1205,7 @@ declare class StemLayer implements Layer {
     private width;
     private markerSize;
     private count;
+    private usage;
     private baseline;
     private xRef;
     private yRef;
@@ -688,6 +1214,10 @@ declare class StemLayer implements Layer {
     private xBounds;
     private yBounds;
     constructor(gl: WebGL2RenderingContext, opts: StemOptions);
+    /** Recompute count/refs/bounds and the stem+tip vertex arrays from new x/y. */
+    private build;
+    /** Replace the data and re-upload (for streaming). */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
     bounds(): {
         x: Range;
         y: Range;
@@ -748,8 +1278,50 @@ declare class TimeScale implements Scale {
     ticks(target?: number): Tick[];
     formatTick(value: number): string;
 }
-type ScaleType = "linear" | "log" | "time";
-declare function makeScale(type: ScaleType, domain?: Range): Scale;
+/**
+ * A categorical (factor) axis. Internally it is **linear over a band domain**
+ * `[-0.5, n-0.5]`, so factor `i` sits at the band centre and `norm(i)` equals the
+ * ordinary linear projection — the GPU transform needs no special handling, and a
+ * layer plotting at integer indices lands on band centres automatically.
+ * "Categorical-ness" lives only in the ticks/labels (one per factor).
+ */
+declare class CategoricalScale implements Scale {
+    readonly type = "categorical";
+    readonly log = false;
+    factors: string[];
+    domain: Range;
+    constructor(factors?: string[]);
+    norm(value: number): number;
+    invert(t: number): number;
+    ticks(): Tick[];
+    formatTick(value: number): string;
+}
+/**
+ * An **ordinal time** axis — the standard financial x-axis. Bars are plotted at
+ * evenly-spaced integer indices `0..n-1` (like {@link CategoricalScale}, so the
+ * domain is the band `[-0.5, n-1+0.5]`), which **collapses market gaps**
+ * (weekends, overnight, holidays) instead of leaving blank space the way a real
+ * {@link TimeScale} would. Each index carries a timestamp; ticks are placed at
+ * natural calendar boundaries (day / month / year, or hour / minute when zoomed
+ * in) and subsampled toward the target count, so labels stay readable at any zoom.
+ *
+ * Plot your candles/bars at `x = 0,1,2,…` and pass the per-bar epoch-ms `times`.
+ */
+declare class OrdinalTimeScale implements Scale {
+    readonly type = "ordinal-time";
+    readonly log = false;
+    times: number[];
+    domain: Range;
+    constructor(times?: ArrayLike<number>);
+    norm(value: number): number;
+    invert(t: number): number;
+    /** Timestamp at a (rounded, clamped) index. */
+    private timeAt;
+    ticks(target?: number): Tick[];
+    formatTick(value: number): string;
+}
+type ScaleType = "linear" | "log" | "time" | "categorical" | "ordinal-time";
+declare function makeScale(type: ScaleType, domain?: Range, factors?: string[], times?: ArrayLike<number>): Scale;
 
 /** Pixel geometry of the plot, in CSS pixels. The plot region excludes margins. */
 interface Layout {
@@ -771,52 +1343,206 @@ interface Theme {
 }
 declare const lightTheme: Theme;
 declare const darkTheme: Theme;
+/** Concrete axis styling, resolved from an {@link AxisConfig} against a {@link Theme}. */
+interface ResolvedAxisStyle {
+    showAxisLine: boolean;
+    axisLineColor: string;
+    axisLineWidth: number;
+    showTicks: boolean;
+    tickColor: string;
+    tickLength: number;
+    tickMinorLength: number;
+    tickWidth: number;
+    labelColor: string;
+    labelFont: string;
+    labelRotation: number;
+    labelStandoff: number;
+    titleColor: string;
+    titleFont: string;
+    showGrid: boolean;
+    gridColor: string;
+    gridMinorColor: string;
+    gridWidth: number;
+    gridDash: number[];
+}
+/**
+ * Fold an {@link AxisConfig}'s optional style fields onto the theme defaults.
+ * Colored fields fall back to `colorOverride` (a secondary y-axis's `color`) before
+ * the theme, so an unstyled colored axis still tints its line/ticks/labels/title.
+ * With an empty config this reproduces the pre-styling look exactly.
+ */
+declare function resolveAxisStyle(cfg: AxisConfig, theme: Theme, colorOverride?: string): ResolvedAxisStyle;
+interface PlotTitleOptions {
+    text: string;
+    /** CSS `font` shorthand. Default `"600 15px system-ui, ..."`. */
+    font?: string;
+    color?: string;
+    align?: "left" | "center" | "right";
+}
 
 interface AxisScaleOptions {
     type?: ScaleType;
     /** Fixed domain. If omitted, the axis autoscales to the data. */
     domain?: Range;
+    /** Factor labels for a `"categorical"` axis (fixes the domain to the bands). */
+    factors?: string[];
+    /**
+     * Per-index epoch-ms timestamps for an `"ordinal-time"` axis (finance/session
+     * axis). Plot bars at integer indices `0..times.length-1`; gaps collapse and
+     * ticks show calendar dates.
+     */
+    times?: ArrayLike<number>;
+}
+/** Legend placement + styling. `legend: true` uses all defaults. */
+interface LegendOptions {
+    /** Corner within the plot region. Default `"top-right"`. */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Stack entries vertically (default) or in a row. */
+    orientation?: "vertical" | "horizontal";
+    background?: string;
+    border?: string;
+    textColor?: string;
+    font?: string;
 }
 interface YAxisOptions extends AxisConfig {
     type?: ScaleType;
     domain?: Range;
+    /** Factor labels for a `"categorical"` axis. */
+    factors?: string[];
+    /** Per-index epoch-ms timestamps for an `"ordinal-time"` axis. */
+    times?: ArrayLike<number>;
     /** Which side to draw the axis on. Default `"right"` for secondary axes. */
     side?: "left" | "right";
     /** Axis + label color (secondary axes often match their series). */
     color?: string;
 }
-/** One line of the hover tooltip header, produced by {@link PlotOptions.hoverReadout}. */
-interface HoverReadoutRow {
-    label: string;
-    value: string;
+/** One series in a grouped/stacked bar chart. */
+interface BarSeries {
+    /** Value per category (parallel to the shared `x` positions). */
+    y: ArrayLike<number>;
+    color?: string;
+    name?: string;
 }
-interface PlotOptions {
-    scales?: {
-        x?: AxisScaleOptions;
-        y?: AxisScaleOptions;
-    };
-    axes?: {
-        x?: AxisConfig;
-        y?: AxisConfig;
-    };
-    theme?: "light" | "dark" | Theme;
-    margin?: Partial<Layout["margin"]>;
-    /** Enable wheel-zoom and drag interaction. Default true. */
-    interactive?: boolean;
-    /** Show the built-in toolbar (home + pan/box/X/Y zoom modes). Default true. */
-    showToolbar?: boolean;
-    /** Initial interaction mode. Default `"pan"`. */
-    mode?: InteractionMode;
-    /** Enable hover crosshair + tooltip. Default true. */
-    hover?: boolean;
-    /**
-     * How hover selects the highlighted point: `"x"` nearest by x (classic),
-     * `"y"` nearest by y, or `"xy"` nearest by 2D distance — the last checks both
-     * axes, which is what a scatter/map needs. Default `"x"`.
-     */
-    pick?: PickMode;
-    /**
-     * When a point's pinned detail box appears: `"click"` pins it on click (until
+/** Options for {@link Plot.addGroupedBars} — one cluster of bars per category. */
+interface GroupedBarOptions {
+    /** Category positions (e.g. `0..n-1` for a categorical axis). */
+    x: ArrayLike<number>;
+    series: BarSeries[];
+    /** Total width of one group (all its bars) in data units. Default 0.8. */
+    groupWidth?: number;
+    /** Fractional gap between bars within a group, 0..1. Default 0.1. */
+    gap?: number;
+    /** `"v"` vertical (default) or `"h"` horizontal bars. */
+    orientation?: "v" | "h";
+    yAxis?: string;
+}
+/** Options for {@link Plot.addStackedBars} — series stacked on top of each other. */
+interface StackedBarOptions {
+    /** Category positions (e.g. `0..n-1` for a categorical axis). */
+    x: ArrayLike<number>;
+    series: BarSeries[];
+    /** Bar width in data units. Defaults to 80% of the median spacing. */
+    width?: number;
+    /** `"v"` vertical (default) or `"h"` horizontal bars. */
+    orientation?: "v" | "h";
+    yAxis?: string;
+}
+/** One series in a stacked area chart. */
+interface AreaSeries {
+    y: ArrayLike<number>;
+    color?: string;
+    name?: string;
+}
+/** Options for {@link Plot.addStackedArea}. */
+interface StackedAreaOptions {
+    x: ArrayLike<number>;
+    series: AreaSeries[];
+    yAxis?: string;
+}
+/** Options for {@link Plot.addGraph}. Positions are optional — omit them (give `nodes`) to auto-lay-out. */
+interface GraphInput extends Omit<GraphOptions, "x" | "y"> {
+    x?: ArrayLike<number>;
+    y?: ArrayLike<number>;
+    /** Node count when `x`/`y` are omitted (else inferred from the max edge index). */
+    nodes?: number;
+}
+/**
+ * A Canvas2D overlay marker drawn above the data, projected through the scales:
+ * a full-width/height guide line (`span`), a shaded range (`band`), a rectangle
+ * (`box`), or text (`label`). `yAxis` targets a secondary axis where relevant.
+ */
+type Annotation = {
+    type: "span";
+    dim: Dim;
+    value: number;
+    color?: string;
+    width?: number;
+    dash?: number[];
+    yAxis?: string;
+} | {
+    type: "band";
+    dim: Dim;
+    from: number;
+    to: number;
+    color?: string;
+    yAxis?: string;
+} | {
+    type: "box";
+    x: Range;
+    y: Range;
+    color?: string;
+    border?: string;
+    yAxis?: string;
+} | {
+    type: "label";
+    x: number;
+    y: number;
+    text: string;
+    color?: string;
+    font?: string;
+    align?: "left" | "center" | "right";
+    yAxis?: string;
+};
+/** One line of the hover tooltip header, produced by {@link PlotOptions.hoverReadout}. */
+interface HoverReadoutRow {
+    label: string;
+    value: string;
+}
+interface PlotOptions {
+    scales?: {
+        x?: AxisScaleOptions;
+        y?: AxisScaleOptions;
+    };
+    axes?: {
+        x?: AxisConfig;
+        y?: AxisConfig;
+    };
+    theme?: "light" | "dark" | Theme;
+    /** Fill color for the plot region (inside the margins). Default transparent. */
+    background?: string;
+    /** Fill color for the whole canvas incl. margins. Default transparent. */
+    border?: string;
+    /** Plot title, drawn in a reserved strip above the plot. */
+    title?: string | PlotTitleOptions;
+    /** Show a legend of named series. `true` uses defaults; pass an object to place/style it. */
+    legend?: boolean | LegendOptions;
+    margin?: Partial<Layout["margin"]>;
+    /** Enable wheel-zoom and drag interaction. Default true. */
+    interactive?: boolean;
+    /** Show the built-in toolbar (home + pan/box/X/Y zoom modes). Default true. */
+    showToolbar?: boolean;
+    /** Initial interaction mode. Default `"pan"`. */
+    mode?: InteractionMode;
+    /** Enable hover crosshair + tooltip. Default true. */
+    hover?: boolean;
+    /**
+     * How hover selects the highlighted point: `"x"` nearest by x (classic),
+     * `"y"` nearest by y, or `"xy"` nearest by 2D distance — the last checks both
+     * axes, which is what a scatter/map needs. Default `"x"`.
+     */
+    pick?: PickMode;
+    /**
+     * When a point's pinned detail box appears: `"click"` pins it on click (until
      * you click empty space), `"hover"` shows it while the cursor is over a point.
      * Default `"click"`.
      */
@@ -888,10 +1614,21 @@ declare class Plot {
     private hoverReadout?;
     /** Cursor position while the pointer is pressed, when `crosshair`. */
     private pressPx;
+    private viewListeners;
+    private cursorListeners;
+    private lastEmittedX;
+    private lastEmittedCursor;
+    private linkedCursorX;
     private tooltip;
     /** A point clicked to pin its details, until another click clears it. */
     private selected;
     private infoBox;
+    private annotations;
+    private bgFill?;
+    private borderFill?;
+    private title;
+    private legend;
+    private legendDiv;
     constructor(container: HTMLElement, options?: PlotOptions);
     private makeCanvas;
     /** Margins grow to make room for extra y axes on each side. */
@@ -919,6 +1656,16 @@ declare class Plot {
     addLine(opts: LineOptions): LineLayer;
     addScatter(opts: ScatterOptions): ScatterLayer;
     addBar(opts: BarOptions): BarLayer;
+    /**
+     * Grouped (clustered) bars: one {@link BarLayer} per series, each shifted within
+     * its category group so the bars sit side by side. Returns the layers in order.
+     */
+    addGroupedBars(opts: GroupedBarOptions): BarLayer[];
+    /**
+     * Stacked bars: each series is drawn from the running cumulative total of the
+     * ones before it, so they stack. Returns the layers bottom-to-top.
+     */
+    addStackedBars(opts: StackedBarOptions): BarLayer[];
     addArea(opts: AreaOptions): AreaLayer;
     addHeatmap(opts: HeatmapOptions): HeatmapLayer;
     addBox(opts: BoxOptions): BoxLayer;
@@ -928,6 +1675,31 @@ declare class Plot {
     addStem(opts: StemOptions): StemLayer;
     addQuiver(opts: QuiverOptions): QuiverLayer;
     addCandlestick(opts: CandlestickOptions): CandlestickLayer;
+    /** An OHLC bar chart (low→high line with open/close ticks). Streams like candlesticks. */
+    addOhlc(opts: OhlcOptions): OhlcLayer;
+    /** Filled polygons (choropleth-capable). Rings are triangulated with earcut. */
+    addPatches(opts: PatchesOptions): PatchesLayer;
+    /** A pie / donut chart. Set `equalAspect: true` on the plot so it stays circular. */
+    addPie(opts: PieOptions): PieLayer;
+    /** An RGBA image / URL drawn over a data-space extent. URLs redraw on load. */
+    addImage(opts: ImageOptions): ImageLayer;
+    /**
+     * A node-link graph. Provide node `x`/`y`, or omit them (with `nodes`, or let the
+     * count be inferred from the edges) to auto-place with a force-directed layout.
+     */
+    addGraph(opts: GraphInput): GraphLayer;
+    /**
+     * Stacked area: each series is filled from the running cumulative total of the
+     * ones before it. Returns the layers bottom-to-top.
+     */
+    addStackedArea(opts: StackedAreaOptions): AreaLayer[];
+    /**
+     * Add a Canvas2D annotation (span / band / box / label) drawn above the data.
+     * Returns a disposer that removes just this annotation.
+     */
+    addAnnotation(a: Annotation): () => void;
+    /** Remove all annotations. */
+    clearAnnotations(): void;
     /** Compute an STFT of `signal` and render it as a heatmap (time × frequency). */
     addHeatmapSpectrogram(signal: ArrayLike<number>, opts?: {
         fftSize?: number;
@@ -945,6 +1717,10 @@ declare class Plot {
     }): BarLayer;
     /** Register an additional named y axis. Series opt in via `addLine({ yAxis })`. */
     addYAxis(id: string, opts?: YAxisOptions): void;
+    /** Whether a y axis with this id exists (the primary is always `"y"`). */
+    hasYAxis(id: string): boolean;
+    /** Remove a secondary y axis. No-op for the primary `"y"` or an unknown id. */
+    removeYAxis(id: string): void;
     removeLayer(layer: Layer): void;
     /** Configure ticks/format/title for the x axis or a y axis (default primary "y"). */
     setAxis(dim: Dim | string, config: Partial<AxisConfig>): void;
@@ -954,6 +1730,18 @@ declare class Plot {
         y?: Range;
         yAxes?: Record<string, Range>;
     }): void;
+    /**
+     * Subscribe to x-domain changes (pan / zoom / home / setView). Fires once per
+     * frame after the domain settles. Returns an unsubscribe function. See {@link linkX}.
+     */
+    onViewChange(cb: (x: Range) => void): () => void;
+    /**
+     * Subscribe to the hover cursor's data-space x (or `null` when it leaves the
+     * plot). Returns an unsubscribe function. Used to share a crosshair across panes.
+     */
+    onCursorMove(cb: (dataX: number | null) => void): () => void;
+    /** Draw a linked crosshair at this data-space x (pushed from another pane), or clear it with `null`. */
+    setLinkedCursor(dataX: number | null): void;
     private setYDomain;
     setMode(mode: InteractionMode): void;
     getMode(): InteractionMode;
@@ -966,7 +1754,15 @@ declare class Plot {
     private resize;
     requestRender(): void;
     private primaryY;
+    /** Fire view/cursor listeners once the frame's x-domain + cursor are settled. */
+    private emitLinks;
     render(): void;
+    /** Named series that can appear in the legend: any layer exposing name + colorCss. */
+    private legendEntries;
+    /** Rebuild and position the legend overlay (or hide it). */
+    private updateLegend;
+    /** Draw all annotations, projected through the scales and clipped to the region. */
+    private renderAnnotations;
     private renderHover;
     private updateTooltip;
     private updateCursor;
@@ -1006,6 +1802,21 @@ declare class Plot {
     private zoomAround;
 }
 
+/**
+ * Link the x-axis (pan / zoom) and hover crosshair of several plots so they move
+ * together — the standard multi-pane financial layout (price on top, volume /
+ * RSI / MACD below, all sharing one time axis). The plots should share the same
+ * x-scale semantics (e.g. all `ordinal-time` over the same bars).
+ *
+ * ```ts
+ * const detach = linkX([pricePlot, volumePlot, rsiPlot]);
+ * // …later: detach();
+ * ```
+ *
+ * @returns a function that unlinks them again.
+ */
+declare function linkX(plots: Plot[]): () => void;
+
 /** The subset of Plot the toolbar drives. Kept minimal to avoid an import cycle. */
 interface ToolbarHost {
     setMode(mode: InteractionMode): void;
@@ -1027,6 +1838,25 @@ declare function createToolbar(container: HTMLElement, host: ToolbarHost, dark:
     destroy: () => void;
 };
 
+/**
+ * A tiny deterministic force-directed layout (Fruchterman–Reingold style). Nodes
+ * seed on a unit circle (no RNG — pure and unit-testable), then relax under
+ * all-pairs repulsion + per-edge attraction + a gentle pull to the center, with
+ * temperature cooling. Returns node positions in roughly a unit box around 0.
+ */
+interface ForceLayoutOptions {
+    /** Relaxation steps. Default 300. */
+    iterations?: number;
+    /** Layout area; the ideal edge length is `sqrt(area / n)`. Default 1. */
+    area?: number;
+    /** Pull toward the origin each step. Default 0.05. */
+    gravity?: number;
+}
+declare function forceLayout(nodeCount: number, edges: ReadonlyArray<readonly [number, number]>, opts?: ForceLayoutOptions): {
+    x: Float64Array;
+    y: Float64Array;
+};
+
 interface PolarOptions {
     theme?: "light" | "dark" | Theme;
     /** Angle unit of input theta values. Default `"rad"`. */
@@ -1054,6 +1884,8 @@ interface PolarLineOptions {
     width?: number;
     /** Connect the last point back to the first. */
     closed?: boolean;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 interface PolarScatterOptions {
     theta: ArrayLike<number>;
@@ -1062,6 +1894,8 @@ interface PolarScatterOptions {
     size?: number;
     /** Optional per-point labels (one per point), shown as the title of the click-pinned info box. */
     labels?: ArrayLike<string>;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 /** A live handle to update a polar series with new (theta, r) data. */
 interface PolarSeries {
@@ -1148,10 +1982,232 @@ 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;
+    /** Series name for the legend (optional). */
+    readonly name?: string;
+    /** A solid CSS color for the legend swatch (solid-colored layers only). */
+    readonly colorCss?: string;
+    bounds3(): Bounds3 | null;
+    /** Colormap + value range for a colorbar, if this layer is colormapped. */
+    colorInfo?(): ColorInfo | null;
+    /**
+     * Data-space points for hover picking (xyz triples), with an optional per-point
+     * tooltip label builder. Null if the layer isn't pickable.
+     */
+    pickData?(): {
+        positions: Float32Array;
+        label?: (i: number) => string;
+    } | null;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
+interface Bar3DOptions {
+    /** Grid x positions (world). */
+    x: ArrayLike<number>;
+    /** Grid z positions (world). */
+    z: ArrayLike<number>;
+    /** Bar heights. */
+    y: ArrayLike<number>;
+    /** Footprint (world units). Defaults to ~0.7× the median grid spacing. */
+    width?: number;
+    color?: string | Color;
+    /** Color bars via a colormap (over `values`, default the heights). */
+    colorBy?: {
+        values?: ArrayLike<number>;
+        colormap?: ColormapName;
+        domain?: Range;
+    };
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/** 3D bars (columns) on an x/z grid, lit like the surface and optionally colormapped. */
+declare class Bar3DLayer 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 width;
+    private b3;
+    private cInfo;
+    private positions;
+    private base;
+    private optWidth?;
+    private colorByOpt?;
+    private usage;
+    private lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: Bar3DOptions);
+    /** Build the per-bar instances (base/height/color) and (re)upload the instance buffer. */
+    private build;
+    /** Stream new bar positions/heights (instances rebuilt). Call `plot.refresh()` after. */
+    setData(x: ArrayLike<number>, z: ArrayLike<number>, y: ArrayLike<number>): void;
+    bounds3(): Bounds3 | null;
+    colorInfo(): ColorInfo | null;
+    pickData(): {
+        positions: Float32Array<ArrayBufferLike>;
+    } | 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>;
+    cols: number;
+    rows: number;
+    /** World footprint. Defaults to unit indices. */
+    extentX?: Range;
+    extentZ?: Range;
+    /** Iso levels: an explicit list, or a count of evenly-spaced levels. Default 10. */
+    levels?: number[] | number;
+    /** Single line color; if omitted, levels are colored by a colormap. */
+    color?: string | Color;
+    colormap?: ColormapName;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/**
+ * 3D contour: iso-height lines of a grid, each drawn at its own level height
+ * (`y = level`) so they stack into a floating topographic map. Marching squares
+ * on the CPU, per-vertex colored by level.
+ */
+declare class Contour3DLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertCount;
+    private b3;
+    private cInfo;
+    private cmapName;
+    private fixed;
+    private levelsOpt?;
+    private cols;
+    private rows;
+    private extentX;
+    private extentZ;
+    private usage;
+    constructor(gl: WebGL2RenderingContext, opts: Contour3DOptions);
+    /** Marching-squares the grid at each iso level and (re)upload the line buffer. */
+    private build;
+    /** Stream a new scalar field (contours recomputed). Call `plot.refresh()` after. */
+    setData(values: ArrayLike<number>, opts?: {
+        cols?: number;
+        rows?: number;
+        extentX?: Range;
+        extentZ?: Range;
+    }): void;
+    bounds3(): Bounds3 | null;
+    colorInfo(): ColorInfo | null;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
+interface IsosurfaceOptions {
+    /** Scalar volume, length `nx*ny*nz`, indexed `x + y*nx + z*nx*ny`. */
+    values: ArrayLike<number>;
+    dims: [number, number, number];
+    /** The iso value to extract the surface at. */
+    isoLevel: number;
+    /** World extent of the volume. Defaults to unit indices. */
+    extent?: {
+        x: Range;
+        y: Range;
+        z: Range;
+    };
+    color?: string | Color;
+    /** Fill opacity 0..1. Default 1. */
+    opacity?: number;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/** A marching-cubes isosurface of a 3D scalar volume, lit and solid-colored. */
+declare class IsosurfaceLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    readonly colorCss: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertCount;
+    private color;
+    private opacity;
+    private b3;
+    private usage;
+    private lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: IsosurfaceOptions);
+    /** Run marching cubes and (re)upload the interleaved pos/normal vertex buffer. */
+    private build;
+    /** Stream a new volume + iso level (marching-cubes mesh recomputed). Call `plot.refresh()` after. */
+    setData(values: ArrayLike<number>, dims: [number, number, number], isoLevel: number, extent?: {
+        x: Range;
+        y: Range;
+        z: Range;
+    }): void;
+    bounds3(): Bounds3 | 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 Line3DOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    z: ArrayLike<number>;
+    color?: string | Color;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/** A 3D polyline / path (`GL_LINE_STRIP`). */
+declare class Line3DLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    readonly colorCss: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private count;
+    private color;
+    private b3;
+    private positions;
+    private usage;
+    constructor(gl: WebGL2RenderingContext, opts: Line3DOptions);
     bounds3(): Bounds3 | null;
+    pickData(): {
+        positions: Float32Array<ArrayBufferLike>;
+    } | null;
+    /** Stream a new path. Call `plot.refresh()` afterwards to re-fit + redraw. */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number>): void;
     draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
     dispose(): void;
 }
@@ -1161,15 +2217,26 @@ interface PointCloudOptions {
     y: ArrayLike<number>;
     z: ArrayLike<number>;
     color?: string | Color;
+    /** Uniform point diameter (px) when `sizes` is omitted. Default 4. */
     size?: number;
+    /** Per-point diameter (px); overrides `size` where > 0. */
+    sizes?: ArrayLike<number>;
     colorBy?: {
         values: ArrayLike<number>;
         colormap?: ColormapName;
         domain?: Range;
     };
+    /** Per-point tooltip text (parallel to x/y/z). */
+    labels?: ArrayLike<string>;
+    /** Series name (legend / colorbar label). */
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 declare class PointCloudLayer implements Layer3D {
     readonly id: string;
+    readonly name?: string;
+    readonly colorCss?: string;
     private gl;
     private program;
     private vao;
@@ -1178,8 +2245,78 @@ declare class PointCloudLayer implements Layer3D {
     private count;
     private size;
     private b3;
+    private cInfo;
+    private positions;
+    private labels?;
+    /** Interleaved pos(3)+color(3)+size(1); positions are streamed in place. */
+    private data;
+    private usage;
     constructor(gl: WebGL2RenderingContext, opts: PointCloudOptions);
+    private updateBounds;
+    /** Stream new point positions (same count keeps colors/sizes). Call `plot.refresh()` after. */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number>): void;
     bounds3(): Bounds3 | null;
+    colorInfo(): ColorInfo | null;
+    pickData(): {
+        positions: Float32Array<ArrayBufferLike>;
+        label: ((i: number) => string) | undefined;
+    } | null;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
+interface Quiver3DOptions {
+    /** Arrow base points. */
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    z: ArrayLike<number>;
+    /** Vector components. */
+    u: ArrayLike<number>;
+    v: ArrayLike<number>;
+    w: ArrayLike<number>;
+    /** Multiply the vectors before drawing. Default 1. */
+    scale?: number;
+    color?: string | Color;
+    /** Color arrows by magnitude via a colormap. */
+    colorBy?: {
+        colormap?: ColormapName;
+        domain?: Range;
+    };
+    /** Arrowhead length as a fraction of the arrow. Default 0.28. */
+    headSize?: number;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/** A 3D vector field: each arrow is a shaft + a 4-wing arrowhead, drawn as lines. */
+declare class Quiver3DLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    readonly colorCss?: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertCount;
+    private b3;
+    private cInfo;
+    private positions;
+    private base;
+    private scale;
+    private headSize;
+    private colorByOpt?;
+    private usage;
+    constructor(gl: WebGL2RenderingContext, opts: Quiver3DOptions);
+    /** Build the arrow line geometry (shaft + 4-wing head) and (re)upload the vertex buffer. */
+    private build;
+    /** Stream a new vector field (arrows rebuilt). Call `plot.refresh()` after. */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number>, u: ArrayLike<number>, v: ArrayLike<number>, w: ArrayLike<number>): void;
+    bounds3(): Bounds3 | null;
+    colorInfo(): ColorInfo | null;
+    pickData(): {
+        positions: Float32Array<ArrayBufferLike>;
+    } | null;
     draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
     dispose(): void;
 }
@@ -1193,9 +2330,16 @@ interface SurfaceOptions {
     extentX?: Range;
     extentZ?: Range;
     colormap?: ColormapName;
+    /** Series name (colorbar label / legend). */
+    name?: string;
+    /** Render the grid as a wireframe (lines) instead of a lit filled surface. */
+    wireframe?: boolean;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
 }
 declare class SurfaceLayer implements Layer3D {
     readonly id: string;
+    readonly name?: string;
     private gl;
     private program;
     private vao;
@@ -1203,16 +2347,90 @@ declare class SurfaceLayer implements Layer3D {
     private uniforms;
     private vertexCount;
     private b3;
+    private cmapName;
+    private vDomain;
+    private wireframe;
+    private cols;
+    private rows;
+    private extentX;
+    private extentZ;
+    private usage;
     private lightDir;
     private ambient;
     constructor(gl: WebGL2RenderingContext, opts: SurfaceOptions);
+    /** Build the mesh (positions/normals/colors or wireframe) and (re)upload the vertex buffer. */
+    private build;
+    /** Stream a new height grid (mesh/normals/wireframe rebuilt). Call `plot.refresh()` after. */
+    setData(values: ArrayLike<number>, opts?: {
+        cols?: number;
+        rows?: number;
+        extentX?: Range;
+        extentZ?: Range;
+    }): void;
     bounds3(): Bounds3;
+    colorInfo(): ColorInfo;
     /** 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 VolumeOptions {
+    /** Scalar volume, length `nx*ny*nz`, indexed `x + y*nx + z*nx*ny`. */
+    values: ArrayLike<number>;
+    dims: [number, number, number];
+    /** World extent of the volume. Defaults to unit indices. */
+    extent?: {
+        x: Range;
+        y: Range;
+        z: Range;
+    };
+    colormap?: ColormapName;
+    /** Value range mapped to the colormap + opacity. Defaults to the data min/max. */
+    domain?: Range;
+    /** Overall opacity multiplier. Default 1. */
+    density?: number;
+    name?: string;
+    /** Buffer-usage hint; set `"dynamic"` when streaming via setData. Default `"static"`. */
+    renderType?: RenderType;
+}
+/**
+ * Direct volume rendering: GPU raymarching through a 3D texture with front-to-back
+ * alpha compositing and a colormap transfer function. Draws the volume's bounding
+ * box (back faces) and integrates each ray across the box interior.
+ */
+declare class VolumeLayer implements Layer3D {
+    readonly id: string;
+    readonly name?: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private tex;
+    private lut;
+    private uniforms;
+    private b3;
+    private ext;
+    private density;
+    private cmapName;
+    private vDomain;
+    private dims;
+    private domainOpt?;
+    private usage;
+    private camLocal;
+    constructor(gl: WebGL2RenderingContext, opts: VolumeOptions);
+    /** Normalize the scalar field and (re)upload it into the R8 3D texture. */
+    private uploadVolume;
+    /** Stream a new scalar volume (same dims); re-uploads the 3D texture. Call `plot.refresh()` after. */
+    setData(values: ArrayLike<number>): void;
+    bounds3(): Bounds3;
+    colorInfo(): ColorInfo;
+    /** Set the camera position in world space; converted to the volume's [0,1] local space. */
+    setCamera(worldEye: [number, number, number]): void;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
 interface Plot3DOptions {
     background?: [number, number, number, number];
     azimuth?: number;
@@ -1226,6 +2444,22 @@ interface Plot3DOptions {
     };
     /** Render a small on-canvas panel with light-angle + ambient sliders. */
     lightControls?: boolean;
+    /** Plot title, drawn top-center. */
+    title?: string;
+    /** Show a legend of named solid-colored layers. Default false. */
+    legend?: boolean;
+    /** Show a colorbar for the first colormapped layer. Default true when one exists. */
+    colorbar?: boolean | {
+        label?: string;
+    };
+    /** Hover tooltip on the nearest pickable point. Default true. */
+    hover?: boolean;
+    /** Show a reset-view (home) button. Default true. */
+    resetButton?: boolean;
+    /** Draw grid lines on the back walls of the cube. Default true. */
+    gridPlanes?: boolean;
+    /** Auto-orbit the camera: `true` for a default speed, or radians/frame. Default off. */
+    autoRotate?: boolean | number;
 }
 /** A 3D scatter/surface plot with an orbit camera, axis ticks, and lighting. */
 declare class Plot3D {
@@ -1253,14 +2487,51 @@ declare class Plot3D {
     private tickBuf;
     private tickCount;
     private labels;
+    /** Tick positions in cube space [-1,1], per axis, for the grid planes. */
+    private tickCube;
+    private gridPlanes;
+    private gridVao;
+    private gridBuf;
+    /** Normalize params (world→cube: `cube = s*world + t`), for the volume camera. */
+    private norm;
+    /** Auto-orbit speed (rad/frame); 0 = off. Paused while the pointer is down. */
+    private autoRotateSpeed;
+    private rotating;
+    private interacting;
     private lightAz;
     private lightEl;
     private ambient;
     private controlsEl;
+    private title?;
+    private showLegend;
+    private colorbarOpt;
+    private legendDiv;
+    private colorbarDiv;
+    private tooltip;
+    private resetBtn;
+    private hoverEnabled;
+    /** Screen position (device px) of the picked point, for the highlight ring. */
+    private hoverHit;
+    /** Initial camera, restored by {@link resetView}. */
+    private initialAz;
+    private initialEl;
+    private initialDist;
     constructor(container: HTMLElement, options?: Plot3DOptions);
     private bindLineVao;
     addSurface(opts: SurfaceOptions): SurfaceLayer;
     addPointCloud(opts: PointCloudOptions): PointCloudLayer;
+    /** A 3D polyline / path. */
+    addLine3D(opts: Line3DOptions): Line3DLayer;
+    /** 3D bars (columns) on an x/z grid, lit and optionally colormapped. */
+    addBar3D(opts: Bar3DOptions): Bar3DLayer;
+    /** 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. */
+    addContour3D(opts: Contour3DOptions): Contour3DLayer;
+    /** A marching-cubes isosurface of a 3D scalar volume (lit, solid-colored). */
+    addIsosurface(opts: IsosurfaceOptions): IsosurfaceLayer;
+    /** Direct volume rendering (GPU raymarch) of a 3D scalar field. */
+    addVolume(opts: VolumeOptions): VolumeLayer;
     /** Update the light direction (azimuth/elevation, radians) and ambient (0..1). */
     setLight(params: {
         azimuth?: number;
@@ -1268,6 +2539,18 @@ declare class Plot3D {
         ambient?: number;
     }): void;
     private lightDir;
+    /** Auto-orbit the camera. `true` = default speed, number = radians/frame, `false`/0 stops. */
+    setAutoRotate(speed: number | boolean): void;
+    /** Restore the initial camera orientation and zoom. */
+    resetView(): void;
+    /** Nearest pickable point to the cursor. Screen coords are device px. */
+    private pick;
+    /** Show/hide the hover tooltip + highlight ring for the point under the cursor. */
+    private updateHover;
+    /** Remove a layer, re-fit, and redraw. */
+    removeLayer(layer: Layer3D): void;
+    /** Re-fit the axes to the data and redraw — call after a layer's `setData(...)`. */
+    refresh(): void;
     destroy(): void;
     private recompute;
     /** Build tick-mark line geometry + tick/title labels from the data bounds. */
@@ -1275,12 +2558,41 @@ declare class Plot3D {
     private resize;
     requestRender(): void;
     private viewProj;
+    /** Build + draw grid lines on the 3 back walls (cube space) for the current eye. */
+    private drawGridPlanes;
     render(): void;
+    /** DOM legend of named, solid-colored layers. */
+    private updateLegend;
+    /** DOM colorbar for the first colormapped layer (gradient + value range). */
+    private updateColorbar;
     private drawLabels;
     private attachControls;
     private buildControls;
 }
 
+/**
+ * Marching cubes: extract a triangle-mesh isosurface from a 3D scalar volume.
+ * Pure and unit-tested. Uses the canonical Bourke/Bloyd edge + triangle tables.
+ *
+ * The volume is indexed `x + y*nx + z*nx*ny`. A corner is "inside" when its value
+ * is below `isoLevel`. Vertex positions are linearly interpolated along the crossed
+ * cube edges; normals come from the (central-difference) volume gradient so the
+ * surface shades smoothly.
+ */
+
+/**
+ * Extract the isosurface of `values` (dims `nx*ny*nz`, index `x + y*nx + z*nx*ny`)
+ * at `isoLevel`. Returns a triangle soup of world-space positions + smooth normals.
+ */
+declare function marchingCubes(values: ArrayLike<number>, dims: [number, number, number], isoLevel: number, extent?: {
+    x: Range;
+    y: Range;
+    z: Range;
+}): {
+    positions: Float32Array;
+    normals: Float32Array;
+};
+
 /**
  * Owns the tick configuration for one axis and resolves the final tick list
  * against a scale. Modes: auto (delegates to the scale), custom (array), or
@@ -1367,14 +2679,259 @@ interface Density {
  */
 declare function kde(values: ArrayLike<number>, lo: number, hi: number, points?: number, bandwidth?: number): Density;
 
+/** 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. */
 declare function createProgram(gl: WebGL2RenderingContext, vert: string, frag: string): WebGLProgram;
 /** Cache uniform locations for a program by name. */
 declare function uniformLocations(gl: WebGL2RenderingContext, program: WebGLProgram, names: string[]): Record<string, WebGLUniformLocation | null>;
 
+/**
+ * Ear-clipping polygon triangulation with hole support.
+ *
+ * A faithful reimplementation of the well-known ear-clipping algorithm (as
+ * popularized by mapbox/earcut, ISC). Input is a flat `[x0,y0,x1,y1,…]`
+ * coordinate array with optional hole start-indices; output is a flat list of
+ * triangle vertex indices into that array. Pure and unit-tested.
+ *
+ * For rings above {@link Z_ORDER_THRESHOLD} vertices it switches on the z-order
+ * (Morton) curve acceleration: each node gets a 32-bit Morton code, the nodes
+ * are merge-sorted into a secondary z-linked list, and the "is this an ear?"
+ * test only scans candidate points whose Morton code falls in the ear's
+ * bounding-box range — turning the inner loop from O(n) into ~O(1) amortized,
+ * so the whole triangulation goes from O(n²) to ~O(n log n). Small rings (most
+ * vector-tile polygons) skip the hashing entirely to avoid its setup cost.
+ */
+/**
+ * Triangulate a polygon. `holeIndices[k]` is the vertex index (not coordinate
+ * index) where hole `k` begins. Returns triangle vertex indices in groups of 3.
+ */
+declare function earcut(data: number[], holeIndices?: number[], dim?: number): number[];
+
+/** Simple moving average over `period` samples. */
+declare function sma(values: ArrayLike<number>, period: number): Float64Array;
+/** Weighted moving average (linear weights 1..period, newest heaviest). */
+declare function wma(values: ArrayLike<number>, period: number): Float64Array;
+/**
+ * Exponential moving average, α = 2/(period+1). Seeded with the SMA of the first
+ * `period` samples at index `period-1` (the standard convention).
+ */
+declare function ema(values: ArrayLike<number>, period: number): Float64Array;
+/** Rolling population standard deviation over `period` samples. */
+declare function rollingStd(values: ArrayLike<number>, period: number): Float64Array;
+interface BollingerBands {
+    middle: Float64Array;
+    upper: Float64Array;
+    lower: Float64Array;
+}
+/** Bollinger Bands: SMA(period) ± `k`·rollingStd(period). Defaults 20, 2. */
+declare function bollinger(close: ArrayLike<number>, period?: number, k?: number): BollingerBands;
+/** Wilder's RSI over `period` (default 14). Values in 0..100; warm-up is NaN. */
+declare function rsi(close: ArrayLike<number>, period?: number): Float64Array;
+interface Macd {
+    macd: Float64Array;
+    signal: Float64Array;
+    histogram: Float64Array;
+}
+/** MACD: EMA(fast) − EMA(slow), its EMA(signal) line, and the histogram. Defaults 12/26/9. */
+declare function macd(close: ArrayLike<number>, fast?: number, slow?: number, signalPeriod?: number): Macd;
+/**
+ * Volume-weighted average price, cumulative from the first sample: running
+ * Σ(typical·volume) / Σ(volume), where typical = (high+low+close)/3.
+ */
+declare function vwap(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>, volume: ArrayLike<number>): Float64Array;
+/** True range per bar: max(H−L, |H−prevC|, |L−prevC|). First bar is H−L. */
+declare function trueRange(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>): Float64Array;
+/** Wilder's Average True Range over `period` (default 14). */
+declare function atr(high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>, period?: number): Float64Array;
+/** Index of the first non-NaN value (−1 if all NaN). Handy for trimming warm-up. */
+declare function firstFinite(values: ArrayLike<number>): number;
+
+/**
+ * Chart-type transforms: turn raw OHLC(V) into the geometry a specialist finance
+ * chart needs. Each returns plain arrays you render with existing layers
+ * (candlestick, bar, area, scatter) — see the `Plot.add*` helpers that wrap them.
+ */
+interface Ohlc {
+    open: ArrayLike<number>;
+    high: ArrayLike<number>;
+    low: ArrayLike<number>;
+    close: ArrayLike<number>;
+}
+interface OhlcArrays {
+    open: Float64Array;
+    high: Float64Array;
+    low: Float64Array;
+    close: Float64Array;
+}
+/**
+ * Heikin-Ashi candles — a smoothed OHLC that filters noise and makes trends
+ * obvious. Output has the same length; feed it to a candlestick layer.
+ *
+ *   haClose = (o+h+l+c)/4
+ *   haOpen  = (prevHaOpen + prevHaClose)/2   (seed: (o₀+c₀)/2)
+ *   haHigh  = max(h, haOpen, haClose)
+ *   haLow   = min(l, haOpen, haClose)
+ */
+declare function heikinAshi(d: Ohlc): OhlcArrays;
+/** One brick / box for Renko & Line-break (each renders as a wickless candle body). */
+interface Brick {
+    /** Sequential column index (0..n-1); bricks are evenly spaced, time is discarded. */
+    x: number;
+    open: number;
+    close: number;
+    /** `true` when close > open (up brick). */
+    up: boolean;
+}
+/**
+ * Renko bricks from a close series. A new brick is emitted each time price moves
+ * a full `brickSize` from the last brick's close (multiple bricks if it jumps
+ * several sizes). Time is discarded — bricks are placed at successive indices.
+ */
+declare function renko(close: ArrayLike<number>, brickSize: number): Brick[];
+/**
+ * Three-line-break (generalised to `lines`): a new up brick when close exceeds
+ * the highest close of the last `lines` bricks, a down brick when it breaks the
+ * lowest; otherwise nothing. Bricks are placed at successive indices.
+ */
+declare function lineBreak(close: ArrayLike<number>, lines?: number): Brick[];
+/** One P&F column: a run of X's (rising) or O's (falling) spanning `from`→`to`. */
+interface PfColumn {
+    col: number;
+    kind: "X" | "O";
+    from: number;
+    to: number;
+    /** Box centers filled in this column (for plotting the X/O glyphs). */
+    boxes: number[];
+}
+/**
+ * Point & Figure columns. Price is quantised to `boxSize`; a column of X's grows
+ * while price rises, O's while it falls, and the column flips only after a
+ * `reversal`-box move against it. Time is discarded.
+ */
+declare function pointAndFigure(high: ArrayLike<number>, low: ArrayLike<number>, boxSize: number, reversal?: number): PfColumn[];
+interface VolumeProfile {
+    /** Bin center price for each level (length = bins). */
+    levels: Float64Array;
+    /** Total volume traded in each price bin. */
+    volume: Float64Array;
+    binSize: number;
+    priceMin: number;
+    priceMax: number;
+    /** Bin index of the highest-volume level (the Point of Control). */
+    pocIndex: number;
+}
+/**
+ * Volume profile — a histogram of traded volume by price level. Plot it as
+ * horizontal bars (`orientation:"h"`) with `levels` on the y axis.
+ */
+declare function volumeProfile(price: ArrayLike<number>, volume: ArrayLike<number>, bins?: number): VolumeProfile;
+interface DepthCurves {
+    /** Bid side: prices ascending toward mid, cumulative volume (best bid = largest cum). */
+    bidPrice: Float64Array;
+    bidCum: Float64Array;
+    /** Ask side: prices ascending away from mid, cumulative volume. */
+    askPrice: Float64Array;
+    askCum: Float64Array;
+}
+/**
+ * Order-book depth curves. `bids`/`asks` are `[price, size]` pairs (any order);
+ * 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;
+
+/**
+ * Convenience builders for specialist finance charts. Each takes a {@link Plot}
+ * and composes existing layers from a transform/indicator — mirroring the
+ * `addMap(plot, …)` free-function style. Import from `@photonviz/core`.
+ */
+
+/** Raw OHLC input shared by the candle-style helpers. */
+interface OhlcInput {
+    x: ArrayLike<number>;
+    open: ArrayLike<number>;
+    high: ArrayLike<number>;
+    low: ArrayLike<number>;
+    close: ArrayLike<number>;
+}
+interface HeikinAshiOptions extends Omit<CandlestickOptions, "open" | "high" | "low" | "close"> {
+    open: ArrayLike<number>;
+    high: ArrayLike<number>;
+    low: ArrayLike<number>;
+    close: ArrayLike<number>;
+}
+/** Heikin-Ashi candles: smooth the OHLC, then draw it as a candlestick layer. */
+declare function addHeikinAshi(plot: Plot, opts: HeikinAshiOptions): CandlestickLayer;
+interface RenkoOptions {
+    close: ArrayLike<number>;
+    /** Fixed brick height in price units. */
+    brickSize: number;
+    upColor?: string | Color;
+    downColor?: string | Color;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+/**
+ * Renko chart — bricks at successive integer indices (time discarded). Rendered
+ * as wickless candles, so pair it with an `ordinal-time`/linear x axis.
+ */
+declare function addRenko(plot: Plot, opts: RenkoOptions): CandlestickLayer;
+interface VolumeProfileOptions {
+    /** Price per sample (typically close). */
+    price: ArrayLike<number>;
+    volume: ArrayLike<number>;
+    /** Number of price bins. Default 24. */
+    bins?: number;
+    color?: string | Color;
+    /** Highlight the Point-of-Control bin with this color. */
+    pocColor?: string | Color;
+    name?: string;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+/** Volume-by-price histogram as horizontal bars (price on the y axis). */
+declare function addVolumeProfile(plot: Plot, opts: VolumeProfileOptions): BarLayer;
+interface BollingerOptions {
+    x: ArrayLike<number>;
+    close: ArrayLike<number>;
+    period?: number;
+    k?: number;
+    /** Line color for the bands + middle. Default light blue. */
+    color?: string | Color;
+    /** Fill color between the bands (omit to skip the fill). */
+    bandColor?: string | Color;
+    width?: number;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+/** Bollinger Bands: a shaded band between upper/lower plus the three lines. */
+interface BollingerHandle {
+    band?: AreaLayer;
+    upper: LineLayer;
+    middle: LineLayer;
+    lower: LineLayer;
+}
+declare function addBollinger(plot: Plot, opts: BollingerOptions): BollingerHandle;
+interface DepthOptions {
+    /** `[price, size]` levels (any order). */
+    bids: ArrayLike<readonly [number, number]>;
+    asks: ArrayLike<readonly [number, number]>;
+    bidColor?: string | Color;
+    askColor?: string | Color;
+    yAxis?: string;
+    renderType?: RenderType;
+}
+/** Order-book depth: cumulative bid/ask volume as two filled areas. */
+interface DepthHandle {
+    bid: AreaLayer;
+    ask: AreaLayer;
+}
+declare function addDepth(plot: Plot, opts: DepthOptions): DepthHandle;
+
 /** Parse a CSS hex/rgb color string into normalized RGBA (0..1). */
 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 { AreaLayer, type AreaOptions, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, BarLayer, type BarOptions, type Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, CandlestickLayer, type CandlestickOptions, type Color, type ColormapName, ContourLayer, type ContourOptions, type Density, type Dim, type DrawState, ErrorBarLayer, type ErrorBarOptions, HeatmapLayer, type HeatmapOptions, HexbinLayer, type HexbinOptions, type Histogram, type HoverReadoutRow, type InteractionMode, type Layer, type Layer3D, type Layout, LineLayer, type LineOptions, LinearScale, LogScale, type PickMode, Plot, Plot3D, type Plot3DOptions, type PlotOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, QuiverLayer, type QuiverOptions, type RGB, type Range, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type Spectrogram, StemLayer, type StemOptions, SurfaceLayer, type SurfaceOptions, TRANSFORM_GLSL, TRANSFORM_UNIFORMS, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type YAxisOptions, autoTicks, boxStats, colormap, createProgram, createToolbar, darkTheme, defaultFormat, fft, histogram, kde, lightTheme, makeScale, parseColor, quantileSorted, resolveTicks, setTransformUniforms, spectrogram, toColorCss, uniformLocations, withMinorTicks };
+export { type Annotation, AreaLayer, type AreaOptions, type AreaSeries, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, Bar3DLayer, type Bar3DOptions, BarLayer, type BarOptions, type BarSeries, type BollingerBands, type BollingerHandle, type BollingerOptions, type Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, type Brick, type Candle, type CandlestickData, CandlestickLayer, type CandlestickOptions, CategoricalScale, type Color, type ColorInfo, type ColormapName, Contour3DLayer, type Contour3DOptions, ContourLayer, type ContourOptions, type Density, type DepthCurves, type DepthHandle, type DepthOptions, type Dim, type DrawState, ErrorBarLayer, type ErrorBarOptions, type ForceLayoutOptions, type GraphInput, GraphLayer, type GraphOptions, type GroupedBarOptions, HeatmapLayer, type HeatmapOptions, type HeikinAshiOptions, HexbinLayer, type HexbinOptions, type Histogram, type HoverReadoutRow, 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, type Macd, type MarkerShape, type Ohlc, type OhlcArrays, type OhlcInput, OhlcLayer, type OhlcOptions, OrdinalTimeScale, type Patch, PatchesLayer, type PatchesOptions, 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, Quiver3DLayer, type Quiver3DOptions, QuiverLayer, type QuiverOptions, type RGB, type Range, type RenderType, type RenkoOptions, type ResolvedAxisStyle, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type Spectrogram, type StackedAreaOptions, type StackedBarOptions, StemLayer, type StemOptions, SurfaceLayer, type SurfaceOptions, TRANSFORM_GLSL, TRANSFORM_UNIFORMS, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, VolumeLayer, type VolumeOptions, type VolumeProfile, type VolumeProfileOptions, type YAxisOptions, addBollinger, addDepth, addHeikinAshi, addRenko, addVolumeProfile, atr, autoTicks, bollinger, boxStats, bufferUsage, colormap, colormapLUT, createProgram, createToolbar, darkTheme, defaultFormat, depth, earcut, ema, fft, firstFinite, forceLayout, heikinAshi, histogram, kde, lightTheme, lineBreak, linkX, macd, makeScale, marchingCubes, parseColor, pointAndFigure, quantileSorted, renko, resolveAxisStyle, resolveTicks, rollingStd, rsi, setTransformUniforms, sma, spectrogram, toColorCss, trueRange, uniformLocations, volumeProfile, vwap, withMinorTicks, wma };