matterviz 0.3.1 → 0.3.3

package/dist/trajectory/format-detect.js

@@ -0,0 +1,76 @@
+// Format detection for trajectory files
+import { COMPRESSION_EXTENSIONS_REGEX, CONFIG_DIRS_REGEX, MD_SIM_EXCLUDE_REGEX, TRAJ_EXTENSIONS_REGEX, TRAJ_FALLBACK_EXTENSIONS_REGEX, TRAJ_KEYWORDS_SIMPLE_REGEX, XDATCAR_REGEX, } from '../constants';
+import { count_xyz_frames } from './helpers';
+export function strip_compression_extensions(filename) {
+    let base_name = filename.toLowerCase();
+    while (COMPRESSION_EXTENSIONS_REGEX.test(base_name)) {
+        base_name = base_name.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
+    }
+    return base_name;
+}
+// Unified format detection
+export const FORMAT_PATTERNS = {
+    ase: (data, filename) => {
+        const base_name = filename ? strip_compression_extensions(filename) : undefined;
+        if (!base_name?.endsWith(`.traj`) || !(data instanceof ArrayBuffer)) {
+            return false;
+        }
+        const view = new Uint8Array(data.slice(0, 24));
+        return [0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d].every((byte, idx) => view[idx] === byte);
+    },
+    hdf5: (data, filename) => {
+        const base_name = filename ? strip_compression_extensions(filename) : undefined;
+        const has_ext = base_name?.match(/\.(h5|hdf5)$/);
+        if (!has_ext || !(data instanceof ArrayBuffer) || data.byteLength < 8)
+            return false;
+        const signature = new Uint8Array(data.slice(0, 8));
+        return [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a].every((b, idx) => signature[idx] === b);
+    },
+    vasp: (data, filename) => {
+        const basename = filename?.toLowerCase().split(`/`).pop() || ``;
+        if (basename === `xdatcar` || basename.startsWith(`xdatcar`))
+            return true;
+        const lines = data.trim().split(/\r?\n/);
+        return (lines.length >= 10 &&
+            lines.some((line) => line.includes(`Direct configuration=`)) &&
+            !isNaN(parseFloat(lines[1])) &&
+            lines.slice(2, 5).every((line) => line.trim().split(/\s+/).length === 3));
+    },
+    xyz_multi: (data, filename) => {
+        const base = filename ? strip_compression_extensions(filename) : ``;
+        if (!/\.(xyz|extxyz)$/.test(base))
+            return false;
+        return count_xyz_frames(data) >= 2;
+    },
+    lammpstrj: (data, filename) => {
+        const base = filename ? strip_compression_extensions(filename) : ``;
+        if (!base.endsWith(`.lammpstrj`))
+            return false;
+        return data.includes(`ITEM: TIMESTEP`) && data.includes(`ITEM: ATOMS`);
+    },
+};
+// Check if file is a trajectory (supports both filename-only and content-based detection)
+export function is_trajectory_file(filename, content) {
+    if (CONFIG_DIRS_REGEX.test(filename))
+        return false;
+    const base_name = strip_compression_extensions(filename);
+    // For xyz/extxyz files, use content-based detection if available
+    if (/\.(xyz|extxyz)$/i.test(base_name)) {
+        if (content)
+            return count_xyz_frames(content) >= 2;
+        return TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
+    }
+    // Always detect these specific trajectory formats
+    if (TRAJ_EXTENSIONS_REGEX.test(base_name) || XDATCAR_REGEX.test(base_name))
+        return true;
+    // Special exclusion for generic md_simulation pattern with certain extensions
+    if (MD_SIM_EXCLUDE_REGEX.test(base_name))
+        return false;
+    // For .h5/.hdf5 files, require trajectory keywords
+    if (/\.(h5|hdf5)$/i.test(base_name)) {
+        return TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
+    }
+    // For other extensions, require both keywords and specific extensions
+    return (TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name) &&
+        TRAJ_FALLBACK_EXTENSIONS_REGEX.test(base_name));
+}

package/dist/trajectory/frame-reader.d.ts

@@ -0,0 +1,17 @@
+import type { FrameIndex, FrameLoader, ParseProgress, TrajectoryFrame, TrajectoryMetadata } from './index';
+export declare class TrajFrameReader implements FrameLoader {
+    private readonly format;
+    private global_numbers?;
+    constructor(filename: string);
+    get_total_frames(data: string | ArrayBuffer): Promise<number>;
+    build_frame_index(data: string | ArrayBuffer, sample_rate: number, on_progress?: (progress: ParseProgress) => void): Promise<FrameIndex[]>;
+    load_frame(data: string | ArrayBuffer, frame_number: number): Promise<TrajectoryFrame | null>;
+    extract_plot_metadata(data: string | ArrayBuffer, options?: {
+        sample_rate?: number;
+        properties?: string[];
+    }, on_progress?: (progress: ParseProgress) => void): Promise<TrajectoryMetadata[]>;
+    private load_xyz_frame;
+    private load_ase_frame;
+    private parse_xyz_metadata;
+    private parse_ase_metadata;
+}

package/dist/trajectory/frame-reader.js

@@ -0,0 +1,332 @@
+import * as math from '../math';
+import { MAX_METADATA_SIZE } from './constants';
+import { coerce_element_symbol, convert_atomic_numbers, count_xyz_frames, create_trajectory_frame, read_ndarray_from_view, validate_3x3_matrix, } from './helpers';
+import { strip_compression_extensions } from './format-detect';
+export class TrajFrameReader {
+    format;
+    global_numbers;
+    constructor(filename) {
+        const base_filename = strip_compression_extensions(filename);
+        this.format = base_filename.endsWith(`.traj`) ? `ase` : `xyz`;
+    }
+    async get_total_frames(data) {
+        if (this.format === `xyz`) {
+            if (data instanceof ArrayBuffer)
+                throw new Error(`XYZ loader requires text data`);
+            return count_xyz_frames(data);
+        }
+        if (!(data instanceof ArrayBuffer))
+            throw new Error(`ASE loader requires binary data`);
+        const view = new DataView(data);
+        return Number(view.getBigInt64(32, true));
+    }
+    async build_frame_index(data, sample_rate, on_progress) {
+        const total_frames = await this.get_total_frames(data);
+        const frame_index = [];
+        if (this.format === `xyz`) {
+            const data_str = data;
+            const lines = data_str.trim().split(/\r?\n/);
+            const encoder = new TextEncoder();
+            const newline_sequence = data_str.includes(`\r\n`) ? `\r\n` : `\n`;
+            const newline_byte_len = encoder.encode(newline_sequence).length;
+            let [current_frame, line_idx, byte_offset] = [0, 0, 0];
+            while (line_idx < lines.length && current_frame < total_frames) {
+                if (!lines[line_idx]?.trim()) {
+                    byte_offset += encoder.encode(lines[line_idx]).length + newline_byte_len;
+                    line_idx++;
+                    continue;
+                }
+                const num_atoms = parseInt(lines[line_idx].trim(), 10);
+                if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
+                    byte_offset += encoder.encode(lines[line_idx]).length + newline_byte_len;
+                    line_idx++;
+                    continue;
+                }
+                if (current_frame % sample_rate === 0) {
+                    frame_index.push({
+                        frame_number: current_frame,
+                        byte_offset,
+                        estimated_size: 0,
+                    });
+                }
+                const frame_start = line_idx;
+                line_idx += 2 + num_atoms;
+                let frame_size = 0;
+                for (let idx = frame_start; idx < line_idx; idx++) {
+                    frame_size += encoder.encode(lines[idx]).length + newline_byte_len;
+                }
+                if (current_frame % sample_rate === 0) {
+                    frame_index[frame_index.length - 1].estimated_size = frame_size;
+                }
+                byte_offset += frame_size;
+                current_frame++;
+                if (on_progress && current_frame % 1000 === 0) {
+                    on_progress({
+                        current: (current_frame / total_frames) * 100,
+                        total: 100,
+                        stage: `Indexing: ${current_frame}`,
+                    });
+                }
+            }
+        }
+        else {
+            const view = new DataView(data);
+            const offsets_pos = Number(view.getBigInt64(40, true));
+            for (let idx = 0; idx < total_frames; idx += sample_rate) {
+                const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
+                frame_index.push({
+                    frame_number: idx,
+                    byte_offset: frame_offset,
+                    estimated_size: 0,
+                });
+                if (on_progress && idx % 10000 === 0) {
+                    on_progress({
+                        current: (idx / total_frames) * 100,
+                        total: 100,
+                        stage: `Indexing ASE: ${idx}`,
+                    });
+                }
+            }
+        }
+        return frame_index;
+    }
+    async load_frame(data, frame_number) {
+        const actual_data_type = data instanceof ArrayBuffer ? `ArrayBuffer` : typeof data;
+        if (this.format === `xyz`) {
+            if (typeof data !== `string`) {
+                throw new TypeError(`load_frame expected string data for xyz format, received ${actual_data_type}`);
+            }
+            return this.load_xyz_frame(data, frame_number);
+        }
+        if (!(data instanceof ArrayBuffer)) {
+            throw new TypeError(`load_frame expected ArrayBuffer data for ase format, received ${actual_data_type}`);
+        }
+        return this.load_ase_frame(data, frame_number);
+    }
+    async extract_plot_metadata(data, options, on_progress) {
+        const { sample_rate = 1, properties } = options || {};
+        const metadata_list = [];
+        const total_frames = await this.get_total_frames(data);
+        if (this.format === `xyz`) {
+            const lines = data.trim().split(/\r?\n/);
+            let [current_frame, line_idx] = [0, 0];
+            while (line_idx < lines.length && current_frame < total_frames) {
+                if (!lines[line_idx]?.trim()) {
+                    line_idx++;
+                    continue;
+                }
+                const num_atoms = parseInt(lines[line_idx].trim(), 10);
+                if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
+                    line_idx++;
+                    continue;
+                }
+                if (current_frame % sample_rate === 0) {
+                    const comment = lines[line_idx + 1] || ``;
+                    let frame_metadata = null;
+                    try {
+                        frame_metadata = this.parse_xyz_metadata(comment, current_frame);
+                    }
+                    catch (error) {
+                        console.warn(`Failed to parse XYZ metadata for frame ${current_frame} at line ${line_idx + 1}:`, error);
+                    }
+                    if (frame_metadata && properties) {
+                        const filtered = Object.fromEntries(Object.entries(frame_metadata.properties).filter(([key]) => properties.includes(key)));
+                        frame_metadata.properties = filtered;
+                    }
+                    if (frame_metadata)
+                        metadata_list.push(frame_metadata);
+                }
+                line_idx += 2 + num_atoms;
+                current_frame++;
+                if (on_progress && current_frame % 5000 === 0) {
+                    on_progress({
+                        current: (current_frame / total_frames) * 100,
+                        total: 100,
+                        stage: `Extracting: ${current_frame}`,
+                    });
+                }
+            }
+        }
+        else if (this.format === `ase`) {
+            const view = new DataView(data);
+            const n_items = Number(view.getBigInt64(32, true));
+            const offsets_pos = Number(view.getBigInt64(40, true));
+            for (let idx = 0; idx < n_items; idx += sample_rate) {
+                try {
+                    const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
+                    const json_length = Number(view.getBigInt64(frame_offset, true));
+                    if (json_length > MAX_METADATA_SIZE) {
+                        console.warn(`Skipping large frame ${idx}: ${Math.round(json_length / 1024 / 1024)}MB`);
+                        continue;
+                    }
+                    const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(data, frame_offset + 8, json_length)));
+                    const frame_metadata = this.parse_ase_metadata(frame_data, idx);
+                    if (properties) {
+                        const filtered = Object.fromEntries(Object.entries(frame_metadata.properties).filter(([key]) => properties.includes(key)));
+                        frame_metadata.properties = filtered;
+                    }
+                    metadata_list.push(frame_metadata);
+                    if (on_progress && idx % 5000 === 0) {
+                        on_progress({
+                            current: (idx / n_items) * 100,
+                            total: 100,
+                            stage: `Extracting ASE: ${idx}/${n_items}`,
+                        });
+                    }
+                }
+                catch (error) {
+                    console.warn(`Failed to extract metadata from ASE frame ${idx}:`, error);
+                }
+            }
+        }
+        return metadata_list;
+    }
+    load_xyz_frame(data, frame_number) {
+        const lines = data.trim().split(/\r?\n/);
+        let [current_frame, line_idx] = [0, 0];
+        while (line_idx < lines.length && current_frame < frame_number) {
+            if (!lines[line_idx]?.trim()) {
+                line_idx++;
+                continue;
+            }
+            const num_atoms = parseInt(lines[line_idx].trim(), 10);
+            if (isNaN(num_atoms) || num_atoms <= 0) {
+                line_idx++;
+                continue;
+            }
+            line_idx += 2 + num_atoms;
+            current_frame++;
+        }
+        if (line_idx >= lines.length)
+            return null;
+        const num_atoms = parseInt(lines[line_idx].trim(), 10);
+        if (isNaN(num_atoms) || line_idx + num_atoms + 1 >= lines.length)
+            return null;
+        const comment = lines[line_idx + 1] || ``;
+        const positions = [];
+        const elements = [];
+        for (let idx = 0; idx < num_atoms; idx++) {
+            const parts = lines[line_idx + 2 + idx]?.trim().split(/\s+/);
+            if (parts?.length >= 4) {
+                const x_coord = parseFloat(parts[1]);
+                const y_coord = parseFloat(parts[2]);
+                const z_coord = parseFloat(parts[3]);
+                if (!Number.isFinite(x_coord) ||
+                    !Number.isFinite(y_coord) ||
+                    !Number.isFinite(z_coord)) {
+                    console.warn(`Skipping XYZ atom with invalid coordinates in indexed frame ${frame_number} at line ${line_idx + 2 + idx}`);
+                    continue;
+                }
+                const raw_symbol = parts[0];
+                const element_symbol = coerce_element_symbol(raw_symbol);
+                if (!element_symbol) {
+                    console.warn(`Skipping XYZ atom with unknown element symbol "${raw_symbol}" in indexed frame ${frame_number}`);
+                    continue;
+                }
+                elements.push(element_symbol);
+                positions.push([x_coord, y_coord, z_coord]);
+            }
+        }
+        const metadata = this.parse_xyz_metadata(comment, frame_number);
+        return create_trajectory_frame(positions, elements, undefined, undefined, metadata.step, metadata.properties);
+    }
+    load_ase_frame(data, frame_number) {
+        try {
+            const view = new DataView(data);
+            const n_items = Number(view.getBigInt64(32, true));
+            const offsets_pos = Number(view.getBigInt64(40, true));
+            if (frame_number >= n_items)
+                return null;
+            const frame_offset = Number(view.getBigInt64(offsets_pos + frame_number * 8, true));
+            const json_length = Number(view.getBigInt64(frame_offset, true));
+            const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(data, frame_offset + 8, json_length)));
+            const positions_ref = frame_data[`positions.`] || frame_data.positions;
+            const positions = positions_ref?.ndarray
+                ? read_ndarray_from_view(view, positions_ref)
+                : positions_ref;
+            const numbers_ref = frame_data[`numbers.`] || frame_data.numbers || this.global_numbers;
+            const numbers = numbers_ref?.ndarray
+                ? read_ndarray_from_view(view, numbers_ref).flat()
+                : numbers_ref;
+            if (numbers)
+                this.global_numbers = numbers;
+            if (!numbers || !positions)
+                throw new Error(`Missing atomic numbers or positions`);
+            const cell = frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined;
+            const metadata = {
+                step: frame_number,
+                ...(frame_data.calculator || {}),
+                ...(frame_data.info || {}),
+            };
+            if (cell) {
+                try {
+                    metadata.volume = Math.abs(math.det_3x3(cell));
+                }
+                catch (error) {
+                    console.warn(`Failed to calculate volume for frame ${frame_number}:`, error);
+                }
+            }
+            return create_trajectory_frame(positions, convert_atomic_numbers(numbers), cell, frame_data.pbc || [true, true, true], frame_number, metadata);
+        }
+        catch (error) {
+            console.warn(`Failed to load ASE frame ${frame_number}:`, error);
+            return null;
+        }
+    }
+    parse_xyz_metadata(comment, frame_number) {
+        const properties = {};
+        const patterns = {
+            energy: /(?:energy|E|etot)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            volume: /(?:volume|vol|V)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            pressure: /(?:pressure|press|P)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            force_max: /(?:max_force|fmax)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+        };
+        Object.entries(patterns).forEach(([key, pattern]) => {
+            const match = pattern.exec(comment);
+            if (match)
+                properties[key] = parseFloat(match[1]);
+        });
+        const step_match = /(?:step|frame)\s*[=:]?\s*(\d+)/i.exec(comment);
+        const step = step_match ? parseInt(step_match[1]) : frame_number;
+        return { frame_number, step, properties };
+    }
+    parse_ase_metadata(frame_data, frame_number) {
+        const properties = {};
+        const step = frame_number;
+        if (frame_data.calculator && typeof frame_data.calculator === `object`) {
+            const calculator = frame_data.calculator;
+            const calc_properties = [`energy`, `potential_energy`, `kinetic_energy`, `total_energy`];
+            for (const prop of calc_properties) {
+                if (prop in calculator && typeof calculator[prop] === `number`) {
+                    properties[prop] = calculator[prop];
+                }
+            }
+        }
+        if (frame_data.info && typeof frame_data.info === `object`) {
+            const info = frame_data.info;
+            const info_properties = [
+                `force_max`,
+                `force_norm`,
+                `stress_max`,
+                `stress_frobenius`,
+                `pressure`,
+                `temperature`,
+            ];
+            for (const prop of info_properties) {
+                if (prop in info && typeof info[prop] === `number`) {
+                    properties[prop] = info[prop];
+                }
+            }
+        }
+        if (frame_data.cell && Array.isArray(frame_data.cell)) {
+            try {
+                const validated_cell = validate_3x3_matrix(frame_data.cell);
+                properties.volume = Math.abs(math.det_3x3(validated_cell));
+            }
+            catch (error) {
+                console.warn(`Failed to calculate volume for ASE frame ${frame_number}:`, error);
+            }
+        }
+        return { frame_number, step, properties };
+    }
+}

package/dist/trajectory/helpers.d.ts

@@ -0,0 +1,14 @@
+import type { ElementSymbol } from '../element';
+import * as math from '../math';
+import type { AnyStructure, Pbc } from '../structure';
+import type { TrajectoryFrame } from './index';
+export declare function is_valid_element_symbol(symbol: string): symbol is ElementSymbol;
+export declare function coerce_element_symbol(symbol: string): ElementSymbol | undefined;
+export declare function validate_3x3_matrix(data: unknown): math.Matrix3x3;
+export declare const convert_atomic_numbers: (numbers: number[]) => ElementSymbol[];
+export declare const create_structure: (positions: number[][], elements: ElementSymbol[], lattice_matrix?: math.Matrix3x3, pbc?: Pbc, force_data?: number[][]) => AnyStructure;
+export declare const create_trajectory_frame: (positions: number[][], elements: ElementSymbol[], lattice_matrix: math.Matrix3x3 | undefined, pbc: Pbc | undefined, step: number, metadata?: Record<string, unknown>) => TrajectoryFrame;
+export declare const read_ndarray_from_view: (view: DataView, ref: {
+    ndarray: unknown[];
+}) => number[][];
+export declare function count_xyz_frames(data: string): number;

package/dist/trajectory/helpers.js

@@ -0,0 +1,172 @@
+// Shared utilities for trajectory parsing
+import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
+import { ELEM_SYMBOLS } from '../labels';
+import * as math from '../math';
+const element_symbol_set = new Set(ELEM_SYMBOLS);
+export function is_valid_element_symbol(symbol) {
+    return element_symbol_set.has(symbol);
+}
+export function coerce_element_symbol(symbol) {
+    return is_valid_element_symbol(symbol) ? symbol : undefined;
+}
+// Validate that data is a proper 3x3 matrix
+// Accepts both regular arrays and typed arrays (Float32Array, Float64Array, etc.)
+export function validate_3x3_matrix(data) {
+    if (!Array.isArray(data) || data.length !== 3) {
+        throw new Error(`Expected 3x3 matrix, got array of length ${Array.isArray(data) ? data.length : `non-array`}`);
+    }
+    const is_valid_row = (row) => {
+        if (Array.isArray(row))
+            return row.length === 3;
+        if (!ArrayBuffer.isView(row))
+            return false;
+        return `length` in row && typeof row.length === `number` && row.length === 3;
+    };
+    if (!data.every(is_valid_row)) {
+        throw new Error(`Invalid 3x3 matrix structure`);
+    }
+    return data;
+}
+export const convert_atomic_numbers = (numbers) => numbers.map((num) => {
+    const symbol = ATOMIC_NUMBER_TO_SYMBOL[num];
+    if (!symbol || !is_valid_element_symbol(symbol)) {
+        throw new Error(`Unknown atomic number in trajectory data: ${num}`);
+    }
+    return symbol;
+});
+export const create_structure = (positions, elements, lattice_matrix, pbc, force_data) => {
+    if (positions.length !== elements.length) {
+        throw new Error(`create_structure requires matching positions and elements lengths, got positions=${positions.length}, elements=${elements.length}`);
+    }
+    const cart_to_frac = lattice_matrix ? math.create_cart_to_frac(lattice_matrix) : null;
+    const is_valid_vec3 = (coords) => Array.isArray(coords) &&
+        coords.length === 3 &&
+        coords.every((value) => typeof value === `number` && Number.isFinite(value));
+    const sites = positions.map((pos, idx) => {
+        if (!is_valid_vec3(pos)) {
+            throw new Error(`Invalid position at index ${idx}: expected 3 finite coordinates`);
+        }
+        const xyz = pos;
+        const abc = cart_to_frac ? cart_to_frac(xyz) : [0, 0, 0];
+        const force = force_data?.[idx];
+        const properties = is_valid_vec3(force) ? { force } : {};
+        return {
+            species: [{ element: elements[idx], occu: 1, oxidation_state: 0 }],
+            abc,
+            xyz,
+            label: `${elements[idx]}${idx + 1}`,
+            properties,
+        };
+    });
+    return lattice_matrix
+        ? {
+            sites,
+            lattice: {
+                matrix: lattice_matrix,
+                ...math.calc_lattice_params(lattice_matrix),
+                pbc: pbc || [true, true, true],
+            },
+        }
+        : { sites };
+};
+export const create_trajectory_frame = (positions, elements, lattice_matrix, pbc, step, metadata = {}) => ({
+    structure: create_structure(positions, elements, lattice_matrix, pbc),
+    step,
+    metadata,
+});
+// Shared utility to read ndarray data from binary format
+export const read_ndarray_from_view = (view, ref) => {
+    const [shape, dtype, array_offset] = ref.ndarray;
+    const total = shape.reduce((product, dim_size) => product * dim_size, 1);
+    const data = [];
+    let pos = array_offset;
+    const readers = {
+        int64: {
+            bytes_per_element: 8,
+            read: () => {
+                const value = Number(view.getBigInt64(pos, true));
+                pos += 8;
+                return value;
+            },
+        },
+        int32: {
+            bytes_per_element: 4,
+            read: () => {
+                const value = view.getInt32(pos, true);
+                pos += 4;
+                return value;
+            },
+        },
+        float64: {
+            bytes_per_element: 8,
+            read: () => {
+                const value = view.getFloat64(pos, true);
+                pos += 8;
+                return value;
+            },
+        },
+        float32: {
+            bytes_per_element: 4,
+            read: () => {
+                const value = view.getFloat32(pos, true);
+                pos += 4;
+                return value;
+            },
+        },
+    };
+    const reader_config = readers[dtype];
+    if (!reader_config)
+        throw new Error(`Unsupported dtype: ${dtype}`);
+    if (!Number.isInteger(array_offset) || array_offset < 0) {
+        throw new Error(`Invalid array_offset: expected non-negative integer, got ${array_offset}`);
+    }
+    const bytes_needed = total * reader_config.bytes_per_element;
+    if (array_offset + bytes_needed > view.byteLength) {
+        throw new Error(`Out-of-bounds read: array_offset + bytesNeeded exceeds view.byteLength`);
+    }
+    for (let idx = 0; idx < total; idx++)
+        data.push(reader_config.read());
+    return shape.length === 1
+        ? [data]
+        : shape.length === 2
+            ? Array.from({ length: shape[0] }, (_, idx) => data.slice(idx * shape[1], (idx + 1) * shape[1]))
+            : (() => {
+                throw new Error(`Unsupported shape`);
+            })();
+};
+// Unified frame counting for XYZ
+export function count_xyz_frames(data) {
+    if (!data || typeof data !== `string`)
+        return 0;
+    const lines = data.trim().split(/\r?\n/);
+    let frame_count = 0;
+    let line_idx = 0;
+    while (line_idx < lines.length) {
+        if (!lines[line_idx]?.trim()) {
+            line_idx++;
+            continue;
+        }
+        const num_atoms = parseInt(lines[line_idx].trim(), 10);
+        if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 2 > lines.length) {
+            line_idx++;
+            continue;
+        }
+        // Quick validation of first few atom lines
+        let valid_coords = 0;
+        for (let idx = 0; idx < Math.min(num_atoms, 3); idx++) {
+            const parts = lines[line_idx + 2 + idx]?.trim().split(/\s+/);
+            if (parts?.length >= 4 && isNaN(parseInt(parts[0])) && parts[0].length <= 3) {
+                if (parts.slice(1, 4).every((coord) => !isNaN(parseFloat(coord))))
+                    valid_coords++;
+            }
+        }
+        if (valid_coords >= Math.min(num_atoms, 3)) {
+            frame_count++;
+            line_idx += 2 + num_atoms;
+        }
+        else {
+            line_idx++;
+        }
+    }
+    return frame_count;
+}

package/dist/trajectory/index.d.ts

@@ -6,6 +6,7 @@ export { default as TrajectoryError } from './TrajectoryError.svelte';
 export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte';
 export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte';
 export type TrajectoryFormat = `hdf5` | `json` | `xyz` | `xdatcar` | `traj` | `unknown`;
+export type { AtomTypeMapping } from './types';
 export interface ParseProgress {
     current: number;
     total: number;