matterviz 0.3.1 → 0.3.3

package/dist/spectral/helpers.d.ts

@@ -4,7 +4,6 @@ import type { RibbonConfig } from './types';
 export declare const is_valid_range: (range: unknown) => range is Vec2;
 export declare const ranges_equal: (a: Vec2 | undefined | null, b: Vec2 | undefined | null, tol?: number) => boolean;
 export declare function detect_zoom_change(bands_range: unknown, dos_range: unknown, shared_range: Vec2, current_synced: Vec2 | null, dos_enabled?: boolean): Vec2 | null | undefined;
-export declare const N_ACOUSTIC_MODES = 3;
 export declare const IMAGINARY_MODE_NOISE_THRESHOLD = 0.005;
 export declare function pretty_sym_point(symbol: string): string;
 export declare const get_segment_key: (start_label?: string, end_label?: string) => string;
@@ -92,4 +91,27 @@ export declare const DEFAULT_UNITS: types.FrequencyUnit;
 export declare function format_sigma(val: number): string;
 export declare function validate_sigma_range([min, max]: [number, number]): [number, number];
 export declare function calculate_sigma_step(range: [number, number]): number;
+export interface BandPointMeta extends Record<string, unknown> {
+    band_idx: number;
+    spin: `up` | `down`;
+    is_acoustic: boolean | null;
+    nb_bands: number;
+    frac_coords: Vec3 | null;
+    qpoint_label: string | null;
+    band_width: number | null;
+    slope: number | null;
+}
+export declare function compute_slope(x_vals: number[], y_vals: number[], idx: number): number | null;
+export declare function find_gamma_indices(bs: types.BaseBandStructure): number[];
+export declare const ACOUSTIC_FREQ_THRESHOLD = 0.5;
+export declare function classify_acoustic(bs: types.BaseBandStructure, band_idx: number, gamma_indices: number[], threshold?: number): boolean | null;
+export declare function build_point_metadata(opts: {
+    x_vals: number[];
+    y_vals: number[];
+    band_idx: number;
+    spin: `up` | `down`;
+    is_acoustic: boolean | null;
+    bs: types.BaseBandStructure;
+    start_idx: number;
+}): BandPointMeta[];
 export {};

package/dist/spectral/helpers.js

@@ -1,6 +1,6 @@
 // Helper utilities for band structure and DOS data processing
 import { SUBSCRIPT_MAP } from '../labels';
-import { centered_frac, euclidean_dist, } from '../math';
+import { centered_frac, euclidean_dist } from '../math';
 // Check if range is a valid [min, max] tuple (strict 2-element array of finite numbers)
 export const is_valid_range = (range) => Array.isArray(range) &&
     range.length === 2 &&
@@ -52,7 +52,6 @@ const THz_TO_MEV = THz_TO_EV * 1000;
 const THz_TO_HA = THz_TO_EV / 27.211386245988; // Hartree
 const THz_TO_CM = THz_TO_HZ / (C_LIGHT * 100); // cm^-1 (c in cm/s)
 // Band structure constants
-export const N_ACOUSTIC_MODES = 3; // Number of acoustic modes in typical 3D crystals
 export const IMAGINARY_MODE_NOISE_THRESHOLD = 0.005; // Clamp negatives < 0.5% as noise
 // Convert symmetry point symbols to pretty-printed versions.
 // Handles Greek letters (both plain and LaTeX backslash-prefixed) and subscripts.
@@ -71,7 +70,10 @@ export function pretty_sym_point(symbol) {
         .replace(/\\?SIGMA/gi, `Σ`)
         .replace(/\\?LAMBDA/gi, `Λ`)
         .replace(/(\p{L})(\d+)/gu, (_, letter, num) => letter +
-        num.split(``).map((digit) => SUBSCRIPT_MAP[digit] ?? digit).join(``));
+        num
+            .split(``)
+            .map((digit) => SUBSCRIPT_MAP[digit] ?? digit)
+            .join(``));
 }
 // Create segment key from start and end labels
 export const get_segment_key = (start_label, end_label) => `${start_label ?? `null`}_${end_label ?? `null`}`;
@@ -149,10 +151,10 @@ export function get_band_xaxis_ticks(band_struct, branches = []) {
 // Convert frequencies from THz to specified units.
 export function convert_frequencies(frequencies, unit = `THz`) {
     const conversion_factors = {
-        'THz': 1,
-        'eV': THz_TO_EV,
-        'meV': THz_TO_MEV,
-        'Ha': THz_TO_HA,
+        THz: 1,
+        eV: THz_TO_EV,
+        meV: THz_TO_MEV,
+        Ha: THz_TO_HA,
         'cm-1': THz_TO_CM,
     };
     const factor = conversion_factors[unit];
@@ -277,7 +279,9 @@ export function clear_smearing_cache() {
 }
 // Type guards for pymatgen qpoint formats
 const is_vec3 = (val) => Array.isArray(val) && val.length >= 3 && val.slice(0, 3).every(Number.isFinite);
-const is_kpoint = (val) => !!val && typeof val === `object` && `frac_coords` in val &&
+const is_kpoint = (val) => !!val &&
+    typeof val === `object` &&
+    `frac_coords` in val &&
     is_vec3(val.frac_coords);
 const is_pymatgen_format = (obj) => {
     // Check for explicit pymatgen markers
@@ -311,11 +315,6 @@ const CM_TO_THZ = 1 / THz_TO_CM;
 // Spin key constants for pymatgen spin-polarized data
 const SPIN_UP_KEYS = [`1`, `Spin.up`];
 const SPIN_DOWN_KEYS = [`-1`, `Spin.down`];
-// Extract first spin channel from pymatgen spin-keyed data.
-// Thin wrapper around extract_spin_channels for backwards compatibility.
-function extract_first_spin_channel(data) {
-    return extract_spin_channels(data)?.up ?? null;
-}
 // Extract both spin channels from pymatgen spin-keyed data.
 // Returns { up: T, down: T | null } where down is null for non-spin-polarized data.
 export function extract_spin_channels(data) {
@@ -359,7 +358,9 @@ function convert_pymatgen_band_structure(pmg) {
     // 1. Standard pymatgen: bands as dict with spin keys {1: [[...], ...]}
     // 2. Custom phonon format: frequencies_cm as 2D array [[...], ...]
     // 3. Already normalized: bands as 2D array [[...], ...]
-    let raw_bands = extract_first_spin_channel(pmg.bands);
+    const spin_channels = extract_spin_channels(pmg.bands);
+    let raw_bands = spin_channels?.up ?? null;
+    let raw_spin_down_bands = spin_channels?.down ?? null;
     const has_frequencies_cm = Array.isArray(pmg.frequencies_cm);
     if (!raw_bands && has_frequencies_cm) {
         // Phonon format: frequencies_cm is [n_qpoints x n_branches] - needs transpose
@@ -367,24 +368,30 @@ function convert_pymatgen_band_structure(pmg) {
         if (freqs.length > 0 && Array.isArray(freqs[0])) {
             // Transpose: [n_qpoints x n_branches] -> [n_branches x n_qpoints]
             raw_bands = Array.from({ length: freqs[0].length }, (_, band_idx) => freqs.map((qpt_freqs) => qpt_freqs[band_idx]));
+            raw_spin_down_bands = null;
         }
     }
     const labels_dict = pmg.labels_dict;
     const lattice_rec = pmg.lattice_rec;
     // Determine unit: cm-1 if frequencies_cm present, else check explicit unit or default to THz
-    const unit = pmg.unit?.toLowerCase() ??
-        (has_frequencies_cm ? `cm-1` : `thz`);
-    if (!Array.isArray(raw_qpts) || !Array.isArray(raw_bands) ||
-        !raw_qpts.length || !raw_bands.length)
+    const unit = pmg.unit?.toLowerCase() ?? (has_frequencies_cm ? `cm-1` : `thz`);
+    if (!Array.isArray(raw_qpts) ||
+        !Array.isArray(raw_bands) ||
+        !raw_qpts.length ||
+        !raw_bands.length)
         return null;
-    const qpoints = raw_qpts.map((q) => parse_qpoint(q, labels_dict)).filter(Boolean);
+    const qpoints = raw_qpts
+        .map((q) => parse_qpoint(q, labels_dict))
+        .filter((q) => q !== null);
     if (!qpoints.length)
         return null;
     // Step distances and discontinuity detection (5x median threshold)
-    const steps = qpoints.slice(1).map((q, idx) => euclidean_dist(qpoints[idx].frac_coords, q.frac_coords));
+    const steps = qpoints
+        .slice(1)
+        .map((q, idx) => euclidean_dist(qpoints[idx].frac_coords, q.frac_coords));
     const sorted = steps.slice().sort((a, b) => a - b);
     const threshold = (sorted[Math.floor(sorted.length / 2)] ?? 0) * 5;
-    const disc_set = new Set(steps.map((s, idx) => s > threshold ? idx + 1 : -1).filter((i) => i >= 0));
+    const disc_set = new Set(steps.map((s, idx) => (s > threshold ? idx + 1 : -1)).filter((i) => i >= 0));
     // Cumulative distance (skip discontinuities)
     const distance = steps.reduce((acc, step, idx) => [...acc, disc_set.has(idx + 1) ? acc[idx] : acc[idx] + step], [0]);
     // Use pymatgen's branches if available - they correctly handle discontinuities
@@ -401,7 +408,7 @@ function convert_pymatgen_band_structure(pmg) {
     }
     // Fallback: infer branches from discontinuities when none provided or all invalid
     if (branches.length === 0) {
-        console.info(`Band structure missing 'branches' field - inferring from path discontinuities`);
+        console.warn(`Band structure missing 'branches' field - inferring from path discontinuities`);
         // Discontinuity indices mark points where the path jumps (disc before that index)
         // Create continuous segments between discontinuities
         const disc_indices = [...disc_set].sort((a, b) => a - b);
@@ -432,14 +439,28 @@ function convert_pymatgen_band_structure(pmg) {
             return val * CM_TO_THZ;
         return val; // THz (default) - no conversion
     };
+    const converted_bands = raw_bands.map((band) => band.map(convert_to_thz));
+    const valid_spin_down_bands = Array.isArray(raw_spin_down_bands) &&
+        raw_spin_down_bands.length === raw_bands.length &&
+        raw_spin_down_bands.every((band, band_idx) => Array.isArray(band) && band.length === raw_bands[band_idx]?.length)
+        ? raw_spin_down_bands
+        : null;
+    const converted_spin_down_bands = valid_spin_down_bands?.map((band) => band.map(convert_to_thz));
     return {
         qpoints,
         branches,
         distance,
-        bands: raw_bands.map((band) => band.map(convert_to_thz)),
+        bands: converted_bands,
+        spin_down_bands: converted_spin_down_bands,
         nb_bands: raw_bands.length,
         labels_dict: labels_dict ?? {},
-        recip_lattice: { matrix: lattice_rec?.matrix ?? [[1, 0, 0], [0, 1, 0], [0, 0, 1]] },
+        recip_lattice: {
+            matrix: lattice_rec?.matrix ?? [
+                [1, 0, 0],
+                [0, 1, 0],
+                [0, 0, 1],
+            ],
+        },
     };
 }
 export function normalize_band_structure(bs) {
@@ -478,8 +499,7 @@ export function normalize_dos(dos, options = {}) {
         return null;
     const dos_obj = dos;
     // Check for pymatgen format (has @class or @module)
-    const is_pymatgen = typeof dos_obj[`@class`] === `string` ||
-        typeof dos_obj[`@module`] === `string`;
+    const is_pymatgen = typeof dos_obj[`@class`] === `string` || typeof dos_obj[`@module`] === `string`;
     const { frequencies, energies, spin_polarized } = dos_obj;
     // Handle densities as either array or dict with spin keys (pymatgen format)
     // Pymatgen stores densities as {1: [...], -1: [...]} or {"Spin.up": [...], ...}
@@ -488,8 +508,7 @@ export function normalize_dos(dos, options = {}) {
         return null;
     const densities = spin_channels.up;
     // Use extracted spin-down or fallback to explicit field (for already-normalized DosData)
-    const spin_down_densities = spin_channels.down ??
-        dos_obj.spin_down_densities ?? null;
+    const spin_down_densities = spin_channels.down ?? dos_obj.spin_down_densities ?? null;
     if (!Array.isArray(densities))
         return null;
     // Phonon DOS: has frequencies
@@ -504,7 +523,7 @@ export function normalize_dos(dos, options = {}) {
         if (auto_convert_units && max_freq > 100) {
             // Likely in cm⁻¹, convert to THz
             final_frequencies = frequencies.map((f) => f * CM_TO_THZ);
-            console.info(`Phonon DOS frequencies appear to be in cm⁻¹ (max: ${max_freq.toFixed(1)}). ` +
+            console.warn(`Phonon DOS frequencies appear to be in cm⁻¹ (max: ${max_freq.toFixed(1)}). ` +
                 `Converting to THz (max: ${(max_freq * CM_TO_THZ).toFixed(1)} THz).`);
         }
         return { type: `phonon`, frequencies: final_frequencies, densities };
@@ -520,9 +539,7 @@ export function normalize_dos(dos, options = {}) {
             type: `electronic`,
             energies,
             densities,
-            spin_down_densities: is_spin_polarized
-                ? spin_down_densities ?? undefined
-                : undefined,
+            spin_down_densities: is_spin_polarized ? (spin_down_densities ?? undefined) : undefined,
             spin_polarized: is_spin_polarized,
         };
     }
@@ -553,11 +570,10 @@ export function extract_k_path_points(band_struct, recip_lattice_matrix, options
             y = centered_frac(y);
             z = centered_frac(z);
         }
-        return [
-            x * m00 + y * m10 + z * m20,
-            x * m01 + y * m11 + z * m21,
-            x * m02 + y * m12 + z * m22,
-        ];
+        const kx = x * m00 + y * m10 + z * m20;
+        const ky = x * m01 + y * m11 + z * m21;
+        const kz = x * m02 + y * m12 + z * m22;
+        return [kx, ky, kz];
     });
 }
 // Find the q-point index closest to a given distance along the band structure path
@@ -633,7 +649,10 @@ export function find_qpoint_at_rescaled_x(band_struct, rescaled_x, x_positions)
         if (!segment_range)
             continue;
         const [x_start, x_end] = segment_range;
-        for (const [x_pos, idx] of [[x_start, start_idx], [x_end, end_idx]]) {
+        for (const [x_pos, idx] of [
+            [x_start, start_idx],
+            [x_end, end_idx],
+        ]) {
             const dist = Math.abs(rescaled_x - x_pos);
             if (dist < min_dist) {
                 min_dist = dist;
@@ -670,15 +689,12 @@ export function extract_pdos(dos, pdos_type, filter_keys) {
         const densities = spin_channels.up;
         if (!Array.isArray(densities) || energies.length !== densities.length)
             continue;
-        const is_spin_polarized = spin_channels.down !== null &&
-            spin_channels.down.length === densities.length;
+        const is_spin_polarized = spin_channels.down !== null && spin_channels.down.length === densities.length;
         result[key] = {
             type: `electronic`,
             energies,
             densities,
-            spin_down_densities: is_spin_polarized
-                ? spin_channels.down ?? undefined
-                : undefined,
+            spin_down_densities: is_spin_polarized ? (spin_channels.down ?? undefined) : undefined,
             spin_polarized: is_spin_polarized,
             efermi: nested_dos.efermi,
         };
@@ -738,9 +754,7 @@ export function generate_ribbon_path(x_values, y_values, width_values, x_scale_f
         const x_px = x_scale_fn(x_values[idx]);
         const y_data = y_values[idx];
         const raw_width = width_values[idx] ?? 0;
-        const width_normalized = Number.isFinite(raw_width) && raw_width > 0
-            ? raw_width / max_width_val
-            : 0;
+        const width_normalized = Number.isFinite(raw_width) && raw_width > 0 ? raw_width / max_width_val : 0;
         const half_width_px = width_normalized * max_width_px * scale;
         // In SVG, y increases downward, so upper edge has smaller y value
         const y_upper_px = y_scale_fn(y_data) - half_width_px;
@@ -752,7 +766,7 @@ export function generate_ribbon_path(x_values, y_values, width_values, x_scale_f
     const path_parts = [
         `M${upper_points[0]}`,
         ...upper_points.slice(1).map((pt) => `L${pt}`),
-        ...lower_points.reverse().map((pt) => `L${pt}`),
+        ...lower_points.toReversed().map((pt) => `L${pt}`),
         `Z`,
     ];
     return path_parts.join(` `);
@@ -806,7 +820,8 @@ function is_electronic_band_struct(bs) {
         return true;
     }
     // Pymatgen @class: BandStructure* but not Phonon*
-    const py_class_name = String(obj[`@class`] ?? ``);
+    const raw_class = obj[`@class`];
+    const py_class_name = typeof raw_class === `string` ? raw_class : ``;
     if (py_class_name.startsWith(`BandStructure`) && !py_class_name.includes(`Phonon`)) {
         return true;
     }
@@ -820,7 +835,8 @@ export function compute_frequency_range(band_structs, doses, padding_factor = 0.
     // (normalized structures always have qpoints, so we can't detect from them)
     let has_electronic_bs = false;
     // Support both qpoints (phonon) and kpoints (electronic) to detect single vs dict
-    const is_single_bs = band_structs && typeof band_structs === `object` &&
+    const is_single_bs = band_structs &&
+        typeof band_structs === `object` &&
         (`qpoints` in band_structs || `kpoints` in band_structs);
     if (band_structs && typeof band_structs === `object`) {
         // Single structure check
@@ -882,7 +898,8 @@ export function compute_frequency_range(band_structs, doses, padding_factor = 0.
     }
     if (!Number.isFinite(min_val) || !Number.isFinite(max_val))
         return undefined;
-    const clamp_min = is_phonon && min_val < 0 && // clamp phonon noise to 0
+    const clamp_min = is_phonon &&
+        min_val < 0 && // clamp phonon noise to 0
         negative_fraction(all_freqs) < IMAGINARY_MODE_NOISE_THRESHOLD;
     if (clamp_min)
         min_val = 0;
@@ -892,7 +909,7 @@ export function compute_frequency_range(band_structs, doses, padding_factor = 0.
 }
 // Parse axis label: "Frequency (THz)" → { name: "Frequency", unit: "THz" }
 function parse_axis_label(label) {
-    const match = label.match(/^(.+?)\s*\(([^)]+)\)$/);
+    const match = /^(.+?)\s*\(([^)]+)\)$/.exec(label);
     return match ? { name: match[1], unit: match[2] } : { name: label };
 }
 // Format DOS tooltip content from axis labels and values
@@ -953,3 +970,54 @@ export function calculate_sigma_step(range) {
     const [min, max] = validate_sigma_range(range);
     return (max - min) / 100 || 0.01;
 }
+// Central difference for local slope (dω/dk or dE/dk).
+// Uses forward/backward difference at endpoints, central difference for interior points.
+export function compute_slope(x_vals, y_vals, idx) {
+    const len = Math.min(x_vals.length, y_vals.length);
+    if (len < 2 || idx < 0 || idx >= len)
+        return null;
+    const lo = idx === 0 ? 0 : idx - 1;
+    const hi = idx >= len - 1 ? len - 1 : idx + 1;
+    const dx = x_vals[hi] - x_vals[lo];
+    return dx ? (y_vals[hi] - y_vals[lo]) / dx : null;
+}
+// Find Gamma-point indices (q ≈ integer lattice point) in a band structure.
+// Returns indices of q-points whose fractional coordinates are all within 0.01 of integers.
+export function find_gamma_indices(bs) {
+    const indices = [];
+    for (let q_idx = 0; q_idx < bs.qpoints.length; q_idx++) {
+        const coords = bs.qpoints[q_idx]?.frac_coords;
+        if (coords?.every((coord) => Math.abs(coord - Math.round(coord)) < 0.01)) {
+            indices.push(q_idx);
+        }
+    }
+    return indices;
+}
+// Threshold below which a band's frequency at Gamma is considered acoustic (THz).
+// Assumes bands are stored in THz (normalize_band_structure converts to THz).
+export const ACOUSTIC_FREQ_THRESHOLD = 0.5;
+// Classify a band as acoustic based on near-zero frequency at Gamma points.
+// Returns true (acoustic), false (optical), or null (no Gamma points → can't determine).
+export function classify_acoustic(bs, band_idx, gamma_indices, threshold = ACOUSTIC_FREQ_THRESHOLD) {
+    if (gamma_indices.length === 0)
+        return null;
+    return gamma_indices.some((gamma_idx) => Math.abs(bs.bands[band_idx]?.[gamma_idx] ?? Infinity) < threshold);
+}
+// Build per-point metadata array for a band series in the tooltip.
+export function build_point_metadata(opts) {
+    const { x_vals, y_vals, band_idx, spin, is_acoustic, bs, start_idx } = opts;
+    return x_vals.map((_, pt_idx) => {
+        const global_idx = start_idx + pt_idx;
+        const qpoint = bs.qpoints[global_idx];
+        return {
+            band_idx,
+            spin,
+            is_acoustic,
+            nb_bands: bs.nb_bands,
+            frac_coords: qpoint?.frac_coords ?? null,
+            qpoint_label: qpoint?.label ?? null,
+            band_width: bs.band_widths?.[band_idx]?.[global_idx] ?? null,
+            slope: compute_slope(x_vals, y_vals, pt_idx),
+        };
+    });
+}

package/dist/spectral/types.d.ts

@@ -25,6 +25,7 @@ export interface BaseBandStructure {
     distance: number[];
     nb_bands: number;
     bands: number[][];
+    spin_down_bands?: number[][];
     band_widths?: number[][];
 }
 export interface RibbonConfig {
@@ -62,6 +63,7 @@ export interface ElectronicDos {
     dos_at_e_fermi?: number;
 }
 export type SpinMode = `mirror` | `overlay` | `up_only` | `down_only` | null;
+export type BandsSpinMode = Exclude<SpinMode, `mirror`>;
 export type PdosType = `atom` | `orbital`;
 export interface StackedAreaData {
     x_values: number[];

package/dist/state.svelte.d.ts

@@ -1,7 +1,7 @@
 import type { ChemicalElement, ElementCategory } from './element/types';
 import { DEFAULT_CATEGORY_COLORS, default_element_colors } from './colors';
 import type { Tooltip } from './plot';
-import type { ThemeMode, ThemeType } from './theme';
+import { type ThemeMode, type ThemeType } from './theme';
 export declare const selected: {
     category: ElementCategory | null;
     element: ChemicalElement | null;

package/dist/state.svelte.js

@@ -1,5 +1,6 @@
 import { AUTO_THEME, COLOR_THEMES, THEME_TYPE } from './theme/index';
 import { DEFAULT_CATEGORY_COLORS, default_element_colors } from './colors';
+import { is_valid_theme_mode } from './theme';
 export const selected = $state({
     category: null,
     element: null,
@@ -22,8 +23,8 @@ let initial_system_mode = COLOR_THEMES.light;
 // Safe theme initialization for test environments
 try {
     if (typeof window !== `undefined` && globalThis.localStorage) {
-        initial_theme_mode = localStorage.getItem(`matterviz-theme`) ||
-            AUTO_THEME;
+        const saved_theme = localStorage.getItem(`matterviz-theme`) ?? ``;
+        initial_theme_mode = is_valid_theme_mode(saved_theme) ? saved_theme : AUTO_THEME;
     }
     else {
         initial_theme_mode = AUTO_THEME;

package/dist/structure/Arrow.svelte

@@ -1,23 +1,62 @@
-<script lang="ts">import * as math from '../math';
-import { DEFAULTS } from '../settings';
-import { T } from '@threlte/core';
-import { Euler, Quaternion, Vector3 } from 'three';
-let { position, vector, scale = DEFAULTS.structure.force_scale, color = DEFAULTS.structure.force_color, shaft_radius = DEFAULTS.structure.force_shaft_radius, arrow_head_radius = DEFAULTS.structure.force_arrow_head_radius, arrow_head_length = DEFAULTS.structure.force_arrow_head_length, ...rest } = $props();
-const mag = $derived(Math.hypot(...vector));
-const dir = $derived(mag > math.EPS ? math.scale(vector, 1 / mag) : [0, 1, 0]);
-const vec_len = $derived(mag * scale);
-const head_len = $derived(arrow_head_length < 0 ? vec_len * -arrow_head_length : arrow_head_length);
-const shaft_len = $derived(Math.max(0, vec_len - head_len * 0.5));
-const shaft_r = $derived(shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius);
-const head_r = $derived(arrow_head_radius < 0 ? shaft_len * -arrow_head_radius : arrow_head_radius);
-const shaft_pos = $derived(math.add(position, math.scale(dir, shaft_len * 0.5)));
-const head_pos = $derived(math.add(position, math.scale(dir, shaft_len + head_len * 0.5)));
-const rotation = $derived.by(() => {
-    if (mag < math.EPS)
-        return [0, 0, 0];
-    const quat = new Quaternion().setFromUnitVectors(new Vector3(0, 1, 0), new Vector3(...dir));
-    return new Euler().setFromQuaternion(quat).toArray().slice(0, 3);
-});
+<script lang="ts">
+  import type { Vec3 } from '../math'
+  import * as math from '../math'
+  import { DEFAULTS } from '../settings'
+  import { T } from '@threlte/core'
+  import type { ComponentProps } from 'svelte'
+  import { Euler, Quaternion, Vector3 } from 'three'
+
+  let {
+    position,
+    vector,
+    scale = DEFAULTS.structure.vector_scale,
+    color = DEFAULTS.structure.vector_color,
+    shaft_radius = DEFAULTS.structure.vector_shaft_radius,
+    arrow_head_radius = DEFAULTS.structure.vector_arrow_head_radius,
+    arrow_head_length = DEFAULTS.structure.vector_arrow_head_length,
+    ...rest
+  }: ComponentProps<typeof T.Mesh> & {
+    position: Vec3
+    vector: Vec3
+    scale?: number
+    color?: string
+    shaft_radius?: number // negative = relative to length
+    arrow_head_radius?: number
+    arrow_head_length?: number
+  } = $props()
+
+  const mag = $derived(Math.hypot(...vector))
+  const dir = $derived(
+    mag > math.EPS ? math.scale(vector, 1 / mag) : ([0, 1, 0] as Vec3),
+  )
+  const vec_len = $derived(mag * scale)
+
+  const head_len = $derived(
+    arrow_head_length < 0 ? vec_len * -arrow_head_length : arrow_head_length,
+  )
+  const shaft_len = $derived(Math.max(0, vec_len - head_len * 0.5))
+  const shaft_r = $derived(
+    shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius,
+  )
+  const head_r = $derived(
+    arrow_head_radius < 0 ? shaft_len * -arrow_head_radius : arrow_head_radius,
+  )
+
+  const shaft_pos = $derived(
+    math.add(position, math.scale(dir, shaft_len * 0.5)) as Vec3,
+  )
+  const head_pos = $derived(
+    math.add(position, math.scale(dir, shaft_len + head_len * 0.5)) as Vec3,
+  )
+
+  const rotation = $derived.by((): Vec3 => {
+    if (mag < math.EPS) return [0, 0, 0]
+    const quat = new Quaternion().setFromUnitVectors(
+      new Vector3(0, 1, 0),
+      new Vector3(...dir),
+    )
+    return new Euler().setFromQuaternion(quat).toArray().slice(0, 3) as Vec3
+  })
 </script>
 
 {#if shaft_len > 0.01}