matterviz 0.3.4 → 0.3.6

package/dist/src/lib/plot/types.ts

@@ -0,0 +1,1144 @@
+import type { D3SymbolName } from '$lib/labels'
+import type { Point2D, Point3D, Vec2, Vec3 } from '$lib/math'
+import type DraggablePane from '$lib/overlays/DraggablePane.svelte'
+import type { ComponentProps, Snippet } from 'svelte'
+import type { HTMLAttributes } from 'svelte/elements'
+import type { TweenOptions } from 'svelte/motion'
+export type { TweenOptions } from 'svelte/motion'
+import type { Sides } from './layout'
+import type PlotLegend from './PlotLegend.svelte'
+import type { TicksOption } from './scales'
+
+export type XyShift = { x?: number; y?: number } // For optional shift/offset values
+
+// Snapshot of axis ranges at interaction start (shared by pan/zoom/touch handlers)
+export type InitialRanges = {
+  initial_x_range: Vec2
+  initial_x2_range: Vec2
+  initial_y_range: Vec2
+  initial_y2_range: Vec2
+}
+
+export type Point<Metadata = Record<string, unknown>> = {
+  x: number
+  y: number
+  metadata?: Metadata
+  offset?: Point2D
+}
+
+export interface PointStyle {
+  fill?: string
+  radius?: number
+  stroke?: string
+  stroke_width?: number
+  stroke_opacity?: number
+  fill_opacity?: number
+  symbol_type?: D3SymbolName
+  symbol_size?: number | null // Optional override for marker size
+  shape?: string // Add optional shape (string for flexibility)
+  cursor?: string // Cursor style for the point
+  // Highlight support for phase diagrams and other use cases
+  is_highlighted?: boolean
+  highlight_color?: string
+  highlight_effect?: `pulse` | `glow` | `size` | `color` | `both`
+}
+
+export interface HoverStyle {
+  enabled?: boolean
+  scale?: number
+  stroke?: string
+  stroke_width?: number
+  brightness?: number
+}
+
+export interface LabelStyle {
+  text?: string
+  offset?: Point2D
+  font_size?: string
+  font_family?: string
+  auto_placement?: boolean // Enable/disable auto-placement
+  size?: { width: number; height: number }
+}
+
+export interface BarStyle {
+  color?: string
+  opacity?: number
+  stroke_width?: number
+  stroke_color?: string
+  stroke_opacity?: number
+  border_radius?: number // Shorthand: sets both rx and ry to this value (lower priority than explicit rx/ry)
+  rx?: number // SVG rx attribute for horizontal corner radius (overrides border_radius)
+  ry?: number // SVG ry attribute for vertical corner radius (overrides border_radius)
+  [key: string]: unknown
+}
+
+export interface LineStyle {
+  color?: string
+  width?: number
+  dash?: string
+  [key: string]: unknown
+}
+
+// Extend the base Point type to include optional styling and metadata
+export interface PlotPoint<Metadata = Record<string, unknown>> extends Point<Metadata> {
+  color_value?: number | null
+  point_style?: PointStyle
+  point_hover?: HoverStyle
+  point_label?: LabelStyle
+  point_offset?: Point2D // Individual point offset (distinct from label offset)
+  point_tween?: TweenOptions<Point2D>
+}
+
+export type Markers = `line` | `points` | `line+points` | `none`
+
+// Define the structure for a data series in the plot
+export interface DataSeries<Metadata = Record<string, unknown>> {
+  id?: string | number // Optional stable identifier for the series (used for keying)
+  x: readonly number[]
+  y: readonly number[]
+  // Optional marker display type override for this specific series
+  markers?: Markers
+  // Specify which x-axis to use: 'x1' (bottom, default) or 'x2' (top)
+  x_axis?: `x1` | `x2`
+  // Specify which y-axis to use: 'y1' (left, default) or 'y2' (right)
+  y_axis?: `y1` | `y2`
+  color_values?: (number | null)[] | null
+  size_values?: readonly (number | null)[] | null
+  metadata?: Metadata[] | Metadata // Can be array or single object
+  point_style?: PointStyle[] | PointStyle // Can be array or single object
+  point_hover?: HoverStyle[] | HoverStyle // Can be array or single object
+  point_label?: LabelStyle[] | LabelStyle // Can be array or single object
+  point_offset?: Point2D[] | Point2D // Can be array or single object
+  point_tween?: TweenOptions<Point2D>
+  visible?: boolean // Optional visibility flag
+  label?: string // Optional series label for legend
+  // Group name for organizing legend items. Series with the same legend_group
+  // are displayed together under a collapsible header. Click the header to toggle
+  // visibility of all series in the group, or the chevron to collapse/expand.
+  legend_group?: string
+  unit?: string // Optional unit for the series (e.g. "eV", "eV/Å", "GPa")
+  line_style?: {
+    stroke?: string
+    stroke_width?: number
+    line_dash?: string
+  }
+  // Internal fields used after processing (not provided by users)
+  filtered_data?: InternalPoint<Metadata>[]
+  _id?: string | number
+  orig_series_idx?: number // Original series index for consistent auto-cycling colors/symbols
+}
+
+// Represents the internal structure used within ScatterPlot, merging series-level and point-level data
+export interface InternalPoint<
+  Metadata = Record<string, unknown>,
+> extends PlotPoint<Metadata> {
+  series_idx: number // Index of the series this point belongs to
+  point_idx: number // Index of the point within its series
+  size_value?: number | null // Size value for the point
+}
+
+export interface Tooltip {
+  show: boolean
+  x: number
+  y: number
+  title?: string
+  items?: { label: string; value: string; color?: string }[]
+}
+
+export interface HandlerProps<Metadata = Record<string, unknown>> {
+  x: number
+  y: number
+  metadata?: Metadata | null
+  label?: string | null
+  series_idx: number
+  x_axis: AxisConfig
+  x2_axis?: AxisConfig
+  y_axis: AxisConfig
+  y2_axis?: AxisConfig
+  fullscreen?: boolean
+}
+
+export interface ScatterHandlerProps<
+  Metadata = Record<string, unknown>,
+> extends HandlerProps<Metadata> {
+  cx: number
+  cy: number
+  x_formatted: string
+  y_formatted: string
+  color_value?: number | null
+  colorbar?: {
+    value?: number | null
+    title?: string | null
+    scale?: unknown
+    tick_format?: string | null
+  }
+}
+export type ScatterHandlerEvent<Metadata = Record<string, unknown>> =
+  ScatterHandlerProps<Metadata> & { event: MouseEvent; point: InternalPoint<Metadata> }
+
+export interface BarHandlerProps<
+  Metadata = Record<string, unknown>,
+> extends HandlerProps<Metadata> {
+  bar_idx: number
+  orient_x: number
+  orient_y: number
+  active_y_axis: `y1` | `y2`
+  active_x_axis: `x1` | `x2`
+  color: string
+  category_label?: string // original string category (undefined when numeric x)
+}
+
+export interface HistogramHandlerProps<
+  Metadata = Record<string, unknown>,
+> extends HandlerProps<Metadata> {
+  value: number
+  count: number
+  property: string
+  active_y_axis: `y1` | `y2`
+  active_x_axis: `x1` | `x2`
+}
+
+export type TimeInterval = `day` | `month` | `year`
+
+// Base scale type names
+export type ScaleTypeName = `linear` | `log` | `arcsinh` | `time`
+
+// Arcsinh scale configuration with optional threshold parameter
+// threshold controls where linear→log transition occurs (default: 1)
+// For |x| << threshold: behaves linearly
+// For |x| >> threshold: behaves logarithmically
+export interface ArcsinhScaleConfig {
+  type: `arcsinh`
+  threshold?: number // default: 1
+}
+
+// Scale type can be a simple string or arcsinh config object
+export type ScaleType = `linear` | `log` | `arcsinh` | `time` | ArcsinhScaleConfig
+
+// Type guard for select value narrowing (avoids unsafe casts)
+const SCALE_TYPE_NAMES = new Set<string>([`linear`, `log`, `arcsinh`, `time`])
+export const is_scale_type_name = (val: string): val is ScaleTypeName =>
+  SCALE_TYPE_NAMES.has(val)
+
+// Helper to normalize ScaleType to base type name
+export function get_scale_type_name(scale_type: ScaleType | undefined): ScaleTypeName {
+  if (!scale_type) return `linear`
+  if (typeof scale_type === `string`) return scale_type
+  return scale_type.type
+}
+
+// Helper to get arcsinh threshold (returns 1 as default for non-arcsinh scales)
+export function get_arcsinh_threshold(scale_type: ScaleType | undefined): number {
+  if (!scale_type) return 1
+  if (typeof scale_type === `object` && scale_type.type === `arcsinh`) {
+    const threshold = scale_type.threshold ?? 1
+    if (!Number.isFinite(threshold) || threshold <= 0) {
+      throw new Error(`arcsinh threshold must be a positive finite number, got ${threshold}`)
+    }
+    return threshold
+  }
+  return 1 // default threshold
+}
+
+// Helper to detect time scale - checks explicit scale_type or falls back to format heuristic
+// Prefer explicit scale_type: 'time' for new code; format heuristic kept for backwards compatibility
+export function is_time_scale(
+  scale_type: ScaleType | undefined,
+  format: string | undefined,
+): boolean {
+  if (get_scale_type_name(scale_type) === `time`) return true
+  // Fallback: d3 time format strings start with '%'
+  return format?.startsWith(`%`) ?? false
+}
+
+export type QuadrantCounts = {
+  top_left: number
+  top_right: number
+  bottom_left: number
+  bottom_right: number
+}
+
+// Energy weights for the simulated annealing label placement
+export interface LabelPlacementWeights {
+  overlap?: number // Label-label overlap penalty (default: 30)
+  marker?: number // Label-marker overlap penalty (default: 100)
+  leader_cross?: number // Leader line crossing penalty (default: 10)
+  leader_text?: number // Leader line crossing label text penalty (default: 8)
+  distance?: number // Anchor distance penalty (default: 0.5)
+  bounds?: number // Out-of-bounds penalty (default: 100)
+}
+
+// Configuration for the label auto-placement algorithm (simulated annealing)
+export interface LabelPlacementConfig {
+  sa_iterations?: number // SA iterations per label (default: 2000)
+  weights?: LabelPlacementWeights // Energy function weights
+  leader_line_threshold?: number // Min displacement (px) to show dotted leader line (default: 15)
+  max_labels?: number // Skip SA when label count exceeds this (default: 300)
+  candidate_gap?: number // Extra gap (px) between marker radius and label candidates (default: 4)
+  // Hide labels in dense regions with more than `count` neighbors within `radius` px
+  max_neighbors?: { count: number; radius: number }
+}
+export type HoverConfig = {
+  threshold_px: number // Max screen distance (pixels) to trigger hover
+}
+
+// Type for PlotLegend props forwarded from ScatterPlot props
+export type LegendConfig = Omit<
+  ComponentProps<typeof PlotLegend>,
+  `series_data` | `on_drag_start` | `on_drag` | `on_drag_end`
+> & {
+  margin?: number | Sides
+  tween?: TweenOptions<Point2D>
+  responsive?: boolean // Allow legend to move if density changes (default: false)
+  draggable?: boolean // Allow legend to be dragged (default: true)
+  // Minimum distance from plot edges to avoid axis label overlap (default: 40)
+  axis_clearance?: number
+}
+
+// attributes for each item passed to the legend
+export interface LegendItem {
+  label: string
+  visible: boolean
+  series_idx: number
+  legend_group?: string // Optional group name for grouped legend rendering
+  // Type of item: 'series' for data series (default), 'fill' for fill regions
+  item_type?: `series` | `fill`
+  // For fill regions, the index in the computed_fills array (for unique keying)
+  fill_idx?: number
+  // For fill regions, the source type and index (for toggle handlers)
+  fill_source_type?: `fill_region` | `error_band`
+  fill_source_idx?: number
+  display_style: {
+    symbol_type?: D3SymbolName
+    symbol_color?: string
+    line_color?: string
+    line_dash?: string
+    // Fill region styling
+    fill_color?: string
+    fill_opacity?: number
+    edge_color?: string
+    // Gradient fill for legend swatch (when fill is a gradient, not a solid color)
+    fill_gradient?: FillGradient
+  }
+}
+
+export type UserContentProps = {
+  height: number
+  width: number
+  x_scale_fn: (x: number) => number
+  x2_scale_fn?: (x: number) => number
+  y_scale_fn: (y: number) => number
+  y2_scale_fn?: (y: number) => number
+  pad: Required<Sides>
+  x_range: Vec2
+  x2_range?: Vec2
+  y_range: Vec2
+  y2_range?: Vec2
+  fullscreen: boolean
+}
+
+export type Orientation = `vertical` | `horizontal`
+export type BarMode = `overlay` | `stacked` | `grouped`
+
+export interface BarSeries<Metadata = Record<string, unknown>> {
+  id?: string | number // Optional stable identifier for the series (used for keying)
+  x: readonly (number | string)[]
+  y: readonly number[]
+  label?: string
+  // Group name for organizing legend items. Series with the same legend_group
+  // are displayed together under a collapsible header. Click the header to toggle
+  // visibility of all series in the group, or the chevron to collapse/expand.
+  legend_group?: string
+  color?: string
+  bar_width?: number | readonly number[]
+  visible?: boolean
+  metadata?: Metadata[] | Metadata
+  labels?: readonly (string | null | undefined)[]
+  render_mode?: `bar` | `line` // Render as bars (default) or as a line
+  // Specify which x-axis to use: 'x1' (bottom, default) or 'x2' (top)
+  x_axis?: `x1` | `x2`
+  // Specify which y-axis to use: 'y1' (left, default) or 'y2' (right)
+  y_axis?: `y1` | `y2`
+  line_style?: {
+    stroke_width?: number
+    line_dash?: string
+  }
+  // Marker-related fields for line series (matching DataSeries)
+  markers?: Markers // 'line' | 'points' | 'line+points' | 'none'
+  color_values?: (number | null)[] | null
+  size_values?: readonly (number | null)[] | null
+  point_style?: PointStyle[] | PointStyle
+  point_hover?: HoverStyle[] | HoverStyle
+  point_label?: LabelStyle[] | LabelStyle
+  point_offset?: Point2D[] | Point2D
+}
+
+// Tick label configuration
+export interface TickLabelConfig {
+  inside?: boolean // Render tick labels inside the plot area (default: false/outside)
+  shift?: XyShift
+  rotation?: number // Rotation angle in degrees
+}
+
+// Tick configuration
+export interface TickConfig {
+  label?: TickLabelConfig
+}
+
+// Option for axis property dropdown (enables interactive axis switching)
+export interface AxisOption {
+  key: string // unique identifier (e.g., 'energy', 'volume')
+  label: string // display name (e.g., 'Total Energy')
+  unit?: string // optional unit (e.g., 'eV', 'ų')
+}
+
+// Y2 axis synchronization modes
+// - 'none': Independent axes (default)
+// - 'synced': Y2 has exact same range as Y1
+// - 'align': Y2 expands to show all data while keeping align_value (default 0) at same position as Y1
+export type Y2SyncMode = `none` | `synced` | `align`
+
+// Type guard for select value narrowing (avoids unsafe casts)
+const Y2_SYNC_MODES = new Set<string>([`none`, `synced`, `align`])
+export const is_y2_sync_mode = (val: string): val is Y2SyncMode => Y2_SYNC_MODES.has(val)
+
+export interface Y2SyncConfig {
+  mode: Y2SyncMode
+  // For align mode: optionally specify which value to align (default: 0)
+  align_value?: number
+}
+
+// Axis configuration type for grouping related axis properties
+export interface AxisConfig {
+  label?: string
+  format?: string
+  ticks?: TicksOption
+  tick?: TickConfig
+  scale_type?: ScaleType
+  range?: [number | null, number | null]
+  unit?: string
+  label_shift?: XyShift
+  grid_style?: HTMLAttributes<SVGLineElement>
+  color?: string | null // Color for axis label, tick labels, and axis line
+  // Interactive axis options (enables clickable axis labels)
+  options?: AxisOption[] // available properties for this axis
+  selected_key?: string // currently selected property key
+  // Synchronization with y1 axis (only applicable when used as y2_axis)
+  // - 'synced': Y2 has exact same range as Y1
+  // - 'align': Y2 expands to show all data, align_value (default 0) at same position
+  // - 'none' or undefined: Independent axes (default)
+  // Shorthand: 'synced' | 'align' | 'none'
+  // Full config: { mode: Y2SyncMode, align_value?: number }
+  sync?: Y2SyncConfig | Y2SyncMode
+  categories?: readonly string[] // explicit category order/filter for categorical bar plots
+}
+
+// Result from data loader - returns complete series array
+// SeriesType defaults to DataSeries but can be BarSeries for bar plots
+export interface DataLoaderResult<
+  Metadata = Record<string, unknown>,
+  SeriesType = DataSeries<Metadata>,
+> {
+  series: SeriesType[] // full replacement series
+  axis_label?: string // optional new axis label
+  axis_unit?: string // optional axis unit
+}
+
+// Callback to fetch data for a property change
+// Called when user selects a new property from the axis dropdown
+// SeriesType defaults to DataSeries but can be BarSeries for bar plots
+export type DataLoaderFn<
+  Metadata = Record<string, unknown>,
+  SeriesType = DataSeries<Metadata>,
+> = (
+  axis: AxisKey,
+  property_key: string,
+  current_series: readonly SeriesType[], // passed for context
+) => Promise<DataLoaderResult<Metadata, SeriesType>>
+
+// Error event for axis data loading failures
+export interface AxisLoadError {
+  axis: AxisKey
+  key: string
+  message: string
+}
+
+// Option for color scale dropdown in ColorBar
+export interface ColorScaleOption {
+  key: string // e.g., 'viridis', 'plasma'
+  label: string // e.g., 'Viridis', 'Plasma'
+  scale: string | ((t: number) => string) // d3 interpolator name or function
+}
+
+// Data loader for ColorBar property changes
+export type ColorBarDataLoaderFn = (
+  property_key: string,
+) => Promise<{ range: Vec2; title?: string }>
+
+// Display configuration for grid lines and zero lines
+export interface DisplayConfig {
+  x_grid?: boolean
+  x2_grid?: boolean
+  y_grid?: boolean
+  y2_grid?: boolean
+  x_zero_line?: boolean
+  x2_zero_line?: boolean
+  y_zero_line?: boolean
+  y2_zero_line?: boolean
+}
+
+// Style overrides for point and line properties
+export interface StyleOverrides {
+  point?: {
+    size?: number
+    color?: string
+    opacity?: number
+    stroke_width?: number
+    stroke_color?: string
+    stroke_opacity?: number
+  }
+  line?: {
+    width?: number
+    color?: string
+    opacity?: number
+    dash?: string
+  }
+  show_points?: boolean
+  show_lines?: boolean
+}
+
+export type AxisKey = `x` | `x2` | `y` | `y2`
+export interface PlotConfig {
+  // Grouped configuration for plot axes and display settings
+  x_axis?: AxisConfig
+  x2_axis?: AxisConfig
+  y_axis?: AxisConfig
+  y2_axis?: AxisConfig
+  display?: DisplayConfig
+}
+
+// Controls configuration
+export interface ControlsConfig {
+  show?: boolean
+  open?: boolean
+  toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+  pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
+}
+
+// Pan configuration for 2D plot components
+export interface PanConfig {
+  enabled?: boolean // default: true - whether panning is enabled
+  wheel_sensitivity?: number // default: 1 - multiplier for wheel delta
+  drag_sensitivity?: number // default: 1 - multiplier for drag delta
+  touch_enabled?: boolean // default: true - whether touch gestures are enabled
+}
+
+export type ControlsState = Required<PlotConfig> & {
+  show_controls: boolean
+  controls_open: boolean
+  range_inputs: Record<string, [number | null, number | null]>
+}
+
+export interface PlotControlsProps extends PlotConfig {
+  // Control pane visibility
+  show_controls?: boolean
+  controls_open?: boolean
+  // Custom snippets for additional controls
+  children?: Snippet<[ControlsState]>
+  post_children?: Snippet<[ControlsState]>
+  // Auto ranges for reset functionality
+  auto_x_range?: Vec2
+  auto_x2_range?: Vec2
+  auto_y_range?: Vec2
+  auto_y2_range?: Vec2
+  // Helper flags
+  has_x2_points?: boolean
+  has_y2_points?: boolean
+  show_ticks?: boolean
+  // Component props
+  controls_title?: string
+  controls_class?: string
+  toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+  pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
+}
+
+// Base props shared across plot components (non-bindable props only)
+// Components should declare x_axis, y_axis, display, etc. as $bindable() grouped configs
+export interface BasePlotProps {
+  // Axis limits (non-bindable - used for auto-range calculation)
+  x_range?: [number | null, number | null]
+  x2_range?: [number | null, number | null]
+  y_range?: [number | null, number | null]
+  y2_range?: [number | null, number | null]
+  range_padding?: number // Factor to pad auto-detected ranges before nicing (e.g. 0.05 = 5%)
+  padding?: Sides
+  // State
+  hovered?: boolean
+  // Controls
+  show_controls?: boolean
+  controls_open?: boolean
+  controls_toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+  controls_pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
+  // Fullscreen
+  fullscreen?: boolean
+  fullscreen_toggle?: boolean // default: true
+  // Callbacks
+  change?: (data: Record<string, unknown> | null) => void
+  // Children
+  children?: Snippet<[{ height: number; width: number; fullscreen?: boolean }]>
+}
+export const LINE_TYPES = [`solid`, `dashed`, `dotted`] as const
+export type LineType = (typeof LINE_TYPES)[number]
+
+// Define grid cell identifiers
+export const CELLS_3X3 = [
+  `top-left`,
+  `top-center`,
+  `top-right`,
+  `middle-left`,
+  `middle-center`,
+  `middle-right`,
+  `bottom-left`,
+  `bottom-center`,
+  `bottom-right`,
+] as const
+export const CORNER_CELLS = [`top-left`, `top-right`, `bottom-left`, `bottom-right`] as const
+
+// Define the structure for GridCell and GridCellCounts for 3x3 grid
+export type Cell3x3 = (typeof CELLS_3X3)[number]
+export type Corner = (typeof CORNER_CELLS)[number]
+
+// Default grid line style (SSOT for all plot components)
+export const DEFAULT_GRID_STYLE = {
+  stroke: `var(--border-color, gray)`,
+  'stroke-dasharray': `4`,
+  'stroke-width': `1`,
+} as const
+
+export const DEFAULT_MARKERS = `line+points` as const
+
+// Default series colors for auto-differentiation (similar to d3 schemeTableau10)
+export const DEFAULT_SERIES_COLORS = [
+  `#4e79a7`, // blue
+  `#f28e2c`, // orange
+  `#e15759`, // red
+  `#76b7b2`, // teal
+  `#59a14f`, // green
+  `#edc949`, // yellow
+  `#af7aa1`, // purple
+  `#ff9da7`, // pink
+  `#9c755f`, // brown
+  `#bab0ab`, // gray
+] as const
+
+// Default series symbols for auto-differentiation (cycling through distinct shapes)
+export const DEFAULT_SERIES_SYMBOLS = [
+  `Circle`,
+  `Square`,
+  `Triangle`,
+  `Cross`,
+  `Diamond`,
+  `Star`,
+  `Wye`,
+] as const satisfies readonly D3SymbolName[]
+
+// 3D point extending base Point with z coordinate (prefixed to avoid conflict with convex-hull)
+export interface ScatterPoint3D<Metadata = Record<string, unknown>> extends Point<Metadata> {
+  z: number
+}
+
+// 3D data series extending DataSeries with z array
+// Omit filtered_data since it uses 2D InternalPoint type, redeclare with 3D type
+export interface DataSeries3D<Metadata = Record<string, unknown>> extends Omit<
+  DataSeries<Metadata>,
+  `y_axis` | `filtered_data`
+> {
+  z: readonly number[]
+  filtered_data?: InternalPoint3D<Metadata>[]
+}
+
+// Internal 3D point for processing within ScatterPlot3D
+export interface InternalPoint3D<
+  Metadata = Record<string, unknown>,
+> extends ScatterPoint3D<Metadata> {
+  series_idx: number
+  point_idx: number
+  color_value?: number | null
+  size_value?: number | null
+  point_style?: PointStyle
+}
+
+// Surface types for 3D visualization
+export type SurfaceType = `grid` | `parametric` | `triangulated`
+
+// Configuration for 3D surfaces
+export interface Surface3DConfig {
+  id?: string | number
+  type: SurfaceType
+  // For grid surfaces: regular grid with z values
+  x_range?: Vec2
+  y_range?: Vec2
+  resolution?: number | Vec2 // grid resolution (x, y)
+  z_fn?: (x: number, y: number) => number
+  // For parametric surfaces: u,v parameterization
+  u_range?: Vec2
+  v_range?: Vec2
+  parametric_fn?: (u: number, v: number) => Point3D
+  // For triangulated surfaces: explicit geometry (only x,y,z needed, not scatter-specific fields)
+  points?: Point3D[]
+  triangles?: Vec3[] // indices into points array
+  // Appearance
+  color?: string
+  color_fn?: (x: number, y: number, z: number) => string
+  opacity?: number
+  wireframe?: boolean
+  wireframe_color?: string
+  wireframe_width?: number
+  visible?: boolean
+  // Double-sided rendering
+  double_sided?: boolean
+}
+
+// Extended axis config for 3D (same as 2D but can add 3D-specific options)
+export interface AxisConfig3D extends AxisConfig {
+  // 3D-specific axis options can be added here
+  show_plane?: boolean // Show grid plane for this axis
+  plane_opacity?: number
+}
+
+// Display config extended for 3D
+export interface DisplayConfig3D extends DisplayConfig {
+  z_grid?: boolean
+  z_zero_line?: boolean
+  show_axes?: boolean
+  show_axis_labels?: boolean
+  show_bounding_box?: boolean
+  show_grid?: boolean
+  // Projection settings - render point shadows on background planes
+  // Coordinate mapping: user X→Three.js X, user Y→Three.js Z, user Z→Three.js Y
+  projections?: {
+    xy?: boolean // Project onto XY plane (floor/ceiling) - fixes user Z
+    xz?: boolean // Project onto XZ plane (back wall) - fixes user Y
+    yz?: boolean // Project onto YZ plane (side wall) - fixes user X
+  }
+  projection_opacity?: number // 0-1, default 0.3
+  projection_scale?: number // Relative to point size, default 0.5
+}
+
+// 3D scatter handler props
+export interface Scatter3DHandlerProps<Metadata = Record<string, unknown>> extends Omit<
+  HandlerProps<Metadata>,
+  `x_axis` | `x2_axis` | `y_axis` | `y2_axis`
+> {
+  z: number
+  x_axis: AxisConfig3D
+  y_axis: AxisConfig3D
+  z_axis: AxisConfig3D
+  x_formatted: string
+  y_formatted: string
+  z_formatted: string
+  color_value?: number | null
+}
+
+export type Scatter3DHandlerEvent<Metadata = Record<string, unknown>> =
+  Scatter3DHandlerProps<Metadata> & {
+    event?: MouseEvent
+    point: InternalPoint3D<Metadata>
+  }
+
+// Camera projection types for 3D
+export type CameraProjection3D = `perspective` | `orthographic`
+
+// 3D plot config extending base
+export interface PlotConfig3D {
+  x_axis?: AxisConfig3D
+  y_axis?: AxisConfig3D
+  z_axis?: AxisConfig3D
+  display?: DisplayConfig3D
+}
+
+// 3D style overrides
+export interface StyleOverrides3D extends StyleOverrides {
+  point?: StyleOverrides[`point`] & {
+    sphere_segments?: number // Level of detail for sphere geometry
+  }
+}
+
+// Controls config for 3D
+export interface ControlsConfig3D extends ControlsConfig {
+  show_camera_controls?: boolean
+  show_surface_controls?: boolean
+}
+
+// FillBoundary - references to data sources for fill regions
+// Can reference series by index, by id, or specify constant/axis/function/data values
+export type FillBoundary =
+  | { type: `series`; series_idx: number }
+  | { type: `series`; series_id: string | number }
+  | { type: `constant`; value: number }
+  | { type: `axis`; axis: `x` | `x2` | `y` | `y2`; value?: number }
+  | { type: `function`; fn: (coord: number) => number }
+  | { type: `data`; values: readonly number[] }
+  | number // Shorthand for constant value
+
+// Styling types for fill regions
+
+// Gradient configuration for fill regions
+export interface FillGradient {
+  type: `linear` | `radial`
+  // For linear gradients: angle in degrees (0 = horizontal left-to-right, 90 = vertical top-to-bottom)
+  angle?: number
+  // For radial gradients: center position (0-1 normalized)
+  center?: { x: number; y: number }
+  // Color stops: array of [offset (0-1), color] pairs
+  stops: readonly [number, string][]
+}
+
+// Edge/stroke styling for fill region boundaries
+export interface FillEdgeStyle {
+  color?: string
+  width?: number
+  dash?: string
+  opacity?: number
+}
+
+// Hover state styling for fill regions
+export interface FillHoverStyle {
+  fill?: string
+  fill_opacity?: number
+  edge?: FillEdgeStyle
+  cursor?: string
+  scale?: number // Scale factor for hover effect
+}
+
+// Event type for fill region interactions
+export interface FillHandlerEvent {
+  event: MouseEvent | KeyboardEvent
+  region_idx: number
+  region_id?: string | number
+  x: number // Data x-coordinate
+  y: number // Data y-coordinate
+  px: number // Pixel x-coordinate
+  py: number // Pixel y-coordinate
+  label?: string
+  metadata?: Record<string, unknown>
+}
+
+// z-index positions for rendering order (used by fill regions and reference lines)
+export type LayerZIndex = `below-grid` | `below-lines` | `below-points` | `above-all`
+
+// Curve types supported for fill path generation (matching d3-shape curves)
+export const FILL_CURVE_TYPES = [
+  `linear`,
+  `monotoneX`,
+  `monotoneY`,
+  `step`,
+  `stepBefore`,
+  `stepAfter`,
+  `basis`,
+  `cardinal`,
+  `catmullRom`,
+  `natural`,
+] as const
+export type FillCurveType = (typeof FILL_CURVE_TYPES)[number]
+
+// Main configuration for a fill region
+export interface FillRegion {
+  // Identity
+  id?: string | number
+  label?: string
+
+  // Boundaries - define the top and bottom of the fill area
+  upper: FillBoundary
+  lower: FillBoundary
+
+  // Optional range constraints
+  x_range?: [number | null, number | null]
+  y_range?: [number | null, number | null]
+
+  // Conditional fill: only fill where condition is true
+  // Example: where: (x, y_upper, y_lower) => y_upper > y_lower
+  where?: (x: number, y_upper: number, y_lower: number) => boolean
+
+  // Styling
+  fill?: string | FillGradient
+  fill_opacity?: number
+  edge_upper?: FillEdgeStyle
+  edge_lower?: FillEdgeStyle
+  curve?: FillCurveType
+  step_position?: number // For step curves: 0 = step, 0.5 = stepMiddle, 1 = stepEnd
+
+  // Rendering
+  z_index?: LayerZIndex
+  visible?: boolean
+
+  // Interactions
+  hover_style?: FillHoverStyle
+  on_click?: (event: FillHandlerEvent) => void
+  on_hover?: (event: FillHandlerEvent | null) => void
+
+  // Legend
+  show_in_legend?: boolean
+  legend_group?: string
+
+  // Metadata for user data
+  metadata?: Record<string, unknown>
+}
+
+// Convenience type for error bands (symmetric or asymmetric around a series)
+export interface ErrorBand {
+  // Reference to the central series
+  series:
+    | { type: `series`; series_idx: number }
+    | {
+        type: `series`
+        series_id: string | number
+      }
+
+  // Error values - can be symmetric (single value/array) or asymmetric (upper/lower)
+  error:
+    | number // Symmetric constant error
+    | readonly number[] // Symmetric per-point error
+    | { upper: number | readonly number[]; lower: number | readonly number[] } // Asymmetric
+
+  // Styling (defaults applied if not specified)
+  fill?: string // Defaults to series color with reduced opacity
+  fill_opacity?: number // Defaults to 0.3
+  edge_style?: FillEdgeStyle
+
+  // Identity
+  id?: string | number
+  label?: string
+  show_in_legend?: boolean
+}
+
+// Reference line styling
+export interface RefLineStyle {
+  color?: string // default: 'currentColor'
+  width?: number // default: 1
+  dash?: string // SVG stroke-dasharray, default: none (solid)
+  opacity?: number // default: 1
+}
+
+// Annotation/label for reference lines
+export interface RefLineAnnotation {
+  text: string
+  position?: `start` | `center` | `end` // position along the line
+  side?: `above` | `below` | `left` | `right` // which side of line
+  offset?: { x?: number; y?: number }
+  gap?: number // pixels between line and annotation text, default: 8
+  edge_padding?: number // pixels inward from plot edge at start/end, default: 4
+  font_size?: string
+  font_family?: string
+  color?: string
+  background?: string
+  padding?: number
+  rotate?: boolean // rotate text to follow line angle
+}
+
+// Event type for reference line interactions
+export interface RefLineEvent {
+  event: MouseEvent | KeyboardEvent | FocusEvent
+  line_idx: number
+  line_id?: string | number
+  type: RefLine[`type`]
+  label?: string
+  metadata?: Record<string, unknown>
+}
+
+// Base properties shared by all reference line types
+export interface RefLineBase {
+  id?: string | number
+  x_span?: [number | null, number | null]
+  y_span?: [number | null, number | null]
+  coord_mode?: `data` | `relative` // default: 'data'
+  x_axis?: `x1` | `x2` // for vertical lines with dual x-axes
+  y_axis?: `y1` | `y2` // for horizontal lines with dual y-axes
+  style?: RefLineStyle
+  annotation?: RefLineAnnotation
+  z_index?: LayerZIndex
+  visible?: boolean
+  hover_style?: RefLineStyle
+  on_click?: (event: RefLineEvent) => void
+  on_hover?: (event: RefLineEvent | null) => void
+  show_in_legend?: boolean
+  label?: string
+  legend_group?: string
+  metadata?: Record<string, unknown>
+}
+
+// Reference line value type - supports numbers, Dates, and ISO date strings
+export type RefLineValue = number | Date | string
+
+// Flat discriminated union - type determines required fields
+export type RefLine = RefLineBase &
+  (
+    | { type: `horizontal`; y: RefLineValue }
+    | { type: `vertical`; x: RefLineValue }
+    | { type: `diagonal`; slope: number; intercept: number }
+    | {
+        type: `segment`
+        p1: [RefLineValue, RefLineValue]
+        p2: [RefLineValue, RefLineValue]
+      }
+    | { type: `line`; p1: [RefLineValue, RefLineValue]; p2: [RefLineValue, RefLineValue] }
+  )
+
+// Default style values for reference lines
+export const REF_LINE_STYLE_DEFAULTS: Required<RefLineStyle> = {
+  color: `currentColor`,
+  width: 1,
+  dash: ``,
+  opacity: 1,
+} as const
+
+type Ref3DBase = Omit<
+  RefLineBase,
+  | `coord_mode`
+  | `x_axis`
+  | `y_axis`
+  | `style`
+  | `hover_style`
+  | `annotation`
+  | `on_click`
+  | `on_hover`
+> & {
+  z_span?: [number | null, number | null]
+}
+
+// Base properties shared by all 3D reference line types
+// Aligned with RefLineBase for future feature parity (interactions, annotations, etc.)
+export interface RefLine3DBase extends Ref3DBase {
+  style?: RefLineStyle
+  hover_style?: RefLineStyle
+  annotation?: RefLineAnnotation
+  on_click?: (event: { line_idx: number; line_id?: string | number }) => void
+  on_hover?: (event: { line_idx: number; line_id?: string | number } | null) => void
+}
+
+// 3D reference line - discriminated union
+export type RefLine3D = RefLine3DBase &
+  (
+    | { type: `x-axis`; y: number; z: number } // line parallel to x-axis
+    | { type: `y-axis`; x: number; z: number } // line parallel to y-axis
+    | { type: `z-axis`; x: number; y: number } // line parallel to z-axis
+    | { type: `segment`; p1: Vec3; p2: Vec3 }
+    | { type: `line`; p1: Vec3; p2: Vec3 }
+  )
+
+// 3D reference plane styling
+export interface RefPlaneStyle {
+  color?: string
+  opacity?: number
+  wireframe?: boolean
+  wireframe_color?: string
+  double_sided?: boolean
+}
+
+// Base properties shared by all 3D reference plane types
+export interface RefPlaneBase extends Ref3DBase {
+  style?: RefPlaneStyle
+}
+
+// 3D reference plane - discriminated union
+export type RefPlane = RefPlaneBase &
+  (
+    | { type: `xy`; z: number } // horizontal plane at z
+    | { type: `xz`; y: number } // vertical plane at y
+    | { type: `yz`; x: number } // vertical plane at x
+    | { type: `normal`; normal: Vec3; point: Vec3 }
+    | { type: `points`; p1: Vec3; p2: Vec3; p3: Vec3 } // plane through 3 points
+  )
+
+// --- Data Cleaning Types ---
+
+// Oscillation detection weights (all default to 1.0)
+export interface OscillationWeights {
+  derivative_variance?: number // Weight for derivative variance method
+  amplitude_growth?: number // Weight for exponential amplitude growth
+  sign_changes?: number // Weight for derivative sign change frequency
+}
+
+// How to handle invalid values (NaN, Infinity)
+export type InvalidValueMode = `remove` | `propagate` | `interpolate`
+
+// Truncation strategy when instability detected
+export type TruncationMode = `hard_cut` | `mark_unstable`
+
+// Physical bounds configuration
+export interface PhysicalBounds {
+  min?: number | ((x: number) => number) // Static or x-dependent minimum
+  max?: number | ((x: number) => number) // Static or x-dependent maximum
+  mode?: `clamp` | `filter` | `null` // How to handle violations
+}
+
+// Smoothing algorithm configuration (discriminated union for type safety)
+export type SmoothingConfig =
+  | { type: `moving_avg`; window: number }
+  | { type: `savgol`; window: number; polynomial_order?: number } // window must be odd
+  | { type: `gaussian`; sigma: number } // sigma controls Gaussian kernel width
+
+// Local outlier detection config (sliding window approach)
+export interface LocalOutlierConfig {
+  window_half?: number // Points on each side for local context (default: 7)
+  mad_threshold?: number // MADs from local median to flag outlier (default: 2.0)
+  max_iterations?: number // Iterative passes to catch clustered outliers (default: 5)
+}
+
+// Result of local outlier detection
+export interface LocalOutlierResult {
+  kept_indices: number[]
+  removed_indices: number[]
+  iterations_used: number
+}
+
+// Main cleaning configuration
+export interface CleaningConfig {
+  // Oscillation detection
+  oscillation_threshold?: number // Combined score threshold (default: 3.0)
+  oscillation_weights?: OscillationWeights // Method weights
+  window_size?: number // Rolling window for detection (default: 5)
+
+  // Data handling
+  invalid_values?: InvalidValueMode // NaN/Infinity handling (default: 'remove')
+  bounds?: PhysicalBounds // Physical constraints
+  smooth?: SmoothingConfig // Optional smoothing
+  local_outliers?: LocalOutlierConfig // Local sliding window outlier removal
+
+  // Truncation
+  truncation_mode?: TruncationMode // 'hard_cut' or 'mark_unstable' (default: 'mark_unstable')
+
+  // Performance
+  in_place?: boolean // Mutate input arrays (default: true)
+}
+
+// Quality report from cleaning operation
+export interface CleaningQuality {
+  points_removed: number
+  invalid_values_found: number // NaN/Infinity count
+  oscillation_detected: boolean
+  oscillation_score?: number // Combined weighted score
+  bounds_violations: number
+  outliers_removed?: number // Count of local outliers removed
+  stable_range?: Vec2 // [start_x, end_x] if mark_unstable mode
+  truncated_at_x?: number // x value if hard_cut mode
+}
+
+// Result of a cleaning operation
+export interface CleaningResult<T = DataSeries> {
+  series: T // Cleaned data (same ref if in_place)
+  quality: CleaningQuality
+}
+
+// Instability detection result
+export interface InstabilityResult {
+  detected: boolean
+  onset_index: number
+  onset_x: number
+  combined_score: number
+  method_scores: {
+    derivative_variance: number
+    amplitude_growth: number
+    sign_changes: number
+  }
+}