matterviz 0.3.0 → 0.3.2

package/dist/structure/Structure.svelte

@@ -1,19 +1,25 @@
 <script lang="ts">import { ELEMENT_COLOR_SCHEMES } from '../colors';
 import { normalize_show_controls } from '../controls';
+import { StatusMessage } from '../feedback';
 import Spinner from '../feedback/Spinner.svelte';
 import Icon from '../Icon.svelte';
-import { decompress_file, handle_url_drop, load_from_url } from '../io';
+import { create_file_drop_handler, load_from_url } from '../io';
+import { parse_volumetric_file } from '../isosurface/parse';
+import { auto_isosurface_settings, DEFAULT_ISOSURFACE_SETTINGS, } from '../isosurface/types';
+import { ELEM_SYMBOLS } from '../labels';
 import { set_fullscreen_bg, toggle_fullscreen } from '../layout';
+import { create_cart_to_frac, create_frac_to_cart } from '../math';
 import { DEFAULTS } from '../settings';
 import { colors } from '../state.svelte';
-import { get_element_counts, get_pbc_image_sites } from './';
+import { get_element_counts, get_pbc_image_sites, get_site_vector, } from './';
+import { wrap_to_unit_cell } from './pbc';
 import { is_valid_supercell_input, make_supercell } from './supercell';
 import * as symmetry from '../symmetry';
 import { transform_cell } from '../symmetry';
 import { Canvas } from '@threlte/core';
 import { untrack } from 'svelte';
 import { click_outside, tooltip } from 'svelte-multiselect';
-import { SvelteMap } from 'svelte/reactivity';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { get_property_colors } from './atom-properties';
 import AtomLegend from './AtomLegend.svelte';
 import CellSelect from './CellSelect.svelte';
@@ -34,7 +40,7 @@ let lattice_props = $state({
     cell_edge_width: DEFAULTS.structure.cell_edge_width,
     show_cell_vectors: DEFAULTS.structure.show_cell_vectors,
 });
-let { structure = $bindable(), scene_props: scene_props_in = $bindable(), lattice_props: lattice_props_in = $bindable(), controls_open = $bindable(false), info_pane_open = $bindable(false), enable_measure_mode = $bindable(true), background_color = $bindable(), background_opacity = $bindable(0.1), show_controls, fullscreen = $bindable(false), wrapper = $bindable(), width = $bindable(0), height = $bindable(0), reset_text = `Reset camera (or double-click)`, color_scheme = $bindable(`Vesta`), atom_color_config = $bindable({
+let { structure = $bindable(), scene_props: scene_props_in = $bindable(), lattice_props: lattice_props_in = $bindable(), controls_open = $bindable(false), info_pane_open = $bindable(false), enable_measure_mode = $bindable(true), measure_mode = $bindable(`distance`), background_color = $bindable(), background_opacity = $bindable(0.1), show_controls, fullscreen = $bindable(false), wrapper = $bindable(), width = $bindable(0), height = $bindable(0), reset_text = `Reset camera (or double-click)`, color_scheme = $bindable(`Vesta`), atom_color_config = $bindable({
     mode: DEFAULTS.structure.atom_color_mode,
     scale: DEFAULTS.structure.atom_color_scale,
     scale_type: DEFAULTS.structure.atom_color_scale_type,
@@ -46,9 +52,9 @@ measured_sites = $bindable([]),
 // expose the displayed structure (with image atoms and supercell) for external use
 displayed_structure = $bindable(), 
 // Track hidden elements across component lifecycle
-hidden_elements = $bindable(new Set()), 
+hidden_elements = $bindable(new SvelteSet()), 
 // Track hidden property values (e.g. Wyckoff positions, coordination numbers)
-hidden_prop_vals = $bindable(new Set()), 
+hidden_prop_vals = $bindable(new SvelteSet()), 
 // Per-element radius overrides (absolute values in Angstroms)
 element_radius_overrides = $bindable({}), 
 // Per-site radius overrides (absolute values in Angstroms)
@@ -61,7 +67,15 @@ symmetry_settings = $bindable(symmetry.default_sym_settings),
 // Useful for LAMMPS files where atom types are mapped to H, He, Li by default
 element_mapping = $bindable(), 
 // Cell type: original, conventional, or primitive (requires symmetry analysis)
-cell_type = $bindable(`original`), children, top_right_controls, on_file_load, on_error, on_fullscreen_change, on_camera_move, on_camera_reset, ...rest } = $props();
+cell_type = $bindable(`original`), 
+// Volumetric data for isosurface rendering (parsed from CHGCAR or .cube files)
+volumetric_data = $bindable(), 
+// Isosurface rendering settings
+isosurface_settings = $bindable({
+    ...DEFAULT_ISOSURFACE_SETTINGS,
+}), 
+// Active volume index when multiple volumes are present
+active_volume_idx = $bindable(0), children, top_right_controls, on_file_load, on_error, on_fullscreen_change, on_camera_move, on_camera_reset, ...rest } = $props();
 // Initialize models from incoming props; mutations come from UI controls; we mirror into local dicts (NOTE only doing shallow merge)
 $effect.pre(() => {
     if (scene_props_in && typeof scene_props_in === `object`) {
@@ -85,21 +99,8 @@ $effect(() => {
                     const text_content = content instanceof ArrayBuffer
                         ? new TextDecoder().decode(content)
                         : content;
-                    const parsed_structure = parse_any_structure(text_content, filename);
-                    if (parsed_structure) {
-                        structure = parsed_structure;
-                        // Emit file load event
-                        on_file_load?.({
-                            structure,
-                            filename,
-                            file_size: new Blob([content]).size,
-                            total_atoms: structure.sites?.length || 0,
-                        });
-                    }
-                    else {
-                        error_msg = `Failed to parse structure from ${filename}`;
-                        on_error?.({ error_msg, filename });
-                    }
+                    const parsed = parse_file_content(text_content, filename);
+                    emit_file_load_event(parsed, filename, content);
                 }
                 catch (error) {
                     error_msg = `Failed to parse structure: ${error instanceof Error ? error.message : String(error)}`;
@@ -141,17 +142,18 @@ $effect(() => {
 });
 // Track if force vectors were auto-enabled to prevent repeated triggering
 let force_vectors_auto_enabled = $state(false);
-// Auto-enable force vectors when structure has force data
+// Auto-enable force vectors when structure has vector data (force, magmom, or spin)
 $effect(() => {
     if (structure?.sites && !force_vectors_auto_enabled) {
-        const has_force_data = structure.sites.some((site) => site.properties?.force && Array.isArray(site.properties.force));
-        // Enable force vectors if structure has force data
-        if (has_force_data && !scene_props.show_force_vectors) {
+        const has_vector_data = structure.sites.some((site) => get_site_vector(site) !== null);
+        if (!has_vector_data)
+            return;
+        if (!scene_props.show_force_vectors) {
             scene_props.show_force_vectors = true;
             scene_props.force_scale ??= DEFAULTS.structure.force_scale;
             scene_props.force_color ??= DEFAULTS.structure.force_color;
-            force_vectors_auto_enabled = true;
         }
+        force_vectors_auto_enabled = true;
     }
 });
 // Optimize scene props for performance based on structure size and mode
@@ -172,23 +174,40 @@ $effect(() => {
 let property_colors = $derived(get_property_colors(structure, atom_color_config, scene_props.bonding_strategy, sym_data));
 let symmetry_run_id = 0;
 let symmetry_error = $state();
-// Trigger symmetry analysis when structure is loaded or settings change
+let last_symmetry_structure_ref = null;
+// Trigger symmetry analysis when structure is loaded or settings change.
+// Skip during atom drags — symmetry doesn't change from moving atoms,
+// and WASM analysis on every drag frame causes severe frame drops.
 $effect(() => {
+    if (dragging_atoms)
+        return;
     if (!structure || !(`lattice` in structure)) {
         untrack(() => {
             sym_data = null;
             symmetry_error = undefined;
         });
+        last_symmetry_structure_ref = null;
         return;
     }
     const current_structure = structure;
+    const structure_changed = current_structure !== last_symmetry_structure_ref;
+    if (structure_changed) {
+        untrack(() => {
+            sym_data = null;
+            symmetry_error = undefined;
+        });
+        last_symmetry_structure_ref = current_structure;
+    }
+    else {
+        // Keep previous symmetry data while recomputing so bound consumers
+        // (e.g. SymmetryStats inputs) do not unmount and lose focus.
+        untrack(() => symmetry_error = undefined);
+    }
     const run_id = ++symmetry_run_id;
     // Destructure symmetry_settings to ensure Svelte tracks changes to symprec and algo
     // (reading just the object reference isn't sufficient for fine-grained reactivity)
     const { symprec, algo } = symmetry_settings ?? symmetry.default_sym_settings;
     const current_settings = { symprec, algo };
-    // Use untrack to prevent cascading reactivity when resetting state
-    untrack(() => [sym_data, symmetry_error] = [null, undefined]);
     symmetry.ensure_moyo_wasm_ready()
         .then(() => run_id === symmetry_run_id
         ? symmetry.analyze_structure_symmetry(current_structure, current_settings)
@@ -200,18 +219,129 @@ $effect(() => {
     })
         .catch((err) => {
         if (run_id === symmetry_run_id) {
+            untrack(() => sym_data = null);
             symmetry_error = `Symmetry analysis failed: ${err?.message || err}`;
             console.error(`Symmetry analysis failed:`, err);
         }
     });
 });
-// Measurement mode and selection state
-let measure_mode = $state(`distance`);
 let measure_menu_open = $state(false);
 let export_pane_open = $state(false);
 // Bond customization state
 let added_bonds = $state([]);
 let removed_bonds = $state([]);
+// === Edit-atoms mode state ===
+let dragging_atoms = $state(false);
+let undo_stack = $state([]);
+let redo_stack = $state([]);
+const MAX_HISTORY = 20;
+// Flag set before internal edits (undo/redo/delete/add/move) to distinguish
+// them from external structure changes (file load, trajectory step, etc.)
+let is_internal_edit = false;
+// Add-atom sub-mode state (bound to StructureScene)
+let add_atom_mode = $state(false);
+let add_element = $state(`C`);
+let canvas_cursor = $state(`default`);
+let change_element_mode = $state(false);
+let change_element_value = $state(``);
+// Ephemeral toast message for edit operations
+let toast_msg = $state(null);
+let toast_timer;
+function show_toast(msg, duration_ms = 2000) {
+    clearTimeout(toast_timer);
+    toast_msg = msg;
+    toast_timer = setTimeout(() => (toast_msg = null), duration_ms);
+}
+// Normalize and validate element symbol (e.g. "fe" → "Fe", "Xx" → null)
+function normalize_element(input) {
+    const normalized = (input.charAt(0).toUpperCase() +
+        input.slice(1).toLowerCase());
+    return ELEM_SYMBOLS.includes(normalized) ? normalized : null;
+}
+function clear_selection() {
+    selected_sites = [];
+    measured_sites = [];
+    dragging_atoms = false;
+}
+function push_undo() {
+    if (!structure)
+        return;
+    if (undo_stack.length >= MAX_HISTORY) {
+        undo_stack.splice(0, undo_stack.length - MAX_HISTORY + 1);
+    }
+    undo_stack.push($state.snapshot(structure));
+    redo_stack.length = 0;
+}
+// Shared undo/redo: pop from `source`, push current state onto `target`
+function apply_history(source, target) {
+    if (source.length === 0 || !structure)
+        return;
+    const restored = source.pop();
+    if (!restored)
+        return;
+    is_internal_edit = true;
+    target.push($state.snapshot(structure));
+    structure = restored;
+    clear_selection();
+}
+const undo = () => apply_history(undo_stack, redo_stack);
+const redo = () => apply_history(redo_stack, undo_stack);
+// Clear undo/redo stacks when structure changes externally (file load, etc.)
+// Internal edits set is_internal_edit=true before modifying structure.
+// This $effect runs after microtask, so the flag is still set from the edit.
+$effect(() => {
+    // Track structure to re-run when it changes
+    void structure;
+    if (is_internal_edit) {
+        is_internal_edit = false;
+        return;
+    }
+    // External change — clear history and stale edit-atoms state
+    untrack(() => {
+        if (undo_stack.length > 0 || redo_stack.length > 0) {
+            undo_stack = [];
+            redo_stack = [];
+        }
+        if (measure_mode === `edit-atoms`) {
+            if (selected_sites.length > 0 || measured_sites.length > 0)
+                clear_selection();
+            if (site_radius_overrides?.size > 0)
+                site_radius_overrides.clear();
+        }
+    });
+});
+// Clear selection when switching measure/edit mode so stale state doesn't carry over
+let mode_first_run = true;
+$effect(() => {
+    void measure_mode; // track reactively
+    if (mode_first_run) {
+        mode_first_run = false;
+        return;
+    }
+    untrack(() => {
+        if (selected_sites.length > 0 || measured_sites.length > 0)
+            clear_selection();
+    });
+});
+// Auto-bake cell type transform and clear stale state when entering edit-atoms mode
+$effect(() => {
+    if (measure_mode !== `edit-atoms`)
+        return;
+    untrack(() => {
+        // Clear bond edits from edit-bonds mode to avoid stale state
+        if (added_bonds.length > 0 || removed_bonds.length > 0) {
+            added_bonds = [];
+            removed_bonds = [];
+        }
+        if (cell_type !== `original` && cell_transformed_structure && structure) {
+            // Bake the transformed cell: push original to undo, replace structure
+            is_internal_edit = true;
+            push_undo();
+            structure = $state.snapshot(cell_transformed_structure);
+            cell_type = `original`;
+        }
+    });
+});
 let controls_config = $derived(normalize_show_controls(show_controls));
 // Normalize structure coordinates: wrap fractional coords to [0,1) and recompute Cartesian
 // This ensures atoms are rendered inside the unit cell regardless of data source
@@ -242,13 +372,10 @@ let cell_transformed_structure = $derived.by(() => {
 // Create supercell if needed (uses cell_transformed_structure as base)
 let supercell_structure = $state(structure);
 let supercell_loading = $state(false);
+let has_supercell = $derived(!!supercell_scaling && ![``, `1x1x1`, `1`].includes(supercell_scaling));
 $effect(() => {
     const base_structure = cell_transformed_structure;
-    if (!base_structure || !(`lattice` in base_structure)) {
-        supercell_structure = base_structure;
-        supercell_loading = false;
-    }
-    else if ([``, `1x1x1`, `1`].includes(supercell_scaling)) {
+    if (!base_structure || !(`lattice` in base_structure) || !has_supercell) {
         supercell_structure = base_structure;
         supercell_loading = false;
     }
@@ -303,16 +430,20 @@ $effect(() => {
         return;
     }
     untrack(() => {
-        if (selected_sites.length > 0 || measured_sites.length > 0) {
-            selected_sites = [];
-            measured_sites = [];
-        }
+        // In edit-atoms mode, structure changes are intentional user edits
+        // (move/add/delete) — preserve the selection so TransformControls stays active
+        if (measure_mode === `edit-atoms`)
+            return;
+        if (selected_sites.length > 0 || measured_sites.length > 0)
+            clear_selection();
         // Clear site radius overrides since site indices are no longer valid
         if (site_radius_overrides?.size > 0)
             site_radius_overrides.clear();
     });
 });
-// Apply element mapping then image atoms to the supercell structure
+// Apply element mapping then image atoms to the supercell structure.
+// Skip get_pbc_image_sites during atom drags — the vector math + doubled site
+// count causes frame drops. Image atoms reappear instantly on drag release.
 $effect(() => {
     let struct = supercell_structure;
     if (struct && element_mapping && Object.keys(element_mapping).length > 0) {
@@ -330,7 +461,8 @@ $effect(() => {
         };
     }
     displayed_structure =
-        show_image_atoms && struct && `lattice` in struct && struct.lattice
+        !dragging_atoms && show_image_atoms && struct && `lattice` in struct &&
+            struct.lattice
             ? get_pbc_image_sites(struct)
             : struct;
 });
@@ -342,7 +474,6 @@ let camera = $state(undefined);
 let orbit_controls = $state(undefined);
 let rotation_target_ref = $state(undefined);
 let initial_computed_zoom = $state(undefined);
-let camera_move_timeout = $state(null);
 // Mutual exclusion: opening one pane closes others
 $effect(() => {
     if (info_pane_open) {
@@ -364,29 +495,53 @@ $effect(() => {
     if (structure)
         camera_has_moved = false;
 });
-// Set camera_has_moved to true when camera starts moving
-$effect(() => untrack(() => {
-    if (camera_is_moving) {
-        camera_has_moved = true;
-        // Debounce camera move events to avoid excessive emissions
-        if (camera_move_timeout)
-            clearTimeout(camera_move_timeout);
-        camera_move_timeout = setTimeout(() => {
-            const { camera_position } = scene_props;
-            on_camera_move?.({ structure, camera_has_moved, camera_position });
-        }, 200);
-    }
-}));
+const read_orbit_target = () => {
+    if (!orbit_controls?.target)
+        return;
+    const { x, y, z } = orbit_controls.target;
+    return [x, y, z];
+};
+const read_camera_position = () => camera
+    ? [camera.position.x, camera.position.y, camera.position.z]
+    : scene_props.camera_position;
+// Emit debounced camera updates while controls are active.
+$effect(() => {
+    if (!camera_is_moving)
+        return;
+    camera_has_moved = true;
+    const emit_camera_move = () => {
+        const camera_position = read_camera_position();
+        if (camera_position === undefined)
+            return;
+        const camera_target = read_orbit_target();
+        scene_props.camera_position = camera_position;
+        scene_props.camera_target = camera_target;
+        on_camera_move?.({
+            structure,
+            camera_has_moved,
+            camera_position,
+            camera_target,
+        });
+    };
+    emit_camera_move();
+    const emit_interval = setInterval(emit_camera_move, 200);
+    return () => clearInterval(emit_interval);
+});
 function reset_camera() {
-    // Reset camera position to trigger automatic positioning
+    // Reset camera position to trigger automatic positioning.
     scene_props.camera_position = [0, 0, 0];
+    scene_props.camera_target = rotation_target_ref;
     camera_has_moved = false;
-    // Manually reset zoom and pan using the exposed initial values
+    let camera_position = [0, 0, 0];
+    let camera_target = rotation_target_ref;
+    // Reset pan/zoom and ensure controls target returns to structure center.
     if (orbit_controls && camera) {
-        // Reset the target to the structure center (pan reset)
+        if (`reset` in orbit_controls &&
+            typeof orbit_controls.reset === `function`)
+            orbit_controls.reset();
         if (orbit_controls.target && rotation_target_ref) {
-            const [x, y, z] = rotation_target_ref;
-            orbit_controls.target.set(x, y, z);
+            const [target_x, target_y, target_z] = rotation_target_ref;
+            orbit_controls.target.set(target_x, target_y, target_z);
         }
         // Reset zoom for orthographic camera
         if (`zoom` in camera && initial_computed_zoom !== undefined) {
@@ -395,11 +550,14 @@ function reset_camera() {
             ortho_camera.updateProjectionMatrix();
         }
         // Call update to apply changes immediately
-        if (typeof orbit_controls.update === `function`) {
+        if (typeof orbit_controls.update === `function`)
             orbit_controls.update();
-        }
+        camera_position = read_camera_position() ?? camera_position;
+        camera_target = read_orbit_target();
     }
-    on_camera_reset?.({ structure, camera_has_moved, camera_position: [0, 0, 0] });
+    scene_props.camera_position = camera_position;
+    scene_props.camera_target = camera_target;
+    on_camera_reset?.({ structure, camera_has_moved, camera_position, camera_target });
 }
 const emit_file_load_event = (structure, filename, content) => on_file_load?.({
     structure: structure,
@@ -409,93 +567,320 @@ const emit_file_load_event = (structure, filename, content) => on_file_load?.({
         : content.byteLength,
     total_atoms: structure.sites?.length || 0,
 });
-async function handle_file_drop(event) {
-    event.preventDefault();
-    dragover = false;
-    if (!allow_file_drop)
-        return;
-    loading = true;
-    error_msg = undefined; // Clear previous error when a new file is dropped
-    try {
-        // Handle URL-based files (e.g. from FilePicker)
-        const handled = await handle_url_drop(event, on_file_drop || ((content, filename) => {
-            try {
-                const text_content = content instanceof ArrayBuffer
-                    ? new TextDecoder().decode(content)
-                    : content;
-                const parsed_structure = parse_any_structure(text_content, filename);
-                if (parsed_structure) {
-                    structure = parsed_structure;
-                    emit_file_load_event(parsed_structure, filename, content);
-                }
-                else
-                    throw new Error(`Failed to parse structure from ${filename}`);
-            }
-            catch (err) {
-                error_msg = `Failed to parse structure: ${err}`;
-                on_error?.({ error_msg, filename });
-            }
-        })).catch(() => false);
-        if (handled)
-            return;
-        // Handle file system drops
-        const file = event.dataTransfer?.files[0];
-        if (file) {
-            try {
-                const { content, filename } = await decompress_file(file);
-                if (content) {
-                    if (on_file_drop)
-                        on_file_drop(content, filename);
-                    else {
-                        // Parse structure internally when no handler provided
-                        try {
-                            const parsed_structure = parse_any_structure(content, filename);
-                            if (parsed_structure) {
-                                structure = parsed_structure;
-                                emit_file_load_event(parsed_structure, filename, content);
-                            }
-                            else
-                                throw new Error(`Failed to parse structure from ${filename}`);
-                        }
-                        catch (err) {
-                            error_msg = `Failed to parse structure: ${err}`;
-                            on_error?.({ error_msg, filename });
-                        }
-                    }
-                }
-            }
-            catch (error) {
-                error_msg = `Failed to load file ${file.name}: ${error}`;
-                on_error?.({ error_msg, filename: file.name });
-            }
-        }
-    }
-    finally {
-        loading = false;
+// Try to parse content as a volumetric file, setting both structure and volumetric data.
+// Delegates format detection entirely to parse_volumetric_file (filename + content sniffing).
+// Returns the parsed structure on success, or null if the file isn't a volumetric format.
+function try_parse_volumetric(text_content, filename) {
+    const vol_result = parse_volumetric_file(text_content, filename);
+    if (!vol_result)
+        return null;
+    // parse_volumetric_file extracts structure from file header;
+    // parsers set pbc so the lattice conforms to Crystal's LatticeType
+    structure = vol_result.structure;
+    volumetric_data = vol_result.volumes;
+    // Auto-compute reasonable isosurface settings from data range
+    const vol = vol_result.volumes[0];
+    if (vol) {
+        isosurface_settings = auto_isosurface_settings(vol.data_range);
+        active_volume_idx = 0;
     }
+    return structure;
 }
-function onkeydown(event) {
+// Parse file content, trying volumetric format first then falling back to plain structure.
+// Returns the parsed structure on success, throws on failure.
+function parse_file_content(text_content, filename) {
+    const vol_struct = try_parse_volumetric(text_content, filename);
+    if (vol_struct)
+        return vol_struct;
+    // Clear stale volumetric data when loading a non-volumetric file
+    volumetric_data = [];
+    const parsed = parse_any_structure(text_content, filename);
+    if (!parsed)
+        throw new Error(`Failed to parse structure from ${filename}`);
+    structure = parsed;
+    return parsed;
+}
+const handle_file_drop = create_file_drop_handler({
+    allow: () => allow_file_drop,
+    on_drop: (content, filename) => {
+        if (on_file_drop)
+            return on_file_drop(content, filename);
+        try {
+            const text_content = content instanceof ArrayBuffer
+                ? new TextDecoder().decode(content)
+                : content;
+            const parsed = parse_file_content(text_content, filename);
+            emit_file_load_event(parsed, filename, content);
+        }
+        catch (err) {
+            error_msg = `Failed to parse structure: ${err instanceof Error ? err.message : String(err)}`;
+            on_error?.({ error_msg, filename });
+        }
+    },
+    on_error: (msg) => {
+        error_msg = msg;
+        on_error?.({ error_msg: msg });
+    },
+    set_loading: (val) => {
+        loading = val;
+        if (val)
+            [error_msg, dragover] = [undefined, false];
+    },
+});
+function handle_keydown(event) {
     // Don't handle shortcuts if user is typing in an input field
     const target = event.target;
     const is_input_focused = target.tagName === `INPUT` ||
         target.tagName === `TEXTAREA`;
+    // Allow Escape to cancel add-atom mode even when the element input is focused
+    if (event.key === `Escape` && measure_mode === `edit-atoms` && add_atom_mode) {
+        event.preventDefault();
+        add_atom_mode = false;
+        return;
+    }
     if (is_input_focused)
         return;
-    // Interface shortcuts
-    if (event.key === `f` && fullscreen_toggle)
+    // Edit-atoms mode shortcuts (including undo/redo)
+    if (measure_mode === `edit-atoms`) {
+        // Undo/redo shortcuts (Ctrl/Cmd + Z/Y) — only active in edit-atoms mode
+        if (event.ctrlKey || event.metaKey) {
+            const key = event.key.toLowerCase();
+            if (key === `z` && !event.shiftKey) {
+                event.preventDefault();
+                undo();
+                show_toast(`Undo (${undo_stack.length} left)`);
+                return;
+            }
+            else if (key === `y` || (key === `z` && event.shiftKey)) {
+                event.preventDefault();
+                redo();
+                show_toast(`Redo (${redo_stack.length} left)`);
+                return;
+            }
+        }
+        if (event.key === `Delete` || event.key === `Backspace`) {
+            // Delete selected atoms
+            if (selected_sites.length > 0 && structure?.sites) {
+                event.preventDefault();
+                is_internal_edit = true;
+                push_undo();
+                const to_delete = scene_to_structure_indices(selected_sites, true);
+                const n_deleted = to_delete.size;
+                clear_selection();
+                structure = {
+                    ...structure,
+                    sites: structure.sites.filter((_, idx) => !to_delete.has(idx)),
+                };
+                // Clear per-site overrides since indices shifted after deletion
+                if (site_radius_overrides?.size > 0)
+                    site_radius_overrides.clear();
+                added_bonds = [];
+                removed_bonds = [];
+                show_toast(`Deleted ${n_deleted} site${n_deleted > 1 ? `s` : ``}`);
+            }
+            return;
+        }
+        const key = event.key.toLowerCase();
+        const plain = !event.ctrlKey && !event.metaKey && !event.altKey;
+        if (key === `a` && plain) {
+            // Enter add-atom sub-mode (plain 'a' only, not Ctrl+A/Cmd+A/Alt+A)
+            event.preventDefault();
+            add_atom_mode = !add_atom_mode;
+            return;
+        }
+        // Change element of selected atoms
+        if (key === `e` && plain && selected_sites.length > 0) {
+            event.preventDefault();
+            change_element_mode = !change_element_mode;
+            return;
+        }
+        // Duplicate selected atoms at a small offset
+        if (key === `d` && (event.ctrlKey || event.metaKey) &&
+            selected_sites.length > 0 && structure?.sites) {
+            event.preventDefault();
+            is_internal_edit = true;
+            push_undo();
+            const orig_indices = scene_to_structure_indices(selected_sites);
+            const cart_to_frac = get_cart_to_frac();
+            const new_sites = structure.sites
+                .filter((_, idx) => orig_indices.has(idx))
+                .map((site) => {
+                const new_xyz = [
+                    site.xyz[0] + 0.5,
+                    site.xyz[1] + 0.5,
+                    site.xyz[2] + 0.5,
+                ];
+                return {
+                    ...site,
+                    xyz: new_xyz,
+                    abc: cart_to_frac?.(new_xyz) ?? new_xyz,
+                    properties: { ...site.properties },
+                };
+            });
+            const base_idx = structure.sites.length;
+            structure = {
+                ...structure,
+                sites: [...structure.sites, ...new_sites],
+            };
+            // Select the newly duplicated atoms
+            selected_sites = new_sites.map((_, idx) => base_idx + idx);
+            measured_sites = [...selected_sites];
+            show_toast(`Duplicated ${new_sites.length} site${new_sites.length > 1 ? `s` : ``}`);
+            return;
+        }
+        // add_atom_mode Escape is already handled above (before is_input_focused guard)
+        if (event.key === `Escape`) {
+            if (change_element_mode) {
+                change_element_mode = false;
+                return;
+            }
+            if (selected_sites.length > 0) {
+                clear_selection();
+                return;
+            }
+        }
+    }
+    // Interface shortcuts (require Ctrl/Cmd modifier to avoid accidental triggers)
+    const has_modifier = event.ctrlKey || event.metaKey;
+    if (event.key === `f` && has_modifier && fullscreen_toggle) {
+        event.preventDefault();
         toggle_fullscreen(wrapper);
-    else if (event.key === `i` && enable_info_pane)
+    }
+    else if (event.key === `i` && has_modifier && enable_info_pane) {
+        event.preventDefault();
         info_pane_open = !info_pane_open;
+    }
     else if (event.key === `Escape`) {
-        // Prioritize closing panes over exiting fullscreen
+        // Prioritize closing panes, then exit edit modes, then exit fullscreen
         if (info_pane_open)
             info_pane_open = false;
         else if (controls_open)
             controls_open = false;
         else if (export_pane_open)
             export_pane_open = false;
+        else if (measure_mode === `edit-bonds` || measure_mode === `edit-atoms`) {
+            measure_mode = `distance`;
+        }
     }
 }
+// === Edit-atoms mode helpers ===
+// Map scene indices (into displayed_structure) back to raw structure indices.
+// Handles supercell atoms via orig_unit_cell_idx property.
+// skip_image_atoms: when true, image atoms (PBC ghosts) are excluded from the result.
+function scene_to_structure_indices(scene_indices, skip_image_atoms = false) {
+    const result = new SvelteSet();
+    for (const scene_idx of scene_indices) {
+        const displayed_site = displayed_structure?.sites?.[scene_idx];
+        if (!displayed_site)
+            continue;
+        if (skip_image_atoms && displayed_site.properties?.orig_site_idx != null) {
+            continue;
+        }
+        if (has_supercell && displayed_site.properties?.orig_unit_cell_idx != null) {
+            result.add(displayed_site.properties.orig_unit_cell_idx);
+        }
+        else if (displayed_site.properties?.orig_site_idx != null) {
+            // Image atom (PBC ghost) — map back to its original site index
+            result.add(displayed_site.properties.orig_site_idx);
+        }
+        else {
+            result.add(scene_idx);
+        }
+    }
+    return result;
+}
+// Try to create a Cartesian→fractional converter for the current structure's lattice
+function get_cart_to_frac() {
+    if (!structure || !(`lattice` in structure))
+        return undefined;
+    try {
+        return create_cart_to_frac(structure.lattice.matrix);
+    }
+    catch {
+        console.warn(`Failed to compute lattice inverse for fractional coordinates`);
+        return undefined;
+    }
+}
+// Handle atom moves from TransformControls. Applies Cartesian delta and wraps
+// fractional coords inline so normalize_fractional_coords hits its fast path.
+function handle_sites_moved(scene_indices, delta) {
+    if (!structure?.sites)
+        return;
+    is_internal_edit = true;
+    const orig_indices = scene_to_structure_indices(scene_indices);
+    // For crystals, wrap to [0,1) inline so normalize_fractional_coords fast-paths.
+    // For molecules (no lattice), just apply the Cartesian delta directly.
+    const lattice = `lattice` in structure
+        ? structure.lattice.matrix
+        : null;
+    const cart_to_frac = lattice ? create_cart_to_frac(lattice) : null;
+    const frac_to_cart = lattice ? create_frac_to_cart(lattice) : null;
+    structure = {
+        ...structure,
+        sites: structure.sites.map((site, idx) => {
+            if (!orig_indices.has(idx))
+                return site;
+            const new_xyz = [
+                site.xyz[0] + delta[0],
+                site.xyz[1] + delta[1],
+                site.xyz[2] + delta[2],
+            ];
+            if (!cart_to_frac || !frac_to_cart) {
+                return { ...site, xyz: new_xyz, abc: new_xyz };
+            }
+            const wrapped_abc = wrap_to_unit_cell(cart_to_frac(new_xyz));
+            return { ...site, xyz: frac_to_cart(wrapped_abc), abc: wrapped_abc };
+        }),
+    };
+}
+// Change element symbol of selected atoms
+function handle_change_element(new_element) {
+    if (!structure?.sites || selected_sites.length === 0)
+        return;
+    const elem = normalize_element(new_element);
+    if (!elem)
+        return;
+    is_internal_edit = true;
+    push_undo();
+    const orig_indices = scene_to_structure_indices(selected_sites);
+    structure = {
+        ...structure,
+        sites: structure.sites.map((site, idx) => {
+            if (!orig_indices.has(idx))
+                return site;
+            return {
+                ...site,
+                species: [{ element: elem, occu: 1, oxidation_state: 0 }],
+                label: elem,
+            };
+        }),
+    };
+    change_element_mode = false;
+    change_element_value = ``;
+    show_toast(`Changed ${orig_indices.size} site${orig_indices.size > 1 ? `s` : ``} to ${elem}`);
+}
+// Handle add-atom from StructureScene click-to-place
+function handle_add_atom(xyz, element) {
+    if (!structure)
+        return;
+    const elem = normalize_element(element);
+    if (!elem) {
+        return console.warn(`Invalid element symbol "${element}", ignoring add-atom`);
+    }
+    is_internal_edit = true;
+    push_undo();
+    structure = {
+        ...structure,
+        sites: [...structure.sites, {
+                species: [{ element: elem, occu: 1, oxidation_state: 0 }],
+                xyz,
+                abc: get_cart_to_frac()?.(xyz) ?? xyz,
+                label: elem,
+                properties: {},
+            }],
+    };
+    show_toast(`Added ${elem} at (${xyz.map((c) => c.toFixed(2)).join(`, `)})`);
+}
 // Only set background override when background_color is explicitly provided
 $effect(() => {
     if (typeof window !== `undefined` && wrapper && background_color) {
@@ -530,10 +915,13 @@ $effect(() => {
   }}
 />
 
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 <div
   class:dragover
   class:active={info_pane_open || controls_open || export_pane_open}
-  role="region"
+  role="application"
+  tabindex="0"
+  style:--canvas-cursor={canvas_cursor}
   aria-label="Structure viewer"
   bind:this={wrapper}
   bind:clientWidth={width}
@@ -567,7 +955,7 @@ $effect(() => {
     event.preventDefault()
     dragover = false
   }}
-  {onkeydown}
+  onkeydown={handle_keydown}
   {...rest}
   class="structure {rest.class ?? ``}"
 >
@@ -579,10 +967,7 @@ $effect(() => {
       style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%)"
     />
   {:else if error_msg}
-    <div class="error-state">
-      <p class="error">{error_msg}</p>
-      <button onclick={() => (error_msg = undefined)}>Dismiss</button>
-    </div>
+    <StatusMessage bind:message={error_msg} type="error" dismissible />
   {:else if (structure?.sites?.length ?? 0) > 0}
     <section
       class="control-buttons {controls_config.class}"
@@ -620,7 +1005,7 @@ $effect(() => {
           >
             <button
               onclick={() => (measure_menu_open = !measure_menu_open)}
-              title="Measurement mode"
+              title="Measure / Edit"
               class="view-mode-button"
               class:active={measure_menu_open}
               aria-expanded={measure_menu_open}
@@ -636,6 +1021,7 @@ $effect(() => {
                     distance: `Ruler`,
                     angle: `Angle`,
                     'edit-bonds': `Link`,
+                    'edit-atoms': `Edit`,
                   } as const)[measure_mode]}
                 />
               {/if}
@@ -650,7 +1036,7 @@ $effect(() => {
                 type="button"
                 aria-label="Reset selection and bond edits"
                 onclick={() => {
-                  ;[measured_sites, selected_sites] = [[], []]
+                  clear_selection()
                   added_bonds = []
                   removed_bonds = []
                 }}
@@ -663,6 +1049,12 @@ $effect(() => {
                 {#each [
             { mode: `distance`, icon: `Ruler`, label: `Distance`, scale: 1.1 },
             { mode: `angle`, icon: `Angle`, label: `Angle`, scale: 1.3 },
+            {
+              mode: `edit-atoms`,
+              icon: `Edit`,
+              label: `Edit Atoms`,
+              scale: 1.0,
+            },
             {
               mode: `edit-bonds`,
               icon: `Link`,
@@ -685,6 +1077,84 @@ $effect(() => {
               </div>
             {/if}
           </div>
+
+          <!-- Undo/redo buttons (only in edit-atoms mode) -->
+          {#if measure_mode === `edit-atoms`}
+            <div class="undo-redo-container">
+              <button
+                type="button"
+                aria-label="Undo (Ctrl+Z)"
+                disabled={undo_stack.length === 0}
+                onclick={undo}
+                title="Undo (Ctrl+Z)"
+                class="undo-redo-btn"
+              >
+                <Icon icon="Undo" />
+                {#if undo_stack.length > 0}
+                  <span class="history-count">{undo_stack.length}</span>
+                {/if}
+              </button>
+              <button
+                type="button"
+                aria-label="Redo (Ctrl+Y)"
+                disabled={redo_stack.length === 0}
+                onclick={redo}
+                title="Redo (Ctrl+Y)"
+                class="undo-redo-btn"
+              >
+                <Icon icon="Redo" />
+                {#if redo_stack.length > 0}
+                  <span class="history-count">{redo_stack.length}</span>
+                {/if}
+              </button>
+            </div>
+          {/if}
+
+          <!-- Add-atom element input (shown when add_atom_mode is active) -->
+          {#if measure_mode === `edit-atoms` && add_atom_mode}
+            <div class="add-atom-input">
+              <label>
+                <span>Element:</span>
+                <input
+                  type="text"
+                  bind:value={add_element}
+                  maxlength="2"
+                  placeholder="C"
+                  style="width: 3em; text-align: center"
+                />
+              </label>
+              <span style="font-size: 0.75em; opacity: 0.7">Click to place</span>
+            </div>
+          {/if}
+
+          <!-- Change-element input (shown when 'e' pressed with selection) -->
+          {#if measure_mode === `edit-atoms` && change_element_mode &&
+        selected_sites.length > 0}
+            <div class="add-atom-input">
+              <label>
+                <span>New element:</span>
+                <input
+                  type="text"
+                  bind:value={change_element_value}
+                  maxlength="2"
+                  placeholder="Fe"
+                  style="width: 3em; text-align: center"
+                  onkeydown={(event: KeyboardEvent) => {
+                    if (event.key === `Enter`) {
+                      handle_change_element(change_element_value)
+                    } else if (event.key === `Escape`) {
+                      change_element_mode = false
+                    }
+                    event.stopPropagation()
+                  }}
+                  {@attach (node: HTMLInputElement) => {
+                    node.focus()
+                  }}
+                />
+              </label>
+              <span style="font-size: 0.75em; opacity: 0.7">Enter to apply</span>
+            </div>
+          {/if}
         {/if}
 
         {#if enable_info_pane && normalized_structure &&
@@ -722,6 +1192,9 @@ $effect(() => {
             bind:color_scheme
             bind:atom_color_config
             bind:cell_type
+            bind:volumetric_data
+            bind:isosurface_settings
+            bind:active_volume_idx
             {structure}
             {supercell_loading}
             {sym_data}
@@ -759,13 +1232,15 @@ $effect(() => {
     <!-- prevent from rendering in vitest runner since WebGLRenderingContext not available -->
     {#if typeof WebGLRenderingContext !== `undefined`}
       <!-- prevent HTML labels from rendering outside of the canvas -->
-      <div style="overflow: hidden; height: 100%">
+      <div style="overflow: hidden; height: 100%; flex: 1">
         <Canvas>
           <StructureScene
             structure={displayed_structure}
             base_structure={cell_transformed_structure}
             {...scene_props}
             {lattice_props}
+            volumetric_data={volumetric_data?.[active_volume_idx]}
+            {isosurface_settings}
             bind:camera_is_moving
             bind:selected_sites
             bind:measured_sites
@@ -785,6 +1260,13 @@ $effect(() => {
             {height}
             {atom_color_config}
             {sym_data}
+            on_sites_moved={handle_sites_moved}
+            on_operation_start={push_undo}
+            on_add_atom={handle_add_atom}
+            bind:add_atom_mode
+            bind:add_element
+            bind:cursor={canvas_cursor}
+            bind:dragging_atoms
           />
         </Canvas>
       </div>
@@ -794,7 +1276,11 @@ $effect(() => {
       {@render bottom_left?.({ structure: displayed_structure })}
     </div>
 
-    {#if (measure_mode as string) === `edit-bonds` &&
+    {#if toast_msg}
+      <div class="edit-toast">{toast_msg}</div>
+    {/if}
+
+    {#if measure_mode === `edit-bonds` &&
       (added_bonds.length > 0 || removed_bonds.length > 0)}
       <div class="bond-edit-status">
         {#if added_bonds.length > 0}
@@ -849,6 +1335,11 @@ $effect(() => {
     background: var(--struct-dragover-bg, var(--dragover-bg));
     border: var(--struct-dragover-border, var(--dragover-border));
   }
+  /* Ensure canvas is transparent so the themed --struct-bg shows through */
+  .structure :global(canvas) {
+    background: transparent;
+    cursor: var(--canvas-cursor, default);
+  }
   /* Avoid accidental text selection while interacting with the viewer */
   .structure :global(canvas),
   .structure section.control-buttons,
@@ -891,7 +1382,7 @@ $effect(() => {
     display: flex;
     padding: 4px;
     border-radius: var(--border-radius, 3pt);
-    font-size: clamp(0.85em, 2cqmin, 2.5em);
+    font-size: clamp(0.85em, 2cqmin, 1.3em);
   }
   section.control-buttons :global(button:hover) {
     background-color: color-mix(in srgb, currentColor 8%, transparent);
@@ -942,7 +1433,7 @@ $effect(() => {
   .measure-mode-dropdown > button {
     background: transparent;
     padding: 0 0 0 4px;
-    font-size: clamp(0.85em, 2cqmin, 2.5em);
+    font-size: clamp(0.85em, 2cqmin, 1.3em);
   }
   .selection-limit-text {
     font-weight: bold;
@@ -957,32 +1448,6 @@ $effect(() => {
     display: grid;
     place-content: center;
   }
-  .error-state {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    height: var(--struct-height, 500px);
-    padding: 2rem;
-    text-align: center;
-    box-sizing: border-box;
-  }
-  .error-state p {
-    color: var(--error-color, #ff6b6b);
-    margin: 0 0 1rem;
-  }
-  .error-state button {
-    padding: 0.5rem 1rem;
-    background: var(--error-color, #ff6b6b);
-    color: white;
-    border: none;
-    border-radius: var(--border-radius, 3pt);
-    cursor: pointer;
-    font-size: 0.9rem;
-  }
-  .error-state button:hover {
-    background: var(--error-color-hover, #ff5252);
-  }
   .symmetry-error {
     position: absolute;
     bottom: 1rem;
@@ -1013,13 +1478,37 @@ $effect(() => {
   .symmetry-error button:hover {
     opacity: 1;
   }
+  .edit-toast {
+    position: absolute;
+    bottom: 3rem;
+    left: 50%;
+    transform: translateX(-50%);
+    background: color-mix(in srgb, var(--page-bg, Canvas) 85%, currentColor);
+    color: var(--text-color, currentColor);
+    padding: 0.4rem 0.8rem;
+    border-radius: var(--border-radius, 3pt);
+    font-size: 0.8rem;
+    z-index: 100;
+    pointer-events: none;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
+    animation: toast-fade 2s ease-in-out;
+    opacity: 0;
+  }
+  @keyframes toast-fade {
+    0%, 70% {
+      opacity: 1;
+    }
+    100% {
+      opacity: 0;
+    }
+  }
   .bond-edit-status {
     position: absolute;
     bottom: 1rem;
     left: 50%;
     transform: translateX(-50%);
-    background: rgba(0, 0, 0, 0.8);
-    color: white;
+    background: color-mix(in srgb, var(--page-bg, Canvas) 85%, currentColor);
+    color: var(--text-color, currentColor);
     padding: 0.5rem 1rem;
     border-radius: var(--border-radius, 3pt);
     font-size: 0.85rem;
@@ -1027,12 +1516,15 @@ $effect(() => {
     gap: 0.75rem;
     z-index: 100;
     pointer-events: none;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
   }
   .bond-edit-status .added {
     color: #4caf50;
+    font-weight: bold;
   }
   .bond-edit-status .removed {
     color: #f44336;
+    font-weight: bold;
   }
   /* CellSelect: position at left of legend, show on hover */
   .structure :global(.cell-select) {
@@ -1045,4 +1537,55 @@ $effect(() => {
     opacity: 1;
     pointer-events: auto;
   }
+  .undo-redo-container {
+    display: flex;
+  }
+  .undo-redo-btn {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .history-count {
+    position: absolute;
+    bottom: -2px;
+    right: -2px;
+    background: var(--accent-color, #007acc);
+    color: white;
+    border-radius: 50%;
+    width: 12px;
+    height: 12px;
+    font-size: 8px;
+    font-weight: bold;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    line-height: 1;
+    pointer-events: none;
+    z-index: 1;
+  }
+  .add-atom-input {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    background: color-mix(in srgb, var(--page-bg, Canvas) 85%, currentColor);
+    color: var(--text-color, currentColor);
+    padding: 0.3em 0.6em;
+    border-radius: var(--border-radius, 3pt);
+    font-size: 0.8rem;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
+    label {
+      display: flex;
+      align-items: center;
+      gap: 0.3em;
+    }
+    input {
+      background: color-mix(in srgb, currentColor 10%, transparent);
+      border: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+      border-radius: 3px;
+      color: inherit;
+      font-size: 0.85rem;
+      padding: 0.1em 0.3em;
+    }
+  }
 </style>