matterviz 0.3.5 → 0.3.6

package/dist/src/lib/index.ts

@@ -0,0 +1,61 @@
+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 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/src/lib/io/decompress.ts

@@ -0,0 +1,92 @@
+import type { COMPRESSION_EXTENSIONS } from '$lib/constants'
+import { COMPRESSION_EXTENSIONS_REGEX, COMPRESSION_FORMATS } from '$lib/constants'
+
+export type CompressionFormat = keyof typeof COMPRESSION_FORMATS
+export type CompressionExtension = (typeof COMPRESSION_EXTENSIONS)[number]
+
+export function detect_compression_format(filename: string): CompressionFormat | null {
+  const lower = filename.toLowerCase()
+  for (const [format, extensions] of Object.entries(COMPRESSION_FORMATS)) {
+    if (extensions.some((ext) => lower.endsWith(ext))) return format as CompressionFormat
+  }
+  return null
+}
+
+// Decompress data and return as text string
+export async function decompress_data(
+  data: ArrayBuffer | ReadableStream<Uint8Array> | null,
+  format: CompressionFormat,
+): Promise<string> {
+  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: ArrayBuffer | ReadableStream<Uint8Array> | null,
+  format: CompressionFormat,
+): Promise<ArrayBuffer> {
+  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: File): Promise<{ content: string; filename: string }> {
+  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
+          if (!result) 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(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/src/lib/io/export.ts

@@ -0,0 +1,385 @@
+import { download } from '$lib/io/fetch'
+import type { AnyStructure } from '$lib/structure'
+import { create_structure_filename } from '$lib/structure/export'
+import { type Camera, type Scene, Vector2, type WebGLRenderer } from 'three'
+
+function is_webgl_renderer_like(value: unknown): value is WebGLRenderer {
+  if (typeof value !== `object` || !value) return false
+  const renderer_obj = value as Record<string, unknown>
+  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: HTMLCanvasElement): WebGLRenderer | undefined {
+  const renderer_val = (canvas as unknown as Record<string, unknown>)[`__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: HTMLCanvasElement,
+  png_dpi = 150,
+  scene: Scene | null = null,
+  camera: Camera | null = null,
+): Promise<Blob> {
+  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(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(error)
+    }
+  })
+}
+
+// Export structure as PNG image from canvas (triggers browser download)
+export function export_canvas_as_png(
+  canvas: HTMLCanvasElement | null,
+  structure_or_filename: AnyStructure | string | undefined,
+  png_dpi = 150,
+  scene: Scene | null = null,
+  camera: Camera | null = null,
+): void {
+  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: SVGElement) {
+  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`)
+}
+
+// Serialize an SVG element to a standalone SVG string with proper XML headers.
+// Clones the element to avoid mutation, sets font-family/xmlns, and
+// prepends XML declaration + SVG DOCTYPE. Returns a complete SVG document string
+// suitable for saving to file or further processing.
+export function svg_to_svg_string(svg_element: SVGElement): string {
+  const cloned_svg = svg_element.cloneNode(true) as SVGElement
+
+  set_svg_font_family(cloned_svg)
+  if (!cloned_svg.hasAttribute(`xmlns`)) {
+    cloned_svg.setAttribute(`xmlns`, `http://www.w3.org/2000/svg`)
+  }
+
+  const svg_string = new XMLSerializer().serializeToString(cloned_svg)
+  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: SVGElement | null, filename: string): void {
+  if (!svg_element) {
+    console.warn(`SVG element not found for export`)
+    return
+  }
+  try {
+    const svg_content = svg_to_svg_string(svg_element)
+    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: SVGElement, png_dpi = 150): Promise<Blob> {
+  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 cloned_svg = svg_element.cloneNode(true) as SVGElement
+  set_svg_font_family(cloned_svg)
+
+  const serialized = new XMLSerializer().serializeToString(cloned_svg)
+  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(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: SVGElement | null,
+  filename: string,
+  png_dpi = 150,
+): void {
+  if (!svg_element) {
+    console.warn(`SVG element not found for PNG export`)
+    return
+  }
+  svg_to_png_blob(svg_element, png_dpi)
+    .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: string): string {
+  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: 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> {
+  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: number | undefined
+  let orig_size: Vector2 | undefined
+
+  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: Blob[] = []
+  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] as MediaStreamTrack & {
+    requestFrame?: () => void
+  }
+
+  // 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(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(error)
+      }
+    }
+  })
+}

package/dist/src/lib/io/fetch.ts

@@ -0,0 +1,46 @@
+import { decompress_data } from '$lib/io/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: Record<string, string | number | undefined>): string =>
+  new URLSearchParams(
+    Object.entries(params)
+      .filter(([, val]) => val !== `` && val !== undefined)
+      .map(([key, val]) => [key, String(val)]),
+  ).toString()
+
+export async function fetch_zipped<T>(url: string, { unzip = true } = {}): Promise<T | null> {
+  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()) as T
+  return JSON.parse(await decompress_data(response.body, `gzip`))
+}
+
+// Original download implementation
+function default_download(data: string | Blob, filename: string, type: string) {
+  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
+  document.body.appendChild(link)
+  link.click()
+  link.remove()
+  URL.revokeObjectURL(url)
+}
+
+// Function to download data to a file - checks for global override first
+export function download(data: string | Blob, filename: string, type: string): void {
+  // Check if there's a global download override (used by VSCode extension)
+  const global_download = (globalThis as Record<string, unknown>).download
+  if (typeof global_download === `function` && global_download !== download) {
+    return (global_download as typeof download)(data, filename, type)
+  }
+
+  // Use default browser download
+  return default_download(data, filename, type)
+}

package/dist/src/lib/io/file-drop.ts

@@ -0,0 +1,51 @@
+// Shared file-drop handler composable for drag-and-drop file loading.
+import { decompress_file } from './decompress'
+import { handle_url_drop } from './url-drop'
+
+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
+}
+
+// Handles URL drops (from FilePicker), direct file drops with decompression,
+// loading state, and error reporting.
+export function create_file_drop_handler(
+  opts: FileDropOptions,
+): (event: DragEvent) => Promise<void> {
+  return async (event: DragEvent) => {
+    event.preventDefault()
+    if (!opts.allow()) return
+
+    opts.set_loading?.(true)
+
+    let drop_filename = ``
+    try {
+      let url_error: string | undefined
+      const handled = await handle_url_drop(event, opts.on_drop).catch((exc) => {
+        url_error = exc instanceof Error ? exc.message : String(exc)
+        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 = exc instanceof Error ? exc.message : String(exc)
+      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/src/lib/io/index.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/src/lib/io/is-binary.ts

@@ -0,0 +1,24 @@
+// Simplified binary detection
+export const is_binary = (content: string): boolean => {
+  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
+  )
+}

package/dist/src/lib/io/types.ts

@@ -0,0 +1,8 @@
+export interface FileInfo {
+  name: string
+  url: string
+  label?: string // human-readable display name (falls back to name)
+  type?: string
+  category?: string
+  category_icon?: string
+}