matterviz 0.3.7 → 0.4.1

package/dist/structure/parse.js

@@ -1,14 +1,43 @@
 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 { FALLBACK_ELEMENTS, is_elem_symbol } from '../element';
+import { strip_compression_extensions } from '../io';
 import * as math from '../math';
 import { wrap_to_unit_cell } from './pbc';
-import { normalize_scientific_notation } from '../utils';
+import { make_site } from './site';
+import { iter_xyz_frames } from '../trajectory/helpers';
+import { normalize_scientific_notation, to_error } from '../utils';
 import { load as yaml_load } from 'js-yaml';
+// === 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);
 const vec3_from_values = (values, context) => {
     if (values?.length !== 3) {
         throw new Error(`Invalid ${context}: expected 3 coordinates, got ${values?.length ?? 0}`);
@@ -41,9 +70,9 @@ function parse_coordinate_line(line) {
         const sanitized = line
             .trim()
             // Add space when '-' follows a digit and precedes a digit or dot
-            .replace(/(\d)-(?=[\d.])/g, `$1 -`)
+            .replaceAll(/(\d)-(?=[\d.])/g, `$1 -`)
             // Revert accidental spaces after exponent markers
-            .replace(/([eE])\s-\s/g, `$1-`);
+            .replaceAll(/([eE])\s-\s/g, `$1-`);
         tokens = sanitized.split(/\s+/);
     }
     if (tokens.length < 3)
@@ -54,13 +83,37 @@ 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
+// species list: highest-concentration entry in chemical_symbols wins, non-element entries
+// like 'vacancy' are skipped, and unresolved names are treated as element symbols.
+// Returns the chosen element plus its index into the species' chemical_symbols
+// (sym_idx = -1 on fallback), so callers can read the matching mass/concentration entry.
+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_elem_symbol(symbol))
+            continue;
+        const conc = spec?.concentration?.[sym_idx] ?? 0;
+        if (!best || conc > best.conc)
+            best = { symbol, conc, sym_idx };
+    }
+    if (best)
+        return { symbol: best.symbol, sym_idx: best.sym_idx };
+    // 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_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);
@@ -74,20 +127,43 @@ const approximate_cart_to_frac = (xyz, axis_lengths) => [
     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) => {
+    const exact_converter = try_create_cart_to_frac(matrix);
+    if (exact_converter)
+        return { convert: exact_converter, exact: true };
+    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 {
-        const lines = content.replace(/^\s+/, ``).split(/\r?\n/);
+        // 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;
         }
-        // Parse scaling factor (line 2)
-        let scale_factor = parseFloat(lines[1]);
+        // 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);
+        const per_axis_scale = scale_vec.length === 3 && !scale_vec.some(isNaN) ? scale_vec : null;
         // Parse lattice vectors (lines 3-5)
         const parse_vector = (line, line_num) => {
             const coords = line.trim().split(/\s+/).map(parse_coordinate);
@@ -98,17 +174,19 @@ export function parse_poscar(content) {
             parse_vector(lines[3], 4),
             parse_vector(lines[4], 5),
         ];
-        // Handle negative scale factor (volume-based scaling)
-        if (scale_factor < 0) {
+        // 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));
-            scale_factor = Math.pow(-scale_factor / volume, 1 / 3);
+            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
-        const scaled_lattice = [
-            math.scale(lattice_vecs[0], scale_factor),
-            math.scale(lattice_vecs[1], scale_factor),
-            math.scale(lattice_vecs[2], scale_factor),
-        ];
+        // Scale lattice vectors (per-axis factors multiply Cartesian components)
+        const axis_scale = per_axis_scale ?? [scale_factor, scale_factor, scale_factor];
+        const apply_axis_scale = (vec) => vec.map((val, axis) => val * axis_scale[axis]);
+        const scaled_lattice = lattice_vecs.map(apply_axis_scale);
         // Parse element symbols and atom counts (may span multiple lines)
         let line_index = 5;
         let element_symbols = [];
@@ -116,7 +194,7 @@ export function parse_poscar(content) {
         // 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);
+        const first_token_as_number = parseInt(first_token, 10);
         const has_element_symbols = isNaN(first_token_as_number);
         if (has_element_symbols) {
             // VASP 5+ format - parse element symbols (may span multiple lines)
@@ -126,7 +204,7 @@ export function parse_poscar(content) {
                 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);
+                const next_token_as_number = parseInt(next_line_first_token, 10);
                 if (!isNaN(next_token_as_number)) {
                     symbol_lines = lookahead_idx;
                     break;
@@ -157,144 +235,104 @@ 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`];
-                        }
-                    }
-                    let xyz;
-                    let abc;
-                    if (is_direct) {
-                        // Store fractional coordinates, wrapping to [0, 1) range
-                        abc = wrap_to_unit_cell(coords);
-                        xyz = poscar_frac_to_cart(abc);
-                    }
-                    else {
-                        // Already Cartesian, scale if needed
-                        xyz = math.scale(coords, scale_factor);
-                        const raw_abc = poscar_cart_to_frac
-                            ? poscar_cart_to_frac(xyz)
-                            : approximate_cart_to_frac(xyz, poscar_axis_lengths);
-                        // Wrap fractional coordinates to [0, 1) range
-                        abc = wrap_to_unit_cell(raw_abc);
+        }
+        // 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`];
                     }
-                    const site = {
-                        species: [{ element, occu: 1, oxidation_state: 0 }],
-                        abc,
-                        xyz,
-                        label: `${element}${atom_index + atom_count_idx + 1}`,
-                        properties: selective_dynamics ? { 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;
-        }
-        else {
-            console.error(`Missing coordinate mode line in POSCAR`);
-            return null;
+            atom_index += count;
         }
+        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());
+        const num_atoms = parseInt(lines[0].trim(), 10);
         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
@@ -305,61 +343,54 @@ export function parse_xyz(content) {
         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;
     }
 }
@@ -369,7 +400,7 @@ const parse_symmetry_expression = (expr_input) => {
     const coefficients = [0, 0, 0];
     let translation = 0;
     // Remove all whitespace
-    const expr = expr_input.replace(/\s+/g, ``);
+    const expr = expr_input.replaceAll(/\s+/g, ``);
     if (!expr)
         return { coefficients, translation };
     // Tokenize: split into terms while preserving signs
@@ -480,13 +511,15 @@ const extract_cif_cell_parameters = (text, type, strict = true) => text
     .split(`\n`)
     .filter((line) => line.startsWith(`_${type}`))
     .map((line) => {
-    const tokens = line.split(/\s+/).filter((token) => token.length > 0);
+    // Strip trailing comment (# after whitespace) and take the value right after the tag
+    const sans_comment = line.replace(/\s#.*$/, ``);
+    const tokens = sans_comment.split(/\s+/).filter(Boolean);
     if (tokens.length < 2) {
         if (strict)
             throw new Error(`Invalid CIF cell parameter line format: ${line}`);
         return null;
     }
-    const value = parseFloat((tokens.at(-1) ?? ``).split(`(`)[0]);
+    const value = parseFloat(tokens[1].split(`(`)[0]);
     if (isNaN(value)) {
         if (strict)
             throw new Error(`Invalid CIF cell parameter in line: ${line}`);
@@ -518,6 +551,23 @@ const build_cif_atom_site_header_indices = (headers) => {
     });
     return indices;
 };
+// 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;
@@ -541,11 +591,11 @@ const parse_cif_atom_data = (raw_data, indices, coords_type) => {
     const occu = occupancy >= 0 && raw_data[occupancy]
         ? parseFloat(raw_data[occupancy].split(`(`)[0]) || 1.0
         : 1.0;
-    const element_symbol = (symbol >= 0 && /^([A-Z][a-z]*)/.exec(raw_data[symbol])?.[1]) ||
-        raw_data[label]?.match(/([A-Z][a-z]*)/g)?.[0] ||
-        (() => {
-            throw new Error(`Could not extract element symbol from: ${raw_data.join(` `)}`);
-        })();
+    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];
+    if (!element_symbol) {
+        throw new Error(`Could not extract element symbol from: ${raw_data.join(` `)}`);
+    }
     return {
         id: raw_data[label],
         element: element_symbol,
@@ -554,12 +604,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)
@@ -567,16 +617,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`))) {
@@ -603,10 +645,8 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 (indices_preview.cart_x !== undefined &&
                     indices_preview.cart_y !== undefined &&
                     indices_preview.cart_z !== undefined);
-            if (!has_coords) {
-                ii = jj - 1;
+            if (!has_coords)
                 continue;
-            }
             // This is the desired atom-site loop with coordinates: collect data lines
             atom_headers = headers;
             while (jj < lines.length) {
@@ -617,7 +657,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                     if (line.startsWith(`;`)) {
                         let multi_line_data = ``;
                         while (jj < lines.length && !lines[jj].trim().endsWith(`;`)) {
-                            multi_line_data += lines[jj] + `\n`;
+                            multi_line_data += `${lines[jj]}\n`;
                             jj++;
                         }
                         multi_line_data += lines[jj];
@@ -632,8 +672,8 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
             if (atom_data_lines.length > 0)
                 break;
         }
-        if (!atom_headers.length || !atom_data_lines.length) {
-            console.error(`No valid atom site loop found in CIF file`);
+        if (atom_headers.length === 0 || atom_data_lines.length === 0) {
+            diag_error(`No valid atom site loop found in CIF file`);
             return null;
         }
         // Parse atom data with error handling
@@ -649,7 +689,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 ? `cart`
                 : null;
         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
@@ -657,12 +697,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
             ? [header_indices.x, header_indices.y, header_indices.z]
             : [header_indices.cart_x, header_indices.cart_y, header_indices.cart_z];
         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.replace(/['"]/g, ``));
-        })
+            .map(split_cif_tokens)
             .filter((tokens) => {
             const { disorder } = header_indices;
             const max_required_idx = Math.max(...required_indices);
@@ -674,20 +709,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) {
-            console.error(`No valid atoms found in CIF file`);
+        if (atoms.length === 0) {
+            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
@@ -696,60 +731,44 @@ 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);
+        const wrap_vec3 = (vec) => wrap_fractional_coords ? wrap_to_unit_cell(vec) : vec;
         // 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.replace(/\s+/g, ``));
+            .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]];
         // 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_`) {
-                    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.replace(/['"]/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]);
-                            if (sym && !Number.isNaN(num))
-                                map[sym] = num;
-                        }
-                        lj++;
-                    }
+        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;
+                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 = /^([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))
+                        atom_type_counts[sym] = num;
                 }
             }
-            return map;
-        })();
+            break;
+        }
         const observed_counts = {};
         for (const atom of atoms) {
             observed_counts[atom.element] = (observed_counts[atom.element] || 0) + 1;
@@ -774,41 +793,26 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
             }
             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]));
+                const atom_abc = wrap_vec3(cart_to_frac(xyz_base));
                 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],
-                    ]);
-                    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: {},
-                    });
-                }
+                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(make_site(element, abc, xyz, equiv_atom.id, {}, equiv_atom.occupancy));
             }
         }
         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;
     }
 }
@@ -816,11 +820,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) {
@@ -831,9 +831,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);
@@ -852,7 +850,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
@@ -879,7 +877,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
@@ -887,10 +885,8 @@ export function parse_phonopy_yaml(content, cell_type) {
             const cell = get_phonopy_cell(data, cell_type);
             if (cell)
                 return convert_phonopy_cell(cell);
-            else {
-                console.error(`Requested cell type '${cell_type}' not found in phonopy YAML`);
-                return null;
-            }
+            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)
@@ -905,11 +901,11 @@ export function parse_phonopy_yaml(content, cell_type) {
             get_phonopy_cell(data, `primitive_cell`);
         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;
     }
 }
@@ -943,8 +939,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;
@@ -982,15 +978,25 @@ export function normalize_fractional_coords(structure) {
     });
     return { ...structure, sites: normalized_sites };
 }
-// Auto-detect file format and parse accordingly
-export function parse_structure_file(content, filename) {
+// Detect a structure inside already-stringified JSON (OPTIMADE or pymatgen/nested).
+// Throws if `content` isn't valid JSON; returns null if it holds no known structure.
+const detect_json_structure = (content) => {
+    const parsed = JSON.parse(content);
+    if (is_optimade_raw(parsed)) {
+        const result = parse_optimade_from_raw(parsed);
+        if (result)
+            return result;
+    }
+    // Otherwise try parsing as pymatgen/nested structure JSON
+    const structure = find_structure_in_json(parsed);
+    return structure ? normalize_fractional_coords(structure) : null;
+};
+// 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`)
@@ -998,27 +1004,18 @@ export function parse_structure_file(content, filename) {
         // CIF files
         if (ext === `cif`)
             return parse_cif(content);
-        // JSON files - try OPTIMADE JSON structure format first, then pymatgen
+        // JSON files - extension is authoritative, so failures return null
         if (ext === `json`) {
             try {
-                // Parse once, reuse for detection and parsing
-                const parsed = JSON.parse(content);
-                if (is_optimade_raw(parsed)) {
-                    const result = parse_optimade_from_raw(parsed);
-                    if (result)
-                        return result;
-                }
-                // Otherwise, try to parse as pymatgen/nested structure JSON
-                const structure = find_structure_in_json(parsed);
-                if (structure)
-                    return normalize_fractional_coords(structure);
-                console.error(`JSON file does not contain a valid structure format`);
-                return null;
+                const result = detect_json_structure(content);
+                if (result)
+                    return result;
+                diag_error(`JSON file does not contain a valid structure format`);
             }
             catch (error) {
-                console.error(`Error parsing JSON file:`, error);
-                return null;
+                diag_error(`Error parsing JSON file`, error);
             }
+            return null;
         }
         // YAML files (phonopy)
         if (ext === `yaml` || ext === `yml`)
@@ -1028,31 +1025,31 @@ export function parse_structure_file(content, filename) {
             return parse_poscar(content);
         }
     }
-    // Try to auto-detect based on content
+    // 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 (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;
     }
-    // JSON format detection: try to parse as JSON first
-    try {
-        const parsed = JSON.parse(content);
-        if (is_optimade_raw(parsed)) {
-            const result = parse_optimade_from_raw(parsed);
-            if (result)
-                return result;
-        }
-        // Otherwise try parsing as regular JSON structure
-        const structure = find_structure_in_json(parsed);
-        if (structure) {
-            return normalize_fractional_coords(structure);
-        }
-    }
-    catch {
-        // Not JSON, continue with other format detection
-    }
     // XYZ format detection: first line should be a number, second line is comment
-    const first_line_number = parseInt(lines[0].trim());
+    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) {
@@ -1066,7 +1063,7 @@ export function parse_structure_file(content, filename) {
                     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)) && first_token.length <= 3;
+                    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
@@ -1098,11 +1095,20 @@ 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) {
+    reset_parse_diagnostics();
     const finalize_structure = (structure) => ({
         sites: structure.sites,
         charge: 0,
@@ -1113,23 +1119,21 @@ export function parse_any_structure(content, filename) {
             lattice: { ...structure.lattice, pbc: [true, true, true] },
         }),
     });
-    // Try JSON first, but handle nested structures properly
+    // 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) {
@@ -1138,16 +1142,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;
@@ -1155,82 +1223,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 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 element = validate_element_symbol(element_symbol, 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;
     }
 }
@@ -1252,9 +1266,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`)
@@ -1270,45 +1282,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);
-        // Build species lookup for site properties (mass, concentration, etc.)
-        const species_map = new Map(species?.map((spec) => [spec.name, spec]));
-        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 element = validate_element_symbol(element_symbol, 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 from species data
-            const spec = species_map.get(element_symbol);
-            const site_props = {};
-            if (spec?.mass?.[0] !== undefined)
-                site_props.mass = spec.mass[0];
-            if (spec?.concentration?.[0] !== undefined && spec.concentration[0] !== 1) {
-                site_props.concentration = spec.concentration[0];
-            }
-            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] },
@@ -1317,7 +1302,7 @@ 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;
     }
 }
@@ -1351,12 +1336,8 @@ export function is_structure_file(filename) {
     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);