matterviz 0.4.1 → 0.4.3

package/dist/trajectory/extract.js

@@ -1,23 +1,21 @@
 // Data extraction functions for trajectory analysis and plotting
 import { get_density } from '../structure/index';
 import { calc_force_stats, copy_numeric_fields } from './helpers';
-// Common data extractor that extracts energy and structural properties
-export const energy_data_extractor = (frame) => {
-    const data = {
-        Step: frame.step,
-    };
-    if (frame.metadata) {
-        // Extract energy-related properties
-        copy_numeric_fields(data, frame.metadata, [
-            `energy`,
-            `energy_per_atom`,
-            `potential_energy`,
-            `kinetic_energy`,
-            `total_energy`,
-        ]);
-    }
+// Build an extractor that copies the listed numeric metadata fields (plus Step)
+const make_metadata_extractor = (fields) => (frame) => {
+    const data = { Step: frame.step };
+    if (frame.metadata)
+        copy_numeric_fields(data, frame.metadata, fields);
     return data;
 };
+// Common data extractor that extracts energy-related properties
+export const energy_data_extractor = make_metadata_extractor([
+    `energy`,
+    `energy_per_atom`,
+    `potential_energy`,
+    `kinetic_energy`,
+    `total_energy`,
+]);
 // Data extractor for forces and stresses
 export const force_stress_data_extractor = (frame) => {
     const data = {
@@ -52,6 +50,15 @@ export const force_stress_data_extractor = (frame) => {
     }
     return data;
 };
+// Data extractor for SCF/electronic-convergence properties. Parsers emit these
+// per frame (per ionic step, or per SCF step for static single-point runs) —
+// e.g. the vaspout.h5 parser fills them from VASP's OSZICAR data.
+const scf_data_extractor = make_metadata_extractor([
+    `n_scf_steps`,
+    `scf_energy_delta`,
+    `scf_rms`,
+    `scf_charge_rms`,
+]);
 // Data extractor for structural properties
 export const structural_data_extractor = (frame) => {
     const data = {
@@ -93,50 +100,55 @@ export const structural_data_extractor = (frame) => {
     }
     return data;
 };
-// Helper function to check if a property varies across trajectory frames
-function property_varies(trajectory, property_key, tolerance = 1e-10) {
-    if (trajectory.frames.length <= 1)
-        return false;
-    const values = [];
+const LATTICE_PARAMS = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
+// Cache per trajectory: full_data_extractor runs once per frame, so without this it
+// rescans all frames on every call (O(n²)). WeakMap → GC'd with the trajectory.
+const constant_params_cache = new WeakMap();
+// Lattice params constant across the trajectory, in a single pass (prefer lattice value,
+// else metadata; tol 1e-10). A param must be observed in ≥1 frame to count as constant;
+// params absent from every frame are excluded (not silently treated as "constant").
+function get_constant_lattice_params(trajectory) {
+    const cached = constant_params_cache.get(trajectory);
+    if (cached)
+        return cached;
+    const tolerance = 1e-10;
+    const first_values = new Map();
+    const varies = new Set();
     for (const frame of trajectory.frames) {
-        // Check both direct structure properties and metadata
-        let value;
-        if (`lattice` in frame.structure) {
-            const lattice_value = frame.structure.lattice[property_key];
-            if (typeof lattice_value === `number`)
-                value = lattice_value;
-        }
-        if (value === undefined && frame.metadata && property_key in frame.metadata) {
-            const metadata_value = frame.metadata[property_key];
-            if (typeof metadata_value === `number`) {
-                value = metadata_value;
-            }
-        }
-        if (value !== undefined) {
-            values.push(value);
+        const lattice = `lattice` in frame.structure
+            ? frame.structure.lattice
+            : null;
+        for (const param of LATTICE_PARAMS) {
+            if (varies.has(param))
+                continue; // already known to vary, skip
+            const lattice_value = lattice?.[param];
+            const value = typeof lattice_value === `number` ? lattice_value : frame.metadata?.[param];
+            // Number.isFinite: NaN is typeof `number` but Math.abs(next-NaN)=NaN → false constant
+            if (typeof value !== `number` || !Number.isFinite(value))
+                continue;
+            const first = first_values.get(param);
+            if (first === undefined)
+                first_values.set(param, value);
+            else if (Math.abs(value - first) > tolerance)
+                varies.add(param);
         }
     }
-    if (values.length <= 1)
-        return false;
-    const first_value = values[0];
-    return values.some((value) => Math.abs(value - first_value) > tolerance);
+    // only params observed in ≥1 frame; a never-present param is not "constant"
+    const constant = new Set([...first_values.keys()].filter((param) => !varies.has(param)));
+    constant_params_cache.set(trajectory, constant);
+    return constant;
 }
 // Combined data extractor that extracts all common properties
 export const full_data_extractor = (frame, trajectory) => {
-    const base_data = {
+    const result = {
         ...energy_data_extractor(frame, trajectory),
         ...force_stress_data_extractor(frame, trajectory),
+        ...scf_data_extractor(frame, trajectory),
         ...structural_data_extractor(frame, trajectory),
     };
-    // Check which lattice parameters vary
-    const lattice_params = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
-    const result = { ...base_data };
-    // Add metadata to specify which properties don't vary
-    for (const param of lattice_params) {
-        if (!property_varies(trajectory, param)) {
-            // Mark individual lattice parameters as constant
-            result[`constant_${param}`] = 1;
-        }
+    // Mark individual lattice parameters that don't vary across the trajectory
+    for (const param of get_constant_lattice_params(trajectory)) {
+        result[`constant_${param}`] = 1;
     }
     return result;
 };

package/dist/trajectory/format-detect.d.ts

@@ -1,4 +1,6 @@
 export declare function ext_hint(filename: string | undefined, ext_regex: RegExp): boolean | null;
+export declare const indexed_trajectory_format: (filename: string) => `ase` | `xyz`;
+export declare const is_indexable_trajectory_filename: (filename: string) => boolean;
 export declare const FORMAT_PATTERNS: {
     readonly ase: (data: unknown, filename?: string) => boolean;
     readonly hdf5: (data: unknown, filename?: string) => boolean;

package/dist/trajectory/format-detect.js

@@ -1,10 +1,11 @@
 // Format detection for trajectory files
-import { CONFIG_DIRS_REGEX, MD_SIM_EXCLUDE_REGEX, TRAJ_EXTENSIONS_REGEX, TRAJ_FALLBACK_EXTENSIONS_REGEX, TRAJ_KEYWORDS_SIMPLE_REGEX, XDATCAR_REGEX, } from '../constants';
-import { strip_compression_extensions } from '../io';
+import { CONFIG_DIRS_REGEX, MD_SIM_EXCLUDE_REGEX, TRAJ_EXTENSIONS_REGEX, TRAJ_FALLBACK_EXTENSIONS_REGEX, TRAJ_KEYWORDS_REGEX, XDATCAR_REGEX, } from '../constants';
+import { strip_compression_extensions } from '../io/decompress';
+import { parse_leading_num } from '../utils';
 import { count_xyz_frames } from './helpers';
 // Extensions that explicitly identify a format — when present, format detection trusts
 // the extension instead of sniffing content
-const KNOWN_FORMAT_EXT_REGEX = /\.(xyz|extxyz|traj|h5|hdf5|lammpstrj|json|cif|poscar|vasp|yaml|yml|xml|csv)$/;
+const KNOWN_FORMAT_EXT_REGEX = /\.(?:xyz|extxyz|traj|h5|hdf5|lammpstrj|json|cif|poscar|vasp|yaml|yml|xml|csv)$/;
 // Classify the filename hint for a format whose extensions match ext_regex:
 // true = filename matches, false = filename names a different known format,
 // null = no usable hint (missing filename or unrecognized extension, e.g. the UUID
@@ -17,6 +18,9 @@ export function ext_hint(filename, ext_regex) {
         return true;
     return KNOWN_FORMAT_EXT_REGEX.test(base) ? false : null;
 }
+// Large-file frame indexing currently supports text XYZ/EXTXYZ and binary ASE .traj.
+export const indexed_trajectory_format = (filename) => strip_compression_extensions(filename).endsWith(`.traj`) ? `ase` : `xyz`;
+export const is_indexable_trajectory_filename = (filename) => /\.(?:xyz|extxyz|traj)$/i.test(strip_compression_extensions(filename));
 // Unified format detection. Each pattern trusts a matching file extension when present
 // but falls back to content/magic-byte detection when the filename gives no hint
 // (e.g. blob: object URLs, extensionless API endpoints).
@@ -29,7 +33,7 @@ export const FORMAT_PATTERNS = {
         return [0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d].every((byte, idx) => view[idx] === byte);
     },
     hdf5: (data, filename) => {
-        if (ext_hint(filename, /\.(h5|hdf5)$/) === false)
+        if (ext_hint(filename, /\.(?:h5|hdf5)$/) === false)
             return false;
         if (!(data instanceof ArrayBuffer) || data.byteLength < 8)
             return false;
@@ -43,11 +47,11 @@ export const FORMAT_PATTERNS = {
         const lines = data.trim().split(/\r?\n/);
         return (lines.length >= 10 &&
             lines.some((line) => line.includes(`Direct configuration=`)) &&
-            !isNaN(parseFloat(lines[1])) &&
+            !isNaN(parse_leading_num(lines[1])) &&
             lines.slice(2, 5).every((line) => line.trim().split(/\s+/).length === 3));
     },
     xyz_multi: (data, filename) => {
-        if (ext_hint(filename, /\.(xyz|extxyz)$/) === false)
+        if (ext_hint(filename, /\.(?:xyz|extxyz)$/) === false)
             return false;
         return count_xyz_frames(data) >= 2;
     },
@@ -63,10 +67,10 @@ export function is_trajectory_file(filename, content) {
         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 (/\.(?:xyz|extxyz)$/i.test(base_name)) {
         if (content)
             return count_xyz_frames(content) >= 2;
-        return TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
+        return TRAJ_KEYWORDS_REGEX.test(base_name);
     }
     // Always detect these specific trajectory formats
     if (TRAJ_EXTENSIONS_REGEX.test(base_name) || XDATCAR_REGEX.test(base_name))
@@ -74,11 +78,11 @@ export function is_trajectory_file(filename, content) {
     // 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 .h5/.hdf5 files, require trajectory keywords. vaspout.h5 (VASP's
+    // HDF5 output) is always trajectory-shaped regardless of keywords.
+    if (/\.(?:h5|hdf5)$/i.test(base_name)) {
+        return /vaspout/i.test(base_name) || TRAJ_KEYWORDS_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));
+    return TRAJ_KEYWORDS_REGEX.test(base_name) && TRAJ_FALLBACK_EXTENSIONS_REGEX.test(base_name);
 }

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

@@ -2,6 +2,7 @@ import type { FrameIndex, FrameLoader, ParseProgress, TrajectoryFrame, Trajector
 export declare class TrajFrameReader implements FrameLoader {
     private readonly format;
     private global_numbers?;
+    private xyz_cache?;
     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[]>;
@@ -10,6 +11,7 @@ export declare class TrajFrameReader implements FrameLoader {
         sample_rate?: number;
         properties?: string[];
     }, on_progress?: (progress: ParseProgress) => void): Promise<TrajectoryMetadata[]>;
+    private get_xyz_cache;
     private load_xyz_frame;
     private load_ase_frame;
     private parse_ase_metadata;

package/dist/trajectory/frame-reader.js

@@ -1,10 +1,10 @@
 // Unified frame loader for XYZ and ASE trajectories (large file indexing)
 import * as math from '../math';
-import { MAX_METADATA_SIZE } from './constants';
 import { copy_numeric_fields, count_xyz_frames, iter_xyz_frames, validate_3x3_matrix, } from './helpers';
-import { strip_compression_extensions } from '../io';
+import { indexed_trajectory_format } from './format-detect';
 import { decode_ase_frame, read_ase_header } from './parse/ase';
 import { build_xyz_frame, parse_xyz_comment_metadata } from './parse/xyz';
+const MAX_METADATA_SIZE = 50 * 1024 * 1024; // 50MB limit for metadata
 // Restrict frame metadata to the requested property keys (no-op when unset)
 const filter_properties = (metadata, properties) => {
     if (!properties)
@@ -14,9 +14,11 @@ const filter_properties = (metadata, properties) => {
 export class TrajFrameReader {
     format;
     global_numbers;
+    // Split lines + per-frame start indices for the last XYZ payload, so repeat seeks are
+    // O(1) lookup instead of re-splitting + rescanning from line 0 (was O(n²) over playback)
+    xyz_cache;
     constructor(filename) {
-        const base_filename = strip_compression_extensions(filename);
-        this.format = base_filename.endsWith(`.traj`) ? `ase` : `xyz`;
+        this.format = indexed_trajectory_format(filename);
     }
     async get_total_frames(data) {
         if (this.format === `xyz`) {
@@ -108,26 +110,19 @@ export class TrajFrameReader {
         if (this.format === `xyz`) {
             const lines = data.trim().split(/\r?\n/);
             let current_frame = 0;
-            for (const { start, comment } of iter_xyz_frames(lines)) {
+            for (const { comment } of iter_xyz_frames(lines)) {
                 if (current_frame >= total_frames)
                     break;
                 if (current_frame % sample_rate === 0) {
-                    let frame_metadata = null;
-                    try {
-                        const { step, properties: props } = parse_xyz_comment_metadata(comment);
-                        frame_metadata = {
-                            frame_number: current_frame,
-                            step: step ?? current_frame,
-                            properties: props,
-                        };
-                    }
-                    catch (error) {
-                        console.warn(`Failed to parse XYZ metadata for frame ${current_frame} at line ${start + 1}:`, error);
-                    }
-                    if (frame_metadata) {
-                        filter_properties(frame_metadata, properties);
-                        metadata_list.push(frame_metadata);
-                    }
+                    // parse_xyz_comment_metadata is pure regex/parseFloat and never throws
+                    const { step, properties: props } = parse_xyz_comment_metadata(comment);
+                    const frame_metadata = {
+                        frame_number: current_frame,
+                        step: step ?? current_frame,
+                        properties: props,
+                    };
+                    filter_properties(frame_metadata, properties);
+                    metadata_list.push(frame_metadata);
                 }
                 current_frame++;
                 if (on_progress && current_frame % 5000 === 0) {
@@ -169,18 +164,26 @@ export class TrajFrameReader {
         }
         return metadata_list;
     }
-    load_xyz_frame(data, frame_number) {
+    // Build + cache the line array and per-frame start indices once per payload
+    get_xyz_cache(data) {
+        if (this.xyz_cache?.data === data)
+            return this.xyz_cache;
         const lines = data.trim().split(/\r?\n/);
-        let current_frame = 0;
-        for (const frame of iter_xyz_frames(lines)) {
-            if (current_frame++ < frame_number)
-                continue; // skip frames before the target
-            return build_xyz_frame(lines, frame, {
-                frame_label: `indexed frame ${frame_number}`,
-                default_step: frame_number,
-            });
-        }
-        return null;
+        const frame_starts = Array.from(iter_xyz_frames(lines), ({ start }) => start);
+        this.xyz_cache = { data, lines, frame_starts };
+        return this.xyz_cache;
+    }
+    load_xyz_frame(data, frame_number) {
+        const { lines, frame_starts } = this.get_xyz_cache(data);
+        const start = frame_starts[frame_number];
+        if (start === undefined)
+            return null; // out-of-range frame
+        const num_atoms = Math.trunc(Number(lines[start]?.trim()));
+        const comment = lines[start + 1] ?? ``;
+        return build_xyz_frame(lines, { start, num_atoms, comment }, {
+            frame_label: `indexed frame ${frame_number}`,
+            default_step: frame_number,
+        });
     }
     load_ase_frame(data, frame_number) {
         try {

package/dist/trajectory/helpers.d.ts

@@ -5,6 +5,7 @@ import type { Pbc } from '../structure/pbc';
 import type { TrajectoryFrame } from './index';
 export declare function validate_3x3_matrix(data: unknown): math.Matrix3x3;
 export declare const convert_atomic_numbers: (numbers: number[]) => ElementSymbol[];
+export declare const count_elements: (elements: readonly string[]) => Record<string, number>;
 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: {
@@ -15,6 +16,7 @@ export declare function calc_force_stats(forces: number[][]): {
     force_max: number;
     force_norm: number;
 } | null;
+export declare const is_xyz_atom_line: (parts: string[] | undefined) => boolean;
 export declare function iter_xyz_frames(lines: string[]): Generator<{
     start: number;
     num_atoms: number;

package/dist/trajectory/helpers.js

@@ -1,13 +1,8 @@
 // Shared utilities for trajectory parsing
 import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
-import { is_elem_symbol } from '../element';
+import { is_elem_symbol } from '../element/helpers';
 import * as math from '../math';
 import { make_site } from '../structure/site';
-const is_valid_row = (row) => {
-    if (!(Array.isArray(row) || (ArrayBuffer.isView(row) && `length` in row)))
-        return false;
-    return math.is_finite_vec3_like(row);
-};
 const is_valid_vec3 = (coords) => Array.isArray(coords) && math.is_finite_vec3_like(coords);
 // Validate that data is a proper 3x3 matrix
 // Accepts both regular arrays and typed arrays (Float32Array, Float64Array, etc.)
@@ -15,7 +10,8 @@ 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`}`);
     }
-    if (!data.every(is_valid_row)) {
+    if (!data.every((row) => (Array.isArray(row) || (ArrayBuffer.isView(row) && `length` in row)) &&
+        math.is_finite_vec3_like(row))) {
         throw new Error(`Invalid 3x3 matrix structure`);
     }
     return data;
@@ -27,6 +23,13 @@ export const convert_atomic_numbers = (numbers) => numbers.map((num) => {
     }
     return symbol;
 });
+// Tally per-element atom counts for trajectory metadata.element_counts
+export const count_elements = (elements) => {
+    const counts = {};
+    for (const element of elements)
+        counts[element] = (counts[element] || 0) + 1;
+    return counts;
+};
 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}`);
@@ -62,54 +65,25 @@ export const create_trajectory_frame = (positions, elements, lattice_matrix, pbc
 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;
-            },
-        },
+        int64: { bytes: 8, read: (pos) => Number(view.getBigInt64(pos, true)) },
+        int32: { bytes: 4, read: (pos) => view.getInt32(pos, true) },
+        float64: { bytes: 8, read: (pos) => view.getFloat64(pos, true) },
+        float32: { bytes: 4, read: (pos) => view.getFloat32(pos, true) },
     };
-    const reader_config = readers[dtype];
-    if (!reader_config)
+    const reader = readers[dtype];
+    if (!reader)
         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) {
+    if (array_offset + total * reader.bytes > 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());
+    const data = [];
+    for (let idx = 0; idx < total; idx++) {
+        data.push(reader.read(array_offset + idx * reader.bytes));
+    }
     return shape.length === 1
         ? [data]
         : shape.length === 2
@@ -140,8 +114,16 @@ export function calc_force_stats(forces) {
     }
     return { force_max, force_norm: Math.sqrt(sum_sq / forces.length) };
 }
-// Walk concatenated (ext)XYZ frames in `lines`, yielding each frame's atom-count line
-// index, parsed atom count, and comment line. A candidate frame is accepted only when its
+// True when a whitespace-split line looks like an XYZ atom line: a short
+// non-numeric element token followed by three numeric coordinates. Shared by
+// trajectory frame iteration and structure-format sniffing so both stay in sync.
+export const is_xyz_atom_line = (parts) => parts !== undefined &&
+    parts.length >= 4 &&
+    isNaN(Number(parts[0])) &&
+    parts[0].length <= 3 &&
+    parts.slice(1, 4).every((coord) => coord !== `` && !isNaN(Number(coord)));
+// Walk concatenated (ext)XYZ frames in `lines`, yielding each frame's start line index,
+// parsed atom count, and comment line. A candidate frame is accepted only when its
 // first few atom lines look like "<element> <x> <y> <z>"; otherwise we advance one line and
 // rescan. That validation doubles as content sniffing so numeric-leading non-XYZ formats
 // (e.g. VASP XDATCAR) aren't misread as frames, and keeps count_xyz_frames consistent with
@@ -149,7 +131,7 @@ export function calc_force_stats(forces) {
 export function* iter_xyz_frames(lines) {
     let line_idx = 0;
     while (line_idx < lines.length) {
-        const num_atoms = parseInt(lines[line_idx]?.trim(), 10);
+        const num_atoms = Math.trunc(Number(lines[line_idx]?.trim()));
         if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 2 > lines.length) {
             line_idx++; // skip blank/invalid lines until the next frame's atom-count line
             continue;
@@ -157,11 +139,7 @@ export function* iter_xyz_frames(lines) {
         let valid_coords = 0;
         const sample = Math.min(num_atoms, 3);
         for (let idx = 0; idx < sample; idx++) {
-            const parts = lines[line_idx + 2 + idx]?.trim().split(/\s+/);
-            if (parts?.length >= 4 &&
-                isNaN(parseInt(parts[0], 10)) &&
-                parts[0].length <= 3 &&
-                parts.slice(1, 4).every((coord) => !isNaN(parseFloat(coord))))
+            if (is_xyz_atom_line(lines[line_idx + 2 + idx]?.trim().split(/\s+/)))
                 valid_coords++;
         }
         if (valid_coords < sample) {
@@ -174,7 +152,7 @@ export function* iter_xyz_frames(lines) {
 }
 // Count XYZ frames via iter_xyz_frames so total_frames matches what gets indexed/loaded
 export function count_xyz_frames(data) {
-    if (!data || typeof data !== `string`)
+    if (!data)
         return 0;
     const frames = iter_xyz_frames(data.trim().split(/\r?\n/));
     let frame_count = 0;

package/dist/trajectory/index.d.ts

@@ -7,6 +7,7 @@ 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 declare const FRAME_LOAD_DEBOUNCE_MS = 75;
 export interface ParseProgress {
     current: number;
     total: number;

package/dist/trajectory/index.js

@@ -2,8 +2,10 @@ export { default as Trajectory } from './Trajectory.svelte';
 export { default as TrajectoryError } from './TrajectoryError.svelte';
 export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte';
 export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte';
+// Debounce for on-demand frame loads while scrubbing: skips fetches for steps
+// the user slides past. Exported so tests stay in sync with the real delay.
+export const FRAME_LOAD_DEBOUNCE_MS = 75;
 export function validate_trajectory(trajectory) {
-    // with detailed error reporting
     const errors = [];
     const { frames, total_frames, indexed_frames, plot_metadata, is_indexed } = trajectory;
     if (!frames?.length)
@@ -110,13 +112,8 @@ export function get_trajectory_stats(trajectory) {
         else
             stats.atom_count_range = [Math.min(...all_counts), Math.max(...all_counts)];
     }
-    else {
-        // Handle empty trajectory case
-        stats.steps = [];
-        stats.step_range = undefined;
-        stats.constant_atom_count = undefined;
-        stats.total_atoms = undefined;
-    }
+    else
+        stats.steps = []; // empty trajectory
     // Additional metadata for large files
     if (indexed_frames)
         stats.indexed_frame_count = indexed_frames.length;

package/dist/trajectory/parse/ase.js

@@ -1,7 +1,7 @@
 // ASE trajectory (.traj) parsing - binary format
 import * as math from '../../math';
-import { MAX_SAFE_STRING_LENGTH } from '../constants';
 import { convert_atomic_numbers, create_trajectory_frame, read_ndarray_from_view, validate_3x3_matrix, } from '../helpers';
+const MAX_SAFE_STRING_LENGTH = 0x1fffffe8 * 0.5; // 50% of JS max string length as safety
 // ULM header: frame count lives at byte 32, frame-offsets table position at byte 40
 export const read_ase_header = (view) => ({
     n_items: Number(view.getBigInt64(32, true)),

package/dist/trajectory/parse/h5-utils.d.ts

@@ -0,0 +1,13 @@
+import type { ElementSymbol } from '../../element/types';
+import type { Matrix3x3 } from '../../math';
+import type { Dataset, Entity, Group } from 'h5wasm';
+import * as h5wasm from 'h5wasm';
+export declare const is_hdf5_dataset: (entity: Entity | null) => entity is Dataset;
+export declare const is_hdf5_group: (entity: Entity | null) => entity is Group;
+export declare const read_dataset: (h5_file: h5wasm.File, path: string) => unknown;
+export declare const to_string_array: (data: unknown) => string[] | null;
+export declare const to_number_array: (data: unknown) => number[] | null;
+export declare const to_scalar_number: (data: unknown) => number | null;
+export declare const scale_matrix: (matrix: Matrix3x3, scale: number) => Matrix3x3;
+export declare const expand_ion_types: (ion_types: string[], ion_counts: number[]) => ElementSymbol[];
+export declare function with_h5_file<T>(buffer: ArrayBuffer, filename: string | undefined, callback: (h5_file: h5wasm.File) => T | Promise<T>): Promise<T>;