matterviz 0.3.1 → 0.3.3

package/dist/structure/StructureScene.svelte

@@ -1,449 +1,907 @@
-<script lang="ts">import { AXIS_COLORS, NEG_AXIS_COLORS } from '../colors';
-import { element_data } from '../element';
-import Isosurface from '../isosurface/Isosurface.svelte';
-import { DEFAULT_ISOSURFACE_SETTINGS } from '../isosurface/types';
-import { format_num } from '../labels';
-import * as math from '../math';
-import { DEFAULTS } from '../settings';
-import { colors } from '../state.svelte';
-import { Arrow, atomic_radii, Cylinder, get_center_of_mass, Lattice, } from './';
-import { get_orig_site_idx, get_property_colors, } from './atom-properties';
-import * as measure from './measure';
-import { T, useThrelte } from '@threlte/core';
-import * as extras from '@threlte/extras';
-import { untrack } from 'svelte';
-import { SvelteMap, SvelteSet } from 'svelte/reactivity';
-import { Color } from 'three';
-import Bond from './Bond.svelte';
-import { BONDING_STRATEGIES, compute_bond_transform } from './bonding';
-import { CanvasTooltip } from './index';
-let pulse_time = $state(0);
-let pulse_opacity = $derived(0.15 + 0.25 * Math.sin(pulse_time * 5));
-$effect(() => {
-    if (!selected_sites?.length && !active_sites?.length)
-        return;
-    if (typeof globalThis === `undefined`)
-        return;
-    const reduce = globalThis.matchMedia?.(`(prefers-reduced-motion: reduce)`).matches;
-    if (reduce)
-        return;
-    let frame_id = 0;
+<script lang="ts">
+  import type { D3InterpolateName } from '../colors'
+  import { AXIS_COLORS, get_d3_interpolator, NEG_AXIS_COLORS } from '../colors'
+  import type { ElementSymbol } from '../element'
+  import { element_data } from '../element'
+  import Isosurface from '../isosurface/Isosurface.svelte'
+  import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types'
+  import { DEFAULT_ISOSURFACE_SETTINGS } from '../isosurface/types'
+  import { format_num } from '../labels'
+  import type { Vec3 } from '../math'
+  import * as math from '../math'
+  import type {
+    CameraProjection,
+    ShowBonds,
+    VectorColorMode,
+    VectorLayerConfig,
+  } from '../settings'
+  import { DEFAULTS } from '../settings'
+  import { sanitize_html } from '../sanitize'
+  import { colors } from '../state.svelte'
+  import type { AnyStructure, BondPair, MeasureMode, Site } from './'
+  import {
+    Arrow,
+    atomic_radii,
+    Cylinder,
+    get_all_site_vectors,
+    get_center_of_mass,
+    get_structure_vector_keys,
+    Lattice,
+    VECTOR_PALETTE,
+  } from './'
+  import type { AtomColorConfig } from './atom-properties'
+  import {
+    get_orig_site_idx,
+    get_property_colors,
+  } from './atom-properties'
+  import * as measure from './measure'
+  import {
+    compute_slice_geometry,
+    merge_split_partial_sites,
+    PARTIAL_OCCUPANCY_CAP_ARC,
+  } from './partial-occupancy'
+  import type { MoyoDataset } from '@spglib/moyo-wasm'
+  import { T, useThrelte } from '@threlte/core'
+  import * as extras from '@threlte/extras'
+  import { type ComponentProps, type Snippet, untrack } from 'svelte'
+  import { SvelteMap, SvelteSet } from 'svelte/reactivity'
+  import { type Camera, Color, type Mesh, type Scene } from 'three'
+  import Bond from './Bond.svelte'
+  import type { BondingStrategy } from './bonding'
+  import { BONDING_STRATEGIES, compute_bond_transform } from './bonding'
+  import { CanvasTooltip } from './index'
+
+  type InstancedAtomGroup = {
+    element: string
+    radius: number
+    color: string
+    is_image_atom: boolean
+    atoms: (typeof atom_data)[number][]
+  }
+
+  let pulse_time = $state(0)
+  let pulse_opacity = $derived(0.15 + 0.25 * Math.sin(pulse_time * 5))
+  $effect(() => {
+    if (!selected_sites?.length && !active_sites?.length) return
+    if (typeof globalThis === `undefined`) return
+    const reduce = globalThis.matchMedia?.(`(prefers-reduced-motion: reduce)`).matches
+    if (reduce) return
+    let frame_id = 0
     const animate = () => {
-        pulse_time += 0.015;
-        frame_id = requestAnimationFrame(animate);
-    };
-    frame_id = requestAnimationFrame(animate);
-    return () => cancelAnimationFrame(frame_id);
-});
-let { structure = undefined, base_structure = undefined, atom_radius = DEFAULTS.structure.atom_radius, same_size_atoms = false, camera_position = DEFAULTS.structure.camera_position, camera_projection = DEFAULTS.structure.camera_projection, rotation_damping = DEFAULTS.structure.rotation_damping, max_zoom = DEFAULTS.structure.max_zoom, min_zoom = DEFAULTS.structure.min_zoom, rotate_speed = DEFAULTS.structure.rotate_speed, zoom_speed = DEFAULTS.structure.zoom_speed, pan_speed = DEFAULTS.structure.pan_speed, zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor, show_atoms = DEFAULTS.structure.show_atoms, show_bonds = DEFAULTS.structure.show_bonds, show_site_labels = DEFAULTS.structure.show_site_labels, show_site_indices = DEFAULTS.structure.show_site_indices, site_label_size = DEFAULTS.structure.site_label_size, site_label_offset = $bindable(DEFAULTS.structure.site_label_offset), site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`, site_label_color = `#ffffff`, site_label_padding = 3, show_force_vectors = DEFAULTS.structure.show_force_vectors, force_scale = DEFAULTS.structure.force_scale, force_color = DEFAULTS.structure.force_color, gizmo = DEFAULTS.structure.show_gizmo, hovered_idx = $bindable(null), hovered_site = $bindable(null), float_fmt = `.3~f`, auto_rotate = DEFAULTS.structure.auto_rotate, bond_thickness = DEFAULTS.structure.bond_thickness, bond_color = DEFAULTS.structure.bond_color, bonding_strategy = DEFAULTS.structure.bonding_strategy, bonding_options = {}, fov = DEFAULTS.structure.fov, initial_zoom = DEFAULTS.structure.initial_zoom, ambient_light = DEFAULTS.structure.ambient_light, directional_light = DEFAULTS.structure.directional_light, sphere_segments = DEFAULTS.structure.sphere_segments, lattice_props = {}, atom_label, camera_is_moving = $bindable(false), width = 0, height = 0, measure_mode = `distance`, selected_sites = $bindable([]), measured_sites = $bindable([]), added_bonds = $bindable([]), removed_bonds = $bindable([]), selection_highlight_color = `#6cf0ff`, 
-// Active highlight group with different color
-active_sites = $bindable([]), active_highlight_color = `var(--struct-active-highlight-color, #2563eb)`, rotation = DEFAULTS.structure.rotation, scene = $bindable(), camera = $bindable(), orbit_controls = $bindable(), rotation_target_ref = $bindable(), initial_computed_zoom = $bindable(), hidden_elements = $bindable(new SvelteSet()), hidden_prop_vals = $bindable(new SvelteSet()), element_radius_overrides = $bindable({}), site_radius_overrides = $bindable(new SvelteMap()), atom_color_config = {
-    mode: DEFAULTS.structure.atom_color_mode,
-    scale: DEFAULTS.structure.atom_color_scale,
-    scale_type: DEFAULTS.structure.atom_color_scale_type,
-}, sym_data = null, 
-// Edit-atoms mode callbacks
-on_sites_moved, on_operation_start, on_add_atom, add_atom_mode = $bindable(false), add_element = $bindable(`C`), cursor = $bindable(`default`), dragging_atoms = $bindable(false), volumetric_data = undefined, isosurface_settings = DEFAULT_ISOSURFACE_SETTINGS, } = $props();
-const threlte = useThrelte();
-$effect(() => {
-    scene = threlte.scene;
-    camera = threlte.camera.current;
+      pulse_time += 0.015
+      frame_id = requestAnimationFrame(animate)
+    }
+    frame_id = requestAnimationFrame(animate)
+    return () => cancelAnimationFrame(frame_id)
+  })
+
+  let {
+    structure = undefined,
+    base_structure = undefined,
+    atom_radius = DEFAULTS.structure.atom_radius,
+    same_size_atoms = false,
+    camera_position = DEFAULTS.structure.camera_position,
+    camera_target = undefined,
+    camera_projection = DEFAULTS.structure.camera_projection,
+    rotation_damping = DEFAULTS.structure.rotation_damping,
+    max_zoom = DEFAULTS.structure.max_zoom,
+    min_zoom = DEFAULTS.structure.min_zoom,
+    rotate_speed = DEFAULTS.structure.rotate_speed,
+    zoom_speed = DEFAULTS.structure.zoom_speed,
+    pan_speed = DEFAULTS.structure.pan_speed,
+    zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor,
+    show_atoms = DEFAULTS.structure.show_atoms,
+    show_bonds = DEFAULTS.structure.show_bonds,
+    show_site_labels = DEFAULTS.structure.show_site_labels,
+    show_site_indices = DEFAULTS.structure.show_site_indices,
+    site_label_size = DEFAULTS.structure.site_label_size,
+    site_label_offset = $bindable(DEFAULTS.structure.site_label_offset),
+    site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`,
+    site_label_color = `#ffffff`,
+    site_label_padding = 3,
+    vector_configs = $bindable<Record<string, VectorLayerConfig>>({}),
+    vector_scale = DEFAULTS.structure.vector_scale,
+    vector_color = DEFAULTS.structure.vector_color,
+    vector_color_mode = DEFAULTS.structure.vector_color_mode as VectorColorMode,
+    vector_color_scale = DEFAULTS.structure.vector_color_scale,
+    vector_normalize = DEFAULTS.structure.vector_normalize,
+    vector_uniform_thickness = DEFAULTS.structure.vector_uniform_thickness,
+    vector_origin_gap = DEFAULTS.structure.vector_origin_gap,
+    vector_shaft_radius = DEFAULTS.structure.vector_shaft_radius,
+    vector_arrow_head_radius = DEFAULTS.structure.vector_arrow_head_radius,
+    vector_arrow_head_length = DEFAULTS.structure.vector_arrow_head_length,
+    gizmo = DEFAULTS.structure.show_gizmo,
+    hovered_idx = $bindable(null),
+    hovered_site = $bindable(null),
+    float_fmt = `.3~f`,
+    auto_rotate = DEFAULTS.structure.auto_rotate,
+    bond_thickness = DEFAULTS.structure.bond_thickness,
+    bond_color = DEFAULTS.structure.bond_color,
+    bonding_strategy = DEFAULTS.structure.bonding_strategy,
+    bonding_options = {},
+    fov = DEFAULTS.structure.fov,
+    initial_zoom = DEFAULTS.structure.initial_zoom,
+    ambient_light = DEFAULTS.structure.ambient_light,
+    directional_light = DEFAULTS.structure.directional_light,
+    sphere_segments = DEFAULTS.structure.sphere_segments,
+    lattice_props = {},
+    atom_label,
+    camera_is_moving = $bindable(false),
+    width = 0,
+    height = 0,
+    measure_mode = `distance`,
+    selected_sites = $bindable([]),
+    measured_sites = $bindable([]),
+    added_bonds = $bindable([]),
+    removed_bonds = $bindable([]),
+    selection_highlight_color = `#6cf0ff`,
+    // Active highlight group with different color
+    active_sites = $bindable([]),
+    active_highlight_color = `var(--struct-active-highlight-color, #2563eb)`,
+    rotation = DEFAULTS.structure.rotation,
+    scene = $bindable(),
+    camera = $bindable(),
+    orbit_controls = $bindable(),
+    rotation_target_ref = $bindable(),
+    initial_computed_zoom = $bindable(),
+    hidden_elements = $bindable(new SvelteSet()),
+    hidden_prop_vals = $bindable(new SvelteSet<number | string>()),
+    element_radius_overrides = $bindable<Partial<Record<ElementSymbol, number>>>({}),
+    site_radius_overrides = $bindable<SvelteMap<number, number>>(new SvelteMap()),
+    atom_color_config = {
+      mode: DEFAULTS.structure.atom_color_mode,
+      scale: DEFAULTS.structure.atom_color_scale as D3InterpolateName,
+      scale_type: DEFAULTS.structure.atom_color_scale_type,
+    },
+    sym_data = null,
+    // Edit-atoms mode callbacks
+    on_sites_moved,
+    on_operation_start,
+    on_add_atom,
+    add_atom_mode = $bindable(false),
+    add_element = $bindable(`C`),
+    cursor = $bindable(`default`),
+    dragging_atoms = $bindable(false),
+    volumetric_data = undefined,
+    isosurface_settings = DEFAULT_ISOSURFACE_SETTINGS,
+  }: {
+    structure?: AnyStructure
+    base_structure?: AnyStructure // The original structure without image atoms, used for property color calculation
+    atom_radius?: number // scale factor for atomic radii
+    same_size_atoms?: boolean // whether to use the same radius for all atoms. if not, the radius will be
+    // determined by the atomic radius of the element
+    camera_position?: [x: number, y: number, z: number] // initial camera position from which to render the scene
+    camera_target?: Vec3 // external orbit-controls target for pan synchronization
+    camera_projection?: CameraProjection // camera projection type
+    rotation_damping?: number // rotation damping factor (how quickly the rotation comes to rest after mouse release)
+    // zoom level of the camera
+    max_zoom?: number
+    min_zoom?: number
+    rotate_speed?: number // rotation speed. set to 0 to disable rotation.
+    zoom_speed?: number // zoom speed. set to 0 to disable zooming.
+    pan_speed?: number // pan speed. set to 0 to disable panning.
+    zoom_to_cursor?: boolean // zoom toward cursor position instead of scene center
+    show_atoms?: boolean
+    show_bonds?: ShowBonds
+    show_site_labels?: boolean
+    show_site_indices?: boolean
+    vector_configs?: Record<string, VectorLayerConfig>
+    vector_scale?: number
+    vector_color?: string
+    vector_color_mode?: VectorColorMode
+    vector_color_scale?: D3InterpolateName
+    vector_normalize?: boolean
+    vector_uniform_thickness?: boolean
+    vector_origin_gap?: number
+    vector_shaft_radius?: number
+    vector_arrow_head_radius?: number
+    vector_arrow_head_length?: number
+    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>
+    hovered_idx?: number | null
+    hovered_site?: Site | null
+    float_fmt?: string
+    auto_rotate?: number
+    initial_zoom?: number
+    bond_thickness?: number
+    bond_color?: string
+    bonding_strategy?: BondingStrategy
+    bonding_options?: Record<string, unknown>
+    fov?: number
+    ambient_light?: number
+    directional_light?: number
+    sphere_segments?: number
+    lattice_props?: ComponentProps<typeof Lattice>
+    atom_label?: Snippet<[{ site: Site; site_idx: number }]>
+    site_label_size?: number
+    site_label_offset?: Vec3
+    site_label_bg_color?: string
+    site_label_color?: string
+    site_label_padding?: number
+    camera_is_moving?: boolean // used to prevent tooltip from showing while camera is moving
+    width?: number // Viewer dimensions for responsive zoom
+    height?: number
+    // measurement props
+    measure_mode?: MeasureMode
+    selected_sites?: number[]
+    measured_sites?: number[]
+    added_bonds?: [number, number][]
+    removed_bonds?: [number, number][]
+    selection_highlight_color?: string
+    // Support for active highlight group with different color
+    active_sites?: number[]
+    active_highlight_color?: string
+    rotation?: Vec3 // rotation control prop
+    // Expose scene and camera for external use (e.g. export pane)
+    scene?: Scene
+    camera?: Camera
+    orbit_controls?: ComponentProps<typeof extras.OrbitControls>[`ref`] // OrbitControls instance
+    rotation_target_ref?: Vec3 // Expose rotation target for reset
+    initial_computed_zoom?: number // Expose initial zoom for reset
+    hidden_elements?: Set<ElementSymbol>
+    hidden_prop_vals?: Set<number | string> // Track hidden property values (e.g. Wyckoff positions, coordination numbers)
+    element_radius_overrides?: Partial<Record<ElementSymbol, number>> // Per-element absolute radius in Angstroms
+    site_radius_overrides?: Map<number, number> | SvelteMap<number, number> // Per-site absolute radius in Angstroms
+    atom_color_config?: Partial<AtomColorConfig> // Atom coloring configuration
+    sym_data?: MoyoDataset | null // Symmetry data for Wyckoff coloring
+    // Edit-atoms mode callbacks and state
+    on_sites_moved?: (scene_indices: number[], delta: Vec3) => void
+    on_operation_start?: () => void
+    on_add_atom?: (xyz: Vec3, element: ElementSymbol) => void
+    add_atom_mode?: boolean // whether user is in click-to-place add-atom sub-mode
+    add_element?: ElementSymbol // element to add when clicking in add-atom mode
+    cursor?: string // cursor style for the 3D canvas
+    dragging_atoms?: boolean // true while TransformControls drag is active (skips expensive recalculations)
+    volumetric_data?: VolumetricData // Active volumetric data for isosurface rendering
+    isosurface_settings?: IsosurfaceSettings // Isosurface rendering settings
+  } = $props()
+
+  const threlte = useThrelte()
+  $effect(() => {
+    scene = threlte.scene
+    camera = threlte.camera.current
     if (threlte.renderer) {
-        Object.assign(threlte.renderer.domElement, {
-            __renderer: threlte.renderer,
-        });
+      Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer })
     }
-});
-// Expose rotation target for external reset
-$effect(() => {
-    rotation_target_ref = rotation_target;
-});
-// Track initial computed zoom for reset
-let stored_initial_zoom = $state(undefined);
-$effect(() => {
+  })
+
+  // Expose rotation target for external reset
+  $effect(() => {
+    rotation_target_ref = rotation_target
+  })
+
+  // Track initial computed zoom for reset
+  let stored_initial_zoom = $state<number | undefined>(undefined)
+  $effect(() => {
     if (stored_initial_zoom === undefined && computed_zoom > 0) {
-        stored_initial_zoom = computed_zoom;
+      stored_initial_zoom = computed_zoom
     }
-    initial_computed_zoom = stored_initial_zoom;
-});
-let bond_pairs = $state([]);
-let active_tooltip = $state(null);
-let hovered_bond_key = $state(null);
-// Cursor style for the canvas, derived from mode and hover state
-let canvas_cursor = $derived.by(() => {
-    if (measure_mode === `edit-atoms` && add_atom_mode)
-        return `crosshair`;
+    initial_computed_zoom = stored_initial_zoom
+  })
+
+  let bond_pairs: BondPair[] = $state([])
+  let active_tooltip = $state<`atom` | `bond` | null>(null)
+  let hovered_bond_key = $state<string | null>(null)
+
+  // Cursor style for the canvas, derived from mode and hover state
+  let canvas_cursor = $derived.by(() => {
+    if (measure_mode === `edit-atoms` && add_atom_mode) return `crosshair`
     if (hovered_idx != null) {
-        if (measure_mode === `edit-atoms`) {
-            const site = structure?.sites?.[hovered_idx];
-            if (site?.properties?.orig_site_idx != null)
-                return `not-allowed`;
-            return `pointer`;
-        }
-        return `pointer`;
+      if (measure_mode === `edit-atoms`) {
+        const site = structure?.sites?.[hovered_idx]
+        if (site?.properties?.orig_site_idx != null) return `not-allowed`
+        return `pointer`
+      }
+      return `pointer`
     }
-    return `default`;
-});
-// Desaturate a color by blending it toward gray (for ghosting image atoms in edit mode)
-const gray = new Color(0x999999);
-function desaturate(hex, amount = 0.4) {
-    return `#${new Color(hex ?? 0x999999).lerp(gray, amount).getHexString()}`;
-}
-// === Edit-atoms mode state ===
-let transform_object = $state(undefined);
-// Plain variable — only used imperatively in TransformControls drag handlers
-let drag_start_centroid = null;
-// Frozen centroid set on drag start. While non-null, the TransformControls mesh
-// position stays at this fixed value so Svelte's reactive centroid updates (from
-// PBC wrapping) don't fight TransformControls. Cleared on mouseUp so the mesh
-// snaps to the new wrapped centroid.
-let frozen_centroid = $state(null);
-function get_bond_key(idx1, idx2) {
-    return idx1 < idx2 ? `${idx1}-${idx2}` : `${idx2}-${idx1}`;
-}
-// Toggle a bond between two atoms: cycles through add → remove → restore states
-function toggle_bond(site_1, site_2) {
-    const idx_i = Math.min(site_1, site_2);
-    const idx_j = Math.max(site_1, site_2);
+    return `default`
+  })
+
+  // Desaturate a color by blending it toward gray (for ghosting image atoms in edit mode)
+  const gray = new Color(0x999999)
+  function desaturate(hex: string | undefined, amount = 0.4): string {
+    return `#${new Color(hex ?? 0x999999).lerp(gray, amount).getHexString()}`
+  }
+
+  // === Edit-atoms mode state ===
+  let transform_object = $state<Mesh | undefined>(undefined)
+  // Plain variable — only used imperatively in TransformControls drag handlers
+  let drag_start_centroid: Vec3 | null = null
+  // Frozen centroid set on drag start. While non-null, the TransformControls mesh
+  // position stays at this fixed value so Svelte's reactive centroid updates (from
+  // PBC wrapping) don't fight TransformControls. Cleared on mouseUp so the mesh
+  // snaps to the new wrapped centroid.
+  let frozen_centroid = $state<Vec3 | null>(null)
+
+  const get_bond_key = (idx1: number, idx2: number): string =>
+    idx1 < idx2 ? `${idx1}-${idx2}` : `${idx2}-${idx1}`
+
+  // Toggle a bond between two atoms: cycles through add → remove → restore states
+  function toggle_bond(site_1: number, site_2: number) {
+    const idx_i = Math.min(site_1, site_2)
+    const idx_j = Math.max(site_1, site_2)
     // added/removed pairs are stored sorted, so direct comparison works
-    const match = ([a, b]) => a === idx_i && b === idx_j;
-    const added_idx = added_bonds.findIndex(match);
+    const match = ([a, b]: [number, number]) => a === idx_i && b === idx_j
+
+    const added_idx = added_bonds.findIndex(match)
     if (added_idx >= 0) {
-        added_bonds = added_bonds.toSpliced(added_idx, 1);
-        return;
+      added_bonds = added_bonds.toSpliced(added_idx, 1)
+      return
     }
-    const removed_idx = removed_bonds.findIndex(match);
+
+    const removed_idx = removed_bonds.findIndex(match)
     if (removed_idx >= 0) {
-        removed_bonds = removed_bonds.toSpliced(removed_idx, 1);
-        return;
+      removed_bonds = removed_bonds.toSpliced(removed_idx, 1)
+      return
     }
+
     // bond_pairs may not be sorted, so use get_bond_key for comparison
-    const key = `${idx_i}-${idx_j}`;
-    if (bond_pairs.some((bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2) === key)) {
-        removed_bonds = [...removed_bonds, [idx_i, idx_j]];
-    }
-    else {
-        added_bonds = [...added_bonds, [idx_i, idx_j]];
+    const key = `${idx_i}-${idx_j}`
+    if (
+      bond_pairs.some((bond) =>
+        get_bond_key(bond.site_idx_1, bond.site_idx_2) === key
+      )
+    ) removed_bonds = [...removed_bonds, [idx_i, idx_j]]
+    else added_bonds = [...added_bonds, [idx_i, idx_j]]
+  }
+
+  // Deduplicate clicks: when a highlight sphere and the underlying atom both
+  // intercept the same native click, only the first intersection should fire.
+  // All threlte intersection events from one click share the same nativeEvent ref.
+  let last_native_event: Event | null = null
+
+  function toggle_selection(site_index: number, evt?: Event) {
+    evt?.stopPropagation?.()
+    const native_event = (evt as Event & { nativeEvent?: unknown } | undefined)
+      ?.nativeEvent
+    if (native_event instanceof Event) {
+      if (native_event === last_native_event) return
+      last_native_event = native_event
     }
-}
-// Deduplicate clicks: when a highlight sphere and the underlying atom both
-// intercept the same native click, only the first intersection should fire.
-// All threlte intersection events from one click share the same nativeEvent ref.
-let last_native_event = null;
-function toggle_selection(site_index, evt) {
-    evt?.stopPropagation?.();
-    const native = evt?.nativeEvent;
-    if (native && native === last_native_event)
-        return;
-    if (native)
-        last_native_event = native;
+
     if (measure_mode === `edit-bonds`) {
-        // In edit-bonds mode, select atoms to add/remove bonds between them
-        const new_sites = measured_sites.includes(site_index)
-            ? measured_sites.filter((idx) => idx !== site_index)
-            : [...measured_sites, site_index];
-        measured_sites = new_sites;
-        selected_sites = new_sites;
-        // When two atoms are selected, toggle the bond between them
-        if (measured_sites.length === 2) {
-            toggle_bond(measured_sites[0], measured_sites[1]);
-            measured_sites = [];
-            selected_sites = [];
-        }
-        return;
+      // In edit-bonds mode, select atoms to add/remove bonds between them
+      const new_sites = measured_sites.includes(site_index)
+        ? measured_sites.filter((idx) => idx !== site_index)
+        : [...measured_sites, site_index]
+
+      measured_sites = new_sites
+      selected_sites = new_sites
+
+      // When two atoms are selected, toggle the bond between them
+      if (measured_sites.length === 2) {
+        toggle_bond(measured_sites[0], measured_sites[1])
+        measured_sites = []
+        selected_sites = []
+      }
+      return
     }
+
     if (measure_mode === `edit-atoms`) {
-        // Block image atoms (detected by orig_site_idx property from PBC)
-        const site = structure?.sites?.[site_index];
-        if (site?.properties?.orig_site_idx != null)
-            return;
-        const is_selected = selected_sites.includes(site_index);
-        const is_shift = evt instanceof MouseEvent && evt.shiftKey;
-        // In edit-atoms mode, selected_sites and measured_sites always stay in sync
-        let new_sites;
-        if (is_shift) {
-            // Multi-select: toggle this site in/out of selection
-            new_sites = is_selected
-                ? selected_sites.filter((idx) => idx !== site_index)
-                : [...selected_sites, site_index];
-        }
-        else {
-            // Single-select: replace selection (or deselect if already selected)
-            new_sites = is_selected ? [] : [site_index];
-        }
-        selected_sites = new_sites;
-        measured_sites = new_sites;
-        return;
+      // Block image atoms (detected by orig_site_idx property from PBC)
+      const site = structure?.sites?.[site_index]
+      if (site?.properties?.orig_site_idx != null) return
+
+      const is_selected = selected_sites.includes(site_index)
+      const is_shift = evt instanceof MouseEvent && evt.shiftKey
+
+      // In edit-atoms mode, selected_sites and measured_sites always stay in sync
+      let new_sites: number[]
+      if (is_shift) {
+        // Multi-select: toggle this site in/out of selection
+        new_sites = is_selected
+          ? selected_sites.filter((idx) => idx !== site_index)
+          : [...selected_sites, site_index]
+      } else {
+        // Single-select: replace selection (or deselect if already selected)
+        new_sites = is_selected ? [] : [site_index]
+      }
+      selected_sites = new_sites
+      measured_sites = new_sites
+      return
     }
-    if (!measured_sites.includes(site_index) &&
-        measured_sites.length >= measure.MAX_SELECTED_SITES) {
-        console.warn(`Selection size limit reached (${measure.MAX_SELECTED_SITES}). Deselect some sites first.`);
-        return;
+
+    if (
+      !measured_sites.includes(site_index) &&
+      measured_sites.length >= measure.MAX_SELECTED_SITES
+    ) {
+      console.warn(
+        `Selection size limit reached (${measure.MAX_SELECTED_SITES}). Deselect some sites first.`,
+      )
+      return
     }
+
     measured_sites = measured_sites.includes(site_index)
-        ? measured_sites.filter((idx) => idx !== site_index)
-        : [...measured_sites, site_index];
+      ? measured_sites.filter((idx) => idx !== site_index)
+      : [...measured_sites, site_index]
     selected_sites = selected_sites.includes(site_index)
-        ? selected_sites.filter((idx) => idx !== site_index)
-        : [...selected_sites, site_index];
-}
-$effect(() => {
-    const count = structure?.sites?.length ?? 0;
+      ? selected_sites.filter((idx) => idx !== site_index)
+      : [...selected_sites, site_index]
+  }
+  $effect(() => {
+    const count = structure?.sites?.length ?? 0
     if (count <= 0) {
-        measured_sites = [];
-        return;
+      measured_sites = []
+      return
     }
     untrack(() => {
-        measured_sites = measured_sites.filter((idx) => idx >= 0 && idx < count);
-    });
-});
-$effect(() => {
-    cursor = canvas_cursor;
-});
-extras.interactivity();
-$effect.pre(() => {
-    hovered_site = structure?.sites?.[hovered_idx ?? -1] ?? null;
-});
-let lattice = $derived(structure && `lattice` in structure ? structure.lattice : null);
-let visual_lattice = $derived(base_structure && `lattice` in base_structure ? base_structure.lattice : lattice);
-let rotation_target = $derived(lattice
-    ? math.scale(math.add(...lattice.matrix), 0.5)
-    : structure
-        ? get_center_of_mass(structure)
-        : [0, 0, 0]);
-let structure_size = $derived(lattice ? (lattice.a + lattice.b + lattice.c) / 2 : 10);
-// Compute dynamic camera clipping planes based on structure size
-// This prevents z-fighting and disappearing objects when zooming in close on large supercells
-let camera_near = $derived(Math.max(0.01, structure_size * 0.01));
-let camera_far = $derived(Math.max(1000, structure_size * 100));
-// Using $state because this is mutated in an effect based on viewport/structure size
-let computed_zoom = $state(untrack(() => initial_zoom));
-$effect(() => {
-    if (!(width > 0) || !(height > 0))
-        return;
-    const structure_max_dim = Math.max(1, untrack(() => structure_size));
-    const viewer_min_dim = Math.min(width, height);
-    const scale_factor = viewer_min_dim / (structure_max_dim * 50); // 50px per unit
-    let new_zoom = initial_zoom * scale_factor;
-    if (min_zoom && min_zoom > 0)
-        new_zoom = Math.max(min_zoom, new_zoom);
-    if (max_zoom && max_zoom > 0)
-        new_zoom = Math.min(max_zoom, new_zoom);
-    computed_zoom = new_zoom;
-});
-$effect.pre(() => {
-    if (camera_position.every((v) => v === 0) && structure) {
-        const distance = Math.max(1, structure_size) * (60 / fov);
-        camera_position = [distance, distance * 0.3, distance * 0.8];
+      measured_sites = measured_sites.filter((idx) => idx >= 0 && idx < count)
+    })
+  })
+
+  $effect(() => {
+    cursor = canvas_cursor
+  })
+
+  extras.interactivity()
+  $effect.pre(() => {
+    hovered_site = structure?.sites?.[hovered_idx ?? -1] ?? null
+  })
+  let lattice = $derived(
+    structure && `lattice` in structure ? structure.lattice : null,
+  )
+
+  let visual_lattice = $derived(
+    base_structure && `lattice` in base_structure ? base_structure.lattice : lattice,
+  )
+
+  let rotation_target = $derived(
+    lattice
+      ? (math.scale(math.add(...lattice.matrix), 0.5) as Vec3)
+      : structure
+      ? get_center_of_mass(structure)
+      : [0, 0, 0] as Vec3,
+  )
+
+  let structure_size = $derived(
+    lattice ? (lattice.a + lattice.b + lattice.c) / 2 : 10,
+  )
+
+  // Characteristic inter-atomic spacing: cube root of volume per atom.
+  // Excludes PBC image atoms (orig_site_idx) so toggling image atoms doesn't affect arrow sizing.
+  let char_atom_spacing = $derived.by(() => {
+    if (!lattice || !structure?.sites?.length) return structure_size
+    const n_real = structure.sites.filter((site) =>
+      site.properties?.orig_site_idx == null
+    ).length
+    return n_real > 0 ? Math.cbrt(lattice.volume / n_real) : structure_size
+  })
+
+  // When uniform thickness is on, convert negative (length-relative) radii to
+  // positive (absolute) values scaled by inter-atomic spacing.
+  // Already-positive (absolute) values are preserved as-is.
+  let eff_shaft_radius = $derived(
+    vector_uniform_thickness && vector_shaft_radius < 0
+      ? char_atom_spacing * -vector_shaft_radius
+      : vector_shaft_radius,
+  )
+  let eff_head_radius = $derived(
+    vector_uniform_thickness && vector_arrow_head_radius < 0
+      ? char_atom_spacing * -vector_arrow_head_radius
+      : vector_arrow_head_radius,
+  )
+  let eff_head_length = $derived(
+    vector_uniform_thickness && vector_arrow_head_length < 0
+      ? char_atom_spacing * -vector_arrow_head_length
+      : vector_arrow_head_length,
+  )
+
+  // Compute dynamic camera clipping planes based on structure size
+  // This prevents z-fighting and disappearing objects when zooming in close on large supercells
+  let camera_near = $derived(Math.max(0.01, structure_size * 0.01))
+  let camera_far = $derived(Math.max(1000, structure_size * 100))
+
+  // Using $state because this is mutated in an effect based on viewport/structure size
+  let computed_zoom = $state(untrack(() => initial_zoom))
+  $effect(() => {
+    if (!(width > 0) || !(height > 0)) return
+    const structure_max_dim = Math.max(1, untrack(() => structure_size))
+    const viewer_min_dim = Math.min(width, height)
+    const scale_factor = viewer_min_dim / (structure_max_dim * 50) // 50px per unit
+    let new_zoom = initial_zoom * scale_factor
+    if (min_zoom && min_zoom > 0) new_zoom = Math.max(min_zoom, new_zoom)
+    if (max_zoom && max_zoom > 0) new_zoom = Math.min(max_zoom, new_zoom)
+    computed_zoom = new_zoom
+  })
+
+  $effect.pre(() => { // Simple initial camera auto-position: proportional to structure size and fov
+    if (camera_position.every((val) => val === 0) && structure) {
+      stored_initial_zoom = undefined
+      const distance = Math.max(1, structure_size) * (60 / fov)
+      camera_position = [distance, distance * 0.3, distance * 0.8]
     }
-});
-$effect(() => {
+  })
+  $effect(() => {
     if (structure && show_bonds !== `never`) {
-        // Determine if we should show bonds based on the setting and structure type
-        const should_show_bonds = show_bonds === `always` ||
-            (show_bonds === `crystals` && lattice) ||
-            (show_bonds === `molecules` && !lattice);
-        if (should_show_bonds) {
-            bond_pairs = BONDING_STRATEGIES[bonding_strategy](structure, bonding_options);
-        }
-        else
-            bond_pairs = [];
-    }
-    else
-        bond_pairs = [];
-});
-// Compute property-based colors when not using element coloring
-// Use base_structure (original unit cell) for color calculation
-let property_colors = $derived(get_property_colors(base_structure || structure, atom_color_config, bonding_strategy, sym_data));
-// Compute weighted average radius for a site based on species occupancies
-// Normalizes by total occupancy so vacancy-containing sites render at full size
-const calc_weighted_radius = (site) => {
-    const total_occu = site.species.reduce((sum, { occu }) => sum + occu, 0);
+      // Determine if we should show bonds based on the setting and structure type
+      const should_show_bonds = show_bonds === `always` ||
+        (show_bonds === `crystals` && lattice) ||
+        (show_bonds === `molecules` && !lattice)
+
+      if (should_show_bonds) {
+        bond_pairs = BONDING_STRATEGIES[bonding_strategy](structure, bonding_options)
+      } else bond_pairs = []
+    } else bond_pairs = []
+  })
+
+  // Compute property-based colors when not using element coloring
+  // Use base_structure (original unit cell) for color calculation
+  let property_colors = $derived(
+    get_property_colors(
+      base_structure || structure,
+      atom_color_config,
+      bonding_strategy,
+      sym_data,
+    ),
+  )
+  // Compute weighted average radius for a site based on species occupancies
+  // Normalizes by total occupancy so vacancy-containing sites render at full size
+  const calc_weighted_radius = (site: Site): number => {
+    const total_occu = site.species.reduce((sum, { occu }) => sum + occu, 0)
     const weighted_sum = site.species.reduce((sum, { element, occu }) => {
-        const override = element_radius_overrides?.[element];
-        return sum + occu * (override ?? atomic_radii[element] ?? 1);
-    }, 0);
-    return total_occu > 0 ? weighted_sum / total_occu : 1;
-};
-let atom_data = $derived.by(() => {
-    if (!show_atoms || !structure?.sites)
-        return [];
-    return structure.sites.flatMap((site, site_idx) => {
-        const orig_idx = get_orig_site_idx(site, site_idx);
-        // Skip sites with hidden property values
-        const prop_val = property_colors?.values[orig_idx];
-        if (prop_val !== undefined && hidden_prop_vals.has(prop_val))
-            return [];
-        // Calculate radius: same_size > site override > element override > default
-        // All radii scale uniformly with atom_radius for consistent slider behavior
-        const base_radius = same_size_atoms
-            ? 1
-            : site_radius_overrides?.get(site_idx) ?? calc_weighted_radius(site);
-        const radius = base_radius * atom_radius;
-        // Use property color if available (e.g. coordination number, Wyckoff position)
-        // Otherwise, each species gets its own element color (important for disordered sites)
-        const site_property_color = property_colors?.colors[orig_idx];
-        // Detect image atoms by presence of orig_site_idx property (set by get_pbc_image_sites)
-        const is_image_atom = site.properties?.orig_site_idx != null;
-        let start_angle = 0;
-        return site.species
-            .filter(({ element }) => !hidden_elements.has(element))
-            .map(({ element, occu }) => ({
-            site_idx,
-            element,
-            occupancy: occu,
-            position: site.xyz,
-            radius,
-            color: site_property_color ?? colors.element?.[element],
-            has_partial_occupancy: occu < 1,
-            start_phi: 2 * Math.PI * start_angle,
-            end_phi: 2 * Math.PI * (start_angle += occu),
-            is_image_atom,
-        }));
-    });
-});
-let filtered_bond_pairs = $derived.by(() => {
-    if (!structure?.sites)
-        return bond_pairs;
-    const is_site_visible = (site_idx) => {
-        const site = structure.sites[site_idx];
-        const has_visible_element = site?.species.some(({ element }) => !hidden_elements.has(element));
-        const orig_idx = get_orig_site_idx(site, site_idx);
-        const prop_val = property_colors?.values[orig_idx];
-        const prop_visible = prop_val === undefined ||
-            !hidden_prop_vals.has(prop_val);
-        return has_visible_element && prop_visible;
-    };
+      const override = element_radius_overrides?.[element as ElementSymbol]
+      return sum + occu * (override ?? atomic_radii[element] ?? 1)
+    }, 0)
+    return total_occu > 0 ? weighted_sum / total_occu : 1
+  }
+
+  let atom_data = $derived.by(() => {
+    if (!show_atoms || !structure?.sites) return []
+    const render_sites = merge_split_partial_sites(structure.sites, hidden_elements)
+    return render_sites.flatMap(({ site_idx, site, is_image_atom }) => {
+      const orig_idx = get_orig_site_idx(site, site_idx)
+
+      // Skip sites with hidden property values
+      const prop_val = property_colors?.values[orig_idx]
+      if (prop_val !== undefined && hidden_prop_vals.has(prop_val)) return []
+
+      // Calculate radius: same_size > site override > element override > default
+      // All radii scale uniformly with atom_radius for consistent slider behavior
+      const base_radius = same_size_atoms
+        ? 1
+        : site_radius_overrides?.get(site_idx) ?? calc_weighted_radius(site)
+      const radius = base_radius * atom_radius
+
+      // Use property color if available (e.g. coordination number, Wyckoff position)
+      // Otherwise, each species gets its own element color (important for disordered sites)
+      const site_property_color = property_colors?.colors[orig_idx]
+
+      const visible_species = site.species.filter(({ element }) =>
+        !hidden_elements.has(element)
+      )
+      const slice_geometry = compute_slice_geometry(visible_species)
+      return slice_geometry.map((slice_data) => {
+        return {
+          site_idx,
+          element: slice_data.element,
+          occupancy: slice_data.occupancy,
+          position: site.xyz,
+          radius,
+          color: site_property_color ?? colors.element?.[slice_data.element],
+          has_partial_occupancy: slice_data.occupancy < 1,
+          start_phi: slice_data.start_phi,
+          end_phi: slice_data.end_phi,
+          phi_length: slice_data.phi_length,
+          render_start_cap: slice_data.render_start_cap,
+          render_end_cap: slice_data.render_end_cap,
+          is_image_atom,
+        }
+      })
+    })
+  })
+
+  // Shared visibility check: site has at least one non-hidden element and
+  // its property value (if any) isn't hidden. Used by both bond and vector filtering.
+  const is_site_visible = (site_idx: number): boolean => {
+    if (!structure?.sites) return false
+    const site = structure.sites[site_idx]
+    const has_visible_element = site?.species.some(({ element }) =>
+      !hidden_elements.has(element)
+    )
+    const orig_idx = get_orig_site_idx(site, site_idx)
+    const prop_val = property_colors?.values[orig_idx]
+    const prop_visible = prop_val === undefined ||
+      !hidden_prop_vals.has(prop_val)
+    return has_visible_element && prop_visible
+  }
+
+  let filtered_bond_pairs = $derived.by(() => {
+    if (!structure?.sites) return bond_pairs
+
     // Build set of removed bond keys for efficient lookup
-    const removed_keys = new Set(removed_bonds.map(([idx_i, idx_j]) => get_bond_key(idx_i, idx_j)));
+    const removed_keys = new Set(
+      removed_bonds.map(([idx_i, idx_j]) => get_bond_key(idx_i, idx_j)),
+    )
+
     // Filter calculated bonds: exclude removed and hidden
     const calculated = bond_pairs.filter(({ site_idx_1, site_idx_2 }) => {
-        if (removed_keys.has(get_bond_key(site_idx_1, site_idx_2)))
-            return false;
-        return is_site_visible(site_idx_1) && is_site_visible(site_idx_2);
-    });
+      if (removed_keys.has(get_bond_key(site_idx_1, site_idx_2))) return false
+      return is_site_visible(site_idx_1) && is_site_visible(site_idx_2)
+    })
+
     // Create BondPair objects for manually added bonds
-    const added = added_bonds
-        .map(([idx_i, idx_j]) => {
-        if (!is_site_visible(idx_i) || !is_site_visible(idx_j))
-            return null;
-        const site1 = structure.sites[idx_i];
-        const site2 = structure.sites[idx_j];
-        if (!site1 || !site2)
-            return null;
-        const pos_1 = site1.xyz;
-        const pos_2 = site2.xyz;
-        const dist = math.euclidean_dist(pos_1, pos_2);
+    const added: BondPair[] = added_bonds
+      .map(([idx_i, idx_j]) => {
+        if (!is_site_visible(idx_i) || !is_site_visible(idx_j)) return null
+        const site1 = structure.sites[idx_i]
+        const site2 = structure.sites[idx_j]
+        if (!site1 || !site2) return null
+
+        const pos_1 = site1.xyz
+        const pos_2 = site2.xyz
+        const dist = math.euclidean_dist(pos_1, pos_2)
+
         return {
-            pos_1,
-            pos_2,
-            site_idx_1: idx_i,
-            site_idx_2: idx_j,
-            bond_length: dist,
-            strength: 1.0,
-            transform_matrix: compute_bond_transform(pos_1, pos_2),
-        };
-    })
-        .filter((bond) => bond !== null);
-    return [...calculated, ...added];
-});
-let instanced_bond_groups = $derived.by(() => {
-    if (!structure?.sites || filtered_bond_pairs.length === 0)
-        return [];
+          pos_1,
+          pos_2,
+          site_idx_1: idx_i,
+          site_idx_2: idx_j,
+          bond_length: dist,
+          strength: 1.0,
+          transform_matrix: compute_bond_transform(pos_1, pos_2),
+        }
+      })
+      .filter((bond): bond is BondPair => bond !== null)
+
+    return [...calculated, ...added]
+  })
+
+  let instanced_bond_groups = $derived.by(() => {
+    if (!structure?.sites || filtered_bond_pairs.length === 0) return []
+
     const group = {
-        thickness: bond_thickness,
-        ambient_light,
-        directional_light,
-        instances: [],
-    };
+      thickness: bond_thickness,
+      ambient_light,
+      directional_light,
+      instances: [] as {
+        matrix: Float32Array
+        color_start: string
+        color_end: string
+      }[],
+    }
+
     for (const bond_data of filtered_bond_pairs) {
-        const site_a = structure.sites[bond_data.site_idx_1];
-        const site_b = structure.sites[bond_data.site_idx_2];
-        const get_majority_color = (site) => {
-            if (!site?.species || site.species.length === 0)
-                return bond_color;
-            const majority_species = site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max);
-            return colors.element?.[majority_species.element] || bond_color;
-        };
-        const color_start = get_majority_color(site_a);
-        const color_end = get_majority_color(site_b);
-        const instance = { matrix: bond_data.transform_matrix, color_start, color_end };
-        group.instances.push(instance);
+      const site_a = structure.sites[bond_data.site_idx_1]
+      const site_b = structure.sites[bond_data.site_idx_2]
+
+      const get_majority_color = (site: typeof site_a) => {
+        if (!site?.species || site.species.length === 0) return bond_color
+        const majority_species = site.species.reduce((max, spec) =>
+          spec.occu > max.occu ? spec : max
+        )
+        return colors.element?.[majority_species.element] || bond_color
+      }
+
+      const color_start = get_majority_color(site_a)
+      const color_end = get_majority_color(site_b)
+      const instance = { matrix: bond_data.transform_matrix, color_start, color_end }
+      group.instances.push(instance)
     }
-    return group.instances.length > 0 ? [group] : [];
-});
-let radius_by_site_idx = $derived.by(() => {
-    const map = new SvelteMap();
+
+    return group.instances.length > 0 ? [group] : []
+  })
+
+  let radius_by_site_idx = $derived.by(() => {
+    const map = new SvelteMap<number, number>()
     for (const atom of atom_data) {
-        if (!map.has(atom.site_idx))
-            map.set(atom.site_idx, atom.radius);
+      if (!map.has(atom.site_idx)) map.set(atom.site_idx, atom.radius)
     }
-    return map;
-});
-// Get radius for a site (for highlight fallback when site is hidden/filtered)
-// Checks site_radius_overrides first for consistency with visible atoms
-const get_site_radius = (site, site_idx) => {
+    return map
+  })
+
+  // Get radius for a site (for highlight fallback when site is hidden/filtered)
+  // Checks site_radius_overrides first for consistency with visible atoms
+  const get_site_radius = (site: Site, site_idx: number | null): number => {
     const override = site_idx !== null
-        ? site_radius_overrides?.get(site_idx)
-        : undefined;
-    const base_radius = same_size_atoms ? 1 : override ?? calc_weighted_radius(site);
-    return base_radius * atom_radius;
-};
-let force_data = $derived.by(() => show_force_vectors && structure?.sites
-    ? structure?.sites
-        .map((site) => {
-        if (!site.properties?.force || !Array.isArray(site.properties.force))
-            return null;
-        const majority_element = site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max).element;
-        return {
-            position: site.xyz,
-            vector: site.properties.force,
-            scale: force_scale,
-            color: colors.element?.[majority_element] || force_color,
-        };
+      ? site_radius_overrides?.get(site_idx)
+      : undefined
+    const base_radius = same_size_atoms ? 1 : override ?? calc_weighted_radius(site)
+    return base_radius * atom_radius
+  }
+
+  // Interpolate between spin-down (#3498db blue) and spin-up (#e74c3c red)
+  // based on the z-component direction of a magnetic vector
+  function spin_direction_color(vec: Vec3): string {
+    const mag = Math.hypot(...vec)
+    const z_frac = mag > 1e-10 ? (vec[2] / mag + 1) / 2 : 0.5 // 0=down, 1=up
+    const red = Math.round(52 + (231 - 52) * z_frac)
+    const grn = Math.round(152 + (76 - 152) * z_frac)
+    const blu = Math.round(219 + (60 - 219) * z_frac)
+    return `#${red.toString(16).padStart(2, `0`)}${
+      grn.toString(16).padStart(2, `0`)
+    }${blu.toString(16).padStart(2, `0`)}`
+  }
+
+  // Build one arrow layer per visible vector key. Auto-scales the longest
+  // vector to 1.8× char_atom_spacing (cube root of volume per atom).
+  // When vector_normalize is on, effective_max is 1 so all arrows get equal length.
+  // Single active key preserves legacy coloring (element for force,
+  // spin-direction for magmom/spin). Multiple keys use flat palette colors.
+  let vector_layers = $derived.by(() => {
+    if (!structure?.sites) return []
+    const keys = get_structure_vector_keys(structure)
+    const active_keys = keys.filter((key) => vector_configs[key]?.visible !== false)
+    if (active_keys.length === 0) return []
+
+    // Build per-site lookup; skip hidden sites so they don't contribute
+    // arrows or affect autoscaling. null entries = hidden site.
+    const active_set = new Set(active_keys)
+    let max_mag = 0
+    const site_vec_maps = structure.sites.map((site, site_idx) => {
+      if (!is_site_visible(site_idx)) return null
+      const map = new SvelteMap<string, Vec3>()
+      for (const { key, vec } of get_all_site_vectors(site)) {
+        map.set(key, vec)
+        if (active_set.has(key)) {
+          max_mag = Math.max(max_mag, Math.hypot(...vec))
+        }
+      }
+      return map
+    })
+
+    // When normalize is on, treat all magnitudes as 1 so arrows have equal length
+    const effective_max = vector_normalize ? 1 : max_mag
+    const auto_scale = effective_max > 1e-10
+      ? (char_atom_spacing * 1.8) / effective_max
+      : 1
+    const is_single = active_keys.length === 1
+    const effective_global_scale = auto_scale * vector_scale
+
+    // When vector_origin_gap > 0 and multiple vectors exist at a site,
+    // arrange arrow origins on a regular polygon centered on the atom, in a
+    // plane perpendicular to the mean vector direction. The gap is a fraction
+    // of the visual atom radius (0 = center, 0.5 = halfway to surface).
+    // get_site_radius() returns the uniform scale applied to SphereGeometry(0.5),
+    // so visual_radius = get_site_radius() * 0.5.
+    const site_offsets = (vector_origin_gap > 0 && !is_single)
+      ? structure.sites.map((site, site_idx) => {
+        const vec_map = site_vec_maps[site_idx]
+        if (!vec_map) return null
+        const site_keys = active_keys.filter((key) => vec_map.has(key))
+        const n_keys = site_keys.length
+        if (n_keys <= 1) return null
+        const visual_radius = get_site_radius(site, site_idx) * 0.5
+        const gap_abs = vector_origin_gap * visual_radius
+        let mean: Vec3 = [0, 0, 0]
+        for (const key of site_keys) {
+          const vec = vec_map.get(key)
+          if (vec) mean = math.add(mean, math.normalize_vec3(vec)) as Vec3
+        }
+        const mean_dir = math.normalize_vec3(mean, [0, 1, 0] as Vec3)
+        const [u_vec, v_vec] = math.compute_in_plane_basis(mean_dir)
+        const offsets = new SvelteMap<string, Vec3>()
+        for (const [idx, key] of site_keys.entries()) {
+          const angle = (2 * Math.PI * idx) / n_keys
+          const dx = math.scale(u_vec, gap_abs * Math.cos(angle)) as Vec3
+          const dy = math.scale(v_vec, gap_abs * Math.sin(angle)) as Vec3
+          offsets.set(key, math.add(dx, dy) as Vec3)
+        }
+        return offsets
+      })
+      : null
+
+    const mag_interpolator = get_d3_interpolator(vector_color_scale)
+
+    return active_keys.map((key, layer_idx) => {
+      const layer_cfg = vector_configs[key]
+      const layer_scale = effective_global_scale * (layer_cfg?.scale ?? 1.0)
+      const layer_color = layer_cfg?.color ??
+        VECTOR_PALETTE[layer_idx % VECTOR_PALETTE.length]
+
+      const arrows = structure.sites
+        .map((site, site_idx) => {
+          const vec_map = site_vec_maps[site_idx]
+          if (!vec_map) return null
+          const vec = vec_map.get(key)
+          if (!vec) return null
+
+          // Resolve color mode: explicit per-key color always wins,
+          // then multi-key uses palette, then mode-based coloring
+          let arrow_color: string
+          if (layer_cfg?.color) {
+            arrow_color = layer_cfg.color
+          } else if (!is_single) arrow_color = layer_color
+          else {
+            const effective_mode = vector_color_mode === `auto`
+              ? (key.startsWith(`magmom`) || key.startsWith(`spin`)
+                ? `spin_direction`
+                : `element`)
+              : vector_color_mode
+            if (effective_mode === `magnitude`) {
+              const mag = Math.hypot(...vec)
+              const norm = max_mag > 1e-10 ? mag / max_mag : 0
+              arrow_color = mag_interpolator(norm)
+            } else if (effective_mode === `spin_direction`) {
+              arrow_color = spin_direction_color(vec)
+            } else if (effective_mode === `uniform`) {
+              arrow_color = vector_color
+            } else {
+              const majority_element = site.species.length > 0
+                ? site.species.reduce((max, spec) =>
+                  spec.occu > max.occu ? spec : max
+                ).element
+                : undefined
+              arrow_color =
+                (majority_element && colors.element?.[majority_element]) ||
+                vector_color
+            }
+          }
+
+          const offset = site_offsets?.[site_idx]?.get(key)
+          const position = offset ? math.add(site.xyz, offset) as Vec3 : site.xyz
+          const arrow_vec = vector_normalize ? math.normalize_vec3(vec) : vec
+
+          return {
+            site_idx,
+            position,
+            vector: arrow_vec,
+            scale: layer_scale,
+            color: arrow_color,
+          }
+        })
+        .filter((item): item is NonNullable<typeof item> => item !== null)
+
+      return { key, arrows }
     })
-        .filter((item) => item !== null)
-    : []);
-let instanced_atom_groups = $derived(Object.values(atom_data
-    .filter((atom) => !atom.has_partial_occupancy)
-    .reduce((groups, atom) => {
-    const { element, radius, color, is_image_atom } = atom;
-    // Separate image atoms into their own groups for distinct styling in edit-atoms mode
-    const key = `${element}-${format_num(radius, `.3~`)}-${color}-${is_image_atom ? `img` : `base`}`;
-    const bucket = groups[key] ||
-        (groups[key] = { element, radius, color, is_image_atom, atoms: [] });
-    bucket.atoms.push(atom);
-    return groups;
-}, {})));
-let unique_instanced_atoms = $derived(Object.values(instanced_atom_groups
-    .flatMap((group) => group.atoms)
-    .reduce((acc, atom) => {
-    acc[atom.site_idx] = atom;
-    return acc;
-}, {})));
-let gizmo_props = $derived.by(() => {
-    const axis_options = Object.fromEntries([...AXIS_COLORS, ...NEG_AXIS_COLORS].map(([axis, color, hover_color]) => [
+  })
+
+  let instanced_atom_groups = $derived(
+    Object.values(
+      atom_data
+        .filter((atom) => !atom.has_partial_occupancy)
+        .reduce(
+          (groups, atom) => {
+            const { element, radius, color, is_image_atom } = atom
+            // Separate image atoms into their own groups for distinct styling in edit-atoms mode
+            const key = `${element}-${format_num(radius, `.3~`)}-${color}-${
+              is_image_atom ? `img` : `base`
+            }`
+            const bucket = groups[key] ||
+              (groups[key] = { element, radius, color, is_image_atom, atoms: [] })
+            bucket.atoms.push(atom)
+            return groups
+          },
+          {} as Record<string, InstancedAtomGroup>,
+        ),
+    ),
+  )
+
+  let unique_instanced_atoms = $derived(
+    Object.values(
+      instanced_atom_groups
+        .flatMap((group) => group.atoms)
+        .reduce((acc, atom) => {
+          acc[atom.site_idx] = atom
+          return acc
+        }, {} as Record<number, (typeof atom_data)[number]>),
+    ),
+  )
+
+  let gizmo_props = $derived.by(() => {
+    const axis_options = Object.fromEntries(
+      [...AXIS_COLORS, ...NEG_AXIS_COLORS].map(([axis, color, hover_color]) => [
         axis,
         {
-            color,
-            labelColor: `#111`,
-            opacity: axis.startsWith(`n`) ? 0.9 : 0.8,
-            hover: {
-                color: hover_color,
-                labelColor: `#222222`,
-                opacity: axis.startsWith(`n`) ? 1 : 0.9,
-            },
+          color,
+          labelColor: `#111`,
+          opacity: axis.startsWith(`n`) ? 0.9 : 0.8,
+          hover: {
+            color: hover_color,
+            labelColor: `#222222`,
+            opacity: axis.startsWith(`n`) ? 1 : 0.9,
+          },
         },
-    ]));
+      ]),
+    )
     return {
-        background: { enabled: false },
-        className: `responsive-gizmo`,
-        ...axis_options,
-        ...(typeof gizmo === `boolean` ? {} : gizmo),
-        offset: { left: 5, bottom: 5 },
-    };
-});
-let orbit_controls_props = $derived({
+      background: { enabled: false },
+      className: `responsive-gizmo`,
+      ...axis_options,
+      ...(typeof gizmo === `boolean` ? {} : gizmo),
+      offset: { left: 5, bottom: 5 },
+    }
+  })
+
+  let orbit_controls_props = $derived({
     position: [0, 0, 0],
     enableRotate: rotate_speed > 0,
     rotateSpeed: rotate_speed,
@@ -452,7 +910,7 @@ let orbit_controls_props = $derived({
     zoomToCursor: zoom_to_cursor,
     enablePan: pan_speed > 0,
     panSpeed: pan_speed,
-    target: rotation_target,
+    target: camera_target ?? rotation_target,
     maxZoom: max_zoom,
     minZoom: min_zoom,
     autoRotate: Boolean(auto_rotate),
@@ -460,20 +918,20 @@ let orbit_controls_props = $derived({
     enableDamping: Boolean(rotation_damping),
     dampingFactor: rotation_damping,
     onstart: () => {
-        camera_is_moving = true;
-        hovered_idx = null;
+      camera_is_moving = true
+      hovered_idx = null
     },
     onend: () => {
-        camera_is_moving = false;
+      camera_is_moving = false
     },
-});
-let measure_line_color = $derived.by(() => {
-    if (typeof window === `undefined`)
-        return;
-    const root_styles = getComputedStyle(document.documentElement);
-    const text_color = root_styles.getPropertyValue(`--text-color`).trim();
-    return text_color || `#808080`;
-});
+  })
+
+  let measure_line_color = $derived.by(() => {
+    if (typeof window === `undefined`) return
+    const root_styles = getComputedStyle(document.documentElement)
+    const text_color = root_styles.getPropertyValue(`--text-color`).trim()
+    return text_color || `#808080`
+  })
 </script>
 
 {#snippet bond_instanced_mesh_snippet(
@@ -498,27 +956,17 @@ let measure_line_color = $derived.by(() => {
         style:padding="{site_label_padding}px"
         style:color={site_label_color}
       >
-        {#if show_site_labels && show_site_indices}
-          {#if site.species.length === 1}
-            {site.species[0].element}-{site_idx + 1}
-          {:else}
-            {@html site.species.map((spec) =>
-        `${spec.element}<sub>${
-          format_num(spec.occu, `.3~`).replace(`0.`, `.`)
-        }</sub>`
-      ).join(``)}-{
-              site_idx + 1
-            }
-          {/if}
-        {:else if show_site_labels}
+        {#if show_site_labels}
           {#if site.species.length === 1}
-            {site.species[0].element}
+            {site.species[0].element}{#if show_site_indices}-{site_idx + 1}{/if}
           {:else}
-            {@html site.species.map((spec) =>
+            {@html sanitize_html(site.species.map((spec) =>
         `${spec.element}<sub>${
           format_num(spec.occu, `.3~`).replace(`0.`, `.`)
         }</sub>`
-      ).join(``)}
+      ).join(``))}{#if show_site_indices}-{
+                site_idx + 1
+              }{/if}
           {/if}
         {:else if show_site_indices}
           {site_idx + 1}
@@ -570,6 +1018,7 @@ let measure_line_color = $derived.by(() => {
           {@const edit_mode_image = measure_mode === `edit-atoms` && is_image_atom}
           <extras.InstancedMesh
             key="{element}-{format_num(radius, `.3~`)}-{color}-{is_image_atom ? `img` : `base`}-{edit_mode_image}"
+            limit={atoms.length}
             range={atoms.length}
             frustumCulled={false}
           >
@@ -637,7 +1086,7 @@ let measure_line_color = $derived.by(() => {
                   sphere_segments,
                   sphere_segments,
                   atom.start_phi,
-                  2 * Math.PI * atom.occupancy,
+                  atom.phi_length,
                 ]}
               />
               <T.MeshStandardMaterial
@@ -647,9 +1096,16 @@ let measure_line_color = $derived.by(() => {
               />
             </T.Mesh>
 
-            {#if atom.has_partial_occupancy}
+            {#if atom.has_partial_occupancy && atom.render_start_cap}
               <T.Mesh rotation={[0, atom.start_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.start_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
                 <T.MeshStandardMaterial
                   color={partial_color}
                   side={2}
@@ -657,8 +1113,17 @@ let measure_line_color = $derived.by(() => {
                   transparent={partial_edit_image}
                 />
               </T.Mesh>
+            {/if}
+            {#if atom.has_partial_occupancy && atom.render_end_cap}
               <T.Mesh rotation={[0, atom.end_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.end_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
                 <T.MeshStandardMaterial
                   color={partial_color}
                   side={2}
@@ -684,11 +1149,16 @@ let measure_line_color = $derived.by(() => {
         {/if}
       {/if}
 
-      {#if force_data.length > 0}
-        {#each force_data as force (force.position.join(`,`) + force.vector.join(`,`))}
-          <Arrow {...force} />
+      {#each vector_layers as layer (layer.key)}
+        {#each layer.arrows as arrow (`${layer.key}-${arrow.site_idx}`)}
+          <Arrow
+            {...arrow}
+            shaft_radius={eff_shaft_radius}
+            arrow_head_radius={eff_head_radius}
+            arrow_head_length={eff_head_length}
+          />
         {/each}
-      {/if}
+      {/each}
 
       <!-- Instanced bond rendering with gradient colors -->
       {#if instanced_bond_groups.length > 0}
@@ -806,8 +1276,12 @@ let measure_line_color = $derived.by(() => {
 
       <!-- hovered site tooltip -->
       {#if hovered_site && !camera_is_moving && active_tooltip === `atom`}
-        {@const abc = hovered_site.abc.map((x) => format_num(x, float_fmt)).join(`, `)}
-        {@const xyz = hovered_site.xyz.map((x) => format_num(x, float_fmt)).join(`, `)}
+        {@const abc = hovered_site.abc.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
+        {@const xyz = hovered_site.xyz.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
         {@const bond_neighbors = (() => {
           if (hovered_idx == null || !structure?.sites) return []
           return filtered_bond_pairs
@@ -853,7 +1327,7 @@ let measure_line_color = $derived.by(() => {
               {#if occu !== 1}<span class="occupancy">{
                   format_num(occu, `.3~f`)
                 }</span>{/if}
-              <strong>{element}{@html oxi_str}</strong>
+              <strong>{element}{@html sanitize_html(oxi_str)}</strong>
               {#if element_name}<span class="elem-name">{element_name}</span>{/if}
             {/each}
           </div>
@@ -874,7 +1348,7 @@ let measure_line_color = $derived.by(() => {
           structure?.sites}
         {@const selected_atoms = selected_sites
           .map((idx) => structure?.sites?.[idx])
-          .filter(Boolean) as Site[]}
+          .filter((site): site is Site => site != null)}
         {#if selected_atoms.length > 0}
           {@const avg = (dim: number) =>
           selected_atoms.reduce((sum, atom) => sum + atom.xyz[dim], 0) /
@@ -994,12 +1468,12 @@ let measure_line_color = $derived.by(() => {
         {:else if measure_mode === `angle` && measured_sites.length >= 3}
           {#each measured_sites as idx_center (idx_center)}
             {@const center = structure.sites[idx_center]}
-            {#each measured_sites.filter((x) => x !== idx_center) as
+            {#each measured_sites.filter((idx) => idx !== idx_center) as
               idx_a,
               loop_idx
               (idx_center + `-` + idx_a)
             }
-              {#each measured_sites.filter((x) => x !== idx_center).slice(loop_idx + 1) as
+              {#each measured_sites.filter((idx) => idx !== idx_center).slice(loop_idx + 1) as
                 idx_b
                 (idx_center + `-` + idx_a + `-` + idx_b)
               }