matterviz 0.4.1 → 0.4.2

package/dist/structure/atom-properties.js

@@ -1,12 +1,21 @@
 // Utility functions for computing atom properties and applying color scales
 import { get_d3_interpolator } from '../colors';
-import { calc_coordination_nums } from '../coordination';
+import { calc_coordination_nums, } from '../coordination/calc-coordination';
 import * as math from '../math';
-import { wrap_to_unit_cell } from './pbc';
+import { element_lookup, get_majority_element } from './bonding';
+import { wrap_frac_coord } from './pbc';
 import { rgb } from 'd3-color';
 import * as d3_sc from 'd3-scale-chromatic';
 const GRAY = `#808080`;
 const DEFAULT_COLOR_SCALE = `interpolateViridis`;
+// Cap on periodic image shells per axis when expanding for coordination. Guards
+// against image explosion in very thin / highly oblique cells (coordination is ~O(n²)).
+const MAX_IMAGE_SHELLS = 3;
+// Max bond distance each strategy can form, mirroring the defaults in bonding.ts
+// (electroneg_ratio.max_distance_ratio, solid_angle.max_distance). Used to size PBC
+// image expansion just tightly enough that coordination never misses a bonded neighbor.
+const ELECTRONEG_MAX_RATIO = 2;
+const SOLID_ANGLE_MAX_DIST = 5; // Å
 export const get_d3_color_scales = () => Object.keys(d3_sc).filter((key) => key.startsWith(`interpolate`));
 const to_hex = (interp_fn, frac) => rgb(interp_fn(frac)).formatHex();
 const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
@@ -22,12 +31,6 @@ const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
         properties: { ...site.properties, orig_site_idx: orig_idx },
     };
 };
-const get_all_offsets = (pbc) => [-1, 0, 1]
-    .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
-    .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
-    (pbc[0] || dx === 0) &&
-    (pbc[1] || dy === 0) &&
-    (pbc[2] || dz === 0));
 const make_categorical = (vals, scale, sort_fn) => {
     const interp_fn = get_d3_interpolator(scale);
     const uniq = sort_fn
@@ -75,46 +78,109 @@ export const get_orig_site_idx = (site, site_idx) => typeof site?.properties?.or
     : typeof site?.properties?.orig_site_idx === `number`
         ? site.properties.orig_site_idx
         : site_idx;
-// Expand structure with PBC images - use minimal expansion based on atom positions
-function expand_structure_for_pbc(structure) {
+// Expand a periodic structure with the neighbor images needed for correct
+// coordination. Each atom's `reach` (the largest bond `strategy` can form for it —
+// electroneg_ratio's (r + r_max)·ratio or solid_angle's flat cap) sizes how many whole
+// cells to image per periodic axis, measured over the perpendicular cell height (not
+// the lattice vector length, so oblique cells work), keeping only images within `reach`
+// of the [0,1] cell and capping at MAX_IMAGE_SHELLS/axis (warns + may undercount beyond
+// that — near-degenerate cells only). Smaller atoms image less; atoms with no covalent
+// radius form no bonds and get no images.
+function expand_structure_for_pbc(structure, strategy) {
     if (!(`lattice` in structure) || !structure.lattice || structure.sites.length === 0) {
         return structure;
     }
     const { sites, lattice } = structure;
-    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
     const pbc = lattice.pbc ?? [true, true, true];
-    const all_offsets = get_all_offsets(pbc);
-    // Small structures: expand all atoms
-    if (sites.length < 20 || !pbc.some(Boolean)) {
-        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx)));
-        return { ...structure, sites: [...sites, ...image_sites] };
-    }
-    // Large structures: only expand atoms near boundaries (within 5Å bond distance)
-    const cutoff = [5.0 / lattice.a, 5.0 / lattice.b, 5.0 / lattice.c];
-    const image_sites = sites.flatMap((site, orig_idx) => {
-        const norm = wrap_to_unit_cell(site.abc);
-        return all_offsets
-            .filter(([dx, dy, dz]) => (dx === 0 || (dx === -1 ? norm[0] <= cutoff[0] : norm[0] >= 1 - cutoff[0])) &&
-            (dy === 0 || (dy === -1 ? norm[1] <= cutoff[1] : norm[1] >= 1 - cutoff[1])) &&
-            (dz === 0 || (dz === -1 ? norm[2] <= cutoff[2] : norm[2] >= 1 - cutoff[2])))
-            .map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx));
+    if (!pbc.some(Boolean))
+        return structure;
+    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
+    // Wrap into [0,1) along PERIODIC axes only so the near-cell filter and image
+    // building share one position (else boundary atoms image on the wrong side and lose
+    // neighbors). Vacuum axes keep their real coord — wrapping would fold apart atoms
+    // together and invent bonds.
+    const cell_sites = sites.map((site) => {
+        const abc = site.abc.map((coord, axis) => pbc[axis] ? wrap_frac_coord(coord) : coord);
+        return { ...site, abc, xyz: frac_to_cart(abc) };
     });
-    return { ...structure, sites: [...sites, ...image_sites] };
+    // Covalent radius per atom (0 = unknown → forms no bonds → needs no images)
+    const radii = cell_sites.map((site) => {
+        const elem = get_majority_element(site);
+        return (elem ? element_lookup.get(elem)?.covalent_radius : undefined) ?? 0;
+    });
+    let max_radius = 0;
+    for (const radius of radii)
+        if (radius > max_radius)
+            max_radius = radius;
+    const reach_of = (radius) => strategy === `solid_angle`
+        ? SOLID_ANGLE_MAX_DIST
+        : (radius + max_radius) * ELECTRONEG_MAX_RATIO;
+    const heights = math.cell_heights(lattice.matrix);
+    // Axes we image along: periodic and non-degenerate (finite height). Non-live axes
+    // (vacuum or degenerate) contribute no images — 0 shells + ∞ cutoff so their only
+    // copy (shift 0) always passes the near-cell filter. Loop-invariant, so hoisted out.
+    const live_axis = heights.map((height, axis) => pbc[axis] && Number.isFinite(height));
+    const image_near_cell = (frac, shift, axis_cutoff) => {
+        const shifted = frac + shift;
+        return shifted >= -axis_cutoff && shifted <= 1 + axis_cutoff;
+    };
+    let capped = false;
+    const image_sites = [];
+    for (const [orig_idx, site] of cell_sites.entries()) {
+        const radius = radii[orig_idx];
+        if (radius === 0)
+            continue; // no covalent radius → no bonds → no images
+        const reach = reach_of(radius);
+        // `cutoff` = fractional reach for the near-cell filter (keep an image shifted by `s`
+        // iff abc+s lands within `cutoff` of [0,1]); `n_shells` bounds the loop so no
+        // in-reach copy is missed.
+        const cutoff = heights.map((height, axis) => (live_axis[axis] ? reach / height : Infinity));
+        const n_shells = heights.map((height, axis) => {
+            if (!live_axis[axis])
+                return 0;
+            const shells = Math.floor(1 + reach / height);
+            if (shells > MAX_IMAGE_SHELLS)
+                capped = true;
+            return Math.min(MAX_IMAGE_SHELLS, shells);
+        });
+        const [frac_a, frac_b, frac_c] = site.abc; // periodic axes wrapped into [0, 1)
+        for (let dx = -n_shells[0]; dx <= n_shells[0]; dx++) {
+            if (!image_near_cell(frac_a, dx, cutoff[0]))
+                continue;
+            for (let dy = -n_shells[1]; dy <= n_shells[1]; dy++) {
+                if (!image_near_cell(frac_b, dy, cutoff[1]))
+                    continue;
+                for (let dz = -n_shells[2]; dz <= n_shells[2]; dz++) {
+                    if (dx === 0 && dy === 0 && dz === 0)
+                        continue;
+                    if (!image_near_cell(frac_c, dz, cutoff[2]))
+                        continue;
+                    image_sites.push(build_image_site(site, frac_to_cart, [dx, dy, dz], orig_idx));
+                }
+            }
+        }
+    }
+    if (capped) {
+        console.warn(`[coordination] cell is very thin or oblique relative to bond reach; capping ` +
+            `PBC images at ${MAX_IMAGE_SHELLS} shells/axis, coordination near cell ` +
+            `boundaries may be undercounted`);
+    }
+    return { ...structure, sites: [...cell_sites, ...image_sites] };
 }
-export function get_coordination_colors(structure, strategy = `electroneg_ratio`, scale = DEFAULT_COLOR_SCALE, type = `continuous`) {
-    const orig_site_count = structure.sites.length;
-    // Check if structure has periodic boundary conditions
+// PBC-aware coordination: expand periodic cells with image atoms (so boundary atoms get
+// full coordination), counting only original atoms as centers. Shared by the 3D viewer and
+// CoordinationBarPlot so both report identical numbers.
+export function calc_structure_coordination(structure, strategy = `electroneg_ratio`) {
     const has_lattice = `lattice` in structure && structure.lattice !== undefined;
     const pbc = has_lattice ? structure.lattice.pbc : undefined;
     const has_pbc = has_lattice && (pbc === undefined || pbc.some(Boolean));
-    // For PBC structures, expand with images from neighboring cells for accurate coordination
-    const coord_structure = has_pbc ? expand_structure_for_pbc(structure) : structure;
-    // Calculate coordination numbers on the (potentially expanded) structure
-    const all_coord_data = calc_coordination_nums(coord_structure, strategy);
-    // Extract coordination numbers only for the original sites (not image atoms)
-    const coord_nums = all_coord_data.sites
-        .slice(0, orig_site_count)
-        .map((site) => site.coordination_num);
+    // Image atoms still count as neighbors but aren't iterated as centers (big speedup)
+    const coord_structure = has_pbc ? expand_structure_for_pbc(structure, strategy) : structure;
+    return calc_coordination_nums(coord_structure, strategy, structure.sites.length);
+}
+export function get_coordination_colors(structure, strategy = `electroneg_ratio`, scale = DEFAULT_COLOR_SCALE, type = `continuous`) {
+    // sites is already limited to the original atoms (calc_coordination_nums center_count)
+    const coord_nums = calc_structure_coordination(structure, strategy).sites.map((site) => site.coordination_num);
     const { colors, unique_values } = apply_color_scale(coord_nums, scale, type);
     return build_prop_colors(coord_nums, colors, unique_values);
 }

package/dist/structure/bonding.d.ts

@@ -1,8 +1,10 @@
 import type { ElementSymbol } from '../element';
 import type { Vec3 } from '../math';
 import type { AnyStructure, BondOrder, BondPair, Site, StructureBond } from './';
-export declare const element_lookup: Map<"S" | "K" | "B" | "H" | "He" | "Li" | "Be" | "C" | "N" | "O" | "F" | "Ne" | "Na" | "Mg" | "Al" | "Si" | "P" | "Cl" | "Ar" | "Ca" | "Sc" | "Ti" | "V" | "Cr" | "Mn" | "Fe" | "Co" | "Ni" | "Cu" | "Zn" | "Ga" | "Ge" | "As" | "Se" | "Br" | "Kr" | "Rb" | "Sr" | "Y" | "Zr" | "Nb" | "Mo" | "Tc" | "Ru" | "Rh" | "Pd" | "Ag" | "Cd" | "In" | "Sn" | "Sb" | "Te" | "I" | "Xe" | "Cs" | "Ba" | "La" | "Ce" | "Pr" | "Nd" | "Pm" | "Sm" | "Eu" | "Gd" | "Tb" | "Dy" | "Ho" | "Er" | "Tm" | "Yb" | "Lu" | "Hf" | "Ta" | "W" | "Re" | "Os" | "Ir" | "Pt" | "Au" | "Hg" | "Tl" | "Pb" | "Bi" | "Po" | "At" | "Rn" | "Fr" | "Ra" | "Ac" | "Th" | "Pa" | "U" | "Np" | "Pu" | "Am" | "Cm" | "Bk" | "Cf" | "Es" | "Fm" | "Md" | "No" | "Lr" | "Rf" | "Db" | "Sg" | "Bh" | "Hs" | "Mt" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", import("../element").ChemicalElement>;
+export declare const element_lookup: Map<"Ac" | "Ag" | "Al" | "Am" | "Ar" | "As" | "At" | "Au" | "B" | "Ba" | "Be" | "Bh" | "Bi" | "Bk" | "Br" | "C" | "Ca" | "Cd" | "Ce" | "Cf" | "Cl" | "Cm" | "Co" | "Cr" | "Cs" | "Cu" | "Db" | "Dy" | "Er" | "Es" | "Eu" | "F" | "Fe" | "Fm" | "Fr" | "Ga" | "Gd" | "Ge" | "H" | "He" | "Hf" | "Hg" | "Ho" | "Hs" | "I" | "In" | "Ir" | "K" | "Kr" | "La" | "Li" | "Lr" | "Lu" | "Md" | "Mg" | "Mn" | "Mo" | "Mt" | "N" | "Na" | "Nb" | "Nd" | "Ne" | "Ni" | "No" | "Np" | "O" | "Os" | "P" | "Pa" | "Pb" | "Pd" | "Pm" | "Po" | "Pr" | "Pt" | "Pu" | "Ra" | "Rb" | "Re" | "Rf" | "Rh" | "Rn" | "Ru" | "S" | "Sb" | "Sc" | "Se" | "Sg" | "Si" | "Sm" | "Sn" | "Sr" | "Ta" | "Tb" | "Tc" | "Te" | "Th" | "Ti" | "Tl" | "Tm" | "U" | "V" | "W" | "Xe" | "Y" | "Yb" | "Zn" | "Zr" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", import("../element").ChemicalElement>;
 export declare const get_majority_element: (site: Site | undefined) => ElementSymbol | null;
+export declare const is_spectator_center: (element: string) => boolean;
+export declare function has_framework_potential(elements: Iterable<string>): boolean;
 export declare const normalize_structure_bond: (site_idx_1: number, site_idx_2: number, order: BondOrder, cell_shift?: Vec3) => StructureBond;
 export declare const get_bond_key: (idx_1: number, idx_2: number, cell_shift?: Vec3) => string;
 export declare function remap_bonds_after_deletion(bonds: readonly StructureBond[], deleted_indices: ReadonlySet<number>): StructureBond[];
@@ -39,12 +41,14 @@ export declare function apply_explicit_bond_metadata(structure: AnyStructure, bo
 export declare function scale_and_offset_bond_matrix(transform_matrix: Float32Array, offset: number, radius_scale: number): Float32Array;
 export declare function get_bond_render_matrices(bond: BondPair, bond_thickness: number): Float32Array[];
 export declare function compute_bond_transform(pos_1: Vec3, pos_2: Vec3): Float32Array;
+export declare const pack_cell_key: (x: number, y: number, z: number) => number;
 export declare const BONDING_STRATEGIES: {
     readonly electroneg_ratio: typeof electroneg_ratio;
     readonly solid_angle: typeof solid_angle;
 };
 export type BondingStrategy = keyof typeof BONDING_STRATEGIES;
 export type BondingAlgo = (typeof BONDING_STRATEGIES)[BondingStrategy];
+export declare function compute_bonds(structure: AnyStructure, strategy: BondingStrategy, options?: Record<string, unknown>): BondPair[];
 export declare function electroneg_ratio(structure: AnyStructure, { electronegativity_threshold, // Max electronegativity difference for bonding
 max_distance_ratio, // Max distance as multiple of sum of covalent radii
 min_bond_dist, // Minimum bond distance in Angstroms
@@ -52,7 +56,8 @@ metal_metal_penalty, // Strength penalty for metal-metal bonds
 metal_nonmetal_bonus, // Strength bonus for metal-nonmetal bonds
 similar_electronegativity_bonus, // Bonus for similar electronegativity
 same_species_penalty, // Penalty for bonds between same element
-strength_threshold, }?: {
+strength_threshold, // Minimum bond strength to include in results
+center_count, }?: {
     electronegativity_threshold?: number | undefined;
     max_distance_ratio?: number | undefined;
     min_bond_dist?: number | undefined;
@@ -61,12 +66,14 @@ strength_threshold, }?: {
     similar_electronegativity_bonus?: number | undefined;
     same_species_penalty?: number | undefined;
     strength_threshold?: number | undefined;
+    center_count?: number | undefined;
 }): BondPair[];
-export declare function solid_angle(structure: AnyStructure, { min_solid_angle, min_face_area, max_distance, min_bond_dist, strength_threshold, }?: {
+export declare function solid_angle(structure: AnyStructure, { min_solid_angle, min_face_area, max_distance, min_bond_dist, strength_threshold, center_count, }?: {
     min_solid_angle?: number | undefined;
     min_face_area?: number | undefined;
     max_distance?: number | undefined;
     min_bond_dist?: number | undefined;
     strength_threshold?: number | undefined;
+    center_count?: number | undefined;
 }): BondPair[];
 export {};

package/dist/structure/bonding.js

@@ -1,5 +1,5 @@
 // Bonding algorithms for structure visualization
-import { element_data } from '../element';
+import { default as element_data } 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]));
@@ -10,6 +10,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 SPECTATOR_CATEGORIES = new Set([`alkali metal`]);
+const HEAVY_ALKALINE_EARTHS = new Set([`Ca`, `Sr`, `Ba`, `Ra`]);
+export const is_spectator_center = (element) => SPECTATOR_CATEGORIES.has(element_lookup.get(element)?.category ?? ``) ||
+    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_lookup.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_lookup.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))
@@ -501,11 +534,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 +564,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 +597,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 +626,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 +640,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);
@@ -608,7 +678,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 +770,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 +780,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 +789,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 +815,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

@@ -123,9 +123,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
@@ -157,7 +158,28 @@ function extract_material_color(mat) {
 // 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();
@@ -244,24 +266,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();
@@ -372,9 +380,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 +393,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);
@@ -536,11 +545,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`);

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

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

package/dist/structure/format-detect.js

@@ -0,0 +1,22 @@
+import { CONFIG_DIRS_REGEX, STRUCT_KEYWORDS_REGEX, STRUCT_KEYWORDS_STRICT_REGEX, STRUCTURE_EXTENSIONS_REGEX, TRAJ_KEYWORDS_REGEX, VASP_FILES_REGEX, } from '../constants';
+import { strip_compression_extensions } from '../io/decompress';
+// Filename-only detection lives apart from the parsers so lightweight callers
+// (desktop recents, file pickers) do not load YAML, structure math, and element
+// data just to choose an icon.
+export function is_structure_file(filename) {
+    const name = strip_compression_extensions(filename);
+    if (/\.(?:traj|xtc|h5|hdf5)$/i.test(name) || /xdatcar/i.test(name))
+        return false;
+    if (STRUCTURE_EXTENSIONS_REGEX.test(name) || VASP_FILES_REGEX.test(name))
+        return true;
+    if (/\.(?:xyz|extxyz)$/i.test(name))
+        return !TRAJ_KEYWORDS_REGEX.test(name);
+    if (/\.(?:yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name))
+        return true;
+    if (/\.json$/i.test(name) &&
+        STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
+        !TRAJ_KEYWORDS_REGEX.test(name) &&
+        !CONFIG_DIRS_REGEX.test(name))
+        return true;
+    return false;
+}