@photonviz/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,961 @@
+/** A single axis tick. Only `value` is required; everything else has sensible defaults. */
+interface Tick {
+    /** Position in data space. */
+    value: number;
+    /** Text shown next to the tick. If omitted, the axis `format` fn is used. */
+    label?: string;
+    /** Minor ticks are short, unlabeled, and (by default) draw no grid line. */
+    minor?: boolean;
+    /** Whether this tick draws a grid line. Defaults to `true` for major, `false` for minor. */
+    grid?: boolean;
+}
+/** How a user may specify ticks for an axis. */
+type TicksSpec = number[] | Tick[] | ((min: number, max: number) => Array<number | Tick>);
+interface AxisConfig {
+    /** Ticks: an array of positions, an array of `Tick` objects, or a generator fn. */
+    ticks?: TicksSpec;
+    /** Extra ticks layered on top of the auto ticks (only used when `ticks` is not set). */
+    addTicks?: Array<number | Tick>;
+    /** Formats a numeric tick value into a label when the tick has no explicit `label`. */
+    format?: (value: number) => string;
+    /** Auto minor ticks: `true` for a default count, or a number of subdivisions per major interval. */
+    minorTicks?: boolean | number;
+    /** Axis title, drawn along the axis. */
+    title?: string;
+}
+type Dim = "x" | "y";
+/**
+ * Pointer interaction modes:
+ *  - `pan`    drag pans the view, wheel zooms both axes
+ *  - `box`    drag selects a rectangle and zooms into it (both axes)
+ *  - `box-x`  drag selects an x-range only (full height band) — X-only zoom
+ *  - `box-y`  drag selects a y-range only (full width band) — Y-only zoom
+ */
+type InteractionMode = "pan" | "box" | "box-x" | "box-y";
+type Range = readonly [number, number];
+interface Bounds {
+    x: Range;
+    y: Range;
+}
+/** RGBA in 0..1. */
+type Color = readonly [number, number, number, number];
+
+/** Per-axis view state handed to a layer each frame. `lo`/`hi` are raw data-space. */
+interface AxisFrame {
+    lo: number;
+    hi: number;
+    log: boolean;
+}
+
+/** State handed to a layer each frame so it can transform data to clip space. */
+interface DrawState {
+    gl: WebGL2RenderingContext;
+    x: AxisFrame;
+    y: AxisFrame;
+    /** Plot-region size in device pixels. */
+    pixelWidth: number;
+    pixelHeight: number;
+    /** devicePixelRatio, for converting pixel-space widths/sizes. */
+    dpr: number;
+}
+/** A drawable data series backed by GPU buffers. */
+interface Layer {
+    readonly id: string;
+    /** The y axis this layer is bound to. */
+    readonly yAxis: string;
+    /** Data-space bounds of this layer, for autoscaling. `null` if empty. */
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface AreaOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    /** Lower edge(s). Number or per-point array — pass cumulative to stack. */
+    base?: number | ArrayLike<number>;
+    color?: string | Color;
+    name?: string;
+    yAxis?: string;
+}
+declare class AreaLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertexCount;
+    private color;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    constructor(gl: WebGL2RenderingContext, opts: AreaOptions);
+    /** Replace the area data and re-upload (for streaming). */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, base?: number | ArrayLike<number>): void;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface BarOptions {
+    /** Bar center positions (data space). */
+    x: ArrayLike<number>;
+    /** Bar top values. */
+    y: ArrayLike<number>;
+    /** Baseline(s). Number or per-bar array — pass cumulative values to stack. */
+    base?: number | ArrayLike<number>;
+    /** Bar width in data units. Defaults to 80% of the median spacing. */
+    width?: number;
+    /** Shift bars by this many data units (use for grouped bars). */
+    offset?: number;
+    color?: string | Color;
+    name?: string;
+    yAxis?: string;
+}
+declare class BarLayer 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 count;
+    private color;
+    private barWidth;
+    private offset;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    constructor(gl: WebGL2RenderingContext, opts: BarOptions);
+    private buildRects;
+    /** Replace bar values and re-upload (for streaming). */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>, base?: number | ArrayLike<number>): void;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface BoxGroup {
+    /** X-axis center for this group. */
+    position: number;
+    values: ArrayLike<number>;
+    color?: string | Color;
+    label?: string;
+}
+interface BoxOptions {
+    groups: BoxGroup[];
+    /** Group width in data units. */
+    width?: number;
+    /** Draw the Tukey box + whiskers (default true). */
+    box?: boolean;
+    /** Draw a violin (KDE) shape behind/instead of the box (default false). */
+    violin?: boolean;
+    yAxis?: string;
+}
+declare class BoxLayer implements Layer {
+    readonly id: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    private triCount;
+    private lineStart;
+    private lineCount;
+    private pointStart;
+    private pointCount;
+    constructor(gl: WebGL2RenderingContext, opts: BoxOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+type RGB = [number, number, number];
+type ColormapName = "viridis" | "plasma" | "coolwarm" | "grayscale";
+/** Returns a `(t in 0..1) => RGB` sampler for the named colormap. */
+declare function colormap(name?: ColormapName): (t: number) => RGB;
+
+interface ContourOptions {
+    /** Row-major grid values, length `cols * rows` (row 0 at the bottom). */
+    values: ArrayLike<number>;
+    cols: number;
+    rows: number;
+    extent: {
+        x: Range;
+        y: Range;
+    };
+    /** Iso levels: an explicit list, or a count of evenly-spaced levels. */
+    levels?: number[] | number;
+    /** Single line color; if omitted, levels are colored by a colormap. */
+    color?: string | Color;
+    colormap?: ColormapName;
+    yAxis?: string;
+}
+declare class ContourLayer implements Layer {
+    readonly id: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertexCount;
+    private xRef;
+    private yRef;
+    private ext;
+    constructor(gl: WebGL2RenderingContext, opts: ContourOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    };
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface HeatmapOptions {
+    /** Row-major grid values, length `cols * rows` (row 0 at the bottom). */
+    values: ArrayLike<number>;
+    cols: number;
+    rows: number;
+    /** Data-space extent the grid spans. */
+    extent: {
+        x: Range;
+        y: Range;
+    };
+    colormap?: ColormapName;
+    /** Value range mapped to the colormap. Defaults to the data min/max. */
+    domain?: Range;
+    /** Bilinear filtering (default true) vs. hard cells. */
+    smooth?: boolean;
+    yAxis?: string;
+}
+declare class HeatmapLayer implements Layer {
+    readonly id: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private texture;
+    private uniforms;
+    private xRef;
+    private yRef;
+    private ext;
+    constructor(gl: WebGL2RenderingContext, opts: HeatmapOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    };
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface HexbinOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    /** Hex radius in data units. Defaults to ~1/30 of the x-extent. */
+    radius?: number;
+    colormap?: ColormapName;
+    /** Count range mapped to the colormap. Defaults to [1, maxCount]. */
+    domain?: Range;
+    yAxis?: string;
+}
+declare class HexbinLayer implements Layer {
+    readonly id: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private vao;
+    private buffers;
+    private uniforms;
+    private radius;
+    private cellCount;
+    private xRef;
+    private yRef;
+    private xBounds;
+    private yBounds;
+    constructor(gl: WebGL2RenderingContext, opts: HexbinOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface LineOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    color?: string | Color;
+    /** Line width in CSS pixels (real thickness via GPU triangle expansion). */
+    width?: number;
+    name?: string;
+    yAxis?: string;
+    step?: "before" | "after" | "center";
+    /** Round joins/caps (default) or square/butt ends. */
+    join?: "round" | "butt";
+    /**
+     * Min/max decimate very large series to ~2 points per pixel column when
+     * zoomed out (preserves peaks). Requires monotonic x; auto-detected. Default true.
+     */
+    decimate?: boolean;
+}
+declare class LineLayer implements Layer {
+    readonly id: string;
+    readonly name: string;
+    readonly colorCss: string;
+    readonly yAxis: string;
+    private gl;
+    private program;
+    private fullVao;
+    private decVao;
+    private cornerBuf;
+    private posBuf;
+    private decBuf;
+    private uniforms;
+    private count;
+    private color;
+    private width;
+    private round;
+    private decimateOn;
+    private monotonic;
+    private step?;
+    private xRef;
+    private yRef;
+    private xs;
+    private ys;
+    private xBounds;
+    private yBounds;
+    private decKey;
+    private decSegments;
+    constructor(gl: WebGL2RenderingContext, opts: LineOptions);
+    private configureVao;
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    nearestByX(x: number): {
+        x: number;
+        y: number;
+        index: number;
+    } | null;
+    /** Replace the series data and re-upload the GPU buffer (for streaming). */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
+    /**
+     * Rebuild the min/max-decimated buffer for the visible x-window if it changed.
+     * Returns the segment count to draw from `decVao`, or null to draw everything.
+     */
+    private decimate;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+interface ScatterOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    color?: string | Color;
+    /** Marker diameter in CSS pixels. */
+    size?: number;
+    name?: string;
+    yAxis?: string;
+    /** Color each point by a value through a colormap. */
+    colorBy?: {
+        values: ArrayLike<number>;
+        colormap?: ColormapName;
+        /** Value range mapped to [0,1]. Defaults to the data min/max. */
+        domain?: Range;
+    };
+}
+declare class ScatterLayer 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 count;
+    private size;
+    private color;
+    private useVertexColor;
+    private xRef;
+    private yRef;
+    private xs;
+    private ys;
+    private xBounds;
+    private yBounds;
+    constructor(gl: WebGL2RenderingContext, opts: ScatterOptions);
+    bounds(): {
+        x: Range;
+        y: Range;
+    } | null;
+    nearestByX(x: number): {
+        x: number;
+        y: number;
+        index: number;
+    } | null;
+    /** Replace point positions and re-upload (for streaming). Keeps uniform color. */
+    setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
+    draw(state: DrawState): void;
+    dispose(): void;
+}
+
+/**
+ * A scale maps data-space values to normalized [0,1] and back, and knows how to
+ * generate its own "nice" ticks + default label format. `log` tells layers to
+ * apply a log10 transform on the GPU.
+ */
+interface Scale {
+    readonly type: string;
+    readonly log: boolean;
+    domain: Range;
+    norm(value: number): number;
+    invert(t: number): number;
+    /** Auto ticks appropriate for this scale type. */
+    ticks(target?: number): Tick[];
+    /** Default label formatter for a tick value. */
+    formatTick(value: number): string;
+}
+declare class LinearScale implements Scale {
+    readonly type = "linear";
+    readonly log = false;
+    domain: Range;
+    constructor(domain?: Range);
+    norm(value: number): number;
+    invert(t: number): number;
+    ticks(target?: number): Tick[];
+    formatTick(value: number): string;
+}
+declare class LogScale implements Scale {
+    readonly type = "log";
+    readonly log = true;
+    domain: Range;
+    constructor(domain?: Range);
+    private static sanitize;
+    private get la();
+    private get lb();
+    norm(value: number): number;
+    invert(t: number): number;
+    ticks(): Tick[];
+    formatTick(value: number): string;
+}
+/** Linear over epoch-millisecond values, with calendar-aware ticks/labels. */
+declare class TimeScale implements Scale {
+    readonly type = "time";
+    readonly log = false;
+    domain: Range;
+    constructor(domain?: Range);
+    norm(value: number): number;
+    invert(t: number): number;
+    private chooseStep;
+    ticks(target?: number): Tick[];
+    formatTick(value: number): string;
+}
+type ScaleType = "linear" | "log" | "time";
+declare function makeScale(type: ScaleType, domain?: Range): Scale;
+
+/** Pixel geometry of the plot, in CSS pixels. The plot region excludes margins. */
+interface Layout {
+    cssWidth: number;
+    cssHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+interface Theme {
+    axis: string;
+    grid: string;
+    gridMinor: string;
+    text: string;
+    font: string;
+}
+declare const lightTheme: Theme;
+declare const darkTheme: Theme;
+
+interface AxisScaleOptions {
+    type?: ScaleType;
+    /** Fixed domain. If omitted, the axis autoscales to the data. */
+    domain?: Range;
+}
+interface YAxisOptions extends AxisConfig {
+    type?: ScaleType;
+    domain?: Range;
+    /** 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;
+}
+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. */
+    toolbar?: boolean;
+    /** Initial interaction mode. Default `"box"`. */
+    mode?: InteractionMode;
+    /** Enable hover crosshair + tooltip. Default true. */
+    hover?: boolean;
+}
+/**
+ * The imperative core plot. Owns a stack of three canvases (grid / WebGL data /
+ * axis overlay), a shared x scale, and one-or-more named y axes.
+ */
+declare class Plot {
+    private container;
+    private gridCanvas;
+    private dataCanvas;
+    private axisCanvas;
+    private gridCtx;
+    private dataCtx;
+    private axisCtx;
+    private gl;
+    /** Shared offscreen WebGL canvas we render into, then blit onto `dataCanvas`. */
+    private sharedCanvas;
+    private scaleX;
+    private axisX;
+    private autoX;
+    private initialX;
+    /** Named y axes, insertion-ordered. `"y"` is always the primary. */
+    private yAxes;
+    private layers;
+    private theme;
+    private isDark;
+    private baseMargin;
+    private dpr;
+    private resizeObserver;
+    private frameRequested;
+    private mode;
+    private selectionDiv;
+    private modeChangeCbs;
+    private toolbarHandle;
+    private hoverEnabled;
+    private hoverPx;
+    private tooltip;
+    constructor(container: HTMLElement, options?: PlotOptions);
+    private makeCanvas;
+    /** Margins grow to make room for extra y axes on each side. */
+    private computeMargin;
+    private layout;
+    /** Pixel x-position (and title x) for each y axis, by draw order per side. */
+    private yAxisPositions;
+    private register;
+    addLine(opts: LineOptions): LineLayer;
+    addScatter(opts: ScatterOptions): ScatterLayer;
+    addBar(opts: BarOptions): BarLayer;
+    addArea(opts: AreaOptions): AreaLayer;
+    addHeatmap(opts: HeatmapOptions): HeatmapLayer;
+    addBox(opts: BoxOptions): BoxLayer;
+    addHexbin(opts: HexbinOptions): HexbinLayer;
+    addContour(opts: ContourOptions): ContourLayer;
+    /** Compute an STFT of `signal` and render it as a heatmap (time × frequency). */
+    addHeatmapSpectrogram(signal: ArrayLike<number>, opts?: {
+        fftSize?: number;
+        hop?: number;
+        sampleRate?: number;
+        colormap?: HeatmapOptions["colormap"];
+    }): HeatmapLayer;
+    /** Bin raw `values` and render a histogram as bars. */
+    addHistogram(values: ArrayLike<number>, opts?: {
+        bins?: number;
+        range?: [number, number];
+        color?: string;
+        name?: string;
+        yAxis?: string;
+    }): BarLayer;
+    /** Register an additional named y axis. Series opt in via `addLine({ yAxis })`. */
+    addYAxis(id: string, opts?: YAxisOptions): 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;
+    /** Set (or lock) the visible domain. `y` targets the primary axis; use `yAxes` for others. */
+    setView(view: {
+        x?: Range;
+        y?: Range;
+        yAxes?: Record<string, Range>;
+    }): void;
+    private setYDomain;
+    setMode(mode: InteractionMode): void;
+    getMode(): InteractionMode;
+    onModeChange(cb: (mode: InteractionMode) => void): void;
+    /** Reset to the home view: explicit domains restored, auto axes re-fit to data. */
+    home(): void;
+    /** Re-fit auto axes to the data: x over all series, each y axis over its own series. */
+    autoscale(): void;
+    destroy(): void;
+    private resize;
+    requestRender(): void;
+    private primaryY;
+    render(): void;
+    private renderHover;
+    private updateTooltip;
+    private updateCursor;
+    private axisLock;
+    /**
+     * Which region the pointer is over: the plot body, the x-axis strip (below),
+     * or a specific y-axis strip (in a side margin). Dragging an axis strip pans
+     * just that axis.
+     */
+    private zoneAt;
+    private panX;
+    private panY;
+    private attachInteraction;
+    private setHover;
+    private drawSelection;
+    private applySelection;
+    private zoomAround;
+}
+
+/** The subset of Plot the toolbar drives. Kept minimal to avoid an import cycle. */
+interface ToolbarHost {
+    setMode(mode: InteractionMode): void;
+    getMode(): InteractionMode;
+    home(): void;
+    onModeChange(cb: (mode: InteractionMode) => void): void;
+}
+interface ToolbarTheme {
+    bg: string;
+    fg: string;
+    border: string;
+    activeBg: string;
+    activeFg: string;
+    hoverBg: string;
+}
+/** Build a floating toolbar in `container` and wire it to the plot host. */
+declare function createToolbar(container: HTMLElement, host: ToolbarHost, dark: boolean): {
+    element: HTMLElement;
+    destroy: () => void;
+};
+
+interface PolarOptions {
+    theme?: "light" | "dark" | Theme;
+    /** Angle unit of input theta values. Default `"rad"`. */
+    angleUnit?: "rad" | "deg";
+    /** Fixed max radius. If omitted, autoscales to the data. */
+    maxRadius?: number;
+    margin?: number;
+}
+interface PolarLineOptions {
+    theta: ArrayLike<number>;
+    r: ArrayLike<number>;
+    color?: string | Color;
+    width?: number;
+    /** Connect the last point back to the first. */
+    closed?: boolean;
+}
+interface PolarScatterOptions {
+    theta: ArrayLike<number>;
+    r: ArrayLike<number>;
+    color?: string | Color;
+    size?: number;
+}
+/** A live handle to update a polar series with new (theta, r) data. */
+interface PolarSeries {
+    setData(theta: ArrayLike<number>, r: ArrayLike<number>): void;
+}
+/** A polar (r, θ) plot: concentric radial grid + angular spokes, WebGL data. */
+declare class PolarPlot {
+    private container;
+    private gridCanvas;
+    private dataCanvas;
+    private gridCtx;
+    private dataCtx;
+    private gl;
+    private sharedCanvas;
+    private theme;
+    private toRad;
+    private fixedR?;
+    private margin;
+    private entries;
+    private R;
+    private dpr;
+    private resizeObserver;
+    private frameRequested;
+    constructor(container: HTMLElement, options?: PolarOptions);
+    private makeCanvas;
+    private toXY;
+    addLine(opts: PolarLineOptions): PolarSeries;
+    addScatter(opts: PolarScatterOptions): PolarSeries;
+    private handle;
+    private refit;
+    destroy(): void;
+    private resize;
+    requestRender(): void;
+    /** The square drawing region (CSS px). */
+    private square;
+    render(): void;
+    private drawGrid;
+}
+
+/** Minimal column-major 4×4 matrix helpers for the 3D plots (WebGL convention). */
+type Mat4 = Float32Array;
+
+interface Bounds3 {
+    x: Range;
+    y: Range;
+    z: Range;
+}
+/** A drawable in the 3D scene. Positions are in world space; Plot3D supplies the MVP. */
+interface Layer3D {
+    readonly id: string;
+    bounds3(): Bounds3 | null;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
+interface PointCloudOptions {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    z: ArrayLike<number>;
+    color?: string | Color;
+    size?: number;
+    colorBy?: {
+        values: ArrayLike<number>;
+        colormap?: ColormapName;
+        domain?: Range;
+    };
+}
+declare class PointCloudLayer implements Layer3D {
+    readonly id: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private count;
+    private size;
+    private b3;
+    constructor(gl: WebGL2RenderingContext, opts: PointCloudOptions);
+    bounds3(): Bounds3 | null;
+    draw(gl: WebGL2RenderingContext, mvp: Mat4): void;
+    dispose(): void;
+}
+
+interface SurfaceOptions {
+    /** Row-major height grid, length `cols * rows`. */
+    values: ArrayLike<number>;
+    cols: number;
+    rows: number;
+    /** World extent of the grid footprint. Defaults to unit indices. */
+    extentX?: Range;
+    extentZ?: Range;
+    colormap?: ColormapName;
+}
+declare class SurfaceLayer implements Layer3D {
+    readonly id: string;
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uniforms;
+    private vertexCount;
+    private b3;
+    private lightDir;
+    private ambient;
+    constructor(gl: WebGL2RenderingContext, opts: SurfaceOptions);
+    bounds3(): Bounds3;
+    /** 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 Plot3DOptions {
+    background?: [number, number, number, number];
+    azimuth?: number;
+    elevation?: number;
+    distance?: number;
+    /** Axis titles drawn along the x / y (height) / z edges. */
+    axisLabels?: {
+        x?: string;
+        y?: string;
+        z?: string;
+    };
+    /** Render a small on-canvas panel with light-angle + ambient sliders. */
+    lightControls?: boolean;
+}
+/** A 3D scatter/surface plot with an orbit camera, axis ticks, and lighting. */
+declare class Plot3D {
+    private container;
+    private canvas;
+    private displayCtx;
+    private gl;
+    private sharedCanvas;
+    private layers;
+    private normalize;
+    private dataBounds;
+    private bg;
+    private dpr;
+    private azimuth;
+    private elevation;
+    private distance;
+    private axisLabels;
+    private resizeObserver;
+    private frameRequested;
+    private lineProgram;
+    private lineUniforms;
+    private boxVao;
+    private boxBuf;
+    private tickVao;
+    private tickBuf;
+    private tickCount;
+    private labels;
+    private lightAz;
+    private lightEl;
+    private ambient;
+    private controlsEl;
+    constructor(container: HTMLElement, options?: Plot3DOptions);
+    private bindLineVao;
+    addSurface(opts: SurfaceOptions): SurfaceLayer;
+    addPointCloud(opts: PointCloudOptions): PointCloudLayer;
+    /** Update the light direction (azimuth/elevation, radians) and ambient (0..1). */
+    setLight(params: {
+        azimuth?: number;
+        elevation?: number;
+        ambient?: number;
+    }): void;
+    private lightDir;
+    destroy(): void;
+    private recompute;
+    /** Build tick-mark line geometry + tick/title labels from the data bounds. */
+    private buildAxes;
+    private resize;
+    requestRender(): void;
+    private viewProj;
+    render(): void;
+    private drawLabels;
+    private attachControls;
+    private buildControls;
+}
+
+/**
+ * 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
+ * generator (function of the range) — plus major/minor, per-tick labels, and
+ * `addTicks` layering.
+ */
+declare class Axis {
+    config: AxisConfig;
+    constructor(config?: AxisConfig);
+    update(patch: Partial<AxisConfig>): void;
+    /** Resolve the concrete tick list (labels filled) for the scale's domain. */
+    resolve(scale: Scale): Tick[];
+}
+
+/**
+ * Auto ticks for a linear axis using nice-number rounding.
+ * Returns major ticks; minor ticks are added separately.
+ */
+declare function autoTicks(min: number, max: number, target?: number): Tick[];
+/** Insert `count` evenly spaced minor ticks between each pair of major ticks. */
+declare function withMinorTicks(major: Tick[], count: number): Tick[];
+/**
+ * Resolve a user `TicksSpec` (array | Tick[] | generator) against the current
+ * axis range into a concrete, sorted Tick list. Returns `null` if no explicit
+ * spec was given, signaling the caller to fall back to auto ticks.
+ */
+declare function resolveTicks(spec: TicksSpec | undefined, min: number, max: number): Tick[] | null;
+/** Default number formatter: compact, avoids noisy trailing decimals. */
+declare function defaultFormat(value: number): string;
+
+/** Pure statistics helpers backing the histogram, box, and violin layers. */
+interface Histogram {
+    edges: Float64Array;
+    counts: Float64Array;
+    centers: Float64Array;
+    binWidth: number;
+}
+/** Bin `values` into `bins` equal-width buckets (or use explicit `edges`). */
+declare function histogram(values: ArrayLike<number>, opts?: {
+    bins?: number;
+    edges?: ArrayLike<number>;
+    range?: [number, number];
+}): Histogram;
+/** Quantile of a *sorted* array via linear interpolation (type-7, like NumPy). */
+declare function quantileSorted(sorted: ArrayLike<number>, q: number): number;
+interface BoxStats {
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    /** Whisker ends: furthest points within 1.5·IQR of the quartiles. */
+    whiskerLo: number;
+    whiskerHi: number;
+    outliers: number[];
+}
+/** Tukey box-plot statistics for a set of values. */
+declare function boxStats(values: ArrayLike<number>): BoxStats;
+/** In-place iterative radix-2 Cooley–Tukey FFT (length must be a power of two). */
+declare function fft(re: Float64Array, im: Float64Array): void;
+interface Spectrogram {
+    /** Row-major magnitudes (dB), rows = freq bins (low at row 0), cols = frames. */
+    values: Float64Array;
+    cols: number;
+    rows: number;
+    extent: {
+        x: [number, number];
+        y: [number, number];
+    };
+}
+/** Short-time Fourier transform of a real signal → a time×frequency dB grid. */
+declare function spectrogram(signal: ArrayLike<number>, opts?: {
+    fftSize?: number;
+    hop?: number;
+    sampleRate?: number;
+}): Spectrogram;
+interface Density {
+    xs: Float64Array;
+    ys: Float64Array;
+}
+/**
+ * Gaussian kernel density estimate over `points` grid samples in [lo, hi].
+ * Bandwidth defaults to Silverman's rule of thumb.
+ */
+declare function kde(values: ArrayLike<number>, lo: number, hi: number, points?: number, bandwidth?: number): Density;
+
+/** 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, type Color, type ColormapName, ContourLayer, type ContourOptions, type Density, type Dim, type DrawState, HeatmapLayer, type HeatmapOptions, HexbinLayer, type HexbinOptions, type Histogram, type InteractionMode, type Layer, type Layer3D, type Layout, LineLayer, type LineOptions, LinearScale, LogScale, Plot, Plot3D, type Plot3DOptions, type PlotOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, type RGB, type Range, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type Spectrogram, SurfaceLayer, type SurfaceOptions, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type YAxisOptions, autoTicks, boxStats, colormap, createToolbar, darkTheme, defaultFormat, fft, histogram, kde, lightTheme, makeScale, parseColor, quantileSorted, resolveTicks, spectrogram, toColorCss, withMinorTicks };