matterviz 0.3.5 → 0.3.6

package/dist/structure/parse.js

@@ -1,1363 +0,0 @@
-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 * as math from '../math';
-import { wrap_to_unit_cell } from './pbc';
-import { normalize_scientific_notation } from '../utils';
-import { load as yaml_load } from 'js-yaml';
-// Parse a coordinate value that might be in various scientific notation formats
-function parse_coordinate(str) {
-    const normalized = normalize_scientific_notation(str.trim());
-    const value = parseFloat(normalized);
-    if (isNaN(value))
-        throw new Error(`Invalid coordinate value: ${str}`);
-    return value;
-}
-// Parse coordinates from a line, handling malformed formatting
-function parse_coordinate_line(line) {
-    let tokens = line.trim().split(/\s+/);
-    // Handle malformed coordinates like "1.0-2.0-3.0" (missing spaces)
-    if (tokens.length < 3) {
-        // Insert a space only for subtraction between numbers, not exponent signs (e/E)
-        const sanitized = line
-            .trim()
-            // Add space when '-' follows a digit and precedes a digit or dot
-            .replace(/(\d)-(?=[\d.])/g, `$1 -`)
-            // Revert accidental spaces after exponent markers
-            .replace(/([eE])\s-\s/g, `$1-`);
-        tokens = sanitized.split(/\s+/);
-    }
-    if (tokens.length < 3)
-        throw new Error(`Insufficient coordinates in line: ${line}`);
-    return tokens.slice(0, 3).map(parse_coordinate);
-}
-// Validate element symbol and provide fallback
-function validate_element_symbol(symbol, index) {
-    // Clean symbol (remove suffixes like _pv, /hash)
-    const clean_symbol = symbol.split(/[_/]/)[0];
-    if (ELEM_SYMBOLS && ELEM_SYMBOLS.includes(clean_symbol)) {
-        return clean_symbol;
-    }
-    // Fallback to default elements by atomic number
-    const fallback_elements = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`];
-    const fallback = fallback_elements[index % fallback_elements.length];
-    console.warn(`Invalid element symbol '${symbol}', using fallback '${fallback}'`);
-    return fallback;
-}
-const try_create_cart_to_frac = (lattice_matrix) => {
-    try {
-        return math.create_cart_to_frac(lattice_matrix);
-    }
-    catch {
-        return null;
-    }
-};
-const approximate_cart_to_frac = (xyz, axis_lengths) => [
-    Math.abs(axis_lengths[0]) > math.EPS ? xyz[0] / axis_lengths[0] : 0,
-    Math.abs(axis_lengths[1]) > math.EPS ? xyz[1] / axis_lengths[1] : 0,
-    Math.abs(axis_lengths[2]) > math.EPS ? xyz[2] / axis_lengths[2] : 0,
-];
-// Parse VASP POSCAR file format
-export function parse_poscar(content) {
-    try {
-        const lines = content.replace(/^\s+/, ``).split(/\r?\n/);
-        if (lines.length < 8) {
-            console.error(`POSCAR file too short`);
-            return null;
-        }
-        // Parse scaling factor (line 2)
-        let scale_factor = parseFloat(lines[1]);
-        if (isNaN(scale_factor)) {
-            console.error(`Invalid scaling factor in POSCAR`);
-            return null;
-        }
-        // Parse lattice vectors (lines 3-5)
-        const parse_vector = (line, line_num) => {
-            const coords = line.trim().split(/\s+/).map(parse_coordinate);
-            if (coords.length !== 3) {
-                throw new Error(`Invalid lattice vector on line ${line_num}: expected 3 coordinates, got ${coords.length}`);
-            }
-            return coords;
-        };
-        const lattice_vecs = [
-            parse_vector(lines[2], 3),
-            parse_vector(lines[3], 4),
-            parse_vector(lines[4], 5),
-        ];
-        // Handle negative scale factor (volume-based scaling)
-        if (scale_factor < 0) {
-            const volume = Math.abs(math.det_3x3(lattice_vecs));
-            scale_factor = Math.pow(-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),
-        ];
-        // Parse element symbols and atom counts (may span multiple lines)
-        let line_index = 5;
-        let element_symbols = [];
-        let atom_counts = [];
-        // Detect if this is VASP 5+ format (has element symbols)
-        // Try to parse the first token as a number - if it succeeds, it's VASP 4 format
-        const first_token = lines[line_index].trim().split(/\s+/)[0];
-        const first_token_as_number = parseInt(first_token);
-        const has_element_symbols = isNaN(first_token_as_number);
-        if (has_element_symbols) {
-            // VASP 5+ format - parse element symbols (may span multiple lines)
-            let symbol_lines = 1;
-            // Look ahead to find where numbers start (atom counts)
-            for (let lookahead_idx = 1; lookahead_idx < 10; lookahead_idx++) {
-                if (line_index + lookahead_idx >= lines.length)
-                    break;
-                const next_line_first_token = lines[line_index + lookahead_idx].trim().split(/\s+/)[0];
-                const next_token_as_number = parseInt(next_line_first_token);
-                if (!isNaN(next_token_as_number)) {
-                    symbol_lines = lookahead_idx;
-                    break;
-                }
-            }
-            // Collect all element symbols from the symbol lines
-            for (let symbol_line_idx = 0; symbol_line_idx < symbol_lines; symbol_line_idx++) {
-                if (line_index + symbol_line_idx < lines.length) {
-                    element_symbols.push(...lines[line_index + symbol_line_idx].trim().split(/\s+/));
-                }
-            }
-            // Parse atom counts (may span multiple lines)
-            for (let count_line_idx = 0; count_line_idx < symbol_lines; count_line_idx++) {
-                if (line_index + symbol_lines + count_line_idx < lines.length) {
-                    const counts = lines[line_index + symbol_lines + count_line_idx]
-                        .trim()
-                        .split(/\s+/)
-                        .map(Number);
-                    atom_counts.push(...counts);
-                }
-            }
-            line_index += 2 * symbol_lines;
-        }
-        else {
-            // VASP 4 format - only atom counts, generate default element symbols
-            atom_counts = lines[line_index].trim().split(/\s+/).map(Number);
-            element_symbols = atom_counts.map((_, idx) => validate_element_symbol(`Element${idx}`, idx));
-            line_index += 1;
-        }
-        if (element_symbols.length !== atom_counts.length) {
-            console.error(`Mismatch between element symbols and atom counts`);
-            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;
-                }
-            }
-            // 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}`);
-                return null;
-            }
-            // Parse atomic positions
-            const poscar_axis_lengths = scaled_lattice.map((lattice_vec) => Math.hypot(...lattice_vec));
-            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 = parse_coordinate_line(lines[coord_line_idx]);
-                    // 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;
-                    const [x, y, z] = coords;
-                    if (is_direct) {
-                        // Store fractional coordinates, wrapping to [0, 1) range
-                        abc = wrap_to_unit_cell([x, y, z]);
-                        xyz = poscar_frac_to_cart(abc);
-                    }
-                    else {
-                        // Already Cartesian, scale if needed
-                        xyz = math.scale([x, y, z], 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);
-                    }
-                    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;
-            }
-            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;
-        }
-    }
-    catch (error) {
-        console.error(`Error parsing POSCAR file:`, error);
-        return null;
-    }
-}
-// Parse XYZ file format. Supports both standard XYZ and extended XYZ formats with multi-frame support
-export function parse_xyz(content) {
-    try {
-        const normalized_content = content.trim();
-        if (!normalized_content) {
-            console.error(`Empty XYZ file`);
-            return null;
-        }
-        // Split into frames by reading the atom count and slicing lines
-        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/);
-        if (lines.length < 2) {
-            console.error(`XYZ frame too short`);
-            return null;
-        }
-        // Parse number of atoms (line 1)
-        const num_atoms = parseInt(lines[0].trim());
-        if (isNaN(num_atoms) || num_atoms <= 0) {
-            console.error(`Invalid number of atoms in XYZ file`);
-            return null;
-        }
-        // Parse comment line (line 2) - may contain lattice info for extended XYZ
-        const comment_line = lines[1];
-        let lattice;
-        // Check for extended XYZ lattice information in comment line
-        const lattice_match = /Lattice="([^"]+)"/.exec(comment_line);
-        if (lattice_match) {
-            const lattice_values = lattice_match[1].split(/\s+/).map(parse_coordinate);
-            if (lattice_values.length === 9) {
-                const lattice_vectors = [
-                    [lattice_values[0], lattice_values[1], lattice_values[2]],
-                    [lattice_values[3], lattice_values[4], lattice_values[5]],
-                    [lattice_values[6], lattice_values[7], lattice_values[8]],
-                ];
-                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);
-        }
-        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`);
-                return null;
-            }
-            const parts = lines[line_idx].trim().split(/\s+/);
-            if (parts.length < 4) {
-                console.error(`Invalid coordinate line in XYZ file`);
-                return null;
-            }
-            const element = validate_element_symbol(parts[0], atom_idx);
-            const coords = [
-                parse_coordinate(parts[1]),
-                parse_coordinate(parts[2]),
-                parse_coordinate(parts[3]),
-            ];
-            // For XYZ files, coordinates are typically in Cartesian
-            const xyz = [coords[0], coords[1], coords[2]];
-            // 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);
-                // Ensure fractional coordinates are wrapped into [0, 1) for consistency
-                abc = wrap_to_unit_cell(abc);
-                // 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);
-        }
-        const structure = { sites, ...(lattice && { lattice }) };
-        return structure;
-    }
-    catch (error) {
-        console.error(`Error parsing XYZ file:`, error);
-        return null;
-    }
-}
-// Parse a single symmetry expression dimension (e.g., "x-y+1/3" or "-x+y")
-// Returns the numeric coefficient for each variable and the translation constant
-const parse_symmetry_expression = (expr_input) => {
-    const coefficients = [0, 0, 0];
-    let translation = 0;
-    // Remove all whitespace
-    const expr = expr_input.replace(/\s+/g, ``);
-    if (!expr)
-        return { coefficients, translation };
-    // Tokenize: split into terms while preserving signs
-    // E.g., "x-y+1/3" → ["x", "-y", "+1/3"] or "-x+y" → ["-x", "+y"]
-    const tokens = [];
-    let current_token = ``;
-    for (let idx = 0; idx < expr.length; idx++) {
-        const char = expr[idx];
-        if ((char === `+` || char === `-`) && current_token.length > 0) {
-            tokens.push(current_token);
-            current_token = char;
-        }
-        else {
-            current_token += char;
-        }
-    }
-    if (current_token)
-        tokens.push(current_token);
-    for (const token of tokens) {
-        // Check if this token is a variable term (x, y, or z with optional sign)
-        const var_match = /^([+-]?)([xyz])$/.exec(token);
-        if (var_match) {
-            const sign = var_match[1] === `-` ? -1 : 1;
-            const var_char = var_match[2];
-            const var_idx = var_char === `x` ? 0 : var_char === `y` ? 1 : 2;
-            coefficients[var_idx] += sign;
-            continue;
-        }
-        // Check if this is a numeric term (integer, decimal, or fraction)
-        let sign = 1;
-        let num_str = token;
-        // Handle leading sign
-        if (num_str.startsWith(`+`)) {
-            num_str = num_str.slice(1);
-        }
-        else if (num_str.startsWith(`-`)) {
-            sign = -1;
-            num_str = num_str.slice(1);
-        }
-        // Skip empty tokens (from dangling operators like "x+")
-        if (!num_str || num_str === `+` || num_str === `-`)
-            continue;
-        if (num_str.includes(`/`)) {
-            // Fraction
-            const parts = num_str.split(`/`);
-            if (parts.length === 2) {
-                const numerator = parseFloat(parts[0]);
-                const denominator = parseFloat(parts[1]);
-                if (!isNaN(numerator) && !isNaN(denominator) && denominator !== 0) {
-                    translation += sign * (numerator / denominator);
-                }
-            }
-        }
-        else {
-            // Integer or decimal
-            const val = parseFloat(num_str);
-            if (!isNaN(val)) {
-                translation += sign * val;
-            }
-        }
-    }
-    return { coefficients, translation };
-};
-// Apply symmetry operations to generate equivalent positions
-const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords) => {
-    if (symmetry_ops.length === 0)
-        return [atom];
-    const equivalent_atoms = [];
-    const seen = new Set();
-    const wrap = (coords) => wrap_fractional_coords ? wrap_to_unit_cell(coords) : coords;
-    // Use 6 decimal places for deduplication to handle floating point imprecision
-    // from compound symmetry operations like x-y, -x+y which can produce small errors
-    const key = (coords) => `${coords[0].toFixed(6)},${coords[1].toFixed(6)},${coords[2].toFixed(6)}`;
-    // Always include base atom (optionally wrapped)
-    const base_coords = wrap(atom.coords);
-    seen.add(key(base_coords));
-    equivalent_atoms.push({ ...atom, coords: base_coords });
-    for (const operation of symmetry_ops) {
-        const operation_match = /['"]([^'"]+)['"]/.exec(operation);
-        const expr_str = operation_match ? operation_match[1] : operation.trim();
-        const parts = expr_str.split(`,`).map((part) => part.trim());
-        if (parts.length !== 3)
-            continue;
-        const new_coords = [0, 0, 0];
-        for (let dim = 0; dim < 3; dim++) {
-            const { coefficients, translation } = parse_symmetry_expression(parts[dim]);
-            // Apply: new_coord = coeff_x * x + coeff_y * y + coeff_z * z + translation
-            new_coords[dim] =
-                coefficients[0] * atom.coords[0] +
-                    coefficients[1] * atom.coords[1] +
-                    coefficients[2] * atom.coords[2] +
-                    translation;
-        }
-        // Wrap and deduplicate transformed coordinates
-        const wrapped = wrap(new_coords);
-        const cache_key = key(wrapped);
-        if (seen.has(cache_key))
-            continue;
-        seen.add(cache_key);
-        equivalent_atoms.push({
-            ...atom,
-            coords: wrapped,
-            id: `${atom.id}_${equivalent_atoms.length}`,
-        });
-    }
-    return equivalent_atoms;
-};
-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);
-    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]);
-    if (isNaN(value)) {
-        if (strict)
-            throw new Error(`Invalid CIF cell parameter in line: ${line}`);
-        return null; // Return null for invalid values in non-strict mode
-    }
-    return value;
-})
-    .filter((val) => val !== null);
-// build header index mapping for atom site data (supports fract and Cartn coordinates)
-const build_cif_atom_site_header_indices = (headers) => {
-    const indices = {};
-    const mappings = [
-        [`_atom_site_label`, `label`],
-        [`_atom_site_type_symbol`, `symbol`],
-        [`_atom_site_fract_x`, `x`],
-        [`_atom_site_fract_y`, `y`],
-        [`_atom_site_fract_z`, `z`],
-        [`_atom_site_cartn_x`, `cart_x`],
-        [`_atom_site_cartn_y`, `cart_y`],
-        [`_atom_site_cartn_z`, `cart_z`],
-        [`_atom_site_occupancy`, `occupancy`],
-        [`_atom_site_disorder_group`, `disorder`],
-    ];
-    headers.forEach((header, idx) => {
-        const lower = header.trim().toLowerCase();
-        const mapping = mappings.find(([suffix]) => lower.endsWith(suffix));
-        if (mapping)
-            indices[mapping[1]] = idx;
-    });
-    return indices;
-};
-// Parse atom data from CIF with robust error handling
-const parse_cif_atom_data = (raw_data, indices, coords_type) => {
-    const { label = 0, symbol = -1, occupancy = -1 } = indices;
-    const coord_indices = coords_type === `fract`
-        ? [indices.x, indices.y, indices.z]
-        : [indices.cart_x, indices.cart_y, indices.cart_z];
-    if (coord_indices.some((idx) => idx === undefined)) {
-        throw new Error(`Missing coordinate indices`);
-    }
-    const coords_triplet = coord_indices.map((idx) => {
-        if (idx === undefined)
-            throw new Error(`Invalid coordinate index`);
-        const coord_str = raw_data[idx];
-        if (!coord_str)
-            throw new Error(`Missing coordinate at index ${idx}`);
-        const coord = parseFloat(coord_str.split(`(`)[0]);
-        if (isNaN(coord))
-            throw new Error(`Invalid coordinate: ${coord_str}`);
-        return coord;
-    });
-    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(` `)}`);
-        })();
-    return {
-        id: raw_data[label],
-        element: element_symbol,
-        coords: coords_triplet,
-        coords_type,
-        occupancy: occu,
-    };
-};
-// Parse CIF (Crystallographic Information File) format
-export function parse_cif(content, wrap_fractional_coords = true, strict = true) {
-    try {
-        const text = content.trim();
-        if (!text) {
-            console.error(`CIF file is empty`);
-            return null;
-        }
-        // Find atom site loop that actually contains coordinates (fract or Cartn)
-        const lines = text.split(`\n`);
-        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++;
-            }
-            // 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`))) {
-                // Collect symmetry operations
-                while (jj < lines.length) {
-                    const line = lines[jj].trim();
-                    if (line === `loop_` || line.startsWith(`data_`))
-                        break;
-                    if (line && !line.startsWith(`#`) && !line.startsWith(`;`)) {
-                        symmetry_ops.push(line);
-                    }
-                    jj++;
-                }
-                continue;
-            }
-            // Not an atom-site loop → continue search
-            if (!headers.some((header) => header.includes(`_atom_site_`)))
-                continue;
-            // Check if this loop contains coordinate headers
-            const indices_preview = build_cif_atom_site_header_indices(headers);
-            const has_coords = (indices_preview.x !== undefined &&
-                indices_preview.y !== undefined &&
-                indices_preview.z !== undefined) ||
-                (indices_preview.cart_x !== undefined &&
-                    indices_preview.cart_y !== undefined &&
-                    indices_preview.cart_z !== undefined);
-            if (!has_coords) {
-                ii = jj - 1;
-                continue;
-            }
-            // This is the desired atom-site loop with coordinates: collect data lines
-            atom_headers = headers;
-            while (jj < lines.length) {
-                const line = lines[jj].trim();
-                if (line === `loop_` || line.startsWith(`data_`))
-                    break;
-                if (line && !line.startsWith(`#`)) {
-                    if (line.startsWith(`;`)) {
-                        let multi_line_data = ``;
-                        while (jj < lines.length && !lines[jj].trim().endsWith(`;`)) {
-                            multi_line_data += lines[jj] + `\n`;
-                            jj++;
-                        }
-                        multi_line_data += lines[jj];
-                        atom_data_lines.push(multi_line_data.trim());
-                    }
-                    else {
-                        atom_data_lines.push(line);
-                    }
-                }
-                jj++;
-            }
-            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`);
-            return null;
-        }
-        // Parse atom data with error handling
-        const header_indices = build_cif_atom_site_header_indices(atom_headers);
-        // Determine available coordinate type
-        const coords_type = header_indices.x !== undefined &&
-            header_indices.y !== undefined &&
-            header_indices.z !== undefined
-            ? `fract`
-            : header_indices.cart_x !== undefined &&
-                header_indices.cart_y !== undefined &&
-                header_indices.cart_z !== undefined
-                ? `cart`
-                : null;
-        if (!coords_type) {
-            console.error(`CIF atom site loop missing coordinates (fract or Cartn)`);
-            return null;
-        }
-        // Collect required coordinate indices
-        const required_indices = coords_type === `fract`
-            ? [header_indices.x, header_indices.y, header_indices.z]
-            : [header_indices.cart_x, header_indices.cart_y, header_indices.cart_z];
-        const 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, ``));
-        })
-            .filter((tokens) => {
-            const { disorder } = header_indices;
-            const max_required_idx = Math.max(...required_indices);
-            return (!(disorder !== undefined && tokens[disorder] === `2`) &&
-                tokens.length > max_required_idx);
-        })
-            .map((tokens) => {
-            try {
-                return parse_cif_atom_data(tokens, header_indices, coords_type);
-            }
-            catch (error) {
-                console.warn(`Skipping invalid atom data: ${error}`);
-                return null;
-            }
-        })
-            .filter((atom) => atom !== null);
-        if (!atoms.length) {
-            console.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`);
-            return null;
-        }
-        // Build lattice and create sites
-        const [a, b, c] = lengths;
-        const [alpha, beta, gamma] = angles;
-        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);
-        // Create sites with coordinate conversion and symmetry operations
-        const wrap_vec3 = (v) => (wrap_fractional_coords ? wrap_to_unit_cell(v) : v);
-        // Apply symmetry operations to generate all equivalent positions
-        const all_sites = [];
-        // Normalize symmetry operations (trim/strip quotes) but preserve duplicates; we deduplicate positions later
-        const normalized_ops = symmetry_ops
-            .map((op) => /['"]([^'"]+)['"]/.exec(op)?.[1] || op.trim())
-            .map((op) => op.replace(/\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++;
-                    }
-                    break;
-                }
-            }
-            return map;
-        })();
-        const observed_counts = {};
-        for (const atom of atoms) {
-            observed_counts[atom.element] = (observed_counts[atom.element] || 0) + 1;
-        }
-        const has_expected_counts = Object.keys(atom_type_counts).length > 0;
-        const already_enumerated = has_expected_counts &&
-            Object.entries(atom_type_counts).every(([el, exp]) => (observed_counts[el] || 0) >= exp);
-        const ops_to_use = already_enumerated ? [] : normalized_ops;
-        // Global deduplication of final sites (per element + coordinates + label)
-        // Use 6 decimal places to handle floating point imprecision from compound symmetry ops
-        const seen_site_keys = new Set();
-        const site_key = (element, abc, label) => `${element}|${label}|${abc[0].toFixed(6)},${abc[1].toFixed(6)},${abc[2].toFixed(6)}`;
-        for (const atom of atoms) {
-            const element = validate_element_symbol(atom.element, all_sites.length);
-            // Convert to fractional coordinates if needed
-            let fractional_atom;
-            if (atom.coords_type === `fract`) {
-                fractional_atom = {
-                    ...atom,
-                    coords: wrap_vec3(atom.coords),
-                    coords_type: `fract`,
-                };
-            }
-            else {
-                const xyz_base = [atom.coords[0], atom.coords[1], atom.coords[2]];
-                const atom_abc = wrap_vec3(cart_to_frac
-                    ? cart_to_frac(xyz_base)
-                    : approximate_cart_to_frac(xyz_base, [a, b, c]));
-                fractional_atom = { ...atom, coords: atom_abc, coords_type: `fract` };
-            }
-            // First apply symmetry operations in fractional space
-            const equiv_atoms = apply_symmetry_ops(fractional_atom, ops_to_use, wrap_fractional_coords);
-            // Then apply lattice centering shifts to each equivalent position
-            for (const equiv_atom of equiv_atoms) {
-                for (const cv of centering_vectors) {
-                    const abc = wrap_vec3([
-                        equiv_atom.coords[0] + cv[0],
-                        equiv_atom.coords[1] + cv[1],
-                        equiv_atom.coords[2] + cv[2],
-                    ]);
-                    const key = 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 sites = all_sites;
-        return { sites, lattice: { matrix: lattice_matrix, ...lattice_params } };
-    }
-    catch (error) {
-        console.error(`Error parsing CIF file:`, error);
-        return null;
-    }
-}
-// Convert phonopy cell to ParsedStructure
-function convert_phonopy_cell(cell) {
-    const sites = [];
-    // Phonopy stores lattice vectors as rows, use them directly
-    const lattice_matrix = cell.lattice;
-    // Process each atomic site
-    const phonopy_frac_to_cart = math.create_frac_to_cart(lattice_matrix);
-    for (const point of cell.points) {
-        const element = validate_element_symbol(point.symbol, sites.length);
-        const abc = [point.coordinates[0], point.coordinates[1], point.coordinates[2]];
-        const xyz = phonopy_frac_to_cart(abc);
-        const properties = {
-            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);
-    }
-    // Calculate lattice parameters
-    const calculated_lattice_params = math.calc_lattice_params(lattice_matrix);
-    return { sites, lattice: { matrix: lattice_matrix, ...calculated_lattice_params } };
-}
-// Parse phonopy YAML file and return the 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
-        const lines = content.split(`\n`);
-        const filtered_lines = [];
-        let skip_displacements = false;
-        for (const line of lines) {
-            // Skip phonon_displacements section for performance
-            if (line.trim().startsWith(`phonon_displacements:`)) {
-                skip_displacements = true;
-                continue;
-            }
-            // Check if we're still in the phonon_displacements section
-            if (skip_displacements) {
-                if (/^[a-zA-Z_]/.exec(line)) {
-                    // New top-level key, stop skipping
-                    skip_displacements = false;
-                }
-                else
-                    continue; // Still in phonon_displacements, skip this line
-            }
-            filtered_lines.push(line);
-        }
-        const filtered_content = filtered_lines.join(`\n`);
-        const data = yaml_load(filtered_content);
-        if (!data) {
-            console.error(`Failed to parse phonopy YAML`);
-            return null;
-        }
-        // If specific cell type requested, parse only that one
-        if (cell_type && cell_type !== `auto`) {
-            const 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;
-            }
-        }
-        // Auto mode: return preferred structure in order of preference
-        // 1. supercell (most detailed)
-        // 2. phonon_supercell
-        // 3. unit_cell
-        // 4. phonon_primitive_cell
-        // 5. primitive_cell
-        if (data.supercell)
-            return convert_phonopy_cell(data.supercell);
-        else if (data.phonon_supercell)
-            return convert_phonopy_cell(data.phonon_supercell);
-        else if (data.unit_cell)
-            return convert_phonopy_cell(data.unit_cell);
-        else if (data.phonon_primitive_cell) {
-            return convert_phonopy_cell(data.phonon_primitive_cell);
-        }
-        else if (data.primitive_cell)
-            return convert_phonopy_cell(data.primitive_cell);
-        console.error(`No valid cells found in phonopy YAML`);
-        return null;
-    }
-    catch (error) {
-        console.error(`Error parsing phonopy YAML:`, error);
-        return null;
-    }
-}
-// Recursively search for a valid structure object in nested JSON
-function find_structure_in_json(obj, visited = new WeakSet()) {
-    // Check if current object is null or undefined
-    if (obj == null)
-        return null;
-    if (typeof obj !== `object`)
-        return null; // If it's not an object, skip it
-    if (visited.has(obj))
-        return null; // Check for circular references
-    visited.add(obj);
-    // If it's an array, search through each element
-    if (Array.isArray(obj)) {
-        for (const item of obj) {
-            const result = find_structure_in_json(item, visited);
-            if (result)
-                return result;
-        }
-        return null;
-    }
-    // Check if this object looks like a valid structure
-    if (is_parsed_structure(obj))
-        return obj;
-    // Otherwise, recursively search through all properties
-    for (const value of Object.values(obj)) {
-        const result = find_structure_in_json(value, visited);
-        if (result)
-            return result;
-    }
-    return null;
-}
-// Type guard to validate structure-like objects
-function is_parsed_structure(obj) {
-    if (!obj || typeof obj !== `object`)
-        return false;
-    const parsed_obj = obj;
-    const sites = parsed_obj.sites;
-    if (!Array.isArray(sites) || sites.length === 0)
-        return false;
-    const first_site = sites[0];
-    if (!first_site || typeof first_site !== `object`)
-        return false;
-    const first_site_obj = first_site;
-    const species = first_site_obj.species;
-    const abc = first_site_obj.abc;
-    const xyz = first_site_obj.xyz;
-    const has_species = Array.isArray(species) && species.length > 0;
-    const has_coords = Array.isArray(abc) || Array.isArray(xyz);
-    return has_species && has_coords;
-}
-// Normalize structure coordinates: wrap fractional coords to [0,1) and recompute Cartesian
-// Only normalizes when lattice matrix is available to ensure abc/xyz stay consistent
-export function normalize_fractional_coords(structure) {
-    if (!structure.sites || structure.sites.length === 0)
-        return structure;
-    // Require lattice to ensure we can keep abc and xyz consistent after wrapping
-    if (!structure.lattice?.matrix)
-        return structure;
-    // Check if any sites have fractional coords outside [0, 1) range
-    const needs_wrapping = structure.sites.some((site) => site.abc?.some((coord) => coord < 0 || coord >= 1));
-    if (!needs_wrapping)
-        return structure;
-    const frac_to_cart = math.create_frac_to_cart(structure.lattice.matrix);
-    // Wrap fractional coordinates and recompute Cartesian
-    const normalized_sites = structure.sites.map((site) => {
-        if (!site.abc)
-            return site;
-        const wrapped_abc = wrap_to_unit_cell(site.abc);
-        return { ...site, abc: wrapped_abc, xyz: frac_to_cart(wrapped_abc) };
-    });
-    return { ...structure, sites: normalized_sites };
-}
-// Auto-detect file format and parse accordingly
-export function parse_structure_file(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 ext = base_filename.split(`.`).pop();
-        // Try to detect format by file extension
-        if (ext === `xyz` || ext === `extxyz`)
-            return parse_xyz(content);
-        // CIF files
-        if (ext === `cif`)
-            return parse_cif(content);
-        // JSON files - try OPTIMADE JSON structure format first, then pymatgen
-        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;
-            }
-            catch (error) {
-                console.error(`Error parsing JSON file:`, error);
-                return null;
-            }
-        }
-        // YAML files (phonopy)
-        if (ext === `yaml` || ext === `yml`)
-            return parse_phonopy_yaml(content);
-        // POSCAR files may not have extensions or have various names
-        if (ext === `poscar` || base_filename.includes(`poscar`)) {
-            return parse_poscar(content);
-        }
-    }
-    // Try to auto-detect based on content
-    const lines = content.trim().split(/\r?\n/);
-    if (lines.length < 2) {
-        console.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());
-    if (!isNaN(first_line_number) && first_line_number > 0) {
-        // Check if this looks like XYZ format
-        if (lines.length >= first_line_number + 2) {
-            // Try to parse a coordinate line to see if it looks like XYZ
-            const coord_line_idx = 2; // First coordinate line in XYZ
-            if (coord_line_idx < lines.length) {
-                const parts = lines[coord_line_idx].trim().split(/\s+/);
-                // XYZ format: element symbol followed by 3 coordinates
-                if (parts.length >= 4) {
-                    const first_token = parts[0];
-                    const coords = parts.slice(1, 4);
-                    // Check if first token looks like an element symbol (not a number)
-                    // and the next 3 tokens look like coordinates (numbers)
-                    const is_element_symbol = isNaN(parseInt(first_token)) && first_token.length <= 3;
-                    const are_coordinates = coords.every((coord) => !isNaN(parseFloat(coord)));
-                    if (is_element_symbol && are_coordinates) {
-                        // First token is likely an element symbol, likely XYZ
-                        return parse_xyz(content);
-                    }
-                }
-            }
-        }
-    }
-    // POSCAR format detection: look for typical structure
-    if (lines.length >= 8) {
-        const second_line_number = parseFloat(lines[1].trim());
-        // Second line is a number (scale factor), likely POSCAR
-        if (!isNaN(second_line_number))
-            return parse_poscar(content);
-    }
-    // CIF format detection: look for CIF-specific keywords
-    const has_cif_keywords = lines.some((line) => line.startsWith(`data_`) ||
-        line.includes(`_cell_length_`) ||
-        line.includes(`_atom_site_`) ||
-        line.trim() === `loop_`);
-    if (has_cif_keywords)
-        return parse_cif(content);
-    // YAML format detection: look for phonopy-specific keywords
-    const has_phonopy_keywords = lines.some((line) => line.includes(`phono3py:`) ||
-        line.includes(`phonopy:`) ||
-        line.includes(`primitive_cell:`) ||
-        line.includes(`supercell:`) ||
-        line.includes(`phonon_supercell:`));
-    if (has_phonopy_keywords)
-        return parse_phonopy_yaml(content);
-    console.error(`Unable to determine file format`);
-    return null;
-}
-// Universal parser that handles JSON and structure files
-export function parse_any_structure(content, filename) {
-    const clone_structure_properties = (properties) => structuredClone(properties);
-    const finalize_structure = (structure) => ({
-        sites: structure.sites,
-        charge: 0,
-        ...(structure.properties && {
-            properties: clone_structure_properties(structure.properties),
-        }),
-        ...(structure.lattice && {
-            lattice: { ...structure.lattice, pbc: [true, true, true] },
-        }),
-    });
-    // Try JSON first, but handle nested structures properly
-    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;
-    }
-}
-// Parse OPTIMADE JSON format
-export function parse_optimade_json(content) {
-    try {
-        const raw = JSON.parse(content);
-        return parse_optimade_from_raw(raw);
-    }
-    catch (error) {
-        console.error(`Error parsing OPTIMADE JSON:`, error);
-        return null;
-    }
-}
-// 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`);
-            return null;
-        }
-        const attrs = structure.attributes;
-        // Inline validation for conciseness
-        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`);
-            return null;
-        }
-        if (positions_raw.length !== species_raw.length) {
-            console.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;
-        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];
-            if (!pos || pos.length < 3) {
-                console.warn(`Invalid position data at site ${idx}`);
-                continue;
-            }
-            const element = validate_element_symbol(element_symbol, idx);
-            const xyz = [pos[0], pos[1], pos[2]];
-            // 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);
-        }
-        if (sites.length === 0) {
-            console.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 = {
-            sites,
-            ...(lattice && { lattice }),
-        };
-        return structure_result;
-    }
-    catch (error) {
-        console.error(`Error parsing OPTIMADE JSON:`, error);
-        return null;
-    }
-}
-// Check if JSON content is OPTIMADE format by looking for structure attributes
-export function is_optimade_json(content) {
-    try {
-        const raw = JSON.parse(content);
-        return is_optimade_raw(raw);
-    }
-    catch {
-        return false;
-    }
-}
-// Check if already-parsed JSON is OPTIMADE-like
-export const is_optimade_raw = (raw) => Boolean(extract_optimade_structure_from_raw(raw));
-// Shared helper to extract an OPTIMADE structure from raw JSON-like data
-function extract_optimade_structure_from_raw(raw) {
-    const payload = unwrap_data(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;
-// Type guard: verify minimal OPTIMADE structure shape
-function is_optimade_structure_object(value) {
-    if (!value || typeof value !== `object`)
-        return false;
-    const obj = value;
-    const type = obj.type;
-    const id = obj.id;
-    const attributes = obj.attributes;
-    return (type === `structures` &&
-        typeof id === `string` &&
-        typeof attributes === `object` &&
-        attributes !== null);
-}
-// 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;
-    if (!lattice_vectors || !cartesian_site_positions || !species_at_sites) {
-        console.error(`Missing required OPTIMADE structure data`);
-        return null;
-    }
-    try {
-        const lattice_matrix = [
-            lattice_vectors[0],
-            lattice_vectors[1],
-            lattice_vectors[2],
-        ];
-        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 = [pos[0], pos[1], pos[2]];
-            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,
-            };
-        });
-        return {
-            sites,
-            lattice: { matrix: lattice_matrix, ...lattice_params, pbc: [true, true, true] },
-            id: optimade_structure.id,
-            properties,
-        };
-    }
-    catch (err) {
-        console.error(`Error converting OPTIMADE to Crystal format:`, err);
-        return null;
-    }
-}
-// Check if filename indicates a structure file
-export function is_structure_file(filename) {
-    const name = filename.toLowerCase();
-    // Trajectory-only formats (can't be structures)
-    if (/\.(traj|xtc|h5|hdf5)$/i.test(name) || /xdatcar/i.test(name))
-        return false;
-    // Always structure formats
-    if (STRUCTURE_EXTENSIONS_REGEX.test(name))
-        return true;
-    if (VASP_FILES_REGEX.test(name))
-        return true;
-    // .xyz/.extxyz files: structure unless they have trajectory keywords
-    if (/\.(xyz|extxyz)$/i.test(name))
-        return !TRAJ_KEYWORDS_REGEX.test(name);
-    // Keyword-based detection for YAML/XML
-    if (/\.(yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name))
-        return true;
-    // More restrictive keyword detection for JSON files
-    if (/\.json$/i.test(name) &&
-        STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
-        !TRAJ_KEYWORDS_REGEX.test(name) &&
-        !CONFIG_DIRS_REGEX.test(name))
-        return true;
-    // Compressed files - check base filename recursively
-    if (COMPRESSION_EXTENSIONS_REGEX.test(name)) {
-        return is_structure_file(name.replace(COMPRESSION_EXTENSIONS_REGEX, ``));
-    }
-    return false;
-}
-export const detect_structure_type = (filename, content) => {
-    const lower_filename = filename.toLowerCase();
-    // Normalize compressed suffixes (gz, gzip, zip, xz, bz2) for detection parity
-    let name_to_check = lower_filename;
-    while (COMPRESSION_EXTENSIONS_REGEX.test(name_to_check)) {
-        name_to_check = name_to_check.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
-    }
-    if (name_to_check.endsWith(`.json`)) {
-        try {
-            const parsed = JSON.parse(content);
-            // Check for crystal indicators: lattice, lattice_vectors, or periodic dimensions
-            const dims = parsed.data?.attributes?.dimension_types;
-            if (parsed.lattice ||
-                parsed.data?.attributes?.lattice_vectors ||
-                (Array.isArray(dims) && dims.some((dim) => dim > 0)) ||
-                parsed.data?.attributes?.nperiodic_dimensions > 0) {
-                return `crystal`;
-            }
-            return `molecule`;
-        }
-        catch {
-            return `unknown`;
-        }
-    }
-    if (name_to_check.endsWith(`.cif`))
-        return `crystal`;
-    if (name_to_check.includes(`poscar`))
-        return `crystal`;
-    if (name_to_check.endsWith(`.yaml`) || name_to_check.endsWith(`.yml`)) {
-        const lower_content = content.toLowerCase();
-        return lower_content.includes(`phono3py:`) || lower_content.includes(`phonopy:`)
-            ? `crystal`
-            : `unknown`;
-    }
-    if (XYZ_EXTXYZ_REGEX.test(name_to_check)) {
-        const lines = content.trim().split(/\r?\n/);
-        return lines.length >= 2 && lines[1].includes(`Lattice=`) ? `crystal` : `molecule`;
-    }
-    return `unknown`;
-};