matterviz 0.4.0 → 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}`);
@@ -54,11 +83,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 +99,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,7 +110,7 @@ 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 };
 }
@@ -98,20 +127,39 @@ 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 {
         // 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 +177,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)
@@ -183,136 +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`];
-                        }
+        }
+        // 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);
         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
@@ -323,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;
     }
 }
@@ -538,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;
@@ -574,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)
@@ -587,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`))) {
@@ -623,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) {
@@ -653,7 +673,7 @@ 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
@@ -669,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
@@ -677,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.replaceAll(/['"]/g, ``));
-        })
+            .map(split_cif_tokens)
             .filter((tokens) => {
             const { disorder } = header_indices;
             const max_required_idx = Math.max(...required_indices);
@@ -694,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 === 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,9 +731,9 @@ 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
@@ -728,48 +743,32 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         // 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.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 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;
@@ -794,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;
     }
 }
@@ -836,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) {
@@ -851,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);
@@ -872,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
@@ -899,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
@@ -907,7 +885,7 @@ 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
@@ -923,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;
     }
 }
@@ -961,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;
@@ -1013,15 +991,12 @@ const detect_json_structure = (content) => {
     const structure = find_structure_in_json(parsed);
     return structure ? 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 +1010,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,17 +1028,24 @@ 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
@@ -1113,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,
@@ -1128,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) {
@@ -1153,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;
@@ -1170,83 +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 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 +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`)
@@ -1286,47 +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);
-        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,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;
     }
 }
@@ -1369,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);