velo-plot 1.11.1

package/dist/plugins/types.d.ts

@@ -0,0 +1,451 @@
+import { Chart } from '../core/chart/types';
+import { Series } from '../core/Series';
+import { Bounds, SeriesData, ChartEventMap } from '../types';
+import { Annotation } from '../core/annotations';
+import { SelectedPoint } from '../core/selection';
+import { ChartTheme } from '../theme';
+
+/**
+ * Plugin semantic version (major.minor.patch)
+ */
+export type PluginVersion = `${number}.${number}.${number}`;
+/**
+ * Plugin capability identifiers
+ * Plugins can declare what features they provide
+ */
+export type PluginCapability = "analysis" | "visualization" | "interaction" | "data-source" | "export" | "ui" | "annotation" | "theme" | string;
+/**
+ * Plugin manifest with metadata
+ */
+export interface PluginManifest {
+    /** Unique plugin identifier (e.g., '@myorg/fft-plugin') */
+    name: string;
+    /** Plugin version following semver */
+    version: PluginVersion;
+    /** Human-readable description */
+    description?: string;
+    /** Author name or organization */
+    author?: string;
+    /** URL for documentation or homepage */
+    homepage?: string;
+    /** License identifier (e.g., 'MIT', 'Apache-2.0') */
+    license?: string;
+    /** Capabilities this plugin provides */
+    provides?: PluginCapability[];
+    /** Required plugins that must be loaded first */
+    dependencies?: string[];
+    /** Optional plugins that enhance this one if present */
+    optionalDependencies?: string[];
+    /** Minimum Sci Plot version required */
+    engineVersion?: PluginVersion;
+    /** Plugin-specific configuration schema (JSON Schema format) */
+    configSchema?: Record<string, unknown>;
+    /** Tags for discovery/categorization */
+    tags?: string[];
+}
+/**
+ * Read-only access to chart rendering context
+ */
+export interface RenderContext {
+    /** WebGL rendering context */
+    readonly gl?: WebGLRenderingContext | WebGL2RenderingContext;
+    /** Overlay 2D canvas context */
+    readonly ctx2d?: CanvasRenderingContext2D;
+    /** Current device pixel ratio */
+    readonly pixelRatio: number;
+    /** Current canvas dimensions */
+    readonly canvasSize: {
+        width: number;
+        height: number;
+    };
+    /** Current plot area bounds */
+    readonly plotArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Coordinate conversion utilities
+ */
+export interface CoordinateContext {
+    /** Convert data X to pixel X */
+    dataToPixelX(dataX: number): number;
+    /** Convert data Y to pixel Y */
+    dataToPixelY(dataY: number, yAxisId?: string): number;
+    /** Convert pixel X to data X */
+    pixelToDataX(pixelX: number): number;
+    /** Convert pixel Y to data Y */
+    pixelToDataY(pixelY: number, yAxisId?: string): number;
+    /** Get data point at pixel position */
+    pickPoint(pixelX: number, pixelY: number, radius?: number): PickResult | null;
+}
+/**
+ * Result from coordinate picking
+ */
+export interface PickResult {
+    seriesId: string;
+    index: number;
+    x: number;
+    y: number;
+    pixelX: number;
+    pixelY: number;
+    distance: number;
+}
+/**
+ * Data access context for plugins
+ */
+export interface DataContext {
+    /** Get all series in the chart */
+    getAllSeries(): readonly Series[];
+    /** Get specific series by ID */
+    getSeries(id: string): Series | undefined;
+    /** Get series data as typed arrays */
+    getSeriesData(id: string): Readonly<SeriesData> | undefined;
+    /** Get visible data bounds */
+    getViewBounds(): Readonly<Bounds>;
+    /** Get data bounds for a specific Y axis */
+    getYAxisBounds(yAxisId?: string): {
+        yMin: number;
+        yMax: number;
+    };
+    /** Get all annotations */
+    getAnnotations(): readonly Annotation[];
+    /** Get selected points */
+    getSelectedPoints(): readonly SelectedPoint[];
+}
+/**
+ * UI context for plugins that need to add UI elements
+ */
+export interface UIContext {
+    /** Chart container element */
+    readonly container: HTMLDivElement;
+    /** Create a plugin UI container (positioned over chart) */
+    createOverlay(id: string, options?: OverlayOptions): HTMLDivElement;
+    /** Remove a plugin UI overlay */
+    removeOverlay(id: string): boolean;
+    /** Get existing overlay by ID */
+    getOverlay(id: string): HTMLDivElement | undefined;
+    /** Show a notification/toast message */
+    showNotification(message: string, options?: NotificationOptions): void;
+    /** Current theme */
+    readonly theme: Readonly<ChartTheme>;
+}
+export interface OverlayOptions {
+    /** Z-index order (default: 1000) */
+    zIndex?: number;
+    /** CSS class name */
+    className?: string;
+    /** Initial position */
+    position?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+    /** Whether overlay should intercept pointer events (default: false) */
+    pointerEvents?: boolean;
+}
+export interface NotificationOptions {
+    type?: "info" | "success" | "warning" | "error";
+    duration?: number;
+    position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+}
+/**
+ * Event context for plugins
+ */
+export interface EventContext {
+    /** Subscribe to chart events */
+    on<K extends keyof ChartEventMap>(event: K, handler: (data: ChartEventMap[K]) => void): () => void;
+    /** Subscribe once to chart events */
+    once<K extends keyof ChartEventMap>(event: K, handler: (data: ChartEventMap[K]) => void): () => void;
+    /** Emit custom plugin events */
+    emit(event: string, data?: unknown): void;
+    /** Listen to custom plugin events */
+    onPlugin(event: string, handler: (data: unknown) => void): () => void;
+}
+/**
+ * Complete plugin context provided to plugins
+ */
+export interface PluginContext {
+    /** The chart instance (full API) */
+    readonly chart: Chart;
+    /** Rendering context access */
+    readonly render: RenderContext;
+    /** Coordinate conversion */
+    readonly coords: CoordinateContext;
+    /** Data access */
+    readonly data: DataContext;
+    /** UI management */
+    readonly ui: UIContext;
+    /** Event handling */
+    readonly events: EventContext;
+    /** Plugin storage (persisted with chart state) */
+    readonly storage: PluginStorage;
+    /** Logger namespaced to plugin */
+    readonly log: PluginLogger;
+    /** Access other loaded plugins */
+    getPlugin<T extends ChartPlugin = ChartPlugin>(name: string): T | undefined;
+    /** Request a re-render */
+    requestRender(): void;
+    /** Schedule work on next frame */
+    requestAnimationFrame(callback: () => void): number;
+    /** Cancel scheduled work */
+    cancelAnimationFrame(id: number): void;
+}
+/**
+ * Plugin-scoped storage
+ */
+export interface PluginStorage {
+    /** Get a stored value */
+    get<T>(key: string): T | undefined;
+    /** Set a value */
+    set<T>(key: string, value: T): void;
+    /** Remove a value */
+    remove(key: string): void;
+    /** Clear all plugin storage */
+    clear(): void;
+    /** Get all storage keys */
+    keys(): string[];
+}
+/**
+ * Plugin-scoped logger
+ */
+export interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Data passed to beforeRender hook
+ */
+export interface BeforeRenderEvent {
+    /** Current timestamp */
+    timestamp: number;
+    /** Time since last render (ms) */
+    deltaTime: number;
+    /** Current frame number */
+    frameNumber: number;
+    /** Whether this is a forced render */
+    forced: boolean;
+}
+/**
+ * Data passed to afterRender hook
+ */
+export interface AfterRenderEvent extends BeforeRenderEvent {
+    /** Render duration (ms) */
+    renderTime: number;
+}
+/**
+ * Data passed to interaction hooks
+ */
+export interface InteractionEvent {
+    /** Event type */
+    type: "mousedown" | "mouseup" | "mousemove" | "wheel" | "click" | "dblclick" | "contextmenu";
+    /** Pixel coordinates */
+    pixelX: number;
+    pixelY: number;
+    /** Data coordinates (if in plot area) */
+    dataX?: number;
+    dataY?: number;
+    /** Whether event is inside plot area */
+    inPlotArea: boolean;
+    /** Original DOM event */
+    originalEvent: MouseEvent | WheelEvent;
+    /** Prevent default chart handling */
+    preventDefault(): void;
+    /** Whether default was prevented */
+    readonly defaultPrevented: boolean;
+}
+/**
+ * Data passed to zoom/pan hooks
+ */
+export interface ViewChangeEvent {
+    /** Previous bounds */
+    previous: Readonly<Bounds>;
+    /** New bounds */
+    current: Readonly<Bounds>;
+    /** Change trigger */
+    trigger: "zoom" | "pan" | "autoScale" | "reset" | "api";
+    /** Whether animated */
+    animated: boolean;
+}
+/**
+ * Data passed to series change hooks
+ */
+export interface SeriesChangeEvent {
+    /** The series that changed */
+    series: Series;
+    /** Change type */
+    changeType: "add" | "remove" | "update" | "style" | "visibility";
+}
+/**
+ * Data passed to data update hooks
+ */
+export interface DataUpdateEvent {
+    /** Series ID */
+    seriesId: string;
+    /** Whether data was appended or replaced */
+    mode: "append" | "replace";
+    /** Number of points added/changed */
+    pointCount: number;
+    /** New data bounds */
+    bounds: Readonly<Bounds>;
+}
+/**
+ * Main plugin interface
+ *
+ * Plugins can implement any subset of these hooks.
+ * All hooks receive the PluginContext as first argument.
+ */
+export interface ChartPlugin<TConfig = unknown> {
+    /** Plugin manifest with metadata */
+    readonly manifest: PluginManifest;
+    /**
+     * Called when plugin is attached to chart
+     * Use for initial setup, event subscriptions, UI creation
+     */
+    onInit?(ctx: PluginContext, config?: TConfig): void | Promise<void>;
+    /**
+     * Called when plugin is about to be removed
+     * Clean up resources, remove UI elements, unsubscribe events
+     */
+    onDestroy?(ctx: PluginContext): void;
+    /**
+     * Called when plugin configuration changes
+     */
+    onConfigChange?(ctx: PluginContext, newConfig: TConfig, oldConfig: TConfig): void;
+    /**
+     * Called before each render cycle
+     * Can be used to prepare data or skip render
+     * Return false to skip this frame
+     */
+    onBeforeRender?(ctx: PluginContext, event: BeforeRenderEvent): boolean | void;
+    /**
+     * Called after WebGL rendering, before overlay rendering
+     * Use for custom WebGL-based rendering
+     */
+    onRenderWebGL?(ctx: PluginContext, event: AfterRenderEvent): void;
+    /**
+     * Called after overlay rendering
+     * Use for custom 2D canvas rendering
+     */
+    onRenderOverlay?(ctx: PluginContext, event: AfterRenderEvent): void;
+    /**
+     * Called after all rendering is complete
+     */
+    onAfterRender?(ctx: PluginContext, event: AfterRenderEvent): void;
+    /**
+     * Called when any series data changes
+     */
+    onDataUpdate?(ctx: PluginContext, event: DataUpdateEvent): void;
+    /**
+     * Called when a series is added
+     */
+    onSeriesAdd?(ctx: PluginContext, event: SeriesChangeEvent): void;
+    /**
+     * Called when a series is removed
+     */
+    onSeriesRemove?(ctx: PluginContext, event: SeriesChangeEvent): void;
+    /**
+     * Called when series style/visibility changes
+     */
+    onSeriesChange?(ctx: PluginContext, event: SeriesChangeEvent): void;
+    /**
+     * Called when view bounds change (zoom/pan)
+     */
+    onViewChange?(ctx: PluginContext, event: ViewChangeEvent): void;
+    /**
+     * Called when chart is resized
+     */
+    onResize?(ctx: PluginContext, size: {
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Called when theme changes
+     */
+    onThemeChange?(ctx: PluginContext, theme: ChartTheme): void;
+    /**
+     * Called for all mouse/touch interactions
+     * Return false to prevent default chart handling
+     */
+    onInteraction?(ctx: PluginContext, event: InteractionEvent): boolean | void;
+    /**
+     * Called when selection changes
+     */
+    onSelectionChange?(ctx: PluginContext, points: readonly SelectedPoint[]): void;
+    /**
+     * Called when chart state is being serialized
+     * Return plugin-specific state to include
+     */
+    onSerialize?(ctx: PluginContext): unknown;
+    /**
+     * Called when chart state is being deserialized
+     * Restore plugin state from saved data
+     */
+    onDeserialize?(ctx: PluginContext, data: unknown): void;
+    /**
+     * Expose public API for other plugins or user code
+     * Accessible via ctx.getPlugin<MyPlugin>('my-plugin').api
+     */
+    readonly api?: Record<string, unknown>;
+}
+/**
+ * Factory function to create plugin instances
+ * Useful for plugins that need configuration
+ */
+export type PluginFactory<TConfig = unknown> = (config?: TConfig) => ChartPlugin<TConfig>;
+/**
+ * Type helper for creating typed plugin factories
+ */
+export type TypedPlugin<T extends ChartPlugin> = T;
+/**
+ * Plugin manager interface
+ */
+export interface PluginManager {
+    /** Register a plugin */
+    use<TConfig>(plugin: ChartPlugin<TConfig> | PluginFactory<TConfig>, config?: TConfig): Promise<void>;
+    /** Remove a plugin by name */
+    remove(name: string): Promise<boolean>;
+    /** Get a plugin by name */
+    get<T extends ChartPlugin = ChartPlugin>(name: string): T | undefined;
+    /** Check if a plugin is loaded */
+    has(name: string): boolean;
+    /** Get all loaded plugin names */
+    getNames(): string[];
+    /** Get all loaded plugin manifests */
+    getManifests(): PluginManifest[];
+    /** Update plugin configuration */
+    configure<TConfig>(name: string, config: TConfig): void;
+    /** Notify all plugins of an event */
+    notify(hook: string, ...args: unknown[]): void;
+    /** Destroy all plugins and cleanup */
+    destroy(): void;
+}
+/**
+ * Registration entry for global plugin registry
+ */
+export interface PluginRegistryEntry {
+    manifest: PluginManifest;
+    factory: PluginFactory;
+}
+/**
+ * Global plugin registry for third-party plugins
+ */
+export interface PluginRegistry {
+    /** Register a plugin globally */
+    register(entry: PluginRegistryEntry): void;
+    /** Unregister a plugin */
+    unregister(name: string): boolean;
+    /** Get a registered plugin factory */
+    get(name: string): PluginFactory | undefined;
+    /** List all registered plugins */
+    list(): PluginManifest[];
+    /** Search plugins by capability */
+    findByCapability(capability: PluginCapability): PluginManifest[];
+    /** Search plugins by tag */
+    findByTag(tag: string): PluginManifest[];
+}

package/dist/plugins/video-recorder/exports.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Video Recorder plugin exports
+ * @module plugins/video-recorder
+ */
+export { PluginVideoRecorder, default } from './index';
+export type { PluginVideoRecorderConfig, VideoRecorderAPI, VideoRecorderOptions, VideoFormat, RecordingMetadata, } from './types';

package/dist/plugins/video-recorder/index.d.ts

@@ -0,0 +1,6 @@
+import { PluginVideoRecorderConfig } from './types';
+import { ChartPlugin } from '../types';
+
+export declare function PluginVideoRecorder(userConfig?: Partial<PluginVideoRecorderConfig>): ChartPlugin<PluginVideoRecorderConfig>;
+export default PluginVideoRecorder;
+export type { PluginVideoRecorderConfig, VideoRecorderAPI, VideoRecorderOptions, } from './types';

package/dist/plugins/video-recorder/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Types for Video Recorder plugin
+ * @module plugins/video-recorder/types
+ */
+export type VideoFormat = "webm" | "mp4";
+export interface VideoRecorderOptions {
+    /** Video format (default: 'webm') */
+    format?: VideoFormat;
+    /** Frame rate in FPS (default: 30) */
+    fps?: number;
+    /** Video bitrate in bits per second (default: 2.5Mbps) */
+    bitrate?: number;
+    /** Whether to include a white background if chart is transparent */
+    fillBackground?: boolean;
+    /** Background color if fillBackground is true */
+    backgroundColor?: string;
+    /** Quality for webm/mp4 (0-1) */
+    quality?: number;
+}
+export interface RecordingMetadata {
+    /** Duration of the recording in seconds */
+    duration: number;
+    /** Number of frames recorded */
+    frameCount: number;
+    /** Width of the video */
+    width: number;
+    /** Height of the video */
+    height: number;
+    /** Timestamp of the recording */
+    timestamp: number;
+}
+export interface VideoRecorderAPI {
+    /** Start recording the chart area */
+    start(): void;
+    /** Stop recording and return the video blob */
+    stop(): Promise<Blob>;
+    /** Pause recording */
+    pause(): void;
+    /** Resume recording */
+    resume(): void;
+    /** Whether the recorder is currently active */
+    isRecording(): boolean;
+    /** Whether the recorder is currently paused */
+    isPaused(): boolean;
+    /** Update current recording options */
+    updateConfig(config: Partial<VideoRecorderOptions>): void;
+}
+export interface PluginVideoRecorderConfig extends VideoRecorderOptions {
+    /** Automatically download the file after stopping (default: false) */
+    autoDownload?: boolean;
+    /** Filename for auto-download (default: 'chart-recording') */
+    filename?: string;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}

package/dist/plugins/virtualization/exports.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Virtualization plugin exports
+ * @module plugins/virtualization
+ */
+export { PluginVirtualization, default } from './index';
+export type { PluginVirtualizationConfig, VirtualizationAPI, VirtualizationStats, VirtualizationMode, VirtualizationStrategy, } from './types';

package/dist/plugins/virtualization/index.d.ts

@@ -0,0 +1,6 @@
+import { PluginVirtualizationConfig } from './types';
+import { ChartPlugin } from '../types';
+
+export declare function PluginVirtualization(userConfig?: Partial<PluginVirtualizationConfig>): ChartPlugin<PluginVirtualizationConfig>;
+export default PluginVirtualization;
+export type { PluginVirtualizationConfig, VirtualizationAPI, VirtualizationStats, VirtualizationMode, VirtualizationStrategy, } from './types';

package/dist/plugins/virtualization/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Types for data virtualization plugin
+ * @module plugins/virtualization/types
+ */
+export type VirtualizationMode = "lod" | "bins" | "hybrid";
+export type VirtualizationStrategy = "lttb" | "minmax";
+export interface PluginVirtualizationConfig {
+    /** Enable virtualization (default: true) */
+    enabled?: boolean;
+    /** Virtualization mode (default: 'lod') */
+    mode?: VirtualizationMode;
+    /** Target points or 'auto' (default: 'auto') */
+    targetPoints?: number | "auto";
+    /** Points per pixel when targetPoints is 'auto' (default: 2) */
+    pointsPerPixel?: number;
+    /** LOD levels (factors) used for heuristic switching (default: [1, 4, 8, 16]) */
+    lodLevels?: number[];
+    /** Downsample strategy (default: 'lttb') */
+    strategy?: VirtualizationStrategy;
+    /** Keep original data cached in plugin (default: true) */
+    reuseOriginalData?: boolean;
+    /** Sync updates with lazy-load (default: true) */
+    syncWithLazyLoad?: boolean;
+    /** Include series IDs (default: all) */
+    includeSeries?: string[];
+    /** Exclude series IDs (default: none) */
+    excludeSeries?: string[];
+    /** Debug logging (default: false) */
+    debug?: boolean;
+}
+export interface VirtualizationStats {
+    seriesId: string;
+    originalPoints: number;
+    renderedPoints: number;
+    targetPoints: number;
+    lastUpdated: number;
+    mode: VirtualizationMode;
+    strategy: VirtualizationStrategy;
+}
+export interface VirtualizationAPI {
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    updateConfig(config: Partial<PluginVirtualizationConfig>): void;
+    invalidate(seriesId?: string): void;
+    getStats(seriesId: string): VirtualizationStats | null;
+    getAllStats(): VirtualizationStats[];
+}

package/dist/react/SciPlot.d.ts

@@ -0,0 +1,60 @@
+import { CSSProperties } from 'react';
+import { UseSciPlotOptions } from './useSciPlot';
+import { ZoomOptions, CursorOptions, Bounds } from '../types';
+import { Chart } from '../core/Chart';
+
+export interface SciPlotSeries {
+    id: string;
+    x: Float32Array | Float64Array;
+    y: Float32Array | Float64Array;
+    color?: string;
+    width?: number;
+    visible?: boolean;
+}
+export interface SciPlotProps extends UseSciPlotOptions {
+    /** Series data to display */
+    series?: SciPlotSeries[];
+    /** Zoom state (controlled) */
+    zoom?: ZoomOptions;
+    /** Callback when zoom changes */
+    onZoomChange?: (bounds: Bounds) => void;
+    /** Cursor configuration */
+    cursor?: CursorOptions;
+    /** Container width */
+    width?: number | string;
+    /** Container height */
+    height?: number | string;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: CSSProperties;
+    /** Debug mode - shows FPS counter */
+    debug?: boolean;
+}
+export interface SciPlotRef {
+    /** Get the chart instance */
+    getChart: () => Chart | null;
+    /** Reset zoom to show all data */
+    resetZoom: () => void;
+    /** Get current bounds */
+    getBounds: () => Bounds | null;
+}
+/**
+ * SciPlot React Component
+ *
+ * @example
+ * ```tsx
+ * <SciPlot
+ *   series={[
+ *     { id: 'cv-1', x: potentialData, y: currentData, color: '#ff0055' }
+ *   ]}
+ *   xAxis={{ label: 'E / V' }}
+ *   yAxis={{ label: 'I / A' }}
+ *   height={400}
+ *   cursor={{ enabled: true, snap: true }}
+ *   onZoomChange={(bounds) => console.log('Zoom:', bounds)}
+ * />
+ * ```
+ */
+export declare const SciPlot: import('react').ForwardRefExoticComponent<SciPlotProps & import('react').RefAttributes<SciPlotRef>>;
+export default SciPlot;

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * React bindings for Sci Plot
+ */
+export { SciPlot, type SciPlotProps, type SciPlotRef, type SciPlotSeries } from './SciPlot';
+export { useSciPlot, type UseSciPlotOptions, type UseSciPlotReturn } from './useSciPlot';