matterviz 0.3.7 → 0.4.1

package/dist/isosurface/parse.js

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

package/dist/isosurface/slice.js

@@ -32,9 +32,10 @@ export function trilinear_interpolate(grid, fx, fy, fz, periodic) {
     const x1 = periodic ? (x0 + 1) % nx : Math.min(x0 + 1, nx - 1);
     const y1 = periodic ? (y0 + 1) % ny : Math.min(y0 + 1, ny - 1);
     const z1 = periodic ? (z0 + 1) % nz : Math.min(z0 + 1, nz - 1);
-    const xd = gx - Math.floor(gx);
-    const yd = gy - Math.floor(gy);
-    const zd = gz - Math.floor(gz);
+    // deltas from clamped lower index (non-periodic x0 clamps to nx-2 so floor(gx) may != x0)
+    const xd = periodic ? gx - Math.floor(gx) : gx - x0;
+    const yd = periodic ? gy - Math.floor(gy) : gy - y0;
+    const zd = periodic ? gz - Math.floor(gz) : gz - z0;
     // 8-point interpolation
     const c000 = grid[x0][y0][z0];
     const c001 = grid[x0][y0][z1];
@@ -71,7 +72,7 @@ export function sample_hkl_slice(volume, miller_indices, distance, n_points) {
     ];
     if (Math.hypot(...plane_normal) < 1e-12)
         return null; // degenerate normal
-    const unit_normal = math.normalize_vec3(plane_normal);
+    const unit_normal = math.normalize_vec(plane_normal);
     // In-plane basis vectors
     const [u_vec, v_vec] = math.compute_in_plane_basis(unit_normal);
     const cart_to_frac = math.create_cart_to_frac(lattice);

package/dist/isosurface/types.js

@@ -13,7 +13,7 @@ export const LAYER_COLORS = [
 // Compute min/max/abs_max/mean of a 3D grid.
 // Prefer using the precomputed `data_range` field on VolumetricData when available.
 export function grid_data_range(grid) {
-    if (!grid.length || !grid[0]?.length || !grid[0][0]?.length) {
+    if (grid.length === 0 || !grid[0]?.length || !grid[0][0]?.length) {
         return { min: 0, max: 0, abs_max: 0, mean: 0 };
     }
     let [min_val, max_val] = [Infinity, -Infinity];

package/dist/keyboard.d.ts

@@ -0,0 +1,3 @@
+export type KeydownHandler = (event: KeyboardEvent) => boolean;
+export declare const handle_and_prevent: (handle: KeydownHandler) => (event: KeyboardEvent) => void;
+export declare const forward_window_keydown: (is_hovered: () => boolean, handle: KeydownHandler) => (event: KeyboardEvent) => void;

package/dist/keyboard.js

@@ -0,0 +1,23 @@
+// Shared helpers for wiring viewer keyboard shortcuts consistently across
+// components (Structure, Trajectory, ...). A handler returns `true` when it
+// handled the event, so the browser default is suppressed in exactly one place
+// instead of scattered `preventDefault()` calls.
+// Wrap a handler for an element-level `onkeydown` binding: run it and suppress
+// the browser default (page scroll, find, ...) when it reports it handled the key.
+export const handle_and_prevent = (handle) => (event) => {
+    if (handle(event))
+        event.preventDefault();
+};
+// Wrap a handler for a `<svelte:window onkeydown>` binding: forward keydowns to a
+// viewer only while it's hovered and focus is on <body>. This lets shortcuts work
+// without first clicking the viewer, while keeping multiple viewers on one page
+// from all responding and never hijacking keys from a focused input/pane.
+// Suppresses the browser default when the handler reports it handled the key.
+export const forward_window_keydown = (is_hovered, handle) => {
+    const run = handle_and_prevent(handle);
+    return (event) => {
+        const active = document.activeElement;
+        if (is_hovered() && (!active || active === document.body))
+            run(event);
+    };
+};

package/dist/labels.d.ts

@@ -11,7 +11,7 @@ export declare const ELEM_PROPERTY_LABELS: Partial<Record<keyof ChemicalElement,
 export declare const ELEM_HEATMAP_KEYS: (keyof ChemicalElement)[];
 export declare const ELEM_HEATMAP_LABELS: Partial<Record<string, keyof ChemicalElement>>;
 export declare const DEFAULT_FMT: [string, string];
-export declare const FRACTION_GLYPHS: ReadonlyArray<readonly [number, string]>;
+export declare const FRACTION_GLYPHS: readonly (readonly [number, string])[];
 export declare const format_num: (num: number, fmt?: string | number) => string;
 export declare const format_vec3: (vec: Readonly<Vec3>, fmt_spec?: string) => string;
 export declare const format_bytes: (bytes?: number) => string;

package/dist/labels.js

@@ -5,7 +5,7 @@ const is_d3_symbol_name = (name) => Object.hasOwn(d3_symbols, `symbol${name}`);
 function name_for_symbol(sym) {
     for (const [key, symbol] of Object.entries(d3_symbols)) {
         if (symbol === sym && /^symbol[A-Z]/.test(key)) {
-            const name = key.substring(6);
+            const name = key.slice(6);
             if (is_d3_symbol_name(name))
                 return name;
         }
@@ -16,7 +16,7 @@ export const symbol_names = [
     ...new Set([...d3_symbols.symbolsFill, ...d3_symbols.symbolsStroke]),
 ]
     .map(name_for_symbol)
-    .filter((n) => n !== null);
+    .filter((name) => name !== null);
 export const symbol_map = Object.fromEntries(
 // Symbol lookup from d3-shape
 symbol_names.map((name) => [name, d3_symbols[`symbol${name}`]]));
@@ -34,7 +34,7 @@ export function format_value(value, formatter) {
     if (Number.isNaN(value))
         return `NaN`;
     // Format and normalize unicode minus
-    const formatted = format(formatter)(value).replace(/−/g, `-`);
+    const formatted = format(formatter)(value).replaceAll('−', `-`);
     // Handle percentage formatting - remove trailing zeros
     if (formatter.includes(`%`)) {
         return formatted.includes(`.`)
@@ -157,9 +157,10 @@ export function parse_si_float(value) {
     if (typeof value !== `string`)
         return value;
     // Remove whitespace and commas
-    const cleaned = value.trim().replace(/(\d),(\d)/g, `$1$2`);
-    // Check if the value is a SI-formatted number (e.g. "1.23k", "4.56M", "789µ", "12n")
-    const match = /^([-+]?\d*\.?\d+)\s*([yzafpnµmkMGTPEZY])?$/i.exec(cleaned);
+    const cleaned = value.trim().replaceAll(/(\d),(\d)/g, `$1$2`);
+    // SI-formatted number (e.g. "1.23k", "789µ"). Suffixes are case-sensitive (m=milli vs
+    // M=mega), so no `i` flag: mismatched-case suffixes return the string as-is.
+    const match = /^([-+]?\d*\.?\d+)\s*([yzafpnµmkMGTPEZY])?$/.exec(cleaned);
     if (match) {
         const [, num_part, suffix] = match;
         let multiplier = 1;
@@ -167,7 +168,7 @@ export function parse_si_float(value) {
             const suffixes = `yzafpnµm kMGTPEZY`;
             const index = suffixes.indexOf(suffix);
             if (index !== -1) {
-                multiplier = Math.pow(1000, index - 8);
+                multiplier = 1000 ** (index - 8);
             }
         }
         return parseFloat(num_part) * multiplier;
@@ -232,7 +233,7 @@ export const SUBSCRIPT_MAP = {
     '9': `₉`,
 };
 // replaces all signs and digits with their unicode superscript equivalent
-export const superscript_digits = (input) => input.replace(/[\d+-]/g, (match) => is_superscript_key(match) ? SUPERSCRIPT_MAP[match] : match);
+export const superscript_digits = (input) => input.replaceAll(/[\d+-]/g, (match) => is_superscript_key(match) ? SUPERSCRIPT_MAP[match] : match);
 // Trajectory property configuration: clean labels and units as structured data
 export const trajectory_property_config = {
     // Energy properties

package/dist/layout/FullscreenButton.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+  // Fullscreen toggle button (default Icon or custom snippet content), shared by the
+  // Trajectory/ChemPotDiagram3D/ConvexHull viewer chromes
+  import Icon from '../Icon.svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+  import { type FullscreenToggleProp, toggle_fullscreen } from './fullscreen'
+
+  let {
+    fullscreen = false,
+    toggle = true, // pass a snippet to render custom button content
+    wrapper = undefined, // element sent fullscreen
+    ...rest
+  }: HTMLButtonAttributes & {
+    fullscreen?: boolean
+    toggle?: FullscreenToggleProp
+    wrapper?: HTMLDivElement
+  } = $props()
+</script>
+
+<button
+  type="button"
+  onclick={() => toggle_fullscreen(wrapper)}
+  title="{fullscreen ? `Exit` : `Enter`} fullscreen"
+  aria-pressed={fullscreen}
+  {...rest}
+  class="fullscreen-btn {rest.class ?? ``}"
+>
+  {#if typeof toggle === `function`}
+    {@render toggle({ fullscreen })}
+  {:else}
+    <Icon icon={fullscreen ? `ExitFullscreen` : `Fullscreen`} />
+  {/if}
+</button>

package/dist/layout/FullscreenButton.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import { type FullscreenToggleProp } from './fullscreen';
+type $$ComponentProps = HTMLButtonAttributes & {
+    fullscreen?: boolean;
+    toggle?: FullscreenToggleProp;
+    wrapper?: HTMLDivElement;
+};
+declare const FullscreenButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type FullscreenButton = ReturnType<typeof FullscreenButton>;
+export default FullscreenButton;

package/dist/layout/FullscreenToggle.svelte

@@ -1,28 +1,22 @@
 <script lang="ts">
+  // Toggles a bindable `fullscreen` flag (plot components manage browser fullscreen
+  // themselves). For chromes that call the browser API directly, use FullscreenButton.
   import Icon from '../Icon.svelte'
   import type { HTMLButtonAttributes } from 'svelte/elements'
 
-  let {
-    fullscreen = $bindable(false),
-    class: className,
-    ...rest
-  }: HTMLButtonAttributes & {
+  let { fullscreen = $bindable(false), ...rest }: HTMLButtonAttributes & {
     fullscreen?: boolean
   } = $props()
 </script>
 
 <button
-  class="fullscreen-toggle {className ?? ``}"
+  {...rest}
+  class="fullscreen-toggle {rest.class ?? ``}"
   onclick={() => (fullscreen = !fullscreen)}
   aria-label={fullscreen ? `Exit fullscreen` : `Enter fullscreen`}
   type="button"
-  {...rest}
 >
-  <Icon
-    icon={fullscreen ? `ExitFullscreen` : `Fullscreen`}
-    width="18"
-    height="18"
-  />
+  <Icon icon="{fullscreen ? `Exit` : ``}Fullscreen" width="18" height="18" />
 </button>
 
 <style>
@@ -45,6 +39,6 @@
     background-color: color-mix(in srgb, currentColor 8%, transparent);
     opacity: var(--fullscreen-btn-hover-opacity, 1);
   }
-  /* Note: Parent component should add styles to show on parent hover */
-  /* Example: .parent:hover :global(.fullscreen-toggle) { opacity: 1; } */
+  /* Note: Parent component should add styles to show on parent hover
+  Example: .parent:hover :global(.fullscreen-toggle) { opacity: 1; } */
 </style>

package/dist/layout/PropertyFilter.svelte

@@ -46,7 +46,7 @@
 
   // Active when either bound is set (undefined = unbounded)
   let active = $derived(min_value !== undefined || max_value !== undefined)
-  let plain_label = $derived(label.replace(/<[^>]*>/g, ``))
+  let plain_label = $derived(label.replaceAll(/<[^>]*>/g, ``))
 
   let filtered_data = $derived.by(() => {
     if (!histogram_data) return []
@@ -69,7 +69,8 @@
   }
 
   function clear_filter(): void {
-    min_value = max_value = undefined
+    min_value = undefined
+    max_value = undefined
     onclear?.()
     onchange?.(undefined, undefined)
   }

package/dist/layout/SettingsSection.svelte

@@ -26,7 +26,7 @@
   // Create a deep copy of current_values on mount to use as reference values
   function deep_copy(obj: unknown): unknown {
     if (obj === null || typeof obj !== `object`) return obj
-    if (obj instanceof Date) return new Date(obj.getTime())
+    if (obj instanceof Date) return new Date(obj)
     if (obj instanceof RegExp) return new RegExp(obj)
     if (Array.isArray(obj)) {
       return obj.map((item) =>

package/dist/layout/ViewerChrome.svelte

@@ -0,0 +1,116 @@
+<script lang="ts">
+  import type { FullscreenToggleProp } from './fullscreen'
+  import type { ShowControlsState } from '../controls'
+  // Shared control-buttons row (filename chip + fullscreen toggle + snippet buttons/panes) for BrillouinZone/FermiSurface/Structure viewers; themed via neutral --viewer-* CSS vars
+  // TODO Trajectory.svelte still has its own control-buttons variant — migrate it here.
+  import type { Snippet } from 'svelte'
+  import { createAttachmentKey } from 'svelte/attachments'
+  import { tooltip } from 'svelte-multiselect/attachments'
+  import FullscreenButton from './FullscreenButton.svelte'
+
+  let {
+    controls_config,
+    filename = undefined,
+    fullscreen = false,
+    fullscreen_toggle = true,
+    fullscreen_btn_style = undefined,
+    wrapper = undefined,
+    style = undefined,
+    before = undefined,
+    children = undefined,
+  }: {
+    controls_config: ShowControlsState
+    filename?: string
+    fullscreen?: boolean
+    fullscreen_toggle?: FullscreenToggleProp
+    fullscreen_btn_style?: string
+    wrapper?: HTMLDivElement
+    style?: string // extra styles/CSS vars for the section (user config style wins)
+    before?: Snippet // rendered before filename/fullscreen (e.g. reset-camera button)
+    children?: Snippet // rendered after the fullscreen toggle (panes, controls, ...)
+  } = $props()
+
+  // Styled tooltip (reads the button's title attr), forwarded as a spreadable attachment
+  const tooltip_attachment = { [createAttachmentKey()]: tooltip() }
+</script>
+
+<section
+  class="control-buttons {controls_config.class}"
+  style={[style, controls_config.style].filter(Boolean).join(`; `)}
+>
+  {#if controls_config.mode !== `never`}
+    {@render before?.()}
+
+    {#if filename && controls_config.visible(`filename`)}
+      <span class="filename">{filename}</span>
+    {/if}
+
+    {#if fullscreen_toggle && controls_config.visible(`fullscreen`)}
+      <FullscreenButton
+        {fullscreen}
+        toggle={fullscreen_toggle}
+        {wrapper}
+        class="fullscreen-toggle"
+        style={fullscreen_btn_style}
+        {...tooltip_attachment}
+      />
+    {/if}
+
+    {@render children?.()}
+  {/if}
+</section>
+
+<style>
+  section.control-buttons {
+    position: absolute;
+    display: flex;
+    top: var(--viewer-buttons-top, var(--ctrl-btn-top, 1ex));
+    right: var(--viewer-buttons-right, var(--ctrl-btn-right, 1ex));
+    gap: var(--viewer-buttons-gap, clamp(6pt, 1cqmin, 9pt));
+    z-index: var(
+      --viewer-buttons-z-index,
+      var(--z-index-overlay-controls, 100000000)
+    );
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s ease;
+    align-items: var(--viewer-buttons-align, center);
+  }
+  /* Mode: always - controls always visible */
+  section.control-buttons.always-visible {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* Mode: hover - controls visible while the parent viewer is hovered/focused */
+  :global(.structure:hover) > section.control-buttons.hover-visible,
+  :global(.structure:focus-within) > section.control-buttons.hover-visible,
+  :global(.brillouin-zone:hover) > section.control-buttons.hover-visible,
+  :global(.brillouin-zone:focus-within) > section.control-buttons.hover-visible,
+  :global(.fermi-surface:hover) > section.control-buttons.hover-visible,
+  :global(.fermi-surface:focus-within) > section.control-buttons.hover-visible {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* Mode: never - stays hidden (default state, no additional CSS needed) */
+  section.control-buttons > :global(button) {
+    background-color: transparent;
+    display: flex;
+    padding: var(--viewer-buttons-btn-padding, 4px);
+    border-radius: var(--border-radius, 3pt);
+    font-size: clamp(0.85em, 2cqmin, 1.3em);
+  }
+  section.control-buttons :global(button:hover) {
+    background-color: color-mix(in srgb, currentColor 8%, transparent);
+  }
+  .filename {
+    font-family: monospace;
+    font-size: 0.9em;
+    background: var(--code-bg, rgba(0, 0, 0, 0.1));
+    padding: 3pt 6pt;
+    border-radius: 3pt;
+    max-width: 200px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>

package/dist/layout/ViewerChrome.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { FullscreenToggleProp } from './fullscreen';
+import type { ShowControlsState } from '../controls';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    controls_config: ShowControlsState;
+    filename?: string;
+    fullscreen?: boolean;
+    fullscreen_toggle?: FullscreenToggleProp;
+    fullscreen_btn_style?: string;
+    wrapper?: HTMLDivElement;
+    style?: string;
+    before?: Snippet;
+    children?: Snippet;
+};
+declare const ViewerChrome: import("svelte").Component<$$ComponentProps, {}, "">;
+type ViewerChrome = ReturnType<typeof ViewerChrome>;
+export default ViewerChrome;

package/dist/layout/fullscreen.d.ts

@@ -1,3 +1,7 @@
+import type { Snippet } from 'svelte';
+export type FullscreenToggleProp = Snippet<[{
+    fullscreen: boolean;
+}]> | boolean;
 export type InfoItem = Readonly<{
     label: string;
     value: string | number;

package/dist/layout/fullscreen.svelte.d.ts

@@ -0,0 +1,8 @@
+export declare function sync_fullscreen(opts: {
+    get_wrapper: () => HTMLDivElement | undefined;
+    get_fullscreen: () => boolean;
+    set_fullscreen: (fullscreen: boolean) => void;
+    bg_css_var: string;
+    on_request_error?: (err: Error) => void;
+    on_change?: (fullscreen: boolean) => void;
+}): void;