matterviz 0.3.1 → 0.3.3

package/dist/spectral/Bands.svelte

@@ -1,409 +1,868 @@
-<script lang="ts">import { PLOT_COLORS } from '../colors';
-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, ...rest } = $props();
-// Helper function to get line styling for a band
-function get_line_style(color, is_acoustic, mode_type, frequencies, band_idx) {
-    const defaults = { stroke: color, stroke_width: is_acoustic ? 1.5 : 1 };
+<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: 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_kwargs = line_kwargs[mode_type];
-        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;
+      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
+      }
     }
-    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;
-});
-// Determine which segments to plot based on path_mode
-let segments_to_plot = $derived.by(() => {
-    const all_segments = {};
-    // Collect all segments from all structures
+    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: 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])
+      }
     }
-    const num_structs = Object.keys(band_structs_dict).length;
-    const is_intersection = path_mode === `strict` || path_mode === `intersection`;
-    if (is_intersection) {
-        // Only segments present in all structures
-        const common_segments = Object.keys(all_segments).filter((seg) => all_segments[seg].length === num_structs);
-        // Warn in strict mode if not all segments are common
-        if (path_mode === `strict` &&
-            common_segments.length !== Object.keys(all_segments).length) {
-            console.warn(`Band structures have different q-point paths. Use path_mode="union" or "intersection".`);
-        }
-        return new Set(common_segments);
+    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
+      }
+    }
+    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(() => {
+    if (Object.keys(band_structs_dict).length === 0 || segments_to_plot.size === 0) {
+      x_positions = {}
+      return
     }
-    // union - all segments
-    return new Set(Object.keys(all_segments));
-});
-// Map segments to x-axis positions
-$effect(() => {
-    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 ordered_segments = helpers.get_ordered_segments(canonical, segments_to_plot);
+    const canonical = Object.values(band_structs_dict)[0]
+    if (!canonical) {
+      x_positions = {}
+      return
+    }
+    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
-let series_data = $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 [];
+      return { series_data: [], max_abs_slope: 1 }
     }
-    const all_series = [];
+
+    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}`;
-        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
-            for (let band_idx = 0; band_idx < bs.nb_bands; band_idx++) {
-                const frequencies = bs.bands[band_idx].slice(start_idx, end_idx);
-                const is_acoustic = detected_band_type === `phonon` &&
-                    band_idx < helpers.N_ACOUSTIC_MODES;
-                const mode_type = is_acoustic ? `acoustic` : `optical`;
-                const line_style = get_line_style(color, is_acoustic, mode_type, frequencies, band_idx);
-                all_series.push({
-                    x: scaled_distances,
-                    y: frequencies,
-                    markers: `line`,
-                    label: structure_label,
-                    line_style,
-                    metadata: { band_idx },
-                });
+      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 all_series;
-});
-// 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 = 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<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)
     }
-    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();
+
     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);
-        }
-        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);
-            }
+          // 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)
         }
-    });
+      })
+
     // 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(() => {
-    const all_freqs = Object.values(band_structs_dict).flatMap((bs) => bs.bands.flat());
-    const finite = all_freqs.filter(Number.isFinite);
-    if (!finite.length)
-        return undefined;
-    let min_val = Math.min(...finite), max_val = Math.max(...finite);
+      ]),
+    )
+  })
+
+  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() ?? []),
+    ])
+    // 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)
     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({
-    label: detected_band_type === `phonon` ? `Frequency (THz)` : `Energy (eV)`,
+    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 display = $state({ x_grid: false, y_grid: true, y_zero_line: true });
-</script>
+  })
+
+  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((): 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(() => {
+    if (is_strict_path_error) {
+      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.`
+    }
+    if (!has_series) {
+      return `No plottable band segments were found in the provided data.`
+    }
+    return `No valid band structure data to display.`
+  })
 
-<ScatterPlot
-  series={series_data}
-  x_axis={{
-    label: `Wave Vector`,
-    ticks: Object.keys(x_axis_ticks).length > 0 ? x_axis_ticks : undefined,
-    format: ``,
-    range: x_range,
-    ...x_axis,
-  }}
-  bind:y_axis={internal_y_axis}
-  bind:display
-  legend={show_legend && Object.keys(band_structs_dict).length > 1 ? {} : null}
-  hover_config={{ threshold_px: 50 }}
-  {...rest}
->
-  {#snippet tooltip({ x, y_formatted, label, metadata })}
-    {@const y_label_full = internal_y_axis.label ?? ``}
-    {@const [, y_label, y_unit] = y_label_full.match(/^(.+?)\s*\(([^)]+)\)$/) ??
+  let display = $state({ x_grid: false, y_grid: true, y_zero_line: true })
+</script>
+{#if has_series && !is_strict_path_error}
+  <ScatterPlot
+    {id}
+    class={class_name}
+    {style}
+    data-testid={data_testid}
+    series={series_data}
+    {fill_regions}
+    x_axis={{
+      label: `Wave Vector`,
+      ticks: Object.keys(x_axis_ticks).length > 0 ? x_axis_ticks : undefined,
+      format: ``,
+      range: x_range,
+      ...x_axis,
+    }}
+    bind:y_axis={internal_y_axis}
+    bind:display
+    legend={show_legend && Object.keys(band_structs_dict).length > 1 ? {} : null}
+    hover_config={{ threshold_px: 50 }}
+    controls={{ show: show_controls }}
+    {...rest}
+  >
+    {#snippet tooltip({ x, y, y_formatted, label, metadata })}
+      {@const y_label_full = internal_y_axis.label ?? ``}
+      {@const [, y_label, y_unit] = y_label_full.match(/^(.+?)\s*\(([^)]+)\)$/) ??
       [, y_label_full, ``]}
-    {@const segment = Object.entries(x_positions ?? {}).find(([, [start, end]]) =>
+      {@const segment = Object.entries(x_positions ?? {}).find(([, [start, end]]) =>
       x >= start && x <= end
     )}
-    {@const path = segment?.[0].split(`_`).map((lbl) =>
+      {@const path = segment?.[0].split(`_`).map((lbl) =>
       lbl !== `null` ? helpers.pretty_sym_point(lbl) : ``
     ).filter(Boolean).join(` → `) || null}
-    {@const band_idx = metadata?.band_idx}
-    {@const num_structs = Object.keys(band_structs_dict).length}
-    {#if num_structs > 1 && label}<strong>{label}</strong><br />{/if}
-    {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}
-  {/snippet}
-
-  {#snippet user_content({ height, x_scale_fn, y_scale_fn, pad })}
-    <!-- Fat band ribbons (rendered behind band lines) -->
-    {#each ribbon_data as
-      ribbon
-      (`${ribbon.structure_label}-${ribbon.segment_key}-${ribbon.band_idx}`)
-    }
-      {@const path_d = helpers.generate_ribbon_path(
+      {@const {
+      band_idx,
+      spin,
+      is_acoustic,
+      nb_bands,
+      frac_coords,
+      qpoint_label,
+      band_width,
+      slope,
+    } = (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 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;{
+            nb_bands
+          }{/if}
+        {#if typeof is_acoustic === `boolean`}
+          ({is_acoustic ? `acoustic` : `optical`})
+        {:else if detected_band_type === `electronic` && effective_fermi_level !== undefined}
+          ({y <= effective_fermi_level ? `valence` : `conduction`})
+        {/if}
+        {#if spin === `up` || spin === `down`}
+          {spin === `up` ? `↑` : `↓`}
+        {/if}
+      {/if}
+      {#if typeof qpoint_label === `string` && qpoint_label}
+        <br />At: {helpers.pretty_sym_point(qpoint_label)}
+      {/if}
+      {#if Array.isArray(frac_coords)}
+        <br />{detected_band_type === `electronic` ? `k` : `q`}: [{
+          frac_coords.map((coord: number) => format_num(coord, `.3f`)).join(`, `)
+        }]
+      {/if}
+      {#if typeof band_width === `number` && band_width > 0}
+        <br />Projection: {format_num(band_width, `.3~g`)}
+      {/if}
+      {#if typeof slope === `number` && Number.isFinite(slope)}
+        {@const rel = Math.abs(slope) / max_abs_slope}
+        <br />Dispersion: {rel < 0.15 ? `flat` : rel < 0.5 ? `moderate` : `steep`}
+      {/if}
+    {/snippet}
+
+    {#snippet controls_extra()}
+      {#if show_path_mode_control}
+        <SettingsSection
+          title="Path Mode"
+          current_values={{ path_mode }}
+          on_reset={() => (path_mode = `strict`)}
+        >
+          <div class="pane-row">
+            <label for="bands-path-mode">Mode:</label>
+            <select id="bands-path-mode" bind:value={path_mode}>
+              <option value="strict">strict</option>
+              <option value="intersection">intersection</option>
+              <option value="union">union</option>
+            </select>
+          </div>
+        </SettingsSection>
+      {/if}
+
+      {#if show_units_control && detected_band_type === `phonon`}
+        <SettingsSection
+          title="Units"
+          current_values={{ units }}
+          on_reset={() => (units = `THz`)}
+        >
+          <div class="pane-row">
+            <label for="bands-units">Frequency:</label>
+            <select id="bands-units" bind:value={units}>
+              <option value="THz">THz</option>
+              <option value="eV">eV</option>
+              <option value="meV">meV</option>
+              <option value="cm-1">cm-1</option>
+              <option value="Ha">Ha</option>
+            </select>
+          </div>
+        </SettingsSection>
+      {/if}
+
+      {#if show_spin_control && detected_band_type === `electronic`}
+        <SettingsSection
+          title="Spin Display"
+          current_values={{ band_spin_mode }}
+          on_reset={() => (band_spin_mode = `overlay`)}
+        >
+          <div class="pane-row">
+            <label for="bands-spin-mode">Mode:</label>
+            <select id="bands-spin-mode" bind:value={band_spin_mode}>
+              <option value="overlay">overlay</option>
+              <option value="up_only">up only</option>
+              <option value="down_only">down only</option>
+            </select>
+          </div>
+        </SettingsSection>
+      {/if}
+
+      {#if show_annotation_controls && detected_band_type === `electronic`}
+        <SettingsSection
+          title="Annotations"
+          current_values={{ show_gap_annotation }}
+          on_reset={() => (show_gap_annotation = true)}
+        >
+          <div class="pane-row pane-checkbox">
+            <input
+              id="bands-gap-annotation"
+              type="checkbox"
+              bind:checked={show_gap_annotation}
+            />
+            <label for="bands-gap-annotation">Show band gap annotation</label>
+          </div>
+        </SettingsSection>
+      {/if}
+    {/snippet}
+
+    {#snippet user_content({ height, x_scale_fn, y_scale_fn, pad })}
+      <!-- Fat band ribbons (rendered behind band lines) -->
+      {#each ribbon_data as
+        ribbon
+        (`${ribbon.structure_label}-${ribbon.segment_key}-${ribbon.band_idx}`)
+      }
+        {@const path_d = helpers.generate_ribbon_path(
       ribbon.x_values,
       ribbon.y_values,
       ribbon.width_values,
@@ -412,78 +871,170 @@ let display = $state({ x_grid: false, y_grid: true, y_zero_line: true });
       ribbon.max_width,
       ribbon.scale,
     )}
-      {#if path_d}
-        <path
-          d={path_d}
-          fill={ribbon.color}
-          opacity={ribbon.opacity}
-          stroke="none"
-          class="fat-band-ribbon"
-        />
-      {/if}
-    {/each}
+        {#if path_d}
+          <path
+            d={path_d}
+            fill={ribbon.color}
+            opacity={ribbon.opacity}
+            stroke="none"
+            class="fat-band-ribbon"
+          />
+        {/if}
+      {/each}
 
-    <!-- Symmetry point vertical lines (filter NaN from scale) -->
-    {#each Object.keys(x_axis_ticks).map(Number).map((x) => x_scale_fn(x)).filter(
+      <!-- Symmetry point vertical lines (filter NaN from scale) -->
+      {#each Object.keys(x_axis_ticks).map(Number).map((x) => x_scale_fn(x)).filter(
       Number.isFinite,
     ) as
-      scaled_x
-      (scaled_x)
-    }
-      <line
-        x1={scaled_x}
-        x2={scaled_x}
-        y1={pad.t}
-        y2={height - pad.b}
-        stroke="var(--bands-symmetry-line-color, light-dark(black, white))"
-        stroke-width="var(--bands-symmetry-line-width, 1)"
-        opacity="var(--bands-symmetry-line-opacity, 0.5)"
-      />
-    {/each}
-
-    <!-- Fermi level line for electronic bands -->
-    {@const fermi_y = effective_fermi_level !== undefined
+        scaled_x
+        (scaled_x)
+      }
+        <line
+          x1={scaled_x}
+          x2={scaled_x}
+          y1={pad.t}
+          y2={height - pad.b}
+          stroke="var(--bands-symmetry-line-color, light-dark(black, white))"
+          stroke-width="var(--bands-symmetry-line-width, 1)"
+          opacity="var(--bands-symmetry-line-opacity, 0.5)"
+        />
+      {/each}
+
+      <!-- Shared geometry for Fermi level and gap annotations -->
+      {@const fermi_y = effective_fermi_level !== undefined
       ? y_scale_fn(effective_fermi_level)
       : NaN}
-    {@const bands_x_end = x_scale_fn(Object.values(x_positions ?? {}).flat().at(-1) ?? 1)}
-    {#if Number.isFinite(fermi_y) && Number.isFinite(bands_x_end)}
-      <line
-        class="fermi-level-line"
-        x1={pad.l}
-        x2={bands_x_end}
-        y1={fermi_y}
-        y2={fermi_y}
-        stroke="var(--bands-fermi-line-color, light-dark(#e74c3c, #ff6b6b))"
-        stroke-width="var(--bands-fermi-line-width, 1.5)"
-        stroke-dasharray="var(--bands-fermi-line-dash, 6,3)"
-        opacity="var(--bands-fermi-line-opacity, 0.8)"
-      />
-      <text
-        class="fermi-level-label"
-        x={bands_x_end + 4}
-        y={fermi_y}
-        dy="0.35em"
-        font-size="10"
-        fill="var(--bands-fermi-line-color, light-dark(#e74c3c, #ff6b6b))"
-        opacity="0.9"
-      >
-        E<tspan dy="2" font-size="8">F</tspan>
-      </text>
-    {/if}
-
-    <!-- Reference frequency horizontal line -->
-    {@const ref_y = reference_frequency !== null ? y_scale_fn(reference_frequency) : NaN}
-    {#if Number.isFinite(ref_y) && Number.isFinite(bands_x_end)}
-      <line
-        x1={pad.l}
-        x2={bands_x_end}
-        y1={ref_y}
-        y2={ref_y}
-        stroke="var(--bands-reference-line-color, light-dark(#d48860, #c47850))"
-        stroke-width="var(--bands-reference-line-width, 1)"
-        stroke-dasharray="var(--bands-reference-line-dash, 4,3)"
-        opacity="var(--bands-reference-line-opacity, 0.5)"
-      />
-    {/if}
-  {/snippet}
-</ScatterPlot>
+      {@const bands_x_end = x_scale_fn(Object.values(x_positions ?? {}).flat().at(-1) ?? 1)}
+      {@const gap_data = electronic_gap_annotation}
+      {@const vbm_y = gap_data ? y_scale_fn(gap_data.vbm) : NaN}
+      {@const cbm_y = gap_data ? y_scale_fn(gap_data.cbm) : NaN}
+      {@const gap_mid_y = (vbm_y + cbm_y) / 2}
+      {@const ef_needs_offset = Number.isFinite(gap_mid_y) &&
+      Math.abs(fermi_y - gap_mid_y) < 16}
+      {@const ef_label_y = ef_needs_offset
+      ? gap_mid_y + (fermi_y >= gap_mid_y ? 16 : -16)
+      : fermi_y}
+
+      <!-- Fermi level line for electronic bands -->
+      {#if Number.isFinite(fermi_y) && Number.isFinite(bands_x_end)}
+        <line
+          class="fermi-level-line"
+          x1={pad.l}
+          x2={bands_x_end}
+          y1={fermi_y}
+          y2={fermi_y}
+          stroke="var(--bands-fermi-line-color, light-dark(#e74c3c, #ff6b6b))"
+          stroke-width="var(--bands-fermi-line-width, 1.5)"
+          stroke-dasharray="var(--bands-fermi-line-dash, 6,3)"
+          opacity="var(--bands-fermi-line-opacity, 0.8)"
+        />
+        {#if ef_needs_offset}
+          <line
+            x1={bands_x_end}
+            y1={fermi_y}
+            x2={bands_x_end + 3}
+            y2={ef_label_y}
+            stroke="var(--bands-fermi-line-color, light-dark(#e74c3c, #ff6b6b))"
+            stroke-width="0.7"
+            opacity="0.5"
+          />
+        {/if}
+        <text
+          class="fermi-level-label"
+          x={bands_x_end + 4}
+          y={ef_label_y}
+          dy="0.35em"
+          font-size="10"
+          fill="var(--bands-fermi-line-color, light-dark(#e74c3c, #ff6b6b))"
+          opacity="0.9"
+        >
+          E<tspan dy="2" font-size="8">F</tspan>
+        </text>
+      {/if}
+
+      <!-- Reference frequency horizontal line -->
+      {@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}
+      {#if Number.isFinite(ref_y) && Number.isFinite(bands_x_end)}
+        <line
+          x1={pad.l}
+          x2={bands_x_end}
+          y1={ref_y}
+          y2={ref_y}
+          stroke="var(--bands-reference-line-color, light-dark(#d48860, #c47850))"
+          stroke-width="var(--bands-reference-line-width, 1)"
+          stroke-dasharray="var(--bands-reference-line-dash, 4,3)"
+          opacity="var(--bands-reference-line-opacity, 0.5)"
+        />
+      {/if}
+
+      <!-- Electronic band edge and gap annotation -->
+      {#if gap_data && Number.isFinite(vbm_y) && Number.isFinite(cbm_y) &&
+      Number.isFinite(bands_x_end)}
+        {#each [
+      [vbm_y, `var(--bands-gap-vbm-color, light-dark(#1f77b4, #7db7ff))`],
+      [cbm_y, `var(--bands-gap-cbm-color, light-dark(#2ca02c, #7ddc7d))`],
+    ] as [number, string][] as
+          [edge_y, color]
+          (edge_y)
+        }
+          <line
+            x1={pad.l}
+            x2={bands_x_end + 3}
+            y1={edge_y}
+            y2={edge_y}
+            stroke={color}
+            stroke-width="var(--bands-gap-line-width, 1)"
+            stroke-dasharray="var(--bands-gap-line-dash, 2,2)"
+            opacity="0.7"
+          />
+        {/each}
+        <text
+          x={bands_x_end + 4}
+          y={gap_mid_y}
+          dy="0.35em"
+          font-size="10"
+          fill="var(--text-color)"
+        >
+          E<tspan dy="2" font-size="8">g:</tspan>
+          <tspan dy="-2">{Number(gap_data.gap.toPrecision(4))} eV</tspan>
+        </text>
+      {/if}
+    {/snippet}
+  </ScatterPlot>
+{:else}
+  <EmptyState
+    {id}
+    class={class_name}
+    {style}
+    data-testid={data_testid}
+    {...empty_state_attrs}
+    message={empty_state_message}
+  />
+{/if}
+
+<style>
+  .pane-row {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    margin: 0.3em 0;
+    font-size: 0.9em;
+  }
+  .pane-row label {
+    min-width: 4.5em;
+    flex-shrink: 0;
+  }
+  .pane-row select {
+    flex: 1;
+    min-width: 0;
+  }
+  .pane-checkbox {
+    gap: 0.4em;
+  }
+  .pane-checkbox label {
+    min-width: 0;
+  }
+</style>