matterviz 0.3.6 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export * from './brillouin';
+export * from './chempot-diagram';
+export * from './colors';
+export * from './composition';
+export * from './constants';
+export * from './controls';
+export * from './convex-hull';
+export * from './coordination';
+export * from './element';
+export { default as EmptyState } from './EmptyState.svelte';
+export * from './feedback';
+export * from './fermi-surface';
+export { default as FilePicker } from './FilePicker.svelte';
+export * from './heatmap-matrix';
+export { default as Icon } from './Icon.svelte';
+export * from './icons';
+export * from './io';
+export { default as MillerIndexInput } from './MillerIndexInput.svelte';
+export { auto_isosurface_settings, DEFAULT_ISOSURFACE_SETTINGS, generate_layers, grid_data_range, Isosurface as VolumetricIsosurface, IsosurfaceControls, LAYER_COLORS, parse_chgcar, parse_cube, parse_volumetric_file, sample_hkl_slice, tile_volumetric_data, trilinear_interpolate, } from './isosurface';
+export type { DataRange, IsosurfaceLayer, IsosurfaceSettings, SliceResult, VolumetricData, VolumetricFileData, } from './isosurface';
+export * from './labels';
+export * from './layout';
+export * from './math';
+export * from './overlays';
+export * from './periodic-table';
+export * from './phase-diagram';
+export * from './plot';
+export * from './rdf';
+export * from './sanitize';
+export * from './settings';
+export * from './spectral';
+export * from './structure';
+export * from './symmetry';
+export * from './table';
+export * from './theme';
+export * from './time';
+export { default as Trajectory } from './trajectory/Trajectory.svelte';
+export * from './utils';
+export * from './xrd';

package/dist/index.js

@@ -0,0 +1,39 @@
+export * from './brillouin';
+export * from './chempot-diagram';
+export * from './colors';
+export * from './composition';
+export * from './constants';
+export * from './controls';
+export * from './convex-hull';
+export * from './coordination';
+export * from './element';
+export { default as EmptyState } from './EmptyState.svelte';
+export * from './feedback';
+export * from './fermi-surface';
+export { default as FilePicker } from './FilePicker.svelte';
+export * from './heatmap-matrix';
+export { default as Icon } from './Icon.svelte';
+export * from './icons';
+export * from './io';
+export { default as MillerIndexInput } from './MillerIndexInput.svelte';
+// Explicit exports to avoid name clash with fermi-surface's Isosurface type
+export { auto_isosurface_settings, DEFAULT_ISOSURFACE_SETTINGS, generate_layers, grid_data_range, Isosurface as VolumetricIsosurface, IsosurfaceControls, LAYER_COLORS, parse_chgcar, parse_cube, parse_volumetric_file, sample_hkl_slice, tile_volumetric_data, trilinear_interpolate, } from './isosurface';
+export * from './labels';
+export * from './layout';
+export * from './math';
+export * from './overlays';
+export * from './periodic-table';
+export * from './phase-diagram';
+export * from './plot';
+export * from './rdf';
+export * from './sanitize';
+export * from './settings';
+export * from './spectral';
+export * from './structure';
+export * from './symmetry';
+export * from './table';
+export * from './theme';
+export * from './time';
+export { default as Trajectory } from './trajectory/Trajectory.svelte';
+export * from './utils';
+export * from './xrd';

package/dist/io/decompress.d.ts

@@ -0,0 +1,11 @@
+import type { COMPRESSION_EXTENSIONS } from '../constants';
+import { COMPRESSION_FORMATS } from '../constants';
+export type CompressionFormat = keyof typeof COMPRESSION_FORMATS;
+export type CompressionExtension = (typeof COMPRESSION_EXTENSIONS)[number];
+export declare function detect_compression_format(filename: string): CompressionFormat | null;
+export declare function decompress_data(data: ArrayBuffer | ReadableStream<Uint8Array> | null, format: CompressionFormat): Promise<string>;
+export declare function decompress_data_binary(data: ArrayBuffer | ReadableStream<Uint8Array> | null, format: CompressionFormat): Promise<ArrayBuffer>;
+export declare function decompress_file(file: File): Promise<{
+    content: string;
+    filename: string;
+}>;

package/dist/io/decompress.js

@@ -0,0 +1,76 @@
+import { COMPRESSION_EXTENSIONS_REGEX, COMPRESSION_FORMATS } from '../constants';
+import { to_error } from '../utils';
+export function detect_compression_format(filename) {
+    const lower = filename.toLowerCase();
+    for (const [format, extensions] of Object.entries(COMPRESSION_FORMATS)) {
+        if (extensions.some((ext) => lower.endsWith(ext)))
+            return format;
+    }
+    return null;
+}
+// Decompress data and return as text string
+export async function decompress_data(data, format) {
+    const buffer = await decompress_data_binary(data, format);
+    return new TextDecoder().decode(buffer);
+}
+// 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.`);
+        }
+        const stream = data instanceof ArrayBuffer
+            ? new ReadableStream({
+                start(controller) {
+                    controller.enqueue(new Uint8Array(data));
+                    controller.close();
+                },
+            })
+            : data;
+        if (!stream)
+            throw new Error(`Invalid data stream`);
+        const unzip = new DecompressionStream(format);
+        return await new Response(stream.pipeThrough(unzip)).arrayBuffer();
+    }
+    catch (error) {
+        throw new Error(`Failed to decompress ${format} file: ${error}`, { cause: error });
+    }
+}
+export function decompress_file(file) {
+    const format = detect_compression_format(file.name);
+    const is_supported = Boolean(format && ![`zip`, `xz`, `bz2`].includes(format));
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.addEventListener(`load`, () => {
+            try {
+                const result = reader.result;
+                // strict null check: empty files legitimately read as '' (falsy)
+                if (result === null)
+                    throw new Error(`Failed to read file`);
+                if (is_supported && format) {
+                    if (!(result instanceof ArrayBuffer))
+                        throw new Error(`Expected binary file data`);
+                    decompress_data(result, format).then((content) => {
+                        const filename = file.name.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
+                        resolve({ content, filename });
+                    }, reject);
+                }
+                else {
+                    if (typeof result !== `string`)
+                        throw new Error(`Expected text file data`);
+                    resolve({ content: result, filename: file.name });
+                }
+            }
+            catch (error) {
+                reject(to_error(error));
+            }
+        }, { once: true });
+        reader.addEventListener(`error`, () => reject(new Error(`Failed to read file ${file.name}`)));
+        if (is_supported)
+            reader.readAsArrayBuffer(file);
+        else
+            reader.readAsText(file);
+    });
+}

package/dist/io/export.d.ts

@@ -0,0 +1,16 @@
+import type { AnyStructure } from '../structure';
+import { type Camera, type Scene } from 'three';
+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 get_ffmpeg_conversion_command(input_filename: string): string;
+export declare function export_trajectory_video(canvas: HTMLCanvasElement | null, filename: string, options?: {
+    fps?: number;
+    total_frames?: number;
+    on_progress?: (progress: number) => void;
+    on_step?: (step_idx: number) => void | Promise<void>;
+    resolution_multiplier?: number;
+}): Promise<void>;

package/dist/io/export.js

@@ -0,0 +1,338 @@
+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;
+}
+// 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);
+    if (resolution_multiplier <= 1.1 || !renderer) {
+        if (renderer && scene && camera)
+            renderer.render(scene, camera);
+        return new Promise((resolve, reject) => {
+            try {
+                canvas.toBlob((blob) => {
+                    if (blob)
+                        resolve(blob);
+                    else
+                        reject(new Error(`Failed to generate PNG - canvas may be empty`));
+                }, `image/png`);
+            }
+            catch (error) {
+                reject(to_error(error));
+            }
+        });
+    }
+    // Temporarily modify the renderer's pixel ratio for high-res capture
+    const orig_pixel_ratio = renderer.getPixelRatio();
+    const orig_size = renderer.getSize(new Vector2());
+    const restore = () => {
+        renderer.setPixelRatio(orig_pixel_ratio);
+        renderer.setSize(orig_size.width, orig_size.height, false);
+    };
+    renderer.setPixelRatio(resolution_multiplier);
+    renderer.setSize(orig_size.width, orig_size.height, false);
+    if (scene && camera)
+        renderer.render(scene, camera);
+    return new Promise((resolve, reject) => {
+        try {
+            canvas.toBlob((blob) => {
+                restore();
+                if (blob)
+                    resolve(blob);
+                else
+                    reject(new Error(`Failed to generate high-resolution PNG`));
+            }, `image/png`);
+        }
+        catch (error) {
+            restore();
+            reject(to_error(error));
+        }
+    });
+}
+// Export structure as PNG image from canvas (triggers browser download)
+export function export_canvas_as_png(canvas, structure_or_filename, png_dpi = 150, scene = null, camera = null) {
+    if (!canvas) {
+        if (typeof window !== `undefined`)
+            console.warn(`Canvas not found for PNG export`);
+        return;
+    }
+    let filename = typeof structure_or_filename === `string`
+        ? structure_or_filename
+        : create_structure_filename(structure_or_filename, `png`);
+    const suffix = `-${Math.round(png_dpi)}dpi`;
+    if (filename.toLowerCase().endsWith(`.png`)) {
+        filename = filename.replace(/\.png$/i, `${suffix}.png`);
+    }
+    else {
+        filename = `${filename}${suffix}.png`;
+    }
+    canvas_to_png_blob(canvas, png_dpi, scene, camera)
+        .then((blob) => download(blob, filename, `image/png`))
+        .catch((error) => console.error(`Error exporting PNG:`, error));
+}
+// Helper to ensure font-family is set on SVG root
+function set_svg_font_family(svg) {
+    const style = svg.getAttribute(`style`) ?? ``;
+    if (!style.includes(`font-family`)) {
+        svg.setAttribute(`style`, `${style}${style ? `;` : ``}font-family:sans-serif;`);
+    }
+    // Also set as attribute for extra robustness
+    svg.setAttribute(`font-family`, `sans-serif`);
+}
+// Copy the given computed-style props from each live SVG element to its clone counterpart;
+// identical structure lets querySelectorAll(`*`) walk both in lockstep. Writes clone-only.
+function inline_computed_styles(live, clone, properties) {
+    const live_els = [live, ...live.querySelectorAll(`*`)];
+    const clone_els = [clone, ...clone.querySelectorAll(`*`)];
+    for (const [idx, live_el] of live_els.entries()) {
+        const computed = getComputedStyle(live_el);
+        for (const prop of properties) {
+            const val = computed.getPropertyValue(prop);
+            if (val)
+                clone_els[idx].setAttribute(prop, val);
+        }
+    }
+}
+// Clone, inline the given computed-style props, ensure font-family + xmlns, then serialize
+// to a standalone SVG string. Never mutates the live element.
+function serialize_svg_for_export(svg_element, inline_styles = []) {
+    const clone = svg_element.cloneNode(true);
+    if (inline_styles.length)
+        inline_computed_styles(svg_element, clone, inline_styles);
+    set_svg_font_family(clone);
+    if (!clone.hasAttribute(`xmlns`)) {
+        clone.setAttribute(`xmlns`, `http://www.w3.org/2000/svg`);
+    }
+    return new XMLSerializer().serializeToString(clone);
+}
+// Wrap serialize_svg_for_export's output as a full SVG document string (XML declaration +
+// DOCTYPE + SVG), suitable for saving to file.
+export function svg_to_svg_string(svg_element, 
+// CSS props to inline from computed styles as presentation attributes; a standalone SVG
+// drops page stylesheets (e.g. Svelte component styles), so class-based styling is lost.
+inline_styles = []) {
+    const svg_string = serialize_svg_for_export(svg_element, inline_styles);
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">\n${svg_string}`;
+}
+// Export SVG element as SVG file (triggers browser download)
+export function export_svg_as_svg(svg_element, filename, inline_styles = []) {
+    if (!svg_element) {
+        console.warn(`SVG element not found for export`);
+        return;
+    }
+    try {
+        const svg_content = svg_to_svg_string(svg_element, inline_styles);
+        download(svg_content, filename, `image/svg+xml;charset=utf-8`);
+    }
+    catch (error) {
+        console.error(`Error exporting SVG:`, error);
+    }
+}
+// Rasterize an SVG element to a PNG Blob at the given DPI.
+// Creates an offscreen canvas at the scaled resolution, draws the SVG via an
+// Image element, and returns the resulting PNG Blob. Rejects if viewBox is
+// missing or dimensions are invalid (zero width/height).
+// DPI is converted to a resolution multiplier relative to 72 DPI baseline, capped at 10x.
+export function svg_to_png_blob(svg_element, png_dpi = 150, inline_styles = []) {
+    const viewBox = svg_element.getAttribute(`viewBox`)?.trim();
+    if (!viewBox)
+        return Promise.reject(new Error(`SVG viewBox not found for PNG export`));
+    const parts = viewBox.split(/[\s,]+/).map(Number);
+    if (parts.length < 4 || !parts.every(Number.isFinite)) {
+        return Promise.reject(new Error(`Invalid SVG dimensions for PNG export`));
+    }
+    const [, , width, height] = parts;
+    if (!(width > 0) || !(height > 0)) {
+        return Promise.reject(new Error(`Invalid SVG dimensions for PNG export`));
+    }
+    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 canvas = document.createElement(`canvas`);
+    const ctx = canvas.getContext(`2d`);
+    if (!ctx)
+        return Promise.reject(new Error(`Canvas 2D context not available`));
+    canvas.width = pixel_width;
+    canvas.height = pixel_height;
+    const serialized = serialize_svg_for_export(svg_element, inline_styles);
+    const svg_blob = new Blob([serialized], { type: `image/svg+xml;charset=utf-8` });
+    const svg_data_url = URL.createObjectURL(svg_blob);
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.addEventListener(`load`, () => {
+            try {
+                ctx.clearRect(0, 0, pixel_width, pixel_height);
+                ctx.drawImage(img, 0, 0, pixel_width, pixel_height);
+                canvas.toBlob((blob) => {
+                    if (blob)
+                        resolve(blob);
+                    else
+                        reject(new Error(`Failed to generate PNG blob`));
+                }, `image/png`, 1);
+            }
+            catch (error) {
+                reject(to_error(error));
+            }
+            finally {
+                URL.revokeObjectURL(svg_data_url);
+            }
+        });
+        img.addEventListener(`error`, () => {
+            URL.revokeObjectURL(svg_data_url);
+            reject(new Error(`Failed to load SVG for PNG export`));
+        });
+        img.src = svg_data_url;
+    });
+}
+// Export SVG element as PNG (triggers browser download)
+export function export_svg_as_png(svg_element, filename, png_dpi = 150, inline_styles = []) {
+    if (!svg_element) {
+        console.warn(`SVG element not found for PNG export`);
+        return;
+    }
+    svg_to_png_blob(svg_element, png_dpi, inline_styles)
+        .then((blob) => download(blob, filename, `image/png`))
+        .catch((error) => console.error(`Error exporting PNG:`, error));
+}
+// Generate FFmpeg command for WebM to MP4 conversion
+export function get_ffmpeg_conversion_command(input_filename) {
+    const output = input_filename.replace(/\.webm$/i, `.mp4`);
+    return `ffmpeg -i "${input_filename}" -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p -movflags faststart "${output}"`;
+}
+// Export trajectory video as WebM with frame-by-frame rendering to prevent dropped frames.
+// Note: Browsers only support WebM natively. Use FFmpeg for MP4 conversion (see get_ffmpeg_conversion_command).
+export async function export_trajectory_video(canvas, filename, options = {}) {
+    const { fps = 30, total_frames = 100, on_progress, on_step, resolution_multiplier = 1, } = options;
+    if (!canvas ||
+        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);
+    // Store original renderer settings if changing resolution
+    let orig_pixel_ratio;
+    let orig_size;
+    if (resolution_multiplier !== 1 && renderer) {
+        orig_pixel_ratio = renderer.getPixelRatio();
+        orig_size = renderer.getSize(new Vector2());
+        // Adjust pixel ratio for different resolution export
+        renderer.setPixelRatio(orig_pixel_ratio * resolution_multiplier);
+        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));
+    const stream = canvas.captureStream(0);
+    const chunks = [];
+    const recorder = new MediaRecorder(stream, {
+        mimeType: `video/webm;codecs=vp9`,
+        videoBitsPerSecond: bitrate,
+    });
+    recorder.addEventListener(`dataavailable`, (event) => {
+        if (event.data.size > 0)
+            chunks.push(event.data);
+    });
+    const track = stream.getVideoTracks()[0];
+    // Start recording
+    recorder.start();
+    const frame_duration = 1000 / fps;
+    try {
+        // Render each frame sequentially with precise timing
+        for (let idx = 0; idx < total_frames; idx++) {
+            const frame_start = performance.now();
+            on_progress?.((idx / total_frames) * 100);
+            // Update trajectory step
+            if (on_step)
+                await on_step(idx);
+            // Double RAF ensures Three.js completes rendering before capture
+            await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+            // Capture frame
+            track.requestFrame?.();
+            // Wait for remaining frame time to maintain consistent FPS
+            const elapsed = performance.now() - frame_start;
+            const remaining = Math.max(0, frame_duration - elapsed);
+            if (remaining > 0) {
+                await new Promise((resolve) => setTimeout(resolve, remaining));
+            }
+        }
+    }
+    finally {
+        // Restore original renderer settings
+        if (orig_pixel_ratio !== undefined && orig_size && renderer) {
+            renderer.setPixelRatio(orig_pixel_ratio);
+            renderer.setSize(orig_size.width, orig_size.height, false);
+        }
+    }
+    // Finalize recording
+    return new Promise((resolve, reject) => {
+        let is_resolved = false;
+        recorder.addEventListener(`stop`, () => {
+            if (is_resolved)
+                return;
+            is_resolved = true;
+            try {
+                const blob = new Blob(chunks, { type: `video/webm` });
+                const webm_filename = filename.replace(/\.(mp4|webm)$/i, `.webm`);
+                download(blob, webm_filename, `video/webm`);
+                on_progress?.(100);
+                resolve();
+            }
+            catch (error) {
+                reject(to_error(error));
+            }
+        });
+        recorder.addEventListener(`error`, (event) => {
+            if (is_resolved)
+                return;
+            is_resolved = true;
+            const error_msg = event instanceof ErrorEvent && event.error instanceof Error
+                ? event.error.message
+                : event.type;
+            reject(new Error(`MediaRecorder error: ${error_msg}`));
+        });
+        // Stop recording with safety timeout
+        try {
+            recorder.stop();
+            // Fallback: force resolution if recorder doesn't stop within 5 seconds
+            setTimeout(() => {
+                if (!is_resolved) {
+                    is_resolved = true;
+                    reject(new Error(`Recording timeout - recorder did not stop`));
+                }
+            }, 5000);
+        }
+        catch (error) {
+            if (!is_resolved) {
+                is_resolved = true;
+                reject(to_error(error));
+            }
+        }
+    });
+}

package/dist/io/fetch.d.ts

@@ -0,0 +1,5 @@
+export declare const to_query: (params: Record<string, string | number | undefined>) => string;
+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;

package/dist/io/fetch.js

@@ -0,0 +1,43 @@
+import { decompress_data } from './decompress';
+// Convert params object to URL query string, omitting empty/undefined values.
+// Example: {foo: "bar", baz: 42, empty: ""} → "foo=bar&baz=42"
+export const to_query = (params) => new URLSearchParams(Object.entries(params)
+    .filter(([, val]) => val !== `` && val !== undefined)
+    .map(([key, val]) => [key, String(val)])).toString();
+export async function fetch_zipped(url, { unzip = true } = {}) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        console.error(`${response.status} ${response.statusText} for ${response.url}`);
+        return null;
+    }
+    if (!unzip)
+        return (await response.blob());
+    return JSON.parse(await decompress_data(response.body, `gzip`));
+}
+// Original download implementation
+function default_download(data, filename, type) {
+    const file = new Blob([data], { type });
+    const link = document.createElement(`a`);
+    const url = URL.createObjectURL(file);
+    link.style.display = `none`;
+    link.href = url;
+    link.download = filename;
+    // keep the synthetic download click from bubbling to document-level handlers
+    // (e.g. DraggablePane's click-outside) that would dismiss an open pane the export
+    // button lives in
+    link.addEventListener(`click`, (evt) => evt.stopPropagation());
+    document.body.append(link);
+    link.click();
+    link.remove();
+    URL.revokeObjectURL(url);
+}
+// Function to download data to a file - checks for global override first
+export function download(data, filename, type) {
+    // Check if there's a global download override (used by VSCode extension)
+    const global_download = globalThis.download;
+    if (typeof global_download === `function` && global_download !== download) {
+        return global_download(data, filename, type);
+    }
+    // Use default browser download
+    return default_download(data, filename, type);
+}

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

@@ -0,0 +1,7 @@
+export interface FileDropOptions {
+    allow: () => boolean;
+    on_drop: (content: string | ArrayBuffer, filename: string) => void | Promise<void>;
+    on_error?: (msg: string) => void;
+    set_loading?: (loading: boolean) => void;
+}
+export declare const create_file_drop_handler: (opts: FileDropOptions) => ((event: DragEvent) => Promise<void>);

package/dist/io/file-drop.js

@@ -0,0 +1,42 @@
+// Shared file-drop handler composable for drag-and-drop file loading.
+import { decompress_file } from './decompress';
+import { handle_url_drop } from './url-drop';
+import { to_error } from '../utils';
+// Handles URL drops (from FilePicker), direct file drops with decompression,
+// loading state, and error reporting.
+export const create_file_drop_handler = (opts) => async (event) => {
+    event.preventDefault();
+    if (!opts.allow())
+        return;
+    opts.set_loading?.(true);
+    let drop_filename = ``;
+    try {
+        let url_error;
+        const handled = await handle_url_drop(event, opts.on_drop).catch((exc) => {
+            url_error = to_error(exc).message;
+            return false;
+        });
+        if (handled)
+            return;
+        const file = event.dataTransfer?.files[0];
+        if (!file) {
+            if (url_error)
+                opts.on_error?.(`Failed to load from URL: ${url_error}`);
+            return;
+        }
+        drop_filename = file.name;
+        const { content, filename } = await decompress_file(file);
+        if (content)
+            await opts.on_drop(content, filename);
+    }
+    catch (exc) {
+        const detail = to_error(exc).message;
+        const msg = drop_filename
+            ? `Failed to load file ${drop_filename}: ${detail}`
+            : `Failed to load file: ${detail}`;
+        opts.on_error?.(msg);
+    }
+    finally {
+        opts.set_loading?.(false);
+    }
+};

package/dist/io/index.d.ts

@@ -0,0 +1,7 @@
+export * from './decompress';
+export * from './export';
+export * from './fetch';
+export * from './file-drop';
+export * from './is-binary';
+export type * from './types';
+export * from './url-drop';

package/dist/io/index.js

@@ -0,0 +1,6 @@
+export * from './decompress';
+export * from './export';
+export * from './fetch';
+export * from './file-drop';
+export * from './is-binary';
+export * from './url-drop';

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

@@ -0,0 +1 @@
+export declare const is_binary: (content: string) => boolean;

package/dist/io/is-binary.js

@@ -0,0 +1,20 @@
+// Simplified binary detection
+export const is_binary = (content) => {
+    if (!content)
+        return false;
+    if (content.includes(`\0`))
+        return true;
+    let binary_char_count = 0;
+    let printable_ascii_count = 0;
+    for (let char_idx = 0; char_idx < content.length; char_idx += 1) {
+        const char_code = content.charCodeAt(char_idx);
+        if (char_code <= 8 ||
+            (char_code >= 14 && char_code <= 31) ||
+            (char_code >= 127 && char_code <= 255)) {
+            binary_char_count += 1;
+        }
+        if (char_code >= 32 && char_code <= 126)
+            printable_ascii_count += 1;
+    }
+    return (binary_char_count / content.length > 0.1 || printable_ascii_count / content.length < 0.7);
+};