matterviz 0.4.0 → 0.4.1

package/dist/io/ExportPane.svelte

@@ -0,0 +1,166 @@
+<script lang="ts">
+  import type { PaneProps, PaneToggleProps } from '../overlays'
+  import type { ExportItem, ExportSection } from './types'
+  import DraggablePane from '../overlays/DraggablePane.svelte'
+  import { sanitize_html } from '../sanitize'
+  import { type ComponentProps, onDestroy, type Snippet } from 'svelte'
+  import { tooltip } from 'svelte-multiselect/attachments'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  let {
+    export_pane_open = $bindable(false),
+    sections = [],
+    png_dpi = $bindable(150),
+    dpi_range = [50, 600],
+    icon_style = ``,
+    toggle_props = {},
+    pane_props = {},
+    children = undefined,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    export_pane_open?: boolean
+    sections?: ExportSection[]
+    png_dpi?: number
+    dpi_range?: readonly [number, number]
+    icon_style?: string
+    toggle_props?: PaneToggleProps
+    pane_props?: PaneProps
+    // Pane-specific extras rendered below the sections (e.g. video export controls)
+    children?: Snippet
+  } = $props()
+
+  // Clamp DPI into dpi_range on input change (fires on blur, before any download click)
+  function clamp_dpi(): void {
+    const [min_dpi, max_dpi] = dpi_range
+    if (typeof png_dpi !== `number` || !Number.isFinite(png_dpi)) png_dpi = 150
+    else png_dpi = Math.round(Math.min(max_dpi, Math.max(min_dpi, png_dpi)))
+  }
+
+  // Copy-to-clipboard with temporary ✅ feedback; copy_text runs only on click
+  let copied_key = $state<string | null>(null)
+  let copied_timeout: ReturnType<typeof setTimeout> | undefined
+  async function handle_copy(item: ExportItem, key: string): Promise<void> {
+    if (item.disabled) return
+    const text = item.copy_text?.()
+    if (!text) return
+    try {
+      await navigator.clipboard.writeText(text)
+      copied_key = key
+      clearTimeout(copied_timeout)
+      copied_timeout = setTimeout(() => (copied_key = null), 1000)
+    } catch (error) {
+      console.error(`Failed to copy ${item.label} to clipboard`, error)
+    }
+  }
+  onDestroy(() => clearTimeout(copied_timeout))
+</script>
+
+<DraggablePane
+  bind:show={export_pane_open}
+  open_icon="Cross"
+  closed_icon="Export"
+  {icon_style}
+  pane_props={{
+    ...rest,
+    ...pane_props,
+    class: `export-pane ${rest.class ?? ``} ${pane_props?.class ?? ``}`.trim(),
+  }}
+  {toggle_props}
+>
+  {#each sections as section, sec_idx (section.title ?? sec_idx)}
+    {#if section.title}
+      <h4
+        {@attach section.tooltip
+          ? tooltip({ allow_html: true, content: sanitize_html(section.tooltip) })
+          : () => {}}
+      >{section.title}</h4>
+    {/if}
+    <div class="export-grid">
+      {#each section.items as item, item_idx (item.label)}
+        {@const copy_key = `${sec_idx}-${item_idx}`}
+        <!-- not a <label>: it would forward label-text clicks to the first (download) button -->
+        <span class="export-item">
+          {#if item.hint}
+            <span
+              {@attach tooltip({ allow_html: true, content: sanitize_html(item.hint) })}
+            >{item.label}</span>
+          {:else}
+            {item.label}
+          {/if}
+          {#if item.on_download}
+            <button
+              type="button"
+              onclick={item.on_download}
+              disabled={item.disabled ?? false}
+              aria-label={`Download ${item.label}`}
+              title={`Download ${item.label}${item.show_dpi ? ` (${png_dpi} DPI)` : ``}`}
+            >
+              ⬇
+            </button>
+          {/if}
+          {#if item.copy_text}
+            <button
+              type="button"
+              onclick={() => handle_copy(item, copy_key)}
+              disabled={item.disabled ?? false}
+              aria-label="Copy {item.label} to clipboard"
+              title="Copy {item.label} to clipboard"
+            >
+              {copied_key === copy_key ? `✅` : `📋`}
+            </button>
+          {/if}
+          {#if item.show_dpi}
+            <span class="dpi-input">(DPI: <input
+                type="number"
+                min={dpi_range[0]}
+                max={dpi_range[1]}
+                bind:value={png_dpi}
+                onchange={clamp_dpi}
+                title="Export resolution in dots per inch"
+              />)</span>
+          {/if}
+        </span>
+      {/each}
+    </div>
+  {/each}
+  {@render children?.()}
+</DraggablePane>
+
+<style>
+  h4 {
+    display: flex;
+    align-items: center;
+    margin: 0;
+  }
+  .export-grid {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4pt 10pt;
+    font-size: 0.95em;
+  }
+  .export-item {
+    display: flex;
+    align-items: center;
+    gap: 4pt;
+    white-space: nowrap;
+  }
+  .export-grid button {
+    min-width: 1.9em;
+    height: 1.6em;
+    padding: 0 4pt;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .export-grid input[type='number'] {
+    width: 3.5em;
+  }
+  .dpi-input {
+    display: inline-flex;
+    align-items: center;
+    gap: 2pt;
+    white-space: nowrap;
+  }
+</style>

package/dist/io/ExportPane.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { PaneProps, PaneToggleProps } from '../overlays';
+import type { ExportSection } from './types';
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    export_pane_open?: boolean;
+    sections?: ExportSection[];
+    png_dpi?: number;
+    dpi_range?: readonly [number, number];
+    icon_style?: string;
+    toggle_props?: PaneToggleProps;
+    pane_props?: PaneProps;
+    children?: Snippet;
+};
+declare const ExportPane: import("svelte").Component<$$ComponentProps, {}, "export_pane_open" | "png_dpi">;
+type ExportPane = ReturnType<typeof ExportPane>;
+export default ExportPane;

package/dist/io/decompress.js

@@ -16,7 +16,6 @@ export async function decompress_data(data, format) {
 // Decompress data and return as ArrayBuffer (for binary files like .brml.gz)
 export async function decompress_data_binary(data, format) {
     try {
-        // Handle unsupported formats
         if (format === `zip` || format === `xz` || format === `bz2`) {
             throw new Error(`${format.toUpperCase()} decompression is not supported in the browser. ` +
                 `Please extract the ${format.toUpperCase()} file first.`);
@@ -40,7 +39,7 @@ export async function decompress_data_binary(data, format) {
 }
 export function decompress_file(file) {
     const format = detect_compression_format(file.name);
-    const is_supported = Boolean(format && ![`zip`, `xz`, `bz2`].includes(format));
+    const is_supported = format !== null && format !== `zip` && format !== `xz` && format !== `bz2`;
     return new Promise((resolve, reject) => {
         const reader = new FileReader();
         reader.addEventListener(`load`, () => {

package/dist/io/export.d.ts

@@ -1,11 +1,15 @@
 import type { AnyStructure } from '../structure';
-import { type Camera, type Scene } from 'three';
+import { type Camera, type Scene, type WebGLRenderer } from 'three';
+export declare const renderer_registry: WeakMap<HTMLCanvasElement, WebGLRenderer>;
+export declare const dpi_to_scale: (png_dpi: number) => number;
 export declare function canvas_to_png_blob(canvas: HTMLCanvasElement, png_dpi?: number, scene?: Scene | null, camera?: Camera | null): Promise<Blob>;
 export declare function export_canvas_as_png(canvas: HTMLCanvasElement | null, structure_or_filename: AnyStructure | string | undefined, png_dpi?: number, scene?: Scene | null, camera?: Camera | null): void;
 export declare function svg_to_svg_string(svg_element: SVGElement, inline_styles?: readonly string[]): string;
 export declare function export_svg_as_svg(svg_element: SVGElement | null, filename: string, inline_styles?: readonly string[]): void;
 export declare function svg_to_png_blob(svg_element: SVGElement, png_dpi?: number, inline_styles?: readonly string[]): Promise<Blob>;
 export declare function export_svg_as_png(svg_element: SVGElement | null, filename: string, png_dpi?: number, inline_styles?: readonly string[]): void;
+export declare function observe_canvas_presence(wrapper: HTMLElement | undefined, set: (has_canvas: boolean) => void): (() => void) | undefined;
+export declare const estimate_video_bitrate: (pixel_count: number, fps: number) => number;
 export declare function get_ffmpeg_conversion_command(input_filename: string): string;
 export declare function export_trajectory_video(canvas: HTMLCanvasElement | null, filename: string, options?: {
     fps?: number;

package/dist/io/export.js

@@ -2,29 +2,20 @@ import { download } from './fetch';
 import { create_structure_filename } from '../structure/export';
 import { to_error } from '../utils';
 import { Vector2 } from 'three';
-function is_webgl_renderer_like(value) {
-    if (typeof value !== `object` || !value)
-        return false;
-    const renderer_obj = value;
-    return (typeof renderer_obj.render === `function` &&
-        typeof renderer_obj.getPixelRatio === `function` &&
-        typeof renderer_obj.setPixelRatio === `function` &&
-        typeof renderer_obj.getSize === `function` &&
-        typeof renderer_obj.setSize === `function`);
-}
-function get_canvas_renderer(canvas) {
-    // oxlint-disable-next-line no-underscore-dangle -- three.js stores its renderer here
-    const renderer_val = canvas.__renderer;
-    return is_webgl_renderer_like(renderer_val) ? renderer_val : undefined;
-}
+// Maps a Threlte canvas to its WebGLRenderer so PNG export can look up the renderer for a
+// given canvas without mutating the DOM element. Populated by bind_renderer (scene/).
+export const renderer_registry = new WeakMap();
+// PNG DPI -> render scale relative to the 72 DPI baseline, capped at 10x. DPI floors
+// at 1 (non-finite -> 72) so bad inputs can't yield 0x0 canvases or NaN pixel ratios.
+export const dpi_to_scale = (png_dpi) => Math.min(Math.max(1, Number.isFinite(png_dpi) ? png_dpi : 72) / 72, 10);
 // Capture a WebGL canvas as a PNG Blob at the given DPI.
 // Temporarily adjusts renderer pixel ratio for high-res capture, then restores.
 // Returns data directly (no browser download), suitable for programmatic capture
 // in test suites, server-side rendering, or Python widget integration via anywidget.
 // DPI is converted to a resolution multiplier relative to 72 DPI baseline, capped at 10x.
 export function canvas_to_png_blob(canvas, png_dpi = 150, scene = null, camera = null) {
-    const resolution_multiplier = Math.min(png_dpi / 72, 10);
-    const renderer = get_canvas_renderer(canvas);
+    const resolution_multiplier = dpi_to_scale(png_dpi);
+    const renderer = renderer_registry.get(canvas);
     if (resolution_multiplier <= 1.1 || !renderer) {
         if (renderer && scene && camera)
             renderer.render(scene, camera);
@@ -168,9 +159,10 @@ export function svg_to_png_blob(svg_element, png_dpi = 150, inline_styles = [])
     if (!Number.isFinite(png_dpi) || png_dpi <= 0) {
         return Promise.reject(new Error(`Invalid PNG DPI for export`));
     }
-    const resolution_multiplier = Math.min(png_dpi / 72, 10);
-    const pixel_width = Math.round(width * resolution_multiplier);
-    const pixel_height = Math.round(height * resolution_multiplier);
+    const resolution_multiplier = dpi_to_scale(png_dpi);
+    // Floor at 1px: small viewBoxes at low DPI round to 0 and make toBlob fail confusingly
+    const pixel_width = Math.max(1, Math.round(width * resolution_multiplier));
+    const pixel_height = Math.max(1, Math.round(height * resolution_multiplier));
     const canvas = document.createElement(`canvas`);
     const ctx = canvas.getContext(`2d`);
     if (!ctx)
@@ -217,6 +209,23 @@ export function export_svg_as_png(svg_element, filename, png_dpi = 150, inline_s
         .then((blob) => download(blob, filename, `image/png`))
         .catch((error) => console.error(`Error exporting PNG:`, error));
 }
+// Watch a wrapper element for <canvas> insertion/removal: calls set(bool) immediately
+// and on every DOM mutation. Returns a cleanup that disconnects the observer (or
+// undefined when no wrapper is given). Used by export panes to enable canvas exports.
+export function observe_canvas_presence(wrapper, set) {
+    if (!wrapper) {
+        set(false);
+        return undefined;
+    }
+    const check = () => set(Boolean(wrapper.querySelector(`canvas`)));
+    check();
+    const observer = new MutationObserver(check);
+    observer.observe(wrapper, { childList: true, subtree: true });
+    return () => observer.disconnect();
+}
+// Estimate VP9 video bitrate (bits/s) from pixel count and frame rate.
+// VP9 needs ~0.1 bits per pixel per frame for good quality; clamped to [1, 200] Mbps.
+export const estimate_video_bitrate = (pixel_count, fps) => Math.max(1_000_000, Math.min(pixel_count * fps * 0.1, 200_000_000));
 // Generate FFmpeg command for WebM to MP4 conversion
 export function get_ffmpeg_conversion_command(input_filename) {
     const output = input_filename.replace(/\.webm$/i, `.mp4`);
@@ -230,7 +239,7 @@ export async function export_trajectory_video(canvas, filename, options = {}) {
         typeof MediaRecorder === `undefined` ||
         !MediaRecorder.isTypeSupported(`video/webm;codecs=vp9`))
         throw new Error(`WebM video recording not supported in this browser`);
-    const renderer = get_canvas_renderer(canvas);
+    const renderer = renderer_registry.get(canvas);
     // Store original renderer settings if changing resolution
     let orig_pixel_ratio;
     let orig_size;
@@ -242,13 +251,8 @@ export async function export_trajectory_video(canvas, filename, options = {}) {
         renderer.setSize(orig_size.width, orig_size.height, false);
     }
     // Calculate bitrate based on actual video dimensions
-    // VP9 typically needs 0.08-0.12 bits per pixel per frame for good quality
-    // canvas dimensions include device pixel ratio and any resolution_multiplier
-    const pixels_per_frame = canvas.width * canvas.height;
-    const bits_per_pixel_per_frame = 0.1; // Good quality for VP9
-    // Clamp bitrate to reasonable bounds (1 Mbps min, 200 Mbps max)
-    const calculated_bitrate = pixels_per_frame * fps * bits_per_pixel_per_frame;
-    const bitrate = Math.max(1_000_000, Math.min(calculated_bitrate, 200_000_000));
+    // (canvas dimensions include device pixel ratio and any resolution_multiplier)
+    const bitrate = estimate_video_bitrate(canvas.width * canvas.height, fps);
     const stream = canvas.captureStream(0);
     const chunks = [];
     const recorder = new MediaRecorder(stream, {

package/dist/io/fetch.d.ts

@@ -2,4 +2,5 @@ export declare const to_query: (params: Record<string, string | number | undefin
 export declare function fetch_zipped<T>(url: string, { unzip }?: {
     unzip?: boolean | undefined;
 }): Promise<T | null>;
-export declare function download(data: string | Blob, filename: string, type: string): void;
+export type DownloadData = string | Blob | ArrayBuffer | ArrayBufferView<ArrayBuffer>;
+export declare function download(data: DownloadData, filename: string, type: string): void;

package/dist/io/file-drop.d.ts

@@ -4,4 +4,11 @@ export interface FileDropOptions {
     on_error?: (msg: string) => void;
     set_loading?: (loading: boolean) => void;
 }
+export declare const drag_over_handlers: (opts: {
+    allow?: () => boolean;
+    set_dragover: (over: boolean) => void;
+}) => {
+    ondragover: (event: DragEvent) => void;
+    ondragleave: () => void;
+};
 export declare const create_file_drop_handler: (opts: FileDropOptions) => ((event: DragEvent) => Promise<void>);

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';
@@ -5,3 +6,4 @@ export * from './file-drop';
 export * from './is-binary';
 export type * from './types';
 export * from './url-drop';
+export declare function strip_compression_extensions(filename: string): string;

package/dist/io/index.js

@@ -1,6 +1,16 @@
+import { COMPRESSION_EXTENSIONS_REGEX } from '../constants';
+export { default as ExportPane } from './ExportPane.svelte';
 export * from './decompress';
 export * from './export';
 export * from './fetch';
 export * from './file-drop';
 export * from './is-binary';
 export * from './url-drop';
+// Lowercase a filename and strip all trailing compression extensions (.gz, .zip, ...)
+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;
+}

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/isosurface/parse.js

@@ -1,10 +1,23 @@
 // Parsers for volumetric data file formats (VASP CHGCAR, Gaussian .cube)
-import { COMPRESSION_EXTENSIONS_REGEX, VASP_VOLUMETRIC_REGEX } from '../constants';
-import { ELEM_SYMBOLS } from '../labels';
+import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
+import { VASP_VOLUMETRIC_REGEX } from '../constants';
+import { coerce_elem_symbol, FALLBACK_ELEMENTS } from '../element';
+import { strip_compression_extensions } from '../io';
 import * as math from '../math';
 import { wrap_to_unit_cell } from '../structure/pbc';
+import { make_site } from '../structure/site';
 // Bohr radius in Angstroms (for Gaussian .cube unit conversion)
 const BOHR_TO_ANGSTROM = 0.529177249;
+// === Parse error contract ===
+// parse_chgcar/parse_cube return null and record reasons here (mirrored to console.error).
+// parse_volumetric_file resets per call and throws when the FILENAME identifies a volumetric
+// format that fails to parse, but returns null when content doesn't look volumetric at all
+// (probe semantics — callers then fall back to structure parsing).
+let vol_parse_errors = [];
+const vol_error = (message) => {
+    vol_parse_errors.push(message);
+    console.error(message);
+};
 // === Fast number parsing utilities ===
 // Parse whitespace-separated numbers directly from a string, starting at `pos`.
 // Writes into a pre-allocated Float64Array and returns { count, end_pos }.
@@ -177,7 +190,7 @@ export function parse_chgcar(content) {
     cur = read_line(content, pos);
     const scale_factor = parseFloat(cur.line);
     if (isNaN(scale_factor)) {
-        console.error(`Invalid scaling factor in CHGCAR`);
+        vol_error(`Invalid scaling factor in CHGCAR`);
         return null;
     }
     pos = cur.next;
@@ -195,7 +208,7 @@ export function parse_chgcar(content) {
     let atom_counts = [];
     cur = read_line(content, pos);
     if (pos >= content.length) {
-        console.error(`CHGCAR: file ends before element/count lines`);
+        vol_error(`CHGCAR: file ends before element/count lines`);
         return null;
     }
     // Detect VASP 5+ format (has element symbols before counts)
@@ -206,19 +219,18 @@ export function parse_chgcar(content) {
         pos = cur.next;
         cur = read_line(content, pos);
         if (pos >= content.length) {
-            console.error(`CHGCAR: file ends before atom counts line`);
+            vol_error(`CHGCAR: file ends before atom counts line`);
             return null;
         }
         atom_counts = cur.line.trim().split(/\s+/).map(Number);
     }
     else {
         atom_counts = cur.line.trim().split(/\s+/).map(Number);
-        const fallback_elements = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`];
-        element_symbols = atom_counts.map((_count, idx) => fallback_elements[idx % fallback_elements.length]);
+        element_symbols = atom_counts.map((_count, idx) => FALLBACK_ELEMENTS[idx % FALLBACK_ELEMENTS.length]);
     }
     pos = cur.next;
     if (pos >= content.length) {
-        console.error(`CHGCAR: file ends before coordinate mode line`);
+        vol_error(`CHGCAR: file ends before coordinate mode line`);
         return null;
     }
     // Check for selective dynamics line
@@ -228,7 +240,7 @@ export function parse_chgcar(content) {
         cur = read_line(content, pos);
     }
     if (pos >= content.length) {
-        console.error(`CHGCAR: file ends before coordinate mode line`);
+        vol_error(`CHGCAR: file ends before coordinate mode line`);
         return null;
     }
     // Coordinate mode line
@@ -242,18 +254,18 @@ export function parse_chgcar(content) {
         ({ cart_to_frac, frac_to_cart } = math.create_lattice_converters(lattice));
     }
     catch {
-        console.error(`CHGCAR: lattice matrix is singular; cannot convert coordinates`);
+        vol_error(`CHGCAR: lattice matrix is singular; cannot convert coordinates`);
         return null;
     }
     const sites = [];
     let atom_idx = 0;
     for (let elem_idx = 0; elem_idx < element_symbols.length; elem_idx++) {
         const symbol = element_symbols[elem_idx].split(/[_/]/)[0];
-        const element = (ELEM_SYMBOLS.includes(symbol) ? symbol : `H`);
+        const element = coerce_elem_symbol(symbol) ?? `H`;
         const count = atom_counts[elem_idx];
         for (let count_idx = 0; count_idx < count; count_idx++) {
             if (pos >= content.length) {
-                console.error(`CHGCAR: file ends before all atom coordinates are read`);
+                vol_error(`CHGCAR: file ends before all atom coordinates are read`);
                 return null;
             }
             cur = read_line(content, pos);
@@ -270,13 +282,7 @@ export function parse_chgcar(content) {
                 const raw = cart_to_frac(xyz);
                 abc = wrap_to_unit_cell(raw);
             }
-            sites.push({
-                species: [{ element, occu: 1, oxidation_state: 0 }],
-                abc,
-                xyz,
-                label: `${element}${atom_idx + count_idx + 1}`,
-                properties: {},
-            });
+            sites.push(make_site(element, abc, xyz, `${element}${atom_idx + count_idx + 1}`));
         }
         atom_idx += count;
     }
@@ -348,7 +354,7 @@ export function parse_chgcar(content) {
         }
     }
     if (volumes.length === 0) {
-        console.error(`No volumetric data found in CHGCAR`);
+        vol_error(`No volumetric data found in CHGCAR`);
         return null;
     }
     return { structure, volumes };
@@ -365,7 +371,7 @@ export function parse_cube(content, options = {}) {
             line_count++;
     }
     if (line_count < 6) {
-        console.error(`.cube file too short`);
+        vol_error(`.cube file too short`);
         return null;
     }
     // Parse header (first 6 lines + atom lines)
@@ -376,7 +382,7 @@ export function parse_cube(content, options = {}) {
     // (negative n_atoms indicates orbital data with extra header line)
     const line2 = header.lines[2].split(/\s+/).map(Number);
     if (line2.length < 4 || line2.some(isNaN)) {
-        console.error(`.cube header line 3 malformed: expected 4 numbers`);
+        vol_error(`.cube header line 3 malformed: expected 4 numbers`);
         return null;
     }
     const n_atoms = Math.abs(line2[0]);
@@ -390,7 +396,7 @@ export function parse_cube(content, options = {}) {
         header.lines[5].split(/\s+/).map(Number),
     ];
     if (voxel_lines.some((line) => line.length < 4 || line.some(isNaN))) {
-        console.error(`.cube voxel lines malformed: expected 4 numbers per line`);
+        vol_error(`.cube voxel lines malformed: expected 4 numbers per line`);
         return null;
     }
     const n_grid = [
@@ -423,7 +429,7 @@ export function parse_cube(content, options = {}) {
     }
     catch {
         // Non-periodic system (molecule), use identity
-        cube_cart_to_frac = (v) => [v[0], v[1], v[2]];
+        cube_cart_to_frac = (vec) => [vec[0], vec[1], vec[2]];
     }
     for (let atom_idx = 0; atom_idx < n_atoms; atom_idx++) {
         const cur = read_line(content, pos);
@@ -444,13 +450,7 @@ export function parse_cube(content, options = {}) {
         const xyz = math.subtract(raw_xyz, origin);
         const abc = cube_cart_to_frac(xyz);
         const element = atomic_number_to_symbol(atom_line[0]);
-        sites.push({
-            species: [{ element, occu: 1, oxidation_state: 0 }],
-            abc,
-            xyz,
-            label: `${element}${atom_idx + 1}`,
-            properties: {},
-        });
+        sites.push(make_site(element, abc, xyz, `${element}${atom_idx + 1}`));
     }
     // Build structure
     const lattice_params = math.calc_lattice_params(lattice);
@@ -474,7 +474,7 @@ export function parse_cube(content, options = {}) {
     if (parsed_count < total_points) {
         console.warn(`.cube: expected ${total_points} data values, got ${parsed_count}`);
         if (parsed_count === 0) {
-            console.error(`No volumetric data found in .cube file`);
+            vol_error(`No volumetric data found in .cube file`);
             return null;
         }
     }
@@ -499,22 +499,24 @@ export function parse_cube(content, options = {}) {
     ];
     return { structure, volumes };
 }
-// Convert atomic number to element symbol using ELEM_SYMBOLS (1-indexed: H=1, He=2, ...)
-function atomic_number_to_symbol(atomic_number) {
-    // ELEM_SYMBOLS is 0-indexed (H at index 0), atomic numbers are 1-indexed
-    const idx = atomic_number - 1;
-    return idx >= 0 && idx < ELEM_SYMBOLS.length ? ELEM_SYMBOLS[idx] : `H`;
-}
-// Auto-detect and parse volumetric file format based on filename and content
+// Convert atomic number to element symbol (falls back to H for unknown numbers)
+const atomic_number_to_symbol = (atomic_number) => ATOMIC_NUMBER_TO_SYMBOL[atomic_number] ?? `H`;
+// Auto-detect and parse volumetric file by filename + content (see parse error contract at top)
 export function parse_volumetric_file(content, filename) {
+    vol_parse_errors = [];
+    const fail = (format) => {
+        const detail = vol_parse_errors.length ? `: ${vol_parse_errors.join(`; `)}` : ``;
+        throw new Error(`Failed to parse ${format} file${filename ? ` '${filename}'` : ``}${detail}`);
+    };
     // Strip compression suffixes so "CHGCAR.gz" and "molecule.cube.bz2" match correctly
-    const lower_name = (filename ?? ``).toLowerCase().replace(COMPRESSION_EXTENSIONS_REGEX, ``);
-    // Extension-based detection
+    const lower_name = strip_compression_extensions(filename ?? ``);
+    // Extension-based detection (filename is authoritative: parse failure throws)
     if (lower_name.endsWith(`.cube`))
-        return parse_cube(content);
+        return parse_cube(content) ?? fail(`.cube`);
     // VASP volumetric file detection by filename
-    if (VASP_VOLUMETRIC_REGEX.test(lower_name))
-        return parse_chgcar(content);
+    if (VASP_VOLUMETRIC_REGEX.test(lower_name)) {
+        return parse_chgcar(content) ?? fail(`VASP volumetric (CHGCAR-like)`);
+    }
     // Content-based detection (only parse first few lines, not the whole file)
     // Find enough lines for detection without splitting the entire string
     const detection_end = find_line_offset(content, 10);

package/dist/labels.js

@@ -16,7 +16,7 @@ export const symbol_names = [
     ...new Set([...d3_symbols.symbolsFill, ...d3_symbols.symbolsStroke]),
 ]
     .map(name_for_symbol)
-    .filter((n) => n !== null);
+    .filter((name) => name !== null);
 export const symbol_map = Object.fromEntries(
 // Symbol lookup from d3-shape
 symbol_names.map((name) => [name, d3_symbols[`symbol${name}`]]));