@photonviz/core 0.2.1 → 0.3.0

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";
 /**
@@ -136,6 +172,12 @@ 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;
     name?: string;
     yAxis?: string;
@@ -154,6 +196,7 @@ declare class BarLayer implements Layer {
     private color;
     private barWidth;
     private offset;
+    private orientation;
     private xRef;
     private yRef;
     private xBounds;
@@ -260,7 +303,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 {
@@ -362,6 +411,50 @@ declare class ErrorBarLayer implements Layer {
     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;
+    name?: string;
+    yAxis?: string;
+}
+/** 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;
+    constructor(gl: WebGL2RenderingContext, opts: GraphOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
 interface HeatmapOptions {
     /** Row-major grid values, length `cols * rows` (row 0 at the bottom). */
     values: ArrayLike<number>;
@@ -433,6 +526,59 @@ 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;
+    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);
+    private upload;
+    bounds(): {
+        x: Range;
+        y: Range;
+    };
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
 /**
  * Shared hover-picking used by point/series layers (line, scatter, stem).
  *
@@ -540,6 +686,106 @@ 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;
+    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;
+    constructor(gl: WebGL2RenderingContext, opts: PatchesOptions);
+    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;
+    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;
+    constructor(gl: WebGL2RenderingContext, opts: PieOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
 interface QuiverOptions {
     /** Arrow anchor positions (data space). */
     x: ArrayLike<number>;
@@ -594,12 +840,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;
     /**
@@ -628,6 +878,7 @@ declare class ScatterLayer implements Layer {
     private uniforms;
     private count;
     private size;
+    private marker;
     private color;
     private useVertexColor;
     private labels?;
@@ -748,8 +999,26 @@ 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;
+}
+type ScaleType = "linear" | "log" | "time" | "categorical";
+declare function makeScale(type: ScaleType, domain?: Range, factors?: string[]): Scale;
 
 /** Pixel geometry of the plot, in CSS pixels. The plot region excludes margins. */
 interface Layout {
@@ -771,20 +1040,158 @@ 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[];
+}
+/** 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[];
     /** 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 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;
+}
+/** 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;
@@ -800,6 +1207,14 @@ interface PlotOptions {
         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;
@@ -892,6 +1307,12 @@ declare class Plot {
     /** 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 +1340,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 +1359,29 @@ declare class Plot {
     addStem(opts: StemOptions): StemLayer;
     addQuiver(opts: QuiverOptions): QuiverLayer;
     addCandlestick(opts: CandlestickOptions): CandlestickLayer;
+    /** 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;
@@ -967,6 +1421,12 @@ declare class Plot {
     requestRender(): void;
     private primaryY;
     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;
@@ -1027,6 +1487,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"`. */
@@ -1148,10 +1627,188 @@ 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;
+}
+/** 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 uniforms;
+    private count;
+    private width;
+    private b3;
+    private cInfo;
+    private positions;
+    private lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: Bar3DOptions);
     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;
+}
+/**
+ * 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;
+    constructor(gl: WebGL2RenderingContext, opts: Contour3DOptions);
+    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;
+}
+/** 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 lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: IsosurfaceOptions);
+    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;
+}
+/** 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;
+    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 +1818,24 @@ 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;
 }
 declare class PointCloudLayer implements Layer3D {
     readonly id: string;
+    readonly name?: string;
+    readonly colorCss?: string;
     private gl;
     private program;
     private vao;
@@ -1178,8 +1844,66 @@ 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;
     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;
+}
+/** 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;
+    constructor(gl: WebGL2RenderingContext, opts: Quiver3DOptions);
+    bounds3(): Bounds3 | null;
+    colorInfo(): ColorInfo | null;
+    pickData(): {
+        positions: Float32Array<ArrayBufferLike>;
+    } | null;
     draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
     dispose(): void;
 }
@@ -1193,9 +1917,14 @@ 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;
 }
 declare class SurfaceLayer implements Layer3D {
     readonly id: string;
+    readonly name?: string;
     private gl;
     private program;
     private vao;
@@ -1203,16 +1932,67 @@ declare class SurfaceLayer implements Layer3D {
     private uniforms;
     private vertexCount;
     private b3;
+    private cmapName;
+    private vDomain;
+    private wireframe;
     private lightDir;
     private ambient;
     constructor(gl: WebGL2RenderingContext, opts: SurfaceOptions);
     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;
+}
+/**
+ * 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 camLocal;
+    constructor(gl: WebGL2RenderingContext, opts: VolumeOptions);
+    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 +2006,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 +2049,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 +2101,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 +2120,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
@@ -1372,9 +2246,31 @@ declare function createProgram(gl: WebGL2RenderingContext, vert: string, frag: s
 /** 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[];
+
 /** 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 Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, CandlestickLayer, type CandlestickOptions, CategoricalScale, type Color, type ColorInfo, type ColormapName, Contour3DLayer, type Contour3DOptions, ContourLayer, type ContourOptions, type Density, type Dim, type DrawState, ErrorBarLayer, type ErrorBarOptions, type ForceLayoutOptions, type GraphInput, GraphLayer, type GraphOptions, type GroupedBarOptions, HeatmapLayer, type HeatmapOptions, 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 MarkerShape, type Patch, PatchesLayer, type PatchesOptions, 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 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 YAxisOptions, autoTicks, boxStats, colormap, colormapLUT, createProgram, createToolbar, darkTheme, defaultFormat, earcut, fft, forceLayout, histogram, kde, lightTheme, makeScale, marchingCubes, parseColor, quantileSorted, resolveAxisStyle, resolveTicks, setTransformUniforms, spectrogram, toColorCss, uniformLocations, withMinorTicks };