matterviz 0.4.0 → 0.4.2

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

@@ -1,4 +1,5 @@
 import type { PhaseData } from '../convex-hull/types';
+import { type FullscreenToggleProp } from '../layout';
 import type { ChemPotDiagramConfig, ChemPotHoverInfo } from './types';
 type $$ComponentProps = {
     entries: PhaseData[];
@@ -10,7 +11,12 @@ type $$ComponentProps = {
     max_interpolation_gap?: number;
     hover_info?: ChemPotHoverInfo | null;
     render_local_tooltip?: boolean;
+    wrapper?: HTMLDivElement;
+    fullscreen?: boolean;
+    fullscreen_toggle?: FullscreenToggleProp;
+    controls_open?: boolean;
+    export_pane_open?: boolean;
 };
-declare const ChemPotDiagram3D: import("svelte").Component<$$ComponentProps, {}, "temperature" | "height" | "width" | "hover_info">;
+declare const ChemPotDiagram3D: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "fullscreen" | "wrapper" | "controls_open" | "export_pane_open" | "temperature" | "hover_info">;
 type ChemPotDiagram3D = ReturnType<typeof ChemPotDiagram3D>;
 export default ChemPotDiagram3D;

package/dist/chempot-diagram/async-compute.svelte.js

@@ -68,7 +68,7 @@ export function compute_chempot_async(entries, config = {}) {
         pending.set(id, { resolve, reject });
         try {
             // $state.snapshot strips Svelte $state proxies (not structured-cloneable)
-            // eslint-disable-next-line unicorn/require-post-message-target-origin
+            // oxlint-disable-next-line unicorn/require-post-message-target-origin
             wkr.postMessage($state.snapshot({ id, entries, config }));
         }
         catch (err) {

package/dist/chempot-diagram/color.d.ts

@@ -1,10 +1,7 @@
 import { type D3InterpolateName } from '../colors';
-/** Resolve D3 interpolator with optional reverse for chempot color scales. */
-export declare function get_chempot_interpolator(name: D3InterpolateName, reverse: boolean): (t: number) => string;
-/** Build sequential color scale from values and D3 interpolator name. */
+import type { Vec2 } from '../math';
 export declare function make_chempot_color_scale(values: number[], interpolator_name: D3InterpolateName, reverse: boolean): ((val: number) => string) | null;
-/** Resolve color bar props for chempot diagrams (interpolator + domain). */
 export declare function get_chempot_color_bar_config(color_scale: D3InterpolateName, reverse: boolean): {
-    color_scale_fn: (t: number) => string;
-    color_scale_domain: [number, number];
+    color_scale_fn: (frac: number) => string;
+    color_scale_domain: Vec2;
 };

package/dist/chempot-diagram/color.js

@@ -1,11 +1,11 @@
 import { get_d3_interpolator } from '../colors';
 import { scaleSequential } from 'd3-scale';
-/** Resolve D3 interpolator with optional reverse for chempot color scales. */
-export function get_chempot_interpolator(name, reverse) {
+// Resolve D3 interpolator with optional reverse for chempot color scales.
+function get_chempot_interpolator(name, reverse) {
     const raw = get_d3_interpolator(name);
-    return reverse ? (t) => raw(1 - t) : raw;
+    return reverse ? (frac) => raw(1 - frac) : raw;
 }
-/** Build sequential color scale from values and D3 interpolator name. */
+// Build sequential color scale from values and D3 interpolator name.
 export function make_chempot_color_scale(values, interpolator_name, reverse) {
     const finite_values = values.filter(Number.isFinite);
     if (finite_values.length === 0)
@@ -23,7 +23,7 @@ export function make_chempot_color_scale(values, interpolator_name, reverse) {
         max_value,
     ]);
 }
-/** Resolve color bar props for chempot diagrams (interpolator + domain). */
+// Resolve color bar props for chempot diagrams (interpolator + domain).
 export function get_chempot_color_bar_config(color_scale, reverse) {
     return {
         color_scale_fn: get_chempot_interpolator(color_scale, reverse),

package/dist/chempot-diagram/compute.d.ts

@@ -1,4 +1,5 @@
 import type { PhaseData } from '../convex-hull/types';
+import type { Vec2 } from '../math';
 import { type ChemPotDiagramConfig, type ChemPotDiagramData } from './types';
 export declare function get_energy_per_atom(entry: PhaseData): number;
 export declare function formula_key_from_composition(composition: Record<string, number>): string;
@@ -6,14 +7,13 @@ export declare function get_min_entries_and_el_refs(entries: PhaseData[]): {
     min_entries: PhaseData[];
     el_refs: Record<string, PhaseData>;
 };
-export declare function compute_form_energy_per_atom(entry: PhaseData, el_refs: Record<string, PhaseData>): number;
 export declare function best_form_energy_for_formula(entries: PhaseData[], formula: string, el_refs: Record<string, PhaseData>): number | undefined;
 export declare const renormalize_entries: (entries: PhaseData[], el_refs: Record<string, PhaseData>, elements: string[]) => PhaseData[];
 export declare function build_hyperplanes(min_entries: PhaseData[], el_refs: Record<string, PhaseData>, elements: string[]): {
     hyperplanes: number[][];
     hyperplane_entries: PhaseData[];
 };
-export declare function build_border_hyperplanes(lims: [number, number][]): number[][];
+export declare function build_border_hyperplanes(lims: Vec2[]): number[][];
 export declare function compute_domains(hyperplanes: number[][], border_hyperplanes: number[][], hyperplane_entries: PhaseData[], dim: number): Record<string, number[][]>;
 export declare function apply_element_padding(domains: Record<string, number[][]>, elem_indices: number[], padding: number, default_min_limit: number): number[];
 export declare function pad_domain_points(pts: number[][], elem_indices: number[], new_lims: number[], default_min_limit: number, padding: number): number[][];
@@ -26,7 +26,7 @@ export declare function simple_pca(data: number[][], k?: number): {
     scores: number[][];
     eigenvectors: number[][];
 };
-export declare function orthonormal_2d(line_pts: number[][]): [number, number];
+export declare function orthonormal_2d(line_pts: number[][]): Vec2;
 export declare function dedup_points(pts: number[][], tol?: number): {
     unique: number[][];
     orig_indices: number[];

package/dist/chempot-diagram/compute.js

@@ -84,7 +84,9 @@ export function get_min_entries_and_el_refs(entries) {
     return { min_entries, el_refs };
 }
 // Compute formation energy per atom against elemental references.
-export function compute_form_energy_per_atom(entry, el_refs) {
+// NOTE: diverges from convex-hull's compute_e_form_per_atom (which returns null on
+// missing refs); kept module-private so the divergent variant can't leak into public API.
+function compute_form_energy_per_atom(entry, el_refs) {
     const atom_count = count_atoms_in_composition(entry.composition);
     const energy_per_atom = get_energy_per_atom(entry);
     let ref_energy = 0;

package/dist/chempot-diagram/controls-state.svelte.d.ts

@@ -0,0 +1,10 @@
+import { type ChemPotDiagramConfig } from './types';
+export declare function create_chempot_overrides<Key extends keyof ChemPotDiagramConfig>(config: () => ChemPotDiagramConfig, keys: readonly Key[], custom_defaults?: {
+    [P in Key]?: NonNullable<ChemPotDiagramConfig[P]>;
+}): {
+    resolve: <P extends Key>(key: P) => NonNullable<ChemPotDiagramConfig[P]>;
+    set: <P extends Key>(key: P, value: NonNullable<ChemPotDiagramConfig[P]>) => void;
+    reset: () => void;
+};
+export declare const CHEMPOT_COLOR_MODE_OPTIONS: readonly [readonly ["none", "None"], readonly ["energy", "Energy/atom"], readonly ["formation_energy", "Formation energy"], readonly ["arity", "Element count"], readonly ["entries", "Entry count"]];
+export declare const CHEMPOT_COLOR_SCALE_OPTIONS: readonly [readonly ["interpolateViridis", "Viridis"], readonly ["interpolatePlasma", "Plasma"], readonly ["interpolateInferno", "Inferno"], readonly ["interpolateMagma", "Magma"], readonly ["interpolateCividis", "Cividis"], readonly ["interpolateTurbo", "Turbo"], readonly ["interpolateRdYlBu", "RdYlBu"], readonly ["interpolateSpectral", "Spectral"]];

package/dist/chempot-diagram/controls-state.svelte.js

@@ -0,0 +1,42 @@
+// Override state + shared <option> lists for the ChemPotDiagram2D/3D control panes
+import { CHEMPOT_DEFAULTS } from './types';
+// Per-key user overrides with `override ?? config ?? default` resolution; `reset()`
+// clears all overrides (the panes' "Reset defaults" buttons). Defaults come from
+// CHEMPOT_DEFAULTS unless overridden via custom_defaults; keys without either throw upfront.
+export function create_chempot_overrides(config, keys, custom_defaults = {}) {
+    const defaults = Object.fromEntries(keys.map((key) => {
+        const fallback = custom_defaults[key] ?? CHEMPOT_DEFAULTS[key];
+        if (fallback === undefined) {
+            throw new Error(`create_chempot_overrides: key '${key}' is missing from both custom_defaults and CHEMPOT_DEFAULTS`);
+        }
+        return [key, fallback];
+    }));
+    let overrides = $state({});
+    return {
+        resolve: (key) => overrides[key] ?? config()[key] ?? defaults[key],
+        set: (key, value) => {
+            overrides[key] = value;
+        },
+        reset: () => {
+            overrides = {};
+        },
+    };
+}
+// [value, label] pairs for the color-mode and color-scale <select>s in both panes
+export const CHEMPOT_COLOR_MODE_OPTIONS = [
+    [`none`, `None`],
+    [`energy`, `Energy/atom`],
+    [`formation_energy`, `Formation energy`],
+    [`arity`, `Element count`],
+    [`entries`, `Entry count`],
+];
+export const CHEMPOT_COLOR_SCALE_OPTIONS = [
+    [`interpolateViridis`, `Viridis`],
+    [`interpolatePlasma`, `Plasma`],
+    [`interpolateInferno`, `Inferno`],
+    [`interpolateMagma`, `Magma`],
+    [`interpolateCividis`, `Cividis`],
+    [`interpolateTurbo`, `Turbo`],
+    [`interpolateRdYlBu`, `RdYlBu`],
+    [`interpolateSpectral`, `Spectral`],
+];

package/dist/chempot-diagram/export.d.ts

@@ -0,0 +1,47 @@
+import * as THREE from 'three';
+export declare const get_json_string: (payload: unknown) => string;
+export declare const export_json_file: (payload: unknown, basename: string) => void;
+interface XYZ {
+    x: number;
+    y: number;
+    z: number;
+}
+export declare function get_view_settings(opts: {
+    elements: string[];
+    camera_projection: string;
+    auto_rotate: number;
+    color_mode: string;
+    color_scale: string;
+    reverse_color_scale: boolean;
+    camera_position?: XYZ | null;
+    camera_target?: XYZ | null;
+}): Record<string, unknown>;
+export declare const export_view_json_file: (view_settings: Record<string, unknown>, basename: string) => void;
+export interface OverlayTextItem {
+    x: number;
+    y: number;
+    text: string;
+    font: string;
+    font_size: string;
+    font_family: string;
+    font_weight: string;
+    color: string;
+}
+export declare function get_overlay_text_items(wrapper: HTMLElement, canvas_rect: DOMRect): OverlayTextItem[];
+export declare function export_png_file(wrapper: HTMLElement | undefined, basename: string, png_dpi: number): void;
+export declare function export_svg_file(wrapper: HTMLElement | undefined, basename: string, view_settings: Record<string, unknown>): void;
+export interface ChemPotGlbParts {
+    hull_geometry?: THREE.BufferGeometry | null;
+    hull_opacity?: number;
+    edge_geometry: THREE.BufferGeometry;
+    formula_meshes?: {
+        geometry: THREE.BufferGeometry;
+        color: string;
+    }[];
+    formula_edges?: {
+        geometry: THREE.BufferGeometry;
+        color: string;
+    }[];
+}
+export declare function export_glb_file(parts: ChemPotGlbParts, basename: string): void;
+export {};

package/dist/chempot-diagram/export.js

@@ -0,0 +1,133 @@
+// Export helpers for chemical potential diagrams (shared between 2D and 3D views).
+import { dpi_to_scale } from '../io/export';
+import { download } from '../io/fetch';
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
+export const get_json_string = (payload) => JSON.stringify(payload, null, 2);
+const download_json = (payload, filename) => download(get_json_string(payload), filename, `application/json`);
+export const export_json_file = (payload, basename) => download_json(payload, `${basename}.json`);
+const xyz_tuple = (point) => point ? [point.x, point.y, point.z] : null;
+const get_gl_canvas = (wrapper) => {
+    const canvas = wrapper?.querySelector(`canvas`);
+    return canvas instanceof HTMLCanvasElement ? canvas : null;
+};
+// Serializable snapshot of the current 3D view (embedded in SVG/JSON exports)
+export function get_view_settings(opts) {
+    const { camera_position, camera_target, ...settings } = opts;
+    return {
+        ...settings,
+        camera_position: xyz_tuple(camera_position),
+        camera_target: xyz_tuple(camera_target),
+    };
+}
+export const export_view_json_file = (view_settings, basename) => download_json(view_settings, `${basename}-view.json`);
+// Collect HTML overlay text (tick/axis/domain labels) positioned relative to the canvas
+export function get_overlay_text_items(wrapper, canvas_rect) {
+    const text_items = [];
+    for (const element of wrapper.querySelectorAll(`.tick-label, .axis-label, .domain-label`)) {
+        const html_element = element;
+        const style = getComputedStyle(html_element);
+        if (style.display === `none` || style.visibility === `hidden`)
+            continue;
+        const element_rect = html_element.getBoundingClientRect();
+        text_items.push({
+            x: element_rect.left + element_rect.width / 2 - canvas_rect.left,
+            y: element_rect.top + element_rect.height / 2 - canvas_rect.top,
+            text: html_element.textContent ?? ``,
+            font: style.font || `${style.fontSize} ${style.fontFamily}`,
+            font_size: style.fontSize || `11px`,
+            font_family: style.fontFamily || `sans-serif`,
+            font_weight: style.fontWeight || `400`,
+            color: style.color || `#333`,
+        });
+    }
+    return text_items;
+}
+// Composite the WebGL canvas + HTML overlay labels into a single PNG download
+export function export_png_file(wrapper, basename, png_dpi) {
+    const gl_canvas = get_gl_canvas(wrapper);
+    if (!gl_canvas || !wrapper)
+        return;
+    const rect = gl_canvas.getBoundingClientRect();
+    // A degenerate rect means the canvas is hidden/unrendered: nothing to capture
+    if (!(rect.width > 0) || !(rect.height > 0)) {
+        console.error(`Cannot export PNG: canvas has zero size (width=${rect.width}, height=${rect.height})`);
+        return;
+    }
+    const scale = dpi_to_scale(png_dpi);
+    const out = document.createElement(`canvas`);
+    // Floor at 1px so tiny rect x min-DPI rounding can't yield an invalid 0x0 canvas
+    out.width = Math.max(1, Math.round(rect.width * scale));
+    out.height = Math.max(1, Math.round(rect.height * scale));
+    const ctx = out.getContext(`2d`);
+    if (!ctx)
+        return;
+    ctx.scale(scale, scale);
+    ctx.drawImage(gl_canvas, 0, 0, rect.width, rect.height);
+    for (const text_item of get_overlay_text_items(wrapper, rect)) {
+        ctx.font = text_item.font;
+        ctx.fillStyle = text_item.color;
+        ctx.textAlign = `center`;
+        ctx.textBaseline = `middle`;
+        ctx.fillText(text_item.text, text_item.x, text_item.y);
+    }
+    out.toBlob((blob) => {
+        if (!blob)
+            return;
+        download(blob, `${basename}.png`, `image/png`);
+    }, `image/png`);
+}
+const xml_escape = (text) => text
+    .replaceAll(`&`, `&`)
+    .replaceAll(`<`, `&lt;`)
+    .replaceAll(`>`, `&gt;`)
+    .replaceAll(`"`, `&quot;`)
+    .replaceAll(`'`, `&#39;`);
+// SVG snapshot: rasterized canvas as embedded image + overlay labels as real text nodes
+export function export_svg_file(wrapper, basename, view_settings) {
+    const gl_canvas = get_gl_canvas(wrapper);
+    if (!gl_canvas || !wrapper)
+        return;
+    const canvas_rect = gl_canvas.getBoundingClientRect();
+    if (canvas_rect.width === 0 || canvas_rect.height === 0)
+        return;
+    const png_data_url = gl_canvas.toDataURL(`image/png`);
+    const text_nodes = get_overlay_text_items(wrapper, canvas_rect).map((text_item) => `<text x="${text_item.x.toFixed(2)}" y="${text_item.y.toFixed(2)}" text-anchor="middle" dominant-baseline="central" fill="${xml_escape(text_item.color)}" font-size="${xml_escape(text_item.font_size)}" font-family="${xml_escape(text_item.font_family)}" font-weight="${xml_escape(text_item.font_weight)}">${xml_escape(text_item.text)}</text>`);
+    const metadata = xml_escape(JSON.stringify(view_settings));
+    const svg = [
+        `<?xml version="1.0" encoding="UTF-8"?>`,
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${canvas_rect.width}" height="${canvas_rect.height}" viewBox="0 0 ${canvas_rect.width} ${canvas_rect.height}">`,
+        `<metadata>${metadata}</metadata>`,
+        `<image href="${png_data_url}" x="0" y="0" width="${canvas_rect.width}" height="${canvas_rect.height}" />`,
+        ...text_nodes,
+        `</svg>`,
+    ].join(``);
+    download(svg, `${basename}.svg`, `image/svg+xml`);
+}
+// Rebuild the scene from its geometries and export as binary GLTF
+export function export_glb_file(parts, basename) {
+    const { hull_geometry, hull_opacity = 0.25, edge_geometry, formula_meshes = [], formula_edges = [], } = parts;
+    const gltf_exporter = new GLTFExporter();
+    const export_root = new THREE.Group();
+    const add_mesh = (geometry, material) => {
+        const opts = { transparent: true, side: THREE.DoubleSide, ...material };
+        export_root.add(new THREE.Mesh(geometry.clone(), new THREE.MeshBasicMaterial(opts)));
+    };
+    const add_lines = (geometry, color) => {
+        export_root.add(new THREE.LineSegments(geometry.clone(), new THREE.LineBasicMaterial({ color })));
+    };
+    if (hull_geometry)
+        add_mesh(hull_geometry, { vertexColors: true, opacity: hull_opacity });
+    add_lines(edge_geometry, 0x333333);
+    for (const { geometry, color } of formula_meshes) {
+        add_mesh(geometry, { color: new THREE.Color(color), opacity: 0.13 });
+    }
+    for (const { geometry, color } of formula_edges) {
+        add_lines(geometry, new THREE.Color(color));
+    }
+    gltf_exporter.parse(export_root, (result) => {
+        if (!(result instanceof ArrayBuffer))
+            return;
+        download(result, `${basename}.glb`, `model/gltf-binary`);
+    }, (err) => console.error(`Failed to export GLB:`, err), { binary: true, onlyVisible: false });
+}

package/dist/chempot-diagram/index.d.ts

@@ -3,4 +3,5 @@ export { default as ChemPotDiagram2D } from './ChemPotDiagram2D.svelte';
 export { default as ChemPotDiagram3D } from './ChemPotDiagram3D.svelte';
 export { compute_chempot_async } from './async-compute.svelte';
 export { compute_chempot_diagram, get_ternary_combinations } from './compute';
+export * from './export';
 export * from './types';

package/dist/chempot-diagram/index.js

@@ -3,4 +3,5 @@ export { default as ChemPotDiagram2D } from './ChemPotDiagram2D.svelte';
 export { default as ChemPotDiagram3D } from './ChemPotDiagram3D.svelte';
 export { compute_chempot_async } from './async-compute.svelte';
 export { compute_chempot_diagram, get_ternary_combinations } from './compute';
+export * from './export';
 export * from './types';

package/dist/chempot-diagram/pointer.d.ts

@@ -1,13 +1,3 @@
-export declare function get_pointer_coords(raw_event: unknown): {
-    clientX: number;
-    clientY: number;
-} | null;
-/** Convert pointer event to container-relative coords for tooltip placement. */
-export declare function get_hover_pointer(raw_event: unknown, container_rect: DOMRect | null | undefined): {
-    x: number;
-    y: number;
-} | null;
-/** Add hover pointer to an info object for tooltip placement. */
 export declare function with_hover_pointer<T extends {
     pointer?: {
         x: number;

package/dist/chempot-diagram/pointer.js

@@ -2,7 +2,7 @@
 // Handles DOM events and Threlte/Three.js event wrappers (nativeEvent, srcEvent).
 const is_pointer_like_event = (event_val) => (typeof PointerEvent !== `undefined` && event_val instanceof PointerEvent) ||
     (typeof MouseEvent !== `undefined` && event_val instanceof MouseEvent);
-export function get_pointer_coords(raw_event) {
+function get_pointer_coords(raw_event) {
     if (is_pointer_like_event(raw_event)) {
         return raw_event;
     }
@@ -22,8 +22,8 @@ export function get_pointer_coords(raw_event) {
     }
     return null;
 }
-/** Convert pointer event to container-relative coords for tooltip placement. */
-export function get_hover_pointer(raw_event, container_rect) {
+// Convert pointer event to container-relative coords for tooltip placement.
+function get_hover_pointer(raw_event, container_rect) {
     const pointer_event = get_pointer_coords(raw_event);
     if (!pointer_event)
         return null;
@@ -33,7 +33,7 @@ export function get_hover_pointer(raw_event, container_rect) {
     const y = pointer_event.clientY - offset_y + 4;
     return { x, y };
 }
-/** Add hover pointer to an info object for tooltip placement. */
+// Add hover pointer to an info object for tooltip placement.
 export function with_hover_pointer(info, raw_event, container_rect) {
     const pointer = get_hover_pointer(raw_event, container_rect);
     return { ...info, pointer: pointer ?? undefined };

package/dist/chempot-diagram/types.d.ts

@@ -1,7 +1,7 @@
 import type { D3InterpolateName } from '../colors';
 import type { PhaseData } from '../convex-hull/types';
-import type { Point2D } from '../math';
-export type ChemPotLimits = Partial<Record<string, [number, number]>>;
+import type { Point2D, Vec2 } from '../math';
+export type ChemPotLimits = Partial<Record<string, Vec2>>;
 export type ChemPotColorMode = `none` | `energy` | `formation_energy` | `arity` | `entries`;
 export type ChemPotProjectionMode = `single` | `grid`;
 export interface ChemPotDiagramConfig {
@@ -31,7 +31,7 @@ export interface ChemPotDiagramData {
     min_entries: PhaseData[];
     hyperplanes: number[][];
     hyperplane_entries: PhaseData[];
-    lims: [number, number][];
+    lims: Vec2[];
 }
 export interface ChemPotHoverInfoBase {
     formula: string;

package/dist/colors/index.d.ts

@@ -1,6 +1,4 @@
 import * as d3_sc from 'd3-scale-chromatic';
-import type { Vec3 } from '../math';
-import type { ELEM_SYMBOLS } from '../labels';
 export type D3InterpolateName = keyof typeof d3_sc & `interpolate${string}`;
 export type D3ColorSchemeName = D3InterpolateName extends `interpolate${infer Name}` ? Name : never;
 export declare const get_d3_interpolator: (name: D3InterpolateName) => ((t: number) => string);
@@ -9,8 +7,6 @@ export type ColorScaleType = (typeof COLOR_SCALE_TYPES)[number];
 export declare const DEFAULT_CATEGORY_COLORS: Record<string, string>;
 export declare const AXIS_COLORS: readonly [readonly ["x", "#d75555", "#e66666"], readonly ["y", "#55b855", "#66c966"], readonly ["z", "#5555d7", "#6666e6"]];
 export declare const NEG_AXIS_COLORS: readonly [readonly ["nx", "#b84444", "#cc5555"], readonly ["ny", "#44a044", "#55b155"], readonly ["nz", "#4444b8", "#5555c9"]];
-export type RGBColor = Vec3;
-export type ElementColorScheme = Record<(typeof ELEM_SYMBOLS)[number], RGBColor>;
 export declare const vesta_hex: Record<string, string>;
 export declare const jmol_hex: Record<string, string>;
 export declare const alloy_hex: Record<string, string>;

package/dist/colors/index.js

@@ -1,5 +1,7 @@
 import { color as d3_color, rgb } from 'd3-color';
 import * as d3_sc from 'd3-scale-chromatic';
+import { COLOR_THEMES, get_system_mode, get_theme_preference, is_valid_theme_name, resolve_theme_mode, THEME_STORAGE_KEY, THEME_TYPE, } from '../theme';
+import { clamp01 } from '../utils';
 import alloy_colors from './alloy-colors.json' with { type: 'json' };
 import dark_mode_colors from './dark-mode-colors.json' with { type: 'json' };
 import jmol_colors from './jmol-colors.json' with { type: 'json' };
@@ -79,19 +81,20 @@ export const PLOT_COLORS = [
 ];
 // calculate human-perceived brightness from RGB color
 export function luminance(clr) {
-    const { r, g, b } = rgb(clr);
-    return (0.299 * r + 0.587 * g + 0.114 * b) / 255; // https://stackoverflow.com/a/596243
+    const { r: red, g: green, b: blue } = rgb(clr);
+    return (0.299 * red + 0.587 * green + 0.114 * blue) / 255; // https://stackoverflow.com/a/596243
 }
+// CSS color string for a fully transparent background
+const NO_BG = `rgba(0, 0, 0, 0)`;
 // get background color of passed DOM node, or recurse up the DOM tree if current node is transparent
 export function get_bg_color(elem, bg_color = null) {
     if (bg_color)
         return bg_color;
     // recurse up the DOM tree to find the first non-transparent background color
-    const transparent = `rgba(0, 0, 0, 0)`;
     if (!elem)
-        return transparent; // if no DOM node, return transparent
+        return NO_BG; // if no DOM node, return transparent
     const bg = getComputedStyle(elem).backgroundColor; // get node background color
-    if (bg !== transparent)
+    if (bg !== NO_BG)
         return bg; // if not transparent, return it
     return get_bg_color(elem.parentElement); // otherwise recurse up the DOM tree
 }
@@ -104,7 +107,7 @@ export function pick_contrast_color(options = {}) {
 export const contrast_color = (options = {}) => (node) => {
     node.style.color = pick_contrast_color({ ...options, bg_color: get_bg_color(node) });
 };
-const is_valid_bg = (bg) => bg !== `` && bg !== `rgba(0, 0, 0, 0)` && bg !== `transparent`;
+const is_valid_bg = (bg) => bg !== `` && bg !== NO_BG && bg !== `transparent`;
 // Detect and return the page background color from html/body elements or user preferences
 export function get_page_background(fallback_dark = `#1a1a1a`, fallback_light = `#ffffff`) {
     if (typeof window === `undefined`)
@@ -119,25 +122,21 @@ export function get_page_background(fallback_dark = `#1a1a1a`, fallback_light =
     if (is_valid_bg(html_bg))
         return html_bg;
     // Fall back to prefers-color-scheme
-    const prefers_dark = globalThis.matchMedia(`(prefers-color-scheme: dark)`).matches;
+    const prefers_dark = globalThis.matchMedia?.(`(prefers-color-scheme: dark)`)?.matches;
     return prefers_dark ? fallback_dark : fallback_light;
 }
-// Detect dark mode: checks data-theme attribute, localStorage, then OS preference
+// Detect dark mode: checks data-theme attribute, then the persisted theme
+// preference (resolving `auto` against the OS), then falls back to OS preference.
 export function is_dark_mode() {
     if (typeof document === `undefined`)
         return false;
+    // Prefer the resolved theme name on data-theme (light/dark/white/black), else
+    // fall back to the persisted preference (resolving `auto` against the OS)
     const data_theme = document.documentElement.dataset.theme;
-    if (data_theme === `dark` || data_theme === `light`)
-        return data_theme === `dark`;
-    try {
-        const stored = localStorage.getItem(`theme`);
-        if (stored === `dark` || stored === `light`)
-            return stored === `dark`;
-    }
-    catch {
-        /* localStorage throws in private browsing mode */
-    }
-    return globalThis.matchMedia?.(`(prefers-color-scheme: dark)`).matches ?? false;
+    const theme_name = data_theme && is_valid_theme_name(data_theme)
+        ? data_theme
+        : resolve_theme_mode(get_theme_preference(), get_system_mode());
+    return THEME_TYPE[theme_name] === COLOR_THEMES.dark;
 }
 // Watch for dark mode changes and call callback on each change. Returns cleanup function.
 export function watch_dark_mode(on_change) {
@@ -149,8 +148,8 @@ export function watch_dark_mode(on_change) {
         attributes: true,
         attributeFilter: [`data-theme`],
     });
-    const on_storage = (ev) => {
-        if (ev.key === `theme`)
+    const on_storage = (event) => {
+        if (event.key === THEME_STORAGE_KEY)
             notify();
     };
     globalThis.addEventListener(`storage`, on_storage);
@@ -178,7 +177,7 @@ export function css_color_to_hex(color, fallback) {
 // Returns the color in rgba() format, or the original color if format is unsupported.
 export function add_alpha(color, alpha) {
     // Clamp alpha to valid CSS range [0, 1]
-    const clamped_alpha = Math.max(0, Math.min(1, alpha));
+    const clamped_alpha = clamp01(alpha);
     // Handle hex colors (#rgb, #rgba, #rrggbb, #rrggbbaa)
     if (color.startsWith(`#`)) {
         const hex = color.slice(1);