matterviz 0.4.0 → 0.4.2

package/dist/io/file-drop.js

@@ -2,6 +2,19 @@
 import { decompress_file } from './decompress';
 import { handle_url_drop } from './url-drop';
 import { to_error } from '../utils';
+// Drag-over visual-state handlers for file-drop zones; spread onto the drop target
+// alongside `ondrop` from create_file_drop_handler
+export const drag_over_handlers = (opts) => ({
+    // preventDefault on dragover marks the element as a valid drop target; dragleave
+    // has no default action to cancel, so it only clears the visual state
+    ondragover: (event) => {
+        event.preventDefault();
+        if (opts.allow && !opts.allow())
+            return;
+        opts.set_dragover(true);
+    },
+    ondragleave: () => opts.set_dragover(false),
+});
 // Handles URL drops (from FilePicker), direct file drops with decompression,
 // loading state, and error reporting.
 export const create_file_drop_handler = (opts) => async (event) => {

package/dist/io/index.d.ts

@@ -1,3 +1,4 @@
+export { default as ExportPane } from './ExportPane.svelte';
 export * from './decompress';
 export * from './export';
 export * from './fetch';

package/dist/io/index.js

@@ -1,3 +1,6 @@
+export { default as ExportPane } from './ExportPane.svelte';
+// strip_compression_extensions lives in ./decompress (Svelte-free) so parser
+// modules can import it inside Web Workers; re-exported here.
 export * from './decompress';
 export * from './export';
 export * from './fetch';

package/dist/io/is-binary.d.ts

@@ -1 +1,10 @@
 export declare const is_binary: (content: string) => boolean;
+export declare const has_gzip_magic: (bytes: Uint8Array) => boolean;
+export declare const has_hdf5_magic: (bytes: Uint8Array) => boolean;
+export declare const has_binary_magic: (bytes: Uint8Array) => boolean;
+export declare const ext_of: (name: string) => string;
+export declare const BINARY_EXTENSIONS: Set<string>;
+export declare const is_known_text_file: (basename: string) => boolean;
+export declare const strip_gz_ext: (filename: string) => string;
+export declare const has_binary_inner_ext: (filename: string) => boolean;
+export declare const is_binary_payload: (filename: string, buffer: ArrayBuffer) => boolean;

package/dist/io/is-binary.js

@@ -1,4 +1,8 @@
-// Simplified binary detection
+// Single source of truth for binary-vs-text detection in the io layer (used by
+// decompress.ts and url-drop.ts): (1) is_binary string heuristic, (2) has_*_magic byte
+// signatures, (3) extension/filename classification.
+// === (1) string-content heuristic ===
+// Detect binary from decoded text: a NUL byte or a high ratio of non-printable chars.
 export const is_binary = (content) => {
     if (!content)
         return false;
@@ -18,3 +22,43 @@ export const is_binary = (content) => {
     }
     return (binary_char_count / content.length > 0.1 || printable_ascii_count / content.length < 0.7);
 };
+// === (2) magic-byte signatures ===
+const starts_with = (bytes, sig) => bytes.length >= sig.length && sig.every((byte, idx) => bytes[idx] === byte);
+// gzip member header
+export const has_gzip_magic = (bytes) => starts_with(bytes, [0x1f, 0x8b]);
+// Full 8-byte HDF5 superblock signature "\x89HDF\r\n\x1a\n" — used to validate that a file
+// claiming a .h5/.hdf5 extension really is HDF5 (stricter than the binary sniff below).
+export const has_hdf5_magic = (bytes) => starts_with(bytes, [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a]);
+// Leading bytes that mark a payload as binary so a lossy UTF-8 decode would corrupt it.
+// HDF5 is matched by its 4-byte "\x89HDF" prefix (the non-ASCII 0x89 already rules out text
+// starting with "HDF"); the full 4-byte ZIP signatures rule out text merely starting "PK".
+export const has_binary_magic = (bytes) => has_gzip_magic(bytes) ||
+    starts_with(bytes, [0x89, 0x48, 0x44, 0x46]) || // HDF5 "\x89HDF"
+    starts_with(bytes, [0x50, 0x4b, 0x03, 0x04]) || // ZIP local file
+    starts_with(bytes, [0x50, 0x4b, 0x05, 0x06]) || // ZIP empty archive (EOCD)
+    starts_with(bytes, [0x50, 0x4b, 0x07, 0x08]) || // ZIP spanned
+    starts_with(bytes, [0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d]); // ASE .traj "- of Ulm"
+// === (3) extension / filename classification ===
+export const ext_of = (name) => name.split(`.`).pop()?.toLowerCase() ?? ``;
+// Binary data formats whose lossy UTF-8 decode would corrupt bytes (post-decompression)
+const BINARY_DATA_EXTENSIONS = new Set(`h5 hdf5 traj npz pkl dat brml raw`.split(` `));
+// All extensions treated as binary: data formats + compressed wrappers that must be
+// downloaded/kept as raw bytes (used for binary-fetch mode and .gz inner-format checks)
+export const BINARY_EXTENSIONS = new Set([
+    ...BINARY_DATA_EXTENSIONS,
+    ...`gz gzip zip bz2 xz`.split(` `),
+]);
+// Known text formats (plus extensionless VASP files) — safe to fetch/sniff as text
+const TEXT_EXTENSIONS = new Set(`xyz extxyz json cif poscar yaml yml txt md py js ts css html xml`.split(` `));
+const VASP_BASENAME_RE = /^(?:poscar|xdatcar|contcar)$/i;
+export const is_known_text_file = (basename) => TEXT_EXTENSIONS.has(ext_of(basename)) || VASP_BASENAME_RE.test(basename);
+const GZ_EXT_RE = /\.(?:gz|gzip)$/i;
+// Strip a trailing .gz/.gzip wrapper extension, leaving any inner extension intact
+export const strip_gz_ext = (filename) => filename.replace(GZ_EXT_RE, ``);
+// Whether the file inside a .gz/.gzip wrapper is a known binary format that a lossy text
+// decode would corrupt (bytes >= 0x80 -> U+FFFD)
+export const has_binary_inner_ext = (filename) => BINARY_EXTENSIONS.has(ext_of(strip_gz_ext(filename)));
+// Binary if the (post-decompression) extension is a known binary data format or the leading
+// bytes match a magic signature
+export const is_binary_payload = (filename, buffer) => BINARY_DATA_EXTENSIONS.has(ext_of(filename)) ||
+    has_binary_magic(new Uint8Array(buffer.slice(0, 8)));

package/dist/io/types.d.ts

@@ -6,3 +6,16 @@ export interface FileInfo {
     category?: string;
     category_icon?: string;
 }
+export interface ExportItem {
+    label: string;
+    hint?: string;
+    disabled?: boolean;
+    on_download?: () => void;
+    copy_text?: () => string | null;
+    show_dpi?: boolean;
+}
+export interface ExportSection {
+    title?: string;
+    tooltip?: string;
+    items: ExportItem[];
+}

package/dist/io/url-drop.js

@@ -1,9 +1,6 @@
 import { load_binary_traj } from '../trajectory/parse';
 import { decompress_data_binary } from './decompress';
-const BINARY_EXTENSIONS = new Set(`h5 hdf5 traj npz pkl dat gz gzip zip bz2 xz brml raw`.split(` `));
-const TEXT_EXTENSIONS = new Set(`xyz extxyz json cif poscar yaml yml txt md py js ts css html xml`.split(` `));
-const VASP_BASENAME_RE = /^(poscar|xdatcar|contcar)$/i;
-const GZ_EXT_RE = /\.(gz|gzip)$/i;
+import { BINARY_EXTENSIONS, ext_of, has_binary_inner_ext, has_binary_magic, has_gzip_magic, has_hdf5_magic, is_known_text_file, strip_gz_ext, } from './is-binary';
 // Extract filename from Content-Disposition header, falling back to url_basename.
 function extract_filename(headers, fallback) {
     if (!headers)
@@ -11,11 +8,11 @@ function extract_filename(headers, fallback) {
     const content_disposition_str = headers.get(`content-disposition`);
     if (!content_disposition_str)
         return fallback;
-    const star_match = /filename\*=([^;]+)/i.exec(content_disposition_str);
+    const star_match = /filename\*=(?<value>[^;]+)/i.exec(content_disposition_str);
     if (star_match?.[1]) {
         let raw = star_match[1].trim().replaceAll(/^"|"$/g, ``);
         // Strip any RFC 5987 charset'language' prefix; bare values pass through unchanged
-        const ext_value_match = /^[\w!#$%&+^`{}~-]+'[\w-]*'(.*)$/.exec(raw);
+        const ext_value_match = /^[\w!#$%&+^`{}~-]+'[\w-]*'(?<value>.*)$/.exec(raw);
         if (ext_value_match)
             raw = ext_value_match[1];
         try {
@@ -25,17 +22,13 @@ function extract_filename(headers, fallback) {
             return raw;
         }
     }
-    const plain_match = /filename\s*=\s*"?([^";]+)"?/i.exec(content_disposition_str);
+    const plain_match = /filename\s*=\s*"?(?<value>[^";]+)"?/i.exec(content_disposition_str);
     // truthiness check (not ??) so whitespace-only `filename=` values fall back too
     const name = plain_match?.[1]?.trim();
     if (!name)
         return fallback;
     return name;
 }
-const ext_of = (name) => name.split(`.`).pop()?.toLowerCase() ?? ``;
-// Whether the file inside a .gz/.gzip wrapper is a known binary format that a
-// lossy text decode would corrupt (bytes >= 0x80 → U+FFFD)
-const has_binary_inner_ext = (filename) => BINARY_EXTENSIONS.has(ext_of(filename.replace(GZ_EXT_RE, ``)));
 // Gunzip a fetched payload → [content, filename] with .gz/.gzip stripped; content
 // stays an ArrayBuffer for binary inner formats, decoded string otherwise
 async function decompress_gz_payload(buffer, filename) {
@@ -43,7 +36,7 @@ async function decompress_gz_payload(buffer, filename) {
     const content = has_binary_inner_ext(filename)
         ? decompressed
         : new TextDecoder().decode(decompressed);
-    return [content, filename.replace(GZ_EXT_RE, ``)];
+    return [content, strip_gz_ext(filename)];
 }
 // Handle URL-based file drop data by fetching content lazily
 export async function handle_url_drop(drag_event, callback) {
@@ -87,12 +80,10 @@ export async function load_from_url(url, callback) {
         if (ext === `h5` || ext === `hdf5`) {
             const result = await load_binary_traj(resp, `H5`, true);
             // Log warning if signature doesn't match (only for ArrayBuffer results)
-            if (result instanceof ArrayBuffer && result.byteLength >= 8) {
-                const view = new Uint8Array(result.slice(0, 8));
-                const hdf5_signature = [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a];
-                if (!hdf5_signature.every((byte, idx) => view[idx] === byte)) {
-                    console.warn(`File has .h5/.hdf5 extension but missing HDF5 signature`);
-                }
+            if (result instanceof ArrayBuffer &&
+                result.byteLength >= 8 &&
+                !has_hdf5_magic(new Uint8Array(result.slice(0, 8)))) {
+                console.warn(`File has .h5/.hdf5 extension but missing HDF5 signature`);
             }
             return callback(result, filename);
         }
@@ -108,7 +99,7 @@ export async function load_from_url(url, callback) {
     }
     // Skip Range requests for known text formats to avoid production server issues
     // Include VASP files that don't have extensions (POSCAR, XDATCAR, CONTCAR)
-    const is_known_text = TEXT_EXTENSIONS.has(ext) || VASP_BASENAME_RE.test(url_basename);
+    const is_known_text = is_known_text_file(url_basename);
     let sniffed_callback_args;
     if (!is_known_text) {
         // Only the Range sniff is guarded (failure → plain text fetch). Once magic bytes
@@ -121,13 +112,10 @@ export async function load_from_url(url, callback) {
             const head = await fetch(url, { headers: { Range: `bytes=0-15` } });
             if (head.ok) {
                 const buf = new Uint8Array(await head.arrayBuffer());
-                const is_gzip = buf[0] === 0x1f && buf[1] === 0x8b;
-                const is_hdf5 = buf[0] === 0x89 && buf[1] === 0x48 && buf[2] === 0x44 && buf[3] === 0x46;
-                // ASE .traj files start with the Ulm signature "- of Ulm"
-                const is_ase_traj = [0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d].every((byte, idx) => buf[idx] === byte);
-                if (is_gzip)
+                // gzip is gunzipped downstream; other binary magic (HDF5, ZIP, ASE Ulm) stays raw
+                if (has_gzip_magic(buf))
                     sniffed = `gzip`;
-                else if (is_hdf5 || is_ase_traj)
+                else if (has_binary_magic(buf))
                     sniffed = `binary`;
             }
         }

package/dist/isosurface/Isosurface.svelte

@@ -14,13 +14,12 @@
     Uint32BufferAttribute,
   } from 'three'
   import type { IsosurfaceLayer, IsosurfaceSettings, VolumetricData } from './types'
-  import {
-    DEFAULT_ISOSURFACE_SETTINGS,
-    downsample_grid,
-    pad_periodic_grid,
-  } from './types'
+  import { DEFAULT_ISOSURFACE_SETTINGS, downsample_grid, pad_periodic_grid } from './types'
 
-  let { volume, settings = DEFAULT_ISOSURFACE_SETTINGS }: {
+  let {
+    volume,
+    settings = DEFAULT_ISOSURFACE_SETTINGS,
+  }: {
     volume: VolumetricData
     settings?: IsosurfaceSettings
   } = $props()
@@ -28,23 +27,22 @@
   // Resolve layers: use explicit layers array if provided, else build from single-isovalue settings
   let resolved_layers = $derived.by((): IsosurfaceLayer[] => {
     if (settings.layers?.length) return settings.layers
-    return [{
-      isovalue: settings.isovalue,
-      color: settings.positive_color,
-      opacity: settings.opacity,
-      visible: true,
-      show_negative: settings.show_negative,
-      negative_color: settings.negative_color,
-    }]
+    return [
+      {
+        isovalue: settings.isovalue,
+        color: settings.positive_color,
+        opacity: settings.opacity,
+        visible: true,
+        show_negative: settings.show_negative,
+        negative_color: settings.negative_color,
+      },
+    ]
   })
 
   // Build indexed BufferGeometry from marching cubes output.
   // Uses Three.js index buffer to avoid tripling vertex data, and
   // computeVertexNormals() for fast GPU-friendly normals.
-  function build_geometry(
-    vertices: Vec3[],
-    faces: number[][],
-  ): BufferGeometry | null {
+  function build_geometry(vertices: Vec3[], faces: number[][]): BufferGeometry | null {
     if (vertices.length === 0 || faces.length === 0) return null
 
     // Flatten vertices: Vec3[] → Float32Array
@@ -242,11 +240,7 @@
     </T.Mesh>
   {:else if entry.opacity < 1}
     <!-- Two-pass rendering for correct transparency -->
-    <T.Mesh
-      geometry={entry.geometry}
-      renderOrder={entry.render_order}
-      frustumCulled={false}
-    >
+    <T.Mesh geometry={entry.geometry} renderOrder={entry.render_order} frustumCulled={false}>
       <T.MeshStandardMaterial
         color={entry.color}
         transparent

package/dist/isosurface/IsosurfaceControls.svelte

@@ -45,7 +45,7 @@
   function update_layer(idx: number, updates: Partial<IsosurfaceLayer>) {
     if (!settings.layers) return
     settings.layers = settings.layers.map((layer, layer_idx) =>
-      layer_idx === idx ? { ...layer, ...updates } : layer
+      layer_idx === idx ? { ...layer, ...updates } : layer,
     )
   }
 </script>
@@ -68,7 +68,9 @@
   <div class="pane-row compact-row">
     {#if volumes.length > 1}
       <label
-        {@attach tooltip({ content: `Select which volume to display (e.g. charge vs magnetization)` })}
+        {@attach tooltip({
+          content: `Select which volume to display (e.g. charge vs magnetization)`,
+        })}
       >
         <span>Volume:</span>
         <select bind:value={active_volume_idx}>
@@ -79,13 +81,14 @@
       </label>
     {/if}
     <label
-      {@attach tooltip({ content: `Number of isosurface shells at different density thresholds` })}
+      {@attach tooltip({
+        content: `Number of isosurface shells at different density thresholds`,
+      })}
     >
       <span>Layers:</span>
       <select
         value={n_layers}
-        onchange={(event) =>
-        set_layer_count(Number(event.currentTarget.value))}
+        onchange={(event) => set_layer_count(Number(event.currentTarget.value))}
       >
         {#each [1, 2, 3, 4, 5] as count (count)}
           <option value={count}>{count}</option>
@@ -95,14 +98,16 @@
     <!-- Sync both settings.show_negative (single-layer fallback) and all layer entries
     so the toggle works consistently regardless of which mode is active -->
     <label
-      {@attach tooltip({ content: `Show negative lobe at −isovalue (for orbitals, ESP, magnetization)` })}
+      {@attach tooltip({
+        content: `Show negative lobe at −isovalue (for orbitals, ESP, magnetization)`,
+      })}
     >
       <span>Neg. lobe</span>
       <input
         type="checkbox"
         checked={is_multi_layer
-        ? settings.layers?.some((layer) => layer.show_negative) ?? false
-        : settings.show_negative}
+          ? (settings.layers?.some((layer) => layer.show_negative) ?? false)
+          : settings.show_negative}
         onchange={(event) => {
           const checked = event.currentTarget.checked
           settings.show_negative = checked
@@ -115,9 +120,7 @@
         }}
       />
     </label>
-    <label
-      {@attach tooltip({ content: `Render as wireframe mesh instead of solid surface` })}
-    >
+    <label {@attach tooltip({ content: `Render as wireframe mesh instead of solid surface` })}>
       <span>Wireframe</span>
       <input type="checkbox" bind:checked={settings.wireframe} />
     </label>
@@ -135,8 +138,7 @@
         <input
           type="color"
           value={layer.color}
-          onchange={(event) =>
-          update_layer(idx, { color: event.currentTarget.value })}
+          onchange={(event) => update_layer(idx, { color: event.currentTarget.value })}
         />
         <input
           type="range"
@@ -145,9 +147,9 @@
           {step}
           value={layer.isovalue}
           oninput={(event) =>
-          update_layer(idx, {
-            isovalue: Number(event.currentTarget.value),
-          })}
+            update_layer(idx, {
+              isovalue: Number(event.currentTarget.value),
+            })}
           style="flex: 1; min-width: 60px"
         />
         <span class="layer-value">{format_num(layer.isovalue, `.3~g`)}</span>
@@ -158,9 +160,9 @@
           step={0.05}
           value={layer.opacity}
           oninput={(event) =>
-          update_layer(idx, {
-            opacity: Number(event.currentTarget.value),
-          })}
+            update_layer(idx, {
+              opacity: Number(event.currentTarget.value),
+            })}
           style="width: 50px"
           title="Opacity: {format_num(layer.opacity, `.2f`)}"
         />
@@ -169,23 +171,21 @@
   {:else}
     <!-- Single-layer: isovalue slider full width -->
     <label
-      {@attach tooltip({ content: `Density threshold — surface is drawn where grid values equal this` })}
+      {@attach tooltip({
+        content: `Density threshold — surface is drawn where grid values equal this`,
+      })}
     >
       <span>Isovalue:</span>
-      <input
-        type="range"
-        min={step}
-        max={slider_max}
-        {step}
-        bind:value={settings.isovalue}
-      />
+      <input type="range" min={step} max={slider_max} {step} bind:value={settings.isovalue} />
       <span class="value">{format_num(settings.isovalue, `.4~g`)}</span>
     </label>
 
     <!-- Opacity + colors on one row -->
     <div class="pane-row compact-row">
       <label
-        {@attach tooltip({ content: `Surface transparency — lower values reveal inner structure` })}
+        {@attach tooltip({
+          content: `Surface transparency — lower values reveal inner structure`,
+        })}
       >
         <span>Opacity:</span>
         <input
@@ -203,9 +203,7 @@
         <input type="color" bind:value={settings.positive_color} />
       </label>
       {#if settings.show_negative}
-        <label
-          {@attach tooltip({ content: `Color for the negative (−isovalue) surface` })}
-        >
+        <label {@attach tooltip({ content: `Color for the negative (−isovalue) surface` })}>
           <span>&minus; Color</span>
           <input type="color" bind:value={settings.negative_color} />
         </label>
@@ -215,24 +213,21 @@
 
   {#if volumes?.[active_volume_idx]?.periodic}
     <label
-      {@attach tooltip({ content: `Extend isosurface beyond cell boundaries to close partial spheres (fraction of cell)` })}
+      {@attach tooltip({
+        content: `Extend isosurface beyond cell boundaries to close partial spheres (fraction of cell)`,
+      })}
     >
       Halo: {format_num(settings.halo, `.2f`)}
-      <input
-        type="range"
-        min={0}
-        max={0.5}
-        step={0.01}
-        bind:value={settings.halo}
-      />
+      <input type="range" min={0} max={0.5} step={0.01} bind:value={settings.halo} />
     </label>
   {/if}
 
   {#if volumes[active_volume_idx]}
     <div class="grid-info">
-      {volumes[active_volume_idx].grid_dims.join(` × `)} grid &nbsp;|&nbsp; [{
-        format_num(data_range.min, `.3~g`)
-      }, {format_num(data_range.max, `.3~g`)}]
+      {volumes[active_volume_idx].grid_dims.join(` × `)} grid &nbsp;|&nbsp; [{format_num(
+        data_range.min,
+        `.3~g`,
+      )}, {format_num(data_range.max, `.3~g`)}]
     </div>
   {/if}
 </SettingsSection>

package/dist/isosurface/parse-vaspwave.d.ts

@@ -0,0 +1,3 @@
+import type { VolumetricFileData } from './types';
+export declare const is_vaspwave_filename: (filename: string) => boolean;
+export declare function parse_vaspwave_charge(buffer: ArrayBuffer, filename?: string): Promise<VolumetricFileData>;

package/dist/isosurface/parse-vaspwave.js

@@ -0,0 +1,138 @@
+// Parser for VASP vaspwave.h5 charge density: charge/charge on charge/grid
+// plus the embedded structure under structure/positions (dataset paths follow
+// ferrox's VASPWAVE_* constants / py4vasp's VASP 6.x schema). Full files are
+// hundreds of MB, so embedding hosts are expected to prune them server-side
+// first; this parser sees only charge/{charge,grid} + structure/positions.
+//
+// Prototype scope: charge (+ magnetization) isosurfaces only — wavefunctions
+// are out of scope. The "charge density RMS per SCF step" convergence signal
+// is already covered by OSZICAR's rms(c) column in the vaspout.h5 parser
+// (scf_charge_rms frame metadata); diffing charge grids between live reloads
+// is explicitly out of scope here.
+import { calc_lattice_params, create_frac_to_cart } from '../math';
+import { wrap_to_unit_cell } from '../structure/pbc';
+import { make_site } from '../structure/site';
+import { validate_3x3_matrix } from '../trajectory/helpers';
+import { expand_ion_types, is_hdf5_dataset, read_dataset, scale_matrix, to_number_array, to_scalar_number, to_string_array, with_h5_file, } from '../trajectory/parse/h5-utils';
+import { grid_data_range } from './types';
+const CHARGE_PATH = `charge/charge`;
+const CHARGE_GRID_PATH = `charge/grid`;
+const STRUCTURE_PREFIX = `structure/positions`;
+// vaspwave carries charge density/wavefunctions, never a trajectory — used by
+// file-open routing to divert from the HDF5 trajectory dispatcher.
+export const is_vaspwave_filename = (filename) => {
+    const basename = filename.split(`/`).pop() ?? filename;
+    return /vaspwave.*\.(?:h5|hdf5)$/i.test(basename);
+};
+const dataset_shape = (h5_file, path) => {
+    const entity = h5_file.get(path);
+    return is_hdf5_dataset(entity) ? (entity.shape ?? null) : null;
+};
+const read_embedded_structure = (h5_file) => {
+    const lattice_data = read_dataset(h5_file, `${STRUCTURE_PREFIX}/lattice_vectors`);
+    if (!lattice_data) {
+        throw new Error(`vaspwave.h5 has no embedded structure (${STRUCTURE_PREFIX}/lattice_vectors) — ` +
+            `cannot place the charge grid in a lattice`);
+    }
+    const scale = to_scalar_number(read_dataset(h5_file, `${STRUCTURE_PREFIX}/scale`)) ?? 1;
+    const lattice = scale_matrix(validate_3x3_matrix(lattice_data), scale);
+    // Sites are optional for rendering (the isosurface needs only the lattice),
+    // so a pruned/torn file missing ion data still opens with an empty cell.
+    const sites = [];
+    const ion_types = to_string_array(read_dataset(h5_file, `${STRUCTURE_PREFIX}/ion_types`));
+    const ion_counts = to_number_array(read_dataset(h5_file, `${STRUCTURE_PREFIX}/number_ion_types`));
+    const frac_positions = read_dataset(h5_file, `${STRUCTURE_PREFIX}/position_ions`);
+    if (ion_types && ion_counts && frac_positions && ion_types.length === ion_counts.length) {
+        const elements = expand_ion_types(ion_types, ion_counts);
+        const frac_to_cart = create_frac_to_cart(lattice);
+        for (const [site_idx, element] of elements.entries()) {
+            const frac = frac_positions[site_idx];
+            if (!Array.isArray(frac) || frac.length < 3)
+                break; // torn positions: keep what parsed
+            const abc = wrap_to_unit_cell(frac.slice(0, 3));
+            sites.push(make_site(element, abc, frac_to_cart(abc), `${element}${site_idx + 1}`));
+        }
+    }
+    return {
+        sites,
+        lattice: { matrix: lattice, pbc: [true, true, true], ...calc_lattice_params(lattice) },
+    };
+};
+// VASP writes volumetric data C-order [components, nz, ny, nx]; the grid
+// dataset [nx, ny, nz] disambiguates (same logic as ferrox's
+// volumetric_grid_shape_and_order — when nx == nz both layouts match, so
+// default to the canonical zyx order).
+const charge_axis_order = (spatial_shape, grid_dims) => {
+    const [nx, ny, nz] = grid_dims;
+    const matches = (dims) => dims.every((dim, idx) => dim === spatial_shape[idx]);
+    if (matches([nz, ny, nx]))
+        return `zyx`;
+    if (matches([nx, ny, nz]))
+        return `xyz`;
+    throw new Error(`vaspwave.h5 ${CHARGE_GRID_PATH} [${grid_dims}] is incompatible with ` +
+        `${CHARGE_PATH} spatial shape [${spatial_shape}]`);
+};
+function parse_vaspwave_charge_file(h5_file) {
+    const shape = dataset_shape(h5_file, CHARGE_PATH);
+    if (!shape) {
+        throw new Error(`vaspwave.h5 file has no charge density (missing ${CHARGE_PATH})`);
+    }
+    // Only the dimension count is checked here — the spatial axis order (zyx vs
+    // xyz) is disambiguated later by charge_axis_order against CHARGE_GRID_PATH.
+    if (shape.length !== 4) {
+        throw new Error(`${CHARGE_PATH} must have 4 dimensions, got [${shape}]`);
+    }
+    const n_components = shape[0];
+    if (n_components < 1 || n_components > 2) {
+        throw new Error(`${CHARGE_PATH} has unsupported component count ${n_components}; expected 1 ` +
+            `(non-spin-polarized) or 2 (total + magnetization)`);
+    }
+    const grid_dims = to_number_array(read_dataset(h5_file, CHARGE_GRID_PATH));
+    if (grid_dims?.length !== 3) {
+        throw new Error(`vaspwave.h5 is missing ${CHARGE_GRID_PATH}; cannot determine the axis order of ${CHARGE_PATH}`);
+    }
+    const axis_order = charge_axis_order(shape.slice(1), grid_dims);
+    const [nx, ny, nz] = grid_dims;
+    const structure = read_embedded_structure(h5_file);
+    const lattice = structure.lattice.matrix;
+    const charge_data = read_dataset(h5_file, CHARGE_PATH);
+    if (!charge_data)
+        throw new Error(`Failed to read ${CHARGE_PATH} data`);
+    // Metadata shape and decoded data can disagree in torn/corrupt files — fail
+    // loudly instead of silently rendering fewer components than the file claims
+    if (charge_data.length !== n_components) {
+        throw new Error(`${CHARGE_PATH} decoded ${charge_data.length} components but its shape claims ${n_components}`);
+    }
+    const component_labels = [`charge density`, `magnetization density`];
+    const volumes = charge_data.map((component, component_idx) => {
+        const grid = Array(nx);
+        for (let x_idx = 0; x_idx < nx; x_idx++) {
+            const plane = Array(ny);
+            for (let y_idx = 0; y_idx < ny; y_idx++) {
+                const row = Array(nz);
+                for (let z_idx = 0; z_idx < nz; z_idx++) {
+                    row[z_idx] =
+                        axis_order === `zyx`
+                            ? component[z_idx][y_idx][x_idx]
+                            : component[x_idx][y_idx][z_idx];
+                }
+                plane[y_idx] = row;
+            }
+            grid[x_idx] = plane;
+        }
+        return {
+            grid,
+            grid_dims: [nx, ny, nz],
+            lattice,
+            origin: [0, 0, 0],
+            data_range: grid_data_range(grid),
+            data_order: `x_fastest`,
+            periodic: true,
+            label: component_labels[component_idx],
+        };
+    });
+    return { structure, volumes };
+}
+export async function parse_vaspwave_charge(buffer, filename) {
+    return with_h5_file(buffer, filename, parse_vaspwave_charge_file);
+}