matterviz 0.4.1 → 0.4.3

package/dist/structure/bonding.js

@@ -1,8 +1,6 @@
 // Bonding algorithms for structure visualization
-import { element_data } from '../element';
+import element_data, { element_by_symbol } from '../element/data';
 import * as math from '../math';
-// Shared per-symbol element data lookup (also used by pbc.ts and polyhedra.ts)
-export const element_lookup = new Map(element_data.map((el) => [el.symbol, el]));
 const covalent_radii = new Map(element_data.flatMap((el) => el.covalent_radius === null ? [] : [[el.symbol, el.covalent_radius]]));
 // Majority-occupancy element of a (possibly disordered) site
 export const get_majority_element = (site) => {
@@ -10,12 +8,39 @@ export const get_majority_element = (site) => {
         return null;
     return site.species.reduce((max, spec) => (spec.occu > max.occu ? spec : max)).element;
 };
+// Large low-valent A-site cations whose coordination polyhedra (CN 8-12) tend to
+// obscure the structural framework. VESTA-style figures draw the framework
+// (e.g. TiO6 in BaTiO3, FeO6/PO4 in LiFePO4) and leave these as plain spheres.
+// They still get polyhedra when they are the only qualifying cations (e.g. NaCl)
+// or when force-included via `included_center_elements`. Shared by polyhedra.ts
+// (vertex/center selection) and pbc.ts (phase-2 boundary completion) so the bond
+// graph and the polyhedra it feeds stay consistent.
+const HEAVY_ALKALINE_EARTHS = new Set([`Ca`, `Sr`, `Ba`, `Ra`]);
+export const is_spectator_center = (element) => element_by_symbol.get(element)?.category === `alkali metal` ||
+    HEAVY_ALKALINE_EARTHS.has(element);
+// True if the composition contains a framework cation: a non-spectator element
+// strictly less electronegative than the most electronegative element present
+// (i.e. one that can coordinate the anions). When true, spectator A-site cations
+// are hidden from coordination polyhedra (compute_polyhedra) and skipped by phase-2
+// boundary completion (find_image_atoms) - sharing this keeps the bond graph and
+// the polyhedra it feeds consistent. Purely ionic binaries (NaCl, Li2O) return
+// false, so the spectator IS the framework and keeps its polyhedra/completions.
+export function has_framework_potential(elements) {
+    const els = [...new Set(elements)]; // dedupe so callers can pass per-site element lists
+    let max_en = -Infinity;
+    for (const el of els) {
+        const en = element_by_symbol.get(el)?.electronegativity;
+        if (en != null && en > max_en)
+            max_en = en;
+    }
+    return els.some((el) => {
+        if (is_spectator_center(el))
+            return false;
+        const en = element_by_symbol.get(el)?.electronegativity;
+        return en != null && en < max_en;
+    });
+}
 const is_zero_cell_shift = (cell_shift) => cell_shift === undefined || cell_shift.every((val) => val === 0);
-const format_cell_shift = (cell_shift) => {
-    if (cell_shift === undefined || is_zero_cell_shift(cell_shift))
-        return ``;
-    return `@${cell_shift.join(`,`)}`;
-};
 const negate_cell_shift = (cell_shift) => [
     cell_shift[0] === 0 ? 0 : -cell_shift[0],
     cell_shift[1] === 0 ? 0 : -cell_shift[1],
@@ -50,7 +75,10 @@ export const normalize_structure_bond = (site_idx_1, site_idx_2, order, cell_shi
 };
 export const get_bond_key = (idx_1, idx_2, cell_shift) => {
     const normalized = normalize_bond_endpoints(idx_1, idx_2, cell_shift);
-    return `${normalized.site_idx_1}-${normalized.site_idx_2}${format_cell_shift(normalized.cell_shift)}`;
+    const shift_suffix = normalized.cell_shift === undefined || is_zero_cell_shift(normalized.cell_shift)
+        ? ``
+        : `@${normalized.cell_shift.join(`,`)}`;
+    return `${normalized.site_idx_1}-${normalized.site_idx_2}${shift_suffix}`;
 };
 // Remap explicit bond metadata after site deletion: drop bonds touching deleted
 // sites and shift each surviving index down by the number of deleted indices below it.
@@ -247,7 +275,6 @@ export const merge_bond_edits = (base_bonds, added, removed, overrides) => {
     }
     return [...merged.values()];
 };
-const is_record = (value) => typeof value === `object` && value !== null;
 export function normalize_bond_order(order) {
     if (order === `aromatic`)
         return order;
@@ -305,13 +332,14 @@ export function get_explicit_bond_metadata(structure) {
     }
     const explicit_bonds = new Map();
     for (const [entry_idx, raw_bond] of raw_bonds.entries()) {
-        if (!is_record(raw_bond)) {
+        if (typeof raw_bond !== `object` || raw_bond === null) {
             console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: expected object`);
             continue;
         }
-        const { order } = raw_bond;
-        const site_idx_1 = raw_bond.site_idx_1;
-        const site_idx_2 = raw_bond.site_idx_2;
+        const bond_record = raw_bond;
+        const { order } = bond_record;
+        const site_idx_1 = bond_record.site_idx_1;
+        const site_idx_2 = bond_record.site_idx_2;
         if (typeof site_idx_1 !== `number` ||
             typeof site_idx_2 !== `number` ||
             !Number.isInteger(site_idx_1) ||
@@ -331,7 +359,7 @@ export function get_explicit_bond_metadata(structure) {
             console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: unsupported order ${String(order)}`);
             continue;
         }
-        const cell_shift = normalize_cell_shift(raw_bond.cell_shift);
+        const cell_shift = normalize_cell_shift(bond_record.cell_shift);
         if (cell_shift === null) {
             console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: cell_shift must be three integers`);
             continue;
@@ -340,9 +368,7 @@ export function get_explicit_bond_metadata(structure) {
             console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: endpoints match`);
             continue;
         }
-        if (cell_shift !== undefined &&
-            !is_zero_cell_shift(cell_shift) &&
-            !(`lattice` in structure)) {
+        if (!is_zero_cell_shift(cell_shift) && !(`lattice` in structure)) {
             console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: cell_shift requires a crystal lattice`);
             continue;
         }
@@ -501,11 +527,22 @@ export function compute_bond_transform(pos_1, pos_2) {
         1,
     ]);
 }
+// Build a BondPair between two sites (shared by electroneg_ratio and solid_angle)
+const make_bond = (sites, idx_1, idx_2, bond_length, strength) => ({
+    pos_1: sites[idx_1].xyz,
+    pos_2: sites[idx_2].xyz,
+    site_idx_1: idx_1,
+    site_idx_2: idx_2,
+    bond_length,
+    strength,
+    transform_matrix: compute_bond_transform(sites[idx_1].xyz, sites[idx_2].xyz),
+});
 // Pack quantized cell coordinates into one integer key (exact for cell coords in
 // [-512, 511], i.e. structures up to ~1000 cells per axis - far beyond any real
 // case). Integer Map keys avoid per-lookup string building in the hot pair loop.
+// Also used by pbc.ts for its phase-2 boundary-completion grid.
 const CELL_OFFSET = 512;
-const pack_cell_key = (x, y, z) => (x + CELL_OFFSET) * 1048576 + (y + CELL_OFFSET) * 1024 + (z + CELL_OFFSET);
+export const pack_cell_key = (x, y, z) => (x + CELL_OFFSET) * 1048576 + (y + CELL_OFFSET) * 1024 + (z + CELL_OFFSET);
 // Build spatial grid by dividing 3D space into cubic cells.
 function build_spatial_grid(sites, cell_size) {
     const grid = new Map();
@@ -520,24 +557,28 @@ function build_spatial_grid(sites, cell_size) {
     return grid;
 }
 // Get all site indices in 3x3x3 cube of cells around position.
+// Fills and returns a REUSED module-level array (valid until the next call):
+// this runs once per bond center, so per-call allocations would dominate GC
+// pressure when computing bonds for large supercells.
+const scratch_neighbors = [];
 function get_neighbors_from_grid(pos, grid, cell_size) {
     const [cx, cy, cz] = [
         Math.floor(pos[0] / cell_size),
         Math.floor(pos[1] / cell_size),
         Math.floor(pos[2] / cell_size),
     ];
-    const neighbors = [];
+    scratch_neighbors.length = 0;
     for (let dx = -1; dx <= 1; dx++) {
         for (let dy = -1; dy <= 1; dy++) {
             for (let dz = -1; dz <= 1; dz++) {
                 const cell = grid.get(pack_cell_key(cx + dx, cy + dy, cz + dz));
                 if (cell)
-                    for (const idx of cell)
-                        neighbors.push(idx);
+                    for (const site_idx of cell)
+                        scratch_neighbors.push(site_idx);
             }
         }
     }
-    return neighbors;
+    return scratch_neighbors;
 }
 // Setup spatial decomposition for structures with >50 atoms.
 function setup_spatial_grid(sites, cutoff) {
@@ -549,6 +590,23 @@ const get_candidates = (pos, sites, spatial) => spatial
     ? get_neighbors_from_grid(pos, spatial.grid, spatial.cell_size)
     : Array.from({ length: sites.length }, (_, idx) => idx);
 export const BONDING_STRATEGIES = { electroneg_ratio, solid_angle };
+// Memo for the costly neighbor search: WeakMap keyed by structure (GC'd with it), each holding a
+// per-signature (strategy + JSON options) map of results. The multi-side view's 4 panes share one
+// search (identical inputs, one flush); the per-signature map also lets alternating
+// strategies/options on the same structure reuse earlier results instead of thrashing one slot.
+const bond_memo = new WeakMap();
+export function compute_bonds(structure, strategy, options = {}) {
+    const sig = `${strategy}:${JSON.stringify(options)}`;
+    let by_sig = bond_memo.get(structure);
+    const cached = by_sig?.get(sig);
+    if (cached)
+        return cached;
+    const bonds = BONDING_STRATEGIES[strategy](structure, options);
+    if (!by_sig)
+        bond_memo.set(structure, (by_sig = new Map()));
+    by_sig.set(sig, bonds);
+    return bonds;
+}
 // Electronegativity-based bonding with chemical preferences.
 // This algorithm considers electronegativity differences between atoms, metal/nonmetal
 // properties, and distance to determine bond strength. Bonds are only created if the
@@ -561,7 +619,11 @@ metal_nonmetal_bonus = 1.5, // Strength bonus for metal-nonmetal bonds
 similar_electronegativity_bonus = 1.2, // Bonus for similar electronegativity
 same_species_penalty = 0.5, // Penalty for bonds between same element
 strength_threshold = 0.3, // Minimum bond strength to include in results
- } = {}) {
+// Only iterate the first `center_count` sites as bond centers (default: all).
+// Coordination coloring sets this to the original-atom count so appended PBC image
+// atoms are used as neighbors but not iterated as centers — identical coordination
+// for the originals (by translational symmetry), far cheaper when images dominate.
+center_count = Infinity, } = {}) {
     const { sites } = structure;
     if (sites.length < 2)
         return [];
@@ -571,6 +633,7 @@ strength_threshold = 0.3, // Minimum bond strength to include in results
     // millions of candidate pairs in large supercells, so object property chains
     // and Map lookups are replaced with indexed array reads.
     const n_sites = sites.length;
+    const n_center = Math.min(center_count, n_sites - 1);
     const electronegs = new Float64Array(n_sites);
     const radii = new Float64Array(n_sites); // 0 = no covalent radius known
     const metal_flags = new Uint8Array(n_sites);
@@ -580,7 +643,7 @@ strength_threshold = 0.3, // Minimum bond strength to include in results
     const elem_id_lookup = new Map();
     for (let idx = 0; idx < n_sites; idx++) {
         const elem = get_majority_element(sites[idx]);
-        const data = elem ? element_lookup.get(elem) : undefined;
+        const data = elem ? element_by_symbol.get(elem) : undefined;
         electronegs[idx] = data?.electronegativity ?? 2.0;
         metal_flags[idx] = data?.metal ? 1 : 0;
         nonmetal_flags[idx] = data?.nonmetal ? 1 : 0;
@@ -608,7 +671,7 @@ strength_threshold = 0.3, // Minimum bond strength to include in results
     const max_cutoff = max_radius * 2 * max_distance_ratio;
     const spatial = setup_spatial_grid(sites, max_cutoff);
     const potential_bonds = [];
-    for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
+    for (let idx_a = 0; idx_a < n_center; idx_a++) {
         const radius_a = radii[idx_a];
         if (radius_a === 0)
             continue; // no covalent radius -> no pairs (symmetric: idx_b skips too)
@@ -700,15 +763,7 @@ strength_threshold = 0.3, // Minimum bond strength to include in results
             strength *= Math.exp(-(norm_dist / closest_dist_b - 1) / 0.5);
         }
         if (strength > strength_threshold) {
-            bonds.push({
-                pos_1: sites[site_idx_1].xyz,
-                pos_2: sites[site_idx_2].xyz,
-                site_idx_1,
-                site_idx_2,
-                bond_length: dist,
-                strength,
-                transform_matrix: compute_bond_transform(sites[site_idx_1].xyz, sites[site_idx_2].xyz),
-            });
+            bonds.push(make_bond(sites, site_idx_1, site_idx_2, dist, strength));
         }
     }
     return apply_explicit_bond_metadata(structure, bonds);
@@ -718,7 +773,8 @@ strength_threshold = 0.3, // Minimum bond strength to include in results
 // This algorithm computes bond strength based on the solid angle subtended by atoms
 // and their distance penalty. Bonds are only created if the computed strength exceeds
 // the strength_threshold parameter.
-export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area = 0.05, max_distance = 5.0, min_bond_dist = 0.4, strength_threshold = 0.05, } = {}) {
+export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area = 0.05, max_distance = 5.0, min_bond_dist = 0.4, strength_threshold = 0.05, center_count = Infinity, // see electroneg_ratio: limit bond centers to first N sites
+ } = {}) {
     const { sites } = structure;
     if (sites.length < 2)
         return [];
@@ -726,7 +782,8 @@ export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area =
     const min_dist_sq = min_bond_dist ** 2;
     const max_dist_sq = max_distance ** 2;
     const spatial = setup_spatial_grid(sites, max_distance);
-    for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
+    const n_center = Math.min(center_count, sites.length - 1);
+    for (let idx_a = 0; idx_a < n_center; idx_a++) {
         const [x1, y1, z1] = sites[idx_a].xyz;
         const elem_a = get_majority_element(sites[idx_a]);
         const radius_a = elem_a ? covalent_radii.get(elem_a) : undefined;
@@ -751,15 +808,7 @@ export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area =
             const angle_strength = Math.min(bond_solid_angle / (4.0 * Math.PI), 1.0);
             const strength = angle_strength * dist_penalty;
             if (strength > strength_threshold) {
-                bonds.push({
-                    pos_1: sites[idx_a].xyz,
-                    pos_2: sites[idx_b].xyz,
-                    site_idx_1: idx_a,
-                    site_idx_2: idx_b,
-                    bond_length: dist,
-                    strength,
-                    transform_matrix: compute_bond_transform(sites[idx_a].xyz, sites[idx_b].xyz),
-                });
+                bonds.push(make_bond(sites, idx_a, idx_b, dist, strength));
             }
         }
     }

package/dist/structure/edit-history.d.ts

@@ -0,0 +1,6 @@
+export type HistoryStacks<T> = [undo_stack: T[], redo_stack: T[]];
+export declare function push_edit<T>([undo_stack]: HistoryStacks<T>, snapshot: T, max_history: number): HistoryStacks<T>;
+export declare function step_history<T>([undo_stack, redo_stack]: HistoryStacks<T>, direction: `undo` | `redo`, current: T): {
+    stacks: HistoryStacks<T>;
+    restored: T;
+} | null;

package/dist/structure/edit-history.js

@@ -0,0 +1,27 @@
+// Pure undo/redo stack mechanics for Structure.svelte's edit-atoms history.
+// Stacks are treated as immutable (updates return new arrays) so they work with
+// $state.raw holders where only reassignment is reactive. Kept free of
+// component state so the real logic (not a test-local mirror) is unit-testable.
+// Record a new edit: push `snapshot` onto the undo stack (trimming to
+// `max_history` entries) and invalidate the redo stack.
+export function push_edit([undo_stack], snapshot, max_history) {
+    const trimmed = undo_stack.length >= max_history
+        ? undo_stack.slice(undo_stack.length - max_history + 1)
+        : undo_stack;
+    return [[...trimmed, snapshot], []];
+}
+// Step the history in `direction`: pop that stack's top as the state to
+// restore, pushing `current` onto the opposite stack. Returns null when there
+// is nothing to step to (callers should snapshot `current` lazily by checking
+// stack length first if snapshots are expensive).
+export function step_history([undo_stack, redo_stack], direction, current) {
+    const source = direction === `undo` ? undo_stack : redo_stack;
+    const restored = source.at(-1);
+    if (restored === undefined)
+        return null;
+    const remaining = source.slice(0, -1);
+    const stacks = direction === `undo`
+        ? [remaining, [...redo_stack, current]]
+        : [[...undo_stack, current], remaining];
+    return { stacks, restored };
+}

package/dist/structure/export.d.ts

@@ -7,6 +7,7 @@ export declare function has_color_property(mat: Material): mat is Material & {
 export declare function extract_bond_color_for_instance(geometry: BufferGeometry, instance_idx: number): Color | null;
 export declare function clean_geometry_for_export(geometry: BufferGeometry): void;
 export declare function generate_mtl_content(scene: Scene): string;
+export declare function convert_instanced_meshes_to_regular(scene: Scene): Scene;
 export declare function create_structure_filename(structure: AnyStructure | undefined, extension: string): string;
 export declare function structure_to_xyz_str(structure?: AnyStructure): string;
 export declare function structure_to_cif_str(structure?: AnyStructure): string;

package/dist/structure/export.js

@@ -6,22 +6,15 @@ import { Color, Group, Matrix4, Mesh, MeshStandardMaterial, ShaderMaterial } fro
 import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
 import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js';
 // @internal exported only for tests - not part of the public API.
-// Type guard to check if a material has a color property (duck typing for bundler
-// compatibility across different Three.js instances - Threlte vs vanilla Three.js).
+// Type guard to check if a material has a Color-like property with numeric r/g/b
+// channels (duck typing for bundler compatibility across different Three.js
+// instances - Threlte vs vanilla Three.js).
 export function has_color_property(mat) {
-    if (!(`color` in mat))
-        return false;
     const color = mat.color;
     if (!color || typeof color !== `object`)
         return false;
-    // Check for Color-like object with numeric r/g/b channels (duck typing)
-    const color_obj = color;
-    const red_channel = color_obj.r;
-    const green_channel = color_obj.g;
-    const blue_channel = color_obj.b;
-    return (typeof red_channel === `number` &&
-        typeof green_channel === `number` &&
-        typeof blue_channel === `number`);
+    const { r: red, g: green, b: blue } = color;
+    return typeof red === `number` && typeof green === `number` && typeof blue === `number`;
 }
 // Extract color from a ShaderMaterial by checking common color uniform patterns
 function extract_shader_color(shader_mat) {
@@ -34,8 +27,8 @@ function extract_shader_color(shader_mat) {
             return uniforms[key].value.clone();
         }
     }
-    // For gradient bonds, try to extract midpoint color from instanceColorStart/End attributes
-    // These are set as geometry attributes, not uniforms, so we return a default gray
+    // Gradient bonds store colors as instanceColorStart/End geometry attributes,
+    // not uniforms — nothing to extract here (caller falls back to gray)
     return null;
 }
 // Convert ShaderMaterial to MeshStandardMaterial for export compatibility
@@ -123,9 +116,10 @@ export function generate_mtl_content(scene) {
             // Get diffuse color (main color)
             if (has_color_property(mat)) {
                 const color = mat.color;
-                lines.push(`Kd ${color.r.toFixed(6)} ${color.g.toFixed(6)} ${color.b.toFixed(6)}`);
+                const fmt = (val) => val.toFixed(6);
+                lines.push(`Kd ${fmt(color.r)} ${fmt(color.g)} ${fmt(color.b)}`);
                 // Ambient is typically a fraction of diffuse
-                lines.push(`Ka ${(color.r * 0.2).toFixed(6)} ${(color.g * 0.2).toFixed(6)} ${(color.b * 0.2).toFixed(6)}`);
+                lines.push(`Ka ${fmt(color.r * 0.2)} ${fmt(color.g * 0.2)} ${fmt(color.b * 0.2)}`);
             }
             else {
                 // Default white if no color
@@ -145,19 +139,33 @@ export function generate_mtl_content(scene) {
     });
     return lines.join(`\n`);
 }
-// Extract color from material, returning RGB values or null if not found
-function extract_material_color(mat) {
-    if (has_color_property(mat)) {
-        return { r: mat.color.r, g: mat.color.g, b: mat.color.b };
-    }
-    return null;
-}
 // Helper function to convert InstancedMesh to regular Mesh objects for export
 // This is necessary because GLB/OBJ exporters don't handle InstancedMesh properly
 // Note: Threlte's InstancedMesh sets isInstancedMesh=true but type remains "Mesh"
 // Type guard for InstancedMesh (Three.js uses isInstancedMesh property, not exposed in Object3D type)
 const is_instanced_mesh = (obj) => obj.isInstancedMesh || obj.type === `InstancedMesh`;
-function convert_instanced_meshes_to_regular(scene) {
+// Resolve the export color for one instance of an InstancedMesh. Precedence:
+// gradient bond midpoints (shader bonds), then per-instance colors on meshes
+// flagged userData.per_instance_color (atoms/arrows keep a white base material
+// and store real colors in the instanceColor buffer), then the shared material
+// color (legacy threlte-instanced meshes carry an all-white instanceColor that
+// must NOT win), then instanceColor as a last resort. null = keep default.
+function resolve_instance_material_color(instanced_mesh, instance_idx, bond_colors, stored_color) {
+    const bond_color = bond_colors?.get(instance_idx);
+    if (bond_color)
+        return bond_color;
+    const { instanceColor } = instanced_mesh;
+    const per_instance = instanceColor
+        ? new Color(instanceColor.getX(instance_idx), instanceColor.getY(instance_idx), instanceColor.getZ(instance_idx))
+        : null;
+    if (instanced_mesh.userData.per_instance_color && per_instance)
+        return per_instance;
+    if (stored_color)
+        return new Color(stored_color.r, stored_color.g, stored_color.b);
+    return per_instance;
+}
+// @internal exported only for tests - not part of the public API.
+export function convert_instanced_meshes_to_regular(scene) {
     // STEP 1: Collect material colors from ORIGINAL scene BEFORE cloning
     // This is crucial because scene.clone() may not properly preserve Threlte's material colors
     const material_colors = new Map();
@@ -187,25 +195,29 @@ function convert_instanced_meshes_to_regular(scene) {
         else {
             // Extract shared material color for atoms
             const single_mat = Array.isArray(mat) ? mat[0] : mat;
-            const color = extract_material_color(single_mat);
-            if (color) {
-                material_colors.set(mesh_id, color);
+            if (has_color_property(single_mat)) {
+                material_colors.set(mesh_id, {
+                    r: single_mat.color.r,
+                    g: single_mat.color.g,
+                    b: single_mat.color.b,
+                });
             }
         }
     });
     // STEP 2: Clone the scene
     const cloned_scene = scene.clone();
-    // STEP 3: Find all InstancedMesh objects in the cloned scene and build uuid mapping
-    const original_meshes = [];
-    const cloned_meshes = [];
-    scene.traverse((object) => {
-        if (is_instanced_mesh(object))
-            original_meshes.push(object);
-    });
-    cloned_scene.traverse((object) => {
-        if (is_instanced_mesh(object))
-            cloned_meshes.push(object);
-    });
+    // STEP 3: Find all InstancedMesh objects in original + cloned scene (same traversal
+    // order) to map cloned meshes back to their original uuid
+    const collect_instanced = (root) => {
+        const meshes = [];
+        root.traverse((object) => {
+            if (is_instanced_mesh(object))
+                meshes.push(object);
+        });
+        return meshes;
+    };
+    const original_meshes = collect_instanced(scene);
+    const cloned_meshes = collect_instanced(cloned_scene);
     // STEP 4: Convert each InstancedMesh to individual Mesh objects
     for (let mesh_idx = 0; mesh_idx < cloned_meshes.length; mesh_idx++) {
         const instanced_mesh = cloned_meshes[mesh_idx];
@@ -244,24 +256,10 @@ function convert_instanced_meshes_to_regular(scene) {
                 roughness: 0.5,
             });
             new_material.name = `material_${mesh_idx}_${idx}`;
-            // Apply the correct color
-            const bond_color = stored_bond_colors?.get(idx);
-            if (bond_color) {
-                // Bond with gradient color - use stored midpoint color
-                new_material.color.copy(bond_color);
-            }
-            else if (stored_color) {
-                // Atom with shared material color
-                new_material.color.setRGB(stored_color.r, stored_color.g, stored_color.b);
-            }
-            else if (instanced_mesh.instanceColor) {
-                // Fallback: per-instance colors from instanceColor attribute
-                const color_r = instanced_mesh.instanceColor.getX(idx);
-                const color_g = instanced_mesh.instanceColor.getY(idx);
-                const color_b = instanced_mesh.instanceColor.getZ(idx);
-                new_material.color.setRGB(color_r, color_g, color_b);
-            }
-            // If no color found, material stays default white
+            // Apply the correct color (null = no color found, material stays default white)
+            const resolved_color = resolve_instance_material_color(instanced_mesh, idx, stored_bond_colors, stored_color);
+            if (resolved_color)
+                new_material.color.copy(resolved_color);
             const mesh = new Mesh(cloned_geometry, new_material);
             // Combine base transform with instance transform
             const combined_matrix = new Matrix4();
@@ -321,26 +319,18 @@ export function create_structure_filename(structure, extension) {
     if (formula && formula !== `Unknown`) {
         safe_push(formula.replaceAll(` `, ``));
     }
-    // Add space group if available
-    if (`symmetry` in structure &&
-        structure.symmetry &&
-        typeof structure.symmetry === `object` &&
-        `space_group_symbol` in structure.symmetry) {
-        const space_group = structure.symmetry.space_group_symbol;
-        if (space_group && typeof space_group === `string`) {
-            safe_push(space_group.replaceAll(` `, ``));
-        }
-    }
-    // Add lattice system if available
-    if (`lattice` in structure &&
-        structure.lattice &&
-        typeof structure.lattice === `object` &&
-        `lattice_system` in structure.lattice) {
-        const lattice_system = structure.lattice.lattice_system;
-        if (lattice_system && typeof lattice_system === `string`) {
-            safe_push(lattice_system);
-        }
+    // Add space group and lattice system if available
+    const symmetry = `symmetry` in structure && is_plain_object(structure.symmetry)
+        ? structure.symmetry
+        : undefined;
+    if (typeof symmetry?.space_group_symbol === `string`) {
+        safe_push(symmetry.space_group_symbol.replaceAll(` `, ``));
     }
+    const lattice = `lattice` in structure && is_plain_object(structure.lattice)
+        ? structure.lattice
+        : undefined;
+    if (lattice && `lattice_system` in lattice && typeof lattice.lattice_system === `string`)
+        safe_push(lattice.lattice_system);
     // Add number of sites
     if (structure.sites?.length)
         parts.push(`${structure.sites.length}sites`);
@@ -372,9 +362,12 @@ export function structure_to_xyz_str(structure) {
     const formula = get_electro_neg_formula(structure, true);
     if (formula && formula !== `Unknown`)
         comment_parts.push(formula);
+    const lattice_matrix = `lattice` in structure && structure.lattice?.matrix?.length === 3
+        ? structure.lattice.matrix
+        : null;
     // Include extended XYZ lattice information when available so round-trips preserve lattice
-    if (`lattice` in structure && structure.lattice?.matrix?.length === 3) {
-        const lattice_values = structure.lattice.matrix
+    if (lattice_matrix) {
+        const lattice_values = lattice_matrix
             .flatMap((row) => row.map((value) => (Number.isFinite(value) ? value : 0).toFixed(8)))
             .join(` `);
         comment_parts.push(`Lattice="${lattice_values}"`);
@@ -382,9 +375,7 @@ export function structure_to_xyz_str(structure) {
     const comment = comment_parts.length > 0 ? comment_parts.join(` `) : `Generated from structure`;
     lines.push(comment);
     // Cache converter for fractional→Cartesian (if lattice available)
-    const frac_to_cart = `lattice` in structure && structure.lattice?.matrix?.length === 3
-        ? math.create_frac_to_cart(structure.lattice.matrix)
-        : null;
+    const frac_to_cart = lattice_matrix ? math.create_frac_to_cart(lattice_matrix) : null;
     // Atom lines: element symbol followed by x, y, z coordinates
     for (const site of structure.sites) {
         const element_symbol = site_element(site);
@@ -456,21 +447,14 @@ export function structure_to_cif_str(structure) {
     }
     const lines = [];
     // CIF header with data block (required by pymatgen and CIF spec)
-    lines.push(`# CIF file generated by MatterViz`);
-    const block_name = get_cif_block_name(structure);
-    lines.push(`data_${block_name}`);
-    lines.push(``);
+    lines.push(`# CIF file generated by MatterViz`, `data_${get_cif_block_name(structure)}`, ``);
     // Cell parameters
     const lattice = structure.lattice;
     if (lattice.a && lattice.b && lattice.c) {
-        lines.push(`_cell_length_a ${lattice.a.toFixed(6)}`);
-        lines.push(`_cell_length_b ${lattice.b.toFixed(6)}`);
-        lines.push(`_cell_length_c ${lattice.c.toFixed(6)}`);
+        lines.push(`_cell_length_a ${lattice.a.toFixed(6)}`, `_cell_length_b ${lattice.b.toFixed(6)}`, `_cell_length_c ${lattice.c.toFixed(6)}`);
     }
     if (lattice.alpha && lattice.beta && lattice.gamma) {
-        lines.push(`_cell_angle_alpha ${lattice.alpha.toFixed(6)}`);
-        lines.push(`_cell_angle_beta ${lattice.beta.toFixed(6)}`);
-        lines.push(`_cell_angle_gamma ${lattice.gamma.toFixed(6)}`);
+        lines.push(`_cell_angle_alpha ${lattice.alpha.toFixed(6)}`, `_cell_angle_beta ${lattice.beta.toFixed(6)}`, `_cell_angle_gamma ${lattice.gamma.toFixed(6)}`);
     }
     // Space group information
     if (`symmetry` in structure && is_plain_object(structure.symmetry)) {
@@ -489,13 +473,7 @@ export function structure_to_cif_str(structure) {
     // full P1 list, so without it parsers would re-apply the H-M ops and multiply sites
     lines.push(`loop_`, `_symmetry_equiv_pos_as_xyz`, `  'x, y, z'`, ``);
     // Atom site loop header
-    lines.push(`loop_`);
-    lines.push(`_atom_site_label`);
-    lines.push(`_atom_site_type_symbol`);
-    lines.push(`_atom_site_fract_x`);
-    lines.push(`_atom_site_fract_y`);
-    lines.push(`_atom_site_fract_z`);
-    lines.push(`_atom_site_occupancy`);
+    lines.push(`loop_`, `_atom_site_label`, `_atom_site_type_symbol`, `_atom_site_fract_x`, `_atom_site_fract_y`, `_atom_site_fract_z`, `_atom_site_occupancy`);
     // Cache inverse transpose for Cartesian→fractional conversion (avoids recomputing per site)
     const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
     // Atom sites: one row per species entry so disordered (multi-species) sites
@@ -536,11 +514,10 @@ export function structure_to_poscar_str(structure) {
     lines.push(`1.0`); // Scale factor (1.0 for direct coordinates)
     const lattice = structure.lattice;
     if (lattice.matrix && Array.isArray(lattice.matrix) && lattice.matrix.length >= 3) {
-        // Convert 3x3 matrix to 3 vectors
-        const matrix = lattice.matrix;
-        lines.push(`${matrix[0][0].toFixed(8)} ${matrix[0][1].toFixed(8)} ${matrix[0][2].toFixed(8)}`);
-        lines.push(`${matrix[1][0].toFixed(8)} ${matrix[1][1].toFixed(8)} ${matrix[1][2].toFixed(8)}`);
-        lines.push(`${matrix[2][0].toFixed(8)} ${matrix[2][1].toFixed(8)} ${matrix[2][2].toFixed(8)}`);
+        // One line per lattice vector, exactly 3 components at 8-decimal fixed precision
+        for (const vec of lattice.matrix.slice(0, 3)) {
+            lines.push([vec[0], vec[1], vec[2]].map((coord) => coord.toFixed(8)).join(` `));
+        }
     }
     else {
         throw new Error(`No valid lattice matrix for POSCAR export`);
@@ -572,16 +549,23 @@ export function structure_to_poscar_str(structure) {
     for (const group of sites_by_element.values()) {
         for (const site of group) {
             const frac_coords = get_frac_coords(site, cart_to_frac);
-            let selective_dynamics_str = ``;
+            const coords_str = frac_coords
+                .slice(0, 3)
+                .map((coord) => coord.toFixed(8))
+                .join(` `);
+            let sel_dyn_str = ``;
             if (has_selective_dynamics) {
                 const sel_dyn = (site.properties?.selective_dynamics ?? [
                     true,
                     true,
                     true,
                 ]);
-                selective_dynamics_str = ` ${sel_dyn[0] ? `T` : `F`} ${sel_dyn[1] ? `T` : `F`} ${sel_dyn[2] ? `T` : `F`}`;
+                sel_dyn_str = ` ${sel_dyn
+                    .slice(0, 3)
+                    .map((flag) => (flag ? `T` : `F`))
+                    .join(` `)}`;
             }
-            lines.push(`${frac_coords[0].toFixed(8)} ${frac_coords[1].toFixed(8)} ${frac_coords[2].toFixed(8)}${selective_dynamics_str}`);
+            lines.push(`${coords_str}${sel_dyn_str}`);
         }
     }
     return lines.join(`\n`);

package/dist/structure/format-detect.d.ts

@@ -0,0 +1 @@
+export declare function is_structure_file(filename: string): boolean;