matterviz 0.3.7 → 0.4.1

package/dist/structure/StructureScene.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import type { D3InterpolateName } from '../colors'
-  import { AXIS_COLORS, get_d3_interpolator, NEG_AXIS_COLORS } from '../colors'
+  import { get_d3_interpolator } from '../colors'
   import type { ElementSymbol } from '../element'
   import { element_data } from '../element'
   import Isosurface from '../isosurface/Isosurface.svelte'
@@ -9,12 +9,9 @@
   import { format_num } from '../labels'
   import type { Vec3 } from '../math'
   import * as math from '../math'
-  import type {
-    CameraProjection,
-    ShowBonds,
-    VectorColorMode,
-    VectorLayerConfig,
-  } from '../settings'
+  import { bind_renderer, build_orbit_props, SceneCamera } from '../scene'
+  import type { SceneControlProps } from '../scene'
+  import type { ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings'
   import { DEFAULTS } from '../settings'
   import { create_pulse_animation } from '../effects.svelte'
   import { colors } from '../state.svelte'
@@ -42,6 +39,9 @@
     get_orig_site_idx,
     get_property_colors,
   } from './atom-properties'
+  import type { SymmetryElement } from '../symmetry'
+  import { has_visible_symmetry_overlay } from '../symmetry/symmetry-elements'
+  import SymmetryElements from '../symmetry/SymmetryElements.svelte'
   import * as measure from './measure'
   import {
     compute_slice_geometry,
@@ -49,11 +49,12 @@
     PARTIAL_OCCUPANCY_CAP_ARC,
   } from './partial-occupancy'
   import type { MoyoDataset } from '@spglib/moyo-wasm'
-  import { T, useThrelte } from '@threlte/core'
+  import { T } from '@threlte/core'
   import * as extras from '@threlte/extras'
   import { type ComponentProps, type Snippet, untrack } from 'svelte'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
-  import { type Camera, Color, type Mesh, type Object3D, type Scene, Vector3 } from 'three'
+  import { BufferAttribute, BufferGeometry, Color, DoubleSide, Vector3 } from 'three'
+  import type { Mesh, Object3D } from 'three'
   import Bond from './Bond.svelte'
   import type { BondEditResult, BondingStrategy, BondKeyTarget } from './bonding'
   import {
@@ -65,6 +66,7 @@
     get_bond_key,
     get_bond_render_matrices,
     get_explicit_bond_metadata,
+    get_majority_element,
     set_bond_order as apply_set_bond_order,
     structure_bond_to_bond_pair,
   } from './bonding'
@@ -77,7 +79,9 @@
     choose_site_label_offset,
     LABEL_OFFSET_EPS,
     make_label_position_calculator,
-  } from './label-placement'
+  } from './atom-label-placement'
+  import type { PolyhedraColorMode, Polyhedron } from './polyhedra'
+  import { compute_polyhedra, merge_polyhedra_buffers } from './polyhedra'
 
   type InstancedAtomGroup = {
     element: string
@@ -168,12 +172,27 @@
     auto_bond_order = DEFAULTS.structure.auto_bond_order,
     aromatic_display = DEFAULTS.structure.aromatic_display,
     bonding_options = {},
+    show_polyhedra = DEFAULTS.structure.show_polyhedra,
+    polyhedra_opacity = DEFAULTS.structure.polyhedra_opacity,
+    polyhedra_show_edges = DEFAULTS.structure.polyhedra_show_edges,
+    polyhedra_edge_color = DEFAULTS.structure.polyhedra_edge_color,
+    polyhedra_color_mode = DEFAULTS.structure.polyhedra_color_mode,
+    polyhedra_color = DEFAULTS.structure.polyhedra_color,
+    polyhedra_hide_center_atoms = DEFAULTS.structure.polyhedra_hide_center_atoms,
+    polyhedra_min_neighbors = DEFAULTS.structure.polyhedra_min_neighbors,
+    polyhedra_max_neighbors = DEFAULTS.structure.polyhedra_max_neighbors,
+    polyhedra_excluded_elements = DEFAULTS.structure.polyhedra_excluded_elements,
+    polyhedra_included_elements = DEFAULTS.structure.polyhedra_included_elements,
+    polyhedra_rendered_elements = $bindable<string[]>([]),
     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 = {},
+    symmetry_elements = [],
+    symmetry_elements_props = {},
+    symmetry_declutter = true,
     atom_label,
     camera_is_moving = $bindable(false),
     width = 0,
@@ -218,7 +237,7 @@
     dragging_atoms = $bindable(false),
     volumetric_data = undefined,
     isosurface_settings = DEFAULT_ISOSURFACE_SETTINGS,
-  }: {
+  }: SceneControlProps & {
     structure?: AnyStructure
     base_structure?: AnyStructure // The original structure without image atoms, used for property color calculation
     atom_radius?: number // scale factor for atomic radii
@@ -226,15 +245,6 @@
     // determined by the atomic radius of the element
     camera_position?: [x: number, y: number, z: number] // initial camera position from which to render the scene
     camera_target?: Vec3 // external orbit-controls target for pan synchronization
-    camera_projection?: CameraProjection // camera projection type
-    rotation_damping?: number // rotation damping factor (how quickly the rotation comes to rest after mouse release)
-    // zoom level of the camera
-    max_zoom?: number
-    min_zoom?: number
-    rotate_speed?: number // rotation speed. set to 0 to disable rotation.
-    zoom_speed?: number // zoom speed. set to 0 to disable zooming.
-    pan_speed?: number // pan speed. set to 0 to disable panning.
-    zoom_to_cursor?: boolean // zoom toward cursor position instead of scene center
     show_atoms?: boolean
     show_bonds?: ShowBonds
     show_site_labels?: boolean
@@ -250,30 +260,46 @@
     vector_shaft_radius?: number
     vector_arrow_head_radius?: number
     vector_arrow_head_length?: number
-    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>
     hovered_idx?: number | null
     hovered_site?: Site | null
     float_fmt?: string
-    auto_rotate?: number
-    initial_zoom?: number
     bond_thickness?: number
     bond_color?: string
     bonding_strategy?: BondingStrategy
     auto_bond_order?: boolean
     aromatic_display?: `aromatic` | `kekule`
     bonding_options?: Record<string, unknown>
-    fov?: number
-    ambient_light?: number
-    directional_light?: number
+    show_polyhedra?: ShowBonds // when to render coordination polyhedra
+    polyhedra_opacity?: number
+    polyhedra_show_edges?: boolean
+    polyhedra_edge_color?: string
+    polyhedra_color_mode?: PolyhedraColorMode
+    polyhedra_color?: string // custom color used when polyhedra_color_mode is 'uniform'
+    polyhedra_hide_center_atoms?: boolean
+    polyhedra_min_neighbors?: number // min coordination number to form a polyhedron
+    polyhedra_max_neighbors?: number // max CN - skips e.g. CN-12 cuboctahedra
+    polyhedra_excluded_elements?: readonly string[] // elements never used as polyhedra centers
+    polyhedra_included_elements?: readonly string[] // force-include (bypasses spectator hiding)
+    polyhedra_rendered_elements?: string[] // (output) elements that currently have polyhedra
     sphere_segments?: number
     lattice_props?: ComponentProps<typeof Lattice>
+    // Symmetry elements (from symmetry_elements_from_ops) to overlay on the structure.
+    // Fractional coords must refer to the SAME cell as the rendered lattice (moyo
+    // operations are in the input-cell frame, i.e. the original untransformed cell).
+    symmetry_elements?: SymmetryElement[]
+    symmetry_elements_props?: Omit<ComponentProps<typeof SymmetryElements>, `elements` | `lattice`>
+    // Auto-reduce visual clutter while a symmetry-element overlay is visible: hides
+    // coordination polyhedra and calculated bonds, and shrinks atoms so axes/planes/
+    // centers stay readable. Purely derived — toggling the overlay off restores the
+    // configured appearance.
+    symmetry_declutter?: boolean
     atom_label?: Snippet<[{ site: Site; site_idx: number }]>
     site_label_size?: number
     site_label_offset?: Vec3
     site_label_bg_color?: string
     site_label_color?: string
     site_label_padding?: number
-    camera_is_moving?: boolean // used to prevent tooltip from showing while camera is moving
+    camera_is_moving?: boolean // bindable: true while orbit controls are active
     width?: number // Viewer dimensions for responsive zoom
     height?: number
     // measurement props
@@ -291,9 +317,6 @@
     active_sites?: number[]
     active_highlight_color?: string
     rotation?: Vec3 // rotation control prop
-    // Expose scene and camera for external use (e.g. export pane)
-    scene?: Scene
-    camera?: Camera
     orbit_controls?: ComponentProps<typeof extras.OrbitControls>[`ref`] // OrbitControls instance
     rotation_target_ref?: Vec3 // Expose rotation target for reset
     initial_computed_zoom?: number // Expose initial zoom for reset
@@ -322,13 +345,9 @@
   )
   let pulse_opacity = $derived(0.15 + 0.25 * pulse.unit)
 
-  const threlte = useThrelte()
-  $effect(() => {
-    scene = threlte.scene
-    camera = threlte.camera.current
-    if (threlte.renderer) {
-      Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer })
-    }
+  bind_renderer((threlte_scene, threlte_camera) => {
+    scene = threlte_scene
+    camera = threlte_camera
   })
 
   // Expose rotation target for external reset
@@ -409,9 +428,8 @@
 
   // Desaturate a color by blending it toward gray (for ghosting image atoms in edit mode)
   const gray = new Color(0x999999)
-  function desaturate(hex: string | undefined, amount = 0.4): string {
-    return `#${new Color(hex ?? 0x999999).lerp(gray, amount).getHexString()}`
-  }
+  const desaturate = (hex: string | undefined, amount = 0.4): string =>
+    `#${new Color(hex ?? 0x999999).lerp(gray, amount).getHexString()}`
 
   // === Edit-atoms mode state ===
   let transform_object = $state<Mesh | undefined>(undefined)
@@ -738,6 +756,27 @@
     return true
   }
 
+  // Pointer props (hover + select) shared by instanced atoms and partial-occupancy
+  // hit targets. is_edit_image disables interaction for ghosted PBC image atoms.
+  const atom_pointer_props = (site_idx: number, is_edit_image: boolean) => ({
+    ...atom_hover_props(site_idx, is_edit_image),
+    onpointerdown(event: PointerEvent) {
+      if (is_edit_image || measure_mode !== `edit-bonds` || bond_edit_mode !== `add`) return
+      select_edit_bonds_site(site_idx, event)
+    },
+    onclick(event: MouseEvent) {
+      if (is_edit_image) return
+      if (measure_mode === `edit-bonds`) {
+        if (bond_edit_mode !== `add`) return
+        if (skip_duplicate_edit_bonds_click(site_idx)) {
+          event.stopPropagation()
+          return
+        }
+      }
+      toggle_selection(site_idx, event)
+    },
+  })
+
   function toggle_selection(site_index: number, evt?: Event) {
     evt?.stopPropagation?.()
     const event_with_native = evt as Event & { nativeEvent?: unknown } | undefined
@@ -853,7 +892,7 @@
 
   let rotation_target = $derived(
     lattice
-      ? (math.scale(math.add(...lattice.matrix), 0.5) as Vec3)
+      ? math.scale(math.add(...lattice.matrix), 0.5)
       : structure
       ? get_center_of_mass(structure)
       : [0, 0, 0] as Vec3,
@@ -924,16 +963,43 @@
       camera_position = [distance, distance * 0.3, distance * 0.8]
     }
   })
+  // Whether a never|always|crystals|molecules setting applies to the current structure
+  const applies_to_structure = (when: ShowBonds): boolean =>
+    when === `always` ||
+    (when === `crystals` && Boolean(lattice)) ||
+    (when === `molecules` && !lattice)
+
+  // Declutter while a symmetry-element overlay actually draws something (elements present
+  // AND an enabled kind among them): hide coordination polyhedra/bonds and shrink atoms so
+  // axes/planes/centers stay readable. Gating on visibility (not just `symmetry_elements`)
+  // avoids hiding everything when nothing renders in its place — e.g. an inversion-only
+  // cell under the rotation-only default. Pure derived overrides: the configured
+  // appearance returns untouched the moment the overlay goes away.
+  const declutter_active = $derived(
+    symmetry_declutter &&
+      has_visible_symmetry_overlay(symmetry_elements, symmetry_elements_props.show_kinds),
+  )
+  const effective_show_polyhedra: ShowBonds = $derived(
+    declutter_active ? `never` : show_polyhedra,
+  )
+  // Calculated bonds are hidden in declutter mode (only their cylinders — bond_pairs
+  // stay computed so tooltips and manually added bonds keep working)
+  const effective_show_bonds: ShowBonds = $derived(
+    declutter_active ? `never` : show_bonds,
+  )
+  const effective_atom_radius = $derived(declutter_active ? atom_radius * 0.6 : atom_radius)
+
   $effect(() => {
-    if (structure && show_bonds !== `never`) {
-      // Determine if we should show bonds based on the setting and structure type
-      const should_show_bonds = show_bonds === `always` ||
-        (show_bonds === `crystals` && lattice) ||
-        (show_bonds === `molecules` && !lattice)
-
-      if (should_show_bonds) {
-        bond_pairs = BONDING_STRATEGIES[bonding_strategy](structure, bonding_options)
-      } else bond_pairs = []
+    // Bonds are computed when either bond rendering or polyhedra need them. The
+    // raw/effective mix is deliberate: RAW show_bonds keeps bond_pairs available
+    // during symmetry declutter (cylinders hide via effective_show_bonds in
+    // bonds_to_render, but tooltips + manually added bonds still need the data),
+    // while EFFECTIVE show_polyhedra skips computing bonds whose only consumer —
+    // the polyhedra $derived below, gated on the same effective value — won't run.
+    const want_bonds = applies_to_structure(show_bonds)
+    const want_polyhedra = applies_to_structure(effective_show_polyhedra)
+    if (structure && (want_bonds || want_polyhedra)) {
+      bond_pairs = BONDING_STRATEGIES[bonding_strategy](structure, bonding_options)
     } else bond_pairs = []
   })
 
@@ -958,9 +1024,16 @@
     return total_occu > 0 ? weighted_sum / total_occu : 1
   }
 
+  // Disordered sites are often stored as separate split sites (one species each)
+  // at the same position; merge_split_partial_sites groups them into one render
+  // site whose `species` holds every element. Shared by atom rendering and the
+  // hover tooltip so it lists all elements, not just the majority one.
+  let render_sites = $derived(
+    structure?.sites ? merge_split_partial_sites(structure.sites, hidden_elements) : [],
+  )
+
   let atom_data = $derived.by(() => {
-    if (!show_atoms || !structure?.sites) return []
-    const render_sites = merge_split_partial_sites(structure.sites, hidden_elements)
+    if (!show_atoms) return []
     return render_sites.flatMap(({ site_idx, site, is_image_atom }) => {
       const orig_idx = get_orig_site_idx(site, site_idx)
 
@@ -968,12 +1041,26 @@
       const prop_val = property_colors?.values[orig_idx]
       if (prop_val !== undefined && hidden_prop_vals.has(prop_val)) return []
 
+      // Optionally hide atoms at the center of a rendered polyhedron
+      if (polyhedra_hide_center_atoms && polyhedra_center_site_idxs.has(site_idx)) {
+        return []
+      }
+
+      // Phase-2 PBC images exist only to complete bonds/coordination polyhedra at
+      // cell faces. When neither renders (polyhedra toggled off, symmetry declutter,
+      // …) they'd float disconnected outside the cell — hide them.
+      if (
+        site.properties?.completion_image &&
+        !applies_to_structure(effective_show_bonds) &&
+        !applies_to_structure(effective_show_polyhedra)
+      ) return []
+
       // Calculate radius: same_size > site override > element override > default
       // All radii scale uniformly with atom_radius for consistent slider behavior
       const base_radius = same_size_atoms
         ? 1
         : site_radius_overrides?.get(site_idx) ?? calc_weighted_radius(site)
-      const radius = base_radius * atom_radius
+      const radius = base_radius * effective_atom_radius
 
       // Use property color if available (e.g. coordination number, Wyckoff position)
       // Otherwise, each species gets its own element color (important for disordered sites)
@@ -1080,17 +1167,110 @@
     return [...calculated, ...added]
   })
 
+  // Bonds drawn as cylinders. When show_bonds doesn't apply, calculated bonds are
+  // hidden but manually added bonds stay visible (bond_pairs may still be computed
+  // for polyhedra, so this can't rely on bond_pairs being empty).
+  let bonds_to_render = $derived.by(() => {
+    if (applies_to_structure(effective_show_bonds)) return filtered_bond_pairs
+    const added_keys = new Set(added_bonds.map(bond_key_for))
+    return filtered_bond_pairs.filter((bond) => added_keys.has(bond_key_for(bond)))
+  })
+
   let editable_bond_pairs = $derived(
-    bond_edits_enabled ? filtered_bond_pairs.filter(can_edit_bond) : [],
+    bond_edits_enabled ? bonds_to_render.filter(can_edit_bond) : [],
+  )
+
+  // Coordination polyhedra around cation-like centers, derived from the same
+  // (edited, filtered) bond graph as rendered bonds so the two never disagree.
+  // Colors are resolved in polyhedra_buffers below, so color-scheme/mode changes
+  // never recompute the hull geometry.
+  let polyhedra: Polyhedron[] = $derived.by(() => {
+    if (
+      !structure?.sites || dragging_atoms ||
+      !applies_to_structure(effective_show_polyhedra) ||
+      filtered_bond_pairs.length === 0
+    ) return []
+    return compute_polyhedra(structure, filtered_bond_pairs, {
+      min_neighbors: polyhedra_min_neighbors,
+      max_neighbors: polyhedra_max_neighbors,
+      excluded_center_elements: polyhedra_excluded_elements,
+      included_center_elements: polyhedra_included_elements,
+    })
+  })
+
+  // Color of a site: property color (coordination/Wyckoff modes) or element color
+  const polyhedra_site_color = (site_idx: number): string => {
+    const site = structure?.sites[site_idx]
+    const orig_idx = get_orig_site_idx(site, site_idx)
+    const element = get_majority_element(site)
+    return property_colors?.colors[orig_idx] ??
+      (element && colors.element?.[element]) ?? `#808080`
+  }
+
+  // Separate derived so material-only changes (opacity, edge color) don't rebuild
+  // buffers and color changes don't rebuild hulls
+  let polyhedra_buffers = $derived.by(() => {
+    if (polyhedra.length === 0) return null
+    const get_vertex_color = (poly: Polyhedron, vertex_idx: number): string => {
+      if (polyhedra_color_mode === `uniform`) return polyhedra_color
+      if (polyhedra_color_mode === `center`) {
+        return polyhedra_site_color(poly.center_site_idx)
+      }
+      // 'vertex' (default): each corner takes the color of the atom that forms it
+      return polyhedra_site_color(poly.vertex_site_idxs[vertex_idx])
+    }
+    return merge_polyhedra_buffers(polyhedra, get_vertex_color)
+  })
+
+  let polyhedra_center_site_idxs = $derived(
+    new Set(polyhedra.map((poly) => poly.center_site_idx)),
   )
 
+  // Publish which elements currently anchor polyhedra (consumed by controls so
+  // per-element toggles reflect the actual render state incl. spectator hiding)
+  $effect(() => {
+    const elems = [...new Set(polyhedra.map((poly) => poly.center_element))].sort()
+    if (elems.join(`,`) !== polyhedra_rendered_elements.join(`,`)) {
+      polyhedra_rendered_elements = elems
+    }
+  })
+
+  // Geometries with proper disposal on dependency change (same pattern as ReferencePlane)
+  const buffer_geometry = (attrs: Record<string, Float32Array>): BufferGeometry => {
+    const geo = new BufferGeometry()
+    for (const [name, array] of Object.entries(attrs)) {
+      geo.setAttribute(name, new BufferAttribute(array, 3))
+    }
+    return geo
+  }
+  let polyhedra_geometry: BufferGeometry | null = $state(null)
+  $effect(() => {
+    let geo: BufferGeometry | null = null
+    if (polyhedra_buffers && polyhedra_buffers.triangle_count > 0) {
+      const { positions: position, colors: color } = polyhedra_buffers
+      geo = buffer_geometry({ position, color })
+      geo.computeVertexNormals() // non-indexed -> per-face normals (flat shading)
+    }
+    polyhedra_geometry = geo
+    return () => geo?.dispose()
+  })
+
+  let polyhedra_edge_geometry: BufferGeometry | null = $state(null)
+  $effect(() => {
+    const geo = polyhedra_show_edges && polyhedra_buffers && polyhedra_buffers.edge_count > 0
+      ? buffer_geometry({ position: polyhedra_buffers.edge_positions })
+      : null
+    polyhedra_edge_geometry = geo
+    return () => geo?.dispose()
+  })
+
   let smart_site_label_offsets = $derived.by(() => {
     const offsets = new SvelteMap<number, Vec3>()
-    if (filtered_bond_pairs.length === 0) return offsets
+    if (bonds_to_render.length === 0) return offsets
 
     const bond_directions_by_site = new SvelteMap<number, Vec3[]>()
     const add_bond_direction = (site_idx: number, pos_1: Vec3, pos_2: Vec3) => {
-      const direction = math.normalize_vec3(
+      const direction = math.normalize_vec(
         math.subtract(pos_2, pos_1),
         [0, 0, 0],
       )
@@ -1101,7 +1281,7 @@
       ])
     }
 
-    for (const { site_idx_1, site_idx_2, pos_1, pos_2 } of filtered_bond_pairs) {
+    for (const { site_idx_1, site_idx_2, pos_1, pos_2 } of bonds_to_render) {
       add_bond_direction(site_idx_1, pos_1, pos_2)
       add_bond_direction(site_idx_2, pos_2, pos_1)
     }
@@ -1112,7 +1292,7 @@
   })
 
   let instanced_bond_groups = $derived.by(() => {
-    if (!structure?.sites || filtered_bond_pairs.length === 0) return []
+    if (!structure?.sites || bonds_to_render.length === 0) return []
 
     const group = {
       thickness: bond_thickness,
@@ -1125,7 +1305,7 @@
       }[],
     }
 
-    for (const bond_data of filtered_bond_pairs) {
+    for (const bond_data of bonds_to_render) {
       const site_a = structure.sites[bond_data.site_idx_1]
       const site_b = structure.sites[bond_data.site_idx_2]
 
@@ -1155,6 +1335,24 @@
     return map
   })
 
+  // Partial-occupancy atoms render as separate wedge (lune) meshes that converge
+  // to a point at the sphere's poles, leaving the ball hard to hover from some
+  // angles. Give each such site one invisible full-sphere hit target so it's as
+  // reliably hoverable as an ordered atom (single solid sphere). One per site.
+  let partial_hit_targets = $derived.by(() => {
+    const targets = new SvelteMap<number, EditableAtomHitTarget & { is_image_atom: boolean }>()
+    for (const atom of atom_data) {
+      if (!atom.has_partial_occupancy || targets.has(atom.site_idx)) continue
+      targets.set(atom.site_idx, {
+        site_idx: atom.site_idx,
+        position: atom.position,
+        radius: atom.radius,
+        is_image_atom: atom.is_image_atom,
+      })
+    }
+    return [...targets.values()]
+  })
+
   let editable_atom_hit_targets = $derived.by(() => {
     if (
       measure_mode !== `edit-bonds` ||
@@ -1184,7 +1382,7 @@
       ? site_radius_overrides?.get(site_idx)
       : undefined
     const base_radius = same_size_atoms ? 1 : override ?? calc_weighted_radius(site)
-    return base_radius * atom_radius
+    return base_radius * effective_atom_radius
   }
 
   // Interpolate between spin-down (#3498db blue) and spin-up (#e74c3c red)
@@ -1253,16 +1451,16 @@
         let mean: Vec3 = [0, 0, 0]
         for (const key of site_keys) {
           const vec = vec_map.get(key)
-          if (vec) mean = math.add(mean, math.normalize_vec3(vec)) as Vec3
+          if (vec) mean = math.add(mean, math.normalize_vec(vec)) as Vec3
         }
-        const mean_dir = math.normalize_vec3(mean, [0, 1, 0] as Vec3)
+        const mean_dir = math.normalize_vec(mean, [0, 1, 0] as Vec3)
         const [u_vec, v_vec] = math.compute_in_plane_basis(mean_dir)
         const offsets = new SvelteMap<string, Vec3>()
         for (const [idx, key] of site_keys.entries()) {
           const angle = (2 * Math.PI * idx) / n_keys
-          const dx = math.scale(u_vec, gap_abs * Math.cos(angle)) as Vec3
-          const dy = math.scale(v_vec, gap_abs * Math.sin(angle)) as Vec3
-          offsets.set(key, math.add(dx, dy) as Vec3)
+          const dx = math.scale(u_vec, gap_abs * Math.cos(angle))
+          const dy = math.scale(v_vec, gap_abs * Math.sin(angle))
+          offsets.set(key, math.add(dx, dy))
         }
         return offsets
       })
@@ -1316,8 +1514,8 @@
           }
 
           const offset = site_offsets?.[site_idx]?.get(key)
-          const position = offset ? math.add(site.xyz, offset) as Vec3 : site.xyz
-          const arrow_vec = vector_normalize ? math.normalize_vec3(vec) : vec
+          const position = offset ? math.add(site.xyz, offset) : site.xyz
+          const arrow_vec = vector_normalize ? math.normalize_vec(vec) : vec
 
           return {
             site_idx,
@@ -1365,57 +1563,29 @@
     ),
   )
 
-  let gizmo_props = $derived.by(() => {
-    const axis_options = Object.fromEntries(
-      [...AXIS_COLORS, ...NEG_AXIS_COLORS].map(([axis, color, hover_color]) => [
-        axis,
-        {
-          color,
-          labelColor: `#111`,
-          opacity: axis.startsWith(`n`) ? 0.9 : 0.8,
-          hover: {
-            color: hover_color,
-            labelColor: `#222222`,
-            opacity: axis.startsWith(`n`) ? 1 : 0.9,
-          },
-        },
-      ]),
-    )
-    return {
-      background: { enabled: false },
-      className: `responsive-gizmo`,
-      ...axis_options,
-      ...(typeof gizmo === `boolean` ? {} : gizmo),
-      offset: { left: 5, bottom: 5 },
-    }
-  })
-
-  let orbit_controls_props = $derived({
-    position: [0, 0, 0],
-    enableRotate: rotate_speed > 0,
-    rotateSpeed: rotate_speed,
-    enableZoom: zoom_speed > 0,
-    zoomSpeed: camera_projection === `orthographic` ? zoom_speed * 2 : zoom_speed,
-    zoomToCursor: zoom_to_cursor,
-    enablePan: pan_speed > 0,
-    panSpeed: pan_speed,
+  let orbit_controls_props = $derived(build_orbit_props({
+    camera_projection,
     target: camera_target ?? rotation_target,
-    maxZoom: max_zoom,
-    minZoom: min_zoom,
-    autoRotate: Boolean(auto_rotate),
-    autoRotateSpeed: auto_rotate,
-    enableDamping: Boolean(rotation_damping),
-    dampingFactor: rotation_damping,
-    onstart: () => {
-      camera_is_moving = true
+    rotate_speed,
+    zoom_speed,
+    zoom_to_cursor,
+    pan_speed,
+    max_zoom,
+    min_zoom,
+    auto_rotate,
+    rotation_damping,
+    set_camera_is_moving: (moving) => (camera_is_moving = moving),
+    // Close hover tooltips + bond context menu while the camera moves. Only hide the
+    // VISIBLE menu (not bond_context_target): clicking a menu button fires this
+    // orbit-controls start handler before the button's own handler runs, which still
+    // needs the target bond to apply the edit (see bond_context_target comment).
+    onstart_extra: () => {
       cancel_atom_hover_clear()
       hovered_idx = null
+      hovered_bond_key = null
       bond_context_menu = null
     },
-    onend: () => {
-      camera_is_moving = false
-    },
-  })
+  }))
 
   let measure_line_color = $derived.by(() => {
     if (typeof window === `undefined`) return
@@ -1492,31 +1662,17 @@
   </extras.HTML>
 {/snippet}
 
-{#if camera_projection === `perspective`}
-  <T.PerspectiveCamera
-    makeDefault
-    position={camera_position}
-    {fov}
-    near={camera_near}
-    far={camera_far}
-  >
-    <extras.OrbitControls bind:ref={orbit_controls} {...orbit_controls_props}>
-      {#if gizmo}<extras.Gizmo {...gizmo_props} />{/if}
-    </extras.OrbitControls>
-  </T.PerspectiveCamera>
-{:else}
-  <T.OrthographicCamera
-    makeDefault
-    position={camera_position}
-    zoom={computed_zoom}
-    near={-100}
-    far={camera_far}
-  >
-    <extras.OrbitControls bind:ref={orbit_controls} {...orbit_controls_props}>
-      {#if gizmo}<extras.Gizmo {...gizmo_props} />{/if}
-    </extras.OrbitControls>
-  </T.OrthographicCamera>
-{/if}
+<SceneCamera
+  {camera_projection}
+  position={camera_position}
+  {fov}
+  zoom={computed_zoom}
+  near={camera_near}
+  far={camera_far}
+  orbit_props={orbit_controls_props}
+  {gizmo}
+  bind:orbit_controls
+/>
 
 <T.DirectionalLight position={[3, 10, 10]} intensity={directional_light} />
 <T.AmbientLight intensity={ambient_light} />
@@ -1546,28 +1702,7 @@
               <extras.Instance
                 position={atom.position}
                 scale={atom.radius}
-                {...atom_hover_props(atom.site_idx, edit_mode_image)}
-                onpointerdown={(event: PointerEvent) => {
-                  if (
-                    edit_mode_image ||
-                    measure_mode !== `edit-bonds` ||
-                    bond_edit_mode !== `add`
-                  ) {
-                    return
-                  }
-                  select_edit_bonds_site(atom.site_idx, event)
-                }}
-                onclick={(event: MouseEvent) => {
-                  if (edit_mode_image) return
-                  if (measure_mode === `edit-bonds`) {
-                    if (bond_edit_mode !== `add`) return
-                    if (skip_duplicate_edit_bonds_click(atom.site_idx)) {
-                      event.stopPropagation()
-                      return
-                    }
-                  }
-                  toggle_selection(atom.site_idx, event)
-                }}
+                {...atom_pointer_props(atom.site_idx, edit_mode_image)}
               />
             {/each}
           </extras.InstancedMesh>
@@ -1580,32 +1715,9 @@
         }
           {@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}
-            {...atom_hover_props(atom.site_idx, partial_edit_image)}
-            onpointerdown={(event: PointerEvent) => {
-              if (
-                partial_edit_image ||
-                measure_mode !== `edit-bonds` ||
-                bond_edit_mode !== `add`
-              ) {
-                return
-              }
-              select_edit_bonds_site(atom.site_idx, event)
-            }}
-            onclick={(event: MouseEvent) => {
-              if (partial_edit_image) return
-              if (measure_mode === `edit-bonds`) {
-                if (bond_edit_mode !== `add`) return
-                if (skip_duplicate_edit_bonds_click(atom.site_idx)) {
-                  event.stopPropagation()
-                  return
-                }
-              }
-              toggle_selection(atom.site_idx, event)
-            }}
-          >
+          <!-- Visual only: pointer interaction handled by the invisible full-sphere
+            hit targets below (wedge meshes leave gaps at the poles). -->
+          <T.Group position={atom.position} scale={atom.radius}>
             {@const partial_color = partial_edit_image
             ? desaturate(atom.color)
             : atom.color}
@@ -1626,7 +1738,7 @@
               />
             </T.Mesh>
 
-            {#if atom.has_partial_occupancy && atom.render_start_cap}
+            {#if atom.render_start_cap}
               <T.Mesh rotation={[0, atom.start_phi, 0]}>
                 <T.CircleGeometry
                   args={[
@@ -1644,7 +1756,7 @@
                 />
               </T.Mesh>
             {/if}
-            {#if atom.has_partial_occupancy && atom.render_end_cap}
+            {#if atom.render_end_cap}
               <T.Mesh rotation={[0, atom.end_phi, 0]}>
                 <T.CircleGeometry
                   args={[
@@ -1671,6 +1783,20 @@
           {/if}
         {/each}
 
+        <!-- Invisible full-sphere hit targets for partial-occupancy sites so the
+          whole ball is hoverable/clickable (wedge meshes leave gaps at the poles). -->
+        {#each partial_hit_targets as hit (hit.site_idx)}
+          {@const hit_edit_image = measure_mode === `edit-atoms` && hit.is_image_atom}
+          <T.Mesh
+            position={hit.position}
+            scale={hit.radius}
+            {...atom_pointer_props(hit.site_idx, hit_edit_image)}
+          >
+            <T.SphereGeometry args={[0.5, sphere_segments, sphere_segments]} />
+            <T.MeshBasicMaterial transparent opacity={0} depthWrite={false} />
+          </T.Mesh>
+        {/each}
+
         <!-- Site labels/indices for instanced atoms -->
         {#if show_site_labels || show_site_indices}
           {#each unique_instanced_atoms as atom (atom.site_idx)}
@@ -1697,6 +1823,32 @@
         {/each}
       {/if}
 
+      <!-- Coordination polyhedra: all faces in one merged mesh, edges in one
+        LineSegments (1-2 draw calls regardless of supercell size) -->
+      {#if polyhedra_geometry}
+        <T.Mesh geometry={polyhedra_geometry} frustumCulled={false} raycast={() => null}>
+          <!-- depthWrite when mostly opaque: VESTA-like occlusion between polyhedra;
+            fully translucent settings fall back to see-through blending -->
+          <T.MeshStandardMaterial
+            vertexColors
+            transparent={polyhedra_opacity < 1}
+            opacity={polyhedra_opacity}
+            side={DoubleSide}
+            depthWrite={polyhedra_opacity >= 0.65}
+            flatShading
+          />
+        </T.Mesh>
+        {#if polyhedra_edge_geometry}
+          <T.LineSegments
+            geometry={polyhedra_edge_geometry}
+            frustumCulled={false}
+            raycast={() => null}
+          >
+            <T.LineBasicMaterial color={polyhedra_edge_color} />
+          </T.LineSegments>
+        {/if}
+      {/if}
+
       <!-- Clickable bond hit-test cylinders in edit-bonds mode -->
       {#if measure_mode === `edit-bonds` && editable_bond_pairs.length > 0}
         {#each editable_bond_pairs as
@@ -1911,8 +2063,8 @@
           {@const site = structure.sites[site_index]}
           {#if site}
             <!-- shift selected site labels down to avoid overlapping regular site labels-->
-            {@const selection_offset = math.add(site_label_offset, [0, -0.5, 0])}
-            {@const pos = math.add(site.xyz, selection_offset) as Vec3}
+            {@const selection_offset = math.add<Vec3>(site_label_offset, [0, -0.5, 0])}
+            {@const pos = math.add(site.xyz, selection_offset)}
             <extras.HTML center position={pos}>
               <span class="selection-label">{loop_idx + 1}</span>
             </extras.HTML>
@@ -1953,10 +2105,13 @@
             .map(([elem, count]) => `${elem}: ${count}`)
           return ` (${parts.join(`, `)})`
         })()}
+        {@const tooltip_species =
+          render_sites.find((rs) => rs.site_idx === hovered_idx)?.site.species ??
+          hovered_site.species ?? []}
         <CanvasTooltip position={hovered_site.xyz}>
           <!-- Element symbols with occupancies for disordered sites -->
           <div class="elements">
-            {#each hovered_site.species ?? [] as
+            {#each tooltip_species as
               { element, occu, oxidation_state: oxi_state },
               idx
               (`${element ?? ``}-${occu ?? ``}-${oxi_state ?? ``}-${idx}`)
@@ -1965,16 +2120,17 @@
               elem.symbol === element
             )?.name ??
               ``}
-              {#if idx > 0}&thinsp;{/if}
-              {#if occu !== 1}<span class="occupancy">{
-                  format_num(occu, `.3~f`)
-                }</span>{/if}
-              <strong>
-                {element}{#if oxi_state != null && oxi_state !== 0}<sup>{Math.abs(
-                    oxi_state,
-                  )}{oxi_state > 0 ? `+` : `−`}</sup>{/if}
-              </strong>
-              {#if element_name}<span class="elem-name">{element_name}</span>{/if}
+              <span class="species">
+                {#if occu !== 1}<span class="occupancy">{
+                    format_num(occu, `.3~f`)
+                  }</span>{/if}
+                <strong>
+                  {element}{#if oxi_state != null && oxi_state !== 0}<sup>{Math.abs(
+                      oxi_state,
+                    )}{oxi_state > 0 ? `+` : `−`}</sup>{/if}
+                </strong>
+                {#if element_name}<span class="elem-name">{element_name}</span>{/if}
+              </span>
             {/each}
           </div>
           <div class="coordinates fractional">abc: ({abc})</div>
@@ -1987,6 +2143,13 @@
 
       {#if visual_lattice}
         <Lattice matrix={visual_lattice.matrix} {...lattice_props} />
+        {#if symmetry_elements.length > 0}
+          <SymmetryElements
+            elements={symmetry_elements}
+            lattice={visual_lattice.matrix}
+            {...symmetry_elements_props}
+          />
+        {/if}
       {/if}
 
       <!-- TransformControls for editing atoms in edit-atoms mode -->
@@ -2096,7 +2259,7 @@
         ] as Vec3}
               {@const direct = math.euclidean_dist(pos_i, pos_j)}
               {@const pbc = lattice
-          ? measure.distance_pbc(pos_i, pos_j, lattice.matrix)
+          ? measure.distance_pbc(pos_i, pos_j, lattice.matrix, undefined, lattice.pbc)
           : direct}
               {@const differ = lattice ? Math.abs(pbc - direct) > 1e-6 : false}
               <extras.HTML center position={midpoint}>
@@ -2125,8 +2288,10 @@
               }
                 {@const site_a = structure.sites[idx_a]}
                 {@const site_b = structure.sites[idx_b]}
-                {@const v1 = measure.displacement_pbc(center.xyz, site_a.xyz, lattice?.matrix)}
-                {@const v2 = measure.displacement_pbc(center.xyz, site_b.xyz, lattice?.matrix)}
+                {@const disp = (to: Vec3) =>
+            measure.displacement_pbc(center.xyz, to, lattice?.matrix, undefined, lattice?.pbc)}
+                {@const v1 = disp(site_a.xyz)}
+                {@const v2 = disp(site_b.xyz)}
                 {@const n1 = Math.hypot(v1[0], v1[1], v1[2])}
                 {@const n2 = Math.hypot(v2[0], v2[1], v2[2])}
                 {@const angle_deg = measure.angle_between_vectors(v1, v2, `degrees`)}
@@ -2162,10 +2327,6 @@
 </T.Group>
 
 <style>
-  :global(.structure .responsive-gizmo) {
-    width: clamp(70px, 18cqmin, 100px) !important;
-    height: clamp(70px, 18cqmin, 100px) !important;
-  }
   .atom-label {
     background: var(--struct-atom-label-bg, rgba(0, 0, 0, 0.1));
     border: 0;
@@ -2179,6 +2340,13 @@
   .elements {
     margin-bottom: var(--canvas-tooltip-elements-margin);
   }
+  .species {
+    display: inline-block;
+    white-space: nowrap;
+    &:not(:first-child) {
+      margin-left: var(--canvas-tooltip-species-gap, 0.5em);
+    }
+  }
   .occupancy {
     font-size: var(--canvas-tooltip-occu-font-size);
     opacity: var(--canvas-tooltip-occu-opacity);