matterviz 0.4.1 → 0.4.3

package/dist/structure/Structure.svelte

@@ -6,14 +6,17 @@
   import { StatusMessage } from '../feedback'
   import Spinner from '../feedback/Spinner.svelte'
   import Icon from '../Icon.svelte'
-  import { create_file_drop_handler, drag_over_handlers, load_from_url } from '../io'
+  import * as io from '../io'
   import { forward_window_keydown, handle_and_prevent } from '../keyboard'
   import { parse_volumetric_file } from '../isosurface/parse'
   import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types'
   import {
     auto_isosurface_settings,
     DEFAULT_ISOSURFACE_SETTINGS,
-    tile_volumetric_data,
+    label_file_volumes,
+    lattices_match,
+    materialize_layers,
+    merge_imported_volumes,
   } from '../isosurface/types'
   import { type FullscreenToggleProp, toggle_fullscreen, ViewerChrome } from '../layout'
   import { sync_fullscreen } from '../layout/fullscreen.svelte'
@@ -21,6 +24,7 @@
   import { create_cart_to_frac, create_frac_to_cart } from '../math'
   import { DEFAULTS } from '../settings'
   import { colors } from '../state.svelte'
+  import StructureViewport from './StructureViewport.svelte'
   import type {
     AnyStructure,
     BondEditMode,
@@ -28,13 +32,16 @@
     Crystal,
     MeasureMode,
     StructureBond,
+    StructureView,
   } from './'
   import {
+    DEFAULT_STRUCTURE_VIEWS,
     default_vector_configs,
     get_element_counts,
     get_pbc_image_sites,
     get_structure_vector_keys,
   } from './'
+  import { push_edit, step_history } from './edit-history'
   import { wrap_to_unit_cell } from './pbc'
   import {
     is_valid_supercell_input,
@@ -45,13 +52,12 @@
   import * as symmetry from '../symmetry'
   import { transform_cell } from '../symmetry'
   import type { MoyoDataset } from '@spglib/moyo-wasm'
-  import { Canvas } from '@threlte/core'
   import type { ComponentProps, Snippet } from 'svelte'
   import { untrack } from 'svelte'
   import { click_outside, tooltip } from 'svelte-multiselect/attachments'
   import type { HTMLAttributes } from 'svelte/elements'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
-  import type { Camera, OrthographicCamera, Scene } from 'three'
+  import type { Camera, Scene } from 'three'
   import type { AtomColorConfig } from './atom-properties'
   import { get_property_colors } from './atom-properties'
   import AtomLegend from './AtomLegend.svelte'
@@ -59,7 +65,11 @@
   import { BOND_ORDER_OPTIONS, merge_bond_edits, remap_bonds_after_deletion } from './bonding'
   import type { StructureHandlerData } from './index'
   import { MAX_SELECTED_SITES } from './measure'
-  import { normalize_fractional_coords, parse_any_structure } from './parse'
+  import {
+    ensure_lattice_params,
+    normalize_fractional_coords,
+    parse_any_structure,
+  } from './parse'
   import StructureControls from './StructureControls.svelte'
   import StructureExportPane from './StructureExportPane.svelte'
   import StructureInfoPane from './StructureInfoPane.svelte'
@@ -107,6 +117,8 @@
     lattice_props: lattice_props_in = $bindable(),
     controls_open = $bindable(false),
     info_pane_open = $bindable(false),
+    multi_view = $bindable(false),
+    views = DEFAULT_STRUCTURE_VIEWS,
     enable_measure_mode = $bindable(true),
     measure_mode = $bindable<MeasureMode>(`distance`),
     bond_edit_mode = $bindable<BondEditMode>(`add`),
@@ -183,95 +195,101 @@
     on_camera_reset,
     on_bonds_change,
     ...rest
-  }:
-    & {
-      structure?: AnyStructure
-      bonds?: StructureBond[]
-      scene_props?: ComponentProps<typeof StructureScene>
-      // Controls visibility configuration.
-      // - 'always': controls always visible
-      // - 'hover': controls visible on component hover (default)
-      // - 'never': controls never visible
-      // - object: { mode, hidden, style } for fine-grained control
-      //
-      // Control names: 'reset-camera', 'fullscreen', 'measure-mode', 'info-pane', 'export-pane', 'controls'
-      show_controls?: ShowControlsProp
-      fullscreen?: boolean
-      // bindable width of the canvas
-      width?: number
-      // bindable height of the canvas
-      height?: number
-      // Canvas wrapper element (for export pane)
-      wrapper?: HTMLDivElement
-      // PNG export DPI setting
-      png_dpi?: number
-      reset_text?: string
-      hovered?: boolean
-      dragover?: boolean
-      allow_file_drop?: boolean
-      enable_info_pane?: boolean
-      enable_measure_mode?: boolean
-      measure_mode?: MeasureMode
-      bond_edit_mode?: BondEditMode
-      bond_edit_order?: BondOrder
-      info_pane_open?: boolean
-      fullscreen_toggle?: FullscreenToggleProp
-      bottom_left?: Snippet<[{ structure?: AnyStructure }]>
-      top_right_controls?: Snippet // Additional controls to render at the end of the control buttons row
-      data_url?: string // URL to load structure from (alternative to providing structure directly)
-      // Generic callback for when files are dropped - receives raw content and filename
-      on_file_drop?: (content: string | ArrayBuffer, filename: string) => void
-      // spinner props (passed to Spinner component)
-      spinner_props?: ComponentProps<typeof Spinner>
-      loading?: boolean
-      error_msg?: string
-      // Performance mode: 'quality' (default) or 'speed' for large structures
-      performance_mode?: `quality` | `speed`
-      // allow parent components to control highlighted/selected site indices
-      selected_sites?: number[]
-      highlighted_sites?: number[]
-      hovered_site_idx?: number | null
-      // explicit measured sites for distance/angle overlays
-      measured_sites?: number[]
-      // expose the displayed structure (with image atoms and/or supercell) for external use
-      displayed_structure?: AnyStructure
-      // Track which elements are hidden (bindable across frames in trajectories)
-      hidden_elements?: Set<ElementSymbol>
-      // Track which property values are hidden (e.g. Wyckoff positions, coordination numbers)
-      hidden_prop_vals?: Set<number | string>
-      // Per-element radius overrides (absolute values in Angstroms)
-      element_radius_overrides?: Partial<Record<ElementSymbol, number>>
-      // Per-site radius overrides (absolute values in Angstroms)
-      // Accepts Map or SvelteMap for flexibility with external callers
-      site_radius_overrides?: Map<number, number> | SvelteMap<number, number>
-      // Symmetry analysis data (bindable for external access)
-      sym_data?: MoyoDataset | null
-      // Symmetry analysis settings (bindable for external control)
-      symmetry_settings?: Partial<SymmetrySettings>
-      // Map element symbols to different elements (e.g. {'H': 'Na', 'He': 'Cl'})
-      element_mapping?: Partial<Record<ElementSymbol, ElementSymbol>>
-      // Cell type: original, conventional, or primitive (requires symmetry analysis)
-      cell_type?: CellType
-      // Volumetric data for isosurface rendering (parsed from CHGCAR or .cube files)
-      volumetric_data?: VolumetricData[]
-      // Isosurface rendering settings
-      isosurface_settings?: IsosurfaceSettings
-      // Active volume index when multiple volumes are present
-      active_volume_idx?: number
-      // structure content as string (alternative to providing structure directly or via data_url)
-      structure_string?: string
-      // Atom coloring configuration
-      atom_color_config?: Partial<AtomColorConfig>
-      children?: Snippet<[{ structure?: AnyStructure; fullscreen: boolean }]>
-      on_file_load?: EventHandler
-      on_error?: EventHandler
-      on_fullscreen_change?: EventHandler
-      on_camera_move?: EventHandler
-      on_camera_reset?: EventHandler
-      on_bonds_change?: (bonds: StructureBond[] | undefined) => void
-    }
-    & Omit<ComponentProps<typeof StructureControls>, `children` | `onclose`>
-    & Omit<HTMLAttributes<HTMLDivElement>, `children`> = $props()
+  }: {
+    structure?: AnyStructure
+    bonds?: StructureBond[]
+    scene_props?: ComponentProps<typeof StructureScene>
+    // Controls visibility configuration.
+    // - 'always': controls always visible
+    // - 'hover': controls visible on component hover (default)
+    // - 'never': controls never visible
+    // - object: { mode, hidden, style } for fine-grained control
+    //
+    // Control names: 'reset-camera', 'fullscreen', 'measure-mode', 'info-pane', 'export-pane', 'controls'
+    show_controls?: ShowControlsProp
+    fullscreen?: boolean
+    // bindable width of the canvas
+    width?: number
+    // bindable height of the canvas
+    height?: number
+    // Canvas wrapper element (for export pane)
+    wrapper?: HTMLDivElement
+    // PNG export DPI setting
+    png_dpi?: number
+    reset_text?: string
+    hovered?: boolean
+    dragover?: boolean
+    allow_file_drop?: boolean
+    enable_info_pane?: boolean
+    enable_measure_mode?: boolean
+    measure_mode?: MeasureMode
+    bond_edit_mode?: BondEditMode
+    bond_edit_order?: BondOrder
+    info_pane_open?: boolean
+    // When true, split the canvas into a 2x2 grid showing the structure from
+    // different angles (Ovito-style). Each pane has independent orbit controls.
+    multi_view?: boolean
+    // The 4 (or more) view definitions used by multi_view. Defaults to an
+    // Ovito-like set: one perspective + three orthographic axis views.
+    views?: StructureView[]
+    fullscreen_toggle?: FullscreenToggleProp
+    bottom_left?: Snippet<[{ structure?: AnyStructure }]>
+    top_right_controls?: Snippet // Additional controls to render at the end of the control buttons row
+    data_url?: string // URL to load structure from (alternative to providing structure directly)
+    // Generic callback for when files are dropped - receives raw content and filename
+    on_file_drop?: (content: string | ArrayBuffer, filename: string) => void
+    // spinner props (passed to Spinner component)
+    spinner_props?: ComponentProps<typeof Spinner>
+    loading?: boolean
+    error_msg?: string
+    // Performance mode: 'quality' (default) or 'speed' for large structures
+    performance_mode?: `quality` | `speed`
+    // allow parent components to control highlighted/selected site indices
+    selected_sites?: number[]
+    highlighted_sites?: number[]
+    hovered_site_idx?: number | null
+    // explicit measured sites for distance/angle overlays
+    measured_sites?: number[]
+    // expose the displayed structure (with image atoms and/or supercell) for external
+    // use. Output-only: the scene renders from an internal raw copy for performance,
+    // so external writes to this prop are ignored (overwritten on the next pipeline run)
+    displayed_structure?: AnyStructure
+    // Track which elements are hidden (bindable across frames in trajectories)
+    hidden_elements?: Set<ElementSymbol>
+    // Track which property values are hidden (e.g. Wyckoff positions, coordination numbers)
+    hidden_prop_vals?: Set<number | string>
+    // Per-element radius overrides (absolute values in Angstroms)
+    element_radius_overrides?: Partial<Record<ElementSymbol, number>>
+    // Per-site radius overrides (absolute values in Angstroms)
+    // Accepts Map or SvelteMap for flexibility with external callers
+    site_radius_overrides?: Map<number, number> | SvelteMap<number, number>
+    // Symmetry analysis data (bindable for external access)
+    sym_data?: MoyoDataset | null
+    // Symmetry analysis settings (bindable for external control)
+    symmetry_settings?: Partial<SymmetrySettings>
+    // Map element symbols to different elements (e.g. {'H': 'Na', 'He': 'Cl'})
+    element_mapping?: Partial<Record<ElementSymbol, ElementSymbol>>
+    // Cell type: original, conventional, or primitive (requires symmetry analysis)
+    cell_type?: CellType
+    // Volumetric data for isosurface rendering (parsed from CHGCAR or .cube files)
+    volumetric_data?: VolumetricData[]
+    // Isosurface rendering settings
+    isosurface_settings?: IsosurfaceSettings
+    // Active volume index when multiple volumes are present
+    active_volume_idx?: number
+    // structure content as string (alternative to providing structure directly or via data_url)
+    structure_string?: string
+    // Atom coloring configuration
+    atom_color_config?: Partial<AtomColorConfig>
+    children?: Snippet<[{ structure?: AnyStructure; fullscreen: boolean }]>
+    on_file_load?: EventHandler
+    on_error?: EventHandler
+    on_fullscreen_change?: EventHandler
+    on_camera_move?: EventHandler
+    on_camera_reset?: EventHandler
+    on_bonds_change?: (bonds: StructureBond[] | undefined) => void
+  } & Omit<ComponentProps<typeof StructureControls>, `children` | `onclose`> &
+    Omit<HTMLAttributes<HTMLDivElement>, `children`> = $props()
 
   // Initialize models from incoming props; mutations come from UI controls; we mirror into local dicts (NOTE only doing shallow merge)
   $effect.pre(() => {
@@ -283,41 +301,70 @@
     }
   })
 
-  // Load structure from URL when data_url is provided
+  // Load structure from URL when data_url is provided. A monotonic load_id ignores stale
+  // completions so a newer data_url (or an externally-supplied structure, via the cleanup)
+  // can't be clobbered by a slow earlier fetch.
+  let data_url_load_id = 0
+  let loaded_data_url: string | undefined
+  let url_owned_structure: AnyStructure | undefined
+
   $effect(() => {
-    if (data_url && !structure) {
-      loading = true
-      error_msg = undefined
-
-      load_from_url(data_url, (content, filename) => {
-        if (on_file_drop) on_file_drop(content, filename)
-        else {
-          // Parse structure internally when no handler provided
-          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 (error) {
-            error_msg = `Failed to parse structure: ${
-              to_error(error).message
-            }`
-            on_error?.({ error_msg, filename })
-          }
+    const requested_url = data_url
+    const current_structure = structure
+    // Host on_file_drop owns the structure; don't treat it as caller-owned cancel.
+    const caller_owns_structure = Boolean(
+      !on_file_drop && current_structure && current_structure !== url_owned_structure,
+    )
+    if (!requested_url || caller_owns_structure) {
+      loaded_data_url = undefined
+      url_owned_structure = undefined
+      return
+    }
+    if (loaded_data_url === requested_url) return
+
+    const load_id = ++data_url_load_id
+    const is_current = () => load_id === data_url_load_id
+    loading = true
+    error_msg = undefined
+
+    io.load_from_url(requested_url, (content, filename) => {
+      if (!is_current()) return // stale response
+      if (on_file_drop) {
+        on_file_drop(content, filename)
+        loaded_data_url = requested_url
+      } else {
+        // Parse structure internally when no handler provided
+        try {
+          parse_and_emit_file(content, filename)
+          url_owned_structure = structure
+          loaded_data_url = requested_url
+        } catch (error) {
+          error_msg = `Failed to parse structure: ${to_error(error).message}`
+          on_error?.({ error_msg, filename })
         }
+      }
+    })
+      .catch((error: Error) => {
+        if (!is_current()) return
+        console.error(`Failed to load structure from URL:`, error)
+        error_msg = `Failed to load structure: ${error.message}`
+        on_error?.({ error_msg, filename: io.basename_from_url(requested_url) })
+      })
+      .finally(() => {
+        if (is_current()) loading = false
       })
-        .then(() => loading = false)
-        .catch((error: Error) => {
-          console.error(`Failed to load structure from URL:`, error)
-          error_msg = `Failed to load structure: ${error.message}`
-          loading = false
-          on_error?.({ error_msg, filename: data_url })
-        })
+
+    return () => {
+      // invalidate in-flight load on data_url change / structure arrival / unmount
+      if (is_current()) {
+        data_url_load_id += 1
+        loading = false
+      }
     }
   })
 
-  $effect(() => { // Parse structure from string when structure_string is provided
+  $effect(() => {
+    // Parse structure from string when structure_string is provided
     if (!structure_string || data_url) return
     loading = true
     error_msg = undefined
@@ -331,9 +378,7 @@
         throw new Error(`Failed to parse structure from string`)
       }
     } catch (err) {
-      error_msg = `Failed to parse structure from string: ${
-        to_error(err).message
-      }`
+      error_msg = `Failed to parse structure from string: ${to_error(err).message}`
       untrack(() => on_error?.({ error_msg, filename: `string` }))
     } finally {
       loading = false
@@ -389,12 +434,7 @@
 
   // Compute property-based colors for legend display
   let property_colors = $derived(
-    get_property_colors(
-      structure,
-      atom_color_config,
-      scene_props.bonding_strategy,
-      sym_data,
-    ),
+    get_property_colors(structure, atom_color_config, scene_props.bonding_strategy, sym_data),
   )
 
   let symmetry_run_id = 0
@@ -426,7 +466,7 @@
     } else {
       // Keep previous symmetry data while recomputing so bound consumers
       // (e.g. SymmetryStats inputs) do not unmount and lose focus.
-      untrack(() => symmetry_error = undefined)
+      untrack(() => (symmetry_error = undefined))
     }
     const run_id = ++symmetry_run_id
     // Destructure symmetry_settings to ensure Svelte tracks changes to symprec and algo
@@ -436,20 +476,21 @@
     // Skip symmetry auto-analysis in unit tests; happy-dom can't fetch WASM assets
     if (typeof process !== `undefined` && process.env?.VITEST) return
 
-    symmetry.ensure_moyo_wasm_ready()
+    symmetry
+      .ensure_moyo_wasm_ready()
       .then(() =>
         run_id === symmetry_run_id
           ? symmetry.analyze_structure_symmetry(current_structure, current_settings)
-          : null
+          : null,
       )
       .then((data) => {
         if (data && run_id === symmetry_run_id) {
-          untrack(() => sym_data = data)
+          untrack(() => (sym_data = data))
         }
       })
       .catch((err) => {
         if (run_id === symmetry_run_id) {
-          untrack(() => sym_data = null)
+          untrack(() => (sym_data = null))
           symmetry_error = `Symmetry analysis failed: ${err?.message || err}`
           console.error(`Symmetry analysis failed:`, err)
         }
@@ -474,8 +515,7 @@
   let last_emitted_bond_signature = $state<string>()
   let bond_edit_snapshot = $state.raw<BondEditSnapshot>()
   let has_bond_edits = $derived(
-    added_bonds.length > 0 || removed_bonds.length > 0 ||
-      bond_order_overrides.length > 0,
+    added_bonds.length > 0 || removed_bonds.length > 0 || bond_order_overrides.length > 0,
   )
 
   const clone_bonds = (edit_bonds: StructureBond[]): StructureBond[] =>
@@ -556,10 +596,10 @@
   const current_source_bond_signature = (): string => {
     const raw_signature = bond_signature(current_source_bonds())
     if (raw_signature !== last_emitted_bond_signature) return raw_signature
-    return bond_history_context?.source_bond_signature ??
-      (bond_edit_snapshot
-        ? bond_signature(bond_edit_snapshot.bonds)
-        : raw_signature)
+    return (
+      bond_history_context?.source_bond_signature ??
+      (bond_edit_snapshot ? bond_signature(bond_edit_snapshot.bonds) : raw_signature)
+    )
   }
 
   const current_bond_edit_context = (): BondEditContext => ({
@@ -646,16 +686,30 @@
 
   // === Edit-atoms mode state ===
   let dragging_atoms = $state(false)
-  let undo_stack = $state<AnyStructure[]>([])
-  let redo_stack = $state<AnyStructure[]>([])
+  // History entries snapshot the bindable `bonds` prop alongside the structure:
+  // atom deletion remaps `bonds` to the shifted site indices, so restoring the
+  // structure alone would leave explicit bonds pointing at wrong sites.
+  type EditSnapshot = { structure: AnyStructure; bonds: StructureBond[] | undefined }
+  // $state.raw: stacks hold full structure snapshots — deep-proxying them would make
+  // every restored structure (and all downstream site reads) go through proxy traps.
+  // Mutations happen via reassignment so .length stays reactive in the template.
+  let undo_stack = $state.raw<EditSnapshot[]>([])
+  let redo_stack = $state.raw<EditSnapshot[]>([])
   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
+  // Claim URL ownership before regular effects so internal edits aren't treated as caller-owned.
+  $effect.pre(() => {
+    void structure
+    if (is_internal_edit && loaded_data_url && loaded_data_url === data_url && structure) {
+      url_owned_structure = structure
+    }
+  })
+
   // Add-atom sub-mode state (bound to StructureScene)
   let add_atom_mode = $state(false)
   let add_element = $state<ElementSymbol>(`C` as ElementSymbol)
-  let canvas_cursor = $state(`default`)
   let is_measure_selection_mode = $derived(
     measure_mode === `distance` || measure_mode === `angle`,
   )
@@ -693,28 +747,40 @@
     dragging_atoms = false
   }
 
+  const snapshot_edit_state = (current: AnyStructure): EditSnapshot => ({
+    structure: $state.snapshot(current) as AnyStructure,
+    bonds: bonds && ($state.snapshot(bonds) as StructureBond[]),
+  })
+
   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) as AnyStructure)
-    redo_stack.length = 0
+    ;[undo_stack, redo_stack] = push_edit(
+      [undo_stack, redo_stack],
+      snapshot_edit_state(structure),
+      MAX_HISTORY,
+    )
   }
 
-  // Shared undo/redo: pop from `source`, push current state onto `target`
-  function apply_history(source: AnyStructure[], target: AnyStructure[]) {
-    if (source.length === 0 || !structure) return
-    const restored = source.pop()
-    if (!restored) return
+  // Shared undo/redo: restore the top of that direction's stack, pushing the
+  // current state onto the opposite one ($state.raw stacks update by reassignment)
+  function apply_history(direction: `undo` | `redo`) {
+    // Check the stack before snapshotting: $state.snapshot deep-clones the structure
+    if (!structure || (direction === `undo` ? undo_stack : redo_stack).length === 0) return
+    const result = step_history(
+      [undo_stack, redo_stack],
+      direction,
+      snapshot_edit_state(structure),
+    )
+    if (!result) return
     is_internal_edit = true
-    target.push($state.snapshot(structure) as AnyStructure)
-    structure = restored
+    ;[undo_stack, redo_stack] = result.stacks
+    structure = result.restored.structure
+    bonds = result.restored.bonds
     clear_selection()
   }
 
-  const undo = () => apply_history(undo_stack, redo_stack)
-  const redo = () => apply_history(redo_stack, undo_stack)
+  const undo = () => apply_history(`undo`)
+  const redo = () => apply_history(`redo`)
 
   // Clear undo/redo stacks when structure changes externally (file load, etc.)
   // Internal edits set is_internal_edit=true before modifying structure.
@@ -757,7 +823,10 @@
   $effect(() => {
     void bond_edit_mode
     untrack(() => {
-      if (measure_mode === `edit-bonds` && (selected_sites.length > 0 || measured_sites.length > 0)) {
+      if (
+        measure_mode === `edit-bonds` &&
+        (selected_sites.length > 0 || measured_sites.length > 0)
+      ) {
         clear_selection()
       }
     })
@@ -788,16 +857,21 @@
   $effect(() => {
     viewer_active = hovered || focused
   })
-  let scene_gizmo = $derived(viewer_active && (scene_props.gizmo ?? scene_props.show_gizmo))
+  // Keep the gizmo mounted whenever enabled — toggling via `{#if gizmo}` on hover remounts
+  // OrbitControls/Gizmo and resets camera rotation. Visibility is CSS-gated by `gizmo-visible`.
+  let scene_gizmo = $derived(scene_props.gizmo ?? scene_props.show_gizmo)
   let active_scene_sites = $derived([
     ...new SvelteSet([...(scene_props.active_sites ?? []), ...highlighted_sites]),
   ])
 
   // 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
+  // This ensures atoms are rendered inside the unit cell regardless of data source.
+  // ensure_lattice_params covers structures that bypass parse_any_structure (direct
+  // props, trajectory JSON frames) with matrix-only pymatgen lattices, which would
+  // otherwise NaN the camera auto-fit and render blank.
   let normalized_structure = $derived.by(() => {
     if (!structure || !(`lattice` in structure)) return structure
-    return normalize_fractional_coords(structure) as AnyStructure
+    return ensure_lattice_params(normalize_fractional_coords(structure)) as AnyStructure
   })
 
   let structure_with_bonds = $derived.by(() => {
@@ -812,7 +886,8 @@
   // This must happen BEFORE supercell transformation
   let cell_transformed_structure = $derived.by(() => {
     if (
-      !structure_with_bonds || !(`lattice` in structure_with_bonds) ||
+      !structure_with_bonds ||
+      !(`lattice` in structure_with_bonds) ||
       cell_type === `original`
     ) {
       return structure_with_bonds
@@ -829,8 +904,11 @@
     }
   })
 
-  // Create supercell if needed (uses cell_transformed_structure as base)
-  let supercell_structure = $state(structure)
+  // Create supercell if needed (uses cell_transformed_structure as base).
+  // $state.raw: supercells can hold thousands of sites — deep-proxying them makes
+  // every downstream read (bonding, PBC images, instancing) traverse proxy traps,
+  // measured ~15x slower for compute_bonds on a 704-site supercell.
+  let supercell_structure = $state.raw(structure)
   let supercell_loading = $state(false)
   let has_supercell = $derived(
     Boolean(supercell_scaling) && ![``, `1x1x1`, `1`].includes(supercell_scaling),
@@ -849,35 +927,48 @@
     })
   })
 
-  // Tile volumetric data to match supercell when active.
-  // Gate on !supercell_loading so the tiled volume and supercell structure update
-  // in the same frame (large supercells defer structure via setTimeout).
-  let supercell_volume = $derived.by(() => {
-    const vol = volumetric_data?.[active_volume_idx]
-    if (!vol || !has_supercell || supercell_loading) return vol
+  // Supercell tiling factors for isosurface geometry (tiling itself happens in
+  // the Isosurface component so color sampling can use the untiled full-res
+  // volumes). Gate on !supercell_loading so tiled surfaces and the supercell
+  // structure update in the same frame (large supercells defer via setTimeout).
+  let volume_scaling = $derived.by((): Vec3 => {
+    if (!has_supercell || supercell_loading) return [1, 1, 1]
     try {
-      return tile_volumetric_data(vol, parse_supercell_scaling(supercell_scaling))
+      return parse_supercell_scaling(supercell_scaling)
     } catch {
-      return vol
+      return [1, 1, 1]
     }
   })
 
   let supercell_timeout: ReturnType<typeof setTimeout> | undefined
+  // Compute the supercell, falling back to the unscaled structure on error
+  const make_supercell_safe = (base: Crystal): Crystal => {
+    try {
+      return make_supercell(base, supercell_scaling)
+    } catch (error) {
+      console.error(`Failed to create supercell:`, error)
+      show_toast(`Failed to create supercell: ${to_error(error).message}`)
+      return base
+    }
+  }
   $effect(() => {
     const base_structure = cell_transformed_structure
     clearTimeout(supercell_timeout)
-    if (!base_structure || !(`lattice` in base_structure) || !has_supercell) {
-      supercell_structure = base_structure
-      supercell_loading = false
-    } else if (!is_valid_supercell_input(supercell_scaling)) {
+    if (
+      !base_structure ||
+      !(`lattice` in base_structure) ||
+      !has_supercell ||
+      !is_valid_supercell_input(supercell_scaling)
+    ) {
       supercell_structure = base_structure
       supercell_loading = false
     } else {
       // For large supercells, show loading state and use async generation
       const sites_count = base_structure.sites?.length || 0
-      const [nx_str, ny_str, nz_str] = supercell_scaling.split(/[x×]/)
-      const scaling_mult = (parseInt(nx_str, 10) || 1) * (parseInt(ny_str, 10) || 1) *
-        (parseInt(nz_str, 10) || 1)
+      // lenient parse just for a size estimate (invalid factors count as 1)
+      const scaling_mult = supercell_scaling
+        .split(/[x×]/)
+        .reduce((product, factor) => product * (Number(factor) || 1), 1)
       const estimated_sites = sites_count * scaling_mult
 
       // Show spinner for supercells with >1000 estimated sites or scaling >8
@@ -887,27 +978,11 @@
         supercell_loading = true
         // Use setTimeout to allow UI to update before heavy computation
         supercell_timeout = setTimeout(() => {
-          try {
-            if (base_structure && `lattice` in base_structure) {
-              supercell_structure = make_supercell(
-                base_structure as Crystal,
-                supercell_scaling,
-              )
-            }
-          } catch (error) {
-            console.error(`Failed to create supercell:`, error)
-            supercell_structure = base_structure
-          } finally {
-            supercell_loading = false
-          }
+          supercell_structure = make_supercell_safe(base_structure as Crystal)
+          supercell_loading = false
         }, 10)
       } else {
-        if (base_structure && `lattice` in base_structure) {
-          supercell_structure = make_supercell(
-            base_structure as Crystal,
-            supercell_scaling,
-          )
-        }
+        supercell_structure = make_supercell_safe(base_structure as Crystal)
         supercell_loading = false
       }
     }
@@ -934,9 +1009,12 @@
     })
   })
 
-  // 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.
+  // Element-map + PBC image atoms. Skipped during drags (doubled site count drops frames);
+  // images return on release.
+  // The render path reads the internal $state.raw copy, NOT the bindable prop:
+  // if a consumer binds displayed_structure to a deep $state, reading the prop
+  // back would re-proxy every site and slow all scene computations ~10x.
+  let internal_displayed_structure = $state.raw<AnyStructure | undefined>(undefined)
   $effect(() => {
     let struct = supercell_structure
     if (struct && element_mapping && Object.keys(element_mapping).length > 0) {
@@ -953,124 +1031,92 @@
         })),
       }
     }
-    displayed_structure =
-      !dragging_atoms && show_image_atoms && struct && `lattice` in struct &&
-        struct.lattice
+    // Local var, NOT a read-back of the states written below: reading our own
+    // fresh-object write inside this effect would self-retrigger it forever.
+    const next =
+      !dragging_atoms && show_image_atoms && struct && `lattice` in struct && struct.lattice
         ? get_pbc_image_sites(struct)
         : struct
+    internal_displayed_structure = next
+    displayed_structure = next
   })
 
-  // Track if camera has ever been moved from initial position
-  let camera_has_moved = $state(false)
-  let camera_is_moving = $state(false)
+  // scene + camera of the primary pane, bound out for the export pane. All other camera
+  // handling (move tracking, reset, re-framing) lives in StructureViewport.
   let scene = $state<Scene | undefined>(undefined)
   let camera = $state<Camera | undefined>(undefined)
-  let orbit_controls = $state<
-    ComponentProps<typeof StructureScene>[`orbit_controls`]
-  >(undefined)
-  let rotation_target_ref = $state<Vec3 | undefined>(undefined)
-  let initial_computed_zoom = $state<number | undefined>(undefined)
+
+  // Multi-side view state: index of the pane the pointer is over (gets edit interactions),
+  // a token bumped to reset every pane, and the set of panes whose camera has moved (so
+  // the reset button stays visible until every moved pane is reset). Pane 0 = primary.
+  let active_pane_idx = $state(0)
+  let reset_token = $state(0)
+  // SvelteSet is already reactive; do NOT wrap in $state (double-proxying breaks it)
+  const moved_panes = new SvelteSet<number>()
+  let any_camera_moved = $derived(moved_panes.size > 0)
+
+  // Inputs shared by every StructureViewport (single + all multi-view panes). Camera,
+  // selection bindings, and per-pane chrome differ and stay on each snippet below.
+  let shared_viewport_props = $derived({
+    structure: internal_displayed_structure,
+    base_structure: cell_transformed_structure,
+    scene_props,
+    gizmo: scene_gizmo,
+    lattice_props,
+    volumetric_data,
+    volume_scaling,
+    active_volume_idx,
+    isosurface_settings,
+    bond_edits_enabled,
+    bond_edit_order,
+    measure_mode,
+    atom_color_config,
+    sym_data,
+    active_sites: active_scene_sites,
+    on_sites_moved: handle_sites_moved,
+    on_operation_start: push_undo,
+    on_bond_edit_start: push_bond_undo,
+    on_add_atom: handle_add_atom,
+  })
 
   // Mutual exclusion: opening one pane closes others
   $effect(() => {
     if (info_pane_open) {
-      untrack(() => [controls_open, export_pane_open] = [false, false])
+      untrack(() => ([controls_open, export_pane_open] = [false, false]))
     }
   })
   $effect(() => {
     if (controls_open) {
-      untrack(() => [info_pane_open, export_pane_open] = [false, false])
+      untrack(() => ([info_pane_open, export_pane_open] = [false, false]))
     }
   })
   $effect(() => {
     if (export_pane_open) {
-      untrack(() => [info_pane_open, controls_open] = [false, false])
+      untrack(() => ([info_pane_open, controls_open] = [false, false]))
     }
   })
 
-  // Reset tracking when structure changes
+  // Reset moved-pane tracking when structure changes
   $effect(() => {
-    if (structure) camera_has_moved = false
+    // untrack: clearing must not add moved_panes as a dependency, else a pane move
+    // (which adds to moved_panes) would immediately re-run this and clear it again.
+    if (structure) untrack(() => moved_panes.clear())
   })
 
   // Clear stale camera target and position so StructureScene uses the new
   // structure's rotation_target (unit cell center) and auto-positions the camera.
   function clear_camera_state() {
+    // Reset to a fresh [0,0,0] so the primary viewport re-frames the new structure.
+    // Side panes reset their local camera state in StructureViewport's structure effect.
     scene_props.camera_target = undefined
     scene_props.camera_position = [0, 0, 0]
   }
 
-  const read_orbit_target = (): Vec3 | undefined => {
-    if (!orbit_controls?.target) return
-    const { x, y, z } = orbit_controls.target
-    return [x, y, z]
-  }
-
-  const read_camera_position = (): Vec3 | undefined =>
-    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.
-    scene_props.camera_position = [0, 0, 0]
-    scene_props.camera_target = rotation_target_ref
-    camera_has_moved = false
-
-    let camera_position: Vec3 = [0, 0, 0]
-    let camera_target: Vec3 | undefined = rotation_target_ref
-
-    // Reset pan/zoom and ensure controls target returns to structure center.
-    if (orbit_controls && camera) {
-      if (
-        `reset` in orbit_controls &&
-        typeof orbit_controls.reset === `function`
-      ) orbit_controls.reset()
-      if (orbit_controls.target && rotation_target_ref) {
-        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) {
-        const ortho_camera = camera as OrthographicCamera
-        ortho_camera.zoom = initial_computed_zoom
-        ortho_camera.updateProjectionMatrix()
-      }
-
-      // Call update to apply changes immediately
-      if (typeof orbit_controls.update === `function`) orbit_controls.update()
-      camera_position = read_camera_position() ?? camera_position
-      camera_target = read_orbit_target()
-    }
-
-    scene_props.camera_position = camera_position
-    scene_props.camera_target = camera_target
-    on_camera_reset?.({ structure, camera_has_moved, camera_position, camera_target })
+  // Reset every pane's camera (each StructureViewport resets on a reset_token bump and,
+  // for the primary, emits on_camera_reset).
+  function reset_all_cameras() {
+    reset_token += 1
+    moved_panes.clear()
   }
 
   const emit_file_load_event = (
@@ -1081,27 +1127,69 @@
     on_file_load?.({
       structure: loaded_structure,
       filename,
-      file_size: typeof content === `string`
-        ? new Blob([content]).size
-        : content.byteLength,
+      file_size: typeof content === `string` ? new Blob([content]).size : content.byteLength,
       total_atoms: loaded_structure.sites?.length || 0,
     })
 
+  // The currently loaded structure's lattice matrix (undefined for molecules/none)
+  const current_lattice_matrix = () =>
+    structure && `lattice` in structure ? structure.lattice.matrix : undefined
+  const shares_current_lattice = (matrix: Parameters<typeof lattices_match>[1]): boolean =>
+    lattices_match(current_lattice_matrix(), matrix)
+
   // 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).
+  // When the file describes the same cell as already-loaded volumes, its volumes are
+  // APPENDED (or replaced in place on re-import of the same source file) so multiple
+  // fields — e.g. density + ESP — coexist and can cross-color each other's isosurfaces.
+  // A file with a different lattice replaces the current structure and volumes.
   // Returns the parsed structure on success, or null if the file isn't a volumetric format.
-  function try_parse_volumetric(
-    text_content: string,
-    filename: string,
-  ): AnyStructure | null {
+  function try_parse_volumetric(text_content: string, filename: string): AnyStructure | null {
     const vol_result = parse_volumetric_file(text_content, filename)
     if (!vol_result) return null
+
+    const incoming = label_file_volumes(vol_result.volumes, filename)
+    const same_cell = shares_current_lattice(vol_result.structure.lattice?.matrix)
+    const added_toast = (count: number) =>
+      `Added ${count} volume${count > 1 ? `s` : ``} from ${filename}`
+
+    if (same_cell && structure) {
+      // Same cell: keep the structure and camera, only update volumes
+      if (volumetric_data?.length) {
+        // Materialize the implicit single surface into explicit layers so existing
+        // surfaces survive the transition to multi-volume mode
+        const merged = merge_imported_volumes(
+          volumetric_data,
+          materialize_layers(isosurface_settings, active_volume_idx),
+          incoming,
+          active_volume_idx,
+        )
+        volumetric_data = merged.volumes
+        isosurface_settings = { ...isosurface_settings, layers: merged.layers }
+        active_volume_idx = merged.first_touched_idx
+        show_toast(
+          merged.n_added > 0
+            ? added_toast(merged.n_added)
+            : `Reloaded volumes from ${filename}`,
+        )
+      } else if (incoming[0]) {
+        // First volumetric file for this structure
+        volumetric_data = incoming
+        isosurface_settings = auto_isosurface_settings(incoming[0].data_range)
+        active_volume_idx = 0
+        show_toast(added_toast(incoming.length))
+      }
+      return structure
+    }
+
+    // Replace: new system (or nothing loaded yet)
+    clear_camera_state()
     // parse_volumetric_file extracts structure from file header;
     // parsers set pbc so the lattice conforms to Crystal's LatticeType
     structure = vol_result.structure as AnyStructure
-    volumetric_data = vol_result.volumes
+    volumetric_data = incoming
     // Auto-compute reasonable isosurface settings from data range
-    const vol = vol_result.volumes[0]
+    const vol = incoming[0]
     if (vol) {
       isosurface_settings = auto_isosurface_settings(vol.data_range)
       active_volume_idx = 0
@@ -1112,33 +1200,36 @@
   // 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: string, filename: string): AnyStructure {
-    clear_camera_state()
     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}`)
+    // Keep loaded volumes and camera when the new structure describes the same
+    // cell (e.g. a mixed batch drop of CHGCAR + POSCAR, in either order);
+    // clear both for a genuinely new system
+    const same_cell = shares_current_lattice(
+      `lattice` in parsed ? parsed.lattice?.matrix : undefined,
+    )
+    if (!same_cell) {
+      clear_camera_state()
+      volumetric_data = []
+    }
     structure = parsed
     return parsed
   }
 
-  const handle_file_drop = create_file_drop_handler({
+  function parse_and_emit_file(content: string | ArrayBuffer, filename: string): void {
+    const text = content instanceof ArrayBuffer ? new TextDecoder().decode(content) : content
+    emit_file_load_event(parse_file_content(text, filename), filename, content)
+  }
+
+  const handle_file_drop = io.create_file_drop_handler({
     allow: () => allow_file_drop,
+    // Parse errors propagate so multi-file batches aggregate all failures into
+    // one message instead of the last error overwriting earlier ones
     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: ${
-          to_error(err).message
-        }`
-        on_error?.({ error_msg, filename })
-      }
+      parse_and_emit_file(content, filename)
     },
     on_error: (msg) => {
       error_msg = msg
@@ -1263,8 +1354,10 @@
       }
       // Duplicate selected atoms at a small offset
       if (
-        key === `d` && (event.ctrlKey || event.metaKey) &&
-        selected_sites.length > 0 && structure?.sites
+        key === `d` &&
+        (event.ctrlKey || event.metaKey) &&
+        selected_sites.length > 0 &&
+        structure?.sites
       ) {
         is_internal_edit = true
         push_undo()
@@ -1273,11 +1366,7 @@
         const new_sites = structure.sites
           .filter((_, idx) => orig_indices.has(idx))
           .map((site) => {
-            const new_xyz: Vec3 = [
-              site.xyz[0] + 0.5,
-              site.xyz[1] + 0.5,
-              site.xyz[2] + 0.5,
-            ]
+            const new_xyz: Vec3 = [site.xyz[0] + 0.5, site.xyz[1] + 0.5, site.xyz[2] + 0.5]
             return {
               ...site,
               xyz: new_xyz,
@@ -1293,9 +1382,7 @@
         // 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` : ``}`,
-        )
+        show_toast(`Duplicated ${new_sites.length} site${new_sites.length > 1 ? `s` : ``}`)
         return true
       }
 
@@ -1320,6 +1407,9 @@
     } else if (event.key === `i` && has_modifier && enable_info_pane) {
       info_pane_open = !info_pane_open
       return true
+    } else if (event.key === `g` && has_modifier && controls_config.visible(`multi-view`)) {
+      multi_view = !multi_view
+      return true
     } else if (event.key === `Escape`) {
       // Prioritize closing panes, then exit edit modes, then exit fullscreen
       if (info_pane_open) info_pane_open = false
@@ -1351,7 +1441,7 @@
   ): SvelteSet<number> {
     const result = new SvelteSet<number>()
     for (const scene_idx of scene_indices) {
-      const displayed_site = displayed_structure?.sites?.[scene_idx]
+      const displayed_site = internal_displayed_structure?.sites?.[scene_idx]
       if (!displayed_site) continue
       if (skip_image_atoms && displayed_site.properties?.orig_site_idx != null) {
         continue
@@ -1389,10 +1479,9 @@
     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 as Crystal).lattice.matrix
-      : null
-    const cart_to_frac = lattice ? create_cart_to_frac(lattice) : null
+    const lattice = `lattice` in structure ? (structure as Crystal).lattice.matrix : null
+    // get_cart_to_frac guards matrix_inverse_3x3, which throws on singular lattices
+    const cart_to_frac = get_cart_to_frac()
     const frac_to_cart = lattice ? create_frac_to_cart(lattice) : null
     structure = {
       ...structure,
@@ -1434,9 +1523,7 @@
     change_element_mode = false
     change_element_value = ``
     show_toast(
-      `Changed ${orig_indices.size} site${
-        orig_indices.size > 1 ? `s` : ``
-      } to ${elem}`,
+      `Changed ${orig_indices.size} site${orig_indices.size > 1 ? `s` : ``} to ${elem}`,
     )
   }
 
@@ -1451,29 +1538,30 @@
     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: {},
-      }],
+      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((coord) => coord.toFixed(2)).join(`, `)})`)
   }
 
   // Only set background override when background_color is explicitly provided
   $effect(() => {
-    if (typeof window !== `undefined` && wrapper && background_color) {
+    if (!wrapper) return
+    if (background_color) {
       // Convert opacity (0-1) to hex alpha value (00-FF)
       const alpha_hex = Math.round(background_opacity * 255)
         .toString(16)
         .padStart(2, `0`)
-      wrapper.style.setProperty(
-        `--struct-bg-override`,
-        `${background_color}${alpha_hex}`,
-      )
-    } else if (typeof window !== `undefined` && wrapper) {
+      wrapper.style.setProperty(`--struct-bg-override`, `${background_color}${alpha_hex}`)
+    } else {
       // Remove override to use theme system
       wrapper.style.removeProperty(`--struct-bg-override`)
     }
@@ -1497,10 +1585,10 @@
 <div
   class:dragover
   class:active={info_pane_open || controls_open || export_pane_open}
-  class:gizmo-visible={Boolean(scene_gizmo)}
+  class:gizmo-visible={viewer_active && Boolean(scene_gizmo)}
+  class:multi-view={multi_view}
   role="application"
   tabindex="0"
-  style:--canvas-cursor={canvas_cursor}
   aria-label="Structure viewer"
   bind:this={wrapper}
   bind:clientWidth={width}
@@ -1513,22 +1601,14 @@
       focused = false
     }
   }}
-  ondblclick={(event) => {
-    const target = event.target
-    if (!(target instanceof HTMLElement)) return
-    // Don't reset if double-click was on UI controls/panes/legend
-    if (
-      [`.control-buttons`, `.structure-legend`, `.atom-legend`, `.info-pane`, `.export-pane`, `.controls-pane`].some((selector) => target.closest(selector))
-      || target.tagName === `BUTTON` || target.tagName === `INPUT` || target.tagName === `SELECT`
-    ) return
-    // Reset camera for double-clicks on the 3D scene
-    reset_camera()
-  }}
   ondrop={handle_file_drop}
-  {...drag_over_handlers({ allow: () => allow_file_drop, set_dragover: (over) => dragover = over })}
+  {...io.drag_over_handlers({
+    allow: () => allow_file_drop,
+    set_dragover: (over) => (dragover = over),
+  })}
   onkeydown={handle_and_prevent(handle_keydown)}
   {...rest}
-  class="structure {rest.class ?? ``}"
+  class={[`structure`, rest.class]}
 >
   {@render children?.({ structure, fullscreen })}
   {#if loading}
@@ -1541,8 +1621,13 @@
     <StatusMessage bind:message={error_msg} type="error" dismissible />
   {:else if (structure?.sites?.length ?? 0) > 0}
     {#snippet reset_camera_btn()}
-      {#if camera_has_moved && controls_config.visible(`reset-camera`)}
-        <button class="reset-camera" onclick={reset_camera} title={reset_text}>
+      {#if any_camera_moved && controls_config.visible(`reset-camera`)}
+        <button
+          class="reset-camera"
+          onclick={reset_all_cameras}
+          title={reset_text}
+          aria-label={reset_text}
+        >
           <!-- Target/Focus icon for reset camera -->
           <Icon icon="Reset" />
         </button>
@@ -1555,20 +1640,36 @@
       fullscreen_btn_style="padding: 0 3px"
       {wrapper}
       before={reset_camera_btn}
-      style="--viewer-buttons-gap: 4pt; --viewer-buttons-btn-padding: 1px 6px; --viewer-buttons-align: stretch"
+      style="--viewer-buttons-gap: 4pt; --viewer-buttons-btn-padding: 1px 6px; --viewer-buttons-align: stretch; --viewer-buttons-hover-bg: transparent; --viewer-buttons-hover-color: light-dark(#000, #fff)"
     >
+      {#if controls_config.visible(`multi-view`)}
+        <button
+          class="multi-view-toggle"
+          class:active={multi_view}
+          onclick={() => (multi_view = !multi_view)}
+          title="Toggle multi-side view 2×2 grid (Cmd/Ctrl+G)"
+          aria-label="Toggle multi-side view"
+          aria-pressed={multi_view}
+          {@attach tooltip()}
+        >
+          <Icon icon="Grid2x2" />
+        </button>
+      {/if}
+
       {#if enable_measure_mode && controls_config.visible(`measure-mode`)}
         <div
           class="measure-mode-dropdown"
-          {@attach click_outside({ callback: () => measure_menu_open = false })}
+          {@attach click_outside({ callback: () => (measure_menu_open = false) })}
         >
           <button
             onclick={() => (measure_menu_open = !measure_menu_open)}
             title="Measure / Edit"
+            aria-label="Measure / Edit"
             class="view-mode-button"
             class:active={measure_menu_open}
             aria-expanded={measure_menu_open}
             style="transform: scale(1.2)"
+            {@attach tooltip()}
           >
             {#if show_measure_selection_limit}
               <span class="selection-limit-text">
@@ -1576,18 +1677,17 @@
               </span>
             {:else}
               <Icon
-                icon={({
-                  distance: `Ruler`,
-                  angle: `Angle`,
-                  'edit-bonds': `Link`,
-                  'edit-atoms': `Edit`,
-                } as const)[measure_mode]}
+                icon={(
+                  {
+                    distance: `Ruler`,
+                    angle: `Angle`,
+                    'edit-bonds': `Link`,
+                    'edit-atoms': `Edit`,
+                  } as const
+                )[measure_mode]}
               />
             {/if}
-            <Icon
-              icon="Arrow{measure_menu_open ? `Up` : `Down`}"
-              style="margin-left: -2px"
-            />
+            <Icon icon="Arrow{measure_menu_open ? `Up` : `Down`}" style="margin-left: -2px" />
           </button>
           {#if show_selection_reset}
             <button
@@ -1603,12 +1703,7 @@
           {/if}
           {#if measure_menu_open}
             <div class="view-mode-dropdown">
-              {#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`, label: `Edit Bonds`, scale: 1.0 },
-        ] as const as { mode, icon, label, scale } (mode)}
+              {#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`, label: `Edit Bonds`, scale: 1.0 }] as const as { mode, icon, label, scale } (mode)}
                 <button
                   class="view-mode-option"
                   class:selected={measure_mode === mode}
@@ -1629,36 +1724,43 @@
           {/if}
         </div>
 
-        <!-- Undo/redo buttons (only in edit-atoms mode) -->
-        {#if measure_mode === `edit-atoms`}
+        {#snippet undo_redo_snippet(
+          buttons: {
+            icon: `Undo` | `Redo`
+            title: string
+            stack: unknown[]
+            action: () => void
+          }[],
+        )}
           <div class="undo-redo-container">
-            <button
-              type="button"
-              aria-label="Undo (Cmd/Ctrl+Z)"
-              disabled={undo_stack.length === 0}
-              onclick={undo}
-              title="Undo (Cmd/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 (Cmd/Ctrl+Y or Cmd+Shift+Z)"
-              disabled={redo_stack.length === 0}
-              onclick={redo}
-              title="Redo (Cmd/Ctrl+Y or Cmd+Shift+Z)"
-              class="undo-redo-btn"
-            >
-              <Icon icon="Redo" />
-              {#if redo_stack.length > 0}
-                <span class="history-count">{redo_stack.length}</span>
-              {/if}
-            </button>
+            {#each buttons as { icon, title, stack, action } (icon)}
+              <button
+                type="button"
+                aria-label={title}
+                disabled={stack.length === 0}
+                onclick={action}
+                {title}
+                class="undo-redo-btn"
+              >
+                <Icon {icon} />
+                {#if stack.length > 0}
+                  <span class="history-count">{stack.length}</span>
+                {/if}
+              </button>
+            {/each}
           </div>
+        {/snippet}
+
+        {#if measure_mode === `edit-atoms`}
+          {@render undo_redo_snippet([
+            { icon: `Undo`, title: `Undo (Cmd/Ctrl+Z)`, stack: undo_stack, action: undo },
+            {
+              icon: `Redo`,
+              title: `Redo (Cmd/Ctrl+Y or Cmd+Shift+Z)`,
+              stack: redo_stack,
+              action: redo,
+            },
+          ])}
         {/if}
 
         {#if measure_mode === `edit-bonds`}
@@ -1674,10 +1776,7 @@
               </label>
             {/if}
             <div class="bond-edit-mode-toggle">
-              {#each [
-                { mode: `add`, label: `Add`, title: `Add: click two atoms` },
-                { mode: `delete`, label: `Delete`, title: `Delete: click a bond` },
-              ] as const as { mode, label, title } (mode)}
+              {#each [{ mode: `add`, label: `Add`, title: `Add: click two atoms` }, { mode: `delete`, label: `Delete`, title: `Delete: click a bond` }] as const as { mode, label, title } (mode)}
                 <button
                   type="button"
                   class:selected={bond_edit_mode === mode}
@@ -1690,34 +1789,20 @@
               {/each}
             </div>
           </div>
-          <div class="undo-redo-container">
-            <button
-              type="button"
-              aria-label="Undo bond edit (Cmd/Ctrl+Z)"
-              disabled={bond_undo_stack.length === 0}
-              onclick={undo_bond_edit}
-              title="Undo bond edit (Cmd/Ctrl+Z)"
-              class="undo-redo-btn"
-            >
-              <Icon icon="Undo" />
-              {#if bond_undo_stack.length > 0}
-                <span class="history-count">{bond_undo_stack.length}</span>
-              {/if}
-            </button>
-            <button
-              type="button"
-              aria-label="Redo bond edit (Cmd/Ctrl+Y or Cmd+Shift+Z)"
-              disabled={bond_redo_stack.length === 0}
-              onclick={redo_bond_edit}
-              title="Redo bond edit (Cmd/Ctrl+Y or Cmd+Shift+Z)"
-              class="undo-redo-btn"
-            >
-              <Icon icon="Redo" />
-              {#if bond_redo_stack.length > 0}
-                <span class="history-count">{bond_redo_stack.length}</span>
-              {/if}
-            </button>
-          </div>
+          {@render undo_redo_snippet([
+            {
+              icon: `Undo`,
+              title: `Undo bond edit (Cmd/Ctrl+Z)`,
+              stack: bond_undo_stack,
+              action: undo_bond_edit,
+            },
+            {
+              icon: `Redo`,
+              title: `Redo bond edit (Cmd/Ctrl+Y or Cmd+Shift+Z)`,
+              stack: bond_redo_stack,
+              action: redo_bond_edit,
+            },
+          ])}
         {/if}
 
         <!-- Add-atom element input (shown when add_atom_mode is active) -->
@@ -1738,8 +1823,7 @@
         {/if}
 
         <!-- Change-element input (shown when 'e' pressed with selection) -->
-        {#if measure_mode === `edit-atoms` && change_element_mode &&
-      selected_sites.length > 0}
+        {#if measure_mode === `edit-atoms` && change_element_mode && selected_sites.length > 0}
           <div class="add-atom-input">
             <label>
               <span>New element:</span>
@@ -1767,8 +1851,7 @@
         {/if}
       {/if}
 
-      {#if enable_info_pane && normalized_structure &&
-      controls_config.visible(`info-pane`)}
+      {#if enable_info_pane && normalized_structure && controls_config.visible(`info-pane`)}
         <StructureInfoPane
           structure={normalized_structure}
           bind:pane_open={info_pane_open}
@@ -1827,7 +1910,7 @@
       bind:element_radius_overrides
       bind:site_radius_overrides
       selected_sites={atom_legend_selected_sites}
-      structure={displayed_structure}
+      structure={internal_displayed_structure}
       show_mode_toggle={viewer_active}
       {sym_data}
     >
@@ -1845,60 +1928,90 @@
       {/snippet}
     </AtomLegend>
 
+    <!-- One StructureViewport renders the single view; four render the 2x2 multi-view.
+      The primary pane (index 0) carries the external camera API: scene/camera are bound
+      out for export and camera_position/target persist into scene_props, and it emits
+      on_camera_move/on_camera_reset. All camera handling itself lives in StructureViewport. -->
+    {#snippet primary_viewport(view: StructureView)}
+      <StructureViewport
+        in_grid={multi_view}
+        label={multi_view ? view.label : undefined}
+        active={multi_view && active_pane_idx === 0}
+        interactive={!multi_view || active_pane_idx === 0}
+        onactivate={() => (active_pane_idx = 0)}
+        {reset_token}
+        report_moved={(moved) => (moved ? moved_panes.add(0) : moved_panes.delete(0))}
+        {on_camera_move}
+        {on_camera_reset}
+        {...shared_viewport_props}
+        camera_direction={view.direction}
+        camera_projection={view.projection ?? scene_props.camera_projection}
+        bind:camera_position={scene_props.camera_position}
+        bind:camera_target={scene_props.camera_target}
+        bind:scene
+        bind:camera
+        bind:selected_sites
+        bind:measured_sites
+        bind:hovered_site_idx
+        bind:hidden_elements
+        bind:hidden_prop_vals
+        bind:element_radius_overrides
+        bind:site_radius_overrides
+        bind:added_bonds
+        bind:removed_bonds
+        bind:bond_order_overrides
+        bind:bond_edit_mode
+        bind:add_atom_mode
+        bind:add_element
+        bind:dragging_atoms
+        bind:polyhedra_rendered_elements
+      />
+    {/snippet}
+
+    {#snippet extra_viewport(view: StructureView, pane_idx: number)}
+      <StructureViewport
+        in_grid
+        label={view.label}
+        active={active_pane_idx === pane_idx}
+        interactive={active_pane_idx === pane_idx}
+        onactivate={() => (active_pane_idx = pane_idx)}
+        {reset_token}
+        report_moved={(moved) =>
+          moved ? moved_panes.add(pane_idx) : moved_panes.delete(pane_idx)}
+        {...shared_viewport_props}
+        camera_direction={view.direction}
+        camera_projection={view.projection ?? scene_props.camera_projection}
+        bind:selected_sites
+        bind:measured_sites
+        bind:hovered_site_idx
+        bind:hidden_elements
+        bind:hidden_prop_vals
+        bind:element_radius_overrides
+        bind:site_radius_overrides
+        bind:added_bonds
+        bind:removed_bonds
+        bind:bond_order_overrides
+        bind:bond_edit_mode
+        bind:add_atom_mode
+        bind:add_element
+        bind:dragging_atoms
+      />
+    {/snippet}
+
     <!-- 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%; width: 100%">
-        <Canvas>
-          <StructureScene
-            structure={displayed_structure}
-            base_structure={cell_transformed_structure}
-            {...scene_props}
-            gizmo={scene_gizmo}
-            {lattice_props}
-            volumetric_data={supercell_volume}
-            {isosurface_settings}
-            bind:camera_is_moving
-            bind:selected_sites
-            active_sites={active_scene_sites}
-            bind:hovered_idx={hovered_site_idx}
-            bind:measured_sites
-            bind:scene
-            bind:camera
-            bind:orbit_controls
-            bind:rotation_target_ref
-            bind:initial_computed_zoom
-            bind:hidden_elements
-            bind:hidden_prop_vals
-            bind:element_radius_overrides
-            bind:site_radius_overrides
-            bind:added_bonds
-            bind:removed_bonds
-            bind:bond_order_overrides
-            {bond_edits_enabled}
-            bind:bond_edit_mode
-            {bond_edit_order}
-            {measure_mode}
-            {width}
-            {height}
-            {atom_color_config}
-            {sym_data}
-            on_sites_moved={handle_sites_moved}
-            on_operation_start={push_undo}
-            on_bond_edit_start={push_bond_undo}
-            on_add_atom={handle_add_atom}
-            bind:add_atom_mode
-            bind:add_element
-            bind:cursor={canvas_cursor}
-            bind:dragging_atoms
-            bind:polyhedra_rendered_elements
-          />
-        </Canvas>
+      <div class:multi={multi_view} class="viewport-stage">
+        {@render primary_viewport(multi_view ? (views[0] ?? {}) : {})}
+        {#if multi_view}
+          {#each views.slice(1) as view, idx (idx)}
+            {@render extra_viewport(view, idx + 1)}
+          {/each}
+        {/if}
       </div>
     {/if}
 
     <div class="bottom-left">
-      {@render bottom_left?.({ structure: displayed_structure })}
+      {@render bottom_left?.({ structure: internal_displayed_structure })}
     </div>
 
     {#if toast_msg}
@@ -1908,9 +2021,7 @@
     {#if symmetry_error}
       <div class="symmetry-error">
         <span>{symmetry_error}</span>
-        <button onclick={() => (symmetry_error = undefined)} aria-label="Dismiss">
-          ×
-        </button>
+        <button onclick={() => (symmetry_error = undefined)} aria-label="Dismiss"> × </button>
       </div>
     {/if}
   {:else if structure}
@@ -1940,7 +2051,9 @@
     background: var(--struct-bg-fullscreen, var(--struct-bg));
     overflow: hidden;
   }
-  .structure:fullscreen :global(canvas) {
+  /* Single view: stretch the lone canvas to the full screen in fullscreen mode.
+    In multi-view the grid fills the screen and each canvas fills its 1fr cell. */
+  .structure:fullscreen:not(.multi-view) :global(canvas) {
     height: 100vh !important;
     width: 100vw !important;
   }
@@ -1948,6 +2061,22 @@
     background: var(--struct-dragover-bg, var(--dragover-bg));
     border: var(--struct-dragover-border, var(--dragover-border));
   }
+  .viewport-stage {
+    height: 100%;
+    width: 100%;
+  }
+  /* 2x2 multi-side view grid: four equal subcanvases. grid-auto-rows keeps rows
+    equal-height if a custom `views` array supplies more than four entries. */
+  .viewport-stage.multi {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    grid-template-rows: 1fr 1fr;
+    grid-auto-rows: 1fr;
+    gap: var(--struct-viewport-gap, 2px);
+  }
+  .multi-view-toggle.active {
+    color: var(--accent-color, #4a9eff);
+  }
   /* Ensure canvas is transparent so the themed --struct-bg shows through */
   .structure :global(canvas) {
     background: transparent;
@@ -1978,7 +2107,9 @@
     right: 0;
     background: var(--surface-bg);
     border-radius: var(--border-radius, 3pt);
-    box-shadow: 0 8px 16px -4px rgba(0, 0, 0, 0.3), 0 4px 8px -2px rgba(0, 0, 0, 0.1);
+    box-shadow:
+      0 8px 16px -4px rgba(0, 0, 0, 0.3),
+      0 4px 8px -2px rgba(0, 0, 0, 0.1);
     display: flex;
     flex-direction: column;
   }
@@ -2017,7 +2148,7 @@
   .measure-mode-dropdown > button {
     background: transparent;
     padding: 1px 6px;
-    font-size: clamp(0.85em, 2cqmin, 1.3em);
+    font-size: var(--ctrl-btn-icon-size, clamp(0.7rem, 2cqmin, 0.85rem));
   }
   .selection-limit-text {
     font-weight: bold;
@@ -2045,7 +2176,7 @@
     gap: 1rem;
     max-width: min(90%, 400px);
     font-size: 0.9rem;
-    z-index: 1000;
+    z-index: var(--z-index-viewer-tooltip, 1000);
   }
   .symmetry-error span {
     flex: 1;
@@ -2072,14 +2203,15 @@
     padding: 0.4rem 0.8rem;
     border-radius: var(--border-radius, 3pt);
     font-size: 0.8rem;
-    z-index: 100;
+    z-index: var(--z-index-viewer-dropdown, 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% {
+    0%,
+    70% {
       opacity: 1;
     }
     100% {