matterviz 0.4.0 → 0.4.2

package/dist/structure/parse.js

@@ -1,14 +1,72 @@
-import { COMPRESSION_EXTENSIONS_REGEX, CONFIG_DIRS_REGEX, STRUCT_KEYWORDS_REGEX, STRUCT_KEYWORDS_STRICT_REGEX, STRUCTURE_EXTENSIONS_REGEX, TRAJ_KEYWORDS_REGEX, VASP_FILES_REGEX, XYZ_EXTXYZ_REGEX, } from '../constants';
-import { ELEM_SYMBOLS } from '../labels';
+import { XYZ_EXTXYZ_REGEX } from '../constants';
+import { FALLBACK_ELEMENTS, is_elem_symbol } from '../element/helpers';
+import { strip_compression_extensions } from '../io/decompress';
 import * as math from '../math';
 import { wrap_to_unit_cell } from './pbc';
-import { normalize_scientific_notation } from '../utils';
+import { make_site } from './site';
+import { is_xyz_atom_line, iter_xyz_frames } from '../trajectory/helpers';
+import { normalize_scientific_notation, parse_leading_num, parse_num_token, to_error, } from '../utils';
 import { load as yaml_load } from 'js-yaml';
+export { is_structure_file } from './format-detect';
+// === Parse error contract ===
+// Individual format parsers (parse_poscar, parse_cif, parse_xyz, parse_phonopy_yaml,
+// parse_optimade_json, ...) return `T | null` on failure and record failure reasons in a
+// module-level collector (mirrored to the console). The top-level entry points
+// parse_structure_file and parse_any_structure reset the collector on entry and THROW a
+// descriptive Error aggregating the recorded reasons when nothing parses, so failure
+// causes can reach the UI (callers surface error.message). Warnings (element-symbol
+// fallbacks, skipped atoms, ...) never fail a parse and only go to the console.
+let parse_errors = [];
+const reset_parse_diagnostics = () => {
+    parse_errors = [];
+};
+// Record a failure reason; with `error` present, logs in `console.error('msg:', error)` form
+const diag_error = (message, error) => {
+    const detail = error === undefined ? `` : `: ${to_error(error).message}`;
+    parse_errors.push(`${message}${detail}`);
+    if (error === undefined)
+        console.error(message);
+    else
+        console.error(`${message}:`, error);
+};
+const diag_warn = (message) => console.warn(message);
+// Aggregate recorded failure reasons into the Error thrown by top-level entry points
+const aggregate_parse_error = (filename) => {
+    const reasons = [...new Set(parse_errors)];
+    const detail = reasons.length ? `: ${reasons.join(`; `)}` : ``;
+    return new Error(`Failed to parse structure${filename ? ` from '${filename}'` : ``}${detail}`);
+};
 const cif_coords_key = (coords) => `${coords[0].toFixed(6)},${coords[1].toFixed(6)},${coords[2].toFixed(6)}`;
 const cif_site_key = (element, abc, label) => `${element}|${label}|${cif_coords_key(abc)}`;
-const clone_structure_properties = (properties) => structuredClone(properties);
-const FALLBACK_ELEMENTS = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`];
-const is_known_element_symbol = (symbol) => ELEM_SYMBOLS.includes(symbol);
+// Bravais lattice centering translations (excluding the identity) keyed by the
+// leading letter of a space-group Hermann-Mauguin symbol. R is the obverse
+// hexagonal setting.
+const CENTERING_VECTORS = {
+    P: [],
+    I: [[0.5, 0.5, 0.5]],
+    F: [
+        [0, 0.5, 0.5],
+        [0.5, 0, 0.5],
+        [0.5, 0.5, 0],
+    ],
+    A: [[0, 0.5, 0.5]],
+    B: [[0.5, 0, 0.5]],
+    C: [[0.5, 0.5, 0]],
+    R: [
+        [2 / 3, 1 / 3, 1 / 3],
+        [1 / 3, 2 / 3, 2 / 3],
+    ],
+};
+// Detect the centering letter from a CIF's space-group H-M symbol, if present.
+const extract_cif_centering = (text) => {
+    for (const line of text.split(`\n`)) {
+        const match = /^_(?:symmetry_space_group_name_h-m|space_group_name_h-m(?:_alt)?)\s+(?<symbol>.+)/i.exec(line.trim());
+        const letter = match?.groups?.symbol.replaceAll(/['"]/g, ``).trim()[0]?.toUpperCase();
+        if (letter && letter in CENTERING_VECTORS)
+            return letter;
+    }
+    return null;
+};
 const vec3_from_values = (values, context) => {
     if (values?.length !== 3) {
         throw new Error(`Invalid ${context}: expected 3 coordinates, got ${values?.length ?? 0}`);
@@ -27,7 +85,7 @@ const vec3_from_values = (values, context) => {
 // Parse a coordinate value that might be in various scientific notation formats
 function parse_coordinate(str) {
     const normalized = normalize_scientific_notation(str.trim());
-    const value = parseFloat(normalized);
+    const value = Number(normalized);
     if (isNaN(value))
         throw new Error(`Invalid coordinate value: ${str}`);
     return value;
@@ -41,9 +99,9 @@ function parse_coordinate_line(line) {
         const sanitized = line
             .trim()
             // Add space when '-' follows a digit and precedes a digit or dot
-            .replaceAll(/(\d)-(?=[\d.])/g, `$1 -`)
+            .replaceAll(/(?<digit>\d)-(?=[\d.])/g, `$1 -`)
             // Revert accidental spaces after exponent markers
-            .replaceAll(/([eE])\s-\s/g, `$1-`);
+            .replaceAll(/(?<exp_marker>[eE])\s-\s/g, `$1-`);
         tokens = sanitized.split(/\s+/);
     }
     if (tokens.length < 3)
@@ -54,11 +112,11 @@ function parse_coordinate_line(line) {
 function validate_element_symbol(symbol, index) {
     // Clean symbol (remove suffixes like _pv, /hash)
     const clean_symbol = symbol.split(/[_/]/)[0];
-    if (is_known_element_symbol(clean_symbol))
+    if (is_elem_symbol(clean_symbol))
         return clean_symbol;
     // Fallback to default elements by atomic number
     const fallback = FALLBACK_ELEMENTS[index % FALLBACK_ELEMENTS.length] ?? `H`;
-    console.warn(`Invalid element symbol '${symbol}', using fallback '${fallback}'`);
+    diag_warn(`Invalid element symbol '${symbol}', using fallback '${fallback}'`);
     return fallback;
 }
 // Per OPTIMADE spec, species_at_sites holds species NAMES (e.g. 'Si1') resolved via the
@@ -70,7 +128,7 @@ function resolve_optimade_element(species_name, species_list, index) {
     const spec = species_list?.find((entry) => entry.name === species_name);
     let best;
     for (const [sym_idx, symbol] of (spec?.chemical_symbols ?? []).entries()) {
-        if (!is_known_element_symbol(symbol))
+        if (!is_elem_symbol(symbol))
             continue;
         const conc = spec?.concentration?.[sym_idx] ?? 0;
         if (!best || conc > best.conc)
@@ -81,37 +139,51 @@ function resolve_optimade_element(species_name, species_list, index) {
     // Fallback: the name may be an element with a trailing atom index (e.g. 'O1');
     // element symbols never contain digits, so stripping them is safe
     const stripped = species_name.replace(/\d+$/, ``);
-    if (is_known_element_symbol(stripped))
+    if (is_elem_symbol(stripped))
         return { symbol: stripped, sym_idx: -1 };
     return { symbol: validate_element_symbol(species_name, index), sym_idx: -1 };
 }
-const try_create_cart_to_frac = (lattice_matrix) => {
-    try {
-        return math.create_cart_to_frac(lattice_matrix);
-    }
-    catch {
-        return null;
-    }
-};
 const approximate_cart_to_frac = (xyz, axis_lengths) => [
     Math.abs(axis_lengths[0]) > math.EPS ? xyz[0] / axis_lengths[0] : 0,
     Math.abs(axis_lengths[1]) > math.EPS ? xyz[1] / axis_lengths[1] : 0,
     Math.abs(axis_lengths[2]) > math.EPS ? xyz[2] / axis_lengths[2] : 0,
 ];
-// Parse VASP POSCAR file format
+// Build a 3x3 matrix from 3 row vectors; error context is suffixed with the 1-based row index
+const matrix3x3_from_rows = (rows, context) => [
+    vec3_from_values(rows[0], `${context} 1`),
+    vec3_from_values(rows[1], `${context} 2`),
+    vec3_from_values(rows[2], `${context} 3`),
+];
+// cart→frac converter that falls back to per-axis-length division for singular lattices.
+// axis_lengths defaults to the row norms of the lattice matrix.
+const cart_to_frac_with_fallback = (matrix, axis_lengths) => {
+    try {
+        return { convert: math.create_cart_to_frac(matrix), exact: true };
+    }
+    catch {
+        // fall through to the per-axis-length approximation below
+    }
+    const lengths = axis_lengths ?? [
+        Math.hypot(...matrix[0]),
+        Math.hypot(...matrix[1]),
+        Math.hypot(...matrix[2]),
+    ];
+    return { convert: (xyz) => approximate_cart_to_frac(xyz, lengths), exact: false };
+};
+// @internal parser exported for tests; public entry points: parse_structure_file/parse_any_structure. Parse VASP POSCAR.
 export function parse_poscar(content) {
     try {
         // Strip only horizontal whitespace: a blank first (comment) line is valid POSCAR
         const lines = content.replace(/^[ \t]+/, ``).split(/\r?\n/);
         if (lines.length < 8) {
-            console.error(`POSCAR file too short`);
+            diag_error(`POSCAR file too short`);
             return null;
         }
         // Scale line: one value (negative = target volume) or three per-axis Cartesian factors
         const scale_tokens = lines[1].trim().split(/\s+/).map(parseFloat);
         let scale_factor = scale_tokens[0];
         if (isNaN(scale_factor)) {
-            console.error(`Invalid scaling factor in POSCAR`);
+            diag_error(`Invalid scaling factor in POSCAR`);
             return null;
         }
         const scale_vec = scale_tokens.slice(0, 3);
@@ -129,6 +201,10 @@ export function parse_poscar(content) {
         // Handle negative scale factor (volume-based scaling, single-factor form only)
         if (!per_axis_scale && scale_factor < 0) {
             const volume = Math.abs(math.det_3x3(lattice_vecs));
+            if (volume < math.EPS) {
+                diag_error(`POSCAR target-volume scaling requires a non-singular lattice`);
+                return null;
+            }
             scale_factor = (-scale_factor / volume) ** (1 / 3);
         }
         // Scale lattice vectors (per-axis factors multiply Cartesian components)
@@ -141,9 +217,7 @@ export function parse_poscar(content) {
         let atom_counts = [];
         // Detect if this is VASP 5+ format (has element symbols)
         // Try to parse the first token as a number - if it succeeds, it's VASP 4 format
-        const first_token = lines[line_index].trim().split(/\s+/)[0];
-        const first_token_as_number = parseInt(first_token, 10);
-        const has_element_symbols = isNaN(first_token_as_number);
+        const has_element_symbols = isNaN(parse_leading_num(lines[line_index]));
         if (has_element_symbols) {
             // VASP 5+ format - parse element symbols (may span multiple lines)
             let symbol_lines = 1;
@@ -151,9 +225,7 @@ export function parse_poscar(content) {
             for (let lookahead_idx = 1; lookahead_idx < 10; lookahead_idx++) {
                 if (line_index + lookahead_idx >= lines.length)
                     break;
-                const next_line_first_token = lines[line_index + lookahead_idx].trim().split(/\s+/)[0];
-                const next_token_as_number = parseInt(next_line_first_token, 10);
-                if (!isNaN(next_token_as_number)) {
+                if (!isNaN(parse_leading_num(lines[line_index + lookahead_idx]))) {
                     symbol_lines = lookahead_idx;
                     break;
                 }
@@ -183,201 +255,163 @@ export function parse_poscar(content) {
             line_index += 1;
         }
         if (element_symbols.length !== atom_counts.length) {
-            console.error(`Mismatch between element symbols and atom counts`);
+            diag_error(`Mismatch between element symbols and atom counts`);
+            return null;
+        }
+        if (line_index >= lines.length) {
+            diag_error(`Missing coordinate mode line in POSCAR`);
             return null;
         }
         // Check for selective dynamics
         let has_selective_dynamics = false;
-        if (line_index < lines.length) {
-            let coordinate_mode = lines[line_index].trim().toUpperCase();
-            if (coordinate_mode.startsWith(`S`)) {
-                has_selective_dynamics = true;
-                line_index += 1;
-                if (line_index < lines.length) {
-                    coordinate_mode = lines[line_index].trim().toUpperCase();
-                }
-                else {
-                    console.error(`Missing coordinate mode after selective dynamics`);
-                    return null;
-                }
+        let coordinate_mode = lines[line_index].trim().toUpperCase();
+        if (coordinate_mode.startsWith(`S`)) {
+            has_selective_dynamics = true;
+            line_index += 1;
+            if (line_index < lines.length) {
+                coordinate_mode = lines[line_index].trim().toUpperCase();
             }
-            // Determine coordinate mode
-            const is_direct = coordinate_mode.startsWith(`D`);
-            const is_cartesian = coordinate_mode.startsWith(`C`) || coordinate_mode.startsWith(`K`);
-            if (!is_direct && !is_cartesian) {
-                console.error(`Unknown coordinate mode in POSCAR: ${coordinate_mode}`);
+            else {
+                diag_error(`Missing coordinate mode after selective dynamics`);
                 return null;
             }
-            // Parse atomic positions
-            const poscar_axis_lengths = [
-                Math.hypot(...scaled_lattice[0]),
-                Math.hypot(...scaled_lattice[1]),
-                Math.hypot(...scaled_lattice[2]),
-            ];
-            const poscar_frac_to_cart = math.create_frac_to_cart(scaled_lattice);
-            const poscar_cart_to_frac = try_create_cart_to_frac(scaled_lattice);
-            if (!is_direct && !poscar_cart_to_frac) {
-                console.warn(`POSCAR: singular lattice, using axis-length fallback for cart→frac`);
-            }
-            const sites = [];
-            let atom_index = 0;
-            for (let elem_idx = 0; elem_idx < element_symbols.length; elem_idx++) {
-                const element = validate_element_symbol(element_symbols[elem_idx], elem_idx);
-                const count = atom_counts[elem_idx];
-                for (let atom_count_idx = 0; atom_count_idx < count; atom_count_idx++) {
-                    const coord_line_idx = line_index + 1 + atom_index + atom_count_idx;
-                    if (coord_line_idx >= lines.length) {
-                        console.error(`Not enough coordinate lines in POSCAR`);
-                        return null;
-                    }
-                    const coords = vec3_from_values(parse_coordinate_line(lines[coord_line_idx]), `POSCAR atom coordinates on line ${coord_line_idx + 1}`);
-                    // Parse selective dynamics if present
-                    let selective_dynamics;
-                    if (has_selective_dynamics) {
-                        const tokens = lines[coord_line_idx].trim().split(/\s+/);
-                        if (tokens.length >= 6) {
-                            selective_dynamics = [tokens[3] === `T`, tokens[4] === `T`, tokens[5] === `T`];
-                        }
+        }
+        // Determine coordinate mode
+        const is_direct = coordinate_mode.startsWith(`D`);
+        const is_cartesian = coordinate_mode.startsWith(`C`) || coordinate_mode.startsWith(`K`);
+        if (!is_direct && !is_cartesian) {
+            diag_error(`Unknown coordinate mode in POSCAR: ${coordinate_mode}`);
+            return null;
+        }
+        // Parse atomic positions
+        const poscar_frac_to_cart = math.create_frac_to_cart(scaled_lattice);
+        const poscar_cart_to_frac = cart_to_frac_with_fallback(scaled_lattice);
+        if (!is_direct && !poscar_cart_to_frac.exact) {
+            diag_warn(`POSCAR: singular lattice, using axis-length fallback for cart→frac`);
+        }
+        const sites = [];
+        let atom_index = 0;
+        for (let elem_idx = 0; elem_idx < element_symbols.length; elem_idx++) {
+            const element = validate_element_symbol(element_symbols[elem_idx], elem_idx);
+            const count = atom_counts[elem_idx];
+            for (let atom_count_idx = 0; atom_count_idx < count; atom_count_idx++) {
+                const coord_line_idx = line_index + 1 + atom_index + atom_count_idx;
+                if (coord_line_idx >= lines.length) {
+                    diag_error(`Not enough coordinate lines in POSCAR`);
+                    return null;
+                }
+                const coords = vec3_from_values(parse_coordinate_line(lines[coord_line_idx]), `POSCAR atom coordinates on line ${coord_line_idx + 1}`);
+                // Parse selective dynamics if present
+                let selective_dynamics;
+                if (has_selective_dynamics) {
+                    const tokens = lines[coord_line_idx].trim().split(/\s+/);
+                    if (tokens.length >= 6) {
+                        selective_dynamics = [tokens[3] === `T`, tokens[4] === `T`, tokens[5] === `T`];
                     }
-                    // Cartesian input is scaled then converted to fractional (axis-length fallback
-                    // for singular lattices); abc wraps to [0, 1) and xyz is recomputed from it so
-                    // both stay consistent (singular Cartesian keeps the scaled input as xyz)
-                    const cart = is_direct ? null : apply_axis_scale(coords);
-                    const raw_abc = cart
-                        ? (poscar_cart_to_frac?.(cart) ??
-                            approximate_cart_to_frac(cart, poscar_axis_lengths))
-                        : coords;
-                    const abc = wrap_to_unit_cell(raw_abc);
-                    const xyz = cart && !poscar_cart_to_frac ? cart : poscar_frac_to_cart(abc);
-                    const site = {
-                        species: [{ element, occu: 1, oxidation_state: 0 }],
-                        abc,
-                        xyz,
-                        label: `${element}${atom_index + atom_count_idx + 1}`,
-                        properties: selective_dynamics ? { selective_dynamics } : {},
-                    };
-                    sites.push(site);
                 }
-                atom_index += count;
+                // Cartesian input is scaled then converted to fractional (axis-length fallback
+                // for singular lattices); abc wraps to [0, 1) and xyz is recomputed from it so
+                // both stay consistent (singular Cartesian keeps the scaled input as xyz)
+                const cart = is_direct ? null : apply_axis_scale(coords);
+                const raw_abc = cart ? poscar_cart_to_frac.convert(cart) : coords;
+                const abc = wrap_to_unit_cell(raw_abc);
+                const xyz = cart && !poscar_cart_to_frac.exact ? cart : poscar_frac_to_cart(abc);
+                sites.push(make_site(element, abc, xyz, `${element}${atom_index + atom_count_idx + 1}`, selective_dynamics ? { selective_dynamics } : {}));
             }
-            const lattice_params = math.calc_lattice_params(scaled_lattice);
-            const structure = {
-                sites,
-                lattice: { matrix: scaled_lattice, ...lattice_params },
-            };
-            return structure;
+            atom_index += count;
         }
-        console.error(`Missing coordinate mode line in POSCAR`);
-        return null;
+        const lattice_params = math.calc_lattice_params(scaled_lattice);
+        return { sites, lattice: { matrix: scaled_lattice, ...lattice_params } };
     }
     catch (error) {
-        console.error(`Error parsing POSCAR file:`, error);
+        diag_error(`Error parsing POSCAR file`, error);
         return null;
     }
 }
-// Parse XYZ file format. Supports both standard XYZ and extended XYZ formats with multi-frame support
+// @internal parser exported for tests + trajectory parser; public entry points: parse_structure_file/parse_any_structure. Parse standard/extended XYZ (multi-frame).
 export function parse_xyz(content) {
     try {
         const normalized_content = content.trim();
         if (!normalized_content) {
-            console.error(`Empty XYZ file`);
+            diag_error(`Empty XYZ file`);
             return null;
         }
-        // Split into frames by reading the atom count and slicing lines
+        // Walk frames by reading atom counts; multi-frame XYZ parses only the last frame
         const all_lines = normalized_content.split(/\r?\n/);
-        const frames = [];
-        let frame_line_idx = 0;
-        while (frame_line_idx < all_lines.length) {
-            const numAtoms = parseInt(all_lines[frame_line_idx].trim(), 10);
-            if (!isNaN(numAtoms) &&
-                numAtoms > 0 &&
-                frame_line_idx + numAtoms + 1 < all_lines.length) {
-                const frameLines = all_lines.slice(frame_line_idx, frame_line_idx + numAtoms + 2);
-                frames.push(frameLines.join(`\n`));
-                frame_line_idx += numAtoms + 2;
-            }
-            else
-                frame_line_idx++;
-        }
-        // If no frames found, try simple parsing
-        if (frames.length === 0)
-            frames.push(normalized_content);
-        // Parse the last frame (or only frame)
-        const frame_content = frames.at(-1) ?? ``;
-        const lines = frame_content.trim().split(/\r?\n/);
+        let last_frame = null;
+        for (const frame of iter_xyz_frames(all_lines))
+            last_frame = frame;
+        // If no complete frame found, fall back to parsing the whole content as one frame
+        const lines = last_frame
+            ? all_lines.slice(last_frame.start, last_frame.start + last_frame.num_atoms + 2)
+            : all_lines;
         if (lines.length < 2) {
-            console.error(`XYZ frame too short`);
+            diag_error(`XYZ frame too short`);
             return null;
         }
-        // Parse number of atoms (line 1)
-        const num_atoms = parseInt(lines[0].trim(), 10);
+        // Parse number of atoms (line 1). Only the first token counts: Tinker-style
+        // XYZ files put a title after the count (e.g. `6 methane`)
+        const num_atoms = Math.trunc(parse_leading_num(lines[0]));
         if (isNaN(num_atoms) || num_atoms <= 0) {
-            console.error(`Invalid number of atoms in XYZ file`);
+            diag_error(`Invalid number of atoms in XYZ file`);
             return null;
         }
         // Parse comment line (line 2) - may contain lattice info for extended XYZ
         const comment_line = lines[1];
         let lattice;
         // Check for extended XYZ lattice information in comment line
-        const lattice_match = /Lattice="([^"]+)"/.exec(comment_line);
+        const lattice_match = /Lattice="(?<lattice>[^"]+)"/.exec(comment_line);
         if (lattice_match) {
             const lattice_values = lattice_match[1].split(/\s+/).map(parse_coordinate);
             if (lattice_values.length === 9) {
-                const lattice_vectors = [
-                    vec3_from_values(lattice_values.slice(0, 3), `XYZ lattice vector 1`),
-                    vec3_from_values(lattice_values.slice(3, 6), `XYZ lattice vector 2`),
-                    vec3_from_values(lattice_values.slice(6, 9), `XYZ lattice vector 3`),
-                ];
+                const lattice_vectors = matrix3x3_from_rows([lattice_values.slice(0, 3), lattice_values.slice(3, 6), lattice_values.slice(6, 9)], `XYZ lattice vector`);
                 const lattice_params = math.calc_lattice_params(lattice_vectors);
                 lattice = { matrix: lattice_vectors, ...lattice_params };
             }
         }
         // Parse atomic coordinates (starting from line 3)
-        const xyz_axis_lengths = lattice ? [lattice.a, lattice.b, lattice.c] : null;
         let xyz_frac_to_cart = null;
         let xyz_cart_to_frac = null;
         if (lattice) {
             xyz_frac_to_cart = math.create_frac_to_cart(lattice.matrix);
-            xyz_cart_to_frac = try_create_cart_to_frac(lattice.matrix);
+            xyz_cart_to_frac = cart_to_frac_with_fallback(lattice.matrix, [
+                lattice.a,
+                lattice.b,
+                lattice.c,
+            ]).convert;
         }
         const sites = [];
         for (let atom_idx = 0; atom_idx < num_atoms; atom_idx++) {
             const line_idx = atom_idx + 2;
             if (line_idx >= lines.length) {
-                console.error(`Not enough coordinate lines in XYZ file`);
+                diag_error(`Not enough coordinate lines in XYZ file`);
                 return null;
             }
             const parts = lines[line_idx].trim().split(/\s+/);
             if (parts.length < 4) {
-                console.error(`Invalid coordinate line in XYZ file`);
+                diag_error(`Invalid coordinate line in XYZ file`);
                 return null;
             }
             const element = validate_element_symbol(parts[0], atom_idx);
             const xyz = vec3_from_values(parts.slice(1, 4).map(parse_coordinate), `XYZ atom position ${atom_idx + 1}`);
             // Calculate fractional coordinates if lattice is available
             let abc = [0, 0, 0];
-            if (lattice && xyz_frac_to_cart && xyz_axis_lengths) {
-                abc = xyz_cart_to_frac
-                    ? xyz_cart_to_frac(xyz)
-                    : approximate_cart_to_frac(xyz, xyz_axis_lengths);
+            if (lattice && xyz_frac_to_cart && xyz_cart_to_frac) {
                 // Ensure fractional coordinates are wrapped into [0, 1) for consistency
-                abc = wrap_to_unit_cell(abc);
+                abc = wrap_to_unit_cell(xyz_cart_to_frac(xyz));
                 // Keep rendered atoms inside primary unit cell by recomputing xyz
                 const wrapped_xyz = xyz_frac_to_cart(abc);
                 xyz[0] = wrapped_xyz[0];
                 xyz[1] = wrapped_xyz[1];
                 xyz[2] = wrapped_xyz[2];
             }
-            const species = [{ element, occu: 1, oxidation_state: 0 }];
-            const label = `${element}${atom_idx + 1}`;
-            const site = { species, abc, xyz, label, properties: {} };
-            sites.push(site);
+            sites.push(make_site(element, abc, xyz, `${element}${atom_idx + 1}`));
         }
         const structure = { sites, ...(lattice && { lattice }) };
         return structure;
     }
     catch (error) {
-        console.error(`Error parsing XYZ file:`, error);
+        diag_error(`Error parsing XYZ file`, error);
         return null;
     }
 }
@@ -394,8 +428,7 @@ const parse_symmetry_expression = (expr_input) => {
     // E.g., "x-y+1/3" → ["x", "-y", "+1/3"] or "-x+y" → ["-x", "+y"]
     const tokens = [];
     let current_token = ``;
-    for (let idx = 0; idx < expr.length; idx++) {
-        const char = expr[idx];
+    for (const char of expr) {
         if ((char === `+` || char === `-`) && current_token.length > 0) {
             tokens.push(current_token);
             current_token = char;
@@ -408,7 +441,7 @@ const parse_symmetry_expression = (expr_input) => {
         tokens.push(current_token);
     for (const token of tokens) {
         // Check if this token is a variable term (x, y, or z with optional sign)
-        const var_match = /^([+-]?)([xyz])$/.exec(token);
+        const var_match = /^(?<sign>[+-]?)(?<axis>[xyz])$/.exec(token);
         if (var_match) {
             const sign = var_match[1] === `-` ? -1 : 1;
             const var_char = var_match[2];
@@ -434,8 +467,8 @@ const parse_symmetry_expression = (expr_input) => {
             // Fraction
             const parts = num_str.split(`/`);
             if (parts.length === 2) {
-                const numerator = parseFloat(parts[0]);
-                const denominator = parseFloat(parts[1]);
+                const numerator = Number(parts[0]);
+                const denominator = Number(parts[1]);
                 if (!isNaN(numerator) && !isNaN(denominator) && denominator !== 0) {
                     translation += sign * (numerator / denominator);
                 }
@@ -443,7 +476,7 @@ const parse_symmetry_expression = (expr_input) => {
         }
         else {
             // Integer or decimal
-            const val = parseFloat(num_str);
+            const val = Number(num_str);
             if (!isNaN(val)) {
                 translation += sign * val;
             }
@@ -451,49 +484,50 @@ const parse_symmetry_expression = (expr_input) => {
     }
     return { coefficients, translation };
 };
-// Apply symmetry operations to generate equivalent positions
-const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords) => {
-    if (symmetry_ops.length === 0)
+// Apply symmetry operations (and optional lattice-centering translations) to
+// generate all equivalent positions. Deduplication uses 6 decimal places to
+// absorb floating point error from compound ops like x-y, -x+y.
+const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords, centering = []) => {
+    if (symmetry_ops.length === 0 && centering.length === 0)
         return [atom];
     const equivalent_atoms = [];
     const seen = new Set();
     const wrap = (coords) => wrap_fractional_coords ? wrap_to_unit_cell(coords) : coords;
-    // Use 6 decimal places for deduplication to handle floating point imprecision
-    // from compound symmetry operations like x-y, -x+y which can produce small errors
-    // Always include base atom (optionally wrapped)
-    const base_coords = wrap(atom.coords);
-    seen.add(cif_coords_key(base_coords));
-    equivalent_atoms.push({ ...atom, coords: base_coords });
+    // Every generated position is also offset by each centering translation
+    const shifts = [[0, 0, 0], ...centering];
+    // Record a position plus its centering images, deduplicating on wrapped coords
+    const add_position = (coords) => {
+        for (const [dx, dy, dz] of shifts) {
+            const wrapped = wrap([coords[0] + dx, coords[1] + dy, coords[2] + dz]);
+            const key = cif_coords_key(wrapped);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const id = equivalent_atoms.length === 0 ? atom.id : `${atom.id}_${equivalent_atoms.length}`;
+            equivalent_atoms.push({ ...atom, coords: wrapped, id });
+        }
+    };
+    add_position(atom.coords); // base atom (+ centering images)
+    // ops arrive pre-normalized (quotes + whitespace already stripped, see normalized_ops)
     for (const operation of symmetry_ops) {
-        const operation_match = /['"]([^'"]+)['"]/.exec(operation);
-        const expr_str = operation_match ? operation_match[1] : operation.trim();
-        const parts = expr_str.split(`,`).map((part) => part.trim());
+        const parts = operation.split(`,`);
         if (parts.length !== 3)
             continue;
         const new_coords = [0, 0, 0];
         for (let dim = 0; dim < 3; dim++) {
             const { coefficients, translation } = parse_symmetry_expression(parts[dim]);
-            // Apply: new_coord = coeff_x * x + coeff_y * y + coeff_z * z + translation
-            new_coords[dim] =
-                coefficients[0] * atom.coords[0] +
-                    coefficients[1] * atom.coords[1] +
-                    coefficients[2] * atom.coords[2] +
-                    translation;
+            // new_coord = coeff_x * x + coeff_y * y + coeff_z * z + translation
+            new_coords[dim] = math.dot(coefficients, atom.coords) + translation;
         }
-        // Wrap and deduplicate transformed coordinates
-        const wrapped = wrap(new_coords);
-        const cache_key = cif_coords_key(wrapped);
-        if (seen.has(cache_key))
-            continue;
-        seen.add(cache_key);
-        equivalent_atoms.push({
-            ...atom,
-            coords: wrapped,
-            id: `${atom.id}_${equivalent_atoms.length}`,
-        });
+        add_position(new_coords);
     }
     return equivalent_atoms;
 };
+// Parse a CIF numeric token, stripping a trailing uncertainty like "1.234(5)"
+const parse_cif_uncertain_number = (token) => {
+    const value = parse_num_token(token.split(`(`)[0]);
+    return isNaN(value) ? null : value;
+};
 const extract_cif_cell_parameters = (text, type, strict = true) => text
     .split(`\n`)
     .filter((line) => line.startsWith(`_${type}`))
@@ -506,11 +540,9 @@ const extract_cif_cell_parameters = (text, type, strict = true) => text
             throw new Error(`Invalid CIF cell parameter line format: ${line}`);
         return null;
     }
-    const value = parseFloat(tokens[1].split(`(`)[0]);
-    if (isNaN(value)) {
-        if (strict)
-            throw new Error(`Invalid CIF cell parameter in line: ${line}`);
-        return null; // Return null for invalid values in non-strict mode
+    const value = parse_cif_uncertain_number(tokens[1]);
+    if (value === null && strict) {
+        throw new Error(`Invalid CIF cell parameter in line: ${line}`);
     }
     return value;
 })
@@ -538,31 +570,63 @@ const build_cif_atom_site_header_indices = (headers) => {
     });
     return indices;
 };
+// Which coordinate triple a CIF atom-site loop provides (fractional preferred), or null
+const cif_coords_type = (indices) => {
+    if (indices.x !== undefined && indices.y !== undefined && indices.z !== undefined) {
+        return `fract`;
+    }
+    if (indices.cart_x !== undefined &&
+        indices.cart_y !== undefined &&
+        indices.cart_z !== undefined) {
+        return `cart`;
+    }
+    return null;
+};
+// The 3 column indices for the requested coordinate type
+const cif_coord_indices = (indices, coords_type) => coords_type === `fract`
+    ? [indices.x, indices.y, indices.z]
+    : [indices.cart_x, indices.cart_y, indices.cart_z];
+// Walk CIF loop_ blocks: yields each loop's header tags plus the index of its first data line
+function* iter_cif_loops(lines) {
+    for (let idx = 0; idx < lines.length; idx++) {
+        if (lines[idx].trim() !== `loop_`)
+            continue;
+        const headers = [];
+        let jj = idx + 1;
+        while (jj < lines.length && lines[jj].trim().startsWith(`_`)) {
+            headers.push(lines[jj].trim());
+            jj++;
+        }
+        yield { headers, data_start: jj };
+    }
+}
+// Split a CIF data line into whitespace-separated tokens, keeping quoted multi-word
+// values as single tokens and stripping the quotes
+const split_cif_tokens = (line) => (line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((token) => token.replaceAll(/['"]/g, ``));
 // Parse atom data from CIF with robust error handling
 const parse_cif_atom_data = (raw_data, indices, coords_type) => {
     const { label = 0, symbol = -1, occupancy = -1 } = indices;
-    const coord_indices = coords_type === `fract`
-        ? [indices.x, indices.y, indices.z]
-        : [indices.cart_x, indices.cart_y, indices.cart_z];
+    const coord_indices = cif_coord_indices(indices, coords_type);
     if (coord_indices.some((idx) => idx === undefined)) {
         throw new Error(`Missing coordinate indices`);
     }
     const coords_triplet = vec3_from_values(coord_indices.map((idx) => {
-        if (idx === undefined)
-            throw new Error(`Invalid coordinate index`);
+        // idx cannot be undefined: the `.some` guard above already threw
         const coord_str = raw_data[idx];
         if (!coord_str)
             throw new Error(`Missing coordinate at index ${idx}`);
-        const coord = parseFloat(coord_str.split(`(`)[0]);
-        if (isNaN(coord))
+        const coord = parse_cif_uncertain_number(coord_str);
+        if (coord === null)
             throw new Error(`Invalid coordinate: ${coord_str}`);
         return coord;
     }), `CIF atom coordinates`);
-    const occu = occupancy >= 0 && raw_data[occupancy]
-        ? parseFloat(raw_data[occupancy].split(`(`)[0]) || 1.0
-        : 1.0;
-    const from_symbol = symbol >= 0 ? /^([A-Z][a-z]*)/.exec(raw_data[symbol])?.[1] : undefined;
-    const element_symbol = from_symbol ?? raw_data[label]?.match(/([A-Z][a-z]*)/g)?.[0];
+    const raw_occu = occupancy >= 0 && raw_data[occupancy]
+        ? parse_cif_uncertain_number(raw_data[occupancy])
+        : null;
+    // invalid or zero occupancy defaults to fully occupied
+    const occu = raw_occu == null || raw_occu === 0 ? 1.0 : raw_occu;
+    const from_symbol = symbol >= 0 ? /^(?<element>[A-Z][a-z]*)/.exec(raw_data[symbol])?.[1] : undefined;
+    const element_symbol = from_symbol ?? raw_data[label]?.match(/(?:[A-Z][a-z]*)/g)?.[0];
     if (!element_symbol) {
         throw new Error(`Could not extract element symbol from: ${raw_data.join(` `)}`);
     }
@@ -574,12 +638,12 @@ const parse_cif_atom_data = (raw_data, indices, coords_type) => {
         occupancy: occu,
     };
 };
-// Parse CIF (Crystallographic Information File) format
+// @internal parser exported for tests; public entry points: parse_structure_file/parse_any_structure. Parse CIF (Crystallographic Information File).
 export function parse_cif(content, wrap_fractional_coords = true, strict = true) {
     try {
         const text = content.trim();
         if (!text) {
-            console.error(`CIF file is empty`);
+            diag_error(`CIF file is empty`);
             return null;
         }
         // Find atom site loop that actually contains coordinates (fract or Cartn)
@@ -587,16 +651,8 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         let atom_headers = [];
         const atom_data_lines = [];
         const symmetry_ops = [];
-        for (let ii = 0; ii < lines.length; ii++) {
-            if (lines[ii].trim() !== `loop_`)
-                continue;
-            let jj = ii + 1;
-            const headers = [];
-            // Collect headers for this loop
-            while (jj < lines.length && lines[jj].trim().startsWith(`_`)) {
-                headers.push(lines[jj].trim());
-                jj++;
-            }
+        for (const { headers, data_start } of iter_cif_loops(lines)) {
+            let jj = data_start;
             // Check if this is a symmetry operations loop
             if (headers.some((header) => header.includes(`_symmetry_equiv_pos_as_xyz`) ||
                 header.includes(`_space_group_symop_operation_xyz`))) {
@@ -617,16 +673,8 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 continue;
             // Check if this loop contains coordinate headers
             const indices_preview = build_cif_atom_site_header_indices(headers);
-            const has_coords = (indices_preview.x !== undefined &&
-                indices_preview.y !== undefined &&
-                indices_preview.z !== undefined) ||
-                (indices_preview.cart_x !== undefined &&
-                    indices_preview.cart_y !== undefined &&
-                    indices_preview.cart_z !== undefined);
-            if (!has_coords) {
-                ii = jj - 1;
+            if (cif_coords_type(indices_preview) === null)
                 continue;
-            }
             // This is the desired atom-site loop with coordinates: collect data lines
             atom_headers = headers;
             while (jj < lines.length) {
@@ -653,36 +701,21 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 break;
         }
         if (atom_headers.length === 0 || atom_data_lines.length === 0) {
-            console.error(`No valid atom site loop found in CIF file`);
+            diag_error(`No valid atom site loop found in CIF file`);
             return null;
         }
         // Parse atom data with error handling
         const header_indices = build_cif_atom_site_header_indices(atom_headers);
         // Determine available coordinate type
-        const coords_type = header_indices.x !== undefined &&
-            header_indices.y !== undefined &&
-            header_indices.z !== undefined
-            ? `fract`
-            : header_indices.cart_x !== undefined &&
-                header_indices.cart_y !== undefined &&
-                header_indices.cart_z !== undefined
-                ? `cart`
-                : null;
+        const coords_type = cif_coords_type(header_indices);
         if (!coords_type) {
-            console.error(`CIF atom site loop missing coordinates (fract or Cartn)`);
+            diag_error(`CIF atom site loop missing coordinates (fract or Cartn)`);
             return null;
         }
         // Collect required coordinate indices
-        const required_indices = coords_type === `fract`
-            ? [header_indices.x, header_indices.y, header_indices.z]
-            : [header_indices.cart_x, header_indices.cart_y, header_indices.cart_z];
+        const required_indices = cif_coord_indices(header_indices, coords_type);
         const atoms = atom_data_lines
-            .map((line) => {
-            // Handle quoted multi-word values by splitting only on whitespace
-            // that is not inside quotes.
-            const tokens = line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
-            return tokens.map((token) => token.replaceAll(/['"]/g, ``));
-        })
+            .map(split_cif_tokens)
             .filter((tokens) => {
             const { disorder } = header_indices;
             const max_required_idx = Math.max(...required_indices);
@@ -694,20 +727,20 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 return parse_cif_atom_data(tokens, header_indices, coords_type);
             }
             catch (error) {
-                console.warn(`Skipping invalid atom data: ${error}`);
+                diag_warn(`Skipping invalid atom data: ${error}`);
                 return null;
             }
         })
             .filter((atom) => atom !== null);
         if (atoms.length === 0) {
-            console.error(`No valid atoms found in CIF file`);
+            diag_error(`No valid atoms found in CIF file`);
             return null;
         }
         // Extract cell parameters and build lattice
         const lengths = extract_cif_cell_parameters(text, `cell_length`, strict);
         const angles = extract_cif_cell_parameters(text, `cell_angle`, strict);
         if (lengths.length < 3 || angles.length < 3) {
-            console.error(`Insufficient cell parameters in CIF file`);
+            diag_error(`Insufficient cell parameters in CIF file`);
             return null;
         }
         // Build lattice and create sites
@@ -716,60 +749,42 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         const lattice_matrix = math.cell_to_lattice_matrix(a, b, c, alpha, beta, gamma);
         const lattice_params = math.calc_lattice_params(lattice_matrix);
         const frac_to_cart = math.create_frac_to_cart(lattice_matrix);
-        const cart_to_frac = try_create_cart_to_frac(lattice_matrix);
+        const cart_to_frac = cart_to_frac_with_fallback(lattice_matrix, [a, b, c]).convert;
         // Create sites with coordinate conversion and symmetry operations
-        const wrap_vec3 = (v) => (wrap_fractional_coords ? wrap_to_unit_cell(v) : v);
-        // Apply symmetry operations to generate all equivalent positions
-        const all_sites = [];
-        // Normalize symmetry operations (trim/strip quotes) but preserve duplicates; we deduplicate positions later
-        const normalized_ops = symmetry_ops
-            .map((op) => /['"]([^'"]+)['"]/.exec(op)?.[1] ?? op.trim())
-            .map((op) => op.replaceAll(/\s+/g, ``));
-        // Rely on symmetry operations list for all centering/translations to avoid double-counting
-        // TODO: Support conventional cells with centering by discovering centering from space group metadata
-        // when present (e.g. P, I, F, C, R centering types)
-        const centering_vectors = [[0, 0, 0]];
+        const wrap_vec3 = (vec) => wrap_fractional_coords ? wrap_to_unit_cell(vec) : vec;
+        // Strip surrounding quotes and all whitespace (preserving duplicates; positions
+        // are deduplicated later). Leaves ops as bare `x,y,z`-style expressions.
+        const normalized_ops = symmetry_ops.map((op) => (/['"](?<expr>[^'"]+)['"]/.exec(op)?.groups?.expr ?? op).replaceAll(/\s+/g, ``));
         // Inspect optional _atom_type_number_in_cell loop to see if atom sites are already expanded
-        const atom_type_counts = (() => {
-            const map = {};
-            const text_lines = text.split(`\n`);
-            for (let li = 0; li < text_lines.length; li++) {
-                if (text_lines[li].trim() !== `loop_`) {
+        const atom_type_counts = {};
+        for (const { headers, data_start } of iter_cif_loops(lines)) {
+            const hdrs = headers.map((hdr) => hdr.toLowerCase());
+            const sym_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_symbol`));
+            const num_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_number_in_cell`));
+            if (sym_idx === -1 || num_idx === -1)
+                continue;
+            for (let lj = data_start; lj < lines.length; lj++) {
+                const line = lines[lj].trim();
+                if (!line || line === `loop_` || line.startsWith(`data_`))
+                    break;
+                if (line.startsWith(`#`))
                     continue;
-                }
-                let lj = li + 1;
-                const hdrs = [];
-                while (lj < text_lines.length && text_lines[lj].trim().startsWith(`_`)) {
-                    hdrs.push(text_lines[lj].trim().toLowerCase());
-                    lj++;
-                }
-                const sym_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_symbol`));
-                const num_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_number_in_cell`));
-                if (sym_idx !== -1 && num_idx !== -1) {
-                    while (lj < text_lines.length) {
-                        const line = text_lines[lj].trim();
-                        if (!line || line === `loop_` || line.startsWith(`data_`))
-                            break;
-                        if (line.startsWith(`#`)) {
-                            lj++;
-                            continue;
-                        }
-                        const toks = (line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((tok) => tok.replaceAll(/['"]/g, ``));
-                        if (toks.length > Math.max(sym_idx, num_idx)) {
-                            // Normalize type symbol to bare element (e.g. 'Sn2+' -> 'Sn')
-                            const match = /^([A-Z][a-z]*)/.exec(toks[sym_idx]);
-                            const sym = match ? match[1] : toks[sym_idx];
-                            const num = parseInt(toks[num_idx], 10);
-                            if (sym && !Number.isNaN(num))
-                                map[sym] = num;
-                        }
-                        lj++;
+                const toks = split_cif_tokens(line);
+                if (toks.length > Math.max(sym_idx, num_idx)) {
+                    // Normalize type symbol to bare element (e.g. 'Sn2+' -> 'Sn')
+                    const match = /^(?<element>[A-Z][a-z]*)/.exec(toks[sym_idx]);
+                    const sym = match ? match[1] : toks[sym_idx];
+                    // Strip standard-uncertainty parentheses (`8(0)` -> `8`) like other CIF
+                    // readers; empty prefixes like `(8)` parse as NaN and get skipped
+                    const num = Math.trunc(parse_num_token(toks[num_idx].split(`(`)[0]));
+                    // sum rows that normalize to the same element (e.g. Fe2+ and Fe3+ → Fe)
+                    if (sym && !Number.isNaN(num)) {
+                        atom_type_counts[sym] = (atom_type_counts[sym] ?? 0) + num;
                     }
-                    break;
                 }
             }
-            return map;
-        })();
+            break;
+        }
         const observed_counts = {};
         for (const atom of atoms) {
             observed_counts[atom.element] = (observed_counts[atom.element] || 0) + 1;
@@ -778,57 +793,65 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         const already_enumerated = has_expected_counts &&
             Object.entries(atom_type_counts).every(([el, exp]) => (observed_counts[el] || 0) >= exp);
         const ops_to_use = already_enumerated ? [] : normalized_ops;
-        // Global deduplication of final sites (per element + coordinates + label)
-        // Use 6 decimal places to handle floating point imprecision from compound symmetry ops
-        const seen_site_keys = new Set();
-        for (const atom of atoms) {
-            const element = validate_element_symbol(atom.element, all_sites.length);
-            // Convert to fractional coordinates if needed
-            let fractional_atom;
-            if (atom.coords_type === `fract`) {
-                fractional_atom = {
-                    ...atom,
-                    coords: wrap_vec3(atom.coords),
-                    coords_type: `fract`,
-                };
-            }
-            else {
-                const xyz_base = [atom.coords[0], atom.coords[1], atom.coords[2]];
-                const atom_abc = wrap_vec3(cart_to_frac
-                    ? cart_to_frac(xyz_base)
-                    : approximate_cart_to_frac(xyz_base, [a, b, c]));
-                fractional_atom = { ...atom, coords: atom_abc, coords_type: `fract` };
-            }
-            // First apply symmetry operations in fractional space
-            const equiv_atoms = apply_symmetry_ops(fractional_atom, ops_to_use, wrap_fractional_coords);
-            // Then apply lattice centering shifts to each equivalent position
-            for (const equiv_atom of equiv_atoms) {
-                for (const cv of centering_vectors) {
-                    const abc = wrap_vec3([
-                        equiv_atom.coords[0] + cv[0],
-                        equiv_atom.coords[1] + cv[1],
-                        equiv_atom.coords[2] + cv[2],
-                    ]);
+        // Candidate lattice-centering translations from the space-group symbol (R
+        // only valid in the hexagonal setting, α≈β≈90°, γ≈120°). Whether to actually
+        // apply them is decided below by reconciling against _atom_type_number_in_cell.
+        const centering_letter = extract_cif_centering(text);
+        const is_hexagonal_setting = Math.abs(alpha - 90) <= 1 && Math.abs(beta - 90) <= 1 && Math.abs(gamma - 120) <= 1;
+        const centering = centering_letter && (centering_letter !== `R` || is_hexagonal_setting)
+            ? CENTERING_VECTORS[centering_letter]
+            : [];
+        // Build all sites by expanding each atom via the symmetry ops (+ optional
+        // centering). Deduplicate globally on element + coordinates + label (6 dp to
+        // absorb floating point error from compound ops).
+        const build_sites = (extra_centering) => {
+            const sites = [];
+            const seen_site_keys = new Set();
+            for (const atom of atoms) {
+                const element = validate_element_symbol(atom.element, sites.length);
+                const coords = atom.coords_type === `fract`
+                    ? wrap_vec3(atom.coords)
+                    : wrap_vec3(cart_to_frac([atom.coords[0], atom.coords[1], atom.coords[2]]));
+                const fractional_atom = { ...atom, coords, coords_type: `fract` };
+                const equiv_atoms = apply_symmetry_ops(fractional_atom, ops_to_use, wrap_fractional_coords, extra_centering);
+                for (const equiv_atom of equiv_atoms) {
+                    const abc = wrap_vec3(equiv_atom.coords);
                     const key = cif_site_key(element, abc, equiv_atom.id);
                     if (seen_site_keys.has(key))
                         continue;
                     seen_site_keys.add(key);
-                    const xyz = frac_to_cart(abc);
-                    all_sites.push({
-                        species: [{ element, occu: equiv_atom.occupancy, oxidation_state: 0 }],
-                        abc,
-                        xyz,
-                        label: equiv_atom.id,
-                        properties: {},
-                    });
+                    sites.push(make_site(element, abc, frac_to_cart(abc), equiv_atom.id, {}, equiv_atom.occupancy));
                 }
             }
+            return sites;
+        };
+        // Expand with point-group ops first. If the space group is centered and the
+        // result falls short of _atom_type_number_in_cell, retry with centering and
+        // adopt it only when it reconciles the expected total exactly — this fixes
+        // CIFs listing point-only ops for the asymmetric unit while avoiding
+        // double-counting CIFs whose atom list already embeds centering (e.g. C2/c
+        // COD 7008984, where listed ops + atoms already total the cell contents).
+        let sites = build_sites([]);
+        const expected_total = Object.values(atom_type_counts).reduce((sum, num) => sum + num, 0);
+        if (centering.length > 0 && expected_total > sites.length) {
+            const centered_sites = build_sites(centering);
+            // Adopt centering only when per-element counts reconcile exactly. Checking
+            // the total alone is insufficient: it can coincide while individual element
+            // counts are wrong (e.g. expected Fe 1 / O 3 but centering yields Fe 2 / O 2).
+            const counts = {};
+            for (const site of centered_sites) {
+                const element = site.species[0].element;
+                counts[element] = (counts[element] ?? 0) + 1;
+            }
+            const reconciles = centered_sites.length === expected_total &&
+                Object.entries(atom_type_counts).every(([element, exp]) => counts[element] === exp);
+            if (reconciles)
+                sites = centered_sites;
         }
-        const sites = all_sites;
         return { sites, lattice: { matrix: lattice_matrix, ...lattice_params } };
     }
     catch (error) {
-        console.error(`Error parsing CIF file:`, error);
+        diag_error(`Error parsing CIF file`, error);
         return null;
     }
 }
@@ -836,11 +859,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
 function convert_phonopy_cell(cell) {
     const sites = [];
     // Phonopy stores lattice vectors as rows, use them directly
-    const lattice_matrix = [
-        vec3_from_values(cell.lattice[0], `phonopy lattice vector 1`),
-        vec3_from_values(cell.lattice[1], `phonopy lattice vector 2`),
-        vec3_from_values(cell.lattice[2], `phonopy lattice vector 3`),
-    ];
+    const lattice_matrix = matrix3x3_from_rows(cell.lattice, `phonopy lattice vector`);
     // Process each atomic site
     const phonopy_frac_to_cart = math.create_frac_to_cart(lattice_matrix);
     for (const point of cell.points) {
@@ -851,9 +870,7 @@ function convert_phonopy_cell(cell) {
             mass: point.mass,
             ...(point.reduced_to !== undefined && { reduced_to: point.reduced_to }),
         };
-        const species = [{ element, occu: 1.0, oxidation_state: 0 }];
-        const site = { species, abc, xyz, label: point.symbol, properties };
-        sites.push(site);
+        sites.push(make_site(element, abc, xyz, point.symbol, properties));
     }
     // Calculate lattice parameters
     const calculated_lattice_params = math.calc_lattice_params(lattice_matrix);
@@ -872,7 +889,7 @@ const get_phonopy_cell = (data, cell_type) => {
     const cell = Reflect.get(data, cell_type);
     return is_phonopy_cell(cell) ? cell : undefined;
 };
-// Parse phonopy YAML file and return the requested cell type (or preferred single structure)
+// @internal parser exported for tests; public entry points: parse_structure_file/parse_any_structure. Parse phonopy YAML, returns requested cell type (or preferred single structure).
 export function parse_phonopy_yaml(content, cell_type) {
     try {
         // Parse YAML content but exclude large phonon_displacements array for performance
@@ -887,7 +904,7 @@ export function parse_phonopy_yaml(content, cell_type) {
             }
             // Check if we're still in the phonon_displacements section
             if (skip_displacements) {
-                if (/^[a-zA-Z_]/.exec(line)) {
+                if (/^[a-zA-Z_]/.test(line)) {
                     // New top-level key, stop skipping
                     skip_displacements = false;
                 }
@@ -899,7 +916,7 @@ export function parse_phonopy_yaml(content, cell_type) {
         const filtered_content = filtered_lines.join(`\n`);
         const data = yaml_load(filtered_content);
         if (!data) {
-            console.error(`Failed to parse phonopy YAML`);
+            diag_error(`Failed to parse phonopy YAML`);
             return null;
         }
         // If specific cell type requested, parse only that one
@@ -907,27 +924,26 @@ export function parse_phonopy_yaml(content, cell_type) {
             const cell = get_phonopy_cell(data, cell_type);
             if (cell)
                 return convert_phonopy_cell(cell);
-            console.error(`Requested cell type '${cell_type}' not found in phonopy YAML`);
+            diag_error(`Requested cell type '${cell_type}' not found in phonopy YAML`);
             return null;
         }
-        // Auto mode: return preferred structure in order of preference
-        // 1. supercell (most detailed)
-        // 2. phonon_supercell
-        // 3. unit_cell
-        // 4. phonon_primitive_cell
-        // 5. primitive_cell
-        const auto_cell = get_phonopy_cell(data, `supercell`) ??
-            get_phonopy_cell(data, `phonon_supercell`) ??
-            get_phonopy_cell(data, `unit_cell`) ??
-            get_phonopy_cell(data, `phonon_primitive_cell`) ??
-            get_phonopy_cell(data, `primitive_cell`);
+        // Auto mode: return first available cell, most detailed first
+        const auto_cell = [
+            `supercell`,
+            `phonon_supercell`,
+            `unit_cell`,
+            `phonon_primitive_cell`,
+            `primitive_cell`,
+        ]
+            .map((kind) => get_phonopy_cell(data, kind))
+            .find(Boolean);
         if (auto_cell)
             return convert_phonopy_cell(auto_cell);
-        console.error(`No valid cells found in phonopy YAML`);
+        diag_error(`No valid cells found in phonopy YAML`);
         return null;
     }
     catch (error) {
-        console.error(`Error parsing phonopy YAML:`, error);
+        diag_error(`Error parsing phonopy YAML`, error);
         return null;
     }
 }
@@ -961,8 +977,8 @@ function find_structure_in_json(obj, visited = new WeakSet()) {
     }
     return null;
 }
-// Type guard to validate structure-like objects
-function is_parsed_structure(obj) {
+// Type guard to validate structure-like objects (sites array with species + coordinates)
+export function is_parsed_structure(obj) {
     if (!obj || typeof obj !== `object`)
         return false;
     const sites = `sites` in obj ? obj.sites : undefined;
@@ -978,6 +994,31 @@ function is_parsed_structure(obj) {
     const has_coords = Array.isArray(abc) || Array.isArray(xyz);
     return has_species && has_coords;
 }
+// Structure JSON serialized by pymatgen (default verbosity) stores only the lattice
+// matrix + pbc; derive the missing scalar params (a/b/c/angles/volume) from the matrix
+// so downstream consumers (camera auto-fit, density, export) never see NaN.
+export function ensure_lattice_params(structure) {
+    const lattice = structure.lattice;
+    if (!lattice?.matrix)
+        return structure;
+    const params = [
+        lattice.a,
+        lattice.b,
+        lattice.c,
+        lattice.alpha,
+        lattice.beta,
+        lattice.gamma,
+        lattice.volume,
+    ];
+    if (params.every(Number.isFinite))
+        return structure;
+    // The matrix is authoritative: recompute all params from it rather than
+    // trusting a partially-populated (or non-numeric) set of values.
+    return {
+        ...structure,
+        lattice: { ...lattice, ...math.calc_lattice_params(lattice.matrix) },
+    };
+}
 // Normalize structure coordinates: wrap fractional coords to [0,1) and recompute Cartesian
 // Only normalizes when lattice matrix is available to ensure abc/xyz stay consistent
 export function normalize_fractional_coords(structure) {
@@ -1011,17 +1052,14 @@ const detect_json_structure = (content) => {
     }
     // Otherwise try parsing as pymatgen/nested structure JSON
     const structure = find_structure_in_json(parsed);
-    return structure ? normalize_fractional_coords(structure) : null;
+    return structure ? ensure_lattice_params(normalize_fractional_coords(structure)) : null;
 };
-// Auto-detect file format and parse accordingly
-export function parse_structure_file(content, filename) {
+// Internal: auto-detect file format, returns null on failure after recording reasons (see parse error contract at top)
+function parse_structure_file_impl(content, filename) {
     // If a filename is provided, try to detect format by file extension first
     if (filename) {
         // Handle compressed files by removing compression extensions
-        let base_filename = filename.toLowerCase();
-        while (COMPRESSION_EXTENSIONS_REGEX.test(base_filename)) {
-            base_filename = base_filename.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
-        }
+        const base_filename = strip_compression_extensions(filename);
         const ext = base_filename.split(`.`).pop();
         // Try to detect format by file extension
         if (ext === `xyz` || ext === `extxyz`)
@@ -1035,10 +1073,10 @@ export function parse_structure_file(content, filename) {
                 const result = detect_json_structure(content);
                 if (result)
                     return result;
-                console.error(`JSON file does not contain a valid structure format`);
+                diag_error(`JSON file does not contain a valid structure format`);
             }
             catch (error) {
-                console.error(`Error parsing JSON file:`, error);
+                diag_error(`Error parsing JSON file`, error);
             }
             return null;
         }
@@ -1053,49 +1091,40 @@ export function parse_structure_file(content, filename) {
     // Try to auto-detect based on content.
     // JSON detection must come before the line-count guard: minified JSON
     // (e.g. fetched via extensionless blob: object URLs) is a single line.
+    const content_start = content.trimStart();
+    const looks_like_json = content_start.startsWith(`{`) || content_start.startsWith(`[`);
     try {
         const result = detect_json_structure(content);
         if (result)
             return result;
+        if (looks_like_json)
+            diag_error(`JSON content does not contain a valid structure format`);
     }
-    catch {
-        // Not JSON, continue with other format detection
+    catch (error) {
+        // Only swallow silently when content doesn't even look like JSON; otherwise the
+        // syntax error is the most useful failure reason and must be surfaced
+        if (looks_like_json)
+            diag_error(`Invalid JSON`, error);
     }
     const lines = content.trim().split(/\r?\n/);
     if (lines.length < 2) {
-        console.error(`File too short to determine format`);
+        diag_error(`File too short to determine format`);
         return null;
     }
-    // XYZ format detection: first line should be a number, second line is comment
-    const first_line_number = parseInt(lines[0].trim(), 10);
-    if (!isNaN(first_line_number) && first_line_number > 0) {
-        // Check if this looks like XYZ format
-        if (lines.length >= first_line_number + 2) {
-            // Try to parse a coordinate line to see if it looks like XYZ
-            const coord_line_idx = 2; // First coordinate line in XYZ
-            if (coord_line_idx < lines.length) {
-                const parts = lines[coord_line_idx].trim().split(/\s+/);
-                // XYZ format: element symbol followed by 3 coordinates
-                if (parts.length >= 4) {
-                    const first_token = parts[0];
-                    const coords = parts.slice(1, 4);
-                    // Check if first token looks like an element symbol (not a number)
-                    // and the next 3 tokens look like coordinates (numbers)
-                    const is_element_symbol = isNaN(parseInt(first_token, 10)) && first_token.length <= 3;
-                    const are_coordinates = coords.every((coord) => !isNaN(parseFloat(coord)));
-                    if (is_element_symbol && are_coordinates) {
-                        // First token is likely an element symbol, likely XYZ
-                        return parse_xyz(content);
-                    }
-                }
-            }
-        }
-    }
+    // XYZ format detection: first line is a positive atom count, second line is a
+    // comment, and the first coordinate line looks like "<element> <x> <y> <z>"
+    const first_line_number = Math.trunc(parse_leading_num(lines[0]));
+    if (!isNaN(first_line_number) &&
+        first_line_number > 0 &&
+        lines.length >= first_line_number + 2 &&
+        is_xyz_atom_line(lines[2]?.trim().split(/\s+/)))
+        return parse_xyz(content);
     // POSCAR format detection: look for typical structure
     if (lines.length >= 8) {
-        const second_line_number = parseFloat(lines[1].trim());
-        // Second line is a number (scale factor), likely POSCAR
-        if (!isNaN(second_line_number))
+        // Second line starts with a number (scale factor), likely POSCAR. First
+        // token only: POSCAR allows three per-axis scale factors (or trailing
+        // comments) on line 2, and blank lines must not pass
+        if (!isNaN(parse_leading_num(lines[1])))
             return parse_poscar(content);
     }
     // CIF format detection: look for CIF-specific keywords
@@ -1113,38 +1142,48 @@ export function parse_structure_file(content, filename) {
         line.includes(`phonon_supercell:`));
     if (has_phonopy_keywords)
         return parse_phonopy_yaml(content);
-    console.error(`Unable to determine file format`);
+    diag_error(`Unable to determine file format`);
     return null;
 }
-// Universal parser that handles JSON and structure files
+// Auto-detect file format and parse; throws an Error aggregating per-format failure reasons when nothing parses
+export function parse_structure_file(content, filename) {
+    reset_parse_diagnostics();
+    const structure = parse_structure_file_impl(content, filename);
+    if (structure)
+        return structure;
+    throw aggregate_parse_error(filename);
+}
+// Universal parser for JSON and structure files; throws an Error aggregating per-format failure reasons when nothing parses
 export function parse_any_structure(content, filename) {
-    const finalize_structure = (structure) => ({
-        sites: structure.sites,
-        charge: 0,
-        ...(structure.properties && {
-            properties: clone_structure_properties(structure.properties),
-        }),
-        ...(structure.lattice && {
-            lattice: { ...structure.lattice, pbc: [true, true, true] },
-        }),
-    });
-    // Try JSON first, but handle nested structures properly
+    reset_parse_diagnostics();
+    const finalize_structure = (parsed_structure) => {
+        const structure = ensure_lattice_params(parsed_structure);
+        return {
+            sites: structure.sites,
+            charge: 0,
+            ...(structure.properties && {
+                properties: structuredClone(structure.properties),
+            }),
+            ...(structure.lattice && {
+                lattice: { ...structure.lattice, pbc: [true, true, true] },
+            }),
+        };
+    };
+    // Fast path: content is already a serialized structure object
     try {
         const parsed = JSON.parse(content);
-        // Check if it's already a valid structure using proper type guard
         if (is_parsed_structure(parsed)) {
             // Normalize coordinates (wrap fractional to [0,1) and recompute Cartesian)
             return finalize_structure(normalize_fractional_coords(parsed));
         }
-        // If not, use parse_structure_file to find nested structures
-        const structure = parse_structure_file(content, filename);
-        return structure ? finalize_structure(structure) : null;
     }
     catch {
-        // Try structure file formats
-        const parsed = parse_structure_file(content, filename);
-        return parsed ? finalize_structure(parsed) : null;
+        // Not plain JSON — fall through to format detection, which records failure reasons
     }
+    const structure = parse_structure_file_impl(content, filename);
+    if (structure)
+        return finalize_structure(structure);
+    throw aggregate_parse_error(filename);
 }
 // Parse OPTIMADE JSON format
 export function parse_optimade_json(content) {
@@ -1153,16 +1192,80 @@ export function parse_optimade_json(content) {
         return parse_optimade_from_raw(raw);
     }
     catch (error) {
-        console.error(`Error parsing OPTIMADE JSON:`, error);
+        diag_error(`Error parsing OPTIMADE JSON`, error);
         return null;
     }
 }
+// Build sites + lattice shared by parse_optimade_from_raw and optimade_to_crystal.
+// on_invalid controls whether invalid positions are skipped with a warning or throw;
+// site_props extracts per-site mass/concentration from the species list.
+function build_optimade_sites(attrs, opts) {
+    const positions = attrs.cartesian_site_positions ?? [];
+    const species_at_sites = attrs.species_at_sites ?? [];
+    const species_list = Array.isArray(attrs.species) ? attrs.species : undefined;
+    // OPTIMADE stores lattice vectors as rows, so use as-is
+    const lattice_matrix = attrs.lattice_vectors
+        ? matrix3x3_from_rows(attrs.lattice_vectors, `OPTIMADE lattice vector`)
+        : undefined;
+    const lattice_params = lattice_matrix ? math.calc_lattice_params(lattice_matrix) : null;
+    let cart_to_frac = null;
+    if (lattice_matrix && lattice_params) {
+        const converter = cart_to_frac_with_fallback(lattice_matrix, [
+            lattice_params.a,
+            lattice_params.b,
+            lattice_params.c,
+        ]);
+        if (!converter.exact) {
+            diag_warn(`Failed to create exact coordinate converter for OPTIMADE structure`);
+        }
+        cart_to_frac = converter.convert;
+    }
+    const sites = [];
+    for (let idx = 0; idx < positions.length; idx++) {
+        const species_name = species_at_sites[idx];
+        if (!species_name) {
+            if (opts.on_invalid === `throw`)
+                throw new Error(`Missing species for site ${idx}`);
+            diag_warn(`Missing species for site ${idx}, skipping`);
+            continue;
+        }
+        let xyz;
+        try {
+            xyz = vec3_from_values(positions[idx], `OPTIMADE atom position ${idx + 1}`);
+        }
+        catch (error) {
+            if (opts.on_invalid === `throw`)
+                throw error;
+            diag_warn(`Invalid position data at site ${idx}: ${error}`);
+            continue;
+        }
+        const { symbol: element, sym_idx } = resolve_optimade_element(species_name, species_list, idx);
+        // Calculate fractional coordinates if lattice is available
+        const abc = cart_to_frac ? cart_to_frac(xyz) : [0, 0, 0];
+        const site_props = {};
+        if (opts.site_props) {
+            // Extract mass/concentration for the chosen element. sym_idx indexes the (parallel)
+            // chemical_symbols/mass/concentration arrays; -1 (name resolved directly, no
+            // chemical_symbols) falls back to index 0 — the single-element entry.
+            const spec = species_list?.find((entry) => entry.name === species_name);
+            const spec_idx = Math.max(sym_idx, 0);
+            if (spec?.mass?.[spec_idx] !== undefined)
+                site_props.mass = spec.mass[spec_idx];
+            if (spec?.concentration?.[spec_idx] !== undefined &&
+                spec.concentration[spec_idx] !== 1) {
+                site_props.concentration = spec.concentration[spec_idx];
+            }
+        }
+        sites.push(make_site(element, abc, xyz, `${element}${idx + 1}`, site_props));
+    }
+    return { sites, lattice_matrix, lattice_params };
+}
 // Parse OPTIMADE from already-parsed JSON
 export function parse_optimade_from_raw(raw) {
     try {
         const structure = extract_optimade_structure_from_raw(raw);
         if (!structure) {
-            console.error(`No valid OPTIMADE structure found in JSON`);
+            diag_error(`No valid OPTIMADE structure found in JSON`);
             return null;
         }
         const attrs = structure.attributes;
@@ -1170,83 +1273,28 @@ export function parse_optimade_from_raw(raw) {
         const positions_raw = attrs.cartesian_site_positions;
         const species_raw = attrs.species_at_sites;
         if (!(Array.isArray(positions_raw) && Array.isArray(species_raw))) {
-            console.error(`OPTIMADE JSON missing required position or species data`);
+            diag_error(`OPTIMADE JSON missing required position or species data`);
             return null;
         }
         if (positions_raw.length !== species_raw.length) {
-            console.error(`OPTIMADE JSON position/species count mismatch`);
+            diag_error(`OPTIMADE JSON position/species count mismatch`);
             return null;
         }
-        const positions = positions_raw;
-        const species = species_raw;
-        // Optimade stores lattice vectors as rows, so use as is
-        const lattice_matrix = attrs.lattice_vectors
-            ? [
-                vec3_from_values(attrs.lattice_vectors[0], `OPTIMADE lattice vector 1`),
-                vec3_from_values(attrs.lattice_vectors[1], `OPTIMADE lattice vector 2`),
-                vec3_from_values(attrs.lattice_vectors[2], `OPTIMADE lattice vector 3`),
-            ]
-            : undefined;
-        const optimade_lattice_params = lattice_matrix
-            ? math.calc_lattice_params(lattice_matrix)
-            : null;
-        // Parse atomic sites
-        const optimade_exact_cart_to_frac = lattice_matrix
-            ? try_create_cart_to_frac(lattice_matrix)
-            : null;
-        const optimade_cart_to_frac = lattice_matrix && optimade_lattice_params
-            ? (optimade_exact_cart_to_frac ??
-                ((xyz) => approximate_cart_to_frac(xyz, [
-                    optimade_lattice_params.a,
-                    optimade_lattice_params.b,
-                    optimade_lattice_params.c,
-                ])))
-            : null;
-        if (lattice_matrix && !optimade_exact_cart_to_frac) {
-            console.warn(`Failed to create exact coordinate converter for OPTIMADE structure`);
-        }
-        const optimade_species = Array.isArray(attrs.species) ? attrs.species : undefined;
-        const sites = [];
-        for (let idx = 0; idx < positions.length; idx++) {
-            const pos = positions[idx];
-            const element_symbol = species[idx];
-            let xyz;
-            try {
-                xyz = vec3_from_values(pos, `OPTIMADE site ${idx} position`);
-            }
-            catch (error) {
-                console.warn(`Invalid position data at site ${idx}: ${error}`);
-                continue;
-            }
-            const { symbol: element } = resolve_optimade_element(element_symbol, optimade_species, idx);
-            // Calculate fractional coordinates if lattice is available
-            const abc = optimade_cart_to_frac ? optimade_cart_to_frac(xyz) : [0, 0, 0];
-            const site = {
-                species: [{ element, occu: 1, oxidation_state: 0 }],
-                abc,
-                xyz,
-                label: `${element}${idx + 1}`,
-                properties: {},
-            };
-            sites.push(site);
-        }
+        const { sites, lattice_matrix, lattice_params } = build_optimade_sites(attrs, {
+            on_invalid: `skip`,
+        });
         if (sites.length === 0) {
-            console.error(`No valid sites found in OPTIMADE JSON`);
+            diag_error(`No valid sites found in OPTIMADE JSON`);
             return null;
         }
-        // Create structure object
-        let lattice;
-        if (lattice_matrix && optimade_lattice_params) {
-            lattice = { matrix: lattice_matrix, ...optimade_lattice_params };
-        }
-        const structure_result = {
+        return {
             sites,
-            ...(lattice && { lattice }),
+            ...(lattice_matrix &&
+                lattice_params && { lattice: { matrix: lattice_matrix, ...lattice_params } }),
         };
-        return structure_result;
     }
     catch (error) {
-        console.error(`Error parsing OPTIMADE JSON:`, error);
+        diag_error(`Error parsing OPTIMADE JSON`, error);
         return null;
     }
 }
@@ -1268,9 +1316,7 @@ function extract_optimade_structure_from_raw(raw) {
     const candidate = Array.isArray(payload) ? payload[0] : payload;
     return is_optimade_structure_object(candidate) ? candidate : null;
 }
-const unwrap_data = (value) => value && typeof value === `object` && `data` in value
-    ? value.data
-    : value;
+const unwrap_data = (value) => value && typeof value === `object` && `data` in value ? value.data : value;
 // Type guard: verify minimal OPTIMADE structure shape
 function is_optimade_structure_object(value) {
     if (!value || typeof value !== `object`)
@@ -1286,47 +1332,18 @@ function is_optimade_structure_object(value) {
 }
 // Convert OPTIMADE structure to Crystal format
 export function optimade_to_crystal(optimade_structure) {
-    const { lattice_vectors, cartesian_site_positions, species_at_sites, species, ...properties } = optimade_structure.attributes;
+    const { lattice_vectors, cartesian_site_positions, species_at_sites, species: _species, // excluded from the properties rest
+    ...properties } = optimade_structure.attributes;
     if (!lattice_vectors || !cartesian_site_positions || !species_at_sites) {
-        console.error(`Missing required OPTIMADE structure data`);
+        diag_error(`Missing required OPTIMADE structure data`);
         return null;
     }
     try {
-        const lattice_matrix = [
-            vec3_from_values(lattice_vectors[0], `OPTIMADE lattice vector 1`),
-            vec3_from_values(lattice_vectors[1], `OPTIMADE lattice vector 2`),
-            vec3_from_values(lattice_vectors[2], `OPTIMADE lattice vector 3`),
-        ];
-        const lattice_params = math.calc_lattice_params(lattice_matrix);
-        const crystal_cart_to_frac = try_create_cart_to_frac(lattice_matrix) ??
-            ((xyz) => approximate_cart_to_frac(xyz, [lattice_params.a, lattice_params.b, lattice_params.c]));
-        const sites = cartesian_site_positions.map((pos, idx) => {
-            const element_symbol = species_at_sites[idx];
-            if (!element_symbol)
-                throw new Error(`Missing species for site ${idx}`);
-            const { symbol: element, sym_idx } = resolve_optimade_element(element_symbol, species, idx);
-            const xyz = vec3_from_values(pos, `OPTIMADE atom position ${idx + 1}`);
-            const abc = crystal_cart_to_frac ? crystal_cart_to_frac(xyz) : [0, 0, 0];
-            // Extract mass/concentration for the chosen element. sym_idx indexes the (parallel)
-            // chemical_symbols/mass/concentration arrays; -1 (name resolved directly, no
-            // chemical_symbols) falls back to index 0 — the single-element entry.
-            const spec = species?.find((entry) => entry.name === element_symbol);
-            const spec_idx = Math.max(sym_idx, 0);
-            const site_props = {};
-            if (spec?.mass?.[spec_idx] !== undefined)
-                site_props.mass = spec.mass[spec_idx];
-            if (spec?.concentration?.[spec_idx] !== undefined &&
-                spec.concentration[spec_idx] !== 1) {
-                site_props.concentration = spec.concentration[spec_idx];
-            }
-            return {
-                species: [{ element, occu: 1, oxidation_state: 0 }],
-                abc,
-                xyz,
-                label: `${element}${idx + 1}`,
-                properties: site_props,
-            };
-        });
+        const { sites, lattice_matrix, lattice_params } = build_optimade_sites(optimade_structure.attributes, { on_invalid: `throw`, site_props: true });
+        if (!lattice_matrix || !lattice_params) {
+            diag_error(`Missing required OPTIMADE structure data`);
+            return null;
+        }
         return {
             sites,
             lattice: { matrix: lattice_matrix, ...lattice_params, pbc: [true, true, true] },
@@ -1335,46 +1352,13 @@ export function optimade_to_crystal(optimade_structure) {
         };
     }
     catch (err) {
-        console.error(`Error converting OPTIMADE to Crystal format:`, err);
+        diag_error(`Error converting OPTIMADE to Crystal format`, err);
         return null;
     }
 }
-// Check if filename indicates a structure file
-export function is_structure_file(filename) {
-    const name = filename.toLowerCase();
-    // Trajectory-only formats (can't be structures)
-    if (/\.(traj|xtc|h5|hdf5)$/i.test(name) || /xdatcar/i.test(name))
-        return false;
-    // Always structure formats
-    if (STRUCTURE_EXTENSIONS_REGEX.test(name))
-        return true;
-    if (VASP_FILES_REGEX.test(name))
-        return true;
-    // .xyz/.extxyz files: structure unless they have trajectory keywords
-    if (/\.(xyz|extxyz)$/i.test(name))
-        return !TRAJ_KEYWORDS_REGEX.test(name);
-    // Keyword-based detection for YAML/XML
-    if (/\.(yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name))
-        return true;
-    // More restrictive keyword detection for JSON files
-    if (/\.json$/i.test(name) &&
-        STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
-        !TRAJ_KEYWORDS_REGEX.test(name) &&
-        !CONFIG_DIRS_REGEX.test(name))
-        return true;
-    // Compressed files - check base filename recursively
-    if (COMPRESSION_EXTENSIONS_REGEX.test(name)) {
-        return is_structure_file(name.replace(COMPRESSION_EXTENSIONS_REGEX, ``));
-    }
-    return false;
-}
 export const detect_structure_type = (filename, content) => {
-    const lower_filename = filename.toLowerCase();
     // Normalize compressed suffixes (gz, gzip, zip, xz, bz2) for detection parity
-    let name_to_check = lower_filename;
-    while (COMPRESSION_EXTENSIONS_REGEX.test(name_to_check)) {
-        name_to_check = name_to_check.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
-    }
+    const name_to_check = strip_compression_extensions(filename);
     if (name_to_check.endsWith(`.json`)) {
         try {
             const parsed = JSON.parse(content);