matterviz 0.3.1 → 0.3.3

package/dist/structure/StructureScene.svelte.d.ts

@@ -1,14 +1,14 @@
+import type { D3InterpolateName } from '../colors';
 import type { ElementSymbol } from '../element';
 import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types';
 import type { Vec3 } from '../math';
-import { type CameraProjection, type ShowBonds } from '../settings';
+import type { CameraProjection, ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings';
 import type { AnyStructure, MeasureMode, Site } from './';
 import { Lattice } from './';
 import type { AtomColorConfig } from './atom-properties';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
 import * as extras from '@threlte/extras';
-import type { ComponentProps } from 'svelte';
-import { type Snippet } from 'svelte';
+import { type ComponentProps, type Snippet } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 import { type Camera, type Scene } from 'three';
 import type { BondingStrategy } from './bonding';
@@ -18,6 +18,7 @@ type $$ComponentProps = {
     atom_radius?: number;
     same_size_atoms?: boolean;
     camera_position?: [x: number, y: number, z: number];
+    camera_target?: Vec3;
     camera_projection?: CameraProjection;
     rotation_damping?: number;
     max_zoom?: number;
@@ -30,9 +31,17 @@ type $$ComponentProps = {
     show_bonds?: ShowBonds;
     show_site_labels?: boolean;
     show_site_indices?: boolean;
-    show_force_vectors?: boolean;
-    force_scale?: number;
-    force_color?: string;
+    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;
@@ -90,6 +99,6 @@ type $$ComponentProps = {
     volumetric_data?: VolumetricData;
     isosurface_settings?: IsosurfaceSettings;
 };
-declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "selected_sites" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "measured_sites" | "added_bonds" | "removed_bonds" | "active_sites" | "scene" | "camera" | "orbit_controls" | "rotation_target_ref" | "initial_computed_zoom" | "add_atom_mode" | "add_element" | "dragging_atoms">;
+declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "vector_configs" | "camera" | "scene" | "orbit_controls" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "selected_sites" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "measured_sites" | "added_bonds" | "removed_bonds" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "add_atom_mode" | "add_element" | "dragging_atoms">;
 type StructureScene = ReturnType<typeof StructureScene>;
 export default StructureScene;

package/dist/structure/atom-properties.d.ts

@@ -1,6 +1,6 @@
-import type { AnyStructure, Site } from './';
 import type { ColorScaleType, D3InterpolateName } from '../colors';
 import type { AtomColorMode } from '../settings';
+import type { AnyStructure, Site } from './';
 import type { BondingStrategy } from './bonding';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
 export interface AtomColorConfig {
@@ -16,6 +16,9 @@ export interface AtomPropertyColors {
     max_value?: number;
     unique_values?: (number | string)[];
 }
+type SymmetryDataWithOrigMap = MoyoDataset & {
+    orig_site_indices_by_std_idx?: number[][];
+};
 export declare const get_d3_color_scales: () => string[];
 export declare function apply_color_scale(vals: number[], scale?: string, type?: ColorScaleType): {
     colors: string[];
@@ -27,7 +30,8 @@ export declare const apply_categorical_color_scale: (vals: string[], scale?: str
 };
 export declare const get_orig_site_idx: (site: Site | undefined, site_idx: number) => number;
 export declare function get_coordination_colors(structure: AnyStructure, strategy?: BondingStrategy, scale?: string, type?: ColorScaleType): AtomPropertyColors;
-export declare function get_wyckoff_colors(structure: AnyStructure, sym_data: MoyoDataset | null, scale?: string): AtomPropertyColors;
+export declare function get_wyckoff_colors(structure: AnyStructure, sym_data: SymmetryDataWithOrigMap | null, scale?: string): AtomPropertyColors;
 export declare function get_custom_colors(structure: AnyStructure, fn: (site: Site, idx: number) => number | string, scale?: string, type?: ColorScaleType): AtomPropertyColors;
 export declare function get_atom_colors(structure: AnyStructure, config: Partial<AtomColorConfig>, bonding_strategy?: BondingStrategy, sym_data?: MoyoDataset | null): AtomPropertyColors;
 export declare function get_property_colors(structure: AnyStructure | undefined, config: Partial<AtomColorConfig>, bonding_strategy: BondingStrategy, sym_data: MoyoDataset | null): AtomPropertyColors | null;
+export {};

package/dist/structure/atom-properties.js

@@ -1,6 +1,7 @@
 // Utility functions for computing atom properties and applying color scales
 import { calc_coordination_nums } from '../coordination';
 import * as math from '../math';
+import { wrap_to_unit_cell } from './pbc';
 import { rgb } from 'd3-color';
 import * as d3_sc from 'd3-scale-chromatic';
 const GRAY = `#808080`;
@@ -15,6 +16,25 @@ const get_interpolator = (scale) => {
     return interp_fn;
 };
 const to_hex = (interp_fn, t) => rgb(interp_fn(t)).formatHex();
+const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
+    const img_abc = [
+        site.abc[0] + offset[0],
+        site.abc[1] + offset[1],
+        site.abc[2] + offset[2],
+    ];
+    return {
+        ...site,
+        abc: img_abc,
+        xyz: frac_to_cart(img_abc),
+        properties: { ...site.properties, orig_site_idx: orig_idx },
+    };
+};
+const get_all_offsets = (pbc) => [-1, 0, 1]
+    .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
+    .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
+    (pbc[0] || dx === 0) &&
+    (pbc[1] || dy === 0) &&
+    (pbc[2] || dz === 0));
 const make_categorical = (vals, scale, sort_fn) => {
     const interp_fn = get_interpolator(scale);
     const uniq = sort_fn ? [...new Set(vals)].sort(sort_fn) : [...new Set(vals)].sort();
@@ -66,45 +86,23 @@ function expand_structure_for_pbc(structure) {
         return structure;
     }
     const { sites, lattice } = structure;
-    const lattice_T = math.transpose_3x3_matrix(lattice.matrix);
+    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
     const pbc = lattice.pbc ?? [true, true, true];
-    // All valid image offsets respecting PBC
-    const all_offsets = [-1, 0, 1]
-        .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
-        .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
-        (pbc[0] || dx === 0) &&
-        (pbc[1] || dy === 0) &&
-        (pbc[2] || dz === 0));
+    const all_offsets = get_all_offsets(pbc);
     // Small structures: expand all atoms
     if (sites.length < 20 || !pbc.some((periodic) => periodic)) {
-        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map(([dx, dy, dz]) => {
-            const img_abc = [site.abc[0] + dx, site.abc[1] + dy, site.abc[2] + dz];
-            return {
-                ...site,
-                abc: img_abc,
-                xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
-                properties: { ...site.properties, orig_site_idx: orig_idx },
-            };
-        }));
+        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx)));
         return { ...structure, sites: [...sites, ...image_sites] };
     }
     // Large structures: only expand atoms near boundaries (within 5Å bond distance)
     const cutoff = [5.0 / lattice.a, 5.0 / lattice.b, 5.0 / lattice.c];
     const image_sites = sites.flatMap((site, orig_idx) => {
-        const norm = site.abc.map((coord) => coord - Math.floor(coord));
+        const norm = wrap_to_unit_cell(site.abc);
         return all_offsets
             .filter(([dx, dy, dz]) => (dx === 0 || (dx === -1 ? norm[0] <= cutoff[0] : norm[0] >= 1 - cutoff[0])) &&
             (dy === 0 || (dy === -1 ? norm[1] <= cutoff[1] : norm[1] >= 1 - cutoff[1])) &&
             (dz === 0 || (dz === -1 ? norm[2] <= cutoff[2] : norm[2] >= 1 - cutoff[2])))
-            .map(([dx, dy, dz]) => {
-            const img_abc = [site.abc[0] + dx, site.abc[1] + dy, site.abc[2] + dz];
-            return {
-                ...site,
-                abc: img_abc,
-                xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
-                properties: { ...site.properties, orig_site_idx: orig_idx },
-            };
-        });
+            .map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx));
     });
     return { ...structure, sites: [...sites, ...image_sites] };
 }
@@ -113,8 +111,7 @@ export function get_coordination_colors(structure, strategy = `electroneg_ratio`
     // Check if structure has periodic boundary conditions
     const has_lattice = `lattice` in structure && structure.lattice !== undefined;
     const pbc = has_lattice ? structure.lattice.pbc : undefined;
-    const has_pbc = has_lattice &&
-        (pbc === undefined || pbc.some((is_periodic) => is_periodic));
+    const has_pbc = has_lattice && (pbc === undefined || pbc.some((is_periodic) => is_periodic));
     // For PBC structures, expand with images from neighboring cells for accurate coordination
     const coord_structure = has_pbc ? expand_structure_for_pbc(structure) : structure;
     // Calculate coordination numbers on the (potentially expanded) structure
@@ -135,9 +132,25 @@ export function get_wyckoff_colors(structure, sym_data, scale = DEFAULT_COLOR_SC
             unique_values: [`unknown`],
         };
     }
+    const wyckoff_by_orig_idx = new Map();
+    const mapping_by_std_idx = sym_data.orig_site_indices_by_std_idx;
+    if (mapping_by_std_idx) {
+        for (let std_idx = 0; std_idx < sym_data.wyckoffs.length; std_idx += 1) {
+            const wyckoff = sym_data.wyckoffs[std_idx];
+            for (const orig_idx of mapping_by_std_idx[std_idx] ?? []) {
+                if (!wyckoff_by_orig_idx.has(orig_idx))
+                    wyckoff_by_orig_idx.set(orig_idx, wyckoff);
+            }
+        }
+    }
     // Create unique orbit identifiers: Wyckoff position + element symbol
     const orbit_ids = structure.sites.map((site, idx) => {
         const sym_idx = get_orig_site_idx(site, idx);
+        const mapped_wyckoff = wyckoff_by_orig_idx.get(sym_idx);
+        if (mapped_wyckoff !== undefined) {
+            const element = site.species[0]?.element ?? `?`;
+            return mapped_wyckoff ? `${mapped_wyckoff}|${element}` : `unknown`;
+        }
         if (sym_idx >= sym_data.wyckoffs.length) {
             console.error(`[get_wyckoff_colors] Site ${idx} (maps to ${sym_idx}) has no Wyckoff data. ` +
                 `Structure has ${n} sites but symmetry data only has ${sym_data.wyckoffs.length}.`);

package/dist/structure/bonding.js

@@ -2,7 +2,9 @@
 import { element_data } from '../element';
 import * as math from '../math';
 const element_lookup = new Map(element_data.map((el) => [el.symbol, el]));
-const covalent_radii = new Map(element_data.filter((el) => el.covalent_radius !== null).map((el) => [el.symbol, el.covalent_radius]));
+const covalent_radii = new Map(element_data
+    .filter((el) => el.covalent_radius !== null)
+    .map((el) => [el.symbol, el.covalent_radius]));
 // Get the species with highest occupancy from a site.
 const get_majority_species = (site) => (site.species ?? []).reduce((max_species, species) => (species.occu > max_species.occu ? species : max_species), site.species?.[0] ?? { element: ``, occu: -1 });
 // Helper to extract numeric index from site properties
@@ -67,6 +69,7 @@ export function compute_bond_transform(pos_1, pos_2) {
         (pos_1[2] + pos_2[2]) / 2,
     ];
     return new Float32Array([
+        // Return flattened column-major 4x4 matrix for Three.js
         ...[m00, m10, m20, 0],
         ...[m01 * height, m11 * height, m21 * height, 0],
         ...[m02, m12, m22, 0],
@@ -263,17 +266,13 @@ export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area =
     for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
         const [x1, y1, z1] = sites[idx_a].xyz;
         const majority_a = get_majority_species(sites[idx_a]);
-        const radius_a = majority_a.element
-            ? covalent_radii.get(majority_a.element)
-            : undefined;
+        const radius_a = majority_a.element ? covalent_radii.get(majority_a.element) : undefined;
         for (const idx_b of get_candidates(sites[idx_a].xyz, sites, spatial)) {
             if (idx_b <= idx_a)
                 continue;
             const [x2, y2, z2] = sites[idx_b].xyz;
             const majority_b = get_majority_species(sites[idx_b]);
-            const radius_b = majority_b.element
-                ? covalent_radii.get(majority_b.element)
-                : undefined;
+            const radius_b = majority_b.element ? covalent_radii.get(majority_b.element) : undefined;
             const [dx, dy, dz] = [x2 - x1, y2 - y1, z2 - z1];
             const dist_sq = dx * dx + dy * dy + dz * dz;
             const dist = Math.sqrt(dist_sq);

package/dist/structure/export.js

@@ -10,13 +10,16 @@ export function has_color_property(mat) {
     if (!(`color` in mat))
         return false;
     const color = mat.color;
-    // Check for Color-like object with r, g, b properties (duck typing)
-    return (color !== null &&
-        typeof color === `object` &&
-        `r` in color &&
-        `g` in color &&
-        `b` in color &&
-        typeof color.r === `number`);
+    if (!color || typeof color !== `object`)
+        return false;
+    // Check for Color-like object with numeric r/g/b channels (duck typing)
+    const color_obj = color;
+    const red_channel = color_obj.r;
+    const green_channel = color_obj.g;
+    const blue_channel = color_obj.b;
+    return (typeof red_channel === `number` &&
+        typeof green_channel === `number` &&
+        typeof blue_channel === `number`);
 }
 // Extract color from a ShaderMaterial by checking common color uniform patterns
 function extract_shader_color(shader_mat) {
@@ -126,9 +129,7 @@ export function generate_mtl_content(scene) {
             lines.push(`Ks 0.500000 0.500000 0.500000`);
             lines.push(`Ns 96.078431`); // Specular exponent
             // Transparency (d = 1.0 is fully opaque)
-            const opacity = `opacity` in mat && typeof mat.opacity === `number`
-                ? mat.opacity
-                : 1.0;
+            const opacity = `opacity` in mat && typeof mat.opacity === `number` ? mat.opacity : 1.0;
             lines.push(`d ${opacity.toFixed(6)}`);
             // Illumination model (2 = highlight on)
             lines.push(`illum 2`);
@@ -148,7 +149,7 @@ function extract_material_color(mat) {
 // This is necessary because GLB/OBJ exporters don't handle InstancedMesh properly
 // Note: Threlte's InstancedMesh sets isInstancedMesh=true but type remains "Mesh"
 // Type guard for InstancedMesh (Three.js uses isInstancedMesh property, not exposed in Object3D type)
-const is_instanced_mesh = (obj) => obj.isInstancedMesh === true || obj.type === `InstancedMesh`;
+const is_instanced_mesh = (obj) => obj.isInstancedMesh || obj.type === `InstancedMesh`;
 function convert_instanced_meshes_to_regular(scene) {
     // STEP 1: Collect material colors from ORIGINAL scene BEFORE cloning
     // This is crucial because scene.clone() may not properly preserve Threlte's material colors
@@ -354,16 +355,14 @@ export function structure_to_xyz_str(structure) {
     if (formula && formula !== `Unknown`)
         comment_parts.push(formula);
     // Include extended XYZ lattice information when available so round-trips preserve lattice
-    if ((`lattice` in structure) && structure.lattice?.matrix?.length === 3) {
+    if (`lattice` in structure && structure.lattice?.matrix?.length === 3) {
         const lattice_values = structure.lattice.matrix
             .flat()
             .map((value) => (Number.isFinite(value) ? value : 0).toFixed(8))
             .join(` `);
         comment_parts.push(`Lattice="${lattice_values}"`);
     }
-    const comment = comment_parts.length > 0
-        ? comment_parts.join(` `)
-        : `Generated from structure`;
+    const comment = comment_parts.length > 0 ? comment_parts.join(` `) : `Generated from structure`;
     lines.push(comment);
     // Cache converter for fractional→Cartesian (if lattice available)
     const frac_to_cart = `lattice` in structure && structure.lattice?.matrix?.length === 3
@@ -373,9 +372,7 @@ export function structure_to_xyz_str(structure) {
     for (const site of structure.sites) {
         // Extract element symbol from species
         let element_symbol = `X`; // default fallback
-        if (site.species &&
-            Array.isArray(site.species) &&
-            site.species.length > 0) {
+        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
             // species is an array of Species objects with element property
             const first_species = site.species[0];
             if (first_species && `element` in first_species && first_species.element)
@@ -466,7 +463,8 @@ export function structure_to_cif_str(structure) {
         lines.push(`_cell_angle_gamma ${lattice.gamma.toFixed(6)}`);
     }
     // Space group information
-    if (`symmetry` in structure && structure.symmetry &&
+    if (`symmetry` in structure &&
+        structure.symmetry &&
         typeof structure.symmetry === `object`) {
         const symmetry = structure.symmetry;
         if (`space_group_symbol` in symmetry && symmetry.space_group_symbol) {
@@ -486,9 +484,7 @@ export function structure_to_cif_str(structure) {
     lines.push(`_atom_site_fract_z`);
     lines.push(`_atom_site_occupancy`);
     // Cache inverse transpose for Cartesian→fractional conversion (avoids recomputing per site)
-    const cart_to_frac = lattice.matrix?.length === 3
-        ? math.create_cart_to_frac(lattice.matrix)
-        : null;
+    const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
     // Atom sites
     for (let idx = 0; idx < structure.sites.length; idx++) {
         const site = structure.sites[idx];
@@ -497,9 +493,7 @@ export function structure_to_cif_str(structure) {
         // Extract element symbol from species
         let element_symbol = `X`; // default fallback
         let occupancy = 1;
-        if (site.species &&
-            Array.isArray(site.species) &&
-            site.species.length > 0) {
+        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
             const first_species = site.species[0];
             if (first_species && `element` in first_species && first_species.element) {
                 element_symbol = first_species.element;
@@ -553,9 +547,7 @@ export function structure_to_poscar_str(structure) {
     const element_symbols = [];
     for (const site of structure.sites) {
         let element_symbol = `X`; // default fallback
-        if (site.species &&
-            Array.isArray(site.species) &&
-            site.species.length > 0) {
+        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
             const first_species = site.species[0];
             if (first_species && `element` in first_species && first_species.element) {
                 element_symbol = first_species.element;
@@ -579,16 +571,12 @@ export function structure_to_poscar_str(structure) {
     // Coordinate mode (Direct = fractional coordinates)
     lines.push(`Direct`);
     // Cache inverse transpose for Cartesian→fractional conversion (avoids recomputing per site)
-    const cart_to_frac = lattice.matrix?.length === 3
-        ? math.create_cart_to_frac(lattice.matrix)
-        : null;
+    const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
     // Atom coordinates grouped by element
     for (const element_symbol of element_symbols) {
         for (const site of structure.sites) {
             let site_element = `X`;
-            if (site.species &&
-                Array.isArray(site.species) &&
-                site.species.length > 0) {
+            if (site.species && Array.isArray(site.species) && site.species.length > 0) {
                 const first_species = site.species[0];
                 if (first_species && `element` in first_species && first_species.element) {
                     site_element = first_species.element;

package/dist/structure/ferrox-wasm-types.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../math';
 export type WasmResult<T> = {
     ok: T;
 } | {
@@ -14,7 +15,7 @@ export declare function unwrap_or<T>(result: WasmResult<T>, default_value: T): T
 export interface NeighborListResult {
     center_indices: number[];
     neighbor_indices: number[];
-    image_offsets: [number, number, number][];
+    image_offsets: Vec3[];
     distances: number[];
 }
 export interface MatcherOptions {
@@ -28,7 +29,7 @@ export interface MatcherOptions {
 export type StructureFormat = `cif` | `poscar` | `json`;
 export type ReductionAlgorithm = `niggli` | `lll`;
 export interface HklInfo {
-    hkl: [number, number, number];
+    hkl: Vec3;
     multiplicity: number;
 }
 export interface XrdPattern {

package/dist/structure/ferrox-wasm-types.js

@@ -1,6 +1,3 @@
-// Pure type definitions and utility functions for ferrox-wasm results.
-// This module has no WASM side effects, making it safe to import in tests
-// without triggering WASM resolution.
 // Type guard to check if result is successful
 export function is_ok(result) {
     return `ok` in result;

package/dist/structure/ferrox-wasm.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../math';
 import type { Crystal } from './';
 import type { MatcherOptions, NeighborListResult, ReductionAlgorithm, StructureFormat, WasmResult, XrdOptions, XrdPattern } from './ferrox-wasm-types';
 export * from './ferrox-wasm-types';
@@ -81,8 +82,8 @@ export declare function interpolate_structures(start: Crystal, end: Crystal, n_i
 }): Promise<WasmResult<Crystal[]>>;
 export declare function copy_structure(structure: Crystal, sanitize?: boolean): Promise<WasmResult<Crystal>>;
 export declare function wrap_to_unit_cell(structure: Crystal): Promise<WasmResult<Crystal>>;
-export declare function create_supercell_matrix(structure: Crystal, matrix: [[number, number, number], [number, number, number], [number, number, number]]): Promise<WasmResult<Crystal>>;
-export declare function translate_sites(structure: Crystal, indices: number[], vector: [number, number, number], frac_coords?: boolean): Promise<WasmResult<Crystal>>;
+export declare function create_supercell_matrix(structure: Crystal, matrix: [Vec3, Vec3, Vec3]): Promise<WasmResult<Crystal>>;
+export declare function translate_sites(structure: Crystal, indices: number[], vector: Vec3, frac_coords?: boolean): Promise<WasmResult<Crystal>>;
 export declare function perturb_structure(structure: Crystal, distance: number, options?: {
     min_distance?: number;
     seed?: number;

package/dist/structure/ferrox-wasm.js

@@ -25,8 +25,7 @@ export function ensure_ferrox_wasm_ready() {
         init_promise = (async () => {
             try {
                 // Dynamic import to avoid loading WASM until needed
-                const { default: init } = (await import(
-                /* @vite-ignore */ `matterviz-wasm`));
+                const { default: init } = (await import(`matterviz-wasm`));
                 // Initialize WASM module (the package handles WASM loading internally)
                 wasm_module = await init();
                 return wasm_module;
@@ -34,7 +33,7 @@ export function ensure_ferrox_wasm_ready() {
             catch (err) {
                 // Clear the promise on failure so retry is possible
                 init_promise = null;
-                throw new Error(`Failed to load matterviz-wasm. Install with: pnpm add matterviz-wasm. Original error: ${err}`);
+                throw new Error(`Failed to load matterviz-wasm. Install with: npm add matterviz-wasm. Original error: ${err}`, { cause: err });
             }
         })();
     }

package/dist/structure/index.d.ts

@@ -67,6 +67,21 @@ export declare function format_formula_by_electronegativity(structure: AnyStruct
 export declare const atomic_radii: CompositionType;
 export declare function get_density(structure: Crystal): number;
 export declare function get_center_of_mass(structure: AnyStructure): Vec3;
+export declare const VECTOR_KEY_PREFIXES: readonly ["force", "forces", "magmom", "magmoms", "spin", "spins"];
+export declare function is_vector_key(key: string): boolean;
+export declare const VECTOR_PALETTE: readonly ["#e74c3c", "#3498db", "#2ecc71", "#f39c12", "#9b59b6", "#1abc9c"];
+export declare const default_vector_configs: (keys: string[]) => {
+    [k: string]: {
+        visible: boolean;
+        color: "#e74c3c" | "#3498db" | "#2ecc71" | "#f39c12" | "#9b59b6" | "#1abc9c" | null;
+        scale: null;
+    };
+};
+export declare function get_all_site_vectors(site: Site): {
+    vec: Vec3;
+    key: string;
+}[];
+export declare function get_structure_vector_keys(structure: AnyStructure): string[];
 export interface StructureHandlerData {
     structure?: AnyStructure;
     filename?: string;
@@ -75,6 +90,7 @@ export interface StructureHandlerData {
     error_msg?: string;
     fullscreen?: boolean;
     camera_position?: Vec3;
+    camera_target?: Vec3;
     camera_has_moved?: boolean;
     color_scheme?: string;
     performance_mode?: `quality` | `speed`;

package/dist/structure/index.js

@@ -42,16 +42,14 @@ export function format_chemical_formula(structure, sort_fn) {
 }
 export function format_formula_by_electronegativity(structure) {
     // concatenate elements in a structure followed by their amount sorted by electronegativity
-    return format_chemical_formula(structure, (symbols) => (symbols.sort((el1, el2) => {
-        const elec_neg1 = element_data.find((el) => el.symbol === el1)?.electronegativity ??
-            0;
-        const elec_neg2 = element_data.find((el) => el.symbol === el2)?.electronegativity ??
-            0;
+    return format_chemical_formula(structure, (symbols) => symbols.sort((el1, el2) => {
+        const elec_neg1 = element_data.find((el) => el.symbol === el1)?.electronegativity ?? 0;
+        const elec_neg2 = element_data.find((el) => el.symbol === el2)?.electronegativity ?? 0;
         // Sort by electronegativity (ascending), then alphabetically for ties
         if (elec_neg1 !== elec_neg2)
             return elec_neg1 - elec_neg2;
         return el1.localeCompare(el2);
-    })));
+    }));
 }
 // Atomic radii in Angstroms (used for relative sizing, not absolute rendering scale)
 export const atomic_radii = Object.fromEntries(element_data.map((el) => [el.symbol, el.atomic_radius ?? 1]));
@@ -84,3 +82,87 @@ export function get_center_of_mass(structure) {
     }
     return math.scale(center, 1 / total_weight);
 }
+// Recognized prefixes for per-site vector data (force, magnetic moment, spin).
+// Both singular and plural forms are accepted. Keys matching exactly or starting
+// with one of these followed by `_` (e.g. `force_DFT`) are treated as vectors.
+export const VECTOR_KEY_PREFIXES = [
+    `force`,
+    `forces`,
+    `magmom`,
+    `magmoms`,
+    `spin`,
+    `spins`,
+];
+export function is_vector_key(key) {
+    return VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`));
+}
+// Default color palette for distinguishing multiple vector layers
+export const VECTOR_PALETTE = [
+    `#e74c3c`,
+    `#3498db`,
+    `#2ecc71`,
+    `#f39c12`,
+    `#9b59b6`,
+    `#1abc9c`,
+];
+// Single key → null color (semantic coloring); multiple keys → palette colors.
+export const default_vector_configs = (keys) => Object.fromEntries(keys.map((key, idx) => [
+    key,
+    {
+        visible: true,
+        color: keys.length > 1 ? VECTOR_PALETTE[idx % VECTOR_PALETTE.length] : null,
+        scale: null,
+    },
+]));
+function try_parse_vec3(val) {
+    if (Array.isArray(val) &&
+        val.length === 3 &&
+        val.every((elem) => typeof elem === `number` && isFinite(elem)))
+        return val;
+    if (typeof val === `number` && isFinite(val))
+        return [0, 0, val];
+    return null;
+}
+// Priority index for ordering: bare names first in VECTOR_KEY_PREFIXES order,
+// then prefixed keys in the same prefix order, alphabetically within each prefix group.
+function vector_key_sort_order(key) {
+    for (const [prefix_idx, prefix] of VECTOR_KEY_PREFIXES.entries()) {
+        if (key === prefix)
+            return [prefix_idx, 0, ``];
+        if (key.startsWith(`${prefix}_`))
+            return [prefix_idx, 1, key];
+    }
+    return [VECTOR_KEY_PREFIXES.length, 0, key];
+}
+function compare_vector_keys(left, right) {
+    const ord_l = vector_key_sort_order(left);
+    const ord_r = vector_key_sort_order(right);
+    return ord_l[0] - ord_r[0] || ord_l[1] - ord_r[1] || ord_l[2].localeCompare(ord_r[2]);
+}
+// Extract ALL vector properties from a site (not just the first match).
+// Returns entries for every key that is_vector_key() and has a valid 3D vector value.
+// Ordered by VECTOR_KEY_PREFIXES priority, then alphabetically for prefixed keys.
+export function get_all_site_vectors(site) {
+    const props = site.properties;
+    if (!props)
+        return [];
+    const results = [];
+    for (const key of Object.keys(props)) {
+        if (!is_vector_key(key))
+            continue;
+        const vec = try_parse_vec3(props[key]);
+        if (vec)
+            results.push({ vec, key });
+    }
+    return results.sort((left, right) => compare_vector_keys(left.key, right.key));
+}
+// Collect the union of all vector property keys across all sites in a structure,
+// preserving VECTOR_KEY_PREFIXES priority order.
+export function get_structure_vector_keys(structure) {
+    const seen = new Set();
+    for (const site of structure.sites) {
+        for (const { key } of get_all_site_vectors(site))
+            seen.add(key);
+    }
+    return [...seen].sort(compare_vector_keys);
+}

package/dist/structure/measure.d.ts

@@ -1,6 +1,6 @@
-import type { Matrix3x3, Vec3 } from '../math';
+import type { LatticeConverters, Matrix3x3, Vec3 } from '../math';
 export type AngleMode = `degrees` | `radians`;
 export declare const MAX_SELECTED_SITES = 8;
-export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, lattice_inv?: Matrix3x3): Vec3;
+export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters): Vec3;
 export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3): number;
 export declare function angle_between_vectors(v1: Vec3, v2: Vec3, mode?: AngleMode): number;

package/dist/structure/measure.js

@@ -1,55 +1,15 @@
 // functions for measuring distances and angles between structure sites
-import { mat3x3_vec3_multiply, matrix_inverse_3x3, subtract } from '../math';
+import { min_image_displacement, subtract } from '../math';
 export const MAX_SELECTED_SITES = 8;
 // Calculate minimum image displacement between two points under PBC
 // If lattice_matrix is null/undefined, returns Euclidean displacement
-export function displacement_pbc(from, to, lattice_matrix, lattice_inv) {
-    // For non-periodic structures, return direct displacement
+export function displacement_pbc(from, to, lattice_matrix, converters) {
     if (!lattice_matrix)
         return subtract(to, from);
-    const inv_mat = lattice_inv ?? matrix_inverse_3x3(lattice_matrix);
-    const frac_from = mat3x3_vec3_multiply(inv_mat, from);
-    const frac_to = mat3x3_vec3_multiply(inv_mat, to);
-    // Wrap fractional coordinates to [0,1) for easier boundary checking
-    const frac_from_wrapped = [
-        frac_from[0] - Math.floor(frac_from[0]),
-        frac_from[1] - Math.floor(frac_from[1]),
-        frac_from[2] - Math.floor(frac_from[2]),
-    ];
-    const frac_to_wrapped = [
-        frac_to[0] - Math.floor(frac_to[0]),
-        frac_to[1] - Math.floor(frac_to[1]),
-        frac_to[2] - Math.floor(frac_to[2]),
-    ];
-    // Find minimum image by testing all nearby lattice translations
-    let min_dist_sq = Infinity;
-    let best_displacement = [0, 0, 0];
-    // Test lattice images in a 3x3x3 neighborhood (sufficient for minimum image)
-    for (let ii = -1; ii <= 1; ii++) {
-        for (let jj = -1; jj <= 1; jj++) {
-            for (let kk = -1; kk <= 1; kk++) {
-                // Fractional displacement with lattice translation
-                const frac_diff = [
-                    frac_to_wrapped[0] - frac_from_wrapped[0] + ii,
-                    frac_to_wrapped[1] - frac_from_wrapped[1] + jj,
-                    frac_to_wrapped[2] - frac_from_wrapped[2] + kk,
-                ];
-                // Convert to cartesian
-                const cart_diff = mat3x3_vec3_multiply(lattice_matrix, frac_diff);
-                const dist_sq = cart_diff[0] ** 2 + cart_diff[1] ** 2 + cart_diff[2] ** 2;
-                // Keep the shortest displacement
-                if (dist_sq < min_dist_sq) {
-                    min_dist_sq = dist_sq;
-                    best_displacement = cart_diff;
-                }
-            }
-        }
-    }
-    return best_displacement;
+    return min_image_displacement(from, to, lattice_matrix, converters);
 }
 export function distance_pbc(a, b, lattice_matrix) {
-    const inv_mat = matrix_inverse_3x3(lattice_matrix);
-    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix, inv_mat);
+    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix);
     return Math.hypot(dx, dy, dz);
 }
 export function angle_between_vectors(v1, v2, mode = `degrees`) {