matterviz 0.4.0 → 0.4.2

package/dist/convex-hull/ConvexHull4D.svelte

@@ -9,14 +9,8 @@
   } from '../colors'
   import { normalize_show_controls } from '../controls'
   import { sanitize_html } from '../sanitize'
-  import { ClickFeedback, DragOverlay, Spinner } from '../feedback'
-  import Icon from '../Icon.svelte'
-  import {
-    set_fullscreen_bg,
-    setup_fullscreen_effect,
-    toggle_fullscreen,
-  } from '../layout'
-  import { ColorBar, PlotTooltip } from '../plot'
+  import { Spinner } from '../feedback'
+  import { ColorBar } from '../plot'
   import { create_pulse_animation } from '../effects.svelte'
   import { DEFAULTS } from '../settings'
   import type { AnyStructure } from '../structure'
@@ -25,38 +19,36 @@
     compute_4d_coords,
     TETRAHEDRON_VERTICES,
   } from './barycentric-coords'
-  import ConvexHullControls from './ConvexHullControls.svelte'
-  import ConvexHullInfoPane from './ConvexHullInfoPane.svelte'
-  import ConvexHullTooltip from './ConvexHullTooltip.svelte'
+  import { create_canvas_interactions } from './canvas-interactions.svelte'
+  import ConvexHullChrome from './ConvexHullChrome.svelte'
   import GasPressureControls from './GasPressureControls.svelte'
   import * as helpers from './helpers'
+  import { create_hull_data_pipeline } from './hull-state.svelte'
   import type { BaseConvexHullProps, Hull3DProps } from './index'
   import { CONVEX_HULL_STYLE, default_controls, default_hull_config } from './index'
-  import StructurePopup from './StructurePopup.svelte'
   import TemperatureSlider from './TemperatureSlider.svelte'
   import type { Point4D } from './thermodynamics'
   import * as thermo from './thermodynamics'
-  import type {
-    ConvexHullEntry,
-    HighlightStyle,
-    HoverData3D,
-    HullFaceColorMode,
-  } from './types'
+  import type { ConvexHullEntry, HighlightStyle, HullFaceColorMode, PhaseData } from './types'
+  import { MAGNETIC_ORDERING_CATEGORY } from './types'
   import { compute_hull_stability } from './helpers'
 
   let {
     entries = [],
     controls = {},
     config = {},
+    show_controls,
     on_point_click,
     on_point_hover,
     fullscreen = $bindable(DEFAULTS.convex_hull.quaternary.fullscreen),
-    enable_fullscreen = true,
+    fullscreen_toggle = true,
     enable_info_pane = true,
     wrapper = $bindable(),
     label_threshold = 50,
     show_stable = $bindable(DEFAULTS.convex_hull.quaternary.show_stable),
     show_unstable = $bindable(DEFAULTS.convex_hull.quaternary.show_unstable),
+    entry_category = MAGNETIC_ORDERING_CATEGORY,
+    hidden_categories = $bindable([]),
     show_hull_faces = $bindable(DEFAULTS.convex_hull.quaternary.show_hull_faces),
     hull_face_opacity = $bindable(DEFAULTS.convex_hull.quaternary.hull_face_opacity),
     hull_face_color_mode = $bindable(
@@ -64,23 +56,17 @@
     ),
     element_colors = vesta_hex,
     color_mode = $bindable(DEFAULTS.convex_hull.quaternary.color_mode),
-    color_scale = $bindable(
-      DEFAULTS.convex_hull.quaternary.color_scale as D3InterpolateName,
-    ),
+    color_scale = $bindable(DEFAULTS.convex_hull.quaternary.color_scale as D3InterpolateName),
     info_pane_open = $bindable(DEFAULTS.convex_hull.quaternary.info_pane_open),
-    legend_pane_open = $bindable(DEFAULTS.convex_hull.quaternary.legend_pane_open),
+    controls_open = $bindable(DEFAULTS.convex_hull.quaternary.legend_pane_open),
     max_hull_dist_show_phases = $bindable(
       DEFAULTS.convex_hull.quaternary.max_hull_dist_show_phases,
     ),
     max_hull_dist_show_labels = $bindable(
       DEFAULTS.convex_hull.quaternary.max_hull_dist_show_labels,
     ),
-    show_stable_labels = $bindable(
-      DEFAULTS.convex_hull.quaternary.show_stable_labels,
-    ),
-    show_unstable_labels = $bindable(
-      DEFAULTS.convex_hull.quaternary.show_unstable_labels,
-    ),
+    show_stable_labels = $bindable(DEFAULTS.convex_hull.quaternary.show_stable_labels),
+    show_unstable_labels = $bindable(DEFAULTS.convex_hull.quaternary.show_unstable_labels),
     on_file_drop,
     enable_click_selection = true,
     enable_structure_preview = true,
@@ -99,12 +85,13 @@
     children,
     tooltip,
     ...rest
-  }: BaseConvexHullProps<ConvexHullEntry> & Hull3DProps & {
-    highlight_style?: HighlightStyle
-  } = $props()
+  }: BaseConvexHullProps<ConvexHullEntry> &
+    Hull3DProps & {
+      highlight_style?: HighlightStyle
+    } = $props()
 
   const merged_controls = $derived({ ...default_controls, ...controls })
-  const controls_config = $derived(normalize_show_controls(merged_controls.show))
+  const controls_config = $derived(normalize_show_controls(show_controls))
   const merged_config = $derived({
     ...default_hull_config,
     ...config,
@@ -114,90 +101,36 @@
 
   // Reactive dark mode detection for canvas text color
   let dark_mode = $state(is_dark_mode())
-  $effect(() => watch_dark_mode((dark) => dark_mode = dark))
+  $effect(() => watch_dark_mode((dark) => (dark_mode = dark)))
   const text_color = $derived(helpers.get_canvas_text_color(dark_mode))
 
-  // Temperature-dependent free energy support
-  const { has_temp_data, available_temperatures } = $derived(
-    helpers.analyze_temperature_data(entries),
-  )
-
-  // Initialize or reset temperature when it's undefined or no longer valid
-  $effect(() => {
-    if (
-      has_temp_data &&
-      available_temperatures.length > 0 &&
-      (temperature === undefined || !available_temperatures.includes(temperature))
-    ) temperature = available_temperatures[0]
-  })
-
-  // Filter entries by temperature when in temperature mode
-  const temp_filtered_entries = $derived(
-    has_temp_data && temperature !== undefined
-      ? helpers.filter_entries_at_temperature(entries, temperature, {
-        interpolate: interpolate_temperature,
-        max_interpolation_gap,
-      })
-      : entries,
-  )
-
-  // Gas-dependent chemical potential support (corrections based on T, P)
-  const {
-    entries: gas_corrected_entries,
-    analysis: gas_analysis,
-    merged_config: merged_gas_config,
-  } = $derived(
-    helpers.get_gas_corrected_entries(
-      temp_filtered_entries,
-      gas_config,
-      gas_pressures,
-      temperature ?? helpers.DEFAULT_GAS_TEMP,
-    ),
-  )
-
-  let { // Compute energy mode information
-    has_precomputed_e_form,
-    has_precomputed_hull,
-    can_compute_e_form,
-    can_compute_hull,
-    energy_mode,
-    unary_refs,
-  } = $derived(
-    helpers.compute_energy_mode_info(
-      gas_corrected_entries,
-      thermo.find_lowest_energy_unary_refs,
-      energy_source_mode,
-    ),
-  )
-
-  const effective_entries = $derived(
-    helpers.get_effective_entries(
-      gas_corrected_entries,
-      energy_mode,
-      unary_refs,
-      thermo.compute_e_form_per_atom,
-    ),
-  )
-
-  // Process convex hull data with unified PhaseData interface using effective entries
-  const pd_data = $derived(thermo.process_hull_entries(effective_entries))
-
-  // Pre-compute polymorph stats once for O(1) tooltip lookups
-  const polymorph_stats_map = $derived(
-    helpers.compute_all_polymorph_stats(effective_entries),
-  )
-
-  const elements = $derived.by(() => {
-    if (pd_data.elements.length > 4) {
-      console.error(
-        `ConvexHull4D: Dataset contains ${pd_data.elements.length} elements, but quaternary diagrams require exactly 4. Found: [${
-          pd_data.elements.join(`, `)
-        }]`,
-      )
-      return []
-    }
-    return pd_data.elements
+  // Shared reactive data pipeline (temperature → gas → energy mode → hull data → threshold)
+  // Explicit generic breaks the circular type inference through the all_enriched_entries thunk
+  const hull_data = create_hull_data_pipeline<ConvexHullEntry>({
+    dim: 4,
+    entries: () => entries,
+    temperature: () => temperature,
+    interpolate_temperature: () => interpolate_temperature,
+    max_interpolation_gap: () => max_interpolation_gap,
+    gas_config: () => gas_config,
+    gas_pressures: () => gas_pressures,
+    energy_source_mode: () => energy_source_mode,
+    all_enriched_entries: () => all_enriched_entries,
+    max_hull_dist_show_phases: () => max_hull_dist_show_phases,
+    show_stable: () => show_stable,
+    show_unstable: () => show_unstable,
+    entry_category: () => entry_category,
+    hidden_categories: () => hidden_categories,
+    keep_plot_entry: helpers.entry_within_hull_dist,
+    set_temperature: (next_temp) => (temperature = next_temp),
+    set_max_hull_dist_show_phases: (value) => (max_hull_dist_show_phases = value),
+    set_stable_entries: (value) => (stable_entries = value),
+    set_unstable_entries: (value) => (unstable_entries = value),
   })
+  const merged_gas_config = $derived(hull_data.merged_gas_config)
+  const pd_data = $derived(hull_data.pd_data)
+  const elements = $derived(hull_data.elements)
+  const plot_entries = $derived(hull_data.plot_entries)
 
   // Compute 4D hull for visualization (always compute when we have formation energies)
   const hull_4d = $derived.by(() => {
@@ -205,8 +138,9 @@
 
     try {
       // Get coords with formation energies, excluding entries that don't participate in hull
-      const coords = compute_4d_coords(pd_data.entries, elements)
-        .filter((ent) => !ent.exclude_from_hull)
+      const coords = compute_4d_coords(pd_data.entries, elements).filter(
+        (ent) => !ent.exclude_from_hull,
+      )
 
       // Convert to 4D points for hull computation using barycentric coordinates (composition fractions)
       const points_4d: Point4D[] = coords
@@ -234,84 +168,46 @@
   })
 
   // Enrich coords with e_above_hull (before filtering)
-  const all_enriched_entries = $derived.by(() => {
+  // Explicit return type breaks circular type inference with the hull_data pipeline
+  const all_enriched_entries = $derived.by((): ConvexHullEntry[] => {
     if (elements.length !== 4) return []
     try {
       const coords = compute_4d_coords(pd_data.entries, elements)
-      if (energy_mode !== `on-the-fly` || hull_4d.length === 0) return coords
+      if (hull_data.energy_mode !== `on-the-fly` || hull_4d.length === 0) return coords
 
       // Build 4D points, tracking original indices for mapping hull distances back
       const valid = coords.flatMap((entry, idx) => {
         if (
           !Number.isFinite(entry.e_form_per_atom) ||
           ![entry.x, entry.y, entry.z].every(Number.isFinite)
-        ) return []
+        )
+          return []
         const amounts = elements.map((el) => entry.composition[el] || 0)
-          const total = amounts.reduce((sum, amt) => sum + amt, 0)
+        const total = amounts.reduce((sum, amt) => sum + amt, 0)
         if (!(total > 0)) return []
-          const [x, y, z] = amounts.map((amt) => amt / total)
+        const [x, y, z] = amounts.map((amt) => amt / total)
         return [x, y, z].every(Number.isFinite)
           ? [{ idx, pt: { x, y, z, w: entry.e_form_per_atom ?? NaN } }]
           : []
       })
-      const raw_dists = thermo.compute_e_above_hull_4d(valid.map((item) => item.pt), hull_4d)
+      const raw_dists = thermo.compute_e_above_hull_4d(
+        valid.map((item) => item.pt),
+        hull_4d,
+      )
       const hull_map = new Map(valid.map((item, hull_idx) => [item.idx, raw_dists[hull_idx]]))
-      return coords.map((entry, idx) => {
-        const raw = hull_map.get(idx)
-        if (raw === undefined) return { ...entry, e_above_hull: raw, is_stable: false }
-        return { ...entry, ...compute_hull_stability(raw, entry.exclude_from_hull) }
-      })
+      // missing/non-finite distance (no energy or point outside hull projection) -> unknown
+      return coords.map((entry, idx) => ({
+        ...entry,
+        ...compute_hull_stability(hull_map.get(idx), entry.exclude_from_hull),
+      }))
     } catch (err) {
       console.error(`Error computing quaternary coordinates:`, err)
       return []
     }
   })
 
-  // Auto threshold: show all for few entries, use default for many, interpolate between
-  const max_hull_dist_in_data = $derived(
-    helpers.calc_max_hull_dist_in_data(all_enriched_entries),
-  )
-  const auto_default_threshold = $derived(helpers.compute_auto_hull_dist_threshold(
-    all_enriched_entries.length,
-    max_hull_dist_in_data,
-    DEFAULTS.convex_hull.quaternary.max_hull_dist_show_phases,
-  ))
-
-  const next_auto_threshold = helpers.auto_threshold_reset(
-    DEFAULTS.convex_hull.quaternary.max_hull_dist_show_phases,
-  )
-  $effect(() => {
-    max_hull_dist_show_phases = next_auto_threshold(
-      entries,
-      max_hull_dist_show_phases,
-      auto_default_threshold,
-    ) ?? max_hull_dist_show_phases
-  })
-
-  // Filter by threshold; visibility is a view predicate, not entry state.
-  const plot_entries = $derived(
-    all_enriched_entries.filter((entry) => {
-      // Always include stable entries and elemental reference points
-      if (helpers.entry_is_stable(entry)) return true
-      return typeof entry.e_above_hull === `number` &&
-        entry.e_above_hull <= max_hull_dist_show_phases
-    }),
-  )
-  const visible_entries = $derived(helpers.visible_entries(
-    plot_entries,
-    show_stable,
-    show_unstable,
-  ))
-
-  // Stable and unstable entries exposed as bindable props
-  $effect(() => {
-    stable_entries = plot_entries.filter(helpers.entry_is_stable)
-    unstable_entries = plot_entries.filter(helpers.entry_is_unstable)
-  })
-
   let canvas: HTMLCanvasElement | undefined = undefined
   let ctx: CanvasRenderingContext2D | null = null
-  let frame_id = 0 // Performance optimization
 
   // Camera state - following Materials Project's 3D camera setup
   let camera = $state({
@@ -322,43 +218,60 @@
     center_y: 20, // Slight offset to avoid legend overlap
   })
 
-  // Interaction state
-  let is_dragging = $state(false)
-  let drag_started = $state(false)
-  let last_mouse = $state({ x: 0, y: 0 })
-  let hover_data = $state.raw<HoverData3D<ConvexHullEntry> | null>(null)
-  let copy_feedback = $state({ visible: false, position: { x: 0, y: 0 } })
-
-  // Drag and drop state
-  let drag_over = $state(false)
-
-  // Structure popup state
-  let modal_open = $state(false)
-  let selected_structure = $state<AnyStructure | null>(null)
-  let modal_place_right = $state(true)
-  $effect(() => {
-    const current_selection = helpers.current_entry(selected_entry, plot_entries)
-    const stale_selection = selected_entry && !current_selection
-    if (stale_selection) selected_entry = null
-    else if (current_selection && !helpers.same_entry(current_selection, selected_entry)) {
-      selected_entry = current_selection
-    }
-    const current_hover = helpers.current_entry(hover_data?.entry, plot_entries)
-    if (hover_data?.entry && !current_hover) {
-      hover_data = null
-      on_point_hover?.(null)
-    } else if (hover_data && current_hover && current_hover !== hover_data.entry) {
-      hover_data = { ...hover_data, entry: current_hover }
-    }
-    if (modal_open) {
-      const structure = current_selection && extract_structure_from_entry(current_selection)
-      if (structure) selected_structure = structure
-      else {
-        modal_open = false
-        selected_structure = null
+  // Shared canvas-interaction scaffold (mouse/keyboard handlers, hover/drag/popup
+  // state, canvas sizing, render scheduler). Rotation math + keydown actions stay local.
+  const interactions = create_canvas_interactions({
+    wheel_clamp: [1.0, 15],
+    fullscreen_bg_var: `--hull-4d-bg-fullscreen`,
+    canvas: () => canvas,
+    wrapper: () => wrapper,
+    ctx: () => ctx,
+    set_ctx: (context) => (ctx = context),
+    set_canvas_dims: (dims) => (canvas_dims = dims),
+    visible_entries: () => hull_data.visible_entries,
+    plot_entries: () => plot_entries,
+    selected_entry: () => selected_entry,
+    set_selected_entry: (entry) => (selected_entry = entry),
+    fullscreen: () => fullscreen,
+    enable_click_selection: () => enable_click_selection,
+    enable_structure_preview: () => enable_structure_preview,
+    on_point_click: () => on_point_click,
+    on_point_hover: () => on_point_hover,
+    on_file_drop: () => on_file_drop,
+    entry_category: () => entry_category,
+    zoom: () => camera.zoom,
+    set_zoom: (zoom) => (camera.zoom = zoom),
+    project_point: project_3d_point,
+    extract_structure: extract_structure_from_entry,
+    render_frame,
+    on_drag: (dx, dy, panning) => {
+      if (panning) {
+        camera.center_x += dx
+        camera.center_y += dy
+      } else {
+        camera.rotation_y += dx * 0.005
+        camera.rotation_x = Math.max(
+          -Math.PI / 3,
+          Math.min(Math.PI / 3, camera.rotation_x - dy * 0.005),
+        )
       }
-    }
+    },
+    // Reset pan center when entering/exiting fullscreen
+    on_fullscreen_change: () => {
+      camera.center_x = 0
+      camera.center_y = 20
+    },
+    actions: () => ({
+      r: reset_camera,
+      b: () => (color_mode = color_mode === `stability` ? `energy` : `stability`),
+      s: () => (show_stable = !show_stable),
+      u: () => (show_unstable = !show_unstable),
+      h: () => (show_hull_faces = !show_hull_faces),
+      l: () => (show_stable_labels = !show_stable_labels),
+    }),
   })
+  const { render_once } = interactions
+  const sorted_points_cache = $derived(interactions.sorted_points_cache)
 
   // Hull face color (customizable via controls)
   let hull_face_color = $state(`#4caf50`)
@@ -371,9 +284,7 @@
   let pulse_opacity = $derived(0.3 + 0.4 * pulse.unit)
 
   // Merge highlight style with defaults
-  const merged_highlight_style = $derived(
-    helpers.merge_highlight_style(highlight_style),
-  )
+  const merged_highlight_style = $derived(helpers.merge_highlight_style(highlight_style))
 
   // Helper to check if entry is highlighted
   const is_highlighted = (entry: ConvexHullEntry): boolean =>
@@ -382,31 +293,27 @@
   // Re-render when important state changes
   $effect(() => {
     // oxfmt-ignore
-    void [show_hull_faces, color_mode, color_scale, camera.rotation_x, camera.rotation_y, camera.zoom, camera.center_x, camera.center_y, plot_entries, hull_face_color, hull_face_opacity, hull_face_color_mode, element_colors, text_color, elements] // track reactively
+    void [show_hull_faces, color_mode, color_scale, camera.rotation_x, camera.rotation_y, camera.zoom, camera.center_x, camera.center_y, plot_entries, hull_data.visible_entries, hull_face_color, hull_face_opacity, hull_face_color_mode, element_colors, text_color, elements] // track reactively
 
     render_once()
   })
 
   // Visibility toggles are now bindable props
 
-  // Smart label defaults - hide labels if too many entries
+  // Smart label defaults: hide labels for large datasets. Applied once per dataset
+  // (keyed on the entries prop) so later entry-count changes from temperature/gas
+  // filtering don't clobber the user's label toggles.
+  let label_defaults_applied_for: PhaseData[] | null = null
   $effect(() => {
-    const total_entries = effective_entries.length
-    if (total_entries > label_threshold) {
-      show_stable_labels = false
-    } else {
-      // For smaller datasets, show stable labels by default
-      show_stable_labels = true
-    }
+    if (label_defaults_applied_for === entries) return
+    label_defaults_applied_for = entries
+    show_stable_labels = hull_data.effective_entries.length <= label_threshold
     show_unstable_labels = false
   })
 
-  // Function to extract structure data from a convex hull entry
-  function extract_structure_from_entry(
-    entry: ConvexHullEntry,
-  ): AnyStructure | null {
-    const orig_entry = entries.find((ent) => ent.entry_id === entry.entry_id)
-    return orig_entry?.structure as AnyStructure || null
+  // function (not const) so the create_canvas_interactions options above can reference it
+  function extract_structure_from_entry(entry: ConvexHullEntry): AnyStructure | null {
+    return helpers.extract_structure_from_entry(entries, entry)
   }
 
   const reset_camera = () => {
@@ -420,17 +327,17 @@
     reset_camera()
     fullscreen = DEFAULTS.convex_hull.quaternary.fullscreen
     info_pane_open = DEFAULTS.convex_hull.quaternary.info_pane_open
-    legend_pane_open = DEFAULTS.convex_hull.quaternary.legend_pane_open
+    controls_open = DEFAULTS.convex_hull.quaternary.legend_pane_open
     color_mode = DEFAULTS.convex_hull.quaternary.color_mode
     color_scale = DEFAULTS.convex_hull.quaternary.color_scale as D3InterpolateName
     show_stable = DEFAULTS.convex_hull.quaternary.show_stable
     show_unstable = DEFAULTS.convex_hull.quaternary.show_unstable
+    hidden_categories = []
     show_stable_labels = DEFAULTS.convex_hull.quaternary.show_stable_labels
     show_unstable_labels = DEFAULTS.convex_hull.quaternary.show_unstable_labels
     // Use auto-computed threshold based on entry count instead of static default
-    max_hull_dist_show_phases = auto_default_threshold
-    max_hull_dist_show_labels =
-      DEFAULTS.convex_hull.quaternary.max_hull_dist_show_labels
+    max_hull_dist_show_phases = hull_data.auto_default_threshold
+    max_hull_dist_show_labels = DEFAULTS.convex_hull.quaternary.max_hull_dist_show_labels
     show_hull_faces = DEFAULTS.convex_hull.quaternary.show_hull_faces
     hull_face_color = DEFAULTS.convex_hull.quaternary.hull_face_color
     hull_face_opacity = DEFAULTS.convex_hull.quaternary.hull_face_opacity
@@ -438,69 +345,6 @@
       .hull_face_color_mode as HullFaceColorMode
   }
 
-  const handle_keydown = (event: KeyboardEvent) => {
-    const target = event.target
-    // Skip if focus is on an interactive element that handles Enter natively
-    const interactive_selector =
-      `input,textarea,select,button,a,[contenteditable="true"],[role="button"],[tabindex]:not([tabindex="-1"])`
-    if (
-      target instanceof HTMLElement &&
-      target.matches(interactive_selector) &&
-      target !== canvas
-    ) return
-
-    // Prevent double handling from canvas + wrapper bubbling
-    if (event.target !== event.currentTarget && event.currentTarget !== canvas) return
-
-    // Handle Enter for keyboard accessibility - select hovered entry
-    if (event.key === `Enter`) {
-      const entry = hover_data?.entry
-      if (entry) {
-        on_point_click?.(entry)
-        if (enable_click_selection) {
-          selected_entry = entry
-          if (enable_structure_preview) {
-            const structure = extract_structure_from_entry(entry)
-            if (structure) {
-              selected_structure = structure
-              modal_place_right = helpers.calculate_modal_side(wrapper)
-              modal_open = true
-            }
-          }
-        }
-      } else if (modal_open) {
-        close_structure_popup()
-      }
-      return
-    }
-
-    const actions: Record<string, () => void> = {
-      r: reset_camera,
-      b: () => color_mode = color_mode === `stability` ? `energy` : `stability`,
-      s: () => show_stable = !show_stable,
-      u: () => show_unstable = !show_unstable,
-      h: () => show_hull_faces = !show_hull_faces,
-      l: () => show_stable_labels = !show_stable_labels,
-    }
-    actions[event.key.toLowerCase()]?.()
-  }
-
-  async function handle_file_drop(event: DragEvent): Promise<void> {
-    drag_over = false
-    const data = await helpers.parse_hull_entries_from_drop(event)
-    if (data) on_file_drop?.(data)
-  }
-
-  async function copy_entry_data(
-    entry: ConvexHullEntry,
-    position: { x: number; y: number },
-  ) {
-    await helpers.copy_entry_to_clipboard(entry, position, (visible, pos) => {
-      copy_feedback.visible = visible
-      copy_feedback.position = pos
-    })
-  }
-
   const get_point_color = (entry: ConvexHullEntry): string =>
     helpers.get_point_color_for_entry(
       entry,
@@ -511,7 +355,7 @@
 
   // Cache energy color scale per frame/setting
   const energy_color_scale = $derived.by(() =>
-    helpers.get_energy_color_scale(color_mode, color_scale, plot_entries)
+    helpers.get_energy_color_scale(color_mode, color_scale, plot_entries),
   )
 
   // Convex hull statistics - compute internally and expose via bindable prop
@@ -672,30 +516,10 @@
       const [p0, p1, p2, p3] = tet.vertices
 
       // Convert barycentric coordinates to tetrahedral 3D coordinates
-      const tet0 = barycentric_to_tetrahedral([
-        p0.x,
-        p0.y,
-        p0.z,
-        1 - p0.x - p0.y - p0.z,
-      ])
-      const tet1 = barycentric_to_tetrahedral([
-        p1.x,
-        p1.y,
-        p1.z,
-        1 - p1.x - p1.y - p1.z,
-      ])
-      const tet2 = barycentric_to_tetrahedral([
-        p2.x,
-        p2.y,
-        p2.z,
-        1 - p2.x - p2.y - p2.z,
-      ])
-      const tet3 = barycentric_to_tetrahedral([
-        p3.x,
-        p3.y,
-        p3.z,
-        1 - p3.x - p3.y - p3.z,
-      ])
+      const tet0 = barycentric_to_tetrahedral([p0.x, p0.y, p0.z, 1 - p0.x - p0.y - p0.z])
+      const tet1 = barycentric_to_tetrahedral([p1.x, p1.y, p1.z, 1 - p1.x - p1.y - p1.z])
+      const tet2 = barycentric_to_tetrahedral([p2.x, p2.y, p2.z, 1 - p2.x - p2.y - p2.z])
+      const tet3 = barycentric_to_tetrahedral([p3.x, p3.y, p3.z, 1 - p3.x - p3.y - p3.z])
 
       // Project to 2D screen space
       const proj0 = project_3d_point(tet0.x, tet0.y, tet0.z)
@@ -709,8 +533,14 @@
         (p0.x + p1.x + p2.x + p3.x) / 4,
         (p0.y + p1.y + p2.y + p3.y) / 4,
         (p0.z + p1.z + p2.z + p3.z) / 4,
-        ((1 - p0.x - p0.y - p0.z) + (1 - p1.x - p1.y - p1.z) +
-          (1 - p2.x - p2.y - p2.z) + (1 - p3.x - p3.y - p3.z)) / 4,
+        (1 -
+          p0.x -
+          p0.y -
+          p0.z +
+          (1 - p1.x - p1.y - p1.z) +
+          (1 - p2.x - p2.y - p2.z) +
+          (1 - p3.x - p3.y - p3.z)) /
+          4,
       ]
 
       // Each tetrahedron has 4 triangular faces
@@ -736,14 +566,14 @@
     triangles.sort((a, b) => a.avg_depth - b.avg_depth)
 
     // Lazy computation for uniform mode: normalize alpha by formation energy
-    let norm_alpha: ((w: number) => number) | null = null
+    let norm_alpha: ((energy: number) => number) | null = null
     if (hull_face_color_mode === `uniform`) {
       norm_alpha = (energy: number) => {
-        const t = Math.max(
+        const frac = Math.max(
           0,
           Math.min(1, (0 - energy) / Math.max(1e-6, 0 - formation_energy_min)),
         )
-        return t * hull_face_opacity
+        return frac * hull_face_opacity
       }
     }
 
@@ -752,7 +582,7 @@
     let min_w = 0
     if (hull_face_color_mode === `formation_energy`) {
       const all_avg_w = triangles.map((tri) => tri.avg_w)
-      min_w = Math.min(...all_avg_w)
+      min_w = helpers.array_min(all_avg_w)
       energy_face_scale = helpers.get_energy_color_scale(
         `energy`,
         color_scale,
@@ -770,7 +600,7 @@
       }
       if (hull_face_color_mode === `dominant_element`) {
         // Find element with highest fraction
-        const max_idx = tri.centroid_bary.indexOf(Math.max(...tri.centroid_bary))
+        const max_idx = tri.centroid_bary.indexOf(helpers.array_max(tri.centroid_bary))
         const el = elements[max_idx]
         return element_colors[el] ?? `#888888`
       }
@@ -784,9 +614,10 @@
     for (const tri of triangles) {
       const [v0, v1, v2] = tri.vertices
       // Uniform mode uses variable opacity; other modes use fixed opacity
-      const alpha = hull_face_color_mode === `uniform`
-        ? (norm_alpha?.(tri.avg_w) ?? hull_face_opacity)
-        : hull_face_opacity
+      const alpha =
+        hull_face_color_mode === `uniform`
+          ? (norm_alpha?.(tri.avg_w) ?? hull_face_opacity)
+          : hull_face_opacity
       const face_color = get_face_color(tri)
 
       ctx.save()
@@ -809,59 +640,16 @@
 
   function draw_data_points(): void {
     if (!ctx || sorted_points_cache.length === 0) return
-
-    for (const { entry, projected } of sorted_points_cache) {
-      const is_stable = helpers.entry_is_stable(entry)
-      const is_entry_highlighted = is_highlighted(entry)
-      const color = get_point_color(entry)
-      const size = (entry.size || (is_stable ? 6 : 4)) * canvas_dims.scale
-      const marker = entry.marker || `circle`
-
-      // Shadow
-      const shadow_offset = Math.abs(entry.z) * 2 * canvas_dims.scale
-      ctx.fillStyle = `rgba(0, 0, 0, 0.2)`
-      const shadow_path = helpers.create_marker_path(size * 0.8, marker)
-      ctx.save()
-      ctx.translate(projected.x + shadow_offset, projected.y + shadow_offset)
-      ctx.fill(shadow_path)
-      ctx.restore()
-
-      // Highlights
-      if (selected_entry && entry.entry_id === selected_entry.entry_id) {
-        helpers.draw_selection_highlight(
-          ctx,
-          projected,
-          size,
-          canvas_dims.scale,
-          pulse.time,
-          pulse_opacity,
-        )
-      }
-      if (is_entry_highlighted) {
-        helpers.draw_highlight_effect(
-          ctx,
-          projected,
-          size,
-          canvas_dims.scale,
-          pulse.time,
-          merged_highlight_style,
-        )
-      }
-
-      // Main point with marker symbol
-      ctx.fillStyle =
-        is_entry_highlighted && merged_highlight_style.effect === `color`
-          ? merged_highlight_style.color
-          : color
-      ctx.strokeStyle = is_stable ? `#ffffff` : `#000000`
-      ctx.lineWidth = 0.5 * canvas_dims.scale
-      const marker_path = helpers.create_marker_path(size, marker)
-      ctx.save()
-      ctx.translate(projected.x, projected.y)
-      ctx.fill(marker_path)
-      ctx.stroke(marker_path)
-      ctx.restore()
-    }
+    helpers.draw_hull_points(ctx, sorted_points_cache, {
+      scale: canvas_dims.scale,
+      shadow_factor: 2,
+      selected_entry,
+      is_highlighted,
+      get_point_color,
+      highlight_style: merged_highlight_style,
+      pulse_time: pulse.time,
+      pulse_opacity,
+    })
 
     if (!merged_config.show_labels) return
 
@@ -871,9 +659,12 @@
         .filter((entry) => {
           if (entry.is_element) return false
           const is_stable = helpers.entry_is_stable(entry)
-          return (is_stable && show_stable_labels) ||
-            (!is_stable && show_unstable_labels &&
+          return (
+            (is_stable && show_stable_labels) ||
+            (!is_stable &&
+              show_unstable_labels &&
               (entry.e_above_hull ?? 0) <= max_hull_dist_show_labels)
+          )
         }),
     )
 
@@ -925,169 +716,7 @@
     draw_data_points() // Draw data points (on top)
   }
 
-  function handle_mouse_down(event: MouseEvent) {
-    is_dragging = true
-    drag_started = false
-    hover_data = null
-    on_point_hover?.(null)
-    last_mouse = { x: event.clientX, y: event.clientY }
-  }
-
-  const handle_mouse_move = (event: MouseEvent) => {
-    if (!is_dragging) return
-    const [dx, dy] = [event.clientX - last_mouse.x, event.clientY - last_mouse.y]
-
-    // Mark as drag if any movement occurred
-    if (dx !== 0 || dy !== 0) drag_started = true
-
-    // With Cmd/Ctrl held: pan the view instead of rotating
-    if (event.metaKey || event.ctrlKey) {
-      camera.center_x += dx
-      camera.center_y += dy
-    } else {
-      camera.rotation_y += dx * 0.005
-      camera.rotation_x = Math.max(
-        -Math.PI / 3,
-        Math.min(Math.PI / 3, camera.rotation_x - dy * 0.005),
-      )
-    }
-    last_mouse = { x: event.clientX, y: event.clientY }
-  }
-
-  const handle_wheel = (event: WheelEvent) => {
-    event.preventDefault()
-    camera.zoom = Math.max(
-      1.0,
-      Math.min(15, camera.zoom * (event.deltaY > 0 ? 0.98 : 1.02)),
-    )
-  }
-
-  const handle_hover = (event: MouseEvent) => {
-    if (is_dragging) return
-    const entry = find_entry_at_mouse(event)
-    hover_data = entry
-      ? { entry, position: { x: event.clientX, y: event.clientY } }
-      : null
-    on_point_hover?.(hover_data)
-  }
-
-  const find_entry_at_mouse = (event: MouseEvent): ConvexHullEntry | null =>
-    helpers.find_hull_entry_at_mouse(
-      canvas,
-      event,
-      visible_entries,
-      (x: number, y: number, z: number) => {
-        const projected = project_3d_point(x, y, z)
-        return { x: projected.x, y: projected.y }
-      },
-    )
-
-  const handle_click = (event: MouseEvent) => {
-    event.stopPropagation()
-
-    // Check if this was a drag operation (any mouse movement during drag)
-    const was_drag = drag_started
-    drag_started = false // Reset for next interaction
-    if (was_drag) return // Don't trigger click if this was a drag
-
-    const entry = find_entry_at_mouse(event)
-    if (entry) {
-      on_point_click?.(entry)
-      if (enable_click_selection) {
-        selected_entry = entry
-        if (enable_structure_preview) {
-          const structure = extract_structure_from_entry(entry)
-          if (structure) {
-            selected_structure = structure
-            modal_place_right = helpers.calculate_modal_side(wrapper)
-            modal_open = true
-          }
-        }
-      }
-    } else if (modal_open) close_structure_popup()
-  }
-
-  function close_structure_popup() {
-    modal_open = false
-    selected_structure = null
-    selected_entry = null
-  }
-
-  const handle_double_click = (event: MouseEvent) => {
-    const entry = find_entry_at_mouse(event)
-    if (entry) {
-      copy_entry_data(entry, {
-        x: event.clientX,
-        y: event.clientY,
-      })
-    }
-  }
-
-  function render_once() {
-    if (!frame_id) {
-      frame_id = requestAnimationFrame(() => {
-        render_frame()
-        frame_id = 0
-      })
-    }
-  }
-
-  function update_canvas_size() {
-    if (!canvas) return
-    const dpr = globalThis.devicePixelRatio || 1
-    const container = canvas.parentElement
-    const rect = container?.getBoundingClientRect()
-    const [width, height] = rect ? [rect.width, rect.height] : [400, 400]
-
-    const new_width = Math.max(0, Math.round(width * dpr))
-    const new_height = Math.max(0, Math.round(height * dpr))
-    canvas_dims = { width, height, scale: Math.min(width, height) / 600 }
-
-    if (!ctx || canvas.width !== new_width || canvas.height !== new_height) {
-      canvas.width = new_width
-      canvas.height = new_height
-      ctx = canvas.getContext(`2d`)
-      if (ctx) {
-        ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
-        ctx.imageSmoothingEnabled = true
-        ctx.imageSmoothingQuality = `high`
-      }
-    }
-    render_once()
-  }
-
-  $effect(() => {
-    if (!canvas) return
-
-    // Initial setup
-    update_canvas_size()
-
-    // Watch for resize events - only update canvas, don't reset camera
-    const resize_observer = new ResizeObserver(update_canvas_size)
-
-    const container = canvas.parentElement
-    if (container) resize_observer.observe(container)
-
-    return () => { // Cleanup on unmount
-      if (frame_id) cancelAnimationFrame(frame_id)
-      resize_observer.disconnect()
-    }
-  })
-
-  // Fullscreen handling with camera reset
-  let was_fullscreen = $state(fullscreen)
-  $effect(() => {
-    setup_fullscreen_effect(fullscreen, wrapper, (entering_fullscreen) => {
-      if (entering_fullscreen !== was_fullscreen) {
-        camera.center_x = 0
-        camera.center_y = 20
-        was_fullscreen = entering_fullscreen
-      }
-    })
-    set_fullscreen_bg(wrapper, fullscreen, `--hull-4d-bg-fullscreen`)
-  })
-
-  // Performance: Cache canvas dimensions and pre-compute sorted point projections
+  // Performance: Cache canvas dimensions and formation energy minimum
   let canvas_dims = $state({ width: 600, height: 600, scale: 1 })
   const formation_energy_min = $derived.by(() => {
     let min_energy = 0
@@ -1096,65 +725,41 @@
     }
     return min_energy
   })
-  const sorted_points_cache = $derived.by(() => {
-    if (!canvas || visible_entries.length === 0) return []
-    return visible_entries
-      .map((entry) => ({
-        entry,
-        projected: project_3d_point(entry.x, entry.y, entry.z),
-      }))
-      .sort((a, b) => a.projected.depth - b.projected.depth)
-  })
 
-  let style = $derived(
-    `--hull-stable-color:${merged_config.colors?.stable || `#0072B2`};
-    --hull-unstable-color:${merged_config.colors?.unstable || `#E69F00`};
-    --hull-edge-color:${merged_config.colors?.edge || `var(--text-color, #212121)`};
-     --hull-text-color:${
-      merged_config.colors?.annotation || `var(--text-color, #212121)`
-    }`,
-  )
+  let style = $derived(helpers.hull_style_css(merged_config.colors))
 </script>
 
 <svelte:document
   onfullscreenchange={() => {
-    fullscreen = Boolean(document.fullscreenElement)
+    // tie fullscreen state to this component's own wrapper, not any fullscreen element
+    fullscreen = document.fullscreenElement === wrapper
   }}
-  onmousemove={handle_mouse_move}
-  onmouseup={() => [is_dragging, drag_started] = [false, false]}
+  onmousemove={interactions.handle_mouse_move}
+  onmouseup={interactions.handle_mouse_up}
 />
 
 <div
   {...rest}
-  class="convex-hull-4d {rest.class ?? ``}"
-  class:dragover={drag_over}
+  class={[`convex-hull-4d`, rest.class]}
+  class:dragover={interactions.drag_over}
   style={`${style}; ${rest.style ?? ``}`}
   data-has-selection={selected_entry !== null}
-  data-has-hover={hover_data !== null}
-  data-is-dragging={is_dragging}
+  data-has-hover={interactions.hover_data !== null}
+  data-is-dragging={interactions.is_dragging}
   data-rotation-x={camera.rotation_x.toFixed(4)}
   data-rotation-y={camera.rotation_y.toFixed(4)}
   bind:this={wrapper}
   role="application"
   tabindex="-1"
-  onkeydown={handle_keydown}
-  ondrop={handle_file_drop}
-  ondragover={(event) => {
-    event.preventDefault()
-    drag_over = true
-  }}
-  ondragleave={(event) => {
-    event.preventDefault()
-    drag_over = false
-  }}
+  {...interactions.wrapper_handlers}
   aria-label="Convex hull visualization"
 >
   {@render children?.({
-      stable_entries,
-      unstable_entries,
-      highlighted_entries,
-      selected_entry,
-    })}
+    stable_entries,
+    unstable_entries,
+    highlighted_entries,
+    selected_entry,
+  })}
   <h3 style="position: absolute; left: 1em; top: 1ex; margin: 0">
     {@html sanitize_html(merged_controls.title || phase_stats?.chemical_system || ``)}
   </h3>
@@ -1163,12 +768,7 @@
     bind:this={canvas}
     tabindex="0"
     aria-label={merged_controls.title || phase_stats?.chemical_system || `4D Convex Hull`}
-    onmousedown={handle_mouse_down}
-    onmousemove={handle_hover}
-    onclick={handle_click}
-    onkeydown={handle_keydown}
-    ondblclick={handle_double_click}
-    onwheel={handle_wheel}
+    {...interactions.canvas_handlers}
   ></canvas>
 
   {#if entries.length === 0}
@@ -1180,14 +780,9 @@
 
   <!-- Energy above hull Color Bar -->
   {#if color_mode === `energy` && plot_entries.length > 0}
-    {@const hull_distances = plot_entries
-      .map((entry) => entry.e_above_hull)
-      .filter((val): val is number => typeof val === `number`)}
-    {@const min_energy = hull_distances.length > 0 ? Math.min(...hull_distances) : 0}
-    {@const max_energy = hull_distances.length > 0 ? Math.max(...hull_distances, 0.1) : 0.1}
     <ColorBar
       title="Energy above hull (eV/atom)"
-      range={[min_energy, max_energy]}
+      range={helpers.hull_distance_range(plot_entries)}
       {color_scale}
       wrapper_style="position: absolute; bottom: 2em; left: 1em; width: 200px;"
       bar_style="height: 12px;"
@@ -1195,137 +790,61 @@
     />
   {/if}
 
-  <!-- Control buttons (top-right corner like Structure.svelte) -->
-  {#if controls_config.mode !== `never`}
-    <section class="control-buttons {controls_config.class}">
-      {#if controls_config.visible(`reset`)}
-        <button
-          type="button"
-          onclick={reset_all}
-          title="Reset camera view (R key)"
-          class="reset-camera-btn"
-        >
-          <Icon icon="Reset" />
-        </button>
-      {/if}
-
-      {#if enable_info_pane && phase_stats && controls_config.visible(`info-pane`)}
-        <ConvexHullInfoPane
-          bind:pane_open={info_pane_open}
-          {phase_stats}
-          {stable_entries}
-          {unstable_entries}
-          {show_stable}
-          {show_unstable}
-          {max_hull_dist_show_phases}
-          {max_hull_dist_show_labels}
-          {label_threshold}
-          toggle_props={{ class: `info-btn` }}
-        />
-      {/if}
-
-      {#if enable_fullscreen && controls_config.visible(`fullscreen`)}
-        <button
-          type="button"
-          onclick={() => toggle_fullscreen(wrapper)}
-          title="{fullscreen ? `Exit` : `Enter`} fullscreen"
-          class="fullscreen-btn"
-        >
-          <Icon icon="{fullscreen ? `Exit` : ``}Fullscreen" />
-        </button>
-      {/if}
-
-      <!-- Legend controls pane -->
-      {#if controls_config.visible(`controls`)}
-        <ConvexHullControls
-          bind:controls_open={legend_pane_open}
-          bind:color_mode
-          bind:color_scale
-          bind:show_stable
-          bind:show_unstable
-          bind:show_stable_labels
-          bind:show_unstable_labels
-          bind:max_hull_dist_show_phases
-          bind:max_hull_dist_show_labels
-          {max_hull_dist_in_data}
-          {stable_entries}
-          {unstable_entries}
-          {camera}
-          {merged_controls}
-          toggle_props={{ class: `legend-controls-btn` }}
-          {show_hull_faces}
-          on_hull_faces_change={(value: boolean) => show_hull_faces = value}
-          {hull_face_color}
-          on_hull_face_color_change={(value: string) => hull_face_color = value}
-          {hull_face_opacity}
-          on_hull_face_opacity_change={(value: number) => hull_face_opacity = value}
-          {hull_face_color_mode}
-          on_hull_face_color_mode_change={(value: HullFaceColorMode) =>
-            hull_face_color_mode = value}
-          bind:energy_source_mode
-          {has_precomputed_e_form}
-          {can_compute_e_form}
-          {has_precomputed_hull}
-          {can_compute_hull}
-        />
-      {/if}
-    </section>
-  {/if}
-
-  {#if has_temp_data && temperature !== undefined}
-    <TemperatureSlider {available_temperatures} bind:temperature />
+  <!-- Toolbar + tooltip/copy-feedback/drag/structure-popup chrome -->
+  <ConvexHullChrome
+    {interactions}
+    {hull_data}
+    {controls_config}
+    {reset_all}
+    reset_title="Reset view and settings"
+    {enable_info_pane}
+    {phase_stats}
+    {label_threshold}
+    {fullscreen}
+    {fullscreen_toggle}
+    {wrapper}
+    {camera}
+    {merged_controls}
+    {stable_entries}
+    {unstable_entries}
+    {get_point_color}
+    {merged_highlight_style}
+    {is_highlighted}
+    {tooltip}
+    {selected_entry}
+    bind:show_hull_faces
+    bind:hull_face_color
+    bind:hull_face_opacity
+    bind:hull_face_color_mode
+    bind:info_pane_open
+    bind:controls_open
+    bind:color_mode
+    bind:color_scale
+    bind:show_stable
+    bind:show_unstable
+    {entry_category}
+    bind:hidden_categories
+    bind:show_stable_labels
+    bind:show_unstable_labels
+    bind:max_hull_dist_show_phases
+    bind:max_hull_dist_show_labels
+    bind:energy_source_mode
+  />
+
+  {#if hull_data.has_temp_data && temperature !== undefined}
+    <TemperatureSlider
+      available_temperatures={hull_data.available_temperatures}
+      bind:temperature
+    />
   {/if}
 
-  {#if gas_analysis.has_gas_dependent_elements && merged_gas_config}
+  {#if hull_data.gas_analysis.has_gas_dependent_elements && merged_gas_config}
     <GasPressureControls
       config={merged_gas_config}
       bind:pressures={gas_pressures}
       temperature={temperature ?? 300}
     />
   {/if}
-
-  <!-- Hover tooltip -->
-  {#if hover_data}
-    {@const { entry, position } = hover_data}
-    {@const entry_highlight = is_highlighted(entry) ? merged_highlight_style : undefined}
-    {@const tooltip_style =
-      `z-index: ${CONVEX_HULL_STYLE.z_index.tooltip}; backdrop-filter: blur(4px);
-      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);`}
-    <PlotTooltip
-      x={position.x}
-      y={position.y}
-      offset={{ x: 10, y: -10 }}
-      bg_color={get_point_color(entry)}
-      fixed
-      style={tooltip_style}
-    >
-      <ConvexHullTooltip
-        {entry}
-        {polymorph_stats_map}
-        highlight_style={entry_highlight}
-        {tooltip}
-      />
-    </PlotTooltip>
-  {/if}
-
-  <!-- Copy-to-clipboard feedback (double-click on point) -->
-  <ClickFeedback bind:visible={copy_feedback.visible} position={copy_feedback.position} />
-
-  <!-- Drag over overlay -->
-  <DragOverlay visible={drag_over} />
-
-  {#if modal_open && selected_structure}
-    <StructurePopup
-      structure={selected_structure}
-      place_right={modal_place_right}
-      stats={{
-        id: selected_entry?.entry_id,
-        e_above_hull: selected_entry?.e_above_hull,
-        e_form: selected_entry?.e_form_per_atom,
-      }}
-      onclose={close_structure_popup}
-    />
-  {/if}
 </div>
 
 <style>
@@ -1353,42 +872,4 @@
   canvas:active {
     cursor: grabbing;
   }
-  .control-buttons {
-    position: absolute;
-    top: 1ex;
-    right: 1ex;
-    display: flex;
-    gap: 8px;
-    transition: opacity 0.2s ease-in-out;
-  }
-  .control-buttons.hover-visible {
-    opacity: 0;
-    pointer-events: none;
-  }
-  .convex-hull-4d:hover .control-buttons.hover-visible,
-  .convex-hull-4d:focus-within .control-buttons.hover-visible {
-    opacity: 1;
-    pointer-events: auto;
-  }
-  .control-buttons.always-visible {
-    opacity: 1;
-    pointer-events: auto;
-  }
-  .control-buttons :global(.draggable-pane) {
-    z-index: 1001 !important;
-  }
-  .control-buttons :global(button) {
-    background: transparent;
-    border: none;
-    padding: 4px;
-    cursor: pointer;
-    border-radius: 3px;
-    color: var(--text-color, currentColor);
-    transition: background-color 0.2s;
-    display: flex;
-    font-size: clamp(0.85em, 2cqmin, 1.3em);
-  }
-  .control-buttons :global(button):hover {
-    background-color: color-mix(in srgb, currentColor 8%, transparent);
-  }
 </style>