matterviz 0.3.7 → 0.4.1

package/dist/plot/sunburst/sunburst.js

@@ -0,0 +1,269 @@
+// Layout helpers for Sunburst charts, wrapping d3-hierarchy's partition.
+// Single source of truth for the hierarchy/angle math so the component stays
+// declarative and the layout is independently unit-testable. The partition is
+// computed in normalized coordinates (angle as fraction of full circle in [0, 1],
+// radius in integer ring units where y0 === depth) independent of pixel size and
+// zoom — the component maps these to screen space per frame (zoomable-sunburst trick).
+import { hsl } from 'd3-color';
+import { hierarchy, partition } from 'd3-hierarchy';
+import { DEFAULT_SERIES_COLORS } from '../core/types';
+import { DEFAULTS } from '../../settings';
+// Compute normalized arc extents, resolved colors and breadcrumbs for a node tree.
+// Never mutates user data: d3-hierarchy wraps inputs in HierarchyNodes and all derived
+// fields (value overrides, ids, colors) are written onto the returned arcs only.
+export function compute_sunburst_layout(data, opts = {}) {
+    const { 
+    // value_mode/min_fraction fallbacks derive from DEFAULTS.sunburst to prevent drift
+    value_mode = DEFAULTS.sunburst.value_mode, sort = `none`, level_lighten = 0, min_fraction = DEFAULTS.sunburst.min_fraction, other_label = `Other`, } = opts;
+    // Fresh object each call (not a shared constant) so callers can't corrupt each other
+    if (Array.isArray(data) ? data.length === 0 : !data) {
+        return { arcs: [], root: null, max_depth: 0 };
+    }
+    // Single root node is used directly; arrays get a synthetic invisible root
+    const root_data = Array.isArray(data) ? { children: data } : data;
+    const root = hierarchy(root_data, (node) => node.children);
+    // 'remainder': d3's .sum() adds the node's own value on top of its children's sum,
+    // which is exactly plotly's branchvalues='remainder'. 'leaf-sum' ignores parent values.
+    // 'total': every explicitly set value is authoritative (plotly branchvalues='total');
+    // nodes without one get their children's sum. Children summing to less than their
+    // parent leave a trailing angular gap; more than the parent overflows (plotly errors
+    // here; we warn and the component clamps angles).
+    if (value_mode === `remainder`)
+        root.sum((node) => node.value ?? 0);
+    else if (value_mode === `total`) {
+        root.eachAfter((node) => {
+            const child_sum = node.children?.reduce((sum, child) => sum + (child.value ?? 0), 0) ?? 0;
+            node.value = node.data.value ?? child_sum;
+            if (node.children && node.data.value != null && child_sum > node.data.value + 1e-9) {
+                console.warn(`Sunburst: children of "${node.data.label ?? node.data.id ?? `root`}" sum to ${child_sum}, exceeding its value of ${node.data.value} (value_mode='total')`);
+            }
+        });
+    }
+    else
+        root.sum((node) => (node.children?.length ? 0 : (node.value ?? 0)));
+    if (sort !== `none`) {
+        const sign = sort === `descending` ? -1 : 1;
+        root.sort((node_a, node_b) => sign * ((node_a.value ?? 0) - (node_b.value ?? 0)));
+    }
+    // 'Other' bucketing: move sub-threshold children to the end of each sibling list
+    // (after sorting, before partition) so the smalls occupy one contiguous angular run
+    // that flatten() below can merge into a single synthetic arc.
+    const bucket_threshold = min_fraction > 0 ? min_fraction * (root.value ?? 0) : 0;
+    if (bucket_threshold > 0) {
+        root.each((node) => {
+            if (!node.children)
+                return;
+            const small = node.children.filter((child) => (child.value ?? 0) < bucket_threshold);
+            if (small.length >= 2) {
+                const kept = node.children.filter((child) => (child.value ?? 0) >= bucket_threshold);
+                node.children = [...kept, ...small];
+            }
+        });
+    }
+    // x in [0, 1] (angle fraction), y in ring units (y0 === depth, y1 === depth + 1)
+    const part_root = partition().size([1, root.height + 1])(root);
+    const arcs = [];
+    const seen_ids = new Set();
+    const root_value = root.value ?? 0;
+    const palette_len = DEFAULT_SERIES_COLORS.length;
+    let depth1_count = 0; // running index among depth-1 nodes, for palette cycling
+    // Resolved fill for a node: explicit > depth-1 palette > inherited, optionally
+    // lightened by depth. base = unlightened color descendants inherit.
+    const resolve_color = (depth, explicit, parent_base) => {
+        const base = explicit ??
+            (depth === 1
+                ? DEFAULT_SERIES_COLORS[depth1_count++ % palette_len]
+                : (parent_base ?? `transparent`));
+        let color = base;
+        if (!explicit && depth > 1 && level_lighten > 0) {
+            color = hsl(base)
+                .brighter(level_lighten * (depth - 1))
+                .formatHex();
+        }
+        return { base, color };
+    };
+    // Construct + append an arc, deriving indices, breadcrumbs and fractions from the
+    // parent (shared by regular nodes and synthetic 'Other' arcs)
+    const push_arc = (parent, fields) => {
+        if (seen_ids.has(fields.id)) {
+            console.warn(`Sunburst: duplicate node id "${fields.id}" — set unique \`id\`s or labels.`);
+        }
+        seen_ids.add(fields.id);
+        const arc = {
+            node_idx: arcs.length,
+            subtree_end: arcs.length, // leaves keep this; branches update after recursion
+            parent_idx: parent?.node_idx ?? null,
+            path: parent ? [...parent.path, fields.id] : [],
+            label_path: parent ? [...parent.label_path, fields.label ?? `${fields.id}`] : [],
+            fraction: root_value > 0 ? fields.value / root_value : 0,
+            parent_fraction: parent ? (parent.value > 0 ? fields.value / parent.value : 0) : 1,
+            ...fields,
+        };
+        arcs.push(arc);
+        return arc;
+    };
+    // Pre-order DFS so each subtree occupies a contiguous node_idx range
+    const flatten = (node, parent, parent_base, // unlightened color descendants inherit
+    child_idx) => {
+        const { depth } = node;
+        const explicit = node.data.color;
+        const { base, color } = resolve_color(depth, explicit, parent_base);
+        // Stable id: explicit, else slash-joined label path (e.g. "cubic/Fm-3m")
+        const parent_prefix = parent && parent.id !== `` ? `${parent.id}/` : ``;
+        const segment = node.data.label ?? `${child_idx}`;
+        const id = node.data.id ?? (depth === 0 ? (node.data.label ?? ``) : `${parent_prefix}${segment}`);
+        const { x0, x1, y0, y1 } = node;
+        const arc = push_arc(parent, {
+            id,
+            label: node.data.label,
+            value: node.value ?? 0,
+            color,
+            depth,
+            is_leaf: !node.children?.length,
+            x0,
+            x1,
+            y0,
+            y1,
+            metadata: node.data.metadata,
+        });
+        // Children below the bucket threshold form a contiguous trailing run (reordered
+        // above); merge runs of >= 2 into one synthetic 'Other' leaf instead of recursing
+        const kids = node.children ?? [];
+        let cut = kids.length;
+        if (bucket_threshold > 0) {
+            const first_small = kids.findLastIndex((kid) => (kid.value ?? 0) >= bucket_threshold) + 1;
+            if (kids.length - first_small >= 2)
+                cut = first_small;
+        }
+        kids.forEach((child, idx) => {
+            if (idx < cut)
+                flatten(child, arc, explicit ?? base, idx);
+        });
+        if (cut < kids.length) {
+            const smalls = kids.slice(cut);
+            push_arc(arc, {
+                id: `${arc.id !== `` ? `${arc.id}/` : ``}${other_label}`,
+                label: other_label,
+                value: smalls.reduce((sum, child) => sum + (child.value ?? 0), 0),
+                color: resolve_color(depth + 1, undefined, explicit ?? base).color,
+                depth: depth + 1,
+                is_leaf: true,
+                is_other: true,
+                x0: smalls[0].x0,
+                x1: smalls[smalls.length - 1].x1,
+                y0: depth + 1,
+                y1: depth + 2,
+            });
+        }
+        arc.subtree_end = arcs.length - 1;
+    };
+    flatten(part_root, null, null, 0);
+    return { arcs, root: arcs[0], max_depth: root.height };
+}
+// Build a nested node tree from flat path rows (plotly-express style), e.g.
+// { path: ['cubic', 'Fm-3m'], value: 12 }. Rows sharing a full path accumulate their
+// values; rows whose path is a proper prefix of others set that interior node's own
+// value (meaningful with value_mode 'total'/'remainder').
+export function sunburst_from_paths(rows) {
+    const roots = new Map();
+    rows.forEach((row, row_idx) => {
+        if (!row.path || row.path.length === 0) {
+            throw new Error(`sunburst_from_paths: row ${row_idx} has an empty path`);
+        }
+        let level = roots;
+        let trie;
+        let id = ``;
+        for (const segment of row.path) {
+            id = id ? `${id}/${segment}` : `${segment}`;
+            trie = level.get(segment);
+            if (!trie) {
+                trie = { node: { id, label: `${segment}` }, children: new Map() };
+                level.set(segment, trie);
+            }
+            level = trie.children;
+        }
+        const node = trie.node;
+        node.value = (node.value ?? 0) + row.value;
+        if (row.color != null)
+            node.color = row.color;
+        if (row.metadata != null)
+            node.metadata = row.metadata;
+    });
+    const to_nodes = (level) => [...level.values()].map(({ node, children }) => children.size ? { ...node, children: to_nodes(children) } : node);
+    return to_nodes(roots);
+}
+// Build a nested node tree from plotly trace arrays (labels/parents/values [+ ids]),
+// the format pymatviz/matbench-discovery sunburst exports use (with branchvalues
+// 'total' -> pair with value_mode 'total'). parents entries of ''/null/undefined mark
+// root-level nodes; parents reference ids when given, else labels.
+export function sunburst_from_labels_parents(labels, parents, values, opts = {}) {
+    const { ids, colors, metadata } = opts;
+    for (const [name, arr] of [
+        [`parents`, parents],
+        [`values`, values],
+        [`ids`, ids],
+        [`colors`, colors],
+        [`metadata`, metadata],
+    ]) {
+        if (arr && arr.length !== labels.length) {
+            throw new Error(`sunburst_from_labels_parents: labels (${labels.length}) and ${name} (${arr.length}) must have equal length`);
+        }
+    }
+    const key_to_idx = new Map();
+    const nodes = labels.map((label, idx) => {
+        const key = ids?.[idx] ?? label;
+        if (key_to_idx.has(key)) {
+            throw new Error(`sunburst_from_labels_parents: duplicate node ${ids ? `id` : `label`} "${key}"${ids ? `` : ` — pass opts.ids to disambiguate`}`);
+        }
+        key_to_idx.set(key, idx);
+        const node = { id: key, label };
+        if (values?.[idx] != null)
+            node.value = values[idx];
+        if (colors?.[idx] != null)
+            node.color = colors[idx];
+        if (metadata?.[idx] != null)
+            node.metadata = metadata[idx];
+        return node;
+    });
+    // Resolve all parent references up front (one map lookup per node)
+    const parent_idxs = labels.map((_, idx) => {
+        const ref = parents[idx];
+        if (ref == null || ref === ``)
+            return null;
+        const found = key_to_idx.get(ref);
+        if (found === undefined) {
+            throw new Error(`sunburst_from_labels_parents: node "${ids?.[idx] ?? labels[idx]}" references unknown parent "${ref}"`);
+        }
+        return found;
+    });
+    // O(n) cycle detection: walk each unvisited parent chain once, marking nodes
+    // 'in-progress' on the way up. Hitting an in-progress node = cycle; hitting a
+    // 'done' node = chain already verified acyclic.
+    const state = new Uint8Array(nodes.length); // 0 = unvisited, 1 = in progress, 2 = done
+    for (let idx = 0; idx < nodes.length; idx++) {
+        if (state[idx] !== 0)
+            continue;
+        let cur = idx;
+        while (cur != null && state[cur] === 0) {
+            state[cur] = 1;
+            cur = parent_idxs[cur];
+        }
+        if (cur != null && state[cur] === 1) {
+            throw new Error(`sunburst_from_labels_parents: cycle detected involving node "${ids?.[cur] ?? labels[cur]}"`);
+        }
+        // Mark the walked chain as verified
+        for (let mark = idx; mark != null && state[mark] === 1;) {
+            state[mark] = 2;
+            mark = parent_idxs[mark];
+        }
+    }
+    const roots = [];
+    nodes.forEach((node, idx) => {
+        const parent = parent_idxs[idx];
+        if (parent == null)
+            roots.push(node);
+        else
+            (nodes[parent].children ??= []).push(node);
+    });
+    return roots;
+}

package/dist/rdf/RdfPlot.svelte

@@ -10,6 +10,7 @@
   import { is_crystal } from '../structure/validation'
   import type { ComponentProps, Snippet } from 'svelte'
   import { calculate_all_pair_rdfs, calculate_rdf, type RdfEntry } from './index'
+  import { to_error } from '../utils'
 
   let {
     patterns,
@@ -66,7 +67,7 @@
       }
     } catch (exc) {
       error_msg = `Failed to process structure: ${
-        exc instanceof Error ? exc.message : String(exc)
+        to_error(exc).message
       }`
     }
   }

package/dist/rdf/RdfPlot.svelte.d.ts

@@ -22,6 +22,6 @@ type $$ComponentProps = {
     drag_dropped?: Crystal[];
     dragging?: boolean;
 } & ComponentProps<typeof ScatterPlot>;
-declare const RdfPlot: import("svelte").Component<$$ComponentProps, {}, "loading" | "error_msg" | "dragging" | "drag_dropped">;
+declare const RdfPlot: import("svelte").Component<$$ComponentProps, {}, "loading" | "dragging" | "error_msg" | "drag_dropped">;
 type RdfPlot = ReturnType<typeof RdfPlot>;
 export default RdfPlot;

package/dist/rdf/calc-rdf.js

@@ -6,7 +6,7 @@ const sum_occu = (sites, elem) => sites.reduce((sum, site) => sum + get_occu(sit
 // Calculate radial distribution function
 export function calculate_rdf(structure, options = {}) {
     const { center_species, neighbor_species, cutoff = 15, n_bins = 75, auto_expand = true, expansion_factor = 2.0, } = options;
-    let { pbc = [true, true, true] } = options;
+    const { pbc = [true, true, true] } = options;
     if (cutoff <= 0 || n_bins <= 0) {
         throw new Error(`cutoff and n_bins must be positive`);
     }
@@ -16,6 +16,7 @@ export function calculate_rdf(structure, options = {}) {
     }
     let lattice = structure.lattice.matrix;
     let { sites } = structure;
+    let center_sites = sites;
     // Expand structure if needed to ensure shortest lattice vector is expansion_factor× the cutoff
     // This prevents artificial close contacts at cell boundaries when using PBC
     // Standard practice uses 2.0-2.5× to eliminate finite-size effects
@@ -27,7 +28,10 @@ export function calculate_rdf(structure, options = {}) {
             const expanded_structure = make_supercell(structure, [n_a, n_b, n_c], false);
             sites = expanded_structure.sites;
             lattice = expanded_structure.lattice.matrix;
-            pbc = [false, false, false]; // Disable PBC since we explicitly expanded the structure
+            // Keep PBC: min-image is exact once every lattice vector ≥ 2× cutoff (disabling PBC
+            // starves boundary atoms and biases g(r) low). Under full PBC all periodic copies are
+            // equivalent, so restrict centers to the first copy (make_supercell emits (0,0,0) first)
+            center_sites = pbc.every(Boolean) ? sites.slice(0, structure.sites.length) : sites;
         }
     }
     const bin_size = cutoff / n_bins;
@@ -36,7 +40,7 @@ export function calculate_rdf(structure, options = {}) {
     if (sites.length === 0)
         return { r, g_r };
     // Get occupancy weight for a site-species pair (supports mixed occupancy)
-    const centers = sites.filter((site) => has_species(site, center_species));
+    const centers = center_sites.filter((site) => has_species(site, center_species));
     const neighbors = sites.filter((site) => has_species(site, neighbor_species));
     if (centers.length === 0 || neighbors.length === 0) {
         const element_pair = center_species && neighbor_species
@@ -45,7 +49,7 @@ export function calculate_rdf(structure, options = {}) {
         return { r, g_r, element_pair };
     }
     // Calculate distances and bin them with occupancy weighting
-    const use_pbc = pbc.some((flag) => flag);
+    const use_pbc = pbc.some(Boolean);
     const converters = use_pbc ? create_lattice_converters(lattice) : undefined;
     for (const center of centers) {
         for (const neighbor of neighbors) {
@@ -85,26 +89,9 @@ export function calculate_all_pair_rdfs(structure, options = {}) {
     const elems = [
         ...new Set(structure.sites.flatMap((site) => site.species.map((spec) => spec.element))),
     ].sort();
-    // If auto_expand is true, expand the structure once and reuse it for all pairs
-    // to avoid repeated supercell computations
-    let structure_to_use = structure;
-    if (options.auto_expand !== false) {
-        const { cutoff = 15, expansion_factor = 2.0 } = options;
-        const lattice = structure.lattice?.matrix;
-        if (lattice) {
-            const { a, b, c } = calc_lattice_params(lattice);
-            const min_size = cutoff * expansion_factor;
-            const [n_a, n_b, n_c] = [a, b, c].map((len) => Math.ceil(min_size / len));
-            if (n_a > 1 || n_b > 1 || n_c > 1) {
-                structure_to_use = make_supercell(structure, [n_a, n_b, n_c], false);
-            }
-        }
-    }
-    // Pass auto_expand=false since we've already expanded, and pbc=false for expanded structure
-    const pbc = [false, false, false];
-    const rdf_options = { ...options, auto_expand: false, pbc };
-    return elems.flatMap((el1, idx1) => elems.slice(idx1).map((el2) => calculate_rdf(structure_to_use, {
-        ...rdf_options,
+    // Forward options unchanged (preserves caller's pbc); each calculate_rdf expands itself
+    return elems.flatMap((el1, idx1) => elems.slice(idx1).map((el2) => calculate_rdf(structure, {
+        ...options,
         center_species: el1,
         neighbor_species: el2,
     })));

package/dist/sanitize.js

@@ -53,7 +53,7 @@ function sanitize_svg_content(html, allowed_tags, allowed_attrs) {
     });
     const open_end = wrapped.indexOf(`>`);
     const close_start = wrapped.lastIndexOf(`</svg>`);
-    if (open_end < 0 || close_start < 0)
+    if (open_end === -1 || close_start === -1)
         return wrapped;
     return wrapped.slice(open_end + 1, close_start);
 }
@@ -75,21 +75,32 @@ const stringify_html_input = (html) => {
         return ``;
     }
 };
+// Memoize by input: two DOMPurify passes per call are costly when a component re-sanitizes
+// many cells on every render (e.g. HeatmapTable). Sanitization is deterministic for the
+// fixed config, so caching is output-identical.
+const sanitize_cache = new Map();
 // Sanitize HTML string, allowing only safe formatting tags and links.
 // Two-pass: happy-dom promotes dangerous children when a non-allowed parent is
 // stripped (e.g. <div><script>…</script></div> → <script>…</script>). The first
 // pass explicitly removes dangerous tags so they can't survive promotion.
 export function sanitize_html(html) {
     const str = stringify_html_input(html);
+    const cached = sanitize_cache.get(str);
+    if (cached !== undefined)
+        return cached;
     const dp = get_purify();
     if (!dp)
-        return str;
+        return str; // no DOM (SSR): return as-is, don't cache
     // oxfmt-ignore
     const safe = dp.sanitize(str, { ADD_ATTR: [`target`], FORBID_TAGS: [
             `script`, `style`, `iframe`, `object`, `embed`, `form`, `input`, `textarea`,
             `select`, `button`, `meta`, `link`, `base`, `template`, `noscript`,
         ] });
-    return dp.sanitize(safe, { ALLOWED_TAGS: SAFE_TAGS, ALLOWED_ATTR: SAFE_ATTRS });
+    const result = dp.sanitize(safe, { ALLOWED_TAGS: SAFE_TAGS, ALLOWED_ATTR: SAFE_ATTRS });
+    if (sanitize_cache.size >= 4096)
+        sanitize_cache.clear(); // bound memory (rarely hit)
+    sanitize_cache.set(str, result);
+    return result;
 }
 export const compact_formula = (formula) => formula.replaceAll(/\s+/g, ``);
 // Sanitize a chemical formula with optional subscript formatting

package/dist/scene/SceneCamera.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+  // Dual perspective/orthographic camera with OrbitControls + axis Gizmo, shared by BrillouinZoneScene, FermiSurfaceScene and StructureScene
+  import type { Vec3 } from '../math'
+  import { type CameraProjection, DEFAULTS } from '../settings'
+  import { T } from '@threlte/core'
+  import * as extras from '@threlte/extras'
+  import type { ComponentProps } from 'svelte'
+  import { build_gizmo_props, build_orbit_props } from './props'
+
+  let {
+    camera_projection = `perspective`,
+    position,
+    fov = DEFAULTS.structure.fov,
+    zoom = DEFAULTS.structure.initial_zoom,
+    near = undefined,
+    far = undefined,
+    orbit_props,
+    gizmo = false,
+    orbit_controls = $bindable(undefined),
+  }: {
+    camera_projection?: CameraProjection
+    position: Vec3 // camera position
+    fov?: number // perspective field of view
+    zoom?: number // orthographic zoom level
+    near?: number // perspective near plane (orthographic always uses -100)
+    far?: number // far plane (applied to either projection when provided)
+    orbit_props: ReturnType<typeof build_orbit_props>
+    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>
+    orbit_controls?: ComponentProps<typeof extras.OrbitControls>[`ref`]
+  } = $props()
+
+  const gizmo_props = $derived(build_gizmo_props(gizmo))
+  // Only pass clipping planes that were explicitly provided so three.js defaults apply otherwise
+  const persp_planes = $derived({
+    ...(near !== undefined && { near }),
+    ...(far !== undefined && { far }),
+  })
+  const ortho_far = $derived(far !== undefined ? { far } : {})
+</script>
+
+{#snippet camera_contents()}
+  <extras.OrbitControls bind:ref={orbit_controls} {...orbit_props}>
+    {#if gizmo}<extras.Gizmo {...gizmo_props} />{/if}
+  </extras.OrbitControls>
+{/snippet}
+
+{#if camera_projection === `perspective`}
+  <T.PerspectiveCamera makeDefault {position} {fov} {...persp_planes}>
+    {@render camera_contents()}
+  </T.PerspectiveCamera>
+{:else}
+  <T.OrthographicCamera makeDefault {position} {zoom} near={-100} {...ortho_far}>
+    {@render camera_contents()}
+  </T.OrthographicCamera>
+{/if}
+
+<style>
+  :global(.responsive-gizmo) {
+    width: clamp(70px, 18cqmin, 100px) !important;
+    height: clamp(70px, 18cqmin, 100px) !important;
+  }
+</style>

package/dist/scene/SceneCamera.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Vec3 } from '../math';
+import { type CameraProjection } from '../settings';
+import * as extras from '@threlte/extras';
+import type { ComponentProps } from 'svelte';
+import { build_orbit_props } from './props';
+type $$ComponentProps = {
+    camera_projection?: CameraProjection;
+    position: Vec3;
+    fov?: number;
+    zoom?: number;
+    near?: number;
+    far?: number;
+    orbit_props: ReturnType<typeof build_orbit_props>;
+    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
+    orbit_controls?: ComponentProps<typeof extras.OrbitControls>[`ref`];
+};
+declare const SceneCamera: import("svelte").Component<$$ComponentProps, {}, "orbit_controls">;
+type SceneCamera = ReturnType<typeof SceneCamera>;
+export default SceneCamera;

package/dist/scene/bind-renderer.svelte.d.ts

@@ -0,0 +1,2 @@
+import type { Camera, Scene, WebGLRenderer } from 'three';
+export declare function bind_renderer(on_bind: (scene: Scene, camera: Camera) => void, on_renderer?: (renderer: WebGLRenderer) => void): import("@threlte/core").ThrelteContext<WebGLRenderer>;

package/dist/scene/bind-renderer.svelte.js

@@ -0,0 +1,14 @@
+import { renderer_registry } from '../io/export';
+import { useThrelte } from '@threlte/core';
+// Mirror the Threlte scene + active camera into bindable props (for export panes etc.) and register the canvas->renderer mapping so PNG-export helpers can find it. Creates an $effect (call during component init). Returns the Threlte context for further use (e.g. clipping planes).
+export function bind_renderer(on_bind, on_renderer) {
+    const threlte = useThrelte();
+    $effect(() => {
+        on_bind(threlte.scene, threlte.camera.current);
+        if (threlte.renderer) {
+            on_renderer?.(threlte.renderer);
+            renderer_registry.set(threlte.renderer.domElement, threlte.renderer);
+        }
+    });
+    return threlte;
+}

package/dist/scene/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bind-renderer.svelte';
+export * from './props';
+export { default as SceneCamera } from './SceneCamera.svelte';
+export type * from './types';

package/dist/scene/index.js

@@ -0,0 +1,5 @@
+// Shared Three.js/Threlte scene boilerplate (cameras, orbit controls, gizmo,
+// renderer binding) used by BrillouinZoneScene, FermiSurfaceScene and StructureScene.
+export * from './bind-renderer.svelte';
+export * from './props';
+export { default as SceneCamera } from './SceneCamera.svelte';

package/dist/scene/props.js

@@ -0,0 +1,52 @@
+import { AXIS_COLORS, NEG_AXIS_COLORS } from '../colors';
+// ScatterPlot3DScene keeps its own gizmo/orbit props on purpose: its gizmo offset is
+// ColorBar-aware (build_gizmo_props' fixed offset would clobber it) and its orbit controls
+// differ by design (no zoom-to-cursor / ortho zoom-doubling / camera-moving tracking).
+// Shared Gizmo config: colored +/- axis handles, transparent background, responsive sizing. An object `gizmo` overrides the per-axis defaults.
+export function build_gizmo_props(gizmo) {
+    return {
+        background: { enabled: false },
+        className: `responsive-gizmo`,
+        ...Object.fromEntries([...AXIS_COLORS, ...NEG_AXIS_COLORS].map(([axis, color, hover]) => [
+            axis,
+            {
+                color,
+                labelColor: `#111`,
+                opacity: axis.startsWith(`n`) ? 0.9 : 0.8,
+                hover: {
+                    color: hover,
+                    labelColor: `#222`,
+                    opacity: axis.startsWith(`n`) ? 1 : 0.9,
+                },
+            },
+        ])),
+        ...(typeof gizmo === `object` ? gizmo : {}),
+        offset: { left: 5, bottom: 5 },
+    };
+}
+// Shared OrbitControls config; `onstart_extra` runs extra cleanup when the camera starts moving (e.g. StructureScene closes hover tooltips/context menus)
+export function build_orbit_props(opts) {
+    const is_ortho = opts.camera_projection === `orthographic`;
+    return {
+        position: [0, 0, 0],
+        target: opts.target,
+        enableRotate: opts.rotate_speed > 0,
+        rotateSpeed: opts.rotate_speed,
+        enableZoom: opts.zoom_speed > 0,
+        zoomSpeed: is_ortho ? opts.zoom_speed * 2 : opts.zoom_speed,
+        zoomToCursor: opts.zoom_to_cursor,
+        enablePan: opts.pan_speed > 0,
+        panSpeed: opts.pan_speed,
+        maxZoom: opts.max_zoom,
+        minZoom: opts.min_zoom,
+        autoRotate: Boolean(opts.auto_rotate),
+        autoRotateSpeed: opts.auto_rotate,
+        enableDamping: Boolean(opts.rotation_damping),
+        dampingFactor: opts.rotation_damping,
+        onstart: () => {
+            opts.set_camera_is_moving?.(true);
+            opts.onstart_extra?.();
+        },
+        onend: () => opts.set_camera_is_moving?.(false),
+    };
+}

package/dist/scene/types.d.ts

@@ -0,0 +1,26 @@
+import type { CameraProjection } from '../settings';
+import type { Gizmo } from '@threlte/extras';
+import type { ComponentProps } from 'svelte';
+import type { Camera, Scene, Vector3 } from 'three';
+export type ThreltePointerEvent = {
+    point: Vector3;
+    nativeEvent: PointerEvent;
+};
+export type SceneControlProps = {
+    camera_projection?: CameraProjection;
+    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 Gizmo>;
+    auto_rotate?: number;
+    scene?: Scene;
+    camera?: Camera;
+};

package/dist/scene/types.js

@@ -0,0 +1 @@
+export {};