matterviz 0.3.4 → 0.3.6

package/tests/node-io.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test, vi } from 'vitest'
+import { stream_file_to_buffer } from '../src/node-io'
+
+const mock_vscode = vi.hoisted(() => ({
+  Uri: {
+    file: vi.fn((file_path: string) => ({ fsPath: file_path })),
+  },
+  workspace: {
+    fs: {
+      stat: vi.fn(),
+      readFile: vi.fn(),
+    },
+  },
+}))
+
+vi.mock(`vscode`, () => mock_vscode)
+
+describe(`stream_file_to_buffer`, () => {
+  test(`returns the underlying buffer without copying for full-span file bytes`, async () => {
+    const file_bytes = new Uint8Array([1, 2, 3])
+    mock_vscode.workspace.fs.stat.mockResolvedValue({ size: file_bytes.byteLength })
+    mock_vscode.workspace.fs.readFile.mockResolvedValue(file_bytes)
+
+    const result = await stream_file_to_buffer(`/tmp/full-span.bin`)
+
+    expect(result).toBe(file_bytes.buffer)
+  })
+
+  test(`returns exact bytes when VS Code returns an ArrayBuffer view`, async () => {
+    const parent_buffer = new Uint8Array([0, 1, 2, 3, 4, 5])
+    const file_bytes = parent_buffer.subarray(2, 5)
+    mock_vscode.workspace.fs.stat.mockResolvedValue({ size: file_bytes.byteLength })
+    mock_vscode.workspace.fs.readFile.mockResolvedValue(file_bytes)
+
+    const result = await stream_file_to_buffer(`/tmp/view-backed.bin`)
+
+    expect(Array.from(new Uint8Array(result))).toEqual([2, 3, 4])
+  })
+})

package/tests/plot-utils.test.ts

@@ -0,0 +1,302 @@
+import { describe, expect, test } from 'vitest'
+import {
+  build_bar_series,
+  build_histogram_series,
+  build_scatter3d_series,
+  build_scatter_series,
+  col_keys,
+  extract_columns,
+  suggest_mapping,
+} from '../src/webview/plot-utils'
+
+describe(`extract_columns`, () => {
+  test(`column-based: extracts numeric and string columns`, () => {
+    const data = { x: [1, 2, 3], y: [4, 5, 6], label: [`a`, `b`, `c`] }
+    const cols = extract_columns(data)
+    expect(cols.size).toBe(3)
+    expect(cols.get(`x`)?.type).toBe(`numeric`)
+    expect(cols.get(`y`)?.type).toBe(`numeric`)
+    expect(cols.get(`label`)?.type).toBe(`string`)
+    expect(cols.get(`x`)?.values).toEqual([1, 2, 3])
+  })
+
+  test(`column-based: skips columns with different lengths`, () => {
+    const data = { x: [1, 2, 3], y: [4, 5], label: [`a`, `b`, `c`] }
+    const cols = extract_columns(data)
+    expect(cols.has(`y`)).toBe(false)
+    expect(cols.size).toBe(2)
+  })
+
+  test(`row-based: extracts from array of objects`, () => {
+    const data = [
+      { energy: -5.4, volume: 20.5, name: `Si` },
+      { energy: -4.6, volume: 22.7, name: `Ge` },
+      { energy: -7.4, volume: 11.2, name: `C` },
+    ]
+    const cols = extract_columns(data)
+    expect(cols.size).toBe(3)
+    expect(cols.get(`energy`)?.type).toBe(`numeric`)
+    expect(cols.get(`volume`)?.type).toBe(`numeric`)
+    expect(cols.get(`name`)?.type).toBe(`string`)
+    expect(cols.get(`energy`)?.values).toEqual([-5.4, -4.6, -7.4])
+  })
+
+  test.each([null, `hello`, 42, [null, { x: 1 }]])(
+    `returns empty map for non-tabular data: %j`,
+    (data) => expect(extract_columns(data).size).toBe(0),
+  )
+
+  test(`single-column column-based data produces one column for histogram`, () => {
+    const cols = extract_columns({ energy: [1, 2, 3] })
+    expect(cols.size).toBe(1)
+    expect(cols.get(`energy`)?.type).toBe(`numeric`)
+  })
+
+  test(`handles null values in columns`, () => {
+    const data = { x: [1, null, 3], y: [4, 5, null] }
+    const cols = extract_columns(data)
+    expect(cols.get(`x`)?.n_valid).toBe(2)
+    expect(cols.get(`y`)?.n_valid).toBe(2)
+  })
+
+  test(`classifies mixed-type columns when below 80% threshold`, () => {
+    const data = [{ val: 1 }, { val: `two` }, { val: 3 }, { val: `four` }, { val: 5 }]
+    const cols = extract_columns(data)
+    expect(cols.get(`val`)?.type).toBe(`mixed`)
+  })
+
+  test(`classifies as numeric when >= 80% are numbers`, () => {
+    const data = { val: [1, 2, 3, 4, `outlier`], idx: [0, 1, 2, 3, 4] }
+    const cols = extract_columns(data)
+    expect(cols.get(`val`)?.type).toBe(`numeric`)
+    expect(cols.get(`val`)?.n_valid).toBe(5)
+  })
+
+  test(`classifies all-null column as mixed with n_valid=0`, () => {
+    const data = { x: [1, 2], y: [null, undefined] }
+    const cols = extract_columns(data)
+    expect(cols.get(`y`)?.type).toBe(`mixed`)
+    expect(cols.get(`y`)?.n_valid).toBe(0)
+  })
+})
+
+describe(`col_keys`, () => {
+  test(`filters columns by type`, () => {
+    const cols = extract_columns({ x: [1, 2], name: [`a`, `b`], y: [3, 4] })
+    expect(col_keys(cols, `numeric`)).toEqual([`x`, `y`])
+    expect(col_keys(cols, `string`)).toEqual([`name`])
+    expect(col_keys(cols, `mixed`)).toEqual([])
+  })
+})
+
+describe(`suggest_mapping`, () => {
+  test(`assigns x and y to first two numeric columns`, () => {
+    const cols = extract_columns({ a: [1, 2], b: [3, 4], c: [5, 6] })
+    const { plot_type, mapping } = suggest_mapping(cols)
+    expect(plot_type).toBe(`scatter`)
+    expect(mapping.x).toBe(`a`)
+    expect(mapping.y).toBe(`b`)
+    expect(mapping.color).toBe(`c`)
+  })
+
+  test(`prefers well-known names for x/y`, () => {
+    const cols = extract_columns({ energy: [1, 2], time: [3, 4], force: [5, 6] })
+    const { mapping } = suggest_mapping(cols)
+    expect(mapping.x).toBe(`time`)
+    expect(mapping.y).toBe(`energy`)
+  })
+
+  test.each([
+    [
+      `bar (string + 2 numeric)`,
+      `bar`,
+      `material`,
+      {
+        material: [`Si`, `Ge`, `C`],
+        energy: [-5.4, -4.6, -7.4],
+        volume: [20.5, 22.7, 11.2],
+      },
+    ],
+    [
+      `bar (string + 1 numeric)`,
+      `bar`,
+      `name`,
+      {
+        name: [`Si`, `Ge`, `C`],
+        energy: [-5.4, -4.6, -7.4],
+      },
+    ],
+    [
+      `scatter3d (x/y/z columns)`,
+      `scatter3d`,
+      `x`,
+      {
+        x: [1, 2],
+        y: [3, 4],
+        z: [5, 6],
+      },
+    ],
+  ] as const)(`suggests %s`, (_, expected_type, expected_x, data) => {
+    const { plot_type, mapping } = suggest_mapping(extract_columns(data))
+    expect(plot_type).toBe(expected_type)
+    expect(mapping.x).toBe(expected_x)
+  })
+
+  test(`assigns color to first unassigned numeric column`, () => {
+    const cols = extract_columns({ x: [1, 2], y: [3, 4], temp: [5, 6], sz: [7, 8] })
+    const { mapping } = suggest_mapping(cols)
+    expect(mapping.color).toBe(`temp`)
+  })
+
+  test(`single numeric column falls back to histogram`, () => {
+    const cols = new Map([
+      [
+        `a`,
+        {
+          values: [1, 2, 3],
+          type: `numeric` as const,
+          n_valid: 3,
+        },
+      ],
+    ])
+    const { plot_type, mapping } = suggest_mapping(cols)
+    expect(plot_type).toBe(`histogram`)
+    expect(mapping.x).toBe(`a`)
+  })
+
+  test(`empty columns map falls back to table`, () => {
+    const { plot_type, mapping } = suggest_mapping(new Map())
+    expect(plot_type).toBe(`table`)
+    expect(mapping.x).toBeUndefined()
+    expect(mapping.y).toBeUndefined()
+  })
+})
+
+describe(`build_scatter_series`, () => {
+  test(`builds series from columns`, () => {
+    const cols = extract_columns({ x: [1, 2, 3], y: [4, 5, 6] })
+    const series = build_scatter_series(cols, { x: `x`, y: `y` })
+    expect(series.x).toEqual([1, 2, 3])
+    expect(series.y).toEqual([4, 5, 6])
+  })
+
+  test.each([
+    [`color`, { x: `x`, y: `y`, color: `extra` }, `color_values`],
+    [`size`, { x: `x`, y: `y`, size: `extra` }, `size_values`],
+  ] as const)(`includes %s_values when mapped`, (_, axis_mapping, prop) => {
+    const cols = extract_columns({ x: [1, 2], y: [3, 4], extra: [5, 6] })
+    const series = build_scatter_series(cols, axis_mapping)
+    expect(series[prop]).toEqual([5, 6])
+  })
+
+  test(`filters out points with non-finite x or y`, () => {
+    const cols = extract_columns({ x: [1, null, 3], y: [4, 5, 6], c: [10, 20, 30] })
+    const series = build_scatter_series(cols, { x: `x`, y: `y`, color: `c` })
+    expect(series.x).toEqual([1, 3])
+    expect(series.y).toEqual([4, 6])
+    expect(series.color_values).toEqual([10, 30])
+  })
+})
+
+describe(`build_scatter3d_series`, () => {
+  test(`builds 3d series`, () => {
+    const cols = extract_columns({ x: [1, 2], y: [3, 4], z: [5, 6] })
+    const series = build_scatter3d_series(cols, { x: `x`, y: `y`, z: `z` })
+    expect(series.x).toEqual([1, 2])
+    expect(series.y).toEqual([3, 4])
+    expect(series.z).toEqual([5, 6])
+  })
+
+  test(`includes color and size values when mapped`, () => {
+    const cols = extract_columns({
+      x: [1, 2],
+      y: [3, 4],
+      z: [5, 6],
+      c: [7, 8],
+      sz: [9, 10],
+    })
+    const series = build_scatter3d_series(cols, {
+      x: `x`,
+      y: `y`,
+      z: `z`,
+      color: `c`,
+      size: `sz`,
+    })
+    expect(series.color_values).toEqual([7, 8])
+    expect(series.size_values).toEqual([9, 10])
+  })
+
+  test(`filters non-finite x/y/z with aligned color and size`, () => {
+    const cols = extract_columns({
+      x: [1, null, 3, 4],
+      y: [5, 6, 7, 8],
+      z: [9, 10, null, 12],
+      c: [100, 200, 300, 400],
+      sz: [10, 20, 30, 40],
+    })
+    const series = build_scatter3d_series(cols, {
+      x: `x`,
+      y: `y`,
+      z: `z`,
+      color: `c`,
+      size: `sz`,
+    })
+    expect(series.x).toEqual([1, 4])
+    expect(series.y).toEqual([5, 8])
+    expect(series.z).toEqual([9, 12])
+    expect(series.color_values).toEqual([100, 400])
+    expect(series.size_values).toEqual([10, 40])
+  })
+})
+
+describe(`build_bar_series`, () => {
+  test(`builds bar series with string x`, () => {
+    const cols = extract_columns({
+      material: [`Si`, `Ge`],
+      energy: [-5.4, -4.6],
+    })
+    const series = build_bar_series(cols, { x: `material`, y: `energy` })
+    expect(series.x).toEqual([`Si`, `Ge`])
+    expect(series.y).toEqual([-5.4, -4.6])
+  })
+})
+
+describe(`build functions return empty on missing columns`, () => {
+  const cols = extract_columns({ x: [1, 2], y: [3, 4] })
+
+  test.each([
+    [`scatter`, () => build_scatter_series(cols, { x: `x`, y: `missing` })],
+    [`scatter3d`, () => build_scatter3d_series(cols, { x: `x`, y: `y`, z: `missing` })],
+    [`bar`, () => build_bar_series(cols, { x: `missing`, y: `y` })],
+    [`histogram`, () => build_histogram_series(cols, { y: `missing` })],
+  ])(`%s returns empty arrays`, (name, build) => {
+    const series = build()
+    expect(series.x).toEqual([])
+    expect(series.y).toEqual([])
+    if (name === `scatter3d`) expect((series as unknown as { z: number[] }).z).toEqual([])
+  })
+})
+
+describe(`build_histogram_series`, () => {
+  test(`builds histogram from y column`, () => {
+    const cols = extract_columns({ values: [1.5, 2.3, 3.1, 4.7], idx: [0, 1, 2, 3] })
+    const series = build_histogram_series(cols, { y: `values` })
+    expect(series.y).toEqual([1.5, 2.3, 3.1, 4.7])
+    expect(series.x).toEqual([0, 1, 2, 3])
+  })
+
+  test(`falls back to x mapping when y is absent`, () => {
+    const cols = extract_columns({ energy: [1.5, 2.3, 3.1], idx: [0, 1, 2] })
+    const series = build_histogram_series(cols, { x: `energy` })
+    expect(series.y).toEqual([1.5, 2.3, 3.1])
+  })
+
+  test(`filters non-numeric values`, () => {
+    const cols = extract_columns({
+      values: [1, null, 3, `bad`, 5, NaN],
+      idx: [0, 1, 2, 3, 4, 5],
+    })
+    const series = build_histogram_series(cols, { y: `values` })
+    expect(series.y).toEqual([1, 3, 5])
+  })
+})

package/tests/vite-plugin-json-gz.test.ts

@@ -0,0 +1,114 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { gunzipSync, gzipSync } from 'node:zlib'
+import { describe, expect, test } from 'vitest'
+import { vite_plugin_json_gz } from '../vite-plugin-json-gz'
+
+const fixture_path = `${import.meta.dirname}/../test-fixtures/all-viz-types.json.gz`
+const expected_data = JSON.parse(gunzipSync(readFileSync(fixture_path)).toString(`utf-8`))
+
+function make_plugin(command: `build` | `serve` = `serve`) {
+  const plugin = vite_plugin_json_gz()
+  const config_resolved = plugin.configResolved as (cfg: { command: string }) => void
+  config_resolved.call({}, { command })
+  return plugin.load as (this: { error: (msg: string) => void }, id: string) => unknown
+}
+
+describe(`vite_plugin_json_gz`, () => {
+  test.each([`foo.json`, `bar.ts`, `data.gz`, `${fixture_path}?url`, `${fixture_path}?raw`])(
+    `returns null for non-matching id: %s`,
+    (id) => {
+      const load = make_plugin()
+      expect(load.call({ error: () => {} }, id)).toBeNull()
+    },
+  )
+
+  test(`dev/serve mode returns JS module matching decompressed content`, () => {
+    const load = make_plugin(`serve`)
+    const result = load.call({ error: () => {} }, fixture_path) as string
+    expect(result).toMatch(/^export default /)
+    expect(JSON.parse(result.replace(/^export default /, ``))).toEqual(expected_data)
+  })
+
+  test(`build mode returns raw JSON with moduleType:'json'`, () => {
+    const load = make_plugin(`build`)
+    const result = load.call({ error: () => {} }, fixture_path) as {
+      code: string
+      moduleType: string
+    }
+    expect(result.moduleType).toBe(`json`)
+    expect(JSON.parse(result.code)).toEqual(expected_data)
+  })
+
+  test.each([
+    [`missing file`, `/nonexistent/file.json.gz`],
+    [
+      `invalid JSON`,
+      (() => {
+        const path = join(tmpdir(), `bad-json-${Date.now()}.json.gz`)
+        writeFileSync(path, gzipSync(`{not valid json!!!`))
+        return path
+      })(),
+    ],
+  ])(`calls this.error for %s`, (_label, path) => {
+    const load = make_plugin()
+    const errors: string[] = []
+    load.call({ error: (msg: string) => errors.push(msg) }, path)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain(`Failed to load`)
+  })
+})
+
+// The inline plugins in vite.config.ts strip query params before checking extensions,
+// so they need explicit ?url skip guards — the bug that broke /convex-hull/chempot-diagram.
+const strip_query = (path: string): string => path.replace(/\?.*$/, ``)
+
+describe(`inline vite-plugin-json-gz query handling`, () => {
+  const should_handle = (source: string): boolean => {
+    const clean = strip_query(source)
+    if (!clean.endsWith(`.json.gz`)) return false
+    if (source.includes(`raw`) || source.includes(`url`)) return false
+    return true
+  }
+
+  test.each([
+    [`bare .json.gz import`, `data.json.gz`, true],
+    [`?url import`, `data.json.gz?url`, false],
+    [`?raw import`, `data.json.gz?raw`, false],
+    [`non .json.gz`, `data.json`, false],
+    [`glob ?url import`, `/src/site/chempot-diagram/entries.json.gz?url`, false],
+    [`glob eager import`, `/src/site/phonons/data.json.gz`, true],
+  ])(`%s → handled: %s`, (_label, source, expected) => {
+    expect(should_handle(source)).toBe(expected)
+  })
+})
+
+describe(`inline vite-plugin-raw-text query handling`, () => {
+  const TEXT_EXT_RE = /\.(xyz|extxyz|cif|poscar|lammpstrj|yaml\.gz)$/
+
+  const should_handle = (source: string): boolean => {
+    if (source.includes(`url`)) return false
+    const clean = strip_query(source)
+    const is_raw_gz = clean.endsWith(`.json.gz`) && source.includes(`raw`)
+    return TEXT_EXT_RE.test(clean) || is_raw_gz
+  }
+
+  test.each([
+    [`bare .xyz`, `trajectory.xyz`, true],
+    [`?raw .xyz`, `trajectory.xyz?raw`, true],
+    [`?url .xyz`, `trajectory.xyz?url`, false],
+    [`bare .extxyz`, `atoms.extxyz`, true],
+    [`?url .extxyz`, `atoms.extxyz?url`, false],
+    [`bare .cif`, `structure.cif`, true],
+    [`?url .cif`, `structure.cif?url`, false],
+    [`bare .lammpstrj`, `dump.lammpstrj`, true],
+    [`?url .lammpstrj`, `dump.lammpstrj?url`, false],
+    [`?raw .json.gz`, `data.json.gz?raw`, true],
+    [`?url .json.gz`, `data.json.gz?url`, false],
+    [`non-text file`, `image.png`, false],
+    [`.json (no gz)`, `data.json`, false],
+  ])(`%s → handled: %s`, (_label, source, expected) => {
+    expect(should_handle(source)).toBe(expected)
+  })
+})

package/tests/vscode-mock.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from 'vite'
+
+export const mock_vscode = (): Plugin => ({
+  name: `vscode-mock`,
+  enforce: `pre`,
+  resolveId: (module_id) => (module_id === `vscode` ? `\0vscode-mock` : null),
+  load: (module_id) =>
+    module_id === `\0vscode-mock`
+      ? `
+export const __noop = () => undefined
+const __proxy = new Proxy(function(){}, { get: () => __proxy, apply: () => undefined, construct: () => ({}) })
+export const window = __proxy
+export const commands = __proxy
+export const workspace = __proxy
+export default { window, commands, workspace }
+`
+      : null,
+})

package/tests/webview.test.ts

@@ -0,0 +1,231 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { base64_to_array_buffer, setup_vscode_download } from '../src/webview/main'
+
+declare global {
+  // download function added by VSCode integration
+  var download: (content: string | Blob, filename: string, contentType: string) => void
+}
+
+describe(`Webview Integration - ASE Binary Trajectory Support`, () => {
+  test.each([
+    [`SGVsbG8gV29ybGQ=`, `Hello World`, 11], // Basic ASCII
+    [`QUJDREVGR0g=`, `ABCDEFGH`, 8], // Another ASCII
+    [``, ``, 0], // Empty string
+    [`QQ==`, `A`, 1], // Single character
+    [`QUI=`, `AB`, 2], // Two characters
+  ])(`base64_to_array_buffer: %s → %s (%i bytes)`, (base64, expected, byte_length) => {
+    const result = base64_to_array_buffer(base64)
+    expect(result).toBeInstanceOf(ArrayBuffer)
+    expect(result.byteLength).toBe(byte_length)
+    expect(new TextDecoder().decode(result)).toBe(expected)
+  })
+
+  test(`handles ASE trajectory file header correctly`, () => {
+    const ase_header = new Uint8Array([
+      0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d, 0x41, 0x53, 0x45, 0x2d, 0x54, 0x72, 0x61,
+      0x6a,
+    ])
+    const result = base64_to_array_buffer(btoa(String.fromCharCode(...ase_header)))
+    expect(result.byteLength).toBe(ase_header.length)
+    expect(new TextDecoder().decode(result.slice(0, 8))).toBe(`- of Ulm`)
+  })
+
+  test(`preserves byte order and handles performance`, () => {
+    const test_bytes = new Uint8Array([0x00, 0x01, 0x02, 0x03, 0xff, 0xfe, 0xfd, 0xfc])
+    const result = base64_to_array_buffer(btoa(String.fromCharCode(...test_bytes)))
+    expect(Array.from(new Uint8Array(result))).toEqual(Array.from(test_bytes))
+
+    const large_data = new Uint8Array(10000).fill(42)
+    const start = performance.now()
+    const large_result = base64_to_array_buffer(btoa(String.fromCharCode(...large_data)))
+    expect(performance.now() - start).toBeLessThan(100)
+    expect(large_result.byteLength).toBe(large_data.length)
+  })
+
+  test.each([1024, 8192, 32768])(
+    `handles typical ASE trajectory file size: %i bytes`,
+    (size) => {
+      const data = new Uint8Array(size)
+      for (let idx = 0; idx < size; idx++) data[idx] = idx % 256
+      const result = base64_to_array_buffer(btoa(String.fromCharCode(...data)))
+      const result_array = new Uint8Array(result)
+      expect(result.byteLength).toBe(size)
+      expect(result_array[0]).toBe(0)
+      expect(result_array[255]).toBe(255)
+      expect(result_array[size - 1]).toBe((size - 1) % 256)
+    },
+  )
+
+  test(`ASE trajectory file regression test - simulates VS Code extension flow`, () => {
+    const ase_data = new Uint8Array([
+      0x2d,
+      0x20,
+      0x6f,
+      0x66,
+      0x20,
+      0x55,
+      0x6c,
+      0x6d, // "- of Ulm"
+      0x41,
+      0x53,
+      0x45,
+      0x2d,
+      0x54,
+      0x72,
+      0x61,
+      0x6a,
+      0x65,
+      0x63,
+      0x74,
+      0x6f,
+      0x72,
+      0x79,
+      0x00,
+      0x00, // "ASE-Trajectory"
+      ...Array(176).fill(0), // Mock trajectory data
+    ])
+    const result = base64_to_array_buffer(btoa(String.fromCharCode(...ase_data)))
+    const result_array = new Uint8Array(result)
+    expect(result.byteLength).toBe(ase_data.length)
+    expect(new TextDecoder().decode(result_array.slice(0, 8))).toBe(`- of Ulm`)
+    expect(new TextDecoder().decode(result_array.slice(8, 24)).replace(/\0/g, ``)).toBe(
+      `ASE-Trajectory`,
+    )
+  })
+})
+
+describe(`VSCode Download Integration`, () => {
+  afterEach(vi.useRealTimers)
+
+  test(`sets up global download override when VSCode API is available`, async () => {
+    vi.resetModules() // Reset modules to clear cached vscode_api variable in webview/main.ts
+    const mock_post_message = vi.fn()
+    globalThis.acquireVsCodeApi = vi.fn(() => ({
+      postMessage: mock_post_message,
+      setState: vi.fn(),
+      getState: vi.fn(),
+    }))
+    const { setup_vscode_download } = await import(`../src/webview/main`)
+    setup_vscode_download()
+    expect(typeof globalThis.download).toBe(`function`)
+    globalThis.download(`test content`, `test.json`, `application/json`)
+    expect(mock_post_message).toHaveBeenCalledWith({
+      command: `saveAs`,
+      content: `test content`,
+      filename: `test.json`,
+      is_binary: false,
+    })
+  })
+
+  test(`handles binary data (PNG) correctly`, async () => {
+    vi.useFakeTimers()
+    vi.resetModules()
+    let load_listener: (() => void) | undefined
+    let result: string | null = null
+
+    globalThis.FileReader = vi.fn(function (this: FileReader) {
+      this.readAsDataURL = vi.fn((blob: Blob) => {
+        setTimeout(async () => {
+          // Read actual Blob content for end-to-end correctness
+          const array_buffer = await blob.arrayBuffer()
+          const uint8_array = new Uint8Array(array_buffer)
+          const binary_string = String.fromCharCode(...uint8_array)
+          const base64_string = btoa(binary_string)
+          result = `data:${blob.type};base64,${base64_string}`
+          load_listener?.()
+        }, 0)
+      })
+      this.addEventListener = vi.fn((type: string, listener: EventListener) => {
+        if (type === `load`) load_listener = listener as () => void
+      })
+      Object.defineProperty(this, `result`, { get: () => result })
+    }) as unknown as typeof FileReader
+
+    const mock_post_message = vi.fn()
+    globalThis.acquireVsCodeApi = vi.fn(() => ({
+      postMessage: mock_post_message,
+      setState: vi.fn(),
+      getState: vi.fn(),
+    }))
+    const { setup_vscode_download } = await import(`../src/webview/main`)
+    setup_vscode_download()
+    globalThis.download(
+      new Blob([`fake png data`], { type: `image/png` }),
+      `structure.png`,
+      `image/png`,
+    )
+    await vi.runAllTimersAsync()
+
+    expect(mock_post_message).toHaveBeenCalledWith({
+      command: `saveAs`,
+      content: `data:image/png;base64,ZmFrZSBwbmcgZGF0YQ==`,
+      filename: `structure.png`,
+      is_binary: true,
+    })
+  })
+
+  test.each([``, `   `])(`rejects invalid filename: "%s"`, (filename) => {
+    vi.resetModules()
+    const mock_post_message = vi.fn()
+    globalThis.acquireVsCodeApi = vi.fn(() => ({
+      postMessage: mock_post_message,
+      setState: vi.fn(),
+      getState: vi.fn(),
+    }))
+    setup_vscode_download()
+
+    globalThis.download(`test content`, filename, `application/json`)
+    expect(mock_post_message).not.toHaveBeenCalled()
+  })
+
+  test(`handles FileReader errors for binary data`, async () => {
+    vi.useFakeTimers()
+    vi.resetModules()
+    let error_listener: (() => void) | undefined
+
+    globalThis.FileReader = vi.fn(function (this: FileReader) {
+      this.readAsDataURL = vi.fn(() => setTimeout(() => error_listener?.(), 0))
+      this.addEventListener = vi.fn((type: string, listener: EventListener) => {
+        if (type === `error`) error_listener = listener as () => void
+      })
+    }) as unknown as typeof FileReader
+
+    const mock_post_message = vi.fn()
+    globalThis.acquireVsCodeApi = vi.fn(() => ({
+      postMessage: mock_post_message,
+      setState: vi.fn(),
+      getState: vi.fn(),
+    }))
+    const { setup_vscode_download } = await import(`../src/webview/main`)
+    setup_vscode_download()
+    globalThis.download(new Blob([`data`]), `test.png`, `image/png`)
+    await vi.runAllTimersAsync()
+
+    expect(mock_post_message).toHaveBeenCalledWith({
+      command: `error`,
+      text: `Failed to read binary data for download`,
+    })
+  })
+
+  test(`handles general exceptions during download`, async () => {
+    vi.resetModules()
+    const mock_post_message = vi.fn()
+    globalThis.acquireVsCodeApi = vi.fn(() => ({
+      postMessage: mock_post_message,
+      setState: vi.fn(),
+      getState: vi.fn(),
+    }))
+    const { setup_vscode_download } = await import(`../src/webview/main`)
+    setup_vscode_download()
+
+    mock_post_message.mockImplementationOnce(() => {
+      throw new Error(`Network error`)
+    })
+
+    globalThis.download(`test content`, `test.json`, `application/json`)
+    expect(mock_post_message).toHaveBeenCalledWith({
+      command: `error`,
+      text: `Download failed: Error: Network error`,
+    })
+  })
+})