chromonym 1.1.0 → 1.3.0

package/dist/indexing.js

@@ -0,0 +1,140 @@
+import { hexToRgba } from './conversions/hex';
+import { rgbaToLab, rgbaToLinearRgb, rgbaToOklab } from './math/colorSpace';
+import { deltaE76Squared, deltaE94, deltaE2000, deltaEokSquared } from './math/deltaE';
+import { squaredDistanceRgb } from './math/euclideanDistance';
+/** Lowercase + strip non-alphanumeric. Used for web and x11. */
+export const standardNormalize = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+/**
+ * Pantone: also strip a leading "Pantone" or "PMS" prefix so that
+ * "185 C", "185c", "Pantone 185 C", "PMS185C" all map to "185c".
+ */
+export const pantoneNormalize = (s) => s
+    .toLowerCase()
+    .replace(/^(pantone|pms)\s*/, '')
+    .replace(/[^a-z0-9]/g, '');
+const nameIndexCache = new WeakMap();
+const rgbaIndexCache = new WeakMap();
+/**
+ * Normalized-name → canonical-key map for a given colorspace.
+ * Each (colorspace, normalize) pair must be stable — callers are
+ * expected to always pair a given colorspace with the same normalizer.
+ */
+export function getNameIndex(space, normalize) {
+    let idx = nameIndexCache.get(space);
+    if (idx === undefined) {
+        idx = new Map();
+        for (const key of Object.keys(space)) {
+            idx.set(normalize(key), key);
+        }
+        nameIndexCache.set(space, idx);
+    }
+    return idx;
+}
+/**
+ * Canonical-key → Rgba entries for a given colorspace, built by parsing
+ * each hex value once. Used by nearest-match lookups (identify, rgbaToPantone).
+ */
+export function getRgbaIndex(space) {
+    let idx = rgbaIndexCache.get(space);
+    if (idx === undefined) {
+        idx = Object.entries(space).map(([name, hex]) => [name, hexToRgba(hex)]);
+        rgbaIndexCache.set(space, idx);
+    }
+    return idx;
+}
+/**
+ * Find the nearest-named entry in a colorspace to the given Rgba, using
+ * squared Euclidean distance in sRGB (alpha ignored). Used by `identify`
+ * and `rgbaToPantone` when metric === 'euclidean-srgb'.
+ */
+export function nearestByRgb(target, space) {
+    const entries = getRgbaIndex(space);
+    let bestName = entries[0]?.[0] ?? '';
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const [name, candidate] of entries) {
+        const d = squaredDistanceRgb(target, candidate);
+        if (d < bestDistance) {
+            bestDistance = d;
+            bestName = name;
+        }
+    }
+    return bestName;
+}
+const labIndexCache = new WeakMap();
+function getLabIndex(space) {
+    let idx = labIndexCache.get(space);
+    if (idx === undefined) {
+        idx = getRgbaIndex(space).map(([name, rgba]) => [name, rgbaToLab(rgba)]);
+        labIndexCache.set(space, idx);
+    }
+    return idx;
+}
+// Precomputed linear-RGB entries for euclidean-linear metric.
+const linearIndexCache = new WeakMap();
+function getLinearIndex(space) {
+    let idx = linearIndexCache.get(space);
+    if (idx === undefined) {
+        idx = getRgbaIndex(space).map(([name, rgba]) => [name, rgbaToLinearRgb(rgba)]);
+        linearIndexCache.set(space, idx);
+    }
+    return idx;
+}
+// Precomputed OKLAB entries for deltaEok metric.
+const oklabIndexCache = new WeakMap();
+function getOklabIndex(space) {
+    let idx = oklabIndexCache.get(space);
+    if (idx === undefined) {
+        idx = getRgbaIndex(space).map(([name, rgba]) => [name, rgbaToOklab(rgba)]);
+        oklabIndexCache.set(space, idx);
+    }
+    return idx;
+}
+/**
+ * Generic argmin over an `[name, value]` entries array with a custom
+ * distance function. Factored so the three metric branches in `nearest`
+ * share one loop body instead of duplicating it three times.
+ */
+function argminBy(entries, target, dist) {
+    let bestName = entries[0]?.[0] ?? '';
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const [name, candidate] of entries) {
+        const d = dist(target, candidate);
+        if (d < bestDistance) {
+            bestDistance = d;
+            bestName = name;
+        }
+    }
+    return bestName;
+}
+// Squared Euclidean on a [number, number, number] triple. Used for the
+// linear-RGB metric (sharing shape with Lab but different meaning).
+function squaredDistanceTriple(a, b) {
+    const d0 = a[0] - b[0];
+    const d1 = a[1] - b[1];
+    const d2 = a[2] - b[2];
+    return d0 * d0 + d1 * d1 + d2 * d2;
+}
+/**
+ * Find the nearest-named entry in a colorspace under the specified distance
+ * metric. Dispatches to the right index (rgba / linear-rgb / Lab) and
+ * the right distance function. See `DistanceMetric` in types.ts for how
+ * to pick a metric.
+ */
+export function nearest(target, space, metric = 'euclidean-srgb') {
+    if (metric === 'euclidean-srgb')
+        return nearestByRgb(target, space);
+    if (metric === 'euclidean-linear') {
+        return argminBy(getLinearIndex(space), rgbaToLinearRgb(target), squaredDistanceTriple);
+    }
+    if (metric === 'deltaEok') {
+        return argminBy(getOklabIndex(space), rgbaToOklab(target), deltaEokSquared);
+    }
+    const labTarget = rgbaToLab(target);
+    const labIndex = getLabIndex(space);
+    if (metric === 'deltaE76')
+        return argminBy(labIndex, labTarget, deltaE76Squared);
+    if (metric === 'deltaE94')
+        return argminBy(labIndex, labTarget, deltaE94);
+    return argminBy(labIndex, labTarget, deltaE2000);
+}
+//# sourceMappingURL=indexing.js.map

package/dist/indexing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.js","sourceRoot":"","sources":["../src/indexing.ts"],"names":[],"mappings":"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"}

package/dist/math/clamp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Clamp n to [lo, hi]. Caller must ensure n is a finite number.
+ */
+export declare function clamp(n: number, lo: number, hi: number): number;
+/**
+ * Require a finite number at an API boundary; throws otherwise.
+ * Used by converter entry points to reject NaN, Infinity, and non-numeric
+ * values before they propagate through color math.
+ */
+export declare function requireFinite(n: unknown, label: string): number;
+//# sourceMappingURL=clamp.d.ts.map

package/dist/math/clamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp.d.ts","sourceRoot":"","sources":["../../src/math/clamp.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/D"}

package/dist/math/clamp.js

@@ -0,0 +1,18 @@
+/**
+ * Clamp n to [lo, hi]. Caller must ensure n is a finite number.
+ */
+export function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+/**
+ * Require a finite number at an API boundary; throws otherwise.
+ * Used by converter entry points to reject NaN, Infinity, and non-numeric
+ * values before they propagate through color math.
+ */
+export function requireFinite(n, label) {
+    if (typeof n !== 'number' || !Number.isFinite(n)) {
+        throw new Error(`Expected finite number for ${label}, got ${typeof n}: ${String(n)}`);
+    }
+    return n;
+}
+//# sourceMappingURL=clamp.js.map

package/dist/math/clamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp.js","sourceRoot":"","sources":["../../src/math/clamp.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,CAAS,EAAE,EAAU,EAAE,EAAU;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU,EAAE,KAAa;IACrD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,SAAS,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/math/colorSpace.d.ts

@@ -0,0 +1,55 @@
+import type { Rgba } from '../types';
+/**
+ * Color-space conversions needed by the perceptual distance metrics.
+ *
+ * Two pipelines:
+ *   CIELAB:  sRGB (0..255)  →  linear RGB  →  XYZ (D65)  →  Lab
+ *   OKLAB:   sRGB (0..255)  →  linear RGB  →  LMS (cbrt)  →  OKLAB
+ *
+ * References:
+ *   sRGB EOTF / companding:      IEC 61966-2-1
+ *   sRGB → XYZ (D65):            Bruce Lindbloom, http://www.brucelindbloom.com/
+ *   XYZ → Lab:                   CIE 15:2004
+ *   OKLAB:                       Ottosson, https://bottosson.github.io/posts/oklab/
+ */
+/** sRGB → linear for a single channel in [0, 255]. Returns [0, 1]. */
+export declare function srgbToLinear(channel: number): number;
+/** Linear → sRGB for a single channel in [0, 1]. Returns [0, 1] (scale by 255 if needed). */
+export declare function linearToSrgb(linear: number): number;
+/** Rgba → linear RGB triple in [0, 1] (alpha dropped). */
+export declare function rgbaToLinearRgb(rgba: Rgba): [number, number, number];
+/**
+ * Linear RGB (D65) → CIE XYZ (D65), using the standard sRGB matrix.
+ * Input and output both in [0, 1] on each axis (approximately; Y = 1 is white).
+ */
+export declare function linearRgbToXyz(r: number, g: number, b: number): [number, number, number];
+/** CIE XYZ (D65) → CIE Lab. L ∈ [0, 100] approx; a,b unbounded but typically [-128, 127]. */
+export declare function xyzToLab(x: number, y: number, z: number): [number, number, number];
+/** Rgba (sRGB, 0..255) → CIE Lab. Canonical pipeline for perceptual distance. */
+export declare function rgbaToLab(rgba: Rgba): [number, number, number];
+/**
+ * Linear sRGB → OKLAB (Björn Ottosson, 2020). OKLAB is strictly more
+ * perceptually uniform than CIELAB, especially in the blue/purple region
+ * where even CIEDE2000 has residual error. Distance in OKLAB is plain
+ * Euclidean — no weighting formula needed, because the space itself is
+ * designed around uniformity.
+ *
+ * Reference: https://bottosson.github.io/posts/oklab/
+ */
+export declare function linearRgbToOklab(r: number, g: number, b: number): [number, number, number];
+/** Rgba (sRGB, 0..255) → OKLAB. */
+export declare function rgbaToOklab(rgba: Rgba): [number, number, number];
+/**
+ * OKLAB → OKLCh (polar form of OKLAB). L stays the same; a,b become
+ * chroma and hue. Useful for hue-aware manipulation and naming strategies
+ * that want to reason about hue distance independently of lightness.
+ *
+ * Returns [L, C, h] where C >= 0 and h is in degrees [0, 360).
+ * Achromatic colors (C ≈ 0) return h = 0 by convention.
+ */
+export declare function oklabToOklch(L: number, a: number, b: number): [number, number, number];
+/** OKLCh → OKLAB. Inverse of `oklabToOklch`. */
+export declare function oklchToOklab(L: number, C: number, h: number): [number, number, number];
+/** Rgba (sRGB, 0..255) → OKLCh. Composition shortcut. */
+export declare function rgbaToOklch(rgba: Rgba): [number, number, number];
+//# sourceMappingURL=colorSpace.d.ts.map

package/dist/math/colorSpace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorSpace.d.ts","sourceRoot":"","sources":["../../src/math/colorSpace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;;;;;;;;GAYG;AAEH,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEpE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKxF;AAaD,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAQlF;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAI9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAa1F;AAED,mCAAmC;AACnC,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAItF;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAGtF;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAGhE"}

package/dist/math/colorSpace.js

@@ -0,0 +1,111 @@
+/**
+ * Color-space conversions needed by the perceptual distance metrics.
+ *
+ * Two pipelines:
+ *   CIELAB:  sRGB (0..255)  →  linear RGB  →  XYZ (D65)  →  Lab
+ *   OKLAB:   sRGB (0..255)  →  linear RGB  →  LMS (cbrt)  →  OKLAB
+ *
+ * References:
+ *   sRGB EOTF / companding:      IEC 61966-2-1
+ *   sRGB → XYZ (D65):            Bruce Lindbloom, http://www.brucelindbloom.com/
+ *   XYZ → Lab:                   CIE 15:2004
+ *   OKLAB:                       Ottosson, https://bottosson.github.io/posts/oklab/
+ */
+/** sRGB → linear for a single channel in [0, 255]. Returns [0, 1]. */
+export function srgbToLinear(channel) {
+    const s = channel / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+/** Linear → sRGB for a single channel in [0, 1]. Returns [0, 1] (scale by 255 if needed). */
+export function linearToSrgb(linear) {
+    return linear <= 0.0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - 0.055;
+}
+/** Rgba → linear RGB triple in [0, 1] (alpha dropped). */
+export function rgbaToLinearRgb(rgba) {
+    return [srgbToLinear(rgba.r), srgbToLinear(rgba.g), srgbToLinear(rgba.b)];
+}
+/**
+ * Linear RGB (D65) → CIE XYZ (D65), using the standard sRGB matrix.
+ * Input and output both in [0, 1] on each axis (approximately; Y = 1 is white).
+ */
+export function linearRgbToXyz(r, g, b) {
+    const x = r * 0.4124564 + g * 0.3575761 + b * 0.1804375;
+    const y = r * 0.2126729 + g * 0.7151522 + b * 0.072175;
+    const z = r * 0.0193339 + g * 0.119192 + b * 0.9503041;
+    return [x, y, z];
+}
+// D65 white reference (CIE 1931 2° observer).
+const XN = 0.95047;
+const YN = 1.0;
+const ZN = 1.08883;
+// f(t) in the CIE Lab formula; cube-root with a linear toe near origin.
+function labF(t) {
+    const DELTA = 6 / 29;
+    return t > DELTA ** 3 ? Math.cbrt(t) : t / (3 * DELTA ** 2) + 4 / 29;
+}
+/** CIE XYZ (D65) → CIE Lab. L ∈ [0, 100] approx; a,b unbounded but typically [-128, 127]. */
+export function xyzToLab(x, y, z) {
+    const fx = labF(x / XN);
+    const fy = labF(y / YN);
+    const fz = labF(z / ZN);
+    const l = 116 * fy - 16;
+    const a = 500 * (fx - fy);
+    const b = 200 * (fy - fz);
+    return [l, a, b];
+}
+/** Rgba (sRGB, 0..255) → CIE Lab. Canonical pipeline for perceptual distance. */
+export function rgbaToLab(rgba) {
+    const [r, g, b] = rgbaToLinearRgb(rgba);
+    const [x, y, z] = linearRgbToXyz(r, g, b);
+    return xyzToLab(x, y, z);
+}
+/**
+ * Linear sRGB → OKLAB (Björn Ottosson, 2020). OKLAB is strictly more
+ * perceptually uniform than CIELAB, especially in the blue/purple region
+ * where even CIEDE2000 has residual error. Distance in OKLAB is plain
+ * Euclidean — no weighting formula needed, because the space itself is
+ * designed around uniformity.
+ *
+ * Reference: https://bottosson.github.io/posts/oklab/
+ */
+export function linearRgbToOklab(r, g, b) {
+    const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+    const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+    const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+    const l_ = Math.cbrt(l);
+    const m_ = Math.cbrt(m);
+    const s_ = Math.cbrt(s);
+    const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+    const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+    const b2 = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+    return [L, a, b2];
+}
+/** Rgba (sRGB, 0..255) → OKLAB. */
+export function rgbaToOklab(rgba) {
+    const [r, g, b] = rgbaToLinearRgb(rgba);
+    return linearRgbToOklab(r, g, b);
+}
+/**
+ * OKLAB → OKLCh (polar form of OKLAB). L stays the same; a,b become
+ * chroma and hue. Useful for hue-aware manipulation and naming strategies
+ * that want to reason about hue distance independently of lightness.
+ *
+ * Returns [L, C, h] where C >= 0 and h is in degrees [0, 360).
+ * Achromatic colors (C ≈ 0) return h = 0 by convention.
+ */
+export function oklabToOklch(L, a, b) {
+    const C = Math.sqrt(a * a + b * b);
+    const h = C === 0 ? 0 : ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360;
+    return [L, C, h];
+}
+/** OKLCh → OKLAB. Inverse of `oklabToOklch`. */
+export function oklchToOklab(L, C, h) {
+    const rad = (h * Math.PI) / 180;
+    return [L, C * Math.cos(rad), C * Math.sin(rad)];
+}
+/** Rgba (sRGB, 0..255) → OKLCh. Composition shortcut. */
+export function rgbaToOklch(rgba) {
+    const [L, a, b] = rgbaToOklab(rgba);
+    return oklabToOklch(L, a, b);
+}
+//# sourceMappingURL=colorSpace.js.map

package/dist/math/colorSpace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorSpace.js","sourceRoot":"","sources":["../../src/math/colorSpace.ts"],"names":[],"mappings":"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"}

package/dist/math/deltaE.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CIE color-difference metrics. Inputs are `Lab` triples (L, a, b) as
+ * produced by `rgbaToLab` from `colorSpace.ts`.
+ *
+ * All three metrics operate in CIELAB; the differences are in how each
+ * region of Lab space is weighted:
+ *   ΔE*76  — simple Euclidean in Lab (CIE 1976). Fast, decent.
+ *   ΔE*94  — adds chroma/hue weighting (CIE 1994). Better saturation handling.
+ *   ΔE00  — also adjusts L/C/h + rotation correction in blue-purple region
+ *            (CIE 2000, aka CIEDE2000). Current industry standard.
+ *
+ * References:
+ *   CIE 15:2004 (Colorimetry), CIE TC1-29 (ΔE2000).
+ *   G. Sharma, W. Wu, E.N. Dalal, "The CIEDE2000 Color-Difference Formula"
+ *   (Color Research & Application, 2005) — canonical test vectors.
+ */
+export type Lab = readonly [l: number, a: number, b: number];
+/**
+ * ΔE*ab (CIE 1976). Simple Euclidean distance in Lab.
+ * Returns the *square* for speed — identify loops only need argmin, and
+ * sqrt is monotonic. Use `deltaE76` if you need the actual distance.
+ */
+export declare function deltaE76Squared(p: Lab, q: Lab): number;
+export declare function deltaE76(p: Lab, q: Lab): number;
+/**
+ * ΔE*94 (CIE 1994). Weights the chroma and hue contributions relative to
+ * Lab Euclidean distance — fixes the "saturated colors feel too far apart"
+ * problem of ΔE*76. Uses graphic-arts constants (kL=1, K1=0.045, K2=0.015).
+ *
+ * Not symmetric in the strict sense (reference vs sample), but we treat
+ * both inputs as graphic-arts samples — the formula reduces to a
+ * symmetric form below.
+ */
+export declare function deltaE94(p: Lab, q: Lab): number;
+export declare function deltaE2000(p: Lab, q: Lab, kL?: number, kC?: number, kH?: number): number;
+/**
+ * Squared Euclidean distance in OKLAB space (Björn Ottosson, 2020).
+ * OKLAB is perceptually uniform by construction — plain Euclidean IS the
+ * perceptual distance, no weighting needed. Returns the square for
+ * argmin speed; `deltaEok` returns the actual distance.
+ *
+ * Often gives more visually-accurate nearest-matches than CIEDE2000 in
+ * the saturated blue/purple region.
+ *
+ * NOTE: the body is byte-identical to `deltaE76Squared` — both compute
+ * `dl² + da² + db²`. The semantic difference is entirely in *which* space
+ * the caller passes coordinates from: CIELAB (for ΔE*76) vs OKLAB (for this).
+ * Kept separate so callers and tests can't cross-wire the indexes.
+ */
+export declare function deltaEokSquared(p: Lab, q: Lab): number;
+export declare function deltaEok(p: Lab, q: Lab): number;
+//# sourceMappingURL=deltaE.d.ts.map

package/dist/math/deltaE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deltaE.d.ts","sourceRoot":"","sources":["../../src/math/deltaE.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAKtD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAE/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAwB/C;AAgCD,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,SAAI,EAAE,EAAE,SAAI,EAAE,EAAE,SAAI,GAAG,MAAM,CAoFzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAKtD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAE/C"}

package/dist/math/deltaE.js

@@ -0,0 +1,190 @@
+/**
+ * CIE color-difference metrics. Inputs are `Lab` triples (L, a, b) as
+ * produced by `rgbaToLab` from `colorSpace.ts`.
+ *
+ * All three metrics operate in CIELAB; the differences are in how each
+ * region of Lab space is weighted:
+ *   ΔE*76  — simple Euclidean in Lab (CIE 1976). Fast, decent.
+ *   ΔE*94  — adds chroma/hue weighting (CIE 1994). Better saturation handling.
+ *   ΔE00  — also adjusts L/C/h + rotation correction in blue-purple region
+ *            (CIE 2000, aka CIEDE2000). Current industry standard.
+ *
+ * References:
+ *   CIE 15:2004 (Colorimetry), CIE TC1-29 (ΔE2000).
+ *   G. Sharma, W. Wu, E.N. Dalal, "The CIEDE2000 Color-Difference Formula"
+ *   (Color Research & Application, 2005) — canonical test vectors.
+ */
+/**
+ * ΔE*ab (CIE 1976). Simple Euclidean distance in Lab.
+ * Returns the *square* for speed — identify loops only need argmin, and
+ * sqrt is monotonic. Use `deltaE76` if you need the actual distance.
+ */
+export function deltaE76Squared(p, q) {
+    const dl = p[0] - q[0];
+    const da = p[1] - q[1];
+    const db = p[2] - q[2];
+    return dl * dl + da * da + db * db;
+}
+export function deltaE76(p, q) {
+    return Math.sqrt(deltaE76Squared(p, q));
+}
+/**
+ * ΔE*94 (CIE 1994). Weights the chroma and hue contributions relative to
+ * Lab Euclidean distance — fixes the "saturated colors feel too far apart"
+ * problem of ΔE*76. Uses graphic-arts constants (kL=1, K1=0.045, K2=0.015).
+ *
+ * Not symmetric in the strict sense (reference vs sample), but we treat
+ * both inputs as graphic-arts samples — the formula reduces to a
+ * symmetric form below.
+ */
+export function deltaE94(p, q) {
+    const [l1, a1, b1] = p;
+    const [l2, a2, b2] = q;
+    const dL = l1 - l2;
+    const c1 = Math.hypot(a1, b1);
+    const c2 = Math.hypot(a2, b2);
+    const dC = c1 - c2;
+    const da = a1 - a2;
+    const db = b1 - b2;
+    const dH2 = da * da + db * db - dC * dC;
+    // dH² can go slightly negative due to floating-point — clamp.
+    const dH2Safe = dH2 < 0 ? 0 : dH2;
+    const K1 = 0.045;
+    const K2 = 0.015;
+    const sL = 1;
+    const sC = 1 + K1 * c1;
+    const sH = 1 + K2 * c1;
+    const termL = dL / sL;
+    const termC = dC / sC;
+    const termH = Math.sqrt(dH2Safe) / sH;
+    return Math.sqrt(termL * termL + termC * termC + termH * termH);
+}
+// ---- ΔE00 helpers --------------------------------------------------------
+const DEG = Math.PI / 180;
+const RAD = 180 / Math.PI;
+function hueDeg(b, a) {
+    if (b === 0 && a === 0)
+        return 0;
+    return (Math.atan2(b, a) * RAD + 360) % 360;
+}
+/**
+ * ΔE*00 (CIE 2000 / CIEDE2000). Current industry-standard perceptual
+ * color-difference formula. Fixes the saturated-blue failure of ΔE76/94
+ * with a rotation term in the blue-purple region (h ≈ 275°).
+ *
+ * kL / kC / kH are parametric factors (default 1/1/1 = graphic arts).
+ * Reference: G. Sharma, W. Wu, E.N. Dalal, "The CIEDE2000 Color-Difference
+ * Formula" (Color Research & Application, 2005).
+ */
+// Precomputed constant: 25^7 = 6,103,515,625. Appears twice in the formula.
+const POW_25_7 = 6103515625;
+// Inline pow(x, 7) — Math.pow with non-integer exponent is slower in V8
+// than three multiplies. x² → x⁴ → x⁶·x.
+function pow7(x) {
+    const x2 = x * x;
+    const x4 = x2 * x2;
+    return x4 * x2 * x;
+}
+export function deltaE2000(p, q, kL = 1, kC = 1, kH = 1) {
+    const l1 = p[0];
+    const a1 = p[1];
+    const b1 = p[2];
+    const l2 = q[0];
+    const a2 = q[1];
+    const b2 = q[2];
+    // Chromas and mean chroma. Lab values stay within ±150 so overflow
+    // protection in Math.hypot is unnecessary — plain sqrt(a²+b²) is ~3×
+    // faster in V8 and more than precise enough for our range.
+    const c1 = Math.sqrt(a1 * a1 + b1 * b1);
+    const c2 = Math.sqrt(a2 * a2 + b2 * b2);
+    const cBar = (c1 + c2) / 2;
+    const cBar7 = pow7(cBar);
+    // G-factor boost for a* in low-chroma regions.
+    const g = 0.5 * (1 - Math.sqrt(cBar7 / (cBar7 + POW_25_7)));
+    const a1p = (1 + g) * a1;
+    const a2p = (1 + g) * a2;
+    // Primed chroma and hue.
+    const c1p = Math.sqrt(a1p * a1p + b1 * b1);
+    const c2p = Math.sqrt(a2p * a2p + b2 * b2);
+    const h1p = hueDeg(b1, a1p);
+    const h2p = hueDeg(b2, a2p);
+    // Differences.
+    const dLp = l2 - l1;
+    const dCp = c2p - c1p;
+    let dhp;
+    if (c1p * c2p === 0) {
+        dhp = 0;
+    }
+    else {
+        const raw = h2p - h1p;
+        if (Math.abs(raw) <= 180)
+            dhp = raw;
+        else if (raw > 180)
+            dhp = raw - 360;
+        else
+            dhp = raw + 360;
+    }
+    const dHp = 2 * Math.sqrt(c1p * c2p) * Math.sin((dhp * DEG) / 2);
+    // Means.
+    const lBarP = (l1 + l2) / 2;
+    const cBarP = (c1p + c2p) / 2;
+    let hBarP;
+    if (c1p * c2p === 0) {
+        hBarP = h1p + h2p;
+    }
+    else if (Math.abs(h1p - h2p) <= 180) {
+        hBarP = (h1p + h2p) / 2;
+    }
+    else if (h1p + h2p < 360) {
+        hBarP = (h1p + h2p + 360) / 2;
+    }
+    else {
+        hBarP = (h1p + h2p - 360) / 2;
+    }
+    // Weighting function T.
+    const hBarRad = hBarP * DEG;
+    const t = 1 -
+        0.17 * Math.cos(hBarRad - 30 * DEG) +
+        0.24 * Math.cos(2 * hBarRad) +
+        0.32 * Math.cos(3 * hBarRad + 6 * DEG) -
+        0.2 * Math.cos(4 * hBarRad - 63 * DEG);
+    // Lightness, chroma, hue weighting factors.
+    const lBarMinus50Sq = (lBarP - 50) ** 2;
+    const sL = 1 + (0.015 * lBarMinus50Sq) / Math.sqrt(20 + lBarMinus50Sq);
+    const sC = 1 + 0.045 * cBarP;
+    const sH = 1 + 0.015 * cBarP * t;
+    // Rotation term — the blue-purple correction that ΔE94 lacks.
+    const hShift = (hBarP - 275) / 25;
+    const dTheta = 30 * Math.exp(-(hShift * hShift));
+    const cBarP7 = pow7(cBarP);
+    const rC = 2 * Math.sqrt(cBarP7 / (cBarP7 + POW_25_7));
+    const rT = -Math.sin(2 * dTheta * DEG) * rC;
+    const termL = dLp / (kL * sL);
+    const termC = dCp / (kC * sC);
+    const termH = dHp / (kH * sH);
+    return Math.sqrt(termL * termL + termC * termC + termH * termH + rT * termC * termH);
+}
+/**
+ * Squared Euclidean distance in OKLAB space (Björn Ottosson, 2020).
+ * OKLAB is perceptually uniform by construction — plain Euclidean IS the
+ * perceptual distance, no weighting needed. Returns the square for
+ * argmin speed; `deltaEok` returns the actual distance.
+ *
+ * Often gives more visually-accurate nearest-matches than CIEDE2000 in
+ * the saturated blue/purple region.
+ *
+ * NOTE: the body is byte-identical to `deltaE76Squared` — both compute
+ * `dl² + da² + db²`. The semantic difference is entirely in *which* space
+ * the caller passes coordinates from: CIELAB (for ΔE*76) vs OKLAB (for this).
+ * Kept separate so callers and tests can't cross-wire the indexes.
+ */
+export function deltaEokSquared(p, q) {
+    const dl = p[0] - q[0];
+    const da = p[1] - q[1];
+    const db = p[2] - q[2];
+    return dl * dl + da * da + db * db;
+}
+export function deltaEok(p, q) {
+    return Math.sqrt(deltaEokSquared(p, q));
+}
+//# sourceMappingURL=deltaE.js.map

package/dist/math/deltaE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deltaE.js","sourceRoot":"","sources":["../../src/math/deltaE.ts"],"names":[],"mappings":"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"}

package/dist/math/euclideanDistance.d.ts

@@ -1,4 +1,11 @@
 import type { Rgba } from '../types';
+/**
+ * Squared Euclidean distance between two colors in RGB space.
+ * Alpha channel is ignored. Faster than `euclideanDistance` — use this
+ * when you only need to compare or minimize (sqrt is monotonic, so
+ * argmin(d) === argmin(d²)).
+ */
+export declare function squaredDistanceRgb(a: Rgba, b: Rgba): number;
 /**
  * Euclidean distance between two colors in RGB space.
  * Alpha channel is ignored (matches classic `detect-color` behavior).

package/dist/math/euclideanDistance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"euclideanDistance.d.ts","sourceRoot":"","sources":["../../src/math/euclideanDistance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAK1D"}
+{"version":3,"file":"euclideanDistance.d.ts","sourceRoot":"","sources":["../../src/math/euclideanDistance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAK3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAE1D"}