matterviz 0.4.1 → 0.4.3

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/url-drop.d.ts

@@ -1,2 +1,4 @@
+export declare const basename_from_url: (url: string) => string;
+export declare function dropped_file_url(drag_event: DragEvent): string | undefined;
 export declare function handle_url_drop(drag_event: DragEvent, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<boolean>;
 export declare function load_from_url(url: string, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<void>;

package/dist/io/url-drop.js

@@ -1,9 +1,14 @@
 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';
+// Strip query/hash; last path segment (same basename load_from_url uses).
+// Trailing-slash URLs yield an empty segment — fall back to the original URL.
+export const basename_from_url = (url) => {
+    const basename = url.split(/[?#]/)[0].split(`/`).pop();
+    if (!basename)
+        return url;
+    return basename;
+};
 // Extract filename from Content-Disposition header, falling back to url_basename.
 function extract_filename(headers, fallback) {
     if (!headers)
@@ -11,11 +16,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 +30,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,29 +44,37 @@ 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) {
+// Extract the URL of a FilePicker-style drop payload. Synchronous because
+// DataTransfer.getData is only readable during drop-event dispatch — callers
+// that defer processing (e.g. drop queues) must capture the URL up front.
+export function dropped_file_url(drag_event) {
     const json_data = drag_event.dataTransfer?.getData(`application/json`);
     if (!json_data)
-        return false;
-    let file_info;
+        return undefined;
     try {
-        file_info = JSON.parse(json_data);
+        // Runtime-check instead of trusting the FileInfo cast: drop payloads are
+        // external input and a truthy non-string url must not reach fetch()
+        const { url } = JSON.parse(json_data);
+        return typeof url === `string` && url ? url : undefined;
     }
     catch {
-        return false;
+        return undefined;
     }
-    if (!file_info.url)
+}
+// Handle URL-based file drop data by fetching content lazily
+export async function handle_url_drop(drag_event, callback) {
+    const url = dropped_file_url(drag_event);
+    if (!url)
         return false;
-    await load_from_url(file_info.url, callback);
+    await load_from_url(url, callback);
     return true;
 }
 export async function load_from_url(url, callback) {
     // Strip query string/hash before basename/extension detection so pre-signed
     // URLs like traj.h5?X-Amz-Expires=300 still hit the right format path
-    const url_basename = url.split(/[?#]/)[0].split(`/`).pop() ?? url;
+    const url_basename = basename_from_url(url);
     const ext = ext_of(url_basename);
     if (BINARY_EXTENSIONS.has(ext)) {
         // Force binary mode for known binary files to handle GitHub Pages content-type issues
@@ -87,12 +96,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,9 +115,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);
-    let sniffed_callback_args;
-    if (!is_known_text) {
+    if (!is_known_text_file(url_basename)) {
         // Only the Range sniff is guarded (failure → plain text fetch). Once magic bytes
         // commit to a binary format, download/decompress errors must propagate instead of
         // falling through to a text fetch that would parse the binary bytes as garbage.
@@ -121,13 +126,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`;
             }
         }
@@ -141,12 +143,10 @@ export async function load_from_url(url, callback) {
             const filename = extract_filename(resp.headers, url_basename);
             const buffer = await resp.arrayBuffer();
             // Gunzip sniffed gzip — downstream parsers can't handle raw gzip bytes
-            sniffed_callback_args =
-                sniffed === `gzip` ? await decompress_gz_payload(buffer, filename) : [buffer, filename];
+            const args = sniffed === `gzip` ? await decompress_gz_payload(buffer, filename) : [buffer, filename];
+            return callback(...args);
         }
     }
-    if (sniffed_callback_args)
-        return callback(...sniffed_callback_args);
     const resp = await fetch(url);
     if (!resp.ok)
         throw new Error(`Fetch failed: ${resp.status}`);