matterviz 0.3.2 → 0.3.3

package/dist/trajectory/helpers.js

@@ -34,24 +34,11 @@ export const convert_atomic_numbers = (numbers) => numbers.map((num) => {
     }
     return symbol;
 });
-// Cache inverse matrices by original matrix reference for performance
-// IMPORTANT: This cache assumes lattice matrices are immutable. Mutating a cached
-// matrix in place yields incorrect inverses. Always create new matrix instances
-// if modifications are needed.
-const matrix_cache = new WeakMap();
-export const get_inverse_matrix = (matrix) => {
-    const cached = matrix_cache.get(matrix);
-    if (cached)
-        return cached;
-    const inverse = math.matrix_inverse_3x3(matrix);
-    matrix_cache.set(matrix, inverse);
-    return inverse;
-};
 export const create_structure = (positions, elements, lattice_matrix, pbc, force_data) => {
     if (positions.length !== elements.length) {
         throw new Error(`create_structure requires matching positions and elements lengths, got positions=${positions.length}, elements=${elements.length}`);
     }
-    const inv_matrix = lattice_matrix ? get_inverse_matrix(lattice_matrix) : null;
+    const cart_to_frac = lattice_matrix ? math.create_cart_to_frac(lattice_matrix) : null;
     const is_valid_vec3 = (coords) => Array.isArray(coords) &&
         coords.length === 3 &&
         coords.every((value) => typeof value === `number` && Number.isFinite(value));
@@ -60,9 +47,7 @@ export const create_structure = (positions, elements, lattice_matrix, pbc, force
             throw new Error(`Invalid position at index ${idx}: expected 3 finite coordinates`);
         }
         const xyz = pos;
-        const abc = inv_matrix
-            ? math.mat3x3_vec3_multiply(inv_matrix, xyz)
-            : [0, 0, 0];
+        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 {

package/dist/trajectory/index.js

@@ -3,6 +3,7 @@ export { default as TrajectoryError } from './TrajectoryError.svelte';
 export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte';
 export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte';
 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)
@@ -42,8 +43,7 @@ export function validate_trajectory(trajectory) {
                 else if (frame_idx.frame_number < 0) {
                     errors.push(`indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be non-negative`);
                 }
-                else if (idx > 0 &&
-                    frame_idx.frame_number <= indexed_frames[idx - 1].frame_number) {
+                else if (idx > 0 && frame_idx.frame_number <= indexed_frames[idx - 1].frame_number) {
                     errors.push(`indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be strictly increasing`);
                 }
                 if (typeof frame_idx.byte_offset !== `number`) {
@@ -85,16 +85,18 @@ export function get_trajectory_stats(trajectory) {
     if (frames.length > 0) {
         const [first_frame, last_frame] = [frames[0], frames.at(-1) ?? frames[0]];
         const max_sample = 100;
-        const sampled = frames.length <= max_sample ? frames : (() => {
-            const interval = Math.floor(frames.length / max_sample);
-            const result = [first_frame];
-            for (let idx = interval; idx < frames.length - 1; idx += interval) {
-                result.push(frames[idx]);
-            }
-            if (result.at(-1) !== last_frame)
-                result.push(last_frame);
-            return result;
-        })();
+        const sampled = frames.length <= max_sample
+            ? frames
+            : (() => {
+                const interval = Math.floor(frames.length / max_sample);
+                const result = [first_frame];
+                for (let idx = interval; idx < frames.length - 1; idx += interval) {
+                    result.push(frames[idx]);
+                }
+                if (result.at(-1) !== last_frame)
+                    result.push(last_frame);
+                return result;
+            })();
         const counts = sampled.map((frame) => frame.structure.sites.length);
         const constant = counts.every((c) => c === counts[0]);
         const all_counts = constant

package/dist/trajectory/parse/ase.js

@@ -15,8 +15,7 @@ export function parse_ase_trajectory(buffer, filename) {
     const offsets_pos = Number(view.getBigInt64(offset, true));
     if (n_items <= 0)
         throw new Error(`Invalid frame count`);
-    if (offsets_pos < 0 ||
-        offsets_pos + n_items * 8 > buffer.byteLength) {
+    if (offsets_pos < 0 || offsets_pos + n_items * 8 > buffer.byteLength) {
         throw new Error(`Invalid ASE frame offsets table bounds: offsets_pos=${offsets_pos}, n_items=${n_items}, byte_length=${buffer.byteLength}`);
     }
     const frame_offsets = Array.from({ length: n_items }, (_, idx) => Number(view.getBigInt64(offsets_pos + idx * 8, true)));
@@ -61,8 +60,10 @@ export function parse_ase_trajectory(buffer, filename) {
     if (frames.length === 0)
         throw new Error(`No valid frames found`);
     const first_struct = frames[0]?.structure;
-    const periodic_boundary_conditions = first_struct !== null && first_struct !== undefined &&
-        typeof first_struct === `object` && `lattice` in first_struct
+    const periodic_boundary_conditions = first_struct !== null &&
+        first_struct !== undefined &&
+        typeof first_struct === `object` &&
+        `lattice` in first_struct
         ? first_struct.lattice.pbc
         : [true, true, true];
     const metadata = {

package/dist/trajectory/parse/hdf5.js

@@ -2,11 +2,14 @@
 import { calc_lattice_params, transpose_3x3_matrix } from '../../math';
 import * as h5wasm from 'h5wasm';
 import { convert_atomic_numbers, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
-const is_hdf5_dataset = (entity) => entity !== null && (`to_array` in entity && entity instanceof h5wasm.Dataset);
-const is_hdf5_group = (entity) => entity !== null && (`keys` in entity && entity instanceof h5wasm.Group);
+const is_hdf5_dataset = (entity) => entity !== null && `to_array` in entity && entity instanceof h5wasm.Dataset;
+const is_hdf5_group = (entity) => entity !== null && `keys` in entity && entity instanceof h5wasm.Group;
 export async function parse_torch_sim_hdf5(buffer, filename) {
     const { FS } = await h5wasm.ready;
-    const file_basename = filename?.split(`/`).at(-1)?.replace(/[^\w.-]/g, `_`) || `temp`;
+    const file_basename = filename
+        ?.split(`/`)
+        .at(-1)
+        ?.replace(/[^\w.-]/g, `_`) || `temp`;
     const unique_suffix = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
     const temp_filename = `${file_basename}-${unique_suffix}.h5`;
     FS.writeFile(temp_filename, new Uint8Array(buffer));
@@ -37,9 +40,13 @@ export async function parse_torch_sim_hdf5(buffer, filename) {
             };
             return discover(h5_file);
         };
-        const positions_data = find_dataset([`positions`, `coords`, `coordinates`])
-            ?.to_array();
-        const atomic_numbers_data = find_dataset([`atomic_numbers`, `numbers`, `Z`, `species`])?.to_array();
+        const positions_data = find_dataset([`positions`, `coords`, `coordinates`])?.to_array();
+        const atomic_numbers_data = find_dataset([
+            `atomic_numbers`,
+            `numbers`,
+            `Z`,
+            `species`,
+        ])?.to_array();
         const cells_data = find_dataset([`cell`, `cells`, `lattice`])?.to_array();
         const energies_data = find_dataset([`potential_energy`, `energy`])?.to_array();
         if (!positions_data || !atomic_numbers_data) {
@@ -68,9 +75,7 @@ export async function parse_torch_sim_hdf5(buffer, filename) {
             const frame_atomic_numbers = atomic_numbers[idx] || atomic_numbers[0];
             const frame_elements = convert_atomic_numbers(frame_atomic_numbers);
             const cell = cells_data?.[idx];
-            const lattice_mat = cell
-                ? transpose_3x3_matrix(validate_3x3_matrix(cell))
-                : undefined;
+            const lattice_mat = cell ? transpose_3x3_matrix(validate_3x3_matrix(cell)) : undefined;
             const energy_entry = energies_data?.[idx];
             const energy = Array.isArray(energy_entry) ? energy_entry[0] : energy_entry;
             const metadata = {};
@@ -82,27 +87,28 @@ export async function parse_torch_sim_hdf5(buffer, filename) {
             const pbc = lattice_mat ? [true, true, true] : [false, false, false];
             return create_trajectory_frame(frame_pos, frame_elements, lattice_mat, pbc, idx, metadata);
         });
-        const first_frame_elements = frames[0]?.structure.sites.map((site) => site.species[0].element) ??
-            [];
+        const first_frame_elements = frames[0]?.structure.sites.map((site) => site.species[0].element) ?? [];
         return {
             frames,
             metadata: {
                 source_format: `hdf5_trajectory`,
                 frame_count: frames.length,
                 num_atoms: first_frame_elements.length,
-                periodic_boundary_conditions: cells_data
-                    ? [true, true, true]
-                    : [false, false, false],
+                periodic_boundary_conditions: cells_data ? [true, true, true] : [false, false, false],
                 element_counts: first_frame_elements.reduce((counts, element) => {
                     counts[element] = (counts[element] || 0) + 1;
                     return counts;
                 }, {}),
                 discovered_datasets: {
-                    positions: found_paths.positions || found_paths.coords ||
+                    positions: found_paths.positions ||
+                        found_paths.coords ||
                         found_paths.coordinates ||
                         `unknown`,
-                    atomic_numbers: found_paths.atomic_numbers || found_paths.numbers ||
-                        found_paths.Z || found_paths.species || `unknown`,
+                    atomic_numbers: found_paths.atomic_numbers ||
+                        found_paths.numbers ||
+                        found_paths.Z ||
+                        found_paths.species ||
+                        `unknown`,
                     cells: found_paths.cell || found_paths.cells || found_paths.lattice,
                     energies: found_paths.potential_energy || found_paths.energy,
                 },
@@ -116,6 +122,8 @@ export async function parse_torch_sim_hdf5(buffer, filename) {
         try {
             FS.unlink(temp_filename);
         }
-        catch { /* temp file cleanup is best-effort */ }
+        catch {
+            /* temp file cleanup is best-effort */
+        }
     }
 }

package/dist/trajectory/parse/index.js

@@ -10,9 +10,8 @@ import { parse_torch_sim_hdf5 } from './hdf5';
 import { parse_lammps_trajectory } from './lammps';
 import { parse_vasp_xdatcar } from './vasp';
 import { parse_xyz_trajectory } from './xyz';
-const log_parse_debug = (message, error) => {
-    console.debug(message, error);
-};
+// Silently swallow expected parse fallbacks — the caller throws if ALL formats fail
+const log_parse_debug = (_message, _error) => { };
 // Re-export constants and types for consumers
 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 { is_trajectory_file, TrajFrameReader };
@@ -56,7 +55,7 @@ export async function parse_trajectory_data(data, filename, atom_type_mapping) {
         }
         catch (error) {
             log_parse_debug(`JSON parse failed for ${filename ?? `unknown file`}:`, error);
-            throw new Error(`Unsupported text format`);
+            throw new Error(`Unsupported text format`, { cause: error });
         }
     }
     if (!data || typeof data !== `object`)
@@ -89,7 +88,8 @@ export async function parse_trajectory_data(data, filename, atom_type_mapping) {
             const raw_properties = frame_properties[idx] || {};
             const processed_properties = {};
             Object.entries(raw_properties).forEach(([key, value]) => {
-                if (value && typeof value === `object` &&
+                if (value &&
+                    typeof value === `object` &&
                     value[`@class`] === `array`) {
                     // Extract numpy array data
                     const array_obj = value;
@@ -99,9 +99,8 @@ export async function parse_trajectory_data(data, filename, atom_type_mapping) {
                         const forces = array_obj.data;
                         const force_magnitudes = forces.map((force) => Math.hypot(...force));
                         if (force_magnitudes.length > 0) {
-                            processed_properties.force_max = force_magnitudes.reduce((max_val, magnitude) => magnitude > max_val ? magnitude : max_val, force_magnitudes[0]);
-                            processed_properties.force_norm = Math.sqrt(force_magnitudes.reduce((sum, f) => sum + f ** 2, 0) /
-                                force_magnitudes.length);
+                            processed_properties.force_max = force_magnitudes.reduce((max_val, magnitude) => (magnitude > max_val ? magnitude : max_val), force_magnitudes[0]);
+                            processed_properties.force_norm = Math.sqrt(force_magnitudes.reduce((sum, f) => sum + f ** 2, 0) / force_magnitudes.length);
                         }
                     }
                     // Calculate stress statistics for stress tensor
@@ -193,9 +192,7 @@ export async function parse_trajectory_async(data, filename, on_progress, option
     const update_progress = (current, stage) => on_progress?.({ current, total: 100, stage });
     try {
         update_progress(0, `Detecting format...`);
-        const data_size = data instanceof ArrayBuffer
-            ? data.byteLength
-            : new TextEncoder().encode(data).byteLength;
+        const data_size = data instanceof ArrayBuffer ? data.byteLength : new TextEncoder().encode(data).byteLength;
         const is_large_file = data_size > LARGE_FILE_THRESHOLD;
         const should_use_indexing = use_indexing ?? is_large_file;
         if (is_large_file) {
@@ -260,14 +257,12 @@ async function parse_with_unified_loader(data, filename, options, on_progress) {
     }
     const stage = `Ready: ${total_frames} frames indexed`;
     on_progress?.({ current: 100, total: 100, stage });
+    const source_format = filename.toLowerCase().endsWith(`.traj`)
+        ? `ase_trajectory`
+        : `xyz_trajectory`;
     return {
         frames,
-        metadata: {
-            source_format: filename.toLowerCase().endsWith(`.traj`)
-                ? `ase_trajectory`
-                : `xyz_trajectory`,
-            frame_count: total_frames,
-        },
+        metadata: { source_format, frame_count: total_frames },
         total_frames,
         indexed_frames: frame_index,
         plot_metadata,
@@ -277,7 +272,7 @@ async function parse_with_unified_loader(data, filename, options, on_progress) {
 }
 // Factory function for frame loader (simplified)
 export function create_frame_loader(filename) {
-    if (!filename.toLowerCase().match(/\.(xyz|extxyz|traj)$/)) {
+    if (!/\.(xyz|extxyz|traj)$/.exec(filename.toLowerCase())) {
         throw new Error(`Unsupported format for frame loading: ${filename}`);
     }
     return new TrajFrameReader(filename);

package/dist/trajectory/parse/lammps.js

@@ -15,15 +15,22 @@ export function parse_lammps_box(box_lines, is_triclinic) {
     if (!is_triclinic) {
         // Orthogonal: bounds = [lo, hi] per dimension
         const [[lo_x, hi_x], [lo_y, hi_y], [lo_z, hi_z]] = bounds;
-        return [[hi_x - lo_x, 0, 0], [0, hi_y - lo_y, 0], [0, 0, hi_z - lo_z]];
+        return [
+            [hi_x - lo_x, 0, 0],
+            [0, hi_y - lo_y, 0],
+            [0, 0, hi_z - lo_z],
+        ];
     }
     // Triclinic: bounds = [lo_bound, hi_bound, tilt] with tilts xy, xz, yz
     const [[xlo_b, xhi_b, xy], [ylo_b, yhi_b, xz], [zlo_b, zhi_b, yz]] = bounds;
-    const lx = (xhi_b - Math.max(0, xy, xz, xy + xz)) -
-        (xlo_b - Math.min(0, xy, xz, xy + xz));
-    const ly = (yhi_b - Math.max(0, yz)) - (ylo_b - Math.min(0, yz));
+    const lx = xhi_b - Math.max(0, xy, xz, xy + xz) - (xlo_b - Math.min(0, xy, xz, xy + xz));
+    const ly = yhi_b - Math.max(0, yz) - (ylo_b - Math.min(0, yz));
     const lz = zhi_b - zlo_b;
-    return [[lx, 0, 0], [xy, ly, 0], [xz, yz, lz]];
+    return [
+        [lx, 0, 0],
+        [xy, ly, 0],
+        [xz, yz, lz],
+    ];
 }
 // Parse LAMMPS trajectory (.lammpstrj). Atom types mapped to elements via atom_type_mapping
 // or by default: 1→H, 2→He, etc. Supports orthogonal and triclinic simulation boxes.
@@ -140,7 +147,10 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
         }
         if (positions.length === elements.length && positions.length === num_atoms) {
             const { volume } = math.calc_lattice_params(lattice_matrix);
-            frames.push(create_trajectory_frame(positions, elements, lattice_matrix, pbc, timestep, { volume, timestep }));
+            frames.push(create_trajectory_frame(positions, elements, lattice_matrix, pbc, timestep, {
+                volume,
+                timestep,
+            }));
         }
     }
     if (frames.length === 0) {
@@ -159,7 +169,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
             source_format: `lammps_trajectory`,
             frame_count: frames.length,
             total_atoms: first_frame.structure.sites.length,
-            periodic_boundary_conditions: (`lattice` in first_frame.structure)
+            periodic_boundary_conditions: `lattice` in first_frame.structure
                 ? first_frame.structure.lattice.pbc
                 : [true, true, true],
             atom_types: Array.from(atom_types_found).sort((a, b) => a - b),

package/dist/trajectory/parse/vasp.js

@@ -7,7 +7,10 @@ export function parse_vasp_xdatcar(content, filename) {
     const scale = parseFloat(lines[1]);
     if (isNaN(scale))
         throw new Error(`Invalid scale factor`);
-    const lattice_matrix = validate_3x3_matrix(lines.slice(2, 5).map((line) => line.trim().split(/\s+/).map((x) => parseFloat(x) * scale)));
+    const lattice_matrix = validate_3x3_matrix(lines.slice(2, 5).map((line) => line
+        .trim()
+        .split(/\s+/)
+        .map((x) => parseFloat(x) * scale)));
     const element_names = lines[5].trim().split(/\s+/);
     const element_counts = lines[6].trim().split(/\s+/).map(Number);
     if (element_names.length !== element_counts.length) {
@@ -32,7 +35,7 @@ export function parse_vasp_xdatcar(content, filename) {
             break;
         const config_line = lines[config_idx];
         line_idx = config_idx + 1;
-        const step_match = config_line.match(/configuration=\s*(\d+)/);
+        const step_match = /configuration=\s*(\d+)/.exec(config_line);
         const step = step_match ? parseInt(step_match[1]) : frames.length + 1;
         const positions = [];
         for (let idx = 0; idx < elements.length && line_idx < lines.length; idx++) {

package/dist/trajectory/parse/xyz.js

@@ -36,16 +36,16 @@ export function parse_xyz_trajectory(content) {
                 metadata[key] = parseFloat(match[1]);
         });
         // Extract lattice matrix
-        const lattice_match = comment.match(/Lattice\s*=\s*"([^"]+)"/i);
+        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]]];
+                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;
             }
         }
@@ -63,7 +63,8 @@ export function parse_xyz_trajectory(content) {
                 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) ||
+                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;

package/dist/trajectory/plotting.js

@@ -107,7 +107,8 @@ function group_and_assign_series(series, default_visible_properties) {
         unit_map.set(unit, group);
     }
     // Create unit groups with priority and visibility
-    const groups = Array.from(unit_map.entries()).map(([unit, group_series]) => {
+    const groups = Array.from(unit_map.entries())
+        .map(([unit, group_series]) => {
         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;
@@ -115,7 +116,8 @@ function group_and_assign_series(series, default_visible_properties) {
             return is_default_visible(property_key, default_visible_properties);
         });
         return { unit, series: group_series, priority, is_visible: has_default_visible };
-    }).sort((a, b) => a.priority - b.priority);
+    })
+        .sort((a, b) => a.priority - b.priority);
     // Apply 2-group visibility limit
     const visible_groups = groups.filter((g) => g.is_visible);
     if (visible_groups.length > 2) {
@@ -183,7 +185,11 @@ function calculate_priority(unit, group_series) {
 }
 // Normalize property keys for robust matching (handles case, underscores, and common aliases)
 const normalize_property_key = (key) => {
-    const normalized = key.toLowerCase().replace(/<[^>]*>/g, ``).replace(/_/g, ` `).trim();
+    const normalized = key
+        .toLowerCase()
+        .replace(/<[^>]*>/g, ``)
+        .replace(/_/g, ` `)
+        .trim();
     // Map common force property aliases to canonical form
     return [`fmax`, `f`, `force maximum`].includes(normalized) ? `force max` : normalized;
 };
@@ -213,7 +219,8 @@ export function toggle_series_visibility(series, target_series_idx) {
         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)
+            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;
@@ -358,8 +365,7 @@ export function generate_streaming_plot_series(metadata_list, options = {}) {
         if (!is_energy && !has_significant_variation(data_points.map((p) => p.y)))
             continue;
         const { clean_label, unit } = extract_label_and_unit(property_key, property_config);
-        const is_visible = is_default_visible(property_key, default_visible_properties) ||
-            color_idx < 2;
+        const is_visible = is_default_visible(property_key, default_visible_properties) || color_idx < 2;
         const color = colors[color_idx % colors.length];
         if (is_visible)
             visible_props.push({ property: property_key, unit });
@@ -411,8 +417,7 @@ function determine_axis_from_groups(property, unit, visible_properties) {
     }));
     const groups = group_and_assign_series(mock_series, new Set([property]));
     const target_group = groups.find((group) => group.series.some((srs) => srs.label === property && srs.unit === unit));
-    return target_group &&
-        groups.filter((group) => group.is_visible).indexOf(target_group) === 1
+    return target_group && groups.filter((group) => group.is_visible).indexOf(target_group) === 1
         ? `y2`
         : `y1`;
 }

package/dist/utils.d.ts

@@ -2,3 +2,4 @@ export declare function merge_nested<T extends Record<string, unknown>>(obj1: 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 function decode_url_safe_base64(encoded: string): string | undefined;

package/dist/utils.js

@@ -21,3 +21,16 @@ export const escape_html = (unsafe_string) => unsafe_string
 export const normalize_unicode_minus = (value) => value.replace(/−/g, `-`);
 // 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`);
+// Decode a URL-safe base64 string (RFC 4648 §5) to its original text.
+// 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 padded = std_b64 + `=`.repeat((4 - (std_b64.length % 4)) % 4);
+    try {
+        return atob(padded);
+    }
+    catch {
+        return undefined;
+    }
+}