matterviz 0.3.6 → 0.4.0

package/dist/trajectory/TrajectoryInfoPane.svelte

@@ -0,0 +1,314 @@
+<script lang="ts">
+  import type { InfoItem } from '../layout'
+  import InfoPaneCards from '../overlays/InfoPaneCards.svelte'
+  import { format_num } from '../labels'
+  import DraggablePane from '../overlays/DraggablePane.svelte'
+  import { get_electro_neg_formula } from '../composition'
+  import { SETTINGS_CONFIG } from '../settings'
+  import type { AnyStructure } from '../structure'
+  import type { ComponentProps } from 'svelte'
+  import type { TrajectoryType } from './index'
+
+  let {
+    trajectory,
+    current_step_idx,
+    current_filename,
+    current_file_path,
+    file_size,
+    file_object,
+    pane_open = $bindable(false),
+    toggle_props,
+    pane_props,
+    ...rest
+  }: Omit<ComponentProps<typeof DraggablePane>, `children`> & {
+    trajectory: TrajectoryType
+    current_step_idx: number
+    current_filename?: string | null
+    current_file_path?: string | null
+    file_size?: number | null
+    file_object?: File | null
+    pane_open?: boolean
+    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
+  } = $props()
+
+  // Helper functions
+  const format_size = (bytes: number) =>
+    bytes > 1024 * 1024
+      ? `${format_num(bytes / (1024 * 1024), `.2~f`)} MB`
+      : `${format_num(bytes / 1024, `.2~f`)} KB`
+
+  const is_valid_number = (val: unknown): val is number =>
+    typeof val === `number` && isFinite(val)
+
+  const extract_numeric_array = (frames: typeof trajectory.frames, prop: string) =>
+    frames.map((frame) => frame.metadata?.[prop]).filter(is_valid_number)
+
+  const format_range = (values: number[], unit = ``, decimals = `.2~f`) => {
+    if (values.length === 0) return null
+    if (values.length === 1) {
+      return `${format_num(values[0], decimals)} ${unit}`.trim()
+    }
+    const [min, max] = [Math.min(...values), Math.max(...values)]
+    return `${format_num(min, decimals)} - ${format_num(max, decimals)} ${unit}`
+      .trim()
+  }
+
+  const safe_item = (
+    label: string,
+    value: string | null,
+    key?: string,
+    tooltip?: string,
+  ): InfoItem | null => value ? { label, value, key, tooltip } : null
+
+  // oxlint-disable-next-line eslint-plugin-unicorn/prefer-native-coercion-functions -- type predicate needed for narrowing
+  const is_info_item = (item: unknown): item is InfoItem => Boolean(item)
+
+  const safe_formula = (structure: AnyStructure) => {
+    try {
+      return get_electro_neg_formula(structure)
+    } catch {
+      return null
+    }
+  }
+
+  // Get trajectory info organized by sections
+  let info_pane_data = $derived.by(() => {
+    if (
+      (!trajectory?.frames?.length && !trajectory?.total_frames) ||
+      current_step_idx < 0 ||
+      current_step_idx >= (trajectory.total_frames ?? trajectory.frames?.length ?? 0)
+    ) return []
+
+    // For indexed trajectories, we might not have the current frame loaded
+    const current_frame = trajectory.frames?.[current_step_idx]
+    const total_frames = trajectory.total_frames ?? trajectory.frames?.length ?? 0
+
+    const sections: { title: string; items: InfoItem[] }[] = []
+
+    // File info section
+    const file_items = [
+      current_filename &&
+      safe_item(
+        `Name`,
+        current_filename,
+        `file-name`,
+        current_file_path || undefined,
+      ),
+      file_size && file_size > 0 &&
+      safe_item(`File Size`, format_size(file_size), `file-size`),
+      file_object?.lastModified &&
+      safe_item(
+        `Modified`,
+        new Date(file_object.lastModified).toLocaleString(),
+        `file-modified`,
+      ),
+      trajectory.metadata?.source_format &&
+      safe_item(`Format`, String(trajectory.metadata.source_format), `file-format`),
+    ].filter(is_info_item)
+
+    if (file_items.length > 0) {
+      sections.push({ title: `File`, items: file_items })
+    }
+
+    // Trajectory info section (always show this)
+    const traj_items = [
+      safe_item(
+        `Total Frames`,
+        `${format_num(total_frames, `.3~s`)} (current: ${
+          format_num(current_step_idx + 1, `.3~s`)
+        })`,
+        `total-frames`,
+      ),
+      trajectory.is_indexed &&
+      safe_item(
+        `Indexed`,
+        `Yes`,
+        `indexed-mode`,
+        SETTINGS_CONFIG.trajectory.use_indexing.description,
+      ),
+      trajectory.indexed_frames &&
+      safe_item(
+        `Index Points`,
+        `${trajectory.indexed_frames.length}`,
+        `index-points`,
+        `Number of frames indexed for fast seeking`,
+      ),
+      trajectory.plot_metadata &&
+      safe_item(
+        `Plot Metadata`,
+        `${trajectory.plot_metadata.length} frames`,
+        `plot-metadata`,
+        `Pre-extracted metadata for plotting`,
+      ),
+    ].filter(is_info_item)
+
+    if (traj_items.length > 0) {
+      sections.push({ title: `Trajectory`, items: traj_items })
+    }
+
+    // Structure info section (only if we have the current frame)
+    if (current_frame?.structure?.sites) {
+      const { structure } = current_frame
+      const lattice = `lattice` in structure ? structure.lattice : null
+      const { volume, a, b, c, alpha, beta, gamma } = lattice || {}
+      const formula = safe_formula(structure)
+
+      const structure_items = [
+        safe_item(`Atoms`, `${structure.sites.length}`, `atoms`),
+        formula && safe_item(`Formula`, String(formula), `formula`),
+        is_valid_number(volume) && volume > 0 &&
+        safe_item(`Volume`, `${format_num(volume, `.3~s`)} ų`, `volume`),
+        is_valid_number(volume) && volume > 0 && structure.sites.length > 0 &&
+        safe_item(
+          `Density`,
+          `${format_num(structure.sites.length / volume, `.4~s`)} atoms/ų`,
+          `density`,
+        ),
+        [a, b, c].every(is_valid_number) &&
+        safe_item(
+          `Cell Lengths`,
+          `${format_num(a as number, `.3~f`)}, ${format_num(b as number, `.3~f`)}, ${
+            format_num(c as number, `.3~f`)
+          } Å`,
+          `cell-lengths`,
+        ),
+        [alpha, beta, gamma].every(is_valid_number) &&
+        safe_item(
+          `Cell Angles`,
+          `${format_num(alpha as number, `.2~f`)}°, ${
+            format_num(beta as number, `.2~f`)
+          }°, ${format_num(gamma as number, `.2~f`)}°`,
+          `cell-angles`,
+        ),
+      ].filter(is_info_item)
+
+      if (structure_items.length > 0) {
+        sections.push({ title: `Structure`, items: structure_items })
+      }
+    } else if (trajectory.is_indexed) {
+      // For indexed trajectories, show a note that frame data is loaded on demand
+      const structure_items = [
+        safe_item(
+          `Frame Loading`,
+          `On-demand`,
+          `frame-loading`,
+          `Structure data loaded when frame is accessed`,
+        ),
+      ].filter(is_info_item)
+
+      if (structure_items.length > 0) {
+        sections.push({ title: `Structure`, items: structure_items })
+      }
+    }
+
+    // Energy section (only for regular trajectories with multiple frames)
+    if (!trajectory.is_indexed && trajectory.frames.length > 1) {
+      const energies = extract_numeric_array(trajectory.frames, `energy`)
+      if (energies.length > 1) {
+        const current_energy = current_frame?.metadata?.energy
+        const energy_range = format_range(energies, `eV`, `.3~s`)
+
+        const energy_items = [
+          is_valid_number(current_energy) &&
+          safe_item(
+            `Current Energy`,
+            `${format_num(current_energy, `.3~s`)} eV`,
+            `energy-current`,
+          ),
+          energy_range && safe_item(`Energy Range`, energy_range, `energy-range`),
+        ].filter(is_info_item)
+
+        if (energy_items.length > 0) {
+          sections.push({ title: `Energy`, items: energy_items })
+        }
+      }
+    }
+
+    // Forces section (only for regular trajectories with multiple frames)
+    if (!trajectory.is_indexed && trajectory.frames.length > 1) {
+      const forces = extract_numeric_array(trajectory.frames, `force_max`)
+      if (forces.length > 1) {
+        const current_force = current_frame?.metadata?.force_max
+        const force_range = format_range(forces, `eV/Å`, `.3~s`)
+
+        const force_items = [
+          is_valid_number(current_force) &&
+          safe_item(
+            `Max Force`,
+            `${format_num(current_force, `.3~s`)} eV/Å`,
+            `force-current`,
+          ),
+          force_range && safe_item(`Force Range`, force_range, `force-range`),
+        ].filter(is_info_item)
+
+        if (force_items.length > 0) {
+          sections.push({ title: `Forces`, items: force_items })
+        }
+      }
+    }
+
+    // Volume change section (only for regular trajectories)
+    if (
+      !trajectory.is_indexed && current_frame?.structure &&
+      trajectory.frames.length > 1
+    ) {
+      const lattice = `lattice` in current_frame.structure
+        ? current_frame.structure.lattice
+        : null
+      if (lattice) {
+        const volumes = trajectory.frames.map((
+          { structure },
+        ) => (`lattice` in structure && structure.lattice?.volume))
+          .filter(is_valid_number)
+          .filter((volume) => volume > 0)
+
+        if (volumes.length > 1) {
+          const vol_change = (Math.max(...volumes) - Math.min(...volumes)) /
+            Math.min(...volumes)
+          if (Math.abs(vol_change) > 0.1 && is_valid_number(vol_change)) {
+            const vol_items = [safe_item(
+              `Volume Change`,
+              `${format_num(vol_change, `.2~%`)}`,
+              `vol-change`,
+            )].filter(is_info_item)
+
+            if (vol_items.length > 0) {
+              sections.push({ title: `Volume`, items: vol_items })
+            }
+          }
+        }
+      }
+    }
+    return sections
+  })
+
+  let info_cards = $derived(
+    info_pane_data.map(({ title, items }) => ({ title, rows: items })),
+  )
+  let n_info_items = $derived(
+    info_pane_data.reduce((count, { items }) => count + items.length, 0),
+  )
+</script>
+
+<DraggablePane
+  bind:show={pane_open}
+  max_width="24em"
+  toggle_props={{
+    title: pane_open ? `` : `Trajectory info`,
+    ...toggle_props,
+    class: `trajectory-info-toggle ${toggle_props?.class ?? ``}`,
+  }}
+  open_icon="Cross"
+  closed_icon="Info"
+  pane_props={{ ...pane_props, class: `trajectory-info-pane ${pane_props?.class ?? ``}` }}
+  {...rest}
+>
+  <h4 id="trajectory-info" style="margin-top: 0">Trajectory Info</h4>
+  <InfoPaneCards
+    cards={info_cards}
+    filter_placeholder="Filter trajectory info"
+    empty_label="trajectory info"
+    show_filter={n_info_items > 5}
+  />
+</DraggablePane>

package/dist/trajectory/TrajectoryInfoPane.svelte.d.ts

@@ -0,0 +1,17 @@
+import DraggablePane from '../overlays/DraggablePane.svelte';
+import type { ComponentProps } from 'svelte';
+import type { TrajectoryType } from './index';
+type $$ComponentProps = Omit<ComponentProps<typeof DraggablePane>, `children`> & {
+    trajectory: TrajectoryType;
+    current_step_idx: number;
+    current_filename?: string | null;
+    current_file_path?: string | null;
+    file_size?: number | null;
+    file_object?: File | null;
+    pane_open?: boolean;
+    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`];
+    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`];
+};
+declare const TrajectoryInfoPane: import("svelte").Component<$$ComponentProps, {}, "pane_open">;
+type TrajectoryInfoPane = ReturnType<typeof TrajectoryInfoPane>;
+export default TrajectoryInfoPane;

package/dist/trajectory/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_SAFE_STRING_LENGTH: number;
+export declare const MAX_METADATA_SIZE: number;
+export declare const LARGE_FILE_THRESHOLD: number;
+export declare const INDEX_SAMPLE_RATE = 100;
+export declare const MAX_BIN_FILE_SIZE: number;
+export declare const MAX_TEXT_FILE_SIZE: number;

package/dist/trajectory/constants.js

@@ -0,0 +1,7 @@
+// Constants for trajectory parsing and large file handling
+export const MAX_SAFE_STRING_LENGTH = 0x1fffffe8 * 0.5; // 50% of JS max string length as safety
+export const MAX_METADATA_SIZE = 50 * 1024 * 1024; // 50MB limit for metadata
+export const LARGE_FILE_THRESHOLD = 400 * 1024 * 1024; // 400MB
+export const INDEX_SAMPLE_RATE = 100; // Default sample rate for frame indexing
+export const MAX_BIN_FILE_SIZE = 100 * 1024 * 1024; // 100MB default for ArrayBuffer files
+export const MAX_TEXT_FILE_SIZE = 50 * 1024 * 1024; // 50MB default for string files

package/dist/trajectory/extract.d.ts

@@ -0,0 +1,5 @@
+import type { TrajectoryDataExtractor } from './index';
+export declare const energy_data_extractor: TrajectoryDataExtractor;
+export declare const force_stress_data_extractor: TrajectoryDataExtractor;
+export declare const structural_data_extractor: TrajectoryDataExtractor;
+export declare const full_data_extractor: TrajectoryDataExtractor;

package/dist/trajectory/extract.js

@@ -0,0 +1,162 @@
+// Data extraction functions for trajectory analysis and plotting
+import { get_density } from '../structure/index';
+// 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
+        const energy_fields = [
+            `energy`,
+            `energy_per_atom`,
+            `potential_energy`,
+            `kinetic_energy`,
+            `total_energy`,
+        ];
+        for (const field of energy_fields) {
+            if (field in frame.metadata && typeof frame.metadata[field] === `number`) {
+                data[field] = frame.metadata[field];
+            }
+        }
+    }
+    return data;
+};
+// Data extractor for forces and stresses
+export const force_stress_data_extractor = (frame) => {
+    const data = {
+        Step: frame.step,
+    };
+    if (frame.metadata) {
+        // Calculate force properties from forces array if available (preferred)
+        if (frame.metadata.forces && Array.isArray(frame.metadata.forces)) {
+            const forces = frame.metadata.forces;
+            if (forces.length > 0) {
+                const force_magnitudes = forces.map((force) => Math.hypot(...force));
+                data.force_max = Math.max(...force_magnitudes);
+                // Calculate RMS (root mean square) of force magnitudes
+                data.force_norm = Math.sqrt(force_magnitudes.reduce((sum, f) => sum + f ** 2, 0) / force_magnitudes.length);
+            }
+        }
+        else {
+            // Fallback to metadata values if forces array not available
+            if (frame.metadata.force_max && typeof frame.metadata.force_max === `number`) {
+                data.force_max = frame.metadata.force_max;
+            }
+            // Prefer force_norm if available, fall back to force_rms
+            if (frame.metadata.force_norm && typeof frame.metadata.force_norm === `number`) {
+                data.force_norm = frame.metadata.force_norm;
+            }
+            else if (frame.metadata.force_rms && typeof frame.metadata.force_rms === `number`) {
+                data.force_norm = frame.metadata.force_rms; // Use force_rms as fallback
+            }
+        }
+        // Extract other stress and pressure properties (no duplicates expected)
+        const other_stress_fields = [`stress_max`, `stress_frobenius`, `stress_trace`, `pressure`];
+        for (const field of other_stress_fields) {
+            if (field in frame.metadata && typeof frame.metadata[field] === `number`) {
+                data[field] = frame.metadata[field];
+            }
+        }
+    }
+    return data;
+};
+// Data extractor for structural properties
+export const structural_data_extractor = (frame) => {
+    const data = {
+        Step: frame.step,
+    };
+    // Extract lattice properties (preferred source for volume)
+    if (`lattice` in frame.structure) {
+        const lattice = frame.structure.lattice;
+        data.volume = lattice.volume; // Use consistent lowercase naming
+        data.a = lattice.a;
+        data.b = lattice.b;
+        data.c = lattice.c;
+        data.alpha = lattice.alpha;
+        data.beta = lattice.beta;
+        data.gamma = lattice.gamma;
+    }
+    if (frame.metadata) {
+        // Extract other structural properties, avoiding volume duplicate
+        const structural_fields = [`temperature`];
+        for (const field of structural_fields) {
+            if (field in frame.metadata && typeof frame.metadata[field] === `number`)
+                data[field] = frame.metadata[field];
+        }
+        // Handle density separately - prefer metadata, but calculate if not available
+        if (frame.metadata.density && typeof frame.metadata.density === `number`) {
+            data.density = frame.metadata.density;
+        }
+        else if (`lattice` in frame.structure) {
+            try {
+                data.density = get_density(frame.structure);
+            }
+            catch (error) {
+                console.warn(`Failed to calculate density for frame ${frame.step}:`, error);
+            }
+        }
+        // Only use metadata volume if lattice volume is not available
+        if (!data.volume && frame.metadata.volume && typeof frame.metadata.volume === `number`) {
+            data.volume = frame.metadata.volume;
+        }
+        // Note: pressure is handled by force_stress_data_extractor to avoid duplication
+    }
+    else if (`lattice` in frame.structure) {
+        // Calculate density even when no metadata is available
+        try {
+            data.density = get_density(frame.structure);
+        }
+        catch (error) {
+            console.warn(`Failed to calculate density for frame ${frame.step}:`, error);
+        }
+    }
+    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 = [];
+    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);
+        }
+    }
+    if (values.length <= 1)
+        return false;
+    const first_value = values[0];
+    return values.some((value) => Math.abs(value - first_value) > tolerance);
+}
+// Combined data extractor that extracts all common properties
+export const full_data_extractor = (frame, trajectory) => {
+    const base_data = {
+        ...energy_data_extractor(frame, trajectory),
+        ...force_stress_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;
+        }
+    }
+    return result;
+};

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

@@ -0,0 +1,10 @@
+export declare function strip_compression_extensions(filename: string): string;
+export declare function ext_hint(filename: string | undefined, ext_regex: RegExp): boolean | null;
+export declare const FORMAT_PATTERNS: {
+    readonly ase: (data: unknown, filename?: string) => boolean;
+    readonly hdf5: (data: unknown, filename?: string) => boolean;
+    readonly vasp: (data: string, filename?: string) => boolean;
+    readonly xyz_multi: (data: string, filename?: string) => boolean;
+    readonly lammpstrj: (data: string, filename?: string) => boolean;
+};
+export declare function is_trajectory_file(filename: string, content?: string): boolean;

package/dist/trajectory/format-detect.js

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

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

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