matterviz 0.4.1 → 0.4.3

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

@@ -17,6 +17,6 @@ type $$ComponentProps = {
     controls_open?: boolean;
     export_pane_open?: boolean;
 };
-declare const ChemPotDiagram3D: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "temperature" | "fullscreen" | "wrapper" | "controls_open" | "export_pane_open" | "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

@@ -1,24 +1,13 @@
 // Async wrapper for compute_chempot_diagram via Web Worker.
 // Falls back to synchronous main-thread computation during SSR.
-import { compute_chempot_diagram, formula_key_from_composition } from './compute';
+import { compute_chempot_diagram, entry_fingerprint } from './compute';
 import { to_error } from '../utils';
 let worker = null;
 let next_id = 0;
 const pending = new Map();
 const pending_by_key = new Map();
 function make_compute_request_key(entries, config) {
-    const keyed_entries = entries
-        .map((entry) => [
-        formula_key_from_composition(entry.composition),
-        entry.energy,
-        entry.energy_per_atom ?? ``,
-        entry.e_form_per_atom ?? ``,
-        entry.is_stable ?? ``,
-        entry.e_above_hull ?? ``,
-        entry.exclude_from_hull ?? ``,
-    ].join(`:`))
-        .sort();
-    return `${keyed_entries.join(`,`)}|${JSON.stringify(config)}`;
+    return `${entries.map(entry_fingerprint).sort().join(`,`)}|${JSON.stringify(config)}`;
 }
 function track_pending(request_key, promise) {
     pending_by_key.set(request_key, promise);
@@ -53,6 +42,16 @@ function get_worker() {
     return worker;
 }
 export function compute_chempot_async(entries, config = {}) {
+    // Never throw synchronously: callers handle errors via .catch() only, so key
+    // construction or Worker instantiation failures (e.g. CSP) must reject instead
+    try {
+        return compute_chempot_async_unsafe(entries, config);
+    }
+    catch (err) {
+        return Promise.reject(to_error(err));
+    }
+}
+function compute_chempot_async_unsafe(entries, config) {
     const request_key = make_compute_request_key(entries, config);
     const existing = pending_by_key.get(request_key);
     if (existing)
@@ -68,7 +67,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,7 +1,27 @@
 import { type D3InterpolateName } from '../colors';
+import type { PhaseData } from '../convex-hull/types';
 import type { Vec2 } from '../math';
-export declare function make_chempot_color_scale(values: number[], interpolator_name: D3InterpolateName, reverse: boolean): ((val: number) => string) | null;
+import { type FormulaEnergyStats } from './compute';
+import type { ChemPotColorMode } from './types';
+export declare const ARITY_COLORS: readonly ["#3498db", "#2ecc71", "#e67e22", "#9b59b6"];
 export declare function get_chempot_color_bar_config(color_scale: D3InterpolateName, reverse: boolean): {
     color_scale_fn: (frac: number) => string;
     color_scale_domain: Vec2;
 };
+export interface ChemPotDomainColorData {
+    colors: Map<string, string>;
+    color_range: {
+        min: number;
+        max: number;
+        label: string;
+    } | null;
+}
+export declare function get_domain_color_data(opts: {
+    formulas: string[];
+    color_mode: ChemPotColorMode;
+    color_scale: D3InterpolateName;
+    reverse_color_scale: boolean;
+    entries: PhaseData[];
+    el_refs: Record<string, PhaseData>;
+    energy_stats: Map<string, FormulaEnergyStats>;
+}): ChemPotDomainColorData;

package/dist/chempot-diagram/color.js

@@ -1,12 +1,24 @@
 import { get_d3_interpolator } from '../colors';
+import { extract_formula_elements } from '../composition/parse';
+import { group } from 'd3-array';
 import { scaleSequential } from 'd3-scale';
+import { best_form_energy_for_formula as best_form_energy, formula_key_from_composition, } from './compute';
+// Categorical palette for arity mode (element count)
+export const ARITY_COLORS = [`#3498db`, `#2ecc71`, `#e67e22`, `#9b59b6`];
+// Exhaustively typed over the numeric color modes so adding a new mode
+// fails compilation here instead of rendering an undefined colorbar title
+const COLOR_MODE_LABELS = {
+    energy: `Energy per atom (eV)`,
+    formation_energy: `Formation energy (eV/atom)`,
+    entries: `Entry count`,
+};
 // Resolve D3 interpolator with optional reverse for chempot color scales.
 function get_chempot_interpolator(name, reverse) {
     const raw = get_d3_interpolator(name);
     return reverse ? (frac) => raw(1 - frac) : raw;
 }
 // Build sequential color scale from values and D3 interpolator name.
-export function make_chempot_color_scale(values, interpolator_name, reverse) {
+function make_chempot_color_scale(values, interpolator_name, reverse) {
     const finite_values = values.filter(Number.isFinite);
     if (finite_values.length === 0)
         return null;
@@ -30,3 +42,60 @@ export function get_chempot_color_bar_config(color_scale, reverse) {
         color_scale_domain: [0, 1],
     };
 }
+// Per-formula domain colors plus color-bar range for the active color mode.
+// Shared by ChemPotDiagram2D and ChemPotDiagram3D.
+export function get_domain_color_data(opts) {
+    const { formulas, color_mode, entries, el_refs, energy_stats } = opts;
+    const colors = new Map();
+    if (color_mode === `none`)
+        return { colors, color_range: null };
+    if (color_mode === `arity`) {
+        for (const formula of formulas) {
+            const n_elements = extract_formula_elements(formula).length;
+            const color_idx = Math.min(n_elements, ARITY_COLORS.length) - 1;
+            colors.set(formula, ARITY_COLORS[Math.max(0, color_idx)]);
+        }
+        return { colors, color_range: null };
+    }
+    const entries_by_formula = color_mode === `formation_energy`
+        ? group(entries, (entry) => formula_key_from_composition(entry.composition))
+        : new Map();
+    const get_value = (formula) => {
+        if (color_mode === `energy`)
+            return energy_stats.get(formula)?.min_energy_per_atom ?? null;
+        if (color_mode === `formation_energy`) {
+            return best_form_energy(entries_by_formula.get(formula) ?? [], formula, el_refs) ?? null;
+        }
+        return energy_stats.get(formula)?.matching_entry_count ?? 0;
+    };
+    const value_by_formula = new Map();
+    for (const formula of formulas) {
+        const value = get_value(formula);
+        if (value == null || !Number.isFinite(value))
+            continue;
+        value_by_formula.set(formula, value);
+    }
+    const values = [...value_by_formula.values()];
+    const scale = make_chempot_color_scale(values, opts.color_scale, opts.reverse_color_scale);
+    for (const formula of formulas) {
+        const value = value_by_formula.get(formula);
+        colors.set(formula, value != null && scale ? scale(value) : `#999`);
+    }
+    if (values.length === 0)
+        return { colors, color_range: null };
+    let [min_val, max_val] = [values[0], values[0]];
+    for (const value of values) {
+        if (value < min_val)
+            min_val = value;
+        if (value > max_val)
+            max_val = value;
+    }
+    return {
+        colors,
+        color_range: {
+            min: min_val,
+            max: Math.max(max_val, min_val + 1e-6),
+            label: COLOR_MODE_LABELS[color_mode],
+        },
+    };
+}

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

@@ -8,6 +8,12 @@ export declare function get_min_entries_and_el_refs(entries: PhaseData[]): {
     el_refs: Record<string, PhaseData>;
 };
 export declare function best_form_energy_for_formula(entries: PhaseData[], formula: string, el_refs: Record<string, PhaseData>): number | undefined;
+export interface FormulaEnergyStats {
+    matching_entry_count: number;
+    min_energy_per_atom: number | null;
+    max_energy_per_atom: number | null;
+}
+export declare function get_energy_stats_by_formula(entries: PhaseData[]): Map<string, FormulaEnergyStats>;
 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[][];
@@ -44,5 +50,6 @@ export interface VisibleDomainLabel {
 }
 export declare function get_visible_domain_labels(face_positions: ArrayLike<number>, face_domain_map: string[], label_font_size_by_formula: ReadonlyMap<string, number>, pinned_labels?: VisibleDomainLabel[]): VisibleDomainLabel[];
 export declare function get_ternary_combinations(elements: string[]): string[][];
+export declare function entry_fingerprint(entry: PhaseData): string;
 export declare function make_nd_cache_key(entries: PhaseData[], formal_chempots: boolean, default_min_limit: number, limits: ChemPotDiagramConfig[`limits`]): string;
 export declare function compute_chempot_diagram(entries: PhaseData[], config?: ChemPotDiagramConfig): ChemPotDiagramData;

package/dist/chempot-diagram/compute.js

@@ -34,16 +34,28 @@ const get_reduced_formula = (composition) => {
         .map(([elem, amt]) => [elem, Math.round(amt * factor)]));
 };
 // === Entry Helpers ===
-// Get energy per atom for a PhaseData entry
+// Energy per atom; NaN for invalid/non-finite so UI can skip without throwing.
 export function get_energy_per_atom(entry) {
-    if (typeof entry.energy_per_atom === `number`)
-        return entry.energy_per_atom;
-    const atoms = count_atoms_in_composition(entry.composition);
-    if (atoms <= 0) {
-        throw new Error(`Invalid composition with non-positive atom count: ${JSON.stringify(entry.composition)}`);
+    if (typeof entry.energy_per_atom === `number`) {
+        return Number.isFinite(entry.energy_per_atom) ? entry.energy_per_atom : Number.NaN;
     }
+    const atoms = count_atoms_in_composition(entry.composition);
+    if (atoms <= 0 || !Number.isFinite(entry.energy))
+        return Number.NaN;
     return entry.energy / atoms;
 }
+// Same-formula EPA total order (keep aligned with make_nd_cache_key / entry_fingerprint).
+function prefer_min_entry(candidate, candidate_epa, existing, existing_epa) {
+    if (candidate_epa !== existing_epa)
+        return candidate_epa < existing_epa;
+    if (Boolean(candidate.exclude_from_hull) !== Boolean(existing.exclude_from_hull)) {
+        return !candidate.exclude_from_hull;
+    }
+    if ((candidate.is_stable === true) !== (existing.is_stable === true)) {
+        return candidate.is_stable === true;
+    }
+    return (candidate.e_above_hull ?? Infinity) < (existing.e_above_hull ?? Infinity);
+}
 // Cache for reduced formula strings -- avoids recomputing get_reduced_formula
 // in hot loops. Key is object identity (WeakMap), value is the formula string.
 const formula_cache = new WeakMap();
@@ -69,8 +81,10 @@ export function get_min_entries_and_el_refs(entries) {
     for (const entry of entries) {
         const key = formula_key_from_composition(entry.composition);
         const epa = get_energy_per_atom(entry);
+        if (!Number.isFinite(epa))
+            continue;
         const existing = by_formula.get(key);
-        if (!existing || epa < existing.epa) {
+        if (!existing || prefer_min_entry(entry, epa, existing.entry, existing.epa)) {
             by_formula.set(key, { entry, epa });
         }
     }
@@ -89,14 +103,20 @@ export function get_min_entries_and_el_refs(entries) {
 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);
+    if (!(atom_count > 0) || !Number.isFinite(energy_per_atom))
+        return Number.NaN;
     let ref_energy = 0;
     for (const [element, amount] of Object.entries(entry.composition)) {
         if (amount <= 0)
             continue;
         const fraction = amount / atom_count;
         const ref_entry = el_refs[element];
-        if (ref_entry)
-            ref_energy += fraction * get_energy_per_atom(ref_entry);
+        if (ref_entry) {
+            const ref_epa = get_energy_per_atom(ref_entry);
+            if (!Number.isFinite(ref_epa))
+                return Number.NaN;
+            ref_energy += fraction * ref_epa;
+        }
     }
     return energy_per_atom - ref_energy;
 }
@@ -107,23 +127,57 @@ export function best_form_energy_for_formula(entries, formula, el_refs) {
         if (formula_key_from_composition(entry.composition) !== formula)
             continue;
         const e_form = entry.e_form_per_atom ?? compute_form_energy_per_atom(entry, el_refs);
+        if (!Number.isFinite(e_form))
+            continue;
         if (best_value === undefined || e_form < best_value)
             best_value = e_form;
     }
     return best_value;
 }
+// Aggregate per-formula entry count and min/max energy per atom (used for
+// region coloring and hover tooltips in the 2D/3D diagram components).
+export function get_energy_stats_by_formula(entries) {
+    const stats = new Map();
+    for (const entry of entries) {
+        const energy_per_atom = get_energy_per_atom(entry);
+        if (!Number.isFinite(energy_per_atom))
+            continue;
+        const formula_key = formula_key_from_composition(entry.composition);
+        const existing = stats.get(formula_key);
+        if (existing) {
+            existing.matching_entry_count += 1;
+            existing.min_energy_per_atom = Math.min(existing.min_energy_per_atom ?? energy_per_atom, energy_per_atom);
+            existing.max_energy_per_atom = Math.max(existing.max_energy_per_atom ?? energy_per_atom, energy_per_atom);
+        }
+        else {
+            stats.set(formula_key, {
+                matching_entry_count: 1,
+                min_energy_per_atom: energy_per_atom,
+                max_energy_per_atom: energy_per_atom,
+            });
+        }
+    }
+    return stats;
+}
 // Renormalize entry energies to be relative to elemental references (formal chemical potentials).
 // For each entry, subtracts sum(x_i * E_ref_i) from its energy per atom.
 export const renormalize_entries = (entries, el_refs, elements) => entries.map((entry) => {
     const atoms = count_atoms_in_composition(entry.composition);
+    const base_epa = get_energy_per_atom(entry);
+    if (!(atoms > 0) || !Number.isFinite(base_epa))
+        return entry;
     let renorm_energy = 0;
     for (const el of elements) {
-        const frac = atoms > 0 ? (entry.composition[el] ?? 0) / atoms : 0;
+        const frac = (entry.composition[el] ?? 0) / atoms;
         const ref = el_refs[el];
-        if (ref)
-            renorm_energy += frac * get_energy_per_atom(ref);
+        if (!ref)
+            continue;
+        const ref_epa = get_energy_per_atom(ref);
+        if (!Number.isFinite(ref_epa))
+            return entry;
+        renorm_energy += frac * ref_epa;
     }
-    const new_energy_per_atom = get_energy_per_atom(entry) - renorm_energy;
+    const new_energy_per_atom = base_epa - renorm_energy;
     return {
         ...entry,
         energy: new_energy_per_atom * atoms,
@@ -137,7 +191,10 @@ export function build_hyperplanes(min_entries, el_refs, elements) {
     const n_elems = elements.length;
     const element_ref_energies = elements.map((element) => {
         const ref_entry = el_refs[element];
-        return ref_entry ? get_energy_per_atom(ref_entry) : 0;
+        if (!ref_entry)
+            return 0;
+        const epa = get_energy_per_atom(ref_entry);
+        return Number.isFinite(epa) ? epa : 0;
     });
     const always_include = new Set(Object.values(el_refs));
     const tol = 1e-6; // PhaseDiagram.formation_energy_tol
@@ -148,6 +205,8 @@ export function build_hyperplanes(min_entries, el_refs, elements) {
         const atom_count = count_atoms_in_composition(entry.composition);
         const composition = entry.composition;
         const energy_per_atom = get_energy_per_atom(entry);
+        if (!(atom_count > 0) || !Number.isFinite(energy_per_atom))
+            continue;
         const row = Array(n_elems + 1).fill(0);
         let ref_energy = 0;
         for (let elem_idx = 0; elem_idx < n_elems; elem_idx++) {
@@ -670,19 +729,19 @@ export function get_ternary_combinations(elements) {
     return combos;
 }
 let nd_cache = null;
-// Content-based fingerprint for N-D result caching. Uses sorted formula keys
-// so deserialized Web Worker copies match and different compositions never collide.
-export function make_nd_cache_key(entries, formal_chempots, default_min_limit, limits) {
-    const keyed = entries
-        .map((entry) => [
+// Fingerprint for N-D / async-compute cache keys (computed EPA; NaN → null).
+export function entry_fingerprint(entry) {
+    const epa = get_energy_per_atom(entry);
+    return JSON.stringify([
         formula_key_from_composition(entry.composition),
-        entry.energy,
-        entry.is_stable ?? ``,
-        entry.e_above_hull ?? ``,
-        entry.exclude_from_hull ?? ``,
-    ].join(`:`))
-        .sort();
-    return `${keyed.join(`,`)}|${formal_chempots}|${default_min_limit}|${JSON.stringify(limits ?? {})}`;
+        Number.isFinite(epa) ? epa : null,
+        entry.is_stable ?? null,
+        entry.e_above_hull ?? null,
+        entry.exclude_from_hull ?? null,
+    ]);
+}
+export function make_nd_cache_key(entries, formal_chempots, default_min_limit, limits) {
+    return `${entries.map(entry_fingerprint).sort().join(`,`)}|${formal_chempots}|${default_min_limit}|${JSON.stringify(limits ?? {})}`;
 }
 // === Main Pipeline ===
 // Compute the full chemical potential diagram from entries and config.

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

@@ -13,7 +13,7 @@ export function create_chempot_overrides(config, keys, custom_defaults = {}) {
     }));
     let overrides = $state({});
     return {
-        resolve: (key) => (overrides[key] ?? config()[key] ?? defaults[key]),
+        resolve: (key) => overrides[key] ?? config()[key] ?? defaults[key],
         set: (key, value) => {
             overrides[key] = value;
         },

package/dist/chempot-diagram/export.js

@@ -1,6 +1,7 @@
 // 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 { escape_html as xml_escape } from '../utils';
 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);
@@ -77,12 +78,6 @@ export function export_png_file(wrapper, basename, png_dpi) {
         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);

package/dist/chempot-diagram/temperature.js

@@ -1,21 +1,20 @@
 import { analyze_temperature_data, filter_entries_at_temperature, } from '../convex-hull/helpers';
 import { CHEMPOT_DEFAULTS } from './types';
 export const get_projection_source_entries = (entries, temp_filtered_entries) => (temp_filtered_entries.length > 0 ? temp_filtered_entries : entries);
-const resolve_temp_filter_options = (config, props) => ({
-    interpolate: config.interpolate_temperature ??
-        props.interpolate_temperature ??
-        CHEMPOT_DEFAULTS.interpolate_temperature,
-    max_interpolation_gap: config.max_interpolation_gap ??
-        props.max_interpolation_gap ??
-        CHEMPOT_DEFAULTS.max_interpolation_gap,
-});
 export function get_temp_filter_payload(entries, temperature, config, props) {
     const { has_temp_data, available_temperatures } = analyze_temperature_data(entries);
     if (!has_temp_data || temperature === undefined) {
         return { has_temp_data, available_temperatures, temp_filtered_entries: entries };
     }
-    const filter_options = resolve_temp_filter_options(config, props);
-    const temp_filtered_entries = filter_entries_at_temperature(entries, temperature, filter_options);
+    // Option resolution order: config beats props beats defaults
+    const temp_filtered_entries = filter_entries_at_temperature(entries, temperature, {
+        interpolate: config.interpolate_temperature ??
+            props.interpolate_temperature ??
+            CHEMPOT_DEFAULTS.interpolate_temperature,
+        max_interpolation_gap: config.max_interpolation_gap ??
+            props.max_interpolation_gap ??
+            CHEMPOT_DEFAULTS.max_interpolation_gap,
+    });
     return { has_temp_data, available_temperatures, temp_filtered_entries };
 }
 export function get_valid_temperature(temperature, has_temp_data, available_temperatures) {

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' };
@@ -82,16 +84,17 @@ export function luminance(clr) {
     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);