matterviz 0.4.2 → 0.4.3

package/dist/file-viewer/detect.js

@@ -0,0 +1,381 @@
+// Data type detection for JSON values -- determines which visualization component to use.
+// Used by JsonBrowser and the file renderer to select visualization components.
+import { build_path } from '../json-path';
+import { is_optimade_raw } from '../structure/parse';
+export { resolve_path } from '../json-path';
+// Human-readable labels for badge display
+export const TYPE_LABELS = {
+    structure: `Structure`,
+    fermi_surface: `Fermi Surface`,
+    band_grid: `Band Grid`,
+    convex_hull: `Convex Hull`,
+    volumetric: `Volumetric`,
+    phase_diagram: `Phase Diagram`,
+    band_structure: `Band Structure`,
+    dos: `DOS`,
+    bands_and_dos: `Bands + DOS`,
+    brillouin_zone: `Brillouin Zone`,
+    xrd: `XRD`,
+    table: `Table`,
+    plot: `Plot`,
+};
+// Badge colors per type (CSS color values)
+export const TYPE_COLORS = {
+    structure: `#4fc3f7`,
+    fermi_surface: `#ab47bc`,
+    band_grid: `#7e57c2`,
+    convex_hull: `#66bb6a`,
+    volumetric: `#ffa726`,
+    phase_diagram: `#ef5350`,
+    band_structure: `#29b6f6`,
+    dos: `#26a69a`,
+    bands_and_dos: `#5c6bc0`,
+    brillouin_zone: `#8d6e63`,
+    xrd: `#ec407a`,
+    table: `#78909c`,
+    plot: `#7c3aed`,
+};
+// === Type Guards ===
+// Narrows unknown to a non-array object record; used by every type guard below
+const as_record = (obj) => obj && typeof obj === `object` && !Array.isArray(obj)
+    ? obj
+    : null;
+// Check that `key` on `data` is an Array with exactly `len` elements (or any length if omitted)
+const has_array = (data, key, len) => {
+    const val = data[key];
+    return Array.isArray(val) && (len === undefined || val.length === len);
+};
+// Structure: must have non-empty `sites` array where first site has `species` + coordinates
+function is_structure(obj) {
+    const data = as_record(obj);
+    if (!data || !has_array(data, `sites`))
+        return false;
+    const sites = data.sites;
+    if (sites.length === 0)
+        return false;
+    const first_site = as_record(sites[0]);
+    if (!first_site)
+        return false;
+    const has_species = Array.isArray(first_site.species) && first_site.species.length > 0;
+    return has_species && (Array.isArray(first_site.abc) || Array.isArray(first_site.xyz));
+}
+// FermiSurfaceData: pre-computed isosurfaces with reciprocal lattice info
+function is_fermi_surface(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    return (has_array(data, `isosurfaces`) &&
+        has_array(data, `k_lattice`, 3) &&
+        typeof data.fermi_energy === `number` &&
+        (data.reciprocal_cell === `wigner_seitz` || data.reciprocal_cell === `parallelepiped`) &&
+        Boolean(as_record(data.metadata)));
+}
+// BandGridData: raw band energies on a k-grid (needs marching cubes extraction)
+function is_band_grid(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    return (has_array(data, `energies`) &&
+        has_array(data, `k_grid`, 3) &&
+        has_array(data, `k_lattice`, 3) &&
+        typeof data.fermi_energy === `number` &&
+        typeof data.n_bands === `number` &&
+        typeof data.n_spins === `number`);
+}
+// ConvexHull entries: array of objects with `composition` (object) + energy field
+// Accepts `energy`, `e_form_per_atom`, or `energy_per_atom` as the energy key
+function is_convex_hull_entries(obj) {
+    if (!Array.isArray(obj) || obj.length < 2)
+        return false;
+    // Check first few entries to avoid false positives on random arrays
+    return obj.slice(0, 3).every((item) => {
+        const entry = as_record(item);
+        return (entry &&
+            as_record(entry.composition) &&
+            (typeof entry.energy === `number` ||
+                typeof entry.e_form_per_atom === `number` ||
+                typeof entry.energy_per_atom === `number`));
+    });
+}
+// VolumetricData: 3D scalar grid with lattice info
+function is_volumetric(obj) {
+    const data = as_record(obj);
+    if (!data || !has_array(data, `grid`))
+        return false;
+    // grid must be a 3D array (array of arrays of arrays)
+    const grid = data.grid;
+    if (grid.length === 0)
+        return false;
+    const first_slice = grid[0];
+    if (!Array.isArray(first_slice) || !first_slice.length || !Array.isArray(first_slice[0]))
+        return false;
+    return (has_array(data, `grid_dims`, 3) &&
+        has_array(data, `lattice`, 3) &&
+        has_array(data, `origin`, 3) &&
+        Boolean(as_record(data.data_range)) &&
+        typeof data.periodic === `boolean`);
+}
+// PhaseDiagramData: binary phase diagram with components, regions, boundaries
+function is_phase_diagram(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    if (!has_array(data, `components`, 2))
+        return false;
+    const [comp_a, comp_b] = data.components;
+    if (typeof comp_a !== `string` || typeof comp_b !== `string`)
+        return false;
+    return (has_array(data, `regions`) &&
+        has_array(data, `boundaries`) &&
+        has_array(data, `temperature_range`, 2));
+}
+// BandStructure: normalized format (qpoints, branches, bands, nb_bands)
+// or pymatgen format (kpoints, branches, bands with spin keys, labels_dict)
+function is_band_structure(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    if (!has_array(data, `branches`) || data.branches.length === 0) {
+        return false;
+    }
+    if (!as_record(data.labels_dict))
+        return false;
+    // Normalized format
+    if (has_array(data, `qpoints`) &&
+        has_array(data, `bands`) &&
+        typeof data.nb_bands === `number`)
+        return true;
+    // Pymatgen format: kpoints + bands object (not array) + efermi
+    if (has_array(data, `kpoints`) && as_record(data.bands)) {
+        return typeof data.efermi === `number`;
+    }
+    return false;
+}
+// DOS: pymatgen CompleteDos format or normalized DosData
+// CompleteDos: has energies, densities, efermi, and @class containing "Dos"
+// DosData: has type ("phonon"|"electronic"), frequencies/energies, densities
+function is_dos(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    const has_spectra = has_array(data, `energies`) || has_array(data, `frequencies`);
+    // pymatgen CompleteDos format
+    if (typeof data[`@class`] === `string` &&
+        data[`@class`].includes(`Dos`) &&
+        has_spectra &&
+        data.densities !== undefined)
+        return true;
+    // Normalized DosData format
+    if ((data.type === `phonon` || data.type === `electronic`) &&
+        has_spectra &&
+        has_array(data, `densities`))
+        return true;
+    return false;
+}
+// BandsAndDos: object containing both band_structure and dos data at the same level.
+// Must be a focused wrapper (few keys), not a large object that happens to have both.
+function is_bands_and_dos(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    const keys = Object.keys(data).filter((key) => !key.startsWith(`@`) && !key.startsWith(`_`));
+    // Wrapper format: { band_structure: {...}, dos: {...} } with few extra keys
+    const has_bands = as_record(data.band_structure) && is_band_structure(data.band_structure);
+    const has_dos_key = as_record(data.dos) && is_dos(data.dos);
+    if (has_bands && has_dos_key && keys.length <= 5)
+        return true;
+    // Combined-fields format: single object with both band structure and DOS fields mixed in
+    const has_bands_fields = has_array(data, `branches`) && as_record(data.labels_dict);
+    const has_dos_fields = (has_array(data, `energies`) || has_array(data, `frequencies`)) &&
+        data.densities !== undefined &&
+        (data.atom_dos !== undefined || data.spd_dos !== undefined);
+    return Boolean(has_bands_fields && has_dos_fields);
+}
+// BrillouinZone: reciprocal lattice data with optional k-path info
+// Matches objects with a lattice that has reciprocal vectors (k_lattice or reciprocal_lattice)
+// and optionally k-path points/labels for overlaying on the zone
+function is_brillouin_zone(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    // Must have reciprocal lattice vectors (3x3 matrix)
+    const has_k_lattice = has_array(data, `k_lattice`, 3) || has_array(data, `reciprocal_lattice`, 3);
+    if (!has_k_lattice)
+        return false;
+    // Must have k-path or explicit BZ data to distinguish from Fermi surface data
+    // (Fermi surface also has k_lattice but additionally has isosurfaces)
+    if (has_array(data, `isosurfaces`))
+        return false; // that's a Fermi surface, not a plain BZ
+    // Accept if it has k_path labels/points, or a structure with lattice
+    return (has_array(data, `k_path`) ||
+        has_array(data, `k_points`) ||
+        Boolean(as_record(data.k_labels)) ||
+        Boolean(as_record(data.labels_dict)) ||
+        data.bz_order !== undefined);
+}
+// XRD pattern: x + y arrays of equal length (2-theta angles vs intensities)
+// with optional hkls (Miller indices) and d_hkls (d-spacings)
+function is_xrd_pattern(obj) {
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    if (!has_array(data, `x`) || !has_array(data, `y`))
+        return false;
+    const x_arr = data.x;
+    const y_arr = data.y;
+    if (x_arr.length !== y_arr.length || x_arr.length === 0)
+        return false;
+    // Must have numeric x/y values
+    if (typeof x_arr[0] !== `number` || typeof y_arr[0] !== `number`)
+        return false;
+    // Distinguish from generic scatter data: XRD patterns typically have hkls or d_hkls,
+    // or have @class containing "Xrd"
+    return (has_array(data, `hkls`) ||
+        has_array(data, `d_hkls`) ||
+        (typeof data[`@class`] === `string` && data[`@class`].includes(`Xrd`)) ||
+        typeof data.wavelength === `number`);
+}
+// Tabular data: array of objects with consistent keys (row-based table format)
+// or object with parallel arrays (column-based format)
+function is_tabular_data(obj) {
+    // Row-based: array of objects with string keys and numeric/string values
+    if (Array.isArray(obj) && obj.length >= 3) {
+        const first = as_record(obj[0]);
+        const second = as_record(obj[1]);
+        if (!first || !second)
+            return false;
+        const first_keys = Object.keys(first);
+        if (first_keys.length < 2)
+            return false;
+        // Check that rows have consistent keys and mostly numeric/string values
+        const second_keys = Object.keys(second);
+        const overlap = first_keys.filter((key) => second_keys.includes(key));
+        if (overlap.length < first_keys.length * 0.5)
+            return false;
+        // At least some values should be numbers (not just metadata objects)
+        const num_count = first_keys.filter((key) => typeof first[key] === `number`).length;
+        return num_count >= 1;
+    }
+    // Column-based: object where multiple values are equal-length arrays
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    const entries = Object.entries(data);
+    if (entries.length < 2)
+        return false;
+    const array_entries = entries.filter(([, val]) => Array.isArray(val) && val.length > 0);
+    if (array_entries.length < 2)
+        return false;
+    // Check that arrays have consistent lengths
+    const lengths = array_entries.map(([, val]) => val.length);
+    const first_len = lengths[0];
+    if (!lengths.every((len) => len === first_len))
+        return false;
+    // At least one column must contain numbers
+    return array_entries.some(([, val]) => typeof val[0] === `number`);
+}
+// Plottable data: tabular data with at least 2 numeric columns (enough for a scatter plot).
+// Samples multiple rows/elements to handle leading nulls.
+export function is_plottable_data(obj) {
+    if (!is_tabular_data(obj))
+        return false;
+    if (Array.isArray(obj)) {
+        const sample = obj.slice(0, 10).map(as_record).filter(Boolean);
+        if (sample.length === 0)
+            return false;
+        const all_keys = new Set(sample.flatMap(Object.keys));
+        const num_cols = [...all_keys].filter((key) => sample.some((row) => typeof row[key] === `number`)).length;
+        return num_cols >= 2;
+    }
+    const data = as_record(obj);
+    if (!data)
+        return false;
+    const array_entries = Object.entries(data).filter(([, val]) => Array.isArray(val) && val.length > 0);
+    const num_cols = array_entries.filter(([, val]) => val.some((elem) => typeof elem === `number`)).length;
+    return num_cols >= 2;
+}
+// === Main Detection Function ===
+// Detect the visualization type for a given JSON value.
+// Returns the type if the value matches a known format, or null if not renderable.
+// Checks are ordered from most specific to least specific to minimize false positives:
+// OPTIMADE before generic structure, combined bands+DOS before individual band/dos,
+// structure late (structures are common building blocks inside other data types),
+// and generic tabular data last.
+export function detect_view_type(value) {
+    if (value == null)
+        return null;
+    if (as_record(value) && is_optimade_raw(value))
+        return `structure`;
+    if (is_fermi_surface(value))
+        return `fermi_surface`;
+    if (is_band_grid(value))
+        return `band_grid`;
+    if (is_phase_diagram(value))
+        return `phase_diagram`;
+    if (is_bands_and_dos(value))
+        return `bands_and_dos`;
+    if (is_band_structure(value))
+        return `band_structure`;
+    if (is_dos(value))
+        return `dos`;
+    if (is_brillouin_zone(value))
+        return `brillouin_zone`;
+    if (is_xrd_pattern(value))
+        return `xrd`;
+    if (is_volumetric(value))
+        return `volumetric`;
+    if (is_structure(value))
+        return `structure`;
+    if (is_convex_hull_entries(value))
+        return `convex_hull`;
+    if (is_tabular_data(value))
+        return `table`;
+    return null;
+}
+// Recursively scan a JSON object to find all paths that contain renderable data.
+// Returns a Map of JSON path strings to their detected type.
+// Used to show badges on JsonTree nodes indicating which subtrees contain visualizable data.
+export function scan_renderable_paths(obj, prefix = ``, max_depth = 10) {
+    const results = new Map();
+    const visited = new WeakSet();
+    function walk(value, path, depth) {
+        if (depth > max_depth)
+            return;
+        if (value == null)
+            return;
+        if (typeof value !== `object`)
+            return;
+        // Circular reference protection
+        const obj_ref = value;
+        if (visited.has(obj_ref))
+            return;
+        visited.add(obj_ref);
+        // Check if this value itself is renderable
+        const detected_type = detect_view_type(value);
+        if (detected_type) {
+            results.set(path, { type: detected_type, label: TYPE_LABELS[detected_type] });
+            // If tabular data is also plottable, register a plot badge too
+            if (detected_type === `table` && is_plottable_data(value)) {
+                const plot_path = path ? `${path}\u0000plot` : `\u0000plot`;
+                results.set(plot_path, { type: `plot`, label: TYPE_LABELS.plot });
+            }
+            // Don't recurse into renderable objects -- their children are part of the data
+            return;
+        }
+        // Recurse into children
+        if (Array.isArray(value)) {
+            // For arrays, only scan first few elements to avoid huge arrays
+            const scan_count = Math.min(value.length, 20);
+            for (let idx = 0; idx < scan_count; idx++) {
+                walk(value[idx], build_path(path, idx), depth + 1);
+            }
+        }
+        else {
+            for (const [key, child_value] of Object.entries(value)) {
+                walk(child_value, build_path(path, key), depth + 1);
+            }
+        }
+    }
+    walk(obj, prefix, 0);
+    return results;
+}

package/dist/file-viewer/eligibility.d.ts

@@ -0,0 +1,4 @@
+export declare const normalize_browser_supported_filename: (filename: string) => string | null;
+export declare const should_encode_filename_as_base64: (filename: string) => boolean;
+export declare const is_matterviz_filename: (filename: unknown) => boolean;
+export declare const is_auto_renderable_filename: (filename: unknown) => boolean;

package/dist/file-viewer/eligibility.js

@@ -0,0 +1,53 @@
+import { COMPRESSION_EXTENSIONS_REGEX, CONFIG_DIRS_REGEX, TRAJ_KEYWORDS_REGEX, } from '../constants';
+import { FERMI_FILE_RE, VOLUMETRIC_EXT_RE, VOLUMETRIC_VASP_RE } from './types';
+import { detect_compression_format, is_browser_decompressible_format, } from '../io/decompress';
+import { is_structure_file } from '../structure/format-detect';
+import { is_trajectory_file } from '../trajectory/format-detect';
+// Return the browser-visible filename after removing one supported compression
+// wrapper. Nested and unsupported wrappers are deliberately rejected because the
+// parser only decompresses one layer.
+export const normalize_browser_supported_filename = (filename) => {
+    const format = detect_compression_format(filename);
+    if (!format)
+        return filename;
+    if (!is_browser_decompressible_format(format))
+        return null;
+    const normalized = filename.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
+    return detect_compression_format(normalized) ? null : normalized;
+};
+export const should_encode_filename_as_base64 = (filename) => detect_compression_format(filename) !== null || /\.(?:traj|h5|hdf5)$/i.test(filename);
+const normalize_eligible_filename = (filename) => {
+    if (typeof filename !== `string` || !filename || CONFIG_DIRS_REGEX.test(filename))
+        return null;
+    return normalize_browser_supported_filename(filename.split(/[\\/]/).pop() ?? ``);
+};
+// Broad: MatterViz can open/view this file (JSON/YAML structures, keyword trajs, …).
+export const is_matterviz_filename = (filename) => {
+    const normalized = normalize_eligible_filename(filename);
+    if (normalized === null)
+        return false;
+    return (FERMI_FILE_RE.test(normalized) ||
+        VOLUMETRIC_EXT_RE.test(normalized) ||
+        VOLUMETRIC_VASP_RE.test(normalized) ||
+        is_structure_file(normalized) ||
+        is_trajectory_file(normalized));
+};
+// Conservative auto-open list: only unambiguous structure / trajectory / volumetric /
+// Fermi filenames. No JSON/YAML/XML, no keyword+.log/.out/.dat/.data heuristics.
+const AUTO_RENDER_EXT_RE = /\.(?:cif|mcif|mmcif|xyz|extxyz|poscar|vasp|cube|pdb|mol|mol2|sdf|lmp|dump|traj|xtc|lammpstrj)$/i;
+const AUTO_RENDER_VASP_NAME_RE = /(?:^|[\\/_.-])(?:poscar|contcar|xdatcar)(?:[\\/_.-]|$)/i;
+export const is_auto_renderable_filename = (filename) => {
+    const normalized = normalize_eligible_filename(filename);
+    if (normalized === null)
+        return false;
+    if (FERMI_FILE_RE.test(normalized) ||
+        VOLUMETRIC_EXT_RE.test(normalized) ||
+        VOLUMETRIC_VASP_RE.test(normalized) ||
+        AUTO_RENDER_VASP_NAME_RE.test(normalized) ||
+        AUTO_RENDER_EXT_RE.test(normalized)) {
+        return true;
+    }
+    // HDF5 only when the name clearly marks a trajectory
+    return (/\.(?:h5|hdf5)$/i.test(normalized) &&
+        (/vaspout/i.test(normalized) || TRAJ_KEYWORDS_REGEX.test(normalized)));
+};

package/dist/file-viewer/host-protocol.d.ts

@@ -0,0 +1,50 @@
+import type { DefaultSettings } from '../settings';
+import type { ThemeName } from '../theme';
+export interface FileData {
+    filename: string;
+    content: string;
+    is_base64: boolean;
+}
+export interface WebviewBootstrapData {
+    data: FileData;
+    theme: ThemeName;
+    defaults?: DefaultSettings;
+    moyo_wasm_url?: string;
+}
+type WatchedFileContext = {
+    file_path: string;
+    request_id?: string;
+    filename?: string;
+    frame_index?: number;
+};
+type HostFileRequest = {
+    request_id: string;
+    file_path: string;
+};
+export type FileChangeMessage = WatchedFileContext & ({
+    command: `fileUpdated`;
+    data: FileData;
+    theme?: ThemeName;
+} | {
+    command: `fileDeleted`;
+});
+export type WebviewToHostMessage = {
+    command: `info` | `error`;
+    text: string;
+} | ({
+    command: `request_large_file`;
+} & HostFileRequest) | ({
+    command: `request_frame`;
+    frame_index: number;
+} & HostFileRequest) | {
+    command: `saveAs`;
+    filename: string;
+    content: string;
+    is_binary?: boolean;
+} | ({
+    command: `startWatching`;
+} & WatchedFileContext) | {
+    command: `stopWatching`;
+    file_path: string;
+};
+export {};

package/dist/file-viewer/host-transfer.d.ts

@@ -0,0 +1,25 @@
+export interface LargeFileMarker {
+    file_path: string;
+    file_size: number;
+}
+export declare const format_large_file_marker: ({ file_path, file_size, }: LargeFileMarker) => string;
+export declare const parse_large_file_marker: (content: string) => LargeFileMarker | null;
+export type HostTransferRejectReason = `file-too-large` | `unsupported-compression` | `unsupported-large-format`;
+export type HostFileTransferPlan = {
+    kind: `inline`;
+    is_base64: boolean;
+} | {
+    kind: `marker`;
+    content: string;
+} | {
+    kind: `reject`;
+    reason: HostTransferRejectReason;
+    max_file_size?: number;
+};
+export interface HostFileTransferInput extends LargeFileMarker {
+    filename: string;
+    large_file_threshold: number;
+    max_file_size: number;
+    max_text_file_size: number;
+}
+export declare const plan_host_file_transfer: ({ filename, file_path, file_size, large_file_threshold, max_file_size, max_text_file_size, }: HostFileTransferInput) => HostFileTransferPlan;

package/dist/file-viewer/host-transfer.js

@@ -0,0 +1,42 @@
+import { normalize_browser_supported_filename, should_encode_filename_as_base64, } from './eligibility';
+import { indexed_trajectory_format, is_indexable_trajectory_filename, } from '../trajectory/format-detect';
+export const format_large_file_marker = ({ file_path, file_size, }) => {
+    if (!file_path || !Number.isSafeInteger(file_size) || file_size < 0)
+        throw new Error(`Invalid large file marker data`);
+    return `LARGE_FILE:${file_path}:${file_size}`;
+};
+export const parse_large_file_marker = (content) => {
+    const prefix = `LARGE_FILE:`;
+    if (!content.startsWith(prefix))
+        return null;
+    const separator_idx = content.lastIndexOf(`:`);
+    const file_path = content.slice(prefix.length, separator_idx);
+    const size_text = content.slice(separator_idx + 1);
+    const file_size = Number(size_text);
+    if (!file_path || !/^\d+$/.test(size_text) || !Number.isSafeInteger(file_size))
+        throw new Error(`Malformed large file marker`);
+    return { file_path, file_size };
+};
+export const plan_host_file_transfer = ({ filename, file_path, file_size, large_file_threshold, max_file_size, max_text_file_size, }) => {
+    const normalized_filename = normalize_browser_supported_filename(filename);
+    const is_large_file = file_size > large_file_threshold;
+    const trajectory_format = normalized_filename !== null && is_indexable_trajectory_filename(normalized_filename)
+        ? indexed_trajectory_format(normalized_filename)
+        : null;
+    const format_max_file_size = is_large_file && trajectory_format === `xyz`
+        ? Math.min(max_text_file_size, max_file_size)
+        : max_file_size;
+    if (file_size > format_max_file_size) {
+        return { kind: `reject`, reason: `file-too-large`, max_file_size: format_max_file_size };
+    }
+    if (!is_large_file)
+        return { kind: `inline`, is_base64: should_encode_filename_as_base64(filename) };
+    if (normalized_filename === null)
+        return { kind: `reject`, reason: `unsupported-compression` };
+    if (!trajectory_format)
+        return { kind: `reject`, reason: `unsupported-large-format` };
+    return {
+        kind: `marker`,
+        content: format_large_file_marker({ file_path, file_size }),
+    };
+};

package/dist/file-viewer/index.d.ts

@@ -0,0 +1,5 @@
+export * from './detect';
+export * from './eligibility';
+export { default as JsonBrowser } from './JsonBrowser.svelte';
+export { default as PlotPanel } from './PlotPanel.svelte';
+export * from './plot-utils';

package/dist/file-viewer/index.js

@@ -0,0 +1,5 @@
+export * from './detect';
+export * from './eligibility';
+export { default as JsonBrowser } from './JsonBrowser.svelte';
+export { default as PlotPanel } from './PlotPanel.svelte';
+export * from './plot-utils';

package/dist/file-viewer/main.d.ts

@@ -0,0 +1,44 @@
+import '../app.css';
+import '../theme/themes.mjs';
+import type { FrameIndex, FrameLoader, TrajectoryFrame, TrajectoryMetadata } from '../trajectory';
+import type { WebviewBootstrapData } from './host-protocol';
+import type { ParseResult } from './parse';
+export type MatterVizData = WebviewBootstrapData;
+export interface MatterVizApp {
+    $on?(type: string, callback: (event: Event) => void): () => void;
+    $set?(props: Partial<Record<string, unknown>>): void;
+}
+export interface DisplayOptions {
+    initial_step_idx?: number;
+    on_step_change?: (step_idx: number, total_frames: number) => void;
+}
+export declare class VSCodeFrameLoader implements FrameLoader {
+    private readonly file_path;
+    private readonly vscode_api;
+    constructor(file_path: string, vscode_api: VSCodeAPI);
+    load_frame(_data: string | ArrayBuffer, frame_index: number, timeout?: number): Promise<TrajectoryFrame | null>;
+    get_total_frames(): Promise<number>;
+    build_frame_index(): Promise<FrameIndex[]>;
+    extract_plot_metadata(): Promise<TrajectoryMetadata[]>;
+}
+export interface VSCodeAPI {
+    postMessage(message: unknown): void;
+}
+declare global {
+    interface Window {
+        matterviz_data?: MatterVizData;
+        initializeMatterViz?: () => Promise<MatterVizApp | null>;
+        cleanupMatterViz?: () => Promise<void>;
+        download?: (data: string | Blob, filename: string) => void;
+    }
+    var matterviz_data: MatterVizData | undefined;
+    function acquireVsCodeApi(): VSCodeAPI;
+}
+export declare const setup_vscode_download: () => void;
+type DisplayResult = ParseResult & {
+    streaming_info?: {
+        file_path: string;
+    };
+};
+export declare const create_display: (container: HTMLElement, result: DisplayResult, display_options?: DisplayOptions) => MatterVizApp;
+export {};