matterviz 0.4.0 → 0.4.1

package/dist/trajectory/frame-reader.js

@@ -1,9 +1,16 @@
 // Unified frame loader for XYZ and ASE trajectories (large file indexing)
 import * as math from '../math';
 import { MAX_METADATA_SIZE } from './constants';
-import { 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';
-import { parse_extxyz_lattice, parse_xyz_atom_lines, parse_xyz_comment_metadata, } from './parse/xyz';
+import { copy_numeric_fields, count_xyz_frames, iter_xyz_frames, validate_3x3_matrix, } from './helpers';
+import { strip_compression_extensions } from '../io';
+import { decode_ase_frame, read_ase_header } from './parse/ase';
+import { build_xyz_frame, parse_xyz_comment_metadata } from './parse/xyz';
+// Restrict frame metadata to the requested property keys (no-op when unset)
+const filter_properties = (metadata, properties) => {
+    if (!properties)
+        return;
+    metadata.properties = Object.fromEntries(Object.entries(metadata.properties).filter(([key]) => properties.includes(key)));
+};
 export class TrajFrameReader {
     format;
     global_numbers;
@@ -19,8 +26,7 @@ export class TrajFrameReader {
         }
         if (!(data instanceof ArrayBuffer))
             throw new Error(`ASE loader requires binary data`);
-        const view = new DataView(data);
-        return Number(view.getBigInt64(32, true));
+        return read_ase_header(new DataView(data)).n_items;
     }
     async build_frame_index(data, sample_rate, on_progress) {
         const total_frames = await this.get_total_frames(data);
@@ -31,35 +37,25 @@ export class TrajFrameReader {
             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;
-                }
+            const line_bytes = (idx) => encoder.encode(lines[idx]).length + newline_byte_len;
+            // cursor = next line whose bytes haven't been added to byte_offset yet
+            let [current_frame, cursor, byte_offset] = [0, 0, 0];
+            for (const { start, num_atoms } of iter_xyz_frames(lines)) {
+                if (current_frame >= total_frames)
+                    break;
+                // Accumulate bytes of blank/invalid lines skipped before this frame
+                for (; cursor < start; cursor++)
+                    byte_offset += line_bytes(cursor);
+                let frame_size = 0;
+                for (; cursor < start + num_atoms + 2; cursor++)
+                    frame_size += line_bytes(cursor);
                 if (current_frame % sample_rate === 0) {
                     frame_index.push({
                         frame_number: current_frame,
                         byte_offset,
-                        estimated_size: 0,
+                        estimated_size: frame_size,
                     });
                 }
-                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) {
@@ -73,7 +69,7 @@ export class TrajFrameReader {
         }
         else {
             const view = new DataView(data);
-            const offsets_pos = Number(view.getBigInt64(40, true));
+            const { offsets_pos } = read_ase_header(view);
             for (let idx = 0; idx < total_frames; idx += sample_rate) {
                 const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
                 frame_index.push({
@@ -111,34 +107,28 @@ export class TrajFrameReader {
         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;
-                }
+            let current_frame = 0;
+            for (const { start, comment } of iter_xyz_frames(lines)) {
+                if (current_frame >= total_frames)
+                    break;
                 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);
+                        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 ${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;
+                        console.warn(`Failed to parse XYZ metadata for frame ${current_frame} at line ${start + 1}:`, error);
                     }
-                    if (frame_metadata)
+                    if (frame_metadata) {
+                        filter_properties(frame_metadata, properties);
                         metadata_list.push(frame_metadata);
+                    }
                 }
-                line_idx += 2 + num_atoms;
                 current_frame++;
                 if (on_progress && current_frame % 5000 === 0) {
                     on_progress({
@@ -151,8 +141,7 @@ export class TrajFrameReader {
         }
         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));
+            const { n_items, offsets_pos } = read_ase_header(view);
             for (let idx = 0; idx < n_items; idx += sample_rate) {
                 try {
                     const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
@@ -163,10 +152,7 @@ export class TrajFrameReader {
                     }
                     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;
-                    }
+                    filter_properties(frame_metadata, properties);
                     metadata_list.push(frame_metadata);
                     if (on_progress && idx % 5000 === 0) {
                         on_progress({
@@ -185,105 +171,53 @@ export class TrajFrameReader {
     }
     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) {
-            const skip_atoms = parseInt(lines[line_idx].trim(), 10);
-            if (isNaN(skip_atoms) || skip_atoms <= 0) {
-                line_idx++; // skip blank/invalid lines until the next frame's atom-count line
-                continue;
-            }
-            line_idx += 2 + skip_atoms;
-            current_frame++;
+        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,
+            });
         }
-        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 lattice_matrix = parse_extxyz_lattice(comment);
-        const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, line_idx + 2, num_atoms, comment, `indexed frame ${frame_number}`);
-        const { step, properties } = this.parse_xyz_metadata(comment, frame_number);
-        const metadata = { ...properties, ...force_stats };
-        // Derive volume from the lattice (parity with the eager parse_xyz_trajectory parser)
-        if (lattice_matrix)
-            metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
-        return create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step, metadata);
+        return null;
     }
     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));
+            const { n_items, offsets_pos } = read_ase_header(view);
             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);
+            const { frame, numbers } = decode_ase_frame(view, data, frame_offset, frame_number, this.global_numbers);
+            this.global_numbers = numbers;
+            return frame;
         }
         catch (error) {
             console.warn(`Failed to load ASE frame ${frame_number}:`, error);
             return null;
         }
     }
-    parse_xyz_metadata(comment, frame_number) {
-        const { step, properties } = parse_xyz_comment_metadata(comment);
-        return { frame_number, step: step ?? frame_number, 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];
-                }
-            }
+            copy_numeric_fields(properties, frame_data.calculator, [
+                `energy`,
+                `potential_energy`,
+                `kinetic_energy`,
+                `total_energy`,
+            ]);
         }
         if (frame_data.info && typeof frame_data.info === `object`) {
-            const info = frame_data.info;
-            const info_properties = [
+            copy_numeric_fields(properties, frame_data.info, [
                 `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 {

package/dist/trajectory/helpers.d.ts

@@ -3,8 +3,6 @@ import * as math from '../math';
 import type { AnyStructure } from '../structure/index';
 import type { Pbc } from '../structure/pbc';
 import type { TrajectoryFrame } from './index';
-export declare const is_valid_element_symbol: (symbol: string) => symbol is ElementSymbol;
-export declare const 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;
@@ -12,4 +10,14 @@ export declare const create_trajectory_frame: (positions: number[][], elements:
 export declare const read_ndarray_from_view: (view: DataView, ref: {
     ndarray: unknown[];
 }) => number[][];
+export declare const copy_numeric_fields: (target: Record<string, number>, source: Record<string, unknown>, fields: readonly string[]) => void;
+export declare function calc_force_stats(forces: number[][]): {
+    force_max: number;
+    force_norm: number;
+} | null;
+export declare function iter_xyz_frames(lines: string[]): Generator<{
+    start: number;
+    num_atoms: number;
+    comment: string;
+}>;
 export declare function count_xyz_frames(data: string): number;

package/dist/trajectory/helpers.js

@@ -1,16 +1,14 @@
 // Shared utilities for trajectory parsing
 import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
-import { ELEM_SYMBOLS } from '../labels';
+import { is_elem_symbol } from '../element';
 import * as math from '../math';
-const element_symbol_set = new Set(ELEM_SYMBOLS);
+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);
-export const is_valid_element_symbol = (symbol) => element_symbol_set.has(symbol);
-export const coerce_element_symbol = (symbol) => 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) {
@@ -24,7 +22,7 @@ export function validate_3x3_matrix(data) {
 }
 export const convert_atomic_numbers = (numbers) => numbers.map((num) => {
     const symbol = ATOMIC_NUMBER_TO_SYMBOL[num];
-    if (!symbol || !is_valid_element_symbol(symbol)) {
+    if (!symbol || !is_elem_symbol(symbol)) {
         throw new Error(`Unknown atomic number in trajectory data: ${num}`);
     }
     return symbol;
@@ -42,13 +40,7 @@ export const create_structure = (positions, elements, lattice_matrix, pbc, force
         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 make_site(elements[idx], abc, xyz, `${elements[idx]}${idx + 1}`, properties);
     });
     return lattice_matrix
         ? {
@@ -126,39 +118,67 @@ export const read_ndarray_from_view = (view, ref) => {
                 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;
+// Copy listed fields from source to target when they hold numbers
+export const copy_numeric_fields = (target, source, fields) => {
+    for (const field of fields) {
+        if (field in source && typeof source[field] === `number`)
+            target[field] = source[field];
+    }
+};
+// Max and RMS of per-atom force magnitudes, or null when no forces present. Loop-based
+// rather than Math.max(...spread) to avoid call-stack overflow on very large frames.
+export function calc_force_stats(forces) {
+    if (forces.length === 0)
+        return null;
+    let force_max = -Infinity;
+    let sum_sq = 0;
+    for (const force of forces) {
+        const magnitude = Math.hypot(...force);
+        if (magnitude > force_max)
+            force_max = magnitude;
+        sum_sq += magnitude ** 2;
+    }
+    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
+// 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
+// the actual parse/index walk (both go through this single source of truth).
+export function* iter_xyz_frames(lines) {
     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);
+        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++;
+            line_idx++; // skip blank/invalid lines until the next frame's atom-count line
             continue;
         }
-        // Quick validation of first few atom lines
         let valid_coords = 0;
-        for (let idx = 0; idx < Math.min(num_atoms, 3); idx++) {
+        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) {
-                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;
+            if (parts?.length >= 4 &&
+                isNaN(parseInt(parts[0], 10)) &&
+                parts[0].length <= 3 &&
+                parts.slice(1, 4).every((coord) => !isNaN(parseFloat(coord))))
+                valid_coords++;
         }
-        else {
-            line_idx++;
+        if (valid_coords < sample) {
+            line_idx++; // count line looks valid but atom lines don't — likely non-XYZ content
+            continue;
         }
+        yield { start: line_idx, num_atoms, comment: lines[line_idx + 1] || `` };
+        line_idx += num_atoms + 2;
     }
+}
+// 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`)
+        return 0;
+    const frames = iter_xyz_frames(data.trim().split(/\r?\n/));
+    let frame_count = 0;
+    while (!frames.next().done)
+        frame_count += 1;
     return frame_count;
 }

package/dist/trajectory/parse/ase.d.ts

@@ -1,2 +1,10 @@
-import type { TrajectoryType } from '../index';
+import type { TrajectoryFrame, TrajectoryType } from '../index';
+export declare const read_ase_header: (view: DataView) => {
+    n_items: number;
+    offsets_pos: number;
+};
+export declare function decode_ase_frame(view: DataView, buffer: ArrayBuffer, frame_offset: number, step: number, fallback_numbers?: number[], max_json_length?: number): {
+    frame: TrajectoryFrame;
+    numbers: number[];
+};
 export declare function parse_ase_trajectory(buffer: ArrayBuffer, filename?: string): TrajectoryType;

package/dist/trajectory/parse/ase.js

@@ -1,18 +1,55 @@
 // 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';
+// 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)),
+    offsets_pos: Number(view.getBigInt64(40, true)),
+});
+// Decode a single ASE/ULM frame (JSON header + optional ndarray payloads) into a
+// TrajectoryFrame. Returns the atomic numbers actually used so callers can cache them
+// as fallback for later frames that omit `numbers` (ASE stores them only once).
+export function decode_ase_frame(view, buffer, frame_offset, step, fallback_numbers, max_json_length) {
+    const json_length = Number(view.getBigInt64(frame_offset, true));
+    if (max_json_length !== undefined && json_length > max_json_length) {
+        throw new Error(`frame JSON too large: ${json_length} bytes`);
+    }
+    const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, 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 ?? fallback_numbers;
+    const numbers = numbers_ref?.ndarray
+        ? read_ndarray_from_view(view, numbers_ref).flat()
+        : numbers_ref;
+    if (!numbers || !positions) {
+        throw new Error(`missing ${!numbers ? `numbers` : `positions`}`);
+    }
+    const cell = frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined;
+    const metadata = {
+        step,
+        ...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 ${step}:`, error);
+        }
+    }
+    const frame = create_trajectory_frame(positions, convert_atomic_numbers(numbers), cell, frame_data.pbc ?? [true, true, true], step, metadata);
+    return { frame, numbers };
+}
 export function parse_ase_trajectory(buffer, filename) {
     const view = new DataView(buffer);
-    let offset = 0;
     const signature = new TextDecoder().decode(new Uint8Array(buffer, 0, 8));
     if (signature !== `- of Ulm`)
         throw new Error(`Invalid ASE trajectory`);
-    offset += 24;
-    // Skip ASE/Ulm version field; current parsing logic is version-independent.
-    offset += 8;
-    const n_items = Number(view.getBigInt64(offset, true));
-    offset += 8;
-    const offsets_pos = Number(view.getBigInt64(offset, true));
+    const { n_items, offsets_pos } = read_ase_header(view);
     if (n_items <= 0)
         throw new Error(`Invalid frame count`);
     if (offsets_pos < 0 || offsets_pos + n_items * 8 > buffer.byteLength) {
@@ -23,31 +60,9 @@ export function parse_ase_trajectory(buffer, filename) {
     let global_numbers;
     for (let idx = 0; idx < n_items; idx++) {
         try {
-            offset = frame_offsets[idx];
-            const json_length = Number(view.getBigInt64(offset, true));
-            offset += 8;
-            if (json_length > MAX_SAFE_STRING_LENGTH) {
-                console.warn(`Skipping frame ${idx + 1}/${n_items}: too large`);
-                continue;
-            }
-            const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, offset, 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 ?? global_numbers;
-            const numbers = numbers_ref?.ndarray
-                ? read_ndarray_from_view(view, numbers_ref).flat()
-                : numbers_ref;
-            if (numbers)
-                global_numbers = numbers;
-            if (!numbers || !positions) {
-                console.warn(`Skipping ASE frame ${idx + 1}/${n_items}: missing ${!numbers ? `numbers` : `positions`}`);
-                continue;
-            }
-            const elements = convert_atomic_numbers(numbers);
-            const metadata = { step: idx, ...frame_data.calculator, ...frame_data.info };
-            frames.push(create_trajectory_frame(positions, elements, frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined, frame_data.pbc ?? [true, true, true], idx, metadata));
+            const { frame, numbers } = decode_ase_frame(view, buffer, frame_offsets[idx], idx, global_numbers, MAX_SAFE_STRING_LENGTH);
+            global_numbers = numbers;
+            frames.push(frame);
         }
         catch (error) {
             console.warn(`Error processing frame ${idx + 1}/${n_items}:`, error);

package/dist/trajectory/parse/diagnostics.d.ts

@@ -0,0 +1,3 @@
+export declare const get_traj_parse_warnings: () => string[];
+export declare const reset_traj_parse_warnings: () => void;
+export declare const traj_warn: (message: string, error?: unknown) => void;

package/dist/trajectory/parse/diagnostics.js

@@ -0,0 +1,14 @@
+import { to_error } from '../../utils';
+// Collector for non-fatal trajectory parse warnings (skipped atoms, dropped frames, plot-metadata extraction failures, ...) so they reach the UI not just the console. Reset at the start of each top-level parse call; format parsers append via traj_warn (mirrored to console.warn). Fatal failures throw — see parse_trajectory_data.
+let traj_parse_warnings = [];
+// Read-only snapshot of warnings since the last top-level parse (attached to trajectory metadata by parse/index.ts for UI surfacing)
+export const get_traj_parse_warnings = () => [...traj_parse_warnings];
+export const reset_traj_parse_warnings = () => void (traj_parse_warnings = []);
+export const traj_warn = (message, error) => {
+    const detail = error === undefined ? `` : `: ${to_error(error).message}`;
+    traj_parse_warnings.push(`${message}${detail}`);
+    if (error === undefined)
+        console.warn(message);
+    else
+        console.warn(`${message}:`, error);
+};

package/dist/trajectory/parse/index.d.ts

@@ -2,7 +2,7 @@ import { is_trajectory_file } from '../format-detect';
 import { TrajFrameReader } from '../frame-reader';
 import type { FrameLoader, ParseProgress, TrajectoryType } from '../index';
 import type { AtomTypeMapping, LoadingOptions } from '../types';
-export { INDEX_SAMPLE_RATE, LARGE_FILE_THRESHOLD, MAX_BIN_FILE_SIZE, MAX_METADATA_SIZE, MAX_SAFE_STRING_LENGTH, MAX_TEXT_FILE_SIZE, } from '../constants';
+export { LARGE_FILE_THRESHOLD, MAX_BIN_FILE_SIZE, MAX_TEXT_FILE_SIZE, } from '../constants';
 export type { AtomTypeMapping, LoadingOptions } from '../types';
 export { is_trajectory_file, TrajFrameReader };
 export declare function parse_trajectory_data(data: unknown, filename?: string, atom_type_mapping?: AtomTypeMapping): Promise<TrajectoryType>;