matterviz 0.3.7 → 0.4.1

package/dist/trajectory/parse/pymatgen.js

@@ -0,0 +1,74 @@
+import * as math from '../../math';
+import { calc_force_stats, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+import { is_plain_object } from '../../utils';
+import { traj_warn } from './diagnostics';
+// Non-empty array of pymatgen Species-like objects with non-empty string element
+// symbols (predicate so callers get narrowing; rejects e.g. { element: null })
+const is_species_array = (val) => Array.isArray(val) &&
+    val.length > 0 &&
+    val.every((sp) => sp != null &&
+        typeof sp === `object` &&
+        `element` in sp &&
+        typeof sp.element === `string` &&
+        sp.element.trim().length > 0);
+// Parse an already-JSON-parsed pymatgen Trajectory object (detected via @class === 'Trajectory' with species/coords/lattice present)
+export function parse_pymatgen_trajectory(obj, filename) {
+    // Validate shape upfront so malformed input fails with a clear message
+    // (callers gate only on truthiness, not structure) rather than a cryptic `.map` error
+    if (!is_species_array(obj.species)) {
+        throw new TypeError(`Invalid pymatgen Trajectory: 'species' must be a non-empty array of { element } objects`);
+    }
+    if (!Array.isArray(obj.coords)) {
+        throw new TypeError(`Invalid pymatgen Trajectory: 'coords' must be an array of frames`);
+    }
+    const frame_elements = obj.species.map((specie) => specie.element);
+    const coords = obj.coords;
+    const matrix = validate_3x3_matrix(obj.lattice);
+    const frame_properties = obj.frame_properties || [];
+    const frac_to_cart = math.create_frac_to_cart(matrix);
+    const frames = coords.map((frame_coords, idx) => {
+        const positions = frame_coords.map((abc) => frac_to_cart(abc));
+        // Process frame properties to extract numpy arrays
+        const raw_properties = frame_properties[idx] || {};
+        const processed_properties = {};
+        Object.entries(raw_properties).forEach(([key, value]) => {
+            if (is_plain_object(value) && value[`@class`] === `array`) {
+                processed_properties[key] = value.data;
+                if (key === `forces` && Array.isArray(value.data)) {
+                    // Object.assign ignores the null calc_force_stats returns for empty forces
+                    Object.assign(processed_properties, calc_force_stats(value.data));
+                }
+                if (key === `stress` && Array.isArray(value.data)) {
+                    const stress_tensor = value.data;
+                    if (!math.is_square_matrix(stress_tensor, 3)) {
+                        traj_warn(`Invalid stress tensor structure in frame ${idx}`);
+                    }
+                    else {
+                        // Calculate stress components (diagonal elements represent normal stresses)
+                        const normal_stresses = [
+                            stress_tensor[0][0],
+                            stress_tensor[1][1],
+                            stress_tensor[2][2],
+                        ];
+                        processed_properties.stress_max = Math.max(...normal_stresses.map(Math.abs));
+                        // Calculate hydrostatic pressure (negative of mean normal stress)
+                        processed_properties.pressure =
+                            -(normal_stresses[0] + normal_stresses[1] + normal_stresses[2]) / 3;
+                    }
+                }
+            }
+            else {
+                processed_properties[key] = value;
+            }
+        });
+        return create_trajectory_frame(positions, frame_elements, matrix, [true, true, true], idx, processed_properties);
+    });
+    const metadata = {
+        filename,
+        source_format: `pymatgen_trajectory`,
+        frame_count: frames.length,
+        species_list: [...new Set(frame_elements)],
+        periodic_boundary_conditions: [true, true, true],
+    };
+    return { frames, metadata };
+}

package/dist/trajectory/parse/vasp.js

@@ -1,42 +1,62 @@
 import * as math from '../../math';
-import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+import { is_elem_symbol } from '../../element';
+import { create_trajectory_frame, validate_3x3_matrix } from '../helpers';
+// Parse the 7-line XDATCAR header at lines[start]: title, scale factor, 3 lattice rows
+// (multiplied by scale), element names, element counts
+function parse_xdatcar_header(lines, start) {
+    const scale = parseFloat(lines[start + 1]);
+    const rows = lines.slice(start + 2, start + 5).map((line) => line
+        .trim()
+        .split(/\s+/)
+        .map((val) => parseFloat(val) * scale));
+    const names = lines[start + 5].trim().split(/\s+/);
+    const counts = lines[start + 6].trim().split(/\s+/).map(Number);
+    return { scale, rows, names, counts };
+}
 export function parse_vasp_xdatcar(content, filename) {
     const lines = content.trim().split(/\r?\n/);
     if (lines.length < 10)
         throw new Error(`XDATCAR file too short`);
-    const scale = parseFloat(lines[1]);
-    if (isNaN(scale))
+    const header = parse_xdatcar_header(lines, 0);
+    const { names: element_names, counts: element_counts } = header;
+    if (isNaN(header.scale))
         throw new Error(`Invalid scale factor`);
-    const lattice_matrix = validate_3x3_matrix(lines.slice(2, 5).map((line) => line
-        .trim()
-        .split(/\s+/)
-        .map((component) => parseFloat(component) * scale)));
-    const element_names = lines[5].trim().split(/\s+/);
-    const element_counts = lines[6].trim().split(/\s+/).map(Number);
+    let lattice_matrix = validate_3x3_matrix(header.rows);
     if (element_names.length !== element_counts.length) {
         throw new Error(`XDATCAR element names/counts mismatch: names=${element_names.length}, counts=${element_counts.length}`);
     }
     if (element_counts.some((count) => !Number.isFinite(count) || !Number.isInteger(count) || count <= 0)) {
         throw new Error(`XDATCAR contains invalid element counts: expected finite positive integers`);
     }
-    const validated_element_names = element_names.map((name) => {
-        if (!is_valid_element_symbol(name)) {
-            throw new Error(`Invalid element symbol in XDATCAR: ${name}`);
-        }
-        return name;
-    });
-    const elements = validated_element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
+    const bad_element = element_names.find((name) => !is_elem_symbol(name));
+    if (bad_element)
+        throw new Error(`Invalid element symbol in XDATCAR: ${bad_element}`);
+    let elements = element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
     const frames = [];
     let line_idx = 7;
-    const frac_to_cart = math.create_frac_to_cart(lattice_matrix);
+    let frac_to_cart = math.create_frac_to_cart(lattice_matrix);
     while (line_idx < lines.length) {
         const config_idx = lines.findIndex((line, idx) => idx >= line_idx && line.includes(`Direct configuration=`));
         if (config_idx === -1)
             break;
+        // Variable-cell runs (NPT/ISIF=3) repeat the full 7-line header before each configuration
+        if (config_idx - line_idx >= 7) {
+            const hdr = parse_xdatcar_header(lines, config_idx - 7);
+            if (Number.isFinite(hdr.scale) &&
+                hdr.rows.every((row) => row.length === 3 && row.every(Number.isFinite))) {
+                lattice_matrix = validate_3x3_matrix(hdr.rows);
+                frac_to_cart = math.create_frac_to_cart(lattice_matrix);
+                if (hdr.names.length === hdr.counts.length &&
+                    hdr.names.every(is_elem_symbol) &&
+                    hdr.counts.every((count) => Number.isInteger(count) && count > 0)) {
+                    elements = hdr.names.flatMap((name, idx) => Array(hdr.counts[idx]).fill(name));
+                }
+            }
+        }
         const config_line = lines[config_idx];
         line_idx = config_idx + 1;
         const step_match = /configuration=\s*(\d+)/.exec(config_line);
-        const step = step_match ? parseInt(step_match[1]) : frames.length + 1;
+        const step = step_match ? parseInt(step_match[1], 10) : frames.length + 1;
         const positions = [];
         for (let idx = 0; idx < elements.length && line_idx < lines.length; idx++) {
             const coords = lines[line_idx].trim().split(/\s+/).slice(0, 3).map(Number);

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

@@ -1,2 +1,14 @@
-import type { TrajectoryType } from '../index';
+import type { TrajectoryFrame, TrajectoryType } from '../index';
+export declare function parse_xyz_comment_metadata(comment: string): {
+    step?: number;
+    properties: Record<string, number>;
+};
+export declare function build_xyz_frame(lines: string[], frame: {
+    start: number;
+    num_atoms: number;
+    comment: string;
+}, opts: {
+    frame_label: string;
+    default_step: number;
+}): TrajectoryFrame;
 export declare function parse_xyz_trajectory(content: string): TrajectoryType;

package/dist/trajectory/parse/xyz.js

@@ -1,103 +1,111 @@
 import * as math from '../../math';
-import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
-export function parse_xyz_trajectory(content) {
-    const lines = content.trim().split(/\r?\n/);
-    const frames = [];
-    let line_idx = 0;
-    while (line_idx < lines.length) {
-        if (!lines[line_idx]?.trim()) {
-            line_idx++;
-            continue;
+import { coerce_elem_symbol } from '../../element';
+import { calc_force_stats, create_trajectory_frame, iter_xyz_frames, } from '../helpers';
+import { traj_warn } from './diagnostics';
+// Resolve species/pos/forces column offsets from an extxyz Properties string of
+// name:type:ncols triples (e.g. "species:S:1:pos:R:3:forces:R:3"), falling back
+// to the conventional "symbol x y z" layout when absent or malformed
+function parse_extxyz_columns(comment) {
+    const fields = /Properties\s*=\s*"?([^"\s]+)"?/i.exec(comment)?.[1].split(`:`) ?? [];
+    // Well-formed Properties is name:type:ncols triples; a non-multiple of 3 is malformed,
+    // so bail to the conventional default rather than trusting a partial layout
+    let layout = fields.length % 3 === 0 ? {} : null;
+    for (let idx = 0, offset = 0; layout && idx + 3 <= fields.length; idx += 3) {
+        const ncols = parseInt(fields[idx + 2], 10);
+        if (Number.isInteger(ncols) && ncols > 0) {
+            layout[fields[idx].toLowerCase()] = { offset, ncols };
+            offset += ncols;
         }
-        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++;
+        else
+            layout = null;
+    }
+    const species_col = layout?.species?.offset ?? 0;
+    const pos_col = layout?.pos?.offset ?? 1;
+    const forces_col = layout?.forces && layout.forces.ncols >= 3 ? layout.forces.offset : -1;
+    return { species_col, pos_col, forces_col, min_cols: Math.max(pos_col + 3, species_col + 1) };
+}
+// Parse Lattice="ax ay az bx by bz cx cy cz" from an extxyz comment line
+function parse_extxyz_lattice(comment) {
+    const vals = /Lattice\s*=\s*"([^"]+)"/i.exec(comment)?.[1].trim().split(/\s+/).map(Number);
+    if (vals?.length !== 9 || !vals.every(Number.isFinite))
+        return undefined;
+    return [vals.slice(0, 3), vals.slice(3, 6), vals.slice(6, 9)];
+}
+// Keys anchored at ^|\s and followed by [=:] so single-letter keys (E/V/P/T) don't match mid-word
+const make_pattern = (keys) => new RegExp(`(?:^|\\s)(?:${keys})\\s*[=:]\\s*([-+]?\\d*\\.?\\d+(?:[eE][-+]?\\d+)?)`, `i`);
+const METADATA_PATTERNS = {
+    energy: make_pattern(`energy|E|etot|total_energy`),
+    volume: make_pattern(`volume|vol|V`),
+    pressure: make_pattern(`pressure|press|P`),
+    temperature: make_pattern(`temperature|temp|T`),
+    force_max: make_pattern(`max_force|force_max|fmax`),
+    bandgap: make_pattern(`bandgap|E_gap|gap`),
+};
+// Extract step number and scalar properties from an (ext)XYZ comment line
+export function parse_xyz_comment_metadata(comment) {
+    const properties = {};
+    for (const [key, pattern] of Object.entries(METADATA_PATTERNS)) {
+        const match = pattern.exec(comment);
+        if (match)
+            properties[key] = parseFloat(match[1]);
+    }
+    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i.exec(comment)?.[1];
+    return { step: step ? parseInt(step, 10) : undefined, properties };
+}
+// Parse num_atoms atom lines starting at lines[start], reading species/pos/forces from
+// their Properties-declared column offsets; invalid atoms are skipped with a warning.
+// force_stats holds raw forces plus max and RMS force magnitudes when forces are present.
+function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_label) {
+    const { species_col, pos_col, forces_col, min_cols } = parse_extxyz_columns(comment);
+    const elements = [];
+    const positions = [];
+    const forces = [];
+    for (let idx = 0; idx < num_atoms; idx++) {
+        const parts = lines[start + idx]?.trim().split(/\s+/) ?? [];
+        if (parts.length < min_cols)
+            continue;
+        const pos = parts.slice(pos_col, pos_col + 3).map(parseFloat);
+        if (!pos.every(Number.isFinite)) {
+            traj_warn(`Skipping XYZ atom with invalid coordinates in ${frame_label} at line ${start + idx + 1}`);
             continue;
         }
-        const comment = lines[++line_idx] || ``;
-        const metadata = {};
-        // Extract properties efficiently
-        const extractors = {
-            step: /(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i,
-            energy: /(?:energy|E|etot|total_energy)\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,
-            temperature: /(?:temperature|temp|T)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
-            force_max: /(?:max_force|force_max|fmax)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
-            bandgap: /(?:bandgap|E_gap|gap)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
-        };
-        const step_match = extractors.step.exec(comment);
-        const step = step_match?.[1] ? parseInt(step_match[1]) : frames.length;
-        Object.entries(extractors).forEach(([key, pattern]) => {
-            if (key === `step`)
-                return;
-            const match = pattern.exec(comment);
-            if (match)
-                metadata[key] = parseFloat(match[1]);
-        });
-        // Extract lattice matrix
-        const lattice_match = /Lattice\s*=\s*"([^"]+)"/i.exec(comment);
-        let lattice_matrix;
-        if (lattice_match) {
-            const values = lattice_match[1].split(/\s+/).map(Number);
-            if (values.length === 9 && values.every((value) => Number.isFinite(value))) {
-                lattice_matrix = [
-                    [values[0], values[1], values[2]],
-                    [values[3], values[4], values[5]],
-                    [values[6], values[7], values[8]],
-                ];
-                metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
-            }
-        }
-        // Parse atoms
-        const positions = [];
-        const elements = [];
-        const forces = [];
-        const has_forces = comment.includes(`forces:R:3`);
-        for (let idx = 0; idx < num_atoms; idx++) {
-            line_idx++;
-            if (line_idx >= lines.length)
-                break;
-            const parts = lines[line_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 frame ${frames.length} at line ${line_idx + 1}`);
-                    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 frame ${frames.length}`);
-                    continue;
-                }
-                elements.push(element_symbol);
-                positions.push([x_coord, y_coord, z_coord]);
-                if (has_forces && parts.length >= 7) {
-                    const force_x = parseFloat(parts[4]);
-                    const force_y = parseFloat(parts[5]);
-                    const force_z = parseFloat(parts[6]);
-                    if (Number.isFinite(force_x) &&
-                        Number.isFinite(force_y) &&
-                        Number.isFinite(force_z)) {
-                        forces.push([force_x, force_y, force_z]);
-                    }
-                }
-            }
+        const symbol = parts[species_col];
+        const element_symbol = coerce_elem_symbol(symbol);
+        if (!element_symbol) {
+            traj_warn(`Skipping XYZ atom with unknown element symbol "${symbol}" in ${frame_label}`);
+            continue;
         }
-        if (forces.length > 0) {
-            metadata.forces = forces;
-            const magnitudes = forces.map((force) => Math.hypot(...force));
-            metadata.force_max = Math.max(...magnitudes);
-            // Calculate RMS (root mean square) of force magnitudes
-            metadata.force_norm = Math.sqrt(magnitudes.reduce((sum, mag) => sum + mag ** 2, 0) / magnitudes.length);
+        elements.push(element_symbol);
+        positions.push(pos);
+        if (forces_col >= 0 && parts.length >= forces_col + 3) {
+            const force_vec = parts.slice(forces_col, forces_col + 3).map(parseFloat);
+            if (force_vec.every(Number.isFinite))
+                forces.push(force_vec);
         }
-        frames.push(create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step, metadata));
-        line_idx++;
+    }
+    const stats = calc_force_stats(forces);
+    return { elements, positions, force_stats: stats && { forces, ...stats } };
+}
+// Assemble a TrajectoryFrame from the XYZ frame starting at lines[start] (count line,
+// comment line, atom lines). Shared by the eager parser and the indexed frame reader.
+export function build_xyz_frame(lines, frame, opts) {
+    const { start, num_atoms, comment } = frame;
+    const { step, properties } = parse_xyz_comment_metadata(comment);
+    const lattice_matrix = parse_extxyz_lattice(comment);
+    const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, start + 2, num_atoms, comment, opts.frame_label);
+    const metadata = { ...properties, ...force_stats };
+    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 ?? opts.default_step, metadata);
+}
+export function parse_xyz_trajectory(content) {
+    const lines = content.trim().split(/\r?\n/);
+    const frames = [];
+    for (const frame of iter_xyz_frames(lines)) {
+        frames.push(build_xyz_frame(lines, frame, {
+            frame_label: `frame ${frames.length}`,
+            default_step: frames.length,
+        }));
     }
     return {
         frames,

package/dist/trajectory/plotting.d.ts

@@ -1,4 +1,4 @@
-import type { DataSeries } from '../plot/types';
+import type { DataSeries } from '../plot/core/types';
 import type { TrajectoryDataExtractor, TrajectoryMetadata, TrajectoryType } from './index';
 export interface PlotSeriesOptions {
     property_config?: Record<string, {
@@ -9,7 +9,6 @@ export interface PlotSeriesOptions {
     default_visible_properties?: Set<string>;
 }
 export declare function generate_plot_series(trajectory: TrajectoryType, data_extractor: TrajectoryDataExtractor, options?: PlotSeriesOptions): DataSeries[];
-export declare function toggle_series_visibility(series: DataSeries[], target_series_idx: number): DataSeries[];
 export declare function should_hide_plot(trajectory: TrajectoryType | undefined, plot_series: DataSeries[], tolerance?: number): boolean;
 export declare function generate_axis_labels(plot_series: DataSeries[]): {
     y1: string;

package/dist/trajectory/plotting.js

@@ -32,18 +32,9 @@ function extract_property_statistics(trajectory, data_extractor) {
             if (typeof value !== `number` || key === `Step` || key.startsWith(`constant_`)) {
                 return;
             }
-            if (!property_stats.has(key)) {
-                const stats = { values: [], sum: 0, sum_squares: 0, min: value, max: value };
-                property_stats.set(key, stats);
-            }
-            const stat = property_stats.get(key);
-            if (stat) {
-                stat.values.push(value);
-                stat.sum += value;
-                stat.sum_squares += value * value;
-                stat.min = Math.min(stat.min, value);
-                stat.max = Math.max(stat.max, value);
-            }
+            const stat = property_stats.get(key) ?? { values: [] };
+            property_stats.set(key, stat);
+            stat.values.push(value);
         });
     });
     // Convert to final format with variation detection
@@ -101,7 +92,7 @@ function group_and_assign_series(series, default_visible_properties) {
     // Group by unit
     const unit_map = new Map();
     for (const srs of series) {
-        const unit = srs.unit || `dimensionless`;
+        const unit = srs.unit ?? `dimensionless`;
         const group = unit_map.get(unit) ?? [];
         group.push(srs);
         unit_map.set(unit, group);
@@ -112,7 +103,7 @@ function group_and_assign_series(series, default_visible_properties) {
         const priority = calculate_priority(unit, group_series);
         const has_default_visible = group_series.some((srs) => {
             const metadata = Array.isArray(srs.metadata) ? srs.metadata[0] : srs.metadata;
-            const property_key = metadata?.property_key || srs.label || ``;
+            const property_key = (metadata?.property_key || srs.label) ?? ``;
             return is_default_visible(property_key, default_visible_properties);
         });
         return { unit, series: group_series, priority, is_visible: has_default_visible };
@@ -158,7 +149,7 @@ function extract_label_and_unit(key, property_config) {
     if (config)
         return { clean_label: config.label, unit: config.unit };
     return {
-        clean_label: key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, ` `),
+        clean_label: key.charAt(0).toUpperCase() + key.slice(1).replaceAll('_', ` `),
         unit: ``,
     };
 }
@@ -169,14 +160,14 @@ function calculate_priority(unit, group_series) {
         return unit_priority;
     // Energy properties get high priority
     const has_energy = group_series.some((srs) => {
-        const label = srs.label?.toLowerCase() || ``;
+        const label = srs.label?.toLowerCase() ?? ``;
         return ENERGY_PROPERTIES.some((prop) => label.includes(prop));
     });
     if (has_energy)
         return 10;
     // Force properties get medium priority
     const has_force = group_series.some((srs) => {
-        const label = srs.label?.toLowerCase() || ``;
+        const label = srs.label?.toLowerCase() ?? ``;
         return FORCE_PROPERTIES.some((prop) => label.includes(prop));
     });
     if (has_force)
@@ -187,8 +178,8 @@ function calculate_priority(unit, group_series) {
 const normalize_property_key = (key) => {
     const normalized = key
         .toLowerCase()
-        .replace(/<[^>]*>/g, ``)
-        .replace(/_/g, ` `)
+        .replaceAll(/<[^>]*>/g, ``)
+        .replaceAll('_', ` `)
         .trim();
     // Map common force property aliases to canonical form
     return [`fmax`, `f`, `force maximum`].includes(normalized) ? `force max` : normalized;
@@ -201,94 +192,6 @@ const is_default_visible = (property_key, default_properties) => {
     }
     return false;
 };
-// Optimized series visibility toggling
-export function toggle_series_visibility(series, target_series_idx) {
-    if (target_series_idx < 0 || target_series_idx >= series.length)
-        return series;
-    const target_series = series[target_series_idx];
-    const new_visibility = !target_series.visible;
-    // Create unit groups from current state
-    const unit_groups = create_unit_groups_from_series(series);
-    const target_group = unit_groups.find((group) => group.series.includes(target_series));
-    if (!target_group)
-        return series;
-    // Start with updating the target series visibility
-    const updated_series = series.map((srs) => srs === target_series ? { ...srs, visible: new_visibility } : { ...srs });
-    // Handle smart group replacement for new groups
-    if (new_visibility && !target_group.is_visible) {
-        const visible_groups = unit_groups.filter((group) => group.is_visible);
-        if (visible_groups.length >= 2) {
-            // Hide lowest priority group (highest priority number)
-            const lowest_priority_group = visible_groups
-                .sort((g1, g2) => g1.priority - g2.priority)
-                .pop(); // Get the last (lowest priority) group
-            if (lowest_priority_group) {
-                lowest_priority_group.is_visible = false;
-                // Also hide the actual series in this group
-                lowest_priority_group.series.forEach((srs1) => {
-                    const series_idx = updated_series.findIndex((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit);
-                    if (series_idx !== -1) {
-                        updated_series[series_idx] = { ...updated_series[series_idx], visible: false };
-                    }
-                });
-            }
-        }
-        target_group.is_visible = true;
-    }
-    // Recalculate group visibility and reassign axes
-    update_group_visibility_and_axes(updated_series, unit_groups);
-    return updated_series;
-}
-function create_unit_groups_from_series(series) {
-    const unit_map = new Map();
-    for (const srs of series) {
-        const unit = srs.unit || `dimensionless`;
-        const group = unit_map.get(unit) ?? [];
-        group.push(srs);
-        unit_map.set(unit, group);
-    }
-    return Array.from(unit_map.entries())
-        .map(([unit, group_series]) => ({
-        unit,
-        series: group_series,
-        priority: calculate_priority(unit, group_series),
-        is_visible: group_series.some((srs) => srs.visible),
-    }))
-        .sort((a, b) => a.priority - b.priority);
-}
-function update_group_visibility_and_axes(series, unit_groups) {
-    // Update group visibility based on series
-    for (const group of unit_groups) {
-        group.is_visible = group.series.some((srs1) => series.find((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit)?.visible);
-    }
-    // Apply 2-group limit
-    if (unit_groups.filter((unit_group) => unit_group.is_visible).length > 2) {
-        for (const group of unit_groups.filter((unit_group) => unit_group.is_visible).slice(2)) {
-            group.is_visible = false;
-            for (const srs1 of group.series) {
-                const idx = series.findIndex((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit);
-                if (idx !== -1)
-                    series[idx] = { ...series[idx], visible: false };
-            }
-        }
-    }
-    // Assign axes
-    const final_visible = unit_groups
-        .filter((group) => group.is_visible)
-        .sort((g1, g2) => g1.priority - g2.priority);
-    const axis_map = new Map();
-    if (final_visible.length >= 1)
-        axis_map.set(final_visible[0], `y1`);
-    if (final_visible.length === 2)
-        axis_map.set(final_visible[1], `y2`);
-    // Apply to series
-    for (const [idx, srs] of series.entries()) {
-        const group = unit_groups.find((unit_group) => unit_group.series.some((member) => member.label === srs.label && member.unit === srs.unit));
-        if (group && axis_map.has(group)) {
-            series[idx] = { ...srs, y_axis: axis_map.get(group) };
-        }
-    }
-}
 // Utility functions
 export function should_hide_plot(trajectory, plot_series, tolerance = 1e-10) {
     if (!trajectory || trajectory.frames.length <= 1 || plot_series.length === 0) {
@@ -313,12 +216,12 @@ export function should_hide_plot(trajectory, plot_series, tolerance = 1e-10) {
 }
 function get_axis_label(axis_series) {
     const visible_series = axis_series.filter((srs) => srs.visible);
-    if (!visible_series.length)
+    if (visible_series.length === 0)
         return `Value`;
     const unit_groups = new Map();
     visible_series.forEach((srs) => {
-        const unit = srs.unit || ``;
-        const label = srs.label || `Value`;
+        const unit = srs.unit ?? ``;
+        const label = srs.label ?? `Value`;
         if (!unit_groups.has(unit))
             unit_groups.set(unit, []);
         const group = unit_groups.get(unit);
@@ -326,14 +229,14 @@ function get_axis_label(axis_series) {
             group.push(label);
     });
     const unit_entries = Array.from(unit_groups.entries());
-    if (!unit_entries.length)
+    if (unit_entries.length === 0)
         return `Value`;
     const [unit, labels] = unit_entries[0];
     const unique_labels = [...new Set(labels)].sort().join(` / `);
     return unit ? `${unique_labels} (${unit})` : unique_labels;
 }
 export function generate_axis_labels(plot_series) {
-    if (!plot_series.length)
+    if (plot_series.length === 0)
         return { y1: `Value`, y2: `Value` };
     return {
         y1: get_axis_label(plot_series.filter((srs) => (srs.y_axis ?? `y1`) === `y1`)),
@@ -341,7 +244,7 @@ export function generate_axis_labels(plot_series) {
     };
 }
 export function generate_streaming_plot_series(metadata_list, options = {}) {
-    if (!metadata_list.length)
+    if (metadata_list.length === 0)
         return [];
     const { property_config = trajectory_property_config, colors = PLOT_COLORS, default_visible_properties = DEFAULT_VISIBLE, max_points = 10_000, // 10,000 plot points provides good visual fidelity while maintaining browser performance
      } = options;

package/dist/utils.d.ts

@@ -1,6 +1,8 @@
+export declare const is_plain_object: (val: unknown) => val is Record<string, unknown>;
 export declare function merge_nested<T extends Record<string, unknown>>(obj1: T, obj2?: Partial<T>): T;
 export declare const escape_html: (unsafe_string: string) => string;
 export declare const normalize_unicode_minus: (value: string) => string;
 export declare const normalize_scientific_notation: (value: string) => string;
+export declare const to_error: (value: unknown) => Error;
 export declare function make_change_detector(): (value: unknown) => boolean;
 export declare function decode_url_safe_base64(encoded: string): string | undefined;

package/dist/utils.js

@@ -1,5 +1,5 @@
 // Check if value is a plain object (not array, null, or other types)
-const is_plain_object = (val) => typeof val === `object` && val !== null && !Array.isArray(val);
+export const is_plain_object = (val) => typeof val === `object` && val !== null && !Array.isArray(val);
 // Merge nested objects (1 level deep).
 export function merge_nested(obj1, obj2) {
     const result = { ...obj1, ...obj2 };
@@ -18,11 +18,13 @@ export const escape_html = (unsafe_string) => unsafe_string
     .replaceAll(`"`, `"`)
     .replaceAll(`'`, `'`);
 // Normalize unicode minus (U+2212) to ASCII hyphen-minus.
-export const normalize_unicode_minus = (value) => value.replace(/−/g, `-`);
+export const normalize_unicode_minus = (value) => value.replaceAll('−', `-`);
 // Normalize scientific notation variants (d/D exponent, Mathematica *^).
-export const normalize_scientific_notation = (value) => normalize_unicode_minus(value).toLowerCase().replace(/d/g, `e`).replace(/\*\^/g, `e`);
+export const normalize_scientific_notation = (value) => normalize_unicode_minus(value).toLowerCase().replaceAll('d', `e`).replaceAll('*^', `e`);
+// Coerce an unknown thrown value into an Error (for typed Promise rejections / error callbacks).
+export const to_error = (value) => value instanceof Error ? value : new Error(String(value));
 export function make_change_detector() {
-    const unset = Symbol();
+    const unset = Symbol(`unset`);
     let prev = unset;
     return (value) => {
         const changed = prev !== unset && value !== prev;
@@ -34,7 +36,7 @@ export function make_change_detector() {
 // Converts `-` → `+`, `_` → `/`, restores padding, then decodes.
 // Returns undefined if decoding fails.
 export function decode_url_safe_base64(encoded) {
-    const std_b64 = encoded.replace(/-/g, `+`).replace(/_/g, `/`);
+    const std_b64 = encoded.replaceAll('-', `+`).replaceAll('_', `/`);
     const padded = std_b64 + `=`.repeat((4 - (std_b64.length % 4)) % 4);
     try {
         return atob(padded);