matterviz 0.3.7 → 0.4.1

package/dist/brillouin/BrillouinZoneScene.svelte.d.ts

@@ -1,13 +1,9 @@
 import type { Vec3 } from '../math';
-import { type CameraProjection } from '../settings';
-import * as extras from '@threlte/extras';
-import type { ComponentProps } from 'svelte';
-import type { Camera, Scene } from 'three';
+import type { SceneControlProps } from '../scene';
 import type { BrillouinZoneData, BZHoverData, IrreducibleBZData } from './types';
-type $$ComponentProps = {
+type $$ComponentProps = SceneControlProps & {
     bz_data?: BrillouinZoneData;
     camera_position?: Vec3 | undefined;
-    camera_projection?: CameraProjection;
     surface_color?: string;
     surface_opacity?: number;
     edge_color?: string;
@@ -18,22 +14,6 @@ type $$ComponentProps = {
     ibz_data?: IrreducibleBZData | null;
     ibz_color?: string;
     ibz_opacity?: number;
-    rotation_damping?: number;
-    max_zoom?: number;
-    min_zoom?: number;
-    rotate_speed?: number;
-    zoom_speed?: number;
-    pan_speed?: number;
-    zoom_to_cursor?: boolean;
-    fov?: number;
-    initial_zoom?: number;
-    ambient_light?: number;
-    directional_light?: number;
-    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
-    auto_rotate?: number;
-    camera_is_moving?: boolean;
-    scene?: Scene;
-    camera?: Camera;
     k_path_points?: Vec3[];
     k_path_labels?: {
         position: Vec3;
@@ -42,7 +22,8 @@ type $$ComponentProps = {
     hovered_k_point?: Vec3 | null;
     hovered_qpoint_index?: number | null;
     hover_data?: BZHoverData | null;
+    on_kpath_hover?: (qpoint_index: number | null) => void;
 };
-declare const BrillouinZoneScene: import("svelte").Component<$$ComponentProps, {}, "camera_position" | "camera_projection" | "vector_scale" | "camera" | "scene" | "camera_is_moving" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "bz_data" | "hover_data">;
+declare const BrillouinZoneScene: import("svelte").Component<$$ComponentProps, {}, "scene" | "camera" | "camera_projection" | "camera_position" | "vector_scale" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "bz_data" | "hover_data">;
 type BrillouinZoneScene = ReturnType<typeof BrillouinZoneScene>;
 export default BrillouinZoneScene;

package/dist/brillouin/BrillouinZoneTooltip.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
   // Tooltip component for Brillouin zone hover information
   // Displays k-coordinates, BZ order, volume, and IBZ-specific info
-  import { format_num, format_vec3 } from '../labels'
-  import { TooltipContent } from '../tooltip'
+  import { format_num } from '../labels'
+  import { KCoords, TooltipContent } from '../tooltip'
   import type { BZHoverData, BZTooltipProp } from './types'
 
   let {
@@ -19,33 +19,26 @@
 
 <TooltipContent data={hover_data} snippet_arg={{ hover_data }} {tooltip}>
   <div class="bz-tooltip-content">
-    <div class="bz-tooltip-title">
-      <strong>{hover_data.is_ibz ? `Irreducible BZ` : `Brillouin Zone`}</strong>
-      {#if hover_data.bz_order > 1}
-        <span class="bz-tooltip-badge">{ordinal(hover_data.bz_order)}</span>
-      {/if}
-    </div>
-    <div class="bz-tooltip-row">
-      <span class="bz-tooltip-label">k (Å⁻¹):</span>
-      <span class="bz-tooltip-value">{format_vec3(hover_data.position_cartesian)}</span>
-    </div>
-    {#if hover_data.position_fractional}
-      <div class="bz-tooltip-row">
-        <span class="bz-tooltip-label">k (frac):</span>
-        <span class="bz-tooltip-value">{
-          format_vec3(hover_data.position_fractional)
-        }</span>
+    {#if hover_data.is_ibz || hover_data.bz_order > 1}
+      <div class="bz-tooltip-title">
+        {#if hover_data.is_ibz}<strong>Irreducible BZ</strong>{/if}
+        {#if hover_data.bz_order > 1}
+          <span class="bz-tooltip-badge">{ordinal(hover_data.bz_order)}</span>
+        {/if}
       </div>
     {/if}
+    <KCoords
+      cartesian={hover_data.position_cartesian}
+      fractional={hover_data.position_fractional}
+    />
     <div class="bz-tooltip-row">
       <span class="bz-tooltip-label">BZ Volume:</span>
-      <span class="bz-tooltip-value">{format_num(hover_data.bz_volume, `.4~`)} Å⁻³</span>
+      <span>{format_num(hover_data.bz_volume, `.4~`)} Å⁻³</span>
     </div>
     {#if hover_data.is_ibz && hover_data.ibz_volume != null}
       <div class="bz-tooltip-row">
         <span class="bz-tooltip-label">IBZ Volume:</span>
-        <span class="bz-tooltip-value">{format_num(hover_data.ibz_volume, `.4~`)}
-          Å⁻³</span>
+        <span>{format_num(hover_data.ibz_volume, `.4~`)} Å⁻³</span>
       </div>
       {#if hover_data.symmetry_multiplicity != null}
         <div class="bz-tooltip-symmetry">
@@ -59,7 +52,6 @@
 <style>
   .bz-tooltip-content {
     max-width: var(--bz-tooltip-max-width, 250px);
-    text-align: left;
   }
   .bz-tooltip-title {
     margin-bottom: 4px;
@@ -71,6 +63,8 @@
     font-weight: 500;
     background: #666;
     color: white;
+  }
+  .bz-tooltip-badge:not(:first-child) {
     margin-left: 6px;
   }
   .bz-tooltip-row {
@@ -81,9 +75,6 @@
     opacity: 0.8;
     min-width: 75px;
   }
-  .bz-tooltip-value {
-    font-family: monospace;
-  }
   .bz-tooltip-symmetry {
     margin-top: 2px;
     opacity: 0.8;

package/dist/brillouin/ReciprocalVectors.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+  // Reciprocal lattice vector arrows (b₁, b₂, b₃) with HTML labels beyond the tips, shared by BrillouinZoneScene and FermiSurfaceScene
+  import type { Matrix3x3, Vec3 } from '../math'
+  import Arrow from '../structure/Arrow.svelte'
+  import * as extras from '@threlte/extras'
+
+  let {
+    k_lattice,
+    vector_scale = 1.0,
+    size = 1,
+  }: {
+    k_lattice: Matrix3x3
+    vector_scale?: number
+    size?: number // characteristic scene size used to scale arrow proportions
+  } = $props()
+
+  const vector_colors = [`red`, `green`, `blue`]
+  const vector_labels = [`b₁`, `b₂`, `b₃`]
+</script>
+
+{#each k_lattice as vec, idx (idx)}
+  {@const scaled_vec = vec.map((coord) => coord * vector_scale) as Vec3}
+  {@const label_position = scaled_vec.map((coord) => coord * 1.15) as Vec3}
+  <Arrow
+    position={[0, 0, 0]}
+    vector={scaled_vec}
+    color={vector_colors[idx]}
+    scale={1}
+    shaft_radius={size * 0.008}
+    arrow_head_radius={size * 0.028}
+    arrow_head_length={-0.1}
+  />
+  <!-- Vector label beyond tip -->
+  <extras.HTML center position={label_position}>
+    <span style:color={vector_colors[idx]} style:font-size="1.2em">
+      {vector_labels[idx]}
+    </span>
+  </extras.HTML>
+{/each}

package/dist/brillouin/ReciprocalVectors.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Matrix3x3 } from '../math';
+type $$ComponentProps = {
+    k_lattice: Matrix3x3;
+    vector_scale?: number;
+    size?: number;
+};
+declare const ReciprocalVectors: import("svelte").Component<$$ComponentProps, {}, "">;
+type ReciprocalVectors = ReturnType<typeof ReciprocalVectors>;
+export default ReciprocalVectors;

package/dist/brillouin/compute.d.ts

@@ -12,6 +12,8 @@ type ClippingPlane = {
     normal: Vec3;
     dist: number;
 };
+export declare const IBZ_REFERENCE_DIRECTIONS: Vec3[];
+export declare function find_ibz_reference_direction(non_identity_ops: Matrix3x3[]): Vec3;
 export declare function compute_ibz_clipping_planes(point_group_ops: Matrix3x3[]): ClippingPlane[];
 export declare function compute_irreducible_bz(bz_data: BrillouinZoneData, point_group_ops: Matrix3x3[], edge_sharp_angle_deg?: number): IrreducibleBZData | null;
 export {};

package/dist/brillouin/compute.js

@@ -3,10 +3,6 @@ import * as math from '../math';
 import { Vector3 } from 'three';
 import { ConvexGeometry } from 'three/examples/jsm/geometries/ConvexGeometry.js';
 const TOL = 1e-8;
-const normalize = (vec) => {
-    const mag = Math.hypot(...vec);
-    return mag < 1e-10 ? [0, 0, 0] : [vec[0] / mag, vec[1] / mag, vec[2] / mag];
-};
 // Check if rotation matrix is identity
 const is_identity_rotation = (rot) => rot.every((row, idx) => row.every((val, jdx) => Math.abs(val - (idx === jdx ? 1 : 0)) < TOL));
 // Extract unique point group rotation matrices from space group operations.
@@ -20,39 +16,21 @@ export function extract_point_group_from_operations(operations) {
         if (seen.has(key))
             continue;
         seen.add(key);
-        const rot = math.vec9_to_mat3x3(Array.from(rotation));
+        // moyo serializes rotations COLUMN-major; vec9_to_mat3x3 reads row-major → transpose to get W
+        const rot = math.transpose_3x3_matrix(math.vec9_to_mat3x3(Array.from(rotation)));
         unique_rotations.push(rot);
     }
     return unique_rotations;
 }
-// Multiply two 3x3 matrices: C = A · B
-function mat3x3_multiply(A, B) {
-    const result = [
-        [0, 0, 0],
-        [0, 0, 0],
-        [0, 0, 0],
-    ];
-    for (let row = 0; row < 3; row++) {
-        for (let col = 0; col < 3; col++) {
-            result[row][col] = A[row][0] * B[0][col] + A[row][1] * B[1][col] + A[row][2] * B[2][col];
-        }
-    }
-    return result;
-}
-// Convert fractional-coordinate rotation W to Cartesian k-space rotation.
-// In reciprocal space: R_cart = B · W^{-T} · B^{-1}, where B is the k_lattice
-// and W^{-T} is the inverse transpose of the direct-space rotation matrix.
-// This follows the dual-basis relation: if direct fractional rotation is x' = W·x,
-// then reciprocal fractional rotation is q' = W^{-T}·q. For non-orthogonal lattices
-// (monoclinic, triclinic, hexagonal), W^{-1} ≠ W^T since integer rotation matrices
-// are not orthogonal in these systems.
+// Convert fractional rotation W to Cartesian k-space rotation. k_lattice stores reciprocal
+// vectors as ROWS (k_cart = Bᵀ·q) and reciprocal fractional rotation is q' = W^{-T}·q, so
+// R_cart = Bᵀ·W^{-T}·B^{-T}. For non-orthogonal lattices W^{-1} ≠ Wᵀ, so the transpose matters.
 export function fractional_to_cartesian_rotation(W, k_lattice) {
     try {
-        const k_lattice_inv = math.matrix_inverse_3x3(k_lattice);
-        const W_inv = math.matrix_inverse_3x3(W);
-        const W_inv_T = math.transpose_3x3_matrix(W_inv);
-        // R_cart = B · W^{-T} · B^{-1}
-        return mat3x3_multiply(mat3x3_multiply(k_lattice, W_inv_T), k_lattice_inv);
+        const B_T = math.transpose_3x3_matrix(k_lattice);
+        const W_inv_T = math.transpose_3x3_matrix(math.matrix_inverse_3x3(W));
+        // R_cart = Bᵀ · W^{-T} · B^{-T}
+        return math.dot(math.dot(B_T, W_inv_T), math.matrix_inverse_3x3(B_T));
     }
     catch {
         // Fallback to identity if inversion fails (shouldn't happen for valid rotations)
@@ -145,7 +123,11 @@ max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
         if (idx === center_idx)
             return null;
         const dist_sq = pt[0] ** 2 + pt[1] ** 2 + pt[2] ** 2;
-        return { normal: normalize(pt), dist: Math.sqrt(dist_sq) / 2, dist_sq };
+        return {
+            normal: math.normalize_vec(pt, [0, 0, 0]),
+            dist: Math.sqrt(dist_sq) / 2,
+            dist_sq,
+        };
     })
         .filter((plane) => plane !== null)
         .sort((a, b) => a.dist_sq - b.dist_sq)
@@ -235,7 +217,7 @@ export function compute_convex_hull(vertices, edge_sharp_angle_deg = 5) {
     // Compute face normals and build edge-to-face adjacency
     const face_normals = faces.map((face) => {
         const [v0, v1, v2] = face.slice(0, 3).map((vertex_idx) => unique_verts[vertex_idx]);
-        return normalize(math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0)));
+        return math.normalize_vec(math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0)), [0, 0, 0]);
     });
     const edge_to_faces = new Map();
     faces.forEach((face, face_idx) => {
@@ -281,51 +263,72 @@ max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
         volume: compute_hull_volume(hull.vertices, hull.faces),
     };
 }
-// Test points for IBZ plane detection. These are chosen to:
-// 1. Avoid common rotation axes (2-fold, 3-fold, 4-fold, 6-fold)
-// 2. Span different directions to catch all symmetry operations
-// 3. Include a generic point [1,2,3] that lies on no special axis
-const IBZ_TEST_POINTS = [
-    [1, 0, 0],
-    [0, 1, 0],
-    [0, 0, 1], // basis vectors (avoid 4-fold axes)
-    [1, 1, 0],
-    [1, 0, 1],
-    [0, 1, 1], // face diagonals (avoid 2-fold axes)
-    [1, 1, 1], // body diagonal (avoid 3-fold axis)
-    [1, 2, 3], // generic point on no special axis
+// Generic reference directions for the Dirichlet-domain construction. Irrational-ish
+// component ratios keep them off every rotation axis and mirror plane of crystallographic
+// point groups in practice; the later directions are fallbacks in case a pathological
+// Cartesian orientation pins the first onto a symmetry element.
+export const IBZ_REFERENCE_DIRECTIONS = [
+    [1, Math.SQRT2 / 3, Math.E / 7],
+    [Math.PI / 5, 1, Math.SQRT1_2 / 4],
+    [Math.E / 9, Math.LN2, 1],
 ];
-// Compute clipping planes from point group operations.
-// For each non-identity rotation, we define a plane that selects one representative
-// from each equivalence class.
+// A reference direction is valid for the Dirichlet construction iff it has a trivial
+// stabilizer: no non-identity operation fixes it (R·t ≠ t for every R). Such a direction
+// always exists because the fixed-point sets (rotation axes, mirror planes) have measure
+// zero. Try the curated generic directions first, then deterministic pseudo-random ones,
+// and throw in the (mathematically unreachable) case where none qualify — rather than
+// silently using a non-generic direction, which would drop that operation's clipping
+// plane and inflate the IBZ volume above V_BZ/|G|.
+export function find_ibz_reference_direction(non_identity_ops) {
+    const has_trivial_stabilizer = (dir) => non_identity_ops.every((rot) => Math.hypot(...math.subtract(math.mat3x3_vec3_multiply(rot, dir), dir)) > TOL);
+    const curated = IBZ_REFERENCE_DIRECTIONS.find(has_trivial_stabilizer);
+    if (curated)
+        return curated;
+    // Park-Miller minstd PRNG (safe-integer arithmetic) keeps the rare fallback
+    // reproducible across runs while sampling generic directions
+    let seed = 16807;
+    const next_component = () => {
+        seed = (seed * 16807) % 2147483647;
+        return (seed / 2147483647) * 2 - 1;
+    };
+    for (let attempt = 0; attempt < 128; attempt++) {
+        const dir = [next_component(), next_component(), next_component()];
+        if (Math.hypot(...dir) > 0.1 && has_trivial_stabilizer(dir))
+            return dir;
+    }
+    throw new Error(`IBZ construction: no generic reference direction found for ${non_identity_ops.length} symmetry operations`);
+}
+// Compute clipping planes from point group operations via the Dirichlet (Voronoi)
+// fundamental-domain construction: pick ONE generic direction t with trivial stabilizer,
+// then for every non-identity operation R keep the half-space x·t ≥ x·(R·t), i.e.
+// (R·t − t)·x ≤ 0. Intersecting all half-spaces with the BZ yields an irreducible wedge
+// of exactly volume(BZ)/|G|. (Using a different reference point per operation — or
+// flipping individual planes — does NOT yield a fundamental domain in general.)
 export function compute_ibz_clipping_planes(point_group_ops) {
+    const non_identity_ops = point_group_ops.filter((rot) => !is_identity_rotation(rot));
+    if (non_identity_ops.length === 0)
+        return [];
+    const ref_dir = find_ibz_reference_direction(non_identity_ops);
     const planes = [];
     const seen_normals = new Set();
-    for (const rot of point_group_ops) {
-        if (is_identity_rotation(rot))
-            continue;
-        for (const test_pt of IBZ_TEST_POINTS) {
-            const rotated = math.mat3x3_vec3_multiply(rot, test_pt);
-            const diff = math.subtract(rotated, test_pt);
-            if (Math.hypot(...diff) < TOL)
-                continue; // point on rotation axis
-            const plane_normal = normalize(diff);
-            const key = plane_normal.map((val) => Math.round(val * 1000)).join(`,`);
-            const neg_key = plane_normal.map((val) => Math.round(-val * 1000)).join(`,`);
-            if (!seen_normals.has(key) && !seen_normals.has(neg_key)) {
-                seen_normals.add(key);
-                planes.push({ normal: plane_normal, dist: 0 });
-            }
-            break;
+    for (const rot of non_identity_ops) {
+        const rotated = math.mat3x3_vec3_multiply(rot, ref_dir);
+        const diff = math.subtract(rotated, ref_dir);
+        // ref_dir has a trivial stabilizer, so every op must move it; a zero diff would
+        // silently drop a plane and inflate the IBZ — surface it instead
+        if (Math.hypot(...diff) < TOL) {
+            throw new Error(`IBZ construction: reference direction unexpectedly fixed by an operation`);
+        }
+        const plane_normal = math.normalize_vec(diff, [0, 0, 0]);
+        // NOTE: do NOT merge antiparallel normals — n and −n select opposite half-spaces
+        const key = plane_normal.map((val) => Math.round(val * 1e6)).join(`,`);
+        if (!seen_normals.has(key)) {
+            seen_normals.add(key);
+            planes.push({ normal: plane_normal, dist: 0 });
         }
     }
     return planes;
 }
-// Flip a clipping plane to the opposite half-space
-const flip_plane = (plane) => ({
-    normal: math.scale(plane.normal, -1),
-    dist: -plane.dist,
-});
 // Clip polyhedron vertices by a half-space, adding intersection points where edges cross
 function clip_polyhedron_by_plane(vertices, faces, plane) {
     const { normal, dist } = plane;
@@ -354,14 +357,14 @@ function clip_polyhedron_by_plane(vertices, faces, plane) {
             // Skip if denominator too small (tighter than TOL for numerical stability)
             if (Math.abs(denom) < 1e-12)
                 continue;
-            const t = d1 / denom;
+            const frac = d1 / denom;
             // Only add intersection if it's not at an endpoint (which is already kept)
-            if (t > TOL && t < 1 - TOL) {
+            if (frac > TOL && frac < 1 - TOL) {
                 const [v1, v2] = [vertices[i1], vertices[i2]];
                 result.push([
-                    v1[0] + t * (v2[0] - v1[0]),
-                    v1[1] + t * (v2[1] - v1[1]),
-                    v1[2] + t * (v2[2] - v1[2]),
+                    v1[0] + frac * (v2[0] - v1[0]),
+                    v1[1] + frac * (v2[1] - v1[1]),
+                    v1[2] + frac * (v2[2] - v1[2]),
                 ]);
             }
         }
@@ -382,7 +385,7 @@ function try_build_hull(vertices, edge_sharp_angle_deg) {
 // Compute the irreducible Brillouin zone by clipping the full BZ with symmetry planes
 export function compute_irreducible_bz(bz_data, point_group_ops, edge_sharp_angle_deg = 5) {
     // Convert fractional rotations to Cartesian k-space rotations
-    // R_cart = B · W^{-T} · B^{-1}, where B is k_lattice and W^{-T} is inverse-transpose
+    // R_cart = Bᵀ · W^{-T} · B^{-T}, where B is k_lattice (reciprocal vectors as rows)
     const cartesian_ops = point_group_ops.map((W) => fractional_to_cartesian_rotation(W, bz_data.k_lattice));
     const clipping_planes = compute_ibz_clipping_planes(cartesian_ops);
     if (clipping_planes.length === 0) {
@@ -397,21 +400,17 @@ export function compute_irreducible_bz(bz_data, point_group_ops, edge_sharp_angl
     let current_vertices = [...bz_data.vertices];
     let current_faces = [...bz_data.faces];
     for (const plane of clipping_planes) {
-        // Try clipping with plane, then flipped plane if needed
-        let clipped_successfully = false;
-        for (const try_plane of [plane, flip_plane(plane)]) {
-            const clipped = clip_polyhedron_by_plane(current_vertices, current_faces, try_plane);
-            const hull = try_build_hull(clipped, edge_sharp_angle_deg);
-            if (hull) {
-                current_vertices = hull.vertices;
-                current_faces = hull.faces;
-                clipped_successfully = true;
-                break;
-            }
+        // Planes from the Dirichlet construction are consistently oriented (the kept side
+        // n·x ≤ 0 always contains the reference direction) so clip directly — flipping a
+        // plane would select the wrong half-space and break the fundamental-domain property
+        const clipped = clip_polyhedron_by_plane(current_vertices, current_faces, plane);
+        const hull = try_build_hull(clipped, edge_sharp_angle_deg);
+        if (hull) {
+            current_vertices = hull.vertices;
+            current_faces = hull.faces;
         }
-        // If both orientations failed, vertices unchanged - continue with best effort
-        if (!clipped_successfully) {
-            console.warn(`IBZ clipping: plane orientation failed, continuing with current geometry`);
+        else {
+            console.warn(`IBZ clipping: degenerate clip result, skipping plane`);
         }
     }
     const hull = try_build_hull(current_vertices, edge_sharp_angle_deg);

package/dist/brillouin/geometry.d.ts

@@ -0,0 +1,8 @@
+import type { Matrix3x3, Vec3 } from '../math';
+import { BufferGeometry } from 'three';
+export declare function polyhedron_geometry(vertices: Vec3[], faces: number[][]): BufferGeometry | null;
+export declare function k_lattice_inverse(k_lattice: Matrix3x3 | undefined): Matrix3x3 | null;
+export declare const cartesian_to_fractional: (k_lattice_inv: Matrix3x3 | null, cart: Vec3) => Vec3 | null;
+export declare const polyhedron_centroid: (vertices: Vec3[] | undefined) => Vec3;
+export declare const k_space_size: (k_lattice: Matrix3x3 | undefined) => number;
+export declare const default_camera_position: (size: number) => Vec3;

package/dist/brillouin/geometry.js

@@ -0,0 +1,57 @@
+import * as math from '../math';
+import { BufferAttribute, BufferGeometry } from 'three';
+// Build a renderable mesh from polyhedron vertices + polygonal faces via fan triangulation with flat per-face normals. Assumes convex faces (true for BZ/IBZ polyhedra); non-convex faces would triangulate incorrectly. Shared by BrillouinZoneScene (BZ + IBZ meshes) and FermiSurfaceScene (BZ overlay). Caller owns disposal.
+export function polyhedron_geometry(vertices, faces) {
+    if (faces.length === 0)
+        return null;
+    const positions = [];
+    const normals = [];
+    for (const face of faces) {
+        if (face.length < 3)
+            continue;
+        for (let face_idx = 1; face_idx < face.length - 1; face_idx++) {
+            const indices = [face[0], face[face_idx], face[face_idx + 1]];
+            if (indices.some((idx) => idx < 0 || idx >= vertices.length))
+                continue;
+            const [vertex_a, vertex_b, vertex_c] = indices.map((idx) => vertices[idx]);
+            positions.push(...vertex_a, ...vertex_b, ...vertex_c);
+            const edge_ab = math.subtract(vertex_b, vertex_a);
+            const edge_ac = math.subtract(vertex_c, vertex_a);
+            const face_normal = math.cross_3d(edge_ab, edge_ac);
+            const normal_length = Math.hypot(...face_normal);
+            const unit_normal = normal_length > 1e-10 ? face_normal.map((coord) => coord / normal_length) : [0, 0, 0];
+            normals.push(...unit_normal, ...unit_normal, ...unit_normal);
+        }
+    }
+    // All faces degenerate or out-of-range -> no triangles, so return null instead of an empty geometry
+    if (positions.length === 0)
+        return null;
+    const geometry = new BufferGeometry();
+    geometry.setAttribute(`position`, new BufferAttribute(new Float32Array(positions), 3));
+    geometry.setAttribute(`normal`, new BufferAttribute(new Float32Array(normals), 3));
+    geometry.computeBoundingSphere();
+    return geometry;
+}
+// Inverse of the reciprocal lattice for Cartesian -> fractional conversion; null if the lattice is missing or singular
+export function k_lattice_inverse(k_lattice) {
+    if (!k_lattice)
+        return null;
+    try {
+        return math.matrix_inverse_3x3(k_lattice);
+    }
+    catch {
+        return null;
+    }
+}
+// Convert Cartesian k-coordinates to fractional (reciprocal lattice units); null if the (pre-computed) lattice inverse is unavailable
+export const cartesian_to_fractional = (k_lattice_inv, cart) => k_lattice_inv && math.mat3x3_vec3_multiply(k_lattice_inv, cart);
+// Centroid of polyhedron vertices, used as orbit/rotation target by BZ + Fermi scenes
+export const polyhedron_centroid = (vertices) => vertices?.length
+    ? math.scale(vertices.reduce((acc, vert) => math.add(acc, vert), [0, 0, 0]), 1 / vertices.length)
+    : [0, 0, 0];
+// Mean reciprocal-lattice vector magnitude: characteristic scene size for camera placement
+// and arrow scaling. Fallback 10 (upper end of typical |b_i| ~ 2pi/a in 1/A) keeps the
+// camera at a sensible distance while no data is loaded.
+export const k_space_size = (k_lattice) => k_lattice ? k_lattice.reduce((sum, vec) => sum + Math.hypot(...vec), 0) / 3 : 10;
+// Default camera position scaled to the scene size
+export const default_camera_position = (size) => [10, 3, 8].map((coord) => coord * Math.max(1, size));

package/dist/brillouin/index.d.ts

@@ -5,4 +5,6 @@ export { default as BrillouinZoneInfoPane } from './BrillouinZoneInfoPane.svelte
 export { default as BrillouinZoneScene } from './BrillouinZoneScene.svelte';
 export { default as BrillouinZoneTooltip } from './BrillouinZoneTooltip.svelte';
 export * from './compute';
+export * from './geometry';
+export { default as ReciprocalVectors } from './ReciprocalVectors.svelte';
 export type * from './types';

package/dist/brillouin/index.js

@@ -5,3 +5,5 @@ export { default as BrillouinZoneInfoPane } from './BrillouinZoneInfoPane.svelte
 export { default as BrillouinZoneScene } from './BrillouinZoneScene.svelte';
 export { default as BrillouinZoneTooltip } from './BrillouinZoneTooltip.svelte';
 export * from './compute';
+export * from './geometry';
+export { default as ReciprocalVectors } from './ReciprocalVectors.svelte';

package/dist/brillouin/types.d.ts

@@ -1,4 +1,4 @@
-import type { Matrix3x3, Point2D, Vec3 } from '../math';
+import type { Matrix3x3, Point2D, Vec2, Vec3 } from '../math';
 import type { Crystal } from '../structure';
 import type { TooltipConfig, TooltipProp } from '../tooltip';
 export type BZHoverData = {
@@ -38,6 +38,6 @@ export type BrillouinZoneProps = {
     show_vectors?: boolean;
 };
 export type ConvexHullData = Pick<BZMeshData, `vertices` | `faces`> & {
-    edges: [number, number][];
+    edges: Vec2[];
 };
 export {};

package/dist/chempot-diagram/ChemPotDiagram.svelte

@@ -1,20 +1,21 @@
 <script lang="ts">
-  import { get_electro_neg_formula } from '../composition/format';
-  import type { PhaseData } from '../convex-hull/types';
-  import Spinner from '../feedback/Spinner.svelte';
-  import { format_num } from '../labels';
-  import { constrain_tooltip_position } from '../plot/layout';
-  import { sanitize_html } from '../sanitize';
-  import { compute_chempot_async } from './async-compute.svelte';
-  import ChemPotDiagram2D from './ChemPotDiagram2D.svelte';
-  import ChemPotDiagram3D from './ChemPotDiagram3D.svelte';
-  import { get_ternary_combinations } from './compute';
+  import { get_electro_neg_formula } from '../composition/format'
+  import type { PhaseData } from '../convex-hull/types'
+  import Spinner from '../feedback/Spinner.svelte'
+  import { format_num } from '../labels'
+  import { constrain_tooltip_position } from '../plot/core/layout'
+  import { sanitize_html } from '../sanitize'
+  import { compute_chempot_async } from './async-compute.svelte'
+  import ChemPotDiagram2D from './ChemPotDiagram2D.svelte'
+  import ChemPotDiagram3D from './ChemPotDiagram3D.svelte'
+  import { get_ternary_combinations } from './compute'
   import type {
       ChemPotDiagramConfig,
       ChemPotHoverInfo,
       ChemPotHoverInfo3D,
-  } from './types';
-  import { CHEMPOT_DEFAULTS } from './types';
+  } from './types'
+  import { CHEMPOT_DEFAULTS } from './types'
+  import { to_error } from '../utils'
 
   let {
     entries = [],
@@ -84,7 +85,7 @@
       .catch((err) => {
         if (cancelled) return
         console.error(`Grid precompute failed:`, err)
-        grid_error = err instanceof Error ? err.message : String(err)
+        grid_error = to_error(err).message
       })
     return () => { cancelled = true }
   })

package/dist/chempot-diagram/ChemPotDiagram.svelte.d.ts

@@ -8,6 +8,6 @@ type $$ComponentProps = {
     temperature?: number;
     hover_info?: ChemPotHoverInfo | null;
 };
-declare const ChemPotDiagram: import("svelte").Component<$$ComponentProps, {}, "temperature" | "height" | "width" | "hover_info">;
+declare const ChemPotDiagram: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "temperature" | "hover_info">;
 type ChemPotDiagram = ReturnType<typeof ChemPotDiagram>;
 export default ChemPotDiagram;