matterviz 0.3.7 → 0.4.1

package/dist/plot/{ScatterPlot.svelte → scatter/ScatterPlot.svelte}

@@ -2,15 +2,15 @@
   lang="ts"
   generics="Metadata extends Record<string, unknown> = Record<string, unknown>"
 >
-  import type { D3ColorSchemeName, D3InterpolateName } from '../colors'
-  import type { D3SymbolName } from '../labels'
-  import { format_value, symbol_names } from '../labels'
-  import { sanitize_html } from '../sanitize'
-  import { FullscreenToggle, set_fullscreen_bg } from '../layout'
-  import type { Point2D, Vec2 } from '../math'
+  import type { D3InterpolateName } from '../../colors'
+  import { format_value } from '../../labels'
+  import { sanitize_html } from '../../sanitize'
+  import { FullscreenToggle, set_fullscreen_bg } from '../../layout'
+  import type { Point2D, Vec2 } from '../../math'
   import type {
     AxisLoadError,
     BasePlotProps,
+    ColorScaleConfig,
     ControlsConfig,
     DataLoaderFn,
     DataSeries,
@@ -18,7 +18,6 @@
     FillHandlerEvent,
     FillRegion,
     HoverConfig,
-    InitialRanges,
     InternalPoint,
     LabelPlacementConfig,
     LegendConfig,
@@ -27,12 +26,12 @@
     Point,
     RefLine,
     RefLineEvent,
-    ScaleType,
     ScatterHandlerEvent,
     ScatterHandlerProps,
+    SizeScaleConfig,
     StyleOverrides,
     UserContentProps,
-  } from './'
+  } from '..'
   import {
     ColorBar,
     compute_element_placement,
@@ -47,86 +46,71 @@
     ScatterPoint,
     ZeroLines,
     ZoomRect,
-  } from './'
+  } from '..'
   import {
     build_obstacles_norm,
     has_explicit_position,
     measured_footprint,
     place_decorations,
-  } from './auto-place'
-  import type { AxisChangeState } from './axis-utils'
-  import { create_axis_change_handler } from './axis-utils'
-  import {
-    get_series_color,
-    get_series_symbol,
-    process_prop,
-  } from './data-transform'
-  import { AXIS_DEFAULTS } from './defaults'
-  import {
-    create_dimension_tracker,
-    create_hover_lock,
-  } from './hover-lock.svelte'
+  } from '../core/auto-place'
+  import type { AxisChangeState } from '../core/axis-utils'
+  import { AXIS_DEFAULTS, create_axis_loader } from '../core/axis-utils'
+  import { get_series_color, get_series_symbol } from '../core/data-transform'
+  import { create_placed_tween } from '../core/placed-tween.svelte'
   import {
     DEFAULT_MARKERS,
     get_scale_type_name,
     is_time_scale,
-  } from './types'
-  import { compute_label_positions } from './utils/label-placement'
-  import type { SeriesVisibilitySnapshot } from './utils/series-visibility'
-  import {
-    handle_legend_double_click,
-    toggle_group_visibility,
-    toggle_series_visibility,
-  } from './utils/series-visibility'
-  import { DEFAULTS } from '../settings'
+  } from '../core/types'
+  import { compute_label_positions } from '../core/utils/label-placement'
+  import { create_legend_visibility } from '../core/utils/series-visibility'
+  import { DEFAULTS } from '../../settings'
   import { extent } from 'd3-array'
   import { scaleTime } from 'd3-scale'
   import type { ComponentProps, Snippet } from 'svelte'
-  import { untrack } from 'svelte'
+  import { onDestroy, untrack } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
-  import { Tween, type TweenOptions } from 'svelte/motion'
+  import type { TweenOptions } from 'svelte/motion'
   import { SvelteSet } from 'svelte/reactivity'
-  import type { FillPathPoint } from './fill-utils'
+  import type { Pt } from '../core/fill-utils'
   import {
-    apply_range_constraints,
-    apply_where_condition,
-    clamp_for_log_scale,
+    compute_fill_segments,
     convert_error_band_to_fill_region,
     generate_fill_path,
-    is_fill_gradient,
-    resolve_boundary,
-  } from './fill-utils'
+  } from '../core/fill-utils'
   import {
     expand_range_if_needed,
     get_relative_coords,
+    invert_rect_range,
     normalize_y2_sync,
-    pan_range,
-    PINCH_ZOOM_THRESHOLD,
-    pixels_to_data_delta,
     sync_y2_range,
-  } from './interactions'
-  import type { Rect, Sides } from './layout'
+  } from '../core/interactions'
+  import { create_pan_zoom } from '../core/pan-zoom.svelte'
+  import type { Rect, Sides } from '../core/layout'
   import {
     calc_auto_padding,
-    constrain_tooltip_position,
     filter_padding,
     LABEL_GAP_DEFAULT,
+    y2_axis_label_x,
     measure_full_footprint,
     measure_max_tick_width,
     sample_series_obstacle_points,
-  } from './layout'
-  import type { IndexedRefLine } from './reference-line'
-  import { group_ref_lines_by_z, index_ref_lines } from './reference-line'
+  } from '../core/layout'
+  import type { IndexedRefLine } from '../core/reference-line'
+  import { group_ref_lines_by_z, index_ref_lines } from '../core/reference-line'
   import {
     create_color_scale,
     create_scale,
     create_size_scale,
     generate_ticks,
     get_nice_data_range,
-  } from './scales'
-
-  const in_range = (val: number | null | undefined, lo: number, hi: number) =>
-    val != null && !isNaN(val) && val >= Math.min(lo, hi) && val <= Math.max(lo, hi)
+  } from '../core/scales'
+  import { resolve_line_tween, unique_id } from '../core/utils'
+  import {
+    build_legend_data,
+    filter_series_to_ranges,
+    pick_tooltip_bg,
+  } from './scatter-data'
 
   let {
     series = $bindable([]),
@@ -201,16 +185,8 @@
     change?: (
       data: (Point<Metadata> & { series: DataSeries<Metadata> }) | null,
     ) => void
-    color_scale?: {
-      type?: ScaleType
-      scheme?: D3ColorSchemeName | D3InterpolateName
-      value_range?: [number, number]
-    } | D3InterpolateName
-    size_scale?: {
-      type?: ScaleType
-      radius_range?: [number, number]
-      value_range?: [number, number]
-    }
+    color_scale?: ColorScaleConfig | D3InterpolateName
+    size_scale?: SizeScaleConfig
     color_bar?:
       | (ComponentProps<typeof ColorBar> & {
         margin?: number | Sides
@@ -285,13 +261,12 @@
 
   let [width, height] = $state([0, 0])
   let svg_element: SVGElement | null = $state(null) // Bind the SVG element
-  let svg_bounding_box: DOMRect | null = $state(null) // Store SVG bounds during drag
 
   // Track which specific control properties user has modified
   let touched = new SvelteSet<string>()
 
   // Unique component ID to avoid clipPath conflicts between multiple instances
-  let component_id = $state(`scatter-${crypto.randomUUID()}`)
+  let component_id = $state(unique_id(`scatter`))
   let clip_path_id = $derived(`plot-area-clip-${component_id}`)
 
   // Assign stable IDs to series for keying
@@ -304,20 +279,15 @@
     }),
   )
 
-  // State for rectangle zoom selection
-  let drag_start_coords = $state<Point2D | null>(null)
-  let drag_current_coords = $state<Point2D | null>(null)
-
   // Zoom/pan state - track both initial (data-driven) and current (after pan/zoom) ranges
-  let initial_x_range = $state<[number, number]>([0, 1])
-  let initial_x2_range = $state<[number, number]>([0, 1])
-  let initial_y_range = $state<[number, number]>([0, 1])
-  let initial_y2_range = $state<[number, number]>([0, 1])
-  let zoom_x_range = $state<[number, number]>([0, 1])
-  let zoom_x2_range = $state<[number, number]>([0, 1])
-  let zoom_y_range = $state<[number, number]>([0, 1])
-  let zoom_y2_range = $state<[number, number]>([0, 1])
-  let prev_series_visibility: SeriesVisibilitySnapshot | null = $state(null)
+  let ranges = $state<{
+    initial: { x: Vec2; x2: Vec2; y: Vec2; y2: Vec2 }
+    current: { x: Vec2; x2: Vec2; y: Vec2; y2: Vec2 }
+  }>({
+    initial: { x: [0, 1], x2: [0, 1], y: [0, 1], y2: [0, 1] },
+    current: { x: [0, 1], x2: [0, 1], y: [0, 1], y2: [0, 1] },
+  })
+  const legend_vis = create_legend_visibility(() => series, (next) => (series = next))
 
   // Y2 axis sync configuration
   let y2_sync_config = $derived(normalize_y2_sync(y2_axis?.sync))
@@ -327,7 +297,7 @@
   // Helper to compute synced y2 range or return fallback when sync disabled
   const get_synced_y2 = (y1_range: Vec2, fallback: Vec2): Vec2 =>
     y2_sync_config.mode !== `none`
-      ? sync_y2_range(y1_range, initial_y2_range, y2_sync_config)
+      ? sync_y2_range(y1_range, ranges.initial.y2, y2_sync_config)
       : fallback
 
   // Effect to update y2 range when sync mode changes - use $effect.pre to capture
@@ -338,25 +308,15 @@
     if (mode !== prev_sync_mode) {
       // When sync mode becomes enabled (or changes), apply sync immediately
       if (mode !== `none`) {
-        zoom_y2_range = sync_y2_range(zoom_y_range, initial_y2_range, y2_sync_config)
+        ranges.current.y2 = sync_y2_range(ranges.current.y, ranges.initial.y2, y2_sync_config)
       } else {
         // When switching to independent mode, reset Y2 to its data range
-        zoom_y2_range = [...initial_y2_range] as [number, number]
+        ranges.current.y2 = [...ranges.initial.y2] as Vec2
       }
       prev_sync_mode = mode
     }
   })
 
-  // Pan state
-  let is_focused = $state(false)
-  let shift_held = $state(false)
-  let pan_drag_state = $state<
-    InitialRanges & { start: { x: number; y: number } } | null
-  >(null)
-  let touch_state = $state<
-    InitialRanges & { start_touches: { x: number; y: number }[] } | null
-  >(null)
-
   // Fill region hover state
   let hovered_fill_key = $state<string | null>(null)
 
@@ -378,20 +338,6 @@
   // State for legend/colorbar placement stability
   let legend_element = $state<HTMLDivElement | undefined>()
   let colorbar_element = $state<HTMLDivElement | undefined>()
-  const legend_hover = create_hover_lock()
-  const colorbar_hover = create_hover_lock()
-  const dim_tracker = create_dimension_tracker()
-  let has_initial_legend_placement = $state(false)
-  let has_initial_colorbar_placement = $state(false)
-
-  // Clear pending hover lock timeouts on unmount
-  $effect(() => () => {
-    legend_hover.cleanup()
-    colorbar_hover.cleanup()
-  })
-
-  // Tooltip element reference for dynamic sizing
-  let tooltip_el = $state<HTMLDivElement | undefined>()
 
   // Module-level constants to avoid repeated allocations
   // Create and categorize points in a single pass (instead of 3 separate iterations)
@@ -431,7 +377,7 @@
   // Update padding when format or ticks change
   $effect(() => {
     const new_pad = width && height &&
-        (y_tick_values.length || y2_tick_values.length || x2_tick_values.length)
+        (y_tick_values.length > 0 || y2_tick_values.length > 0 || x2_tick_values.length > 0)
       ? calc_auto_padding({
         padding,
         default_padding,
@@ -607,60 +553,52 @@
       return { explicit, range }
     }
 
-    const x = get_range(final_x_axis, auto_x_range)
-    const x2 = get_range(final_x2_axis, auto_x2_range)
-    const y = get_range(final_y_axis, auto_y_range)
-    const y2 = get_range(final_y2_axis, auto_y2_range)
-
-    // X axis: explicit → direct, auto → lazy expand
-    if (x.explicit) {
-      zoom_x_range = x.range
-    } else {
-      const result = expand_range_if_needed(initial_x_range, x.range)
-      if (result.changed) {
-        ;[initial_x_range, zoom_x_range] = [result.range, result.range]
-      }
-    }
-
-    // X2 axis: explicit → direct, auto → lazy expand
-    if (x2.explicit) {
-      zoom_x2_range = x2.range
-    } else {
-      const result = expand_range_if_needed(initial_x2_range, x2.range)
-      if (result.changed) {
-        ;[initial_x2_range, zoom_x2_range] = [result.range, result.range]
-      }
+    const resolved = {
+      x: get_range(final_x_axis, auto_x_range),
+      x2: get_range(final_x2_axis, auto_x2_range),
+      y: get_range(final_y_axis, auto_y_range),
+      y2: get_range(final_y2_axis, auto_y2_range),
     }
 
-    // Y axis: explicit → direct, auto → lazy expand
-    if (y.explicit) {
-      zoom_y_range = y.range
-    } else {
-      const result = expand_range_if_needed(initial_y_range, y.range)
-      if (result.changed) {
-        ;[initial_y_range, zoom_y_range] = [result.range, result.range]
+    // untrack reads of `ranges`: this effect also writes it, and tracked reads of the
+    // deep proxy would re-trigger the effect on every current/initial write
+    for (const axis of [`x`, `x2`, `y`] as const) {
+      const { explicit, range } = resolved[axis]
+      if (explicit) {
+        ranges.current[axis] = range
+      } else {
+        const result = expand_range_if_needed(untrack(() => ranges.initial[axis]), range)
+        if (result.changed) {
+          ranges.initial[axis] = result.range
+          ranges.current[axis] = result.range
+        }
       }
     }
 
     // Y2 axis: explicit → direct, else expand initial range then optionally sync
-    if (y2.explicit) {
-      zoom_y2_range = y2.range
+    if (resolved.y2.explicit) {
+      ranges.current.y2 = resolved.y2.range
     } else {
-      const result = expand_range_if_needed(initial_y2_range, y2.range)
-      if (result.changed) initial_y2_range = result.range
+      const result = expand_range_if_needed(untrack(() => ranges.initial.y2), resolved.y2.range)
+      if (result.changed) ranges.initial.y2 = result.range
       // Apply sync if enabled, otherwise use expanded range (or keep current if unchanged)
       if (y2_sync_config.mode !== `none`) {
-        zoom_y2_range = sync_y2_range(zoom_y_range, initial_y2_range, y2_sync_config)
+        // Pan/zoom handlers sync y2 themselves.
+        ranges.current.y2 = sync_y2_range(
+          untrack(() => ranges.current.y),
+          untrack(() => ranges.initial.y2),
+          y2_sync_config,
+        )
       } else if (result.changed) {
-        zoom_y2_range = result.range
+        ranges.current.y2 = result.range
       }
     }
   })
 
-  let [x_min, x_max] = $derived(zoom_x_range)
-  let [x2_min, x2_max] = $derived(zoom_x2_range)
-  let [y_min, y_max] = $derived(zoom_y_range)
-  let [y2_min, y2_max] = $derived(zoom_y2_range)
+  let [x_min, x_max] = $derived(ranges.current.x)
+  let [x2_min, x2_max] = $derived(ranges.current.x2)
+  let [y_min, y_max] = $derived(ranges.current.y)
+  let [y2_min, y2_max] = $derived(ranges.current.y2)
 
   // Create auto color range
   let auto_color_range = $derived(
@@ -723,80 +661,29 @@
 
   // Filter series data to only include points within bounds and augment with internal data
   let filtered_series = $derived(
-    series_with_ids
-      .map((data_series: DataSeries<Metadata>, series_idx): DataSeries<Metadata> => {
-        // Handle null/undefined series first
-        if (!data_series) {
-          return {
-            x: [],
-            y: [],
-            visible: true,
-            filtered_data: [],
-            _id: series_idx,
-            orig_series_idx: series_idx,
-          }
-        }
-
-        // Handle explicitly hidden series
-        if (!(data_series.visible ?? true)) {
-          return {
-            ...data_series,
-            visible: false,
-            filtered_data: [],
-            orig_series_idx: series_idx,
-          }
-        }
-
-        const { x: xs, y: ys, color_values, size_values, ...series_rest } = data_series
-
-        // Process points internally, adding properties beyond the base Point type
-        const processed_points: InternalPoint<Metadata>[] = xs.map(
-          (x_val: number, point_idx: number) => ({
-            x: x_val,
-            y: ys[point_idx],
-            color_value: color_values?.[point_idx],
-            metadata: process_prop(series_rest.metadata, point_idx) as Metadata | undefined,
-            point_style: process_prop(series_rest.point_style, point_idx),
-            point_hover: process_prop(series_rest.point_hover, point_idx),
-            point_label: process_prop(series_rest.point_label, point_idx),
-            point_offset: process_prop(series_rest.point_offset, point_idx),
-            series_idx,
-            point_idx,
-            size_value: size_values?.[point_idx],
-          }),
-        )
-
-        // Filter to points within the plot bounds (handles inverted ranges like [3.5, 1.4])
-        // Determine which ranges to use based on series axis properties
-        const [series_x_min, series_x_max] = (data_series.x_axis ?? `x1`) === `x2`
-          ? [x2_min, x2_max]
-          : [x_min, x_max]
-        const [series_y_min, series_y_max] = (data_series.y_axis ?? `y1`) === `y2`
-          ? [y2_min, y2_max]
-          : [y_min, y_max]
-
-        const filtered_data_with_extras = processed_points.filter(
-          ({ x, y }) =>
-            in_range(x, series_x_min, series_x_max) &&
-            in_range(y, series_y_min, series_y_max),
-        )
-
-        // Return structure consistent with DataSeries but acknowledge internal data structure (filtered_data)
-        return {
-          ...data_series,
-          visible: true, // Mark series as visible here
-          filtered_data: filtered_data_with_extras,
-          orig_series_idx: series_idx, // Store original index for auto-cycling colors/symbols
-        }
-      })
-      // Filter series end up completely empty after point filtering
-      .filter((
-        srs,
-      ): srs is DataSeries<Metadata> & { filtered_data: InternalPoint<Metadata>[] } =>
-        !!srs.filtered_data && srs.filtered_data.length > 0
-      ),
+    filter_series_to_ranges(series_with_ids, {
+      x: [x_min, x_max],
+      x2: [x2_min, x2_max],
+      y: [y_min, y_max],
+      y2: [y2_min, y2_max],
+    }),
   )
 
+  // Tally line series/points to budget path-morph tweens (see resolve_line_tween).
+  // Disabling the morph for high-cardinality plots (e.g. phonon bands) keeps them
+  // snappy; Line.svelte short-circuits the Tween when duration <= 0.
+  let line_tween_load = $derived.by(() => {
+    if (!styles.show_lines) return { series: 0, points: 0 }
+    let [n_series, n_points] = [0, 0]
+    for (const srs of filtered_series ?? []) {
+      if (!(srs.markers ?? DEFAULT_MARKERS).includes(`line`)) continue
+      n_series += 1
+      n_points += srs.x.length
+    }
+    return { series: n_series, points: n_points }
+  })
+  let effective_line_tween = $derived(resolve_line_tween(line_tween, line_tween_load))
+
   // Obstacle field for legend/colorbar auto-placement. Sampling only data points lets the
   // legend land on top of a steep connecting line whose markers are sparse (e.g. y=x^2), so
   // sample_series_obstacle_points also walks each drawn segment at a fixed pixel cadence.
@@ -824,14 +711,6 @@
     return points
   })
 
-  // Explicitly define the type for display_style matching PlotLegend expectations
-  type LegendDisplayStyle = {
-    symbol_type?: D3SymbolName
-    symbol_color?: string
-    line_color?: string
-    line_dash?: string
-  }
-
   const fill_hover_key = (
     source_type: `fill_region` | `error_band`,
     source_idx: number,
@@ -894,19 +773,22 @@
       })),
     ]
 
-    // Compute unique x-values once for all fills
-    // Optimization: deduplicate first (O(n)), then sort only unique values (O(k log k))
-    // This is faster for datasets with many duplicate x-values across series
-    const x_set = new SvelteSet<number>()
-    for (const data_series of series_with_ids) {
-      if (!data_series) continue
-      for (const val of data_series.x) {
-        if (typeof val === `number` && isFinite(val)) x_set.add(val)
-      }
-    }
-    const unique_x = [...x_set].sort((val_a, val_b) => val_a - val_b)
+    // On log axes, clamp non-positive coords to the scale's domain floor (x_min/y_min) before
+    // scaling. A fixed tiny epsilon can sit far below the domain and map to extreme pixel coords.
+    const x_scale_type = final_x_axis.scale_type ?? `linear`
+    const y_scale_type = final_y_axis.scale_type ?? `linear`
+    const to_px = (pt: Pt): Pt => ({
+      x: x_scale_fn(x_scale_type === `log` && pt.x <= 0 ? x_min : pt.x),
+      y: y_scale_fn(y_scale_type === `log` && pt.y <= 0 ? y_min : pt.y),
+    })
 
-    if (unique_x.length === 0) return []
+    // Each boundary is traced through its own points with the same curve the series line uses,
+    // so fill edges coincide exactly with the lines they border (x_domain anchors flat boundaries).
+    const domains = {
+      x_domain: [x_min, x_max] as Vec2,
+      y_domain: [y_min, y_max] as Vec2,
+      y2_domain: [y2_min, y2_max] as Vec2,
+    }
 
     return all_regions
       .filter((
@@ -918,71 +800,24 @@
         hover_key: string
       } => entry.region !== null)
       .map(({ region, source_type, source_idx, hover_key }, idx) => {
-        if (region.visible === false) return null
-
-        // Domain context for boundary resolution
-        const domains = {
-          y_domain: [y_min, y_max] as Vec2,
-          y2_domain: [y2_min, y2_max] as Vec2,
-        }
-
-        // Resolve upper and lower boundaries
-        const upper_values = resolve_boundary(
-          region.upper,
-          series_with_ids,
-          unique_x,
-          domains,
-        )
-        const lower_values = resolve_boundary(
-          region.lower,
-          series_with_ids,
-          unique_x,
-          domains,
-        )
-
-        if (!upper_values || !lower_values) return null
-
-        // Apply range constraints
-        const range_filtered = apply_range_constraints(
-          unique_x,
-          lower_values,
-          upper_values,
-          region,
-        )
-
-        // Clamp for log scale if needed
-        const y_scale_type = final_y_axis.scale_type ?? `linear`
-        const x_scale_type = final_x_axis.scale_type ?? `linear`
-        const clamped = clamp_for_log_scale(
-          range_filtered.x,
-          range_filtered.y1,
-          range_filtered.y2,
-          y_scale_type,
-          x_scale_type,
-        )
-
-        // Apply where condition (splits into segments)
-        const conditioned = apply_where_condition(
-          clamped.x,
-          clamped.y1,
-          clamped.y2,
-          region,
-        )
-
-        // Generate paths for each segment (convert to pixel coordinates)
-        const path_segments = conditioned.segments
-          .filter((segment) => segment.length > 1)
-          .map((segment) => {
-            const pixel_data: FillPathPoint[] = segment.map((point) => ({
-              x: x_scale_fn(point.x),
-              y1: y_scale_fn(point.y1),
-              y2: y_scale_fn(point.y2),
-            }))
-            return generate_fill_path(pixel_data, region.curve ?? `monotoneX`)
-          })
-          .filter((path) => path.length > 0)
+        // Hidden fills keep their entry (with empty path_segments -> nothing renders) so the
+        // legend item persists greyed-out and can be toggled back on.
+        const hidden = region.visible === false
+        const path_segments = hidden
+          ? []
+          : compute_fill_segments(region, series_with_ids, domains)
+            .map((seg) =>
+              generate_fill_path(
+                seg.upper.map(to_px),
+                seg.lower.map(to_px),
+                seg.upper_curve,
+                seg.lower_curve,
+              )
+            )
+            .filter((path) => path.length > 0)
 
-        if (path_segments.length === 0) return null
+        // Drop only visible fills with no geometry; keep hidden ones for the legend
+        if (!hidden && path_segments.length === 0) return null
 
         return { ...region, idx, source_type, source_idx, hover_key, path_segments }
       })
@@ -990,161 +825,9 @@
   })
 
   // Prepare data needed for the legend component
-  let legend_data = $derived.by(() => {
-    const items = series_with_ids.map(
-      (data_series: DataSeries & { _id?: string | number }, series_idx: number) => {
-        const is_visible = data_series?.visible ?? true
-        // Prefer top-level label, fallback to metadata label
-        const explicit_label = data_series?.label ??
-          (typeof data_series?.metadata === `object` &&
-              data_series.metadata !== null &&
-              `label` in data_series.metadata &&
-              typeof data_series.metadata.label === `string`
-            ? data_series.metadata.label
-            : null)
-        // Use explicit label or generate default
-        const label = explicit_label ?? `Series ${series_idx + 1}`
-        const has_explicit_label = explicit_label != null
-
-        // Use series-specific defaults for auto-differentiation
-        const series_default_color = get_series_color(series_idx)
-        const series_default_symbol = get_series_symbol(series_idx)
-
-        const display_style: LegendDisplayStyle = {
-          symbol_type: series_default_symbol,
-          symbol_color: series_default_color,
-          line_color: series_default_color,
-        }
-        const series_markers = data_series?.markers ?? DEFAULT_MARKERS
-
-        // Check point_style (could be object or array)
-        const first_point_style = Array.isArray(data_series?.point_style)
-          ? data_series.point_style[0]
-          : data_series?.point_style
-
-        if (series_markers?.includes(`points`)) {
-          if (first_point_style) {
-            // Use explicit symbol_type if provided and valid, otherwise keep series default
-            if (
-              typeof first_point_style.symbol_type === `string` &&
-              symbol_names.includes(first_point_style.symbol_type as D3SymbolName)
-            ) {
-              display_style.symbol_type = first_point_style
-                .symbol_type as D3SymbolName
-            }
-
-            // Use explicit fill color if provided
-            if (first_point_style.fill) {
-              display_style.symbol_color = first_point_style.fill
-            }
-            if (first_point_style.stroke) {
-              // Use stroke color if fill is none or transparent
-              if (
-                !display_style.symbol_color ||
-                display_style.symbol_color === `none` ||
-                display_style.symbol_color.startsWith(`rgba(`, 0) // Check if transparent
-              ) display_style.symbol_color = first_point_style.stroke
-            }
-          }
-          // else: keep series-specific defaults for symbol_type and symbol_color
-        } else {
-          // If no points marker, explicitly remove marker style for legend
-          display_style.symbol_type = undefined
-          display_style.symbol_color = undefined
-        }
-
-        // Check line_style
-        if (series_markers?.includes(`line`)) {
-          // Prefer explicit line stroke, then other explicit colors, then series default
-          let legend_line_color = data_series?.line_style?.stroke
-          if (!legend_line_color) {
-            // Try color scale if available
-            const first_cv = Array.isArray(data_series?.color_values)
-              ? data_series?.color_values?.find((color_val: number | null) =>
-                color_val != null
-              )
-              : undefined
-            legend_line_color =
-              (first_cv != null ? color_scale_fn(first_cv) : undefined) ||
-              first_point_style?.fill ||
-              first_point_style?.stroke ||
-              series_default_color
-          }
-          display_style.line_color = legend_line_color
-          display_style.line_dash = data_series?.line_style?.line_dash
-        } else {
-          // If no line marker, explicitly remove line style for legend
-          display_style.line_dash = undefined
-          display_style.line_color = undefined
-        }
-
-        return {
-          series_idx,
-          label,
-          visible: is_visible,
-          display_style,
-          has_explicit_label,
-          legend_group: data_series?.legend_group,
-        }
-      },
-    )
-
-    // Deduplicate by label+legend_group - keep first occurrence of each unique combination
-    const seen_labels = new SvelteSet<string>()
-    const series_items = items.filter(
-      (
-        legend_item: {
-          label: string
-          series_idx: number
-          visible: boolean
-          display_style: LegendDisplayStyle
-          has_explicit_label: boolean
-          legend_group?: string
-        },
-      ) => {
-        // Use label+group as unique key (group may be undefined)
-        const unique_key = `${legend_item.legend_group ?? ``}::${legend_item.label}`
-        if (seen_labels.has(unique_key)) return false
-        seen_labels.add(unique_key)
-        return true
-      },
-    )
-
-    // Add fill region items to legend (deduplicated using same key format as series)
-    const fill_items = computed_fills
-      .filter((fill) => fill.show_in_legend !== false && fill.label)
-      .filter((fill) => {
-        // Use same composite key as series: legend_group::label
-        const unique_key = `${fill.legend_group ?? ``}::${fill.label ?? ``}`
-        if (seen_labels.has(unique_key)) return false
-        seen_labels.add(unique_key)
-        return true
-      })
-      .map((fill) => {
-        // Pass gradient for swatch rendering, or solid color as fallback
-        const fill_gradient = is_fill_gradient(fill.fill) ? fill.fill : undefined
-        const fill_color = typeof fill.fill === `string` ? fill.fill : undefined
-
-        return {
-          series_idx: -1, // Not a series
-          fill_idx: fill.idx,
-          fill_source_type: fill.source_type,
-          fill_source_idx: fill.source_idx,
-          item_type: `fill` as const,
-          label: fill.label ?? ``,
-          visible: fill.visible !== false,
-          legend_group: fill.legend_group,
-          display_style: {
-            fill_color,
-            fill_opacity: fill.fill_opacity ?? 0.3,
-            edge_color: fill.edge_upper?.color,
-            fill_gradient,
-          },
-        }
-      })
-
-    return [...series_items, ...fill_items]
-  })
+  let legend_data = $derived(
+    build_legend_data(series_with_ids, computed_fills, color_scale_fn),
+  )
 
   // Group fills by z-index for ordered rendering (single pass instead of 4 filters)
   let fills_by_z = $derived.by(() => {
@@ -1171,7 +854,7 @@
   // Calculate best legend placement using continuous grid sampling
   let legend_placement = $derived.by(() => {
     const should_place = legend != null &&
-      (legend_data.length > 1 || Object.keys(legend).length > 0)
+      (legend_data.length > 1 || Object.keys(legend ?? {}).length > 0)
 
     if (!should_place || !width || !height) return null
 
@@ -1192,7 +875,7 @@
 
   // Calculate color bar placement (coordinates with legend to avoid overlap)
   let color_bar_placement = $derived.by(() => {
-    if (!color_bar || !all_color_values.length || !width || !height) return null
+    if (!color_bar || all_color_values.length === 0 || !width || !height) return null
 
     const plot_width = width - pad.l - pad.r
     const plot_height = height - pad.t - pad.b
@@ -1242,60 +925,23 @@
     return legend_placement
   })
 
-  // Initialize tweened values for color bar position - create once, update target via effect
-  // untrack() explicitly captures initial tween config (intentional - config set once at mount)
-  const tweened_colorbar_coords = new Tween(
-    { x: 0, y: 0 },
-    untrack(() => ({ duration: 400, ...color_bar?.tween })),
-  )
-  // Initialize tweened values for legend position - create once, update target via effect
-  const tweened_legend_coords = new Tween(
-    { x: 0, y: 0 },
-    untrack(() => ({ duration: 400, ...legend?.tween })),
-  )
-
-  // Update placement positions (with animation and stability checks)
-  $effect(() => {
-    if (!width || !height) return
-
-    // Track dimensions for resize detection
-    const dims_changed = dim_tracker.has_changed(width, height)
-    if (dims_changed) dim_tracker.update(width, height)
-
-    // Update colorbar position (stable after initial placement unless responsive)
-    if (color_bar_placement) {
-      const is_responsive = color_bar?.responsive ?? false
-      const should_update = dims_changed || (!colorbar_hover.is_locked.current &&
-        (is_responsive || !has_initial_colorbar_placement))
-
-      if (should_update) {
-        tweened_colorbar_coords.set(
-          { x: color_bar_placement.x, y: color_bar_placement.y },
-          has_initial_colorbar_placement ? undefined : { duration: 0 },
-        )
-        if (colorbar_element && !has_initial_colorbar_placement) {
-          has_initial_colorbar_placement = true
-        }
-      }
-    }
-
-    // Update legend position (stable after initial placement unless responsive)
-    if (legend_manual_position && !legend_is_dragging) {
-      // Immediate update (no animation) for manually dragged positions
-      tweened_legend_coords.set(legend_manual_position, { duration: 0 })
-    } else if (active_legend_placement && !legend_is_dragging) {
-      const is_responsive = legend?.responsive ?? false
-      const should_update = dims_changed || (!legend_hover.is_locked.current &&
-        (is_responsive || !has_initial_legend_placement))
-
-      if (should_update) {
-        tweened_legend_coords.set(
-          { x: active_legend_placement.x, y: active_legend_placement.y },
-          has_initial_legend_placement ? undefined : { duration: 0 },
-        )
-        if (legend_element) has_initial_legend_placement = true
-      }
-    }
+  // Tweened colorbar/legend coordinates with shared placement stability gating
+  const colorbar_tween = create_placed_tween({
+    placement: () => color_bar_placement,
+    dims: () => ({ width, height }),
+    responsive: () => color_bar?.responsive ?? false,
+    element: () => colorbar_element,
+    tween: () => color_bar?.tween,
+  })
+  const legend_tween = create_placed_tween({
+    placement: () => active_legend_placement,
+    dims: () => ({ width, height }),
+    responsive: () => legend?.responsive ?? false,
+    element: () => legend_element,
+    tween: () => legend?.tween,
+    // Leave coords alone mid-drag; once dragged, the manual position wins permanently
+    suspended: () => legend_is_dragging,
+    manual_position: () => legend_manual_position,
   })
 
   // Generate axis ticks - consolidated into single derived for efficiency
@@ -1361,346 +1007,76 @@
     y2_max: measure_max_tick_width(y2_tick_values, final_y2_axis.format ?? ``),
   })
 
-  // Define global handlers reference for adding/removing listeners
-  const on_window_mouse_move = (evt: MouseEvent) => {
-    if (!drag_start_coords || !svg_bounding_box) return // Exit if not dragging or no bounds
-
-    // Calculate mouse position relative to the stored SVG bounding box
-    const current_x = evt.clientX - svg_bounding_box.left
-    const current_y = evt.clientY - svg_bounding_box.top
-    drag_current_coords = { x: current_x, y: current_y }
-
-    // Optional: update tooltip only if inside SVG bounds
-    const is_inside_svg = current_x >= 0 &&
-      current_x <= svg_bounding_box.width &&
-      current_y >= 0 &&
-      current_y <= svg_bounding_box.height
-
-    if (is_inside_svg) {
-      // Use the already calculated relative coordinates
-      update_tooltip_point(current_x, current_y)
-    } else tooltip_point = null // Clear tooltip if outside
-  }
-
-  const on_window_mouse_up = (_evt: MouseEvent) => {
-    if (drag_start_coords && drag_current_coords) {
-      // Use current scales to invert screen coords to data coords
-      const start_data_x_val = x_scale_fn.invert(drag_start_coords.x)
-      const end_data_x_val = x_scale_fn.invert(drag_current_coords.x)
-      const start_data_y_val = y_scale_fn.invert(drag_start_coords.y)
-      const end_data_y_val = y_scale_fn.invert(drag_current_coords.y)
-
-      // Ensure range is not zero and order is correct
-      let x1: number, x2: number
-      if (start_data_x_val instanceof Date && end_data_x_val instanceof Date) {
-        x1 = start_data_x_val.getTime()
-        x2 = end_data_x_val.getTime()
-      } else if (
-        typeof start_data_x_val === `number` &&
-        typeof end_data_x_val === `number`
-      ) {
-        x1 = start_data_x_val
-        x2 = end_data_x_val
-      } else {
-        console.error(`Mismatched types for x-axis zoom calculation`)
-        // Reset states without zooming if types are wrong
-        drag_start_coords = null
-        drag_current_coords = null
-        window.removeEventListener(`mousemove`, on_window_mouse_move)
-        window.removeEventListener(`mouseup`, on_window_mouse_up)
-        return
-      }
-
-      const next_x_range: [number, number] = [Math.min(x1, x2), Math.max(x1, x2)]
-      // Y axis is always number
-      const next_y_range: [number, number] = [
-        Math.min(start_data_y_val, end_data_y_val),
-        Math.max(start_data_y_val, end_data_y_val),
-      ]
-
-      // Check for minuscule zoom box (e.g. accidental click)
-      const min_zoom_size = 5 // Minimum pixels to trigger zoom
-      const dx = Math.abs(drag_start_coords.x - drag_current_coords.x)
-      const dy = Math.abs(drag_start_coords.y - drag_current_coords.y)
-
-      if (
-        dx > min_zoom_size &&
-        dy > min_zoom_size &&
-        next_x_range[0] !== next_x_range[1] &&
-        next_y_range[0] !== next_y_range[1]
-      ) {
-        // Update axis ranges to trigger reactivity (like BarPlot/Histogram do)
-        // Y2 sync is handled by the effect that reacts to y_axis changes
-        x_axis = { ...x_axis, range: next_x_range }
-        y_axis = { ...y_axis, range: next_y_range }
-
-        // X2 axis: invert screen coords using x2 scale
-        if (x2_points.length > 0) {
-          const start_x2_val = x2_scale_fn.invert(drag_start_coords.x)
-          const end_x2_val = x2_scale_fn.invert(drag_current_coords.x)
-          const x2_a = start_x2_val instanceof Date
-            ? start_x2_val.getTime()
-            : start_x2_val as number
-          const x2_b = end_x2_val instanceof Date
-            ? end_x2_val.getTime()
-            : end_x2_val as number
-          x2_axis = {
-            ...x2_axis,
-            range: [Math.min(x2_a, x2_b), Math.max(x2_a, x2_b)],
-          }
-        }
-      }
-    }
-
-    // Reset states and remove listeners
-    drag_start_coords = null
-    drag_current_coords = null
-    svg_bounding_box = null
-    window.removeEventListener(`mousemove`, on_window_mouse_move)
-    window.removeEventListener(`mouseup`, on_window_mouse_up)
-    document.body.style.cursor = `default`
-  }
-
-  // Pan drag handlers
-  const on_pan_move = (evt: MouseEvent) => {
-    if (!pan_drag_state) return
-    const dx = evt.clientX - pan_drag_state.start.x
-    const dy = evt.clientY - pan_drag_state.start.y
-
-    // Convert pixel delta to data delta (note: drag direction is inverted for natural pan feel)
+  // Shared pan/zoom/touch/drag-rect interaction controller. set_range routes y2
+  // writes through get_synced_y2 (write-order contract: y is written before y2, so
+  // the sync reads the just-updated y range).
+  const pan_zoom = create_pan_zoom({
+    ranges: () => ranges.current,
+    scale_type: (axis) =>
+      ({ x: final_x_axis, x2: final_x2_axis, y: final_y_axis, y2: final_y2_axis })[axis]
+        .scale_type,
     // Clamp to at least 1 to avoid Infinity deltas when padding equals container size
-    const plot_width = Math.max(1, width - pad.l - pad.r)
-    const plot_height = Math.max(1, height - pad.t - pad.b)
-    const sensitivity = pan?.drag_sensitivity ?? 1
-
-    const x_delta = pixels_to_data_delta(
-      -dx * sensitivity,
-      pan_drag_state.initial_x_range,
-      plot_width,
-    )
-    const x2_delta = pixels_to_data_delta(
-      -dx * sensitivity,
-      pan_drag_state.initial_x2_range,
-      plot_width,
-    )
-    const y_delta = pixels_to_data_delta(
-      dy * sensitivity,
-      pan_drag_state.initial_y_range,
-      plot_height,
-    )
-    const y2_delta = pixels_to_data_delta(
-      dy * sensitivity,
-      pan_drag_state.initial_y2_range,
-      plot_height,
-    )
-
-    zoom_x_range = pan_range(pan_drag_state.initial_x_range, x_delta)
-    zoom_x2_range = pan_range(pan_drag_state.initial_x2_range, x2_delta)
-    zoom_y_range = pan_range(pan_drag_state.initial_y_range, y_delta)
-    zoom_y2_range = get_synced_y2(
-      zoom_y_range,
-      pan_range(pan_drag_state.initial_y2_range, y2_delta),
-    )
-  }
-
-  const on_pan_end = () => {
-    pan_drag_state = null
-    document.body.style.cursor = ``
-    window.removeEventListener(`mousemove`, on_pan_move)
-    window.removeEventListener(`mouseup`, on_pan_end)
-  }
-
-  function handle_mouse_down(evt: MouseEvent) {
-    if (!svg_element) return
-
-    // Check if pan is enabled and shift is held for pan mode
-    const pan_enabled = pan?.enabled !== false
-    if (pan_enabled && evt.shiftKey) {
-      evt.preventDefault()
-      pan_drag_state = {
-        start: { x: evt.clientX, y: evt.clientY },
-        initial_x_range: [...zoom_x_range] as [number, number],
-        initial_x2_range: [...zoom_x2_range] as [number, number],
-        initial_y_range: [...zoom_y_range] as [number, number],
-        initial_y2_range: [...zoom_y2_range] as [number, number],
+    plot_dims: () => ({
+      width: Math.max(1, width - pad.l - pad.r),
+      height: Math.max(1, height - pad.t - pad.b),
+    }),
+    pan: () => pan,
+    set_range: (axis, range) => {
+      if (axis === `y2`) ranges.current.y2 = get_synced_y2(ranges.current.y, range)
+      else ranges.current[axis] = range
+    },
+    svg: () => svg_element,
+    on_rect_zoom: (start, current) => {
+      // Update axis ranges to trigger reactivity; both x and y must invert to valid
+      // (finite, non-degenerate) ranges or the rect zoom is discarded entirely
+      const next_x = invert_rect_range(x_scale_fn, start.x, current.x)
+      const next_y = invert_rect_range(y_scale_fn, start.y, current.y)
+      if (!next_x || !next_y) return
+      x_axis = { ...x_axis, range: next_x }
+      y_axis = { ...y_axis, range: next_y }
+
+      // X2 axis: invert screen coords using x2 scale
+      const next_x2 = x2_points.length > 0
+        ? invert_rect_range(x2_scale_fn, start.x, current.x)
+        : null
+      if (next_x2) x2_axis = { ...x2_axis, range: next_x2 }
+
+      // Y2 axis: when sync is enabled the y_axis effect derives y2; with sync 'none'
+      // y2 must zoom from the rect directly (parity with BarPlot/Histogram/BoxPlot)
+      const next_y2 = y2_points.length > 0 && y2_sync_config.mode === `none`
+        ? invert_rect_range(y2_scale_fn, start.y, current.y)
+        : null
+      if (next_y2) y2_axis = { ...y2_axis, range: next_y2 }
+    },
+    on_reset: () => {
+      // Reset to current auto ranges (not stale initial ranges which may have expanded)
+      // This ensures lazy expansion restarts fresh from current data bounds
+      ranges.initial = {
+        x: [...auto_x_range] as Vec2,
+        x2: [...auto_x2_range] as Vec2,
+        y: [...auto_y_range] as Vec2,
+        y2: [...auto_y2_range] as Vec2,
       }
-      document.body.style.cursor = `grabbing`
-      window.addEventListener(`mousemove`, on_pan_move)
-      window.addEventListener(`mouseup`, on_pan_end)
-      return
-    }
-
-    // Store bounding box first, then calculate coords using it
-    svg_bounding_box = svg_element.getBoundingClientRect()
-
-    // Calculate initial coords using the same bounding box that will be used during drag
-    const initial_x = evt.clientX - svg_bounding_box.left
-    const initial_y = evt.clientY - svg_bounding_box.top
-    const coords = { x: initial_x, y: initial_y }
-
-    drag_start_coords = coords
-    drag_current_coords = coords
-
-    window.addEventListener(`mousemove`, on_window_mouse_move)
-    window.addEventListener(`mouseup`, on_window_mouse_up)
-    document.body.style.cursor = `crosshair`
-    evt.preventDefault()
-  }
-
-  // Wheel handler for pan (requires focus and shift)
-  function handle_wheel(evt: WheelEvent) {
-    const pan_enabled = pan?.enabled !== false
-    // Only capture wheel when focused AND Shift is held
-    // Use shift_held state (tracked via keydown/keyup) for compatibility with synthetic events
-    if (!pan_enabled || !is_focused || !shift_held) return
-
-    evt.preventDefault()
-
-    // Clamp to at least 1 to avoid Infinity deltas when padding equals container size
-    const plot_width = Math.max(1, width - pad.l - pad.r)
-    const plot_height = Math.max(1, height - pad.t - pad.b)
-    const sensitivity = pan?.wheel_sensitivity ?? 1
-
-    // Determine pan direction based on wheel delta
-    // deltaX for horizontal scroll (trackpad), deltaY for vertical
-    const x_delta = pixels_to_data_delta(
-      evt.deltaX * sensitivity,
-      zoom_x_range,
-      plot_width,
-    )
-    const x2_delta = pixels_to_data_delta(
-      evt.deltaX * sensitivity,
-      zoom_x2_range,
-      plot_width,
-    )
-    const y_delta = pixels_to_data_delta(
-      evt.deltaY * sensitivity,
-      zoom_y_range,
-      plot_height,
-    )
-    const y2_delta = pixels_to_data_delta(
-      evt.deltaY * sensitivity,
-      zoom_y2_range,
-      plot_height,
-    )
-
-    if (Math.abs(evt.deltaX) > Math.abs(evt.deltaY)) {
-      zoom_x_range = pan_range(zoom_x_range, x_delta)
-      zoom_x2_range = pan_range(zoom_x2_range, x2_delta)
-    } else {
-      zoom_y_range = pan_range(zoom_y_range, y_delta)
-      zoom_y2_range = get_synced_y2(zoom_y_range, pan_range(zoom_y2_range, y2_delta))
-    }
-  }
-
-  // Touch handlers for pinch-zoom and two-finger pan
-  function handle_touch_start(evt: TouchEvent) {
-    const touch_enabled = pan?.enabled !== false && pan?.touch_enabled !== false
-    if (!touch_enabled || evt.touches.length !== 2) return
-
-    evt.preventDefault()
-    const touches = Array.from(evt.touches)
-    touch_state = {
-      start_touches: touches.map((touch) => ({ x: touch.clientX, y: touch.clientY })),
-      initial_x_range: [...zoom_x_range] as [number, number],
-      initial_x2_range: [...zoom_x2_range] as [number, number],
-      initial_y_range: [...zoom_y_range] as [number, number],
-      initial_y2_range: [...zoom_y2_range] as [number, number],
-    }
-  }
-
-  function handle_touch_move(evt: TouchEvent) {
-    if (!touch_state || evt.touches.length !== 2) return
-    evt.preventDefault()
-
-    const [t1, t2] = Array.from(evt.touches)
-    const [s1, s2] = touch_state.start_touches
-
-    // Calculate center movement for pan
-    const start_center = { x: (s1.x + s2.x) / 2, y: (s1.y + s2.y) / 2 }
-    const curr_center = {
-      x: (t1.clientX + t2.clientX) / 2,
-      y: (t1.clientY + t2.clientY) / 2,
-    }
-    const dx = curr_center.x - start_center.x
-    const dy = curr_center.y - start_center.y
-
-    // Calculate pinch scale (curr/start so spread = zoom out, pinch = zoom in)
-    const start_dist = Math.hypot(s2.x - s1.x, s2.y - s1.y)
-    // Guard against zero-distance pinch to avoid Infinity scale
-    if (start_dist < Number.EPSILON) return
-    const curr_dist = Math.hypot(t2.clientX - t1.clientX, t2.clientY - t1.clientY)
-    const scale = curr_dist / start_dist
-
-    // Clamp to at least 1 to avoid Infinity deltas when padding equals container size
-    const plot_width = Math.max(1, width - pad.l - pad.r)
-    const plot_height = Math.max(1, height - pad.t - pad.b)
-
-    // If scale changed significantly, treat as pinch-zoom
-    // Also guard against scale being too small to avoid division by zero
-    if (Math.abs(scale - 1) > PINCH_ZOOM_THRESHOLD && scale > Number.EPSILON) {
-      // Pinch zoom centered on gesture center
-      // Divide by scale so spread (scale > 1) = smaller span (zoom in)
-      const x_span = touch_state.initial_x_range[1] - touch_state.initial_x_range[0]
-      const x2_span = touch_state.initial_x2_range[1] -
-        touch_state.initial_x2_range[0]
-      const y_span = touch_state.initial_y_range[1] - touch_state.initial_y_range[0]
-      const y2_span = touch_state.initial_y2_range[1] -
-        touch_state.initial_y2_range[0]
-      const x_center =
-        (touch_state.initial_x_range[0] + touch_state.initial_x_range[1]) / 2
-      const x2_center =
-        (touch_state.initial_x2_range[0] + touch_state.initial_x2_range[1]) / 2
-      const y_center =
-        (touch_state.initial_y_range[0] + touch_state.initial_y_range[1]) / 2
-      const y2_center =
-        (touch_state.initial_y2_range[0] + touch_state.initial_y2_range[1]) / 2
-
-      zoom_x_range = [x_center - x_span / scale / 2, x_center + x_span / scale / 2]
-      zoom_x2_range = [
-        x2_center - x2_span / scale / 2,
-        x2_center + x2_span / scale / 2,
-      ]
-      zoom_y_range = [y_center - y_span / scale / 2, y_center + y_span / scale / 2]
-      zoom_y2_range = get_synced_y2(zoom_y_range, [
-        y2_center - y2_span / scale / 2,
-        y2_center + y2_span / scale / 2,
-      ])
-    } else {
-      // Pan
-      const x_delta = pixels_to_data_delta(
-        -dx,
-        touch_state.initial_x_range,
-        plot_width,
-      )
-      const x2_delta = pixels_to_data_delta(
-        -dx,
-        touch_state.initial_x2_range,
-        plot_width,
-      )
-      const y_delta = pixels_to_data_delta(
-        dy,
-        touch_state.initial_y_range,
-        plot_height,
-      )
-      const y2_delta = pixels_to_data_delta(
-        dy,
-        touch_state.initial_y2_range,
-        plot_height,
-      )
-      zoom_x_range = pan_range(touch_state.initial_x_range, x_delta)
-      zoom_x2_range = pan_range(touch_state.initial_x2_range, x2_delta)
-      zoom_y_range = pan_range(touch_state.initial_y_range, y_delta)
-      zoom_y2_range = get_synced_y2(
-        zoom_y_range,
-        pan_range(touch_state.initial_y2_range, y2_delta),
-      )
-    }
-  }
-
-  function handle_touch_end() {
-    touch_state = null
-  }
+      ranges.current = {
+        x: [...auto_x_range] as Vec2,
+        x2: [...auto_x2_range] as Vec2,
+        y: [...auto_y_range] as Vec2,
+        y2: get_synced_y2(auto_y_range, [...auto_y2_range] as Vec2),
+      }
+      // Also reset axis props so future data changes recalculate auto ranges
+      x_axis = { ...x_axis, range: [null, null] }
+      x2_axis = { ...x2_axis, range: [null, null] }
+      y_axis = { ...y_axis, range: [null, null] }
+      y2_axis = { ...y2_axis, range: [null, null] }
+    },
+    // Live tooltip while rect-dragging: update for the closest point inside the
+    // plot bounds, clear when the cursor leaves the svg
+    on_drag_move: (coords, inside_svg) => {
+      if (inside_svg) update_tooltip_point(coords.x, coords.y)
+      else tooltip_point = null
+    },
+  })
+  onDestroy(() => pan_zoom.destroy())
 
   // tooltip logic: find closest point and update tooltip state
   function update_tooltip_point(x_rel: number, y_rel: number, evt?: MouseEvent) {
@@ -1832,7 +1208,7 @@
     legend_manual_position = { x: constrained_x, y: constrained_y }
   }
 
-  function get_screen_coords(point: Point, data_series?: DataSeries): [number, number] {
+  function get_screen_coords(point: Point, data_series?: DataSeries): Vec2 {
     // convert data coordinates to potentially non-finite screen coordinates
     const use_x2 = data_series?.x_axis === `x2`
     const active_x_scale = use_x2 ? x2_scale_fn : x_scale_fn
@@ -1906,7 +1282,6 @@
     return construct_handler_props(tooltip_point)
   })
 
-  let using_controls = $derived(controls.show)
   let has_multiple_series = $derived(series_with_ids.filter(Boolean).length > 1)
 
   // Precompute non-click event names from point_events so we don't rebuild
@@ -1943,32 +1318,12 @@
     set_loading: (axis) => (axis_loading = axis),
   }
 
-  // Create shared handler bound to this component's state
-  // Using $derived so handler updates when callback props change
-  const handle_axis_change = $derived(create_axis_change_handler(
+  // Shared handler + one-shot auto-load bound to this component's state
+  const { handle_axis_change, try_auto_load } = create_axis_loader(
     axis_state,
-    data_loader,
-    on_axis_change,
-    on_error,
-  ))
-
-  let auto_load_attempted = false // prevent infinite retries on failure
-
-  // Auto-load data if series is empty but options exist (runs once)
-  $effect(() => {
-    if (series.length === 0 && data_loader && !auto_load_attempted) {
-      // Check x-axis first, then y-axis
-      if (x_axis.options?.length) {
-        auto_load_attempted = true
-        const first_key = x_axis.selected_key ?? x_axis.options[0].key
-        handle_axis_change(`x`, first_key).catch(() => {})
-      } else if (y_axis.options?.length) {
-        auto_load_attempted = true
-        const first_key = y_axis.selected_key ?? y_axis.options[0].key
-        handle_axis_change(`y`, first_key).catch(() => {})
-      }
-    }
-  })
+    () => ({ data_loader, on_axis_change, on_error }),
+  )
+  $effect(try_auto_load)
 </script>
 
 {#snippet fill_regions_layer(fills: typeof computed_fills)}
@@ -2034,11 +1389,9 @@
       evt.preventDefault()
       fullscreen = false
     }
-    if (evt.key === `Shift`) shift_held = true
-  }}
-  onkeyup={(evt) => {
-    if (evt.key === `Shift`) shift_held = false
+    pan_zoom.on_window_key_down(evt)
   }}
+  onkeyup={pan_zoom.on_window_key_up}
 />
 
 <div
@@ -2065,45 +1418,27 @@
       ([final_x_axis.label, final_y_axis.label].filter(Boolean).join(` vs `) ||
         `Scatter plot`)}
       tabindex="0"
-      onfocusin={() => (is_focused = true)}
-      onfocusout={() => (is_focused = false)}
+      onfocusin={() => pan_zoom.set_focused(true)}
+      onfocusout={() => pan_zoom.set_focused(false)}
       onmouseenter={() => (hovered = true)}
-      onmousedown={handle_mouse_down}
+      onmousedown={pan_zoom.on_mouse_down}
       onmousemove={(evt: MouseEvent) => {
         // Only find closest point if not actively dragging
-        if (!drag_start_coords && !pan_drag_state) on_mouse_move(evt)
+        if (!pan_zoom.drag_start && !pan_zoom.is_pan_dragging) on_mouse_move(evt)
       }}
       onmouseleave={() => {
         hovered = false
         tooltip_point = null
         on_point_hover?.(null)
       }}
-      ondblclick={() => {
-        // Reset to current auto ranges (not stale initial_*_range which may have expanded)
-        // This ensures lazy expansion restarts fresh from current data bounds
-        initial_x_range = [...auto_x_range] as [number, number]
-        initial_x2_range = [...auto_x2_range] as [number, number]
-        initial_y_range = [...auto_y_range] as [number, number]
-        initial_y2_range = [...auto_y2_range] as [number, number]
-        zoom_x_range = [...auto_x_range] as [number, number]
-        zoom_x2_range = [...auto_x2_range] as [number, number]
-        zoom_y_range = [...auto_y_range] as [number, number]
-        zoom_y2_range = get_synced_y2(auto_y_range, [...auto_y2_range] as Vec2)
-        // Also reset axis props so future data changes recalculate auto ranges
-        x_axis = { ...x_axis, range: [null, null] }
-        x2_axis = { ...x2_axis, range: [null, null] }
-        y_axis = { ...y_axis, range: [null, null] }
-        y2_axis = { ...y2_axis, range: [null, null] }
-      }}
-      onwheel={handle_wheel}
-      ontouchstart={handle_touch_start}
-      ontouchmove={handle_touch_move}
-      ontouchend={handle_touch_end}
-      style:cursor={pan_drag_state
-      ? `grabbing`
-      : shift_held && pan?.enabled !== false
-      ? `grab`
-      : `crosshair`}
+      ondblclick={pan_zoom.reset_view}
+      onkeydown={pan_zoom.on_key_down}
+      onwheel={pan_zoom.on_wheel}
+      ontouchstart={pan_zoom.on_touch_start}
+      ontouchmove={pan_zoom.on_touch_move}
+      ontouchend={pan_zoom.on_touch_end}
+      ontouchcancel={pan_zoom.on_touch_end}
+      style:cursor={pan_zoom.cursor}
     >
       {@render user_content?.({
         height,
@@ -2191,9 +1526,6 @@
 
       <!-- Y2-axis (Right) -->
       {#if y2_points.length > 0}
-        {@const y2_inside = final_y2_axis.tick?.label?.inside ?? false}
-        {@const y2_tick_shift = y2_inside ? 0 : (final_y2_axis.tick?.label?.shift?.x ?? 0) + 8}
-        {@const y2_tick_width = y2_inside ? 0 : tick_label_widths.y2_max}
         <PlotAxis
           side="y2"
           ticks={y2_tick_values}
@@ -2207,8 +1539,7 @@
           domain={[y2_min, y2_max]}
           unit_on_first_tick
           tick_label={(tick) => get_tick_label(tick, final_y2_axis.ticks)}
-          label_x={width - pad.r + y2_tick_shift + y2_tick_width + LABEL_GAP_DEFAULT +
-          (final_y2_axis.label_shift?.x ?? 0)}
+          label_x={y2_axis_label_x(final_y2_axis, width, pad.r, tick_label_widths.y2_max)}
           label_y={pad.t + (height - pad.t - pad.b) / 2 + (final_y2_axis.label_shift?.y ?? 0)}
           axis_loading={axis_loading === `y2`}
           on_axis_change={(key) => handle_axis_change(`y2`, key)}
@@ -2238,7 +1569,7 @@
 
       <!-- Tooltip rendered inside overlay (moved outside SVG for stacking above colorbar) -->
 
-      <ZoomRect start={drag_start_coords} current={drag_current_coords} />
+      <ZoomRect start={pan_zoom.drag_start} current={pan_zoom.drag_current} />
 
       <ZeroLines
         display={final_display}
@@ -2246,10 +1577,10 @@
         {x2_scale_fn}
         {y_scale_fn}
         {y2_scale_fn}
-        x_range={zoom_x_range}
-        x2_range={zoom_x2_range}
-        y_range={zoom_y_range}
-        y2_range={zoom_y2_range}
+        x_range={ranges.current.x}
+        x2_range={ranges.current.x2}
+        y_range={ranges.current.y}
+        y2_range={ranges.current.y2}
         x_scale_type={final_x_axis.scale_type}
         x2_scale_type={final_x2_axis.scale_type}
         y_scale_type={final_y_axis.scale_type}
@@ -2300,7 +1631,7 @@
               {@const finite_screen_points = all_line_points
           .map((point) => get_screen_coords(point, series_data))
           .filter(([sx, sy]) => isFinite(sx) && isFinite(sy))}
-              {@const apply_line_controls = using_controls &&
+              {@const apply_line_controls = controls.show &&
           (!has_multiple_series ||
             series_data._id === series_with_ids[selected_series_idx]?._id)}
               {@const ls = series_data.line_style}
@@ -2322,7 +1653,7 @@
                 line_width={(tc(`line.width`) ? styles.line?.width : null) ?? ls?.stroke_width ?? 2}
                 line_dash={(tc(`line.dash`) ? styles.line?.dash : null) ?? ls?.line_dash}
                 area_color="transparent"
-                {line_tween}
+                line_tween={effective_line_tween}
               />
             {/if}
           </g>
@@ -2371,7 +1702,7 @@
                 {@const screen_y = isFinite(raw_screen_y)
           ? raw_screen_y
           : (series_data.y_axis === `y2` ? y2_scale_fn : y_scale_fn).range()[0]}
-                {@const apply_controls = using_controls &&
+                {@const apply_controls = controls.show &&
           (!has_multiple_series ||
             series_data._id === series_with_ids[selected_series_idx]?._id)}
                 {@const pt = point.point_style}
@@ -2446,60 +1777,19 @@
 
     <!-- Tooltip overlay above all plot overlays (legend, colorbar) -->
     {#if handler_props && hovered && tooltip_point}
-      {@const { color_value, point_label, point_style, series_idx } = tooltip_point}
-      {@const hovered_series = series_with_ids[series_idx]}
-      {@const series_markers = hovered_series?.markers ?? DEFAULT_MARKERS}
-      {@const is_transparent_or_none = (color: string | undefined | null): boolean =>
-      !color ||
-      color === `none` ||
-      color === `transparent` ||
-      /rgba\([^)]+[,/]\s*0(\.0*)?\s*\)$/.test(color)}
-      {@const tooltip_bg_color = (() => {
-      const scale_color = color_value != null
-        ? color_scale_fn(color_value)
-        : undefined
-      if (!is_transparent_or_none(scale_color)) return scale_color
-      const fill_color = point_style?.fill
-      if (!is_transparent_or_none(fill_color)) return fill_color
-      if (series_markers?.includes(`points`)) {
-        const stroke_color = point_style?.stroke
-        if (!is_transparent_or_none(stroke_color)) return stroke_color
-      }
-      if (series_markers?.includes(`line`)) {
-        const line_style = hovered_series?.line_style ?? {}
-        const first_point_style = Array.isArray(hovered_series?.point_style)
-          ? hovered_series?.point_style[0]
-          : hovered_series?.point_style
-        const first_color_value = hovered_series?.color_values?.[0]
-        let line_color_candidate = line_style.stroke
-        if (is_transparent_or_none(line_color_candidate)) {line_color_candidate =
-            first_point_style?.fill}
-        if (
-          is_transparent_or_none(line_color_candidate) && first_color_value != null
-        ) line_color_candidate = color_scale_fn(first_color_value)
-        if (
-          is_transparent_or_none(line_color_candidate) &&
-          series_markers?.includes(`points`)
-        ) line_color_candidate = first_point_style?.stroke
-        if (!is_transparent_or_none(line_color_candidate)) return line_color_candidate
-      }
-      return `rgba(0, 0, 0, 0.7)`
-    })()}
-      {@const tooltip_pos = constrain_tooltip_position(
-      handler_props.cx,
-      handler_props.cy,
-      tooltip_el?.offsetWidth ?? 120,
-      tooltip_el?.offsetHeight ?? 50,
-      width,
-      height,
-      { offset_x: 10, offset_y: 5 },
+      {@const { point_label, series_idx } = tooltip_point}
+      {@const tooltip_bg_color = pick_tooltip_bg(
+      tooltip_point,
+      series_with_ids[series_idx],
+      color_scale_fn,
     )}
       <PlotTooltip
-        x={tooltip_pos.x}
-        y={tooltip_pos.y}
-        offset={{ x: 0, y: 0 }}
+        x={handler_props.cx}
+        y={handler_props.cy}
+        offset={{ x: 10, y: 5 }}
+        constrain_to={{ width, height }}
+        fallback_size={{ width: 120, height: 50 }}
         bg_color={tooltip_bg_color}
-        bind:wrapper={tooltip_el}
       >
         {#if tooltip}
           {@render tooltip(handler_props)}
@@ -2558,15 +1848,15 @@
     ] as Vec2}
       <div
         bind:this={colorbar_element}
-        onmouseenter={() => colorbar_hover.set_locked(true)}
-        onmouseleave={() => colorbar_hover.set_locked(false)}
+        onmouseenter={() => colorbar_tween.set_locked(true)}
+        onmouseleave={() => colorbar_tween.set_locked(false)}
         class="colorbar-wrapper"
         role="img"
         aria-label="Color scale legend"
         style={`${
         // explicit wrapper_style or auto-outside places the colorbar; else auto-placement coords
         effective_cbar_wrapper_style ??
-          `position: absolute; left: ${tweened_colorbar_coords.current.x}px; top: ${tweened_colorbar_coords.current.y}px`}; pointer-events: auto;`}
+          `position: absolute; left: ${colorbar_tween.coords.current.x}px; top: ${colorbar_tween.coords.current.y}px`}; pointer-events: auto;`}
       >
         <ColorBar
           tick_labels={4}
@@ -2585,7 +1875,7 @@
     <!-- Legend -->
     <!-- Only render if multiple series or if legend prop was explicitly provided by user (even if empty object) -->
     {#if legend != null && legend_data.length > 0 &&
-      (legend_data.length > 1 || Object.keys(legend).length > 0)}
+      (legend_data.length > 1 || Object.keys(legend ?? {}).length > 0)}
       {@const default_x = pad.l + 10}
       {@const default_y = pad.t + 10}
       {@const current_x = legend_is_dragging && legend_manual_position
@@ -2593,14 +1883,14 @@
       : legend_auto_outside
       ? legend_outside_x
       : legend_placement
-      ? tweened_legend_coords.current.x
+      ? legend_tween.coords.current.x
       : default_x}
       {@const current_y = legend_is_dragging && legend_manual_position
       ? legend_manual_position.y
       : legend_auto_outside
       ? legend_outside_y
       : legend_placement
-      ? tweened_legend_coords.current.y
+      ? legend_tween.coords.current.y
       : default_y}
       <PlotLegend
         bind:root_element={legend_element}
@@ -2608,32 +1898,29 @@
         on_drag_start={handle_legend_drag_start}
         on_drag={handle_legend_drag}
         on_drag_end={() => (legend_is_dragging = false)}
-        on_hover_change={legend_hover.set_locked}
-        on_item_hover={(series_idx: number | null) =>
-          (hovered_legend_series_idx = series_idx != null && series_idx >= 0
-            ? series_idx
-            : null)}
+        on_hover_change={legend_tween.set_locked}
+        on_item_hover={(item) => {
+          if (item?.item_type === `fill`) {
+            // highlight the matching fill in the plot (same state plot fill-hover uses), but skip
+            // hidden fills since they render nothing and would mark the legend item active for naught
+            const fill = computed_fills.find((entry) => entry.idx === item.fill_idx)
+            hovered_fill_key = fill && fill.visible !== false ? fill.hover_key : null
+            hovered_legend_series_idx = null
+          } else {
+            hovered_legend_series_idx = item != null && item.series_idx >= 0
+              ? item.series_idx
+              : null
+            hovered_fill_key = null
+          }
+        }}
         active_series_idx={tooltip_point?.series_idx ?? hovered_legend_series_idx}
+        active_fill_idx={computed_fills.find((fill) => fill.hover_key === hovered_fill_key)?.idx ??
+          null}
         draggable={legend?.draggable ?? true}
         {...legend}
-        on_toggle={legend?.on_toggle ??
-        ((series_idx: number) => {
-          series = toggle_series_visibility(series, series_idx)
-        })}
-        on_double_click={legend?.on_double_click ??
-        ((double_clicked_idx: number) => {
-          const result = handle_legend_double_click(
-            series,
-            double_clicked_idx,
-            prev_series_visibility,
-          )
-          series = result.series
-          prev_series_visibility = result.prev_visibility
-        })}
-        on_group_toggle={legend?.on_group_toggle ??
-        ((_group_name: string, series_indices: number[]) => {
-          series = toggle_group_visibility(series, series_indices)
-        })}
+        on_toggle={legend?.on_toggle ?? legend_vis.on_toggle}
+        on_double_click={legend?.on_double_click ?? legend_vis.on_double_click}
+        on_group_toggle={legend?.on_group_toggle ?? legend_vis.on_group_toggle}
         on_fill_toggle={(source_type: `fill_region` | `error_band`, source_idx: number) => {
           // Only fill_regions can be toggled (error_bands are not bindable)
           if (source_type === `fill_region`) {
@@ -2707,8 +1994,10 @@
     background: var(--scatter-fullscreen-bg, var(--scatter-bg, var(--plot-bg)));
     max-height: none !important;
     overflow: hidden;
-    /* Add padding to prevent titles from being cropped at top */
-    padding-top: var(--plot-fullscreen-padding-top, 2em);
+    /* border-top (not padding-top): bind:clientHeight includes padding but excludes
+    borders - padding made the chart overflow + clip its bottom 2em (x-axis title) */
+    border-top: var(--plot-fullscreen-padding-top, 2em) solid
+      var(--scatter-fullscreen-bg, var(--scatter-bg, var(--plot-bg, transparent)));
     box-sizing: border-box;
   }
   /* Center the colorbar within its wrapper when shorter than it (e.g. capped by --cbar-max-height