matterviz 0.3.0 → 0.3.2

package/dist/structure/StructureScene.svelte

@@ -1,16 +1,20 @@
 <script lang="ts">import { AXIS_COLORS, NEG_AXIS_COLORS } from '../colors';
 import { element_data } from '../element';
+import Isosurface from '../isosurface/Isosurface.svelte';
+import { DEFAULT_ISOSURFACE_SETTINGS } from '../isosurface/types';
 import { format_num } from '../labels';
 import * as math from '../math';
 import { DEFAULTS } from '../settings';
 import { colors } from '../state.svelte';
-import { Arrow, atomic_radii, Cylinder, get_center_of_mass, Lattice, } from './';
+import { Arrow, atomic_radii, Cylinder, get_center_of_mass, get_site_vector_info, Lattice, } from './';
 import { get_orig_site_idx, get_property_colors, } from './atom-properties';
 import * as measure from './measure';
+import { compute_slice_geometry, merge_split_partial_sites, PARTIAL_OCCUPANCY_CAP_ARC, } from './partial-occupancy';
 import { T, useThrelte } from '@threlte/core';
 import * as extras from '@threlte/extras';
 import { untrack } from 'svelte';
-import { SvelteMap } from 'svelte/reactivity';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { Color } from 'three';
 import Bond from './Bond.svelte';
 import { BONDING_STRATEGIES, compute_bond_transform } from './bonding';
 import { CanvasTooltip } from './index';
@@ -32,21 +36,21 @@ $effect(() => {
     frame_id = requestAnimationFrame(animate);
     return () => cancelAnimationFrame(frame_id);
 });
-let { structure = undefined, base_structure = undefined, atom_radius = DEFAULTS.structure.atom_radius, same_size_atoms = false, camera_position = DEFAULTS.structure.camera_position, camera_projection = DEFAULTS.structure.camera_projection, rotation_damping = DEFAULTS.structure.rotation_damping, max_zoom = DEFAULTS.structure.max_zoom, min_zoom = DEFAULTS.structure.min_zoom, rotate_speed = DEFAULTS.structure.rotate_speed, zoom_speed = DEFAULTS.structure.zoom_speed, pan_speed = DEFAULTS.structure.pan_speed, zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor, show_atoms = DEFAULTS.structure.show_atoms, show_bonds = DEFAULTS.structure.show_bonds, show_site_labels = DEFAULTS.structure.show_site_labels, show_site_indices = DEFAULTS.structure.show_site_indices, site_label_size = DEFAULTS.structure.site_label_size, site_label_offset = $bindable(DEFAULTS.structure.site_label_offset), site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`, site_label_color = `#ffffff`, site_label_padding = 3, show_force_vectors = DEFAULTS.structure.show_force_vectors, force_scale = DEFAULTS.structure.force_scale, force_color = DEFAULTS.structure.force_color, gizmo = DEFAULTS.structure.show_gizmo, hovered_idx = $bindable(null), hovered_site = $bindable(null), float_fmt = `.3~f`, auto_rotate = DEFAULTS.structure.auto_rotate, bond_thickness = DEFAULTS.structure.bond_thickness, bond_color = DEFAULTS.structure.bond_color, bonding_strategy = DEFAULTS.structure.bonding_strategy, bonding_options = {}, fov = DEFAULTS.structure.fov, initial_zoom = DEFAULTS.structure.initial_zoom, ambient_light = DEFAULTS.structure.ambient_light, directional_light = DEFAULTS.structure.directional_light, sphere_segments = DEFAULTS.structure.sphere_segments, lattice_props = {}, atom_label, camera_is_moving = $bindable(false), width = 0, height = 0, measure_mode = `distance`, selected_sites = $bindable([]), measured_sites = $bindable([]), added_bonds = $bindable([]), removed_bonds = $bindable([]), selection_highlight_color = `#6cf0ff`, 
+let { structure = undefined, base_structure = undefined, atom_radius = DEFAULTS.structure.atom_radius, same_size_atoms = false, camera_position = DEFAULTS.structure.camera_position, camera_target = undefined, camera_projection = DEFAULTS.structure.camera_projection, rotation_damping = DEFAULTS.structure.rotation_damping, max_zoom = DEFAULTS.structure.max_zoom, min_zoom = DEFAULTS.structure.min_zoom, rotate_speed = DEFAULTS.structure.rotate_speed, zoom_speed = DEFAULTS.structure.zoom_speed, pan_speed = DEFAULTS.structure.pan_speed, zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor, show_atoms = DEFAULTS.structure.show_atoms, show_bonds = DEFAULTS.structure.show_bonds, show_site_labels = DEFAULTS.structure.show_site_labels, show_site_indices = DEFAULTS.structure.show_site_indices, site_label_size = DEFAULTS.structure.site_label_size, site_label_offset = $bindable(DEFAULTS.structure.site_label_offset), site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`, site_label_color = `#ffffff`, site_label_padding = 3, show_force_vectors = DEFAULTS.structure.show_force_vectors, force_scale = DEFAULTS.structure.force_scale, force_color = DEFAULTS.structure.force_color, gizmo = DEFAULTS.structure.show_gizmo, hovered_idx = $bindable(null), hovered_site = $bindable(null), float_fmt = `.3~f`, auto_rotate = DEFAULTS.structure.auto_rotate, bond_thickness = DEFAULTS.structure.bond_thickness, bond_color = DEFAULTS.structure.bond_color, bonding_strategy = DEFAULTS.structure.bonding_strategy, bonding_options = {}, fov = DEFAULTS.structure.fov, initial_zoom = DEFAULTS.structure.initial_zoom, ambient_light = DEFAULTS.structure.ambient_light, directional_light = DEFAULTS.structure.directional_light, sphere_segments = DEFAULTS.structure.sphere_segments, lattice_props = {}, atom_label, camera_is_moving = $bindable(false), width = 0, height = 0, measure_mode = `distance`, selected_sites = $bindable([]), measured_sites = $bindable([]), added_bonds = $bindable([]), removed_bonds = $bindable([]), selection_highlight_color = `#6cf0ff`, 
 // Active highlight group with different color
-active_sites = $bindable([]), active_highlight_color = `var(--struct-active-highlight-color, #2563eb)`, rotation = DEFAULTS.structure.rotation, scene = $bindable(), camera = $bindable(), orbit_controls = $bindable(), rotation_target_ref = $bindable(), initial_computed_zoom = $bindable(), hidden_elements = $bindable(new Set()), hidden_prop_vals = $bindable(new Set()), element_radius_overrides = $bindable({}), site_radius_overrides = $bindable(new SvelteMap()), atom_color_config = {
+active_sites = $bindable([]), active_highlight_color = `var(--struct-active-highlight-color, #2563eb)`, rotation = DEFAULTS.structure.rotation, scene = $bindable(), camera = $bindable(), orbit_controls = $bindable(), rotation_target_ref = $bindable(), initial_computed_zoom = $bindable(), hidden_elements = $bindable(new SvelteSet()), hidden_prop_vals = $bindable(new SvelteSet()), element_radius_overrides = $bindable({}), site_radius_overrides = $bindable(new SvelteMap()), atom_color_config = {
     mode: DEFAULTS.structure.atom_color_mode,
     scale: DEFAULTS.structure.atom_color_scale,
     scale_type: DEFAULTS.structure.atom_color_scale_type,
-}, sym_data = null, } = $props();
+}, sym_data = null, 
+// Edit-atoms mode callbacks
+on_sites_moved, on_operation_start, on_add_atom, add_atom_mode = $bindable(false), add_element = $bindable(`C`), cursor = $bindable(`default`), dragging_atoms = $bindable(false), volumetric_data = undefined, isosurface_settings = DEFAULT_ISOSURFACE_SETTINGS, } = $props();
 const threlte = useThrelte();
 $effect(() => {
     scene = threlte.scene;
     camera = threlte.camera.current;
     if (threlte.renderer) {
-        Object.assign(threlte.renderer.domElement, {
-            __renderer: threlte.renderer,
-        });
+        Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer });
     }
 });
 // Expose rotation target for external reset
@@ -63,11 +67,75 @@ $effect(() => {
 });
 let bond_pairs = $state([]);
 let active_tooltip = $state(null);
+let hovered_bond_key = $state(null);
+// Cursor style for the canvas, derived from mode and hover state
+let canvas_cursor = $derived.by(() => {
+    if (measure_mode === `edit-atoms` && add_atom_mode)
+        return `crosshair`;
+    if (hovered_idx != null) {
+        if (measure_mode === `edit-atoms`) {
+            const site = structure?.sites?.[hovered_idx];
+            if (site?.properties?.orig_site_idx != null)
+                return `not-allowed`;
+            return `pointer`;
+        }
+        return `pointer`;
+    }
+    return `default`;
+});
+// Desaturate a color by blending it toward gray (for ghosting image atoms in edit mode)
+const gray = new Color(0x999999);
+function desaturate(hex, amount = 0.4) {
+    return `#${new Color(hex ?? 0x999999).lerp(gray, amount).getHexString()}`;
+}
+// === Edit-atoms mode state ===
+let transform_object = $state(undefined);
+// Plain variable — only used imperatively in TransformControls drag handlers
+let drag_start_centroid = null;
+// Frozen centroid set on drag start. While non-null, the TransformControls mesh
+// position stays at this fixed value so Svelte's reactive centroid updates (from
+// PBC wrapping) don't fight TransformControls. Cleared on mouseUp so the mesh
+// snaps to the new wrapped centroid.
+let frozen_centroid = $state(null);
 function get_bond_key(idx1, idx2) {
     return idx1 < idx2 ? `${idx1}-${idx2}` : `${idx2}-${idx1}`;
 }
+// Toggle a bond between two atoms: cycles through add → remove → restore states
+function toggle_bond(site_1, site_2) {
+    const idx_i = Math.min(site_1, site_2);
+    const idx_j = Math.max(site_1, site_2);
+    // added/removed pairs are stored sorted, so direct comparison works
+    const match = ([a, b]) => a === idx_i && b === idx_j;
+    const added_idx = added_bonds.findIndex(match);
+    if (added_idx >= 0) {
+        added_bonds = added_bonds.toSpliced(added_idx, 1);
+        return;
+    }
+    const removed_idx = removed_bonds.findIndex(match);
+    if (removed_idx >= 0) {
+        removed_bonds = removed_bonds.toSpliced(removed_idx, 1);
+        return;
+    }
+    // bond_pairs may not be sorted, so use get_bond_key for comparison
+    const key = `${idx_i}-${idx_j}`;
+    if (bond_pairs.some((bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2) === key))
+        removed_bonds = [...removed_bonds, [idx_i, idx_j]];
+    else
+        added_bonds = [...added_bonds, [idx_i, idx_j]];
+}
+// Deduplicate clicks: when a highlight sphere and the underlying atom both
+// intercept the same native click, only the first intersection should fire.
+// All threlte intersection events from one click share the same nativeEvent ref.
+let last_native_event = null;
 function toggle_selection(site_index, evt) {
     evt?.stopPropagation?.();
+    const native_event = evt
+        ?.nativeEvent;
+    if (native_event instanceof Event) {
+        if (native_event === last_native_event)
+            return;
+        last_native_event = native_event;
+    }
     if (measure_mode === `edit-bonds`) {
         // In edit-bonds mode, select atoms to add/remove bonds between them
         const new_sites = measured_sites.includes(site_index)
@@ -77,34 +145,35 @@ function toggle_selection(site_index, evt) {
         selected_sites = new_sites;
         // When two atoms are selected, toggle the bond between them
         if (measured_sites.length === 2) {
-            const [idx_i, idx_j] = measured_sites.sort((a, b) => a - b);
-            const key = get_bond_key(idx_i, idx_j);
-            // Check if bond exists in calculated bonds (and not removed)
-            const calculated_exists = bond_pairs.some((bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2) === key);
-            const is_removed = removed_bonds.some((pair) => get_bond_key(pair[0], pair[1]) === key);
-            const is_added = added_bonds.some((pair) => get_bond_key(pair[0], pair[1]) === key);
-            if (is_added) {
-                // Toggle off added bond
-                added_bonds = added_bonds.filter((pair) => get_bond_key(pair[0], pair[1]) !== key);
-            }
-            else if (calculated_exists && !is_removed) {
-                // Remove calculated bond
-                removed_bonds = [...removed_bonds, [idx_i, idx_j]];
-            }
-            else if (is_removed) {
-                // Restore calculated bond
-                removed_bonds = removed_bonds.filter((pair) => get_bond_key(pair[0], pair[1]) !== key);
-            }
-            else {
-                // Add new bond
-                added_bonds = [...added_bonds, [idx_i, idx_j]];
-            }
-            // Reset selection after toggling bond
+            toggle_bond(measured_sites[0], measured_sites[1]);
             measured_sites = [];
             selected_sites = [];
         }
         return;
     }
+    if (measure_mode === `edit-atoms`) {
+        // Block image atoms (detected by orig_site_idx property from PBC)
+        const site = structure?.sites?.[site_index];
+        if (site?.properties?.orig_site_idx != null)
+            return;
+        const is_selected = selected_sites.includes(site_index);
+        const is_shift = evt instanceof MouseEvent && evt.shiftKey;
+        // In edit-atoms mode, selected_sites and measured_sites always stay in sync
+        let new_sites;
+        if (is_shift) {
+            // Multi-select: toggle this site in/out of selection
+            new_sites = is_selected
+                ? selected_sites.filter((idx) => idx !== site_index)
+                : [...selected_sites, site_index];
+        }
+        else {
+            // Single-select: replace selection (or deselect if already selected)
+            new_sites = is_selected ? [] : [site_index];
+        }
+        selected_sites = new_sites;
+        measured_sites = new_sites;
+        return;
+    }
     if (!measured_sites.includes(site_index) &&
         measured_sites.length >= measure.MAX_SELECTED_SITES) {
         console.warn(`Selection size limit reached (${measure.MAX_SELECTED_SITES}). Deselect some sites first.`);
@@ -127,6 +196,9 @@ $effect(() => {
         measured_sites = measured_sites.filter((idx) => idx >= 0 && idx < count);
     });
 });
+$effect(() => {
+    cursor = canvas_cursor;
+});
 extras.interactivity();
 $effect.pre(() => {
     hovered_site = structure?.sites?.[hovered_idx ?? -1] ?? null;
@@ -159,7 +231,7 @@ $effect(() => {
     computed_zoom = new_zoom;
 });
 $effect.pre(() => {
-    if (camera_position.every((v) => v === 0) && structure) {
+    if (camera_position.every((val) => val === 0) && structure) {
         const distance = Math.max(1, structure_size) * (60 / fov);
         camera_position = [distance, distance * 0.3, distance * 0.8];
     }
@@ -195,7 +267,8 @@ const calc_weighted_radius = (site) => {
 let atom_data = $derived.by(() => {
     if (!show_atoms || !structure?.sites)
         return [];
-    return structure.sites.flatMap((site, site_idx) => {
+    const render_sites = merge_split_partial_sites(structure.sites, hidden_elements);
+    return render_sites.flatMap(({ site_idx, site, is_image_atom }) => {
         const orig_idx = get_orig_site_idx(site, site_idx);
         // Skip sites with hidden property values
         const prop_val = property_colors?.values[orig_idx];
@@ -210,20 +283,25 @@ let atom_data = $derived.by(() => {
         // Use property color if available (e.g. coordination number, Wyckoff position)
         // Otherwise, each species gets its own element color (important for disordered sites)
         const site_property_color = property_colors?.colors[orig_idx];
-        let start_angle = 0;
-        return site.species
-            .filter(({ element }) => !hidden_elements.has(element))
-            .map(({ element, occu }) => ({
-            site_idx,
-            element,
-            occupancy: occu,
-            position: site.xyz,
-            radius,
-            color: site_property_color ?? colors.element?.[element],
-            has_partial_occupancy: occu < 1,
-            start_phi: 2 * Math.PI * start_angle,
-            end_phi: 2 * Math.PI * (start_angle += occu),
-        }));
+        const visible_species = site.species.filter(({ element }) => !hidden_elements.has(element));
+        const slice_geometry = compute_slice_geometry(visible_species);
+        return slice_geometry.map((slice_data) => {
+            return {
+                site_idx,
+                element: slice_data.element,
+                occupancy: slice_data.occupancy,
+                position: site.xyz,
+                radius,
+                color: site_property_color ?? colors.element?.[slice_data.element],
+                has_partial_occupancy: slice_data.occupancy < 1,
+                start_phi: slice_data.start_phi,
+                end_phi: slice_data.end_phi,
+                phi_length: slice_data.phi_length,
+                render_start_cap: slice_data.render_start_cap,
+                render_end_cap: slice_data.render_end_cap,
+                is_image_atom,
+            };
+        });
     });
 });
 let filtered_bond_pairs = $derived.by(() => {
@@ -313,28 +391,55 @@ const get_site_radius = (site, site_idx) => {
     const base_radius = same_size_atoms ? 1 : override ?? calc_weighted_radius(site);
     return base_radius * atom_radius;
 };
-let force_data = $derived.by(() => show_force_vectors && structure?.sites
-    ? structure?.sites
+// Interpolate between spin-down (#3498db blue) and spin-up (#e74c3c red)
+// based on the z-component direction of a magnetic vector
+function spin_direction_color(vec) {
+    const mag = Math.hypot(...vec);
+    const z_frac = mag > 1e-10 ? (vec[2] / mag + 1) / 2 : 0.5; // 0=down, 1=up
+    const red = Math.round(52 + (231 - 52) * z_frac);
+    const grn = Math.round(152 + (76 - 152) * z_frac);
+    const blu = Math.round(219 + (60 - 219) * z_frac);
+    return `#${red.toString(16).padStart(2, `0`)}${grn.toString(16).padStart(2, `0`)}${blu.toString(16).padStart(2, `0`)}`;
+}
+// Extract per-site vectors from force, magmom, or spin properties.
+// For magmom/spin, color interpolates between spin-up (red) and spin-down (blue).
+let force_data = $derived.by(() => {
+    if (!show_force_vectors || !structure?.sites)
+        return [];
+    return structure.sites
         .map((site) => {
-        if (!site.properties?.force || !Array.isArray(site.properties.force))
+        const info = get_site_vector_info(site);
+        if (!info)
             return null;
-        const majority_element = site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max).element;
+        let arrow_color;
+        if (info.key !== `force`) {
+            arrow_color = spin_direction_color(info.vec);
+        }
+        else {
+            const majority_element = site.species.length > 0
+                ? site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max)
+                    .element
+                : undefined;
+            arrow_color = (majority_element && colors.element?.[majority_element]) ||
+                force_color;
+        }
         return {
             position: site.xyz,
-            vector: site.properties.force,
+            vector: info.vec,
             scale: force_scale,
-            color: colors.element?.[majority_element] || force_color,
+            color: arrow_color,
         };
     })
-        .filter((item) => item !== null)
-    : []);
+        .filter((item) => item !== null);
+});
 let instanced_atom_groups = $derived(Object.values(atom_data
     .filter((atom) => !atom.has_partial_occupancy)
     .reduce((groups, atom) => {
-    const { element, radius, color } = atom;
-    const key = `${element}-${format_num(radius, `.3~`)}-${color}`;
+    const { element, radius, color, is_image_atom } = atom;
+    // Separate image atoms into their own groups for distinct styling in edit-atoms mode
+    const key = `${element}-${format_num(radius, `.3~`)}-${color}-${is_image_atom ? `img` : `base`}`;
     const bucket = groups[key] ||
-        (groups[key] = { element, radius, color, atoms: [] });
+        (groups[key] = { element, radius, color, is_image_atom, atoms: [] });
     bucket.atoms.push(atom);
     return groups;
 }, {})));
@@ -375,7 +480,7 @@ let orbit_controls_props = $derived({
     zoomToCursor: zoom_to_cursor,
     enablePan: pan_speed > 0,
     panSpeed: pan_speed,
-    target: rotation_target,
+    target: camera_target ?? rotation_target,
     maxZoom: max_zoom,
     minZoom: min_zoom,
     autoRotate: Boolean(auto_rotate),
@@ -421,27 +526,17 @@ let measure_line_color = $derived.by(() => {
         style:padding="{site_label_padding}px"
         style:color={site_label_color}
       >
-        {#if show_site_labels && show_site_indices}
-          {#if site.species.length === 1}
-            {site.species[0].element}-{site_idx + 1}
-          {:else}
-            {@html site.species.map((spec) =>
-        `${spec.element}<sub>${
-          format_num(spec.occu, `.3~`).replace(`0.`, `.`)
-        }</sub>`
-      ).join(``)}-{
-              site_idx + 1
-            }
-          {/if}
-        {:else if show_site_labels}
+        {#if show_site_labels}
           {#if site.species.length === 1}
-            {site.species[0].element}
+            {site.species[0].element}{#if show_site_indices}-{site_idx + 1}{/if}
           {:else}
             {@html site.species.map((spec) =>
         `${spec.element}<sub>${
           format_num(spec.occu, `.3~`).replace(`0.`, `.`)
         }</sub>`
-      ).join(``)}
+      ).join(``)}{#if show_site_indices}-{
+                site_idx + 1
+              }{/if}
           {/if}
         {:else if show_site_indices}
           {site_idx + 1}
@@ -487,31 +582,38 @@ let measure_line_color = $derived.by(() => {
       {#if show_atoms}
         <!-- Instanced rendering for full occupancy atoms -->
         {#each instanced_atom_groups as
-          { element, radius, color, atoms }
-          (`${element}-${radius}-${color}`)
+          { element, radius, color, is_image_atom, atoms }
+          (`${element}-${radius}-${color}-${is_image_atom ? `img` : `base`}`)
         }
+          {@const edit_mode_image = measure_mode === `edit-atoms` && is_image_atom}
           <extras.InstancedMesh
-            key="{element}-{format_num(radius, `.3~`)}-{color}-{atoms.length}"
+            key="{element}-{format_num(radius, `.3~`)}-{color}-{is_image_atom ? `img` : `base`}-{edit_mode_image}"
             range={atoms.length}
             frustumCulled={false}
           >
             <T.SphereGeometry args={[0.5, sphere_segments, sphere_segments]} />
-            <T.MeshStandardMaterial {color} />
+            <T.MeshStandardMaterial
+              color={edit_mode_image ? desaturate(color) : color}
+              opacity={edit_mode_image ? 0.5 : 1}
+              transparent={edit_mode_image}
+            />
             {#each atoms as atom (atom.site_idx)}
               <extras.Instance
                 position={atom.position}
                 scale={atom.radius}
                 onpointerenter={() => {
+                  if (edit_mode_image) return
                   hovered_idx = atom.site_idx
                   active_tooltip = `atom`
                 }}
                 onpointerleave={() => {
+                  if (edit_mode_image) return
                   hovered_idx = null
                   active_tooltip = null
                 }}
                 onclick={(event: MouseEvent) => {
-                  const site_idx = atom.site_idx
-                  toggle_selection(site_idx, event)
+                  if (edit_mode_image) return
+                  toggle_selection(atom.site_idx, event)
                 }}
               />
             {/each}
@@ -523,22 +625,29 @@ let measure_line_color = $derived.by(() => {
           atom
           (atom.site_idx + atom.element + atom.occupancy)
         }
+          {@const partial_edit_image = measure_mode === `edit-atoms` && atom.is_image_atom}
+          {@const ghost_opacity = partial_edit_image ? 0.5 : 1}
           <T.Group
             position={atom.position}
             scale={atom.radius}
             onpointerenter={() => {
+              if (partial_edit_image) return
               hovered_idx = atom.site_idx
               active_tooltip = `atom`
             }}
             onpointerleave={() => {
+              if (partial_edit_image) return
               hovered_idx = null
               active_tooltip = null
             }}
             onclick={(event: MouseEvent) => {
-              const site_idx = atom.site_idx
-              toggle_selection(site_idx, event)
+              if (partial_edit_image) return
+              toggle_selection(atom.site_idx, event)
             }}
           >
+            {@const partial_color = partial_edit_image
+            ? desaturate(atom.color)
+            : atom.color}
             <T.Mesh>
               <T.SphereGeometry
                 args={[
@@ -546,20 +655,50 @@ let measure_line_color = $derived.by(() => {
                   sphere_segments,
                   sphere_segments,
                   atom.start_phi,
-                  2 * Math.PI * atom.occupancy,
+                  atom.phi_length,
                 ]}
               />
-              <T.MeshStandardMaterial color={atom.color} />
+              <T.MeshStandardMaterial
+                color={partial_color}
+                opacity={ghost_opacity}
+                transparent={partial_edit_image}
+              />
             </T.Mesh>
 
-            {#if atom.has_partial_occupancy}
+            {#if atom.has_partial_occupancy && atom.render_start_cap}
               <T.Mesh rotation={[0, atom.start_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
-                <T.MeshStandardMaterial color={atom.color} side={2} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.start_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
+                <T.MeshStandardMaterial
+                  color={partial_color}
+                  side={2}
+                  opacity={ghost_opacity}
+                  transparent={partial_edit_image}
+                />
               </T.Mesh>
+            {/if}
+            {#if atom.has_partial_occupancy && atom.render_end_cap}
               <T.Mesh rotation={[0, atom.end_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
-                <T.MeshStandardMaterial color={atom.color} side={2} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.end_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
+                <T.MeshStandardMaterial
+                  color={partial_color}
+                  side={2}
+                  opacity={ghost_opacity}
+                  transparent={partial_edit_image}
+                />
               </T.Mesh>
             {/if}
           </T.Group>
@@ -592,6 +731,41 @@ let measure_line_color = $derived.by(() => {
         {/each}
       {/if}
 
+      <!-- Clickable bond hit-test cylinders in edit-bonds mode -->
+      {#if measure_mode === `edit-bonds` && filtered_bond_pairs.length > 0}
+        {#each filtered_bond_pairs as
+          bond
+          (`bond-hit-${bond.site_idx_1}-${bond.site_idx_2}`)
+        }
+          {@const bond_key = get_bond_key(bond.site_idx_1, bond.site_idx_2)}
+          {@const is_hovered = hovered_bond_key === bond_key}
+          <T.Mesh
+            matrixAutoUpdate={false}
+            oncreate={(ref) => {
+              ref.matrix.fromArray(bond.transform_matrix)
+              ref.matrixWorldNeedsUpdate = true
+            }}
+            onclick={(event: MouseEvent) => {
+              event.stopPropagation()
+              toggle_bond(bond.site_idx_1, bond.site_idx_2)
+              measured_sites = []
+              selected_sites = []
+              hovered_bond_key = null
+            }}
+            onpointerenter={() => (hovered_bond_key = bond_key)}
+            onpointerleave={() => (hovered_bond_key = null)}
+          >
+            <T.CylinderGeometry args={[bond_thickness * 3, bond_thickness * 3, 1, 6]} />
+            <T.MeshBasicMaterial
+              transparent
+              opacity={is_hovered ? 0.25 : 0}
+              color={is_hovered ? `#ff4444` : `white`}
+              depthWrite={false}
+            />
+          </T.Mesh>
+        {/each}
+      {/if}
+
       <!-- highlight hovered, active and selected sites -->
       {#each [
           {
@@ -648,8 +822,9 @@ let measure_line_color = $derived.by(() => {
         {/if}
       {/each}
 
-      <!-- selection order labels (1, 2, 3, ...) for measured sites -->
-      {#if structure?.sites && (measured_sites?.length ?? 0) > 0}
+      <!-- selection order labels (1, 2, 3, ...) for measured sites (hidden in edit-atoms mode) -->
+      {#if structure?.sites && (measured_sites?.length ?? 0) > 0 &&
+          measure_mode !== `edit-atoms`}
         {#each measured_sites as site_index, loop_idx (site_index)}
           {@const site = structure.sites[site_index]}
           {#if site}
@@ -665,8 +840,36 @@ let measure_line_color = $derived.by(() => {
 
       <!-- hovered site tooltip -->
       {#if hovered_site && !camera_is_moving && active_tooltip === `atom`}
-        {@const abc = hovered_site.abc.map((x) => format_num(x, float_fmt)).join(`, `)}
-        {@const xyz = hovered_site.xyz.map((x) => format_num(x, float_fmt)).join(`, `)}
+        {@const abc = hovered_site.abc.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
+        {@const xyz = hovered_site.xyz.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
+        {@const bond_neighbors = (() => {
+          if (hovered_idx == null || !structure?.sites) return []
+          return filtered_bond_pairs
+            .filter((b) =>
+              b.site_idx_1 === hovered_idx || b.site_idx_2 === hovered_idx
+            )
+            .map((b) => {
+              const neighbor_idx = b.site_idx_1 === hovered_idx
+                ? b.site_idx_2
+                : b.site_idx_1
+              return structure.sites[neighbor_idx]?.species[0]?.element ?? `?`
+            })
+        })()}
+        {@const bond_summary = (() => {
+          if (bond_neighbors.length === 0) return ``
+          const counts: Record<string, number> = {}
+          for (const elem of bond_neighbors) {
+            counts[elem] = (counts[elem] ?? 0) + 1
+          }
+          const parts = Object.entries(counts)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([elem, count]) => `${elem}: ${count}`)
+          return ` (${parts.join(`, `)})`
+        })()}
         <CanvasTooltip position={hovered_site.xyz}>
           <!-- Element symbols with occupancies for disordered sites -->
           <div class="elements">
@@ -694,6 +897,9 @@ let measure_line_color = $derived.by(() => {
           </div>
           <div class="coordinates fractional">abc: ({abc})</div>
           <div class="coordinates cartesian">xyz: ({xyz}) Å</div>
+          {#if bond_neighbors.length > 0}
+            <div class="coordinates">Bonds: {bond_neighbors.length}{bond_summary}</div>
+          {/if}
         </CanvasTooltip>
       {/if}
 
@@ -701,6 +907,91 @@ let measure_line_color = $derived.by(() => {
         <Lattice matrix={visual_lattice.matrix} {...lattice_props} />
       {/if}
 
+      <!-- TransformControls for editing atoms in edit-atoms mode -->
+      {#if measure_mode === `edit-atoms` && selected_sites.length > 0 &&
+          structure?.sites}
+        {@const selected_atoms = selected_sites
+          .map((idx) => structure?.sites?.[idx])
+          .filter((site): site is Site => site != null)}
+        {#if selected_atoms.length > 0}
+          {@const avg = (dim: number) =>
+          selected_atoms.reduce((sum, atom) => sum + atom.xyz[dim], 0) /
+          selected_atoms.length}
+          {@const centroid = [avg(0), avg(1), avg(2)] as Vec3}
+          <!-- Invisible mesh at centroid for TransformControls to manipulate.
+               During drag, use frozen_centroid so Svelte doesn't override TransformControls
+               with the wrapped centroid (which jumps on PBC boundary crossings). -->
+          <T.Mesh
+            position={frozen_centroid ?? centroid}
+            bind:ref={transform_object}
+          >
+            <T.SphereGeometry args={[0.01, 4, 4]} />
+            <T.MeshBasicMaterial transparent opacity={0} />
+          </T.Mesh>
+          <extras.TransformControls
+            object={transform_object}
+            translationSnap={0.1}
+            size={1.2}
+            space="world"
+            onobjectChange={() => {
+              if (!transform_object?.position || !drag_start_centroid) return
+              const { x: tx, y: ty, z: tz } = transform_object.position
+              const delta: Vec3 = [
+                tx - drag_start_centroid[0],
+                ty - drag_start_centroid[1],
+                tz - drag_start_centroid[2],
+              ]
+              // Update reference point so deltas are incremental, not cumulative.
+              // Without this, each frame compounds: sites already moved by previous
+              // delta get the full cumulative delta re-applied.
+              drag_start_centroid = [tx, ty, tz]
+              on_sites_moved?.(selected_sites, delta)
+            }}
+            onmouseDown={() => {
+              dragging_atoms = true
+              drag_start_centroid = frozen_centroid = [...centroid] as Vec3
+              on_operation_start?.()
+            }}
+            onmouseUp={() => {
+              dragging_atoms = false
+              frozen_centroid = null
+              drag_start_centroid = null
+            }}
+          />
+        {/if}
+      {/if}
+
+      <!-- Invisible plane for click-to-place atom in add-atom mode -->
+      <!-- Uses onBeforeRender to orient normal toward camera so raycasts always hit -->
+      {#if measure_mode === `edit-atoms` && add_atom_mode}
+        {@const center = rotation_target ?? [0, 0, 0]}
+        <T.Mesh
+          position={center}
+          onBeforeRender={(mesh: Mesh) => {
+            if (camera) {
+              mesh.lookAt(camera.position)
+            }
+          }}
+          onclick={(event: { point: { x: number; y: number; z: number } }) => {
+            const { x, y, z } = event.point
+            on_add_atom?.([x, y, z] as Vec3, add_element as ElementSymbol)
+          }}
+        >
+          <T.PlaneGeometry
+            args={[
+              Math.max(200, structure_size * 4),
+              Math.max(200, structure_size * 4),
+            ]}
+          />
+          <T.MeshBasicMaterial transparent opacity={0} side={2} depthWrite={false} />
+        </T.Mesh>
+      {/if}
+
+      <!-- Isosurface rendering from volumetric data (CHGCAR, .cube files) -->
+      {#if volumetric_data && isosurface_settings}
+        <Isosurface volume={volumetric_data} settings={isosurface_settings} />
+      {/if}
+
       <!-- Measurement overlays for measured sites -->
       {#if structure?.sites && (measured_sites?.length ?? 0) > 0}
         {#if measure_mode === `distance`}
@@ -741,12 +1032,12 @@ let measure_line_color = $derived.by(() => {
         {:else if measure_mode === `angle` && measured_sites.length >= 3}
           {#each measured_sites as idx_center (idx_center)}
             {@const center = structure.sites[idx_center]}
-            {#each measured_sites.filter((x) => x !== idx_center) as
+            {#each measured_sites.filter((idx) => idx !== idx_center) as
               idx_a,
               loop_idx
               (idx_center + `-` + idx_a)
             }
-              {#each measured_sites.filter((x) => x !== idx_center).slice(loop_idx + 1) as
+              {#each measured_sites.filter((idx) => idx !== idx_center).slice(loop_idx + 1) as
                 idx_b
                 (idx_center + `-` + idx_a + `-` + idx_b)
               }