matterviz 0.3.2 → 0.3.3

package/dist/spectral/Bands.svelte

@@ -1,533 +1,712 @@
-<script lang="ts">import { PLOT_COLORS } from '../colors';
-import EmptyState from '../EmptyState.svelte';
-import { format_num } from '../labels';
-import { SettingsSection } from '../layout';
-import ScatterPlot from '../plot/ScatterPlot.svelte';
-import * as helpers from './helpers';
-import { SvelteMap } from 'svelte/reactivity';
-let { band_structs, line_kwargs = {}, path_mode = `strict`, band_type = undefined, show_legend = true, x_axis = {}, y_axis = $bindable({}), x_positions = $bindable(), reference_frequency = null, ribbon_config = {}, fermi_level = undefined, units = $bindable(`THz`), band_spin_mode = $bindable(`overlay`), highlight_regions = [], shade_imaginary_modes = true, show_gap_annotation = true, show_controls = true, show_path_mode_control = true, show_units_control = true, show_spin_control = true, show_annotation_controls = true, id = undefined, class: class_name = undefined, style = undefined, 'data-testid': data_testid = undefined, ...rest } = $props();
-const is_dom_attr_value = (attr_value) => typeof attr_value === `string` ||
+<script lang="ts">
+  import { PLOT_COLORS } from '../colors'
+  import EmptyState from '../EmptyState.svelte'
+  import { format_num } from '../labels'
+  import { sanitize_html } from '../sanitize'
+  import { SettingsSection } from '../layout'
+  import type { Vec2 } from '../math'
+  import ScatterPlot from '../plot/ScatterPlot.svelte'
+  import type { AxisConfig, DataSeries, FillRegion } from '../plot/types'
+  import * as helpers from './helpers'
+  import type {
+    BandsSpinMode,
+    BandStructureType,
+    BaseBandStructure,
+    FrequencyUnit,
+    LineKwargs,
+    PathMode,
+    RibbonConfig,
+  } from './types'
+  import type { ComponentProps } from 'svelte'
+  import { SvelteMap } from 'svelte/reactivity'
+
+  type Dom_attr_value = string | number | boolean
+
+  let {
+    band_structs,
+    line_kwargs = {},
+    path_mode = `strict`,
+    band_type = undefined,
+    show_legend = true,
+    x_axis = {},
+    y_axis = $bindable({}),
+    x_positions = $bindable(),
+    reference_frequency = null,
+    ribbon_config = {},
+    fermi_level = undefined,
+    units = $bindable(`THz`),
+    band_spin_mode = $bindable(`overlay`),
+    highlight_regions = [],
+    shade_imaginary_modes = true,
+    show_gap_annotation = true,
+    show_controls = true,
+    show_path_mode_control = true,
+    show_units_control = true,
+    show_spin_control = true,
+    show_annotation_controls = true,
+    id = undefined,
+    class: class_name = undefined,
+    style = undefined,
+    'data-testid': data_testid = undefined,
+    ...rest
+  }: ComponentProps<typeof ScatterPlot> & {
+    band_structs: BaseBandStructure | Record<string, BaseBandStructure>
+    x_axis?: AxisConfig
+    y_axis?: AxisConfig
+    line_kwargs?: LineKwargs
+    path_mode?: PathMode
+    band_type?: BandStructureType
+    show_legend?: boolean
+    x_positions?: Record<string, [number, number]>
+    reference_frequency?: number | null
+    ribbon_config?: RibbonConfig | Record<string, RibbonConfig>
+    fermi_level?: number // Fermi level for electronic bands (auto-detected if not provided)
+    units?: FrequencyUnit // Phonon frequency display units (electronic always eV)
+    band_spin_mode?: BandsSpinMode // Electronic spin display: overlay (default), up_only, down_only
+    highlight_regions?: {
+      y_min: number
+      y_max: number
+      color?: string
+      opacity?: number
+      label?: string
+    }[]
+    shade_imaginary_modes?: boolean // Shade y<0 region for phonon plots with imaginary modes
+    show_gap_annotation?: boolean // Annotate electronic VBM/CBM and gap when available
+    show_controls?: boolean
+    show_path_mode_control?: boolean
+    show_units_control?: boolean
+    show_spin_control?: boolean
+    show_annotation_controls?: boolean
+    id?: string
+    class?: string
+    style?: string
+    'data-testid'?: string
+  } = $props()
+
+  const is_dom_attr_value = (attr_value: unknown): attr_value is Dom_attr_value =>
+    typeof attr_value === `string` ||
     typeof attr_value === `number` ||
-    typeof attr_value === `boolean`;
-// Helper function to get line styling for a band
-function get_line_style(color, is_acoustic, frequencies, band_idx) {
-    const defaults = { stroke: color, stroke_width: is_acoustic ? 1.5 : 1 };
+    typeof attr_value === `boolean`
+
+  // Helper function to get line styling for a band
+  function get_line_style(
+    color: string,
+    is_acoustic: boolean,
+    frequencies: number[],
+    band_idx: number,
+  ): { stroke: string; stroke_width: number } {
+    const defaults = { stroke: color, stroke_width: is_acoustic ? 1.5 : 1 }
+
     if (typeof line_kwargs === `function`) {
-        const custom = line_kwargs(frequencies, band_idx);
-        return {
-            stroke: custom.stroke ?? defaults.stroke,
-            stroke_width: custom.stroke_width ?? defaults.stroke_width,
-        };
+      const custom = line_kwargs(frequencies, band_idx)
+      return {
+        stroke: (custom.stroke as string) ?? defaults.stroke,
+        stroke_width: (custom.stroke_width as number) ?? defaults.stroke_width,
+      }
     }
+
     if (typeof line_kwargs === `object` && line_kwargs !== null) {
-        const mode_key = is_acoustic ? `acoustic` : `optical`;
-        const mode_kwargs = line_kwargs[mode_key];
-        const source = (mode_kwargs ?? line_kwargs);
-        return {
-            stroke: source.stroke ?? defaults.stroke,
-            stroke_width: source.stroke_width ?? defaults.stroke_width,
-        };
+      const mode_key = is_acoustic ? `acoustic` : `optical`
+      const mode_kwargs = (line_kwargs as Record<string, unknown>)[mode_key] as
+        | Record<string, unknown>
+        | undefined
+      const source = (mode_kwargs ?? line_kwargs) as Record<string, unknown>
+      return {
+        stroke: (source.stroke as string) ?? defaults.stroke,
+        stroke_width: (source.stroke_width as number) ?? defaults.stroke_width,
+      }
     }
-    return defaults;
-}
-// Normalize input to dict format
-// Supports multiple formats:
-// - matterviz format: qpoints + branches arrays
-// - pymatgen phonon: qpoints + bands (or frequencies_cm) arrays
-// - pymatgen electronic: kpoints + bands arrays
-let band_structs_dict = $derived.by(() => {
-    if (!band_structs)
-        return {};
+
+    return defaults
+  }
+
+  // Ribbon data structure for rendering
+  interface RibbonData {
+    x_values: number[]
+    y_values: number[]
+    width_values: number[]
+    color: string
+    opacity: number
+    max_width: number
+    scale: number
+    band_idx: number
+    structure_label: string
+    segment_key: string
+  }
+
+  // Normalize input to dict format
+  // Supports multiple formats:
+  // - matterviz format: qpoints + branches arrays
+  // - pymatgen phonon: qpoints + bands (or frequencies_cm) arrays
+  // - pymatgen electronic: kpoints + bands arrays
+  let band_structs_dict = $derived.by(() => {
+    if (!band_structs) return {}
+
     // Detect single band structure by checking for characteristic fields
     // - pymatgen format: has @class or @module markers (may also have branches)
     // - matterviz format: has qpoints + branches (no pymatgen markers)
     const has_qpoints = `qpoints` in band_structs &&
-        Array.isArray(band_structs.qpoints) &&
-        band_structs.qpoints.length > 0;
+      Array.isArray(band_structs.qpoints) &&
+      band_structs.qpoints.length > 0
     const has_kpoints = `kpoints` in band_structs &&
-        Array.isArray(band_structs.kpoints) &&
-        band_structs.kpoints.length > 0;
-    const has_bands = `bands` in band_structs;
+      Array.isArray(band_structs.kpoints) &&
+      band_structs.kpoints.length > 0
+    const has_bands = `bands` in band_structs
     const has_frequencies_cm = `frequencies_cm` in band_structs &&
-        Array.isArray(band_structs.frequencies_cm);
-    const has_branches = `branches` in band_structs;
+      Array.isArray(band_structs.frequencies_cm)
+    const has_branches = `branches` in band_structs
     // Pymatgen structures have explicit class/module markers
-    const is_pymatgen = `@class` in band_structs || `@module` in band_structs;
+    const is_pymatgen = `@class` in band_structs || `@module` in band_structs
+
     // Pymatgen single: has markers and point/band data (may have branches too)
     const is_pymatgen_single = is_pymatgen &&
-        (has_qpoints || has_kpoints) &&
-        (has_bands || has_frequencies_cm);
+      (has_qpoints || has_kpoints) &&
+      (has_bands || has_frequencies_cm)
     // Matterviz single: has qpoints + branches but NO pymatgen markers
-    const is_matterviz_single = !is_pymatgen && has_qpoints && has_branches;
-    const is_single = is_matterviz_single || is_pymatgen_single;
-    const result = {};
+    const is_matterviz_single = !is_pymatgen && has_qpoints && has_branches
+    const is_single = is_matterviz_single || is_pymatgen_single
+
+    const result: Record<string, BaseBandStructure> = {}
+
     if (is_single) {
-        const normalized = helpers.normalize_band_structure(band_structs);
-        if (normalized)
-            result.default = normalized;
-    }
-    else {
-        for (const [key, bs] of Object.entries(band_structs)) {
-            const normalized = helpers.normalize_band_structure(bs);
-            if (normalized)
-                result[key] = normalized;
-        }
+      const normalized = helpers.normalize_band_structure(band_structs)
+      if (normalized) result.default = normalized
+    } else {
+      for (const [key, bs] of Object.entries(band_structs)) {
+        const normalized = helpers.normalize_band_structure(bs)
+        if (normalized) result[key] = normalized
+      }
     }
-    return result;
-});
-// Auto-detect band type if not explicitly set
-let detected_band_type = $derived.by(() => {
-    if (band_type)
-        return band_type;
-    if (!band_structs)
-        return `phonon`;
+    return result
+  })
+
+  // Auto-detect band type if not explicitly set
+  let detected_band_type = $derived.by((): BandStructureType => {
+    if (band_type) return band_type
+    if (!band_structs) return `phonon`
+
     // Single structure has marker fields; dict of structures has label keys
     const is_single = `@class` in band_structs || `@module` in band_structs ||
-        `kpoints` in band_structs || `qpoints` in band_structs;
-    const source = (is_single ? band_structs : Object.values(band_structs)[0]);
-    if (!source)
-        return `phonon`;
+      `kpoints` in band_structs || `qpoints` in band_structs
+    const source = (is_single ? band_structs : Object.values(band_structs)[0]) as
+      | Record<string, unknown>
+      | undefined
+    if (!source) return `phonon`
+
     // Electronic: has kpoints, BandStructure* class (not Phonon*), or electronic_structure module
-    const py_class_name = String(source[`@class`] ?? ``);
-    if ((`kpoints` in source && Array.isArray(source.kpoints) &&
+    const py_class_name = String(source[`@class`] ?? ``)
+    if (
+      (`kpoints` in source && Array.isArray(source.kpoints) &&
         source.kpoints.length > 0) ||
-        (py_class_name.startsWith(`BandStructure`) &&
-            !py_class_name.startsWith(`Phonon`)) ||
-        String(source[`@module`] ?? ``).includes(`electronic_structure`))
-        return `electronic`;
-    return `phonon`;
-});
-// Auto-detect Fermi level from electronic band structure data if not explicitly provided
-let effective_fermi_level = $derived.by(() => {
-    if (fermi_level !== undefined)
-        return fermi_level;
-    if (detected_band_type !== `electronic`)
-        return undefined;
+      (py_class_name.startsWith(`BandStructure`) &&
+        !py_class_name.startsWith(`Phonon`)) ||
+      String(source[`@module`] ?? ``).includes(`electronic_structure`)
+    ) return `electronic`
+
+    return `phonon`
+  })
+
+  // Auto-detect Fermi level from electronic band structure data if not explicitly provided
+  let effective_fermi_level = $derived.by((): number | undefined => {
+    if (fermi_level !== undefined) return fermi_level
+    if (detected_band_type !== `electronic`) return undefined
+
     // Check raw input for efermi field
-    const source = `efermi` in band_structs
-        ? band_structs
-        : Object.values(band_structs)[0];
-    const efermi = source?.efermi;
-    return typeof efermi === `number` ? efermi : undefined;
-});
-let effective_spin_mode = $derived.by(() => {
-    if (detected_band_type !== `electronic`)
-        return null;
+    const source = `efermi` in (band_structs as object)
+      ? band_structs
+      : Object.values(band_structs)[0]
+    const efermi = (source as Record<string, unknown>)?.efermi
+    return typeof efermi === `number` ? efermi : undefined
+  })
+
+  let effective_spin_mode = $derived.by((): BandsSpinMode => {
+    if (detected_band_type !== `electronic`) return null
     return (band_spin_mode === `up_only` || band_spin_mode === `down_only`)
-        ? band_spin_mode
-        : `overlay`;
-});
-const convert_band_values = (values) => {
-    if (detected_band_type !== `phonon`)
-        return values;
-    if (units === `THz`)
-        return values;
-    return helpers.convert_frequencies(values, units);
-};
-// Collect all path segments across structures once (shared by strict checks and plotting)
-let all_segments = $derived.by(() => {
-    const all_segments = {};
+      ? band_spin_mode
+      : `overlay`
+  })
+
+  const convert_band_values = (values: number[]): number[] => {
+    if (detected_band_type !== `phonon`) return values
+    if (units === `THz`) return values
+    return helpers.convert_frequencies(values, units)
+  }
+
+  // Collect all path segments across structures once (shared by strict checks and plotting)
+  let all_segments = $derived.by(() => {
+    const all_segments: Record<string, [string, BaseBandStructure][]> = {}
     for (const [label, bs] of Object.entries(band_structs_dict)) {
-        for (const branch of bs.branches) {
-            const start_label = bs.qpoints[branch.start_index]?.label ?? undefined;
-            const end_label = bs.qpoints[branch.end_index]?.label ?? undefined;
-            const segment_key = helpers.get_segment_key(start_label, end_label);
-            all_segments[segment_key] ??= [];
-            all_segments[segment_key].push([label, bs]);
-        }
+      for (const branch of bs.branches) {
+        const start_label = bs.qpoints[branch.start_index]?.label ?? undefined
+        const end_label = bs.qpoints[branch.end_index]?.label ?? undefined
+        const segment_key = helpers.get_segment_key(start_label, end_label)
+        all_segments[segment_key] ??= []
+        all_segments[segment_key].push([label, bs])
+      }
     }
-    return all_segments;
-});
-let num_structures = $derived(Object.keys(band_structs_dict).length);
-let all_segment_keys = $derived(Object.keys(all_segments));
-let common_segment_keys = $derived.by(() => all_segment_keys.filter((segment_key) => all_segments[segment_key].length === num_structures));
-let empty_state_attrs = $derived.by(() => {
-    const attrs = {};
+    return all_segments
+  })
+
+  let num_structures = $derived(Object.keys(band_structs_dict).length)
+  let all_segment_keys = $derived(Object.keys(all_segments))
+  let common_segment_keys = $derived.by(() =>
+    all_segment_keys.filter(
+      (segment_key) => all_segments[segment_key].length === num_structures,
+    )
+  )
+  let empty_state_attrs = $derived.by(() => {
+    const attrs: Record<string, Dom_attr_value> = {}
     for (const [attr_name, attr_value] of Object.entries(rest)) {
-        if ((attr_name === `role` || attr_name.startsWith(`aria-`)) &&
-            is_dom_attr_value(attr_value)) {
-            attrs[attr_name] = attr_value;
-        }
+      if (
+        (attr_name === `role` || attr_name.startsWith(`aria-`)) &&
+        is_dom_attr_value(attr_value)
+      ) {
+        attrs[attr_name] = attr_value
+      }
     }
-    return attrs;
-});
-// Compute path mismatch details for strict mode handling
-let strict_path_error = $derived.by(() => {
-    if (path_mode !== `strict`)
-        return null;
+    return attrs
+  })
+
+  // Compute path mismatch details for strict mode handling
+  let strict_path_error = $derived.by((): string | null => {
+    if (path_mode !== `strict`) return null
     return common_segment_keys.length === all_segment_keys.length
-        ? null
-        : `Band structures have different q-point paths. Switch to path_mode="union" or "intersection" to compare non-identical paths.`;
-});
-// Determine which segments to plot based on path_mode
-let segments_to_plot = $derived.by(() => {
-    if (path_mode === `union`)
-        return new Set(all_segment_keys);
-    return new Set(common_segment_keys);
-});
-// Map segments to x-axis positions
-$effect(() => {
+      ? null
+      : `Band structures have different q-point paths. Switch to path_mode="union" or "intersection" to compare non-identical paths.`
+  })
+
+  // Determine which segments to plot based on path_mode
+  let segments_to_plot = $derived.by(() => {
+    if (path_mode === `union`) return new Set(all_segment_keys)
+    return new Set(common_segment_keys)
+  })
+
+  // Map segments to x-axis positions
+  $effect(() => {
     if (Object.keys(band_structs_dict).length === 0 || segments_to_plot.size === 0) {
-        x_positions = {};
-        return;
+      x_positions = {}
+      return
     }
-    const positions = {};
-    let current_x = 0;
+    const positions: Record<string, [number, number]> = {}
+    let current_x = 0
+
     // Preserve physical path order using the first available structure
-    const canonical = Object.values(band_structs_dict)[0];
+    const canonical = Object.values(band_structs_dict)[0]
     if (!canonical) {
-        x_positions = {};
-        return;
+      x_positions = {}
+      return
     }
-    const ordered_segments = helpers.get_ordered_segments(canonical, segments_to_plot);
+    const ordered_segments = helpers.get_ordered_segments(canonical, segments_to_plot)
+
     for (let seg_idx = 0; seg_idx < ordered_segments.length; seg_idx++) {
-        const segment_key = ordered_segments[seg_idx];
-        if (positions[segment_key])
-            continue;
-        const [start_label, end_label] = segment_key.split(`_`);
-        // Find the first band structure that has this segment
-        for (const bs of Object.values(band_structs_dict)) {
-            const matching_branch = bs.branches.find((branch) => {
-                const branch_start = bs.qpoints[branch.start_index]?.label || `null`;
-                const branch_end = bs.qpoints[branch.end_index]?.label || `null`;
-                return branch_start === start_label && branch_end === end_label;
-            });
-            if (matching_branch) {
-                // Check if this is a discontinuity: consecutive indices mean no path between points
-                const is_discontinuity = matching_branch.end_index - matching_branch.start_index === 1;
-                if (is_discontinuity) {
-                    // Place at same x position as current, no advancement
-                    positions[segment_key] = [current_x, current_x];
-                }
-                else {
-                    const segment_len = bs.distance[matching_branch.end_index] -
-                        bs.distance[matching_branch.start_index];
-                    positions[segment_key] = [current_x, current_x + segment_len];
-                    current_x += segment_len;
-                }
-                break;
-            }
+      const segment_key = ordered_segments[seg_idx]
+      if (positions[segment_key]) continue
+
+      const [start_label, end_label] = segment_key.split(`_`)
+
+      // Find the first band structure that has this segment
+      for (const bs of Object.values(band_structs_dict)) {
+        const matching_branch = bs.branches.find((branch) => {
+          const branch_start = bs.qpoints[branch.start_index]?.label || `null`
+          const branch_end = bs.qpoints[branch.end_index]?.label || `null`
+          return branch_start === start_label && branch_end === end_label
+        })
+
+        if (matching_branch) {
+          // Check if this is a discontinuity: consecutive indices mean no path between points
+          const is_discontinuity =
+            matching_branch.end_index - matching_branch.start_index === 1
+
+          if (is_discontinuity) {
+            // Place at same x position as current, no advancement
+            positions[segment_key] = [current_x, current_x]
+          } else {
+            const segment_len = bs.distance[matching_branch.end_index] -
+              bs.distance[matching_branch.start_index]
+            positions[segment_key] = [current_x, current_x + segment_len]
+            current_x += segment_len
+          }
+          break
         }
+      }
     }
-    x_positions = positions;
-});
-// Convert band structures to scatter plot series + track max slope in one pass
-let { series_data, max_abs_slope } = $derived.by(() => {
+
+    x_positions = positions
+  })
+
+  // Convert band structures to scatter plot series + track max slope in one pass
+  let { series_data, max_abs_slope } = $derived.by((): {
+    series_data: DataSeries[]
+    max_abs_slope: number
+  } => {
     if (Object.keys(band_structs_dict).length === 0 || segments_to_plot.size === 0) {
-        return { series_data: [], max_abs_slope: 1 };
+      return { series_data: [], max_abs_slope: 1 }
     }
-    const all_series = [];
-    let max_slope = 0;
+
+    const all_series: DataSeries[] = []
+    let max_slope = 0
+
     for (const [bs_idx, [label, bs]] of Object.entries(band_structs_dict).entries()) {
-        const color = PLOT_COLORS[bs_idx % PLOT_COLORS.length];
-        const structure_label = label || `Structure ${bs_idx + 1}`;
-        const gamma_indices = detected_band_type === `phonon`
-            ? helpers.find_gamma_indices(bs)
-            : [];
-        for (const branch of bs.branches) {
-            const start_idx = branch.start_index;
-            const end_idx = branch.end_index + 1;
-            const start_label = bs.qpoints[start_idx]?.label ?? undefined;
-            const end_label = bs.qpoints[end_idx - 1]?.label ?? undefined;
-            const segment_key = helpers.get_segment_key(start_label, end_label);
-            if (!segments_to_plot.has(segment_key))
-                continue;
-            // Skip discontinuous segments (consecutive labeled points)
-            const is_discontinuity = branch.end_index - branch.start_index === 1;
-            if (is_discontinuity)
-                continue;
-            const [x_start, x_end] = x_positions?.[segment_key] || [0, 1];
-            // Scale distances for this segment
-            const segment_distances = bs.distance.slice(start_idx, end_idx);
-            const scaled_distances = helpers.scale_segment_distances(segment_distances, x_start, x_end);
-            // Create series for each band (and spin channel for electronic structures)
-            for (let band_idx = 0; band_idx < bs.nb_bands; band_idx++) {
-                const frequencies = convert_band_values(bs.bands[band_idx].slice(start_idx, end_idx));
-                const is_acoustic = helpers.classify_acoustic(bs, band_idx, gamma_indices);
-                const line_style_up = get_line_style(color, is_acoustic === true, frequencies, band_idx);
-                const spin_down_band = bs.spin_down_bands?.[band_idx];
-                const has_spin_down_channel = detected_band_type === `electronic` &&
-                    Array.isArray(spin_down_band) &&
-                    spin_down_band.length >= end_idx;
-                const track_max_slope = (meta) => {
-                    for (const pt of meta) {
-                        if (typeof pt.slope === `number` && Number.isFinite(pt.slope)) {
-                            max_slope = Math.max(max_slope, Math.abs(pt.slope));
-                        }
-                    }
-                };
-                if (effective_spin_mode !== `down_only`) {
-                    const meta = helpers.build_point_metadata({
-                        x_vals: scaled_distances,
-                        y_vals: frequencies,
-                        band_idx,
-                        spin: `up`,
-                        is_acoustic,
-                        bs,
-                        start_idx,
-                    });
-                    track_max_slope(meta);
-                    all_series.push({
-                        x: scaled_distances,
-                        y: frequencies,
-                        markers: `line`,
-                        label: has_spin_down_channel
-                            ? `${structure_label} (↑)`
-                            : structure_label,
-                        line_style: line_style_up,
-                        metadata: meta,
-                    });
-                }
-                if (has_spin_down_channel && effective_spin_mode !== `up_only`) {
-                    const spin_down_frequencies = convert_band_values(spin_down_band.slice(start_idx, end_idx));
-                    const meta = helpers.build_point_metadata({
-                        x_vals: scaled_distances,
-                        y_vals: spin_down_frequencies,
-                        band_idx,
-                        spin: `down`,
-                        is_acoustic,
-                        bs,
-                        start_idx,
-                    });
-                    track_max_slope(meta);
-                    all_series.push({
-                        x: scaled_distances,
-                        y: spin_down_frequencies,
-                        markers: `line`,
-                        label: `${structure_label} (↓)`,
-                        line_style: {
-                            ...line_style_up,
-                            line_dash: `4,2`,
-                            stroke_width: Math.max(1, line_style_up.stroke_width - 0.1),
-                        },
-                        metadata: meta,
-                    });
-                }
+      const color = PLOT_COLORS[bs_idx % PLOT_COLORS.length]
+      const structure_label = label || `Structure ${bs_idx + 1}`
+      const gamma_indices = detected_band_type === `phonon`
+        ? helpers.find_gamma_indices(bs)
+        : []
+
+      for (const branch of bs.branches) {
+        const start_idx = branch.start_index
+        const end_idx = branch.end_index + 1
+        const start_label = bs.qpoints[start_idx]?.label ?? undefined
+        const end_label = bs.qpoints[end_idx - 1]?.label ?? undefined
+        const segment_key = helpers.get_segment_key(start_label, end_label)
+
+        if (!segments_to_plot.has(segment_key)) continue
+
+        // Skip discontinuous segments (consecutive labeled points)
+        const is_discontinuity = branch.end_index - branch.start_index === 1
+        if (is_discontinuity) continue
+
+        const [x_start, x_end] = x_positions?.[segment_key] || [0, 1]
+
+        // Scale distances for this segment
+        const segment_distances = bs.distance.slice(start_idx, end_idx)
+        const scaled_distances = helpers.scale_segment_distances(
+          segment_distances,
+          x_start,
+          x_end,
+        )
+
+        // Create series for each band (and spin channel for electronic structures)
+        for (let band_idx = 0; band_idx < bs.nb_bands; band_idx++) {
+          const frequencies = convert_band_values(
+            bs.bands[band_idx].slice(start_idx, end_idx),
+          )
+          const is_acoustic = helpers.classify_acoustic(bs, band_idx, gamma_indices)
+
+          const line_style_up = get_line_style(
+            color,
+            is_acoustic === true,
+            frequencies,
+            band_idx,
+          )
+
+          const spin_down_band = bs.spin_down_bands?.[band_idx]
+          const has_spin_down_channel = detected_band_type === `electronic` &&
+            Array.isArray(spin_down_band) &&
+            spin_down_band.length >= end_idx
+
+          const track_max_slope = (meta: helpers.BandPointMeta[]) => {
+            for (const pt of meta) {
+              if (typeof pt.slope === `number` && Number.isFinite(pt.slope)) {
+                max_slope = Math.max(max_slope, Math.abs(pt.slope))
+              }
             }
+          }
+
+          if (effective_spin_mode !== `down_only`) {
+            const meta = helpers.build_point_metadata({
+              x_vals: scaled_distances,
+              y_vals: frequencies,
+              band_idx,
+              spin: `up`,
+              is_acoustic,
+              bs,
+              start_idx,
+            })
+            track_max_slope(meta)
+            all_series.push({
+              x: scaled_distances,
+              y: frequencies,
+              markers: `line`,
+              label: has_spin_down_channel
+                ? `${structure_label} (↑)`
+                : structure_label,
+              line_style: line_style_up,
+              metadata: meta,
+            })
+          }
+
+          if (has_spin_down_channel && effective_spin_mode !== `up_only`) {
+            const spin_down_frequencies = convert_band_values(
+              spin_down_band.slice(start_idx, end_idx),
+            )
+            const meta = helpers.build_point_metadata({
+              x_vals: scaled_distances,
+              y_vals: spin_down_frequencies,
+              band_idx,
+              spin: `down`,
+              is_acoustic,
+              bs,
+              start_idx,
+            })
+            track_max_slope(meta)
+            all_series.push({
+              x: scaled_distances,
+              y: spin_down_frequencies,
+              markers: `line`,
+              label: `${structure_label} (↓)`,
+              line_style: {
+                ...line_style_up,
+                line_dash: `4,2`,
+                stroke_width: Math.max(1, line_style_up.stroke_width - 0.1),
+              },
+              metadata: meta,
+            })
+          }
         }
+      }
     }
-    return { series_data: all_series, max_abs_slope: max_slope || 1 };
-});
-// Compute ribbon data for bands with width information
-let ribbon_data = $derived.by(() => {
+
+    return { series_data: all_series, max_abs_slope: max_slope || 1 }
+  })
+
+  // Compute ribbon data for bands with width information
+  let ribbon_data = $derived.by((): RibbonData[] => {
     if (Object.keys(band_structs_dict).length === 0 || segments_to_plot.size === 0) {
-        return [];
+      return []
     }
-    const all_ribbons = [];
+
+    const all_ribbons: RibbonData[] = []
+
     for (const [bs_idx, [label, bs]] of Object.entries(band_structs_dict).entries()) {
-        // Skip if this band structure has no width data
-        if (!bs.band_widths || bs.band_widths.length === 0)
-            continue;
-        const color = PLOT_COLORS[bs_idx % PLOT_COLORS.length];
-        const structure_label = label || `Structure ${bs_idx + 1}`;
-        const config = helpers.get_ribbon_config(ribbon_config, label);
-        for (const branch of bs.branches) {
-            const start_idx = branch.start_index;
-            const end_idx = branch.end_index + 1;
-            const start_label = bs.qpoints[start_idx]?.label ?? undefined;
-            const end_label = bs.qpoints[end_idx - 1]?.label ?? undefined;
-            const segment_key = helpers.get_segment_key(start_label, end_label);
-            if (!segments_to_plot.has(segment_key))
-                continue;
-            // Skip discontinuous segments
-            const is_discontinuity = branch.end_index - branch.start_index === 1;
-            if (is_discontinuity)
-                continue;
-            const [x_start, x_end] = x_positions?.[segment_key] || [0, 1];
-            // Scale distances for this segment
-            const segment_distances = bs.distance.slice(start_idx, end_idx);
-            const scaled_distances = helpers.scale_segment_distances(segment_distances, x_start, x_end);
-            // Create ribbon data for each band that has width data
-            for (let band_idx = 0; band_idx < bs.nb_bands; band_idx++) {
-                const band_widths = bs.band_widths[band_idx];
-                if (!band_widths)
-                    continue;
-                const width_values = band_widths.slice(start_idx, end_idx);
-                // Skip if all widths are zero or missing
-                if (width_values.every((wv) => !wv || wv <= 0))
-                    continue;
-                const y_values = convert_band_values(bs.bands[band_idx].slice(start_idx, end_idx));
-                all_ribbons.push({
-                    x_values: scaled_distances,
-                    y_values,
-                    width_values,
-                    color: config.color ?? color,
-                    opacity: config.opacity ?? 0.3,
-                    max_width: config.max_width ?? 6,
-                    scale: config.scale ?? 1,
-                    band_idx,
-                    structure_label,
-                    segment_key,
-                });
-            }
+      // Skip if this band structure has no width data
+      if (!bs.band_widths || bs.band_widths.length === 0) continue
+
+      const color = PLOT_COLORS[bs_idx % PLOT_COLORS.length]
+      const structure_label = label || `Structure ${bs_idx + 1}`
+      const config = helpers.get_ribbon_config(ribbon_config, label)
+
+      for (const branch of bs.branches) {
+        const start_idx = branch.start_index
+        const end_idx = branch.end_index + 1
+        const start_label = bs.qpoints[start_idx]?.label ?? undefined
+        const end_label = bs.qpoints[end_idx - 1]?.label ?? undefined
+        const segment_key = helpers.get_segment_key(start_label, end_label)
+
+        if (!segments_to_plot.has(segment_key)) continue
+
+        // Skip discontinuous segments
+        const is_discontinuity = branch.end_index - branch.start_index === 1
+        if (is_discontinuity) continue
+
+        const [x_start, x_end] = x_positions?.[segment_key] || [0, 1]
+
+        // Scale distances for this segment
+        const segment_distances = bs.distance.slice(start_idx, end_idx)
+        const scaled_distances = helpers.scale_segment_distances(
+          segment_distances,
+          x_start,
+          x_end,
+        )
+
+        // Create ribbon data for each band that has width data
+        for (let band_idx = 0; band_idx < bs.nb_bands; band_idx++) {
+          const band_widths = bs.band_widths[band_idx]
+          if (!band_widths) continue
+
+          const width_values = band_widths.slice(start_idx, end_idx)
+          // Skip if all widths are zero or missing
+          if (width_values.every((wv) => !wv || wv <= 0)) continue
+
+          const y_values = convert_band_values(
+            bs.bands[band_idx].slice(start_idx, end_idx),
+          )
+
+          all_ribbons.push({
+            x_values: scaled_distances,
+            y_values,
+            width_values,
+            color: config.color ?? color,
+            opacity: config.opacity ?? 0.3,
+            max_width: config.max_width ?? 6,
+            scale: config.scale ?? 1,
+            band_idx,
+            structure_label,
+            segment_key,
+          })
         }
+      }
     }
-    return all_ribbons;
-});
-// Get x-axis tick positions with custom labels for symmetry points
-let x_axis_ticks = $derived.by(() => {
-    const tick_map = new SvelteMap();
+
+    return all_ribbons
+  })
+
+  // Get x-axis tick positions with custom labels for symmetry points
+  let x_axis_ticks = $derived.by(() => {
+    const tick_map = new SvelteMap<number, string[]>()
+    const add_label = (pos: number, label: string) => {
+      let labels = tick_map.get(pos)
+      if (!labels) {
+        labels = []
+        tick_map.set(pos, labels)
+      }
+      if (!labels.includes(label)) labels.push(label)
+    }
+
     Object.entries(x_positions ?? {})
-        .sort(([, [a]], [, [b]]) => a - b)
-        .forEach(([segment_key, [x_start, x_end]]) => {
-        const [start_lbl, end_lbl] = segment_key.split(`_`);
+      .sort(([, [a]], [, [b]]) => a - b)
+      .forEach(([segment_key, [x_start, x_end]]) => {
+        const [start_lbl, end_lbl] = segment_key.split(`_`)
         const pretty_start = start_lbl !== `null`
-            ? helpers.pretty_sym_point(start_lbl)
-            : ``;
-        const pretty_end = end_lbl !== `null` ? helpers.pretty_sym_point(end_lbl) : ``;
+          ? helpers.pretty_sym_point(start_lbl)
+          : ``
+        const pretty_end = end_lbl !== `null` ? helpers.pretty_sym_point(end_lbl) : ``
+
         // Check if this is a discontinuity (zero-length segment)
-        const is_discontinuity = Math.abs(x_end - x_start) < 1e-6;
+        const is_discontinuity = Math.abs(x_end - x_start) < 1e-6
+
         if (is_discontinuity && pretty_start && pretty_end) {
-            // Combine labels at discontinuity points
-            if (!tick_map.has(x_start))
-                tick_map.set(x_start, []);
-            const labels = tick_map.get(x_start);
-            if (!labels.includes(pretty_start))
-                labels.push(pretty_start);
-            if (!labels.includes(pretty_end))
-                labels.push(pretty_end);
+          // Combine labels at discontinuity points
+          add_label(x_start, pretty_start)
+          add_label(x_start, pretty_end)
+        } else {
+          // Normal segment with distinct start/end
+          if (pretty_start) add_label(x_start, pretty_start)
+          if (pretty_end) add_label(x_end, pretty_end)
         }
-        else {
-            // Normal segment with distinct start/end
-            if (pretty_start) {
-                if (!tick_map.has(x_start))
-                    tick_map.set(x_start, []);
-                const labels = tick_map.get(x_start);
-                if (!labels.includes(pretty_start))
-                    labels.push(pretty_start);
-            }
-            if (pretty_end) {
-                if (!tick_map.has(x_end))
-                    tick_map.set(x_end, []);
-                const labels = tick_map.get(x_end);
-                if (!labels.includes(pretty_end))
-                    labels.push(pretty_end);
-            }
-        }
-    });
+      })
+
     // Merge labels at same position with pipe separator
-    return Object.fromEntries(Array.from(tick_map.entries()).map(([pos, labels]) => [
+    return Object.fromEntries(
+      Array.from(tick_map.entries()).map(([pos, labels]) => [
         pos,
         labels.join(` | `),
-    ]));
-});
-let x_range = $derived.by(() => {
-    const flat = Object.values(x_positions ?? {}).flat();
-    return [flat[0] ?? 0, flat.at(-1) ?? 1];
-});
-// Calculate y-range, enforcing 0 minimum for phonon bands without imaginary modes
-let y_range = $derived.by(() => {
+      ]),
+    )
+  })
+
+  let x_range = $derived.by((): Vec2 => {
+    const flat = Object.values(x_positions ?? {}).flat()
+    return [flat[0] ?? 0, flat.at(-1) ?? 1]
+  })
+
+  // Calculate y-range, enforcing 0 minimum for phonon bands without imaginary modes
+  let y_range = $derived.by((): Vec2 | undefined => {
     const all_freqs = Object.values(band_structs_dict).flatMap((bs) => [
-        ...bs.bands.flat(),
-        ...(bs.spin_down_bands?.flat() ?? []),
-    ]);
+      ...bs.bands.flat(),
+      ...(bs.spin_down_bands?.flat() ?? []),
+    ])
     // Keep electronic y-range independent of phonon unit conversion options.
     const display_values = detected_band_type === `phonon`
-        ? convert_band_values(all_freqs)
-        : all_freqs;
-    if (!display_values.length)
-        return undefined;
-    const finite = display_values.filter(Number.isFinite);
-    if (!finite.length)
-        return undefined;
-    let min_val = Math.min(...finite), max_val = Math.max(...finite);
+      ? convert_band_values(all_freqs)
+      : all_freqs
+    if (!display_values.length) return undefined
+    const finite = display_values.filter(Number.isFinite)
+    if (!finite.length) return undefined
+    let min_val = Math.min(...finite), max_val = Math.max(...finite)
     if (
-    // clamp phonon min to 0 if negatives are noise
-    detected_band_type === `phonon` && min_val < 0 &&
-        helpers.negative_fraction(finite) < helpers.IMAGINARY_MODE_NOISE_THRESHOLD) {
-        min_val = 0;
+      // clamp phonon min to 0 if negatives are noise
+      detected_band_type === `phonon` && min_val < 0 &&
+      helpers.negative_fraction(finite) < helpers.IMAGINARY_MODE_NOISE_THRESHOLD
+    ) {
+      min_val = 0
     }
-    const padding = (max_val - min_val) * 0.02;
-    return [min_val === 0 ? 0 : min_val - padding, max_val + padding];
-});
-// Internal y_axis that ScatterPlot binds to - syncs zoom changes back to parent
-let internal_y_axis = $derived({
+    const padding = (max_val - min_val) * 0.02
+    return [min_val === 0 ? 0 : min_val - padding, max_val + padding]
+  })
+
+  // Internal y_axis that ScatterPlot binds to - syncs zoom changes back to parent
+  let internal_y_axis = $derived({
     label: detected_band_type === `phonon` ? `Frequency (${units})` : `Energy (eV)`,
     format: `.2f`,
     label_shift: { y: 15 },
     range: y_range,
     ...y_axis,
-});
-// Sync zoom changes from ScatterPlot back to parent via bindable y_axis
-// Also clears parent range when internal range becomes invalid (auto-range reset)
-$effect(() => {
-    const range = internal_y_axis.range;
+  })
+
+  // Sync zoom changes from ScatterPlot back to parent via bindable y_axis
+  // Also clears parent range when internal range becomes invalid (auto-range reset)
+  $effect(() => {
+    const range = internal_y_axis.range
     if (helpers.is_valid_range(range)) {
-        if (y_axis.range?.[0] !== range[0] || y_axis.range?.[1] !== range[1]) {
-            y_axis = { ...y_axis, range };
-        }
-        return;
+      if (y_axis.range?.[0] !== range[0] || y_axis.range?.[1] !== range[1]) {
+        y_axis = { ...y_axis, range }
+      }
+      return
     }
     // Range became invalid - clear parent's range to propagate reset
     if (`range` in y_axis) {
-        const { range: _omit, ...rest } = y_axis;
-        y_axis = rest;
+      const { range: _omit, ...rest } = y_axis
+      y_axis = rest
     }
-});
-let has_series = $derived(series_data.length > 0);
-let is_strict_path_error = $derived(path_mode === `strict` && !!strict_path_error);
-let imaginary_mode_region = $derived.by(() => {
-    if (detected_band_type !== `phonon` ||
-        !shade_imaginary_modes ||
-        !y_range ||
-        y_range[0] >= 0)
-        return [];
+  })
+
+  let has_series = $derived(series_data.length > 0)
+  let is_strict_path_error = $derived(path_mode === `strict` && !!strict_path_error)
+
+  let imaginary_mode_region = $derived.by((): FillRegion[] => {
+    if (
+      detected_band_type !== `phonon` ||
+      !shade_imaginary_modes ||
+      !y_range ||
+      y_range[0] >= 0
+    ) return []
     return [{
-            lower: y_range[0],
-            upper: 0,
-            fill: `var(--bands-imaginary-region-color, light-dark(#f8d7da, #5a1a1f))`,
-            fill_opacity: 0.2,
-            label: `Imaginary modes`,
-            show_in_legend: false,
-            z_index: `below-lines`,
-        }];
-});
-let custom_highlight_regions = $derived.by(() => (highlight_regions ?? [])
-    .filter((region) => Number.isFinite(region.y_min) && Number.isFinite(region.y_max))
-    .map((region) => ({
-    lower: Math.min(region.y_min, region.y_max),
-    upper: Math.max(region.y_min, region.y_max),
-    fill: region.color ??
-        `var(--bands-highlight-region-color, light-dark(#f6e8c3, #4d3f20))`,
-    fill_opacity: region.opacity ?? 0.2,
-    label: region.label,
-    show_in_legend: Boolean(region.label),
-    z_index: `below-lines`,
-})));
-let fill_regions = $derived([
+      lower: y_range[0],
+      upper: 0,
+      fill: `var(--bands-imaginary-region-color, light-dark(#f8d7da, #5a1a1f))`,
+      fill_opacity: 0.2,
+      label: `Imaginary modes`,
+      show_in_legend: false,
+      z_index: `below-lines`,
+    }]
+  })
+
+  let custom_highlight_regions = $derived.by((): FillRegion[] =>
+    (highlight_regions ?? [])
+      .filter((region) =>
+        Number.isFinite(region.y_min) && Number.isFinite(region.y_max)
+      )
+      .map((region) => ({
+        lower: Math.min(region.y_min, region.y_max),
+        upper: Math.max(region.y_min, region.y_max),
+        fill: region.color ??
+          `var(--bands-highlight-region-color, light-dark(#f6e8c3, #4d3f20))`,
+        fill_opacity: region.opacity ?? 0.2,
+        label: region.label,
+        show_in_legend: Boolean(region.label),
+        z_index: `below-lines` as const,
+      }))
+  )
+
+  let fill_regions = $derived([
     ...imaginary_mode_region,
     ...custom_highlight_regions,
-]);
-let electronic_gap_annotation = $derived.by(() => {
-    if (!show_gap_annotation ||
-        detected_band_type !== `electronic` ||
-        effective_fermi_level === undefined)
-        return null;
-    const all_energies = series_data.flatMap((series_item) => series_item.y.filter(Number.isFinite));
-    const occupied = all_energies.filter((energy) => energy <= effective_fermi_level);
-    const unoccupied = all_energies.filter((energy) => energy > effective_fermi_level);
-    if (!occupied.length || !unoccupied.length)
-        return null;
-    const vbm = Math.max(...occupied);
-    const cbm = Math.min(...unoccupied);
-    const gap = cbm - vbm;
-    if (!(gap > 0))
-        return null;
-    return { vbm, cbm, gap };
-});
-let empty_state_message = $derived.by(() => {
+  ])
+
+  let electronic_gap_annotation = $derived.by(() => {
+    if (
+      !show_gap_annotation ||
+      detected_band_type !== `electronic` ||
+      effective_fermi_level === undefined
+    ) return null
+    const all_energies = series_data.flatMap((series_item) =>
+      series_item.y.filter(Number.isFinite)
+    )
+    const occupied = all_energies.filter((energy) => energy <= effective_fermi_level)
+    const unoccupied = all_energies.filter((energy) => energy > effective_fermi_level)
+    if (!occupied.length || !unoccupied.length) return null
+    const vbm = Math.max(...occupied)
+    const cbm = Math.min(...unoccupied)
+    const gap = cbm - vbm
+    if (!(gap > 0)) return null
+    return { vbm, cbm, gap }
+  })
+
+  let empty_state_message = $derived.by(() => {
     if (is_strict_path_error) {
-        return strict_path_error ?? `Path mismatch in strict mode.`;
+      return strict_path_error ?? `Path mismatch in strict mode.`
     }
     if (!band_structs || Object.keys(band_structs_dict).length === 0) {
-        return `No valid band structure data to display.`;
+      return `No valid band structure data to display.`
     }
     if (!has_series) {
-        return `No plottable band segments were found in the provided data.`;
+      return `No plottable band segments were found in the provided data.`
     }
-    return `No valid band structure data to display.`;
-});
-let display = $state({ x_grid: false, y_grid: true, y_zero_line: true });
+    return `No valid band structure data to display.`
+  })
+
+  let display = $state({ x_grid: false, y_grid: true, y_zero_line: true })
 </script>
 {#if has_series && !is_strict_path_error}
   <ScatterPlot
@@ -573,7 +752,7 @@ let display = $state({ x_grid: false, y_grid: true, y_zero_line: true });
     } = (metadata ?? {}) as Partial<helpers.BandPointMeta>}
       {@const num_structs = Object.keys(band_structs_dict).length}
       {#if num_structs > 1 && label}<strong>{label}</strong><br />{/if}
-      {@html y_label || `Value`}: {y_formatted}{y_unit ? ` ${y_unit}` : ``}<br />
+      {@html sanitize_html(y_label || `Value`)}: {y_formatted}{y_unit ? ` ${y_unit}` : ``}<br />
       {#if path}Path: {path}<br />{/if}
       {#if typeof band_idx === `number`}
         Band: {band_idx + 1}{#if typeof nb_bands === `number`}&thinsp;/&thinsp;{
@@ -774,7 +953,7 @@ let display = $state({ x_grid: false, y_grid: true, y_zero_line: true });
       {/if}
 
       <!-- Reference frequency horizontal line -->
-      {@const ref_freq = reference_frequency !== null && reference_frequency !== undefined
+      {@const ref_freq = reference_frequency != null
       ? convert_band_values([reference_frequency])[0]
       : NaN}
       {@const ref_y = Number.isFinite(ref_freq) ? y_scale_fn(ref_freq) : NaN}