@zakkster/lite-color-engine 1.0.4 → 1.2.0

package/src/Remap.js

@@ -0,0 +1,306 @@
+// -----------------------------------------------------------------------------
+// @zakkster/lite-color-engine/remap
+//
+// SoA remap kernels: nearest-palette-index search in OKLab, and a one-shot
+// pixel-remap function for image recoloring. The engine layer that
+// `lite-hueforge v1.3 remapImageToPalette` sits on top of.
+//
+// Design opinions:
+//   1. Search happens in OKLab, not OKLCH. Distance in OKLab is Euclidean;
+//      distance in OKLCH needs a cos/sin per comparison. Palette is authored
+//      in OKLCH (what humans think in), converted to OKLab once at call
+//      entry, searched forever.
+//   2. Palette is limited to whatever fits typical use (hundreds of colors).
+//      Scratch buffers grow monotonically inside the module — never shrink.
+//      Zero allocations on the hot per-pixel loop.
+//   3. `preserveLightness` is the shading-preservation trick: search by (a, b)
+//      only, keep the original pixel's L, and synthesize the output color
+//      from (pixel.L, palette.a, palette.b). This is what makes recolored
+//      AI motifs still look *shaded*, not posterized.
+//   4. Alpha byte from the input passes through unchanged in the output.
+//
+// Trust model: hot path trusts input shapes. Buffer sizes assumed correct.
+// -----------------------------------------------------------------------------
+
+const _RAD = Math.PI / 180;
+const _DEG = 180 / Math.PI;
+
+// Grow-only module-level scratch for remapPixelsToPalette.
+let _paletteLab = new Float32Array(0);
+let _paletteU32 = new Uint32Array(0);
+
+
+// -----------------------------------------------------------------------------
+// Batch converters
+// -----------------------------------------------------------------------------
+
+function _linearizeSrgbByte(b) {
+    const v = b / 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+function _srgbGammaEncode(v) {
+    if (v <= 0) return 0;
+    if (v >= 1) return 1;
+    return v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+}
+
+/**
+ * Batch RGBA8 → OKLab conversion. Reads 4 bytes per pixel from `inU8`
+ * (Uint8ClampedArray or Uint8Array), writes 3 floats per pixel to `outLab`.
+ * Alpha is discarded; carry it separately if needed.
+ */
+export function sRgba8ToOklabBuffer(inU8, outLab, pixelCount) {
+    for (let i = 0; i < pixelCount; i++) {
+        const inOff = i * 4;
+        const outOff = i * 3;
+        const r = _linearizeSrgbByte(inU8[inOff]);
+        const g = _linearizeSrgbByte(inU8[inOff + 1]);
+        const b = _linearizeSrgbByte(inU8[inOff + 2]);
+        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);
+        outLab[outOff]     = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+        outLab[outOff + 1] = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+        outLab[outOff + 2] = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+    }
+}
+
+/**
+ * Batch OKLCH → OKLab conversion. Both buffers stride 3.
+ */
+export function oklchToOklabBuffer(inLch, outLab, pixelCount) {
+    for (let i = 0; i < pixelCount; i++) {
+        const off = i * 3;
+        const L = inLch[off];
+        const C = inLch[off + 1];
+        const H = inLch[off + 2];
+        const hRad = H * _RAD;
+        outLab[off]     = L;
+        outLab[off + 1] = C * Math.cos(hRad);
+        outLab[off + 2] = C * Math.sin(hRad);
+    }
+}
+
+/**
+ * Batch OKLab → OKLCH conversion. Both buffers stride 3.
+ * Hue canonicalized to [0, 360).
+ */
+export function oklabToOklchBuffer(inLab, outLch, pixelCount) {
+    for (let i = 0; i < pixelCount; i++) {
+        const off = i * 3;
+        const L = inLab[off];
+        const a = inLab[off + 1];
+        const b = inLab[off + 2];
+        const C = Math.sqrt(a * a + b * b);
+        let H = Math.atan2(b, a) * _DEG;
+        if (H < 0) H += 360;
+        outLch[off]     = L;
+        outLch[off + 1] = C;
+        outLch[off + 2] = H;
+    }
+}
+
+
+// -----------------------------------------------------------------------------
+// nearestPaletteIndexBuffer
+// -----------------------------------------------------------------------------
+
+/**
+ * For each pixel in `pixelsLab`, write the index of the nearest palette
+ * color in `paletteLab` (by squared Euclidean distance in OKLab) into
+ * `indicesOut`.
+ *
+ * Tie-break: lowest index wins. Deterministic across runs.
+ *
+ * @param {Float32Array} pixelsLab   stride 3 [L, a, b]
+ * @param {Float32Array} paletteLab  stride 3 [L, a, b]
+ * @param {Uint32Array|Uint16Array|Uint8Array} indicesOut  length ≥ pixelCount
+ * @param {number} pixelCount
+ * @param {number} paletteCount
+ * @param {object} [opts]
+ * @param {boolean} [opts.preserveLightness=false] if true, distance uses (a, b) only
+ */
+export function nearestPaletteIndexBuffer(pixelsLab, paletteLab, indicesOut, pixelCount, paletteCount, opts) {
+    const preserveLightness = opts != null && opts.preserveLightness === true;
+    for (let i = 0; i < pixelCount; i++) {
+        const pOff = i * 3;
+        const pL = pixelsLab[pOff];
+        const pA = pixelsLab[pOff + 1];
+        const pB = pixelsLab[pOff + 2];
+        let bestIdx = 0;
+        let bestD = Infinity;
+        for (let k = 0; k < paletteCount; k++) {
+            const kOff = k * 3;
+            const dA = pA - paletteLab[kOff + 1];
+            const dB = pB - paletteLab[kOff + 2];
+            let d = dA * dA + dB * dB;
+            if (!preserveLightness) {
+                const dL = pL - paletteLab[kOff];
+                d += dL * dL;
+            }
+            if (d < bestD) {
+                bestD = d;
+                bestIdx = k;
+            }
+        }
+        indicesOut[i] = bestIdx;
+    }
+}
+
+
+// -----------------------------------------------------------------------------
+// remapPixelsToPalette — one-shot end-to-end
+// -----------------------------------------------------------------------------
+
+/**
+ * One-shot: read RGBA8 pixels, find nearest palette color per pixel, write
+ * RGBA-LE Uint32 result. Handles palette OKLCH→OKLab conversion internally.
+ * Alpha byte is passed through unchanged from input.
+ *
+ * Two code paths:
+ *   - preserveLightness=false: pre-packs palette to U32 once, per-pixel is
+ *     convert-search-gather. Fast enough for live drag at moderate image
+ *     sizes (~500x500 comfortably at 60fps on modern V8).
+ *   - preserveLightness=true: per-pixel synthesizes (pixel.L, palette.a,
+ *     palette.b), converts back through OKLab → linear sRGB → gamma → pack.
+ *     ~3x slower but produces shading-preserved output — the AI motif
+ *     recolor look.
+ *
+ * @param {Uint8Array|Uint8ClampedArray} inU8   RGBA8 pixel buffer
+ * @param {Float32Array} paletteLch             palette OKLCH, stride 3
+ * @param {Uint32Array} outU32                  output Uint32 pixels, length ≥ pixelCount
+ * @param {number} pixelCount
+ * @param {number} paletteCount
+ * @param {object} [opts]
+ * @param {boolean} [opts.preserveLightness=false]
+ */
+export function remapPixelsToPalette(inU8, paletteLch, outU32, pixelCount, paletteCount, opts) {
+    const preserveLightness = opts != null && opts.preserveLightness === true;
+
+    // Grow scratch if needed. Monotonic — never shrinks.
+    const needLab = paletteCount * 3;
+    if (_paletteLab.length < needLab) {
+        _paletteLab = new Float32Array(needLab);
+    }
+    if (_paletteU32.length < paletteCount) {
+        _paletteU32 = new Uint32Array(paletteCount);
+    }
+
+    // Palette OKLCH → OKLab + pre-pack to opaque U32 (alpha comes from input pixels).
+    for (let k = 0; k < paletteCount; k++) {
+        const kOff = k * 3;
+        const L = paletteLch[kOff];
+        const C = paletteLch[kOff + 1];
+        const H = paletteLch[kOff + 2];
+        const hRad = H * _RAD;
+        const a = C * Math.cos(hRad);
+        const b = C * Math.sin(hRad);
+        _paletteLab[kOff]     = L;
+        _paletteLab[kOff + 1] = a;
+        _paletteLab[kOff + 2] = b;
+
+        // Pack once (opaque; alpha comes from input pixels).
+        const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+        const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+        const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+        const l3 = l_ * l_ * l_;
+        const m3 = m_ * m_ * m_;
+        const s3 = s_ * s_ * s_;
+        const rL =  4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3;
+        const gL = -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3;
+        const bL = -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3;
+        const gR = _srgbGammaEncode(rL);
+        const gG = _srgbGammaEncode(gL);
+        const gB = _srgbGammaEncode(bL);
+        const R = (gR * 255 + 0.5) | 0;
+        const G = (gG * 255 + 0.5) | 0;
+        const B = (gB * 255 + 0.5) | 0;
+        _paletteU32[k] = (B << 16) | (G << 8) | R;
+    }
+
+    if (!preserveLightness) {
+        // Fast path: pre-packed gather.
+        for (let i = 0; i < pixelCount; i++) {
+            const inOff = i * 4;
+            const r = _linearizeSrgbByte(inU8[inOff]);
+            const g = _linearizeSrgbByte(inU8[inOff + 1]);
+            const b = _linearizeSrgbByte(inU8[inOff + 2]);
+            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 pL = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+            const pA = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+            const pB = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+
+            let bestIdx = 0;
+            let bestD = Infinity;
+            for (let k = 0; k < paletteCount; k++) {
+                const kOff = k * 3;
+                const dL = pL - _paletteLab[kOff];
+                const dA = pA - _paletteLab[kOff + 1];
+                const dB = pB - _paletteLab[kOff + 2];
+                const d = dL * dL + dA * dA + dB * dB;
+                if (d < bestD) { bestD = d; bestIdx = k; }
+            }
+            const A = inU8[inOff + 3];
+            outU32[i] = (A << 24) | _paletteU32[bestIdx];
+        }
+        return;
+    }
+
+    // Preserve-L path: search by (a, b), synthesize per pixel.
+    for (let i = 0; i < pixelCount; i++) {
+        const inOff = i * 4;
+        const r = _linearizeSrgbByte(inU8[inOff]);
+        const g = _linearizeSrgbByte(inU8[inOff + 1]);
+        const b = _linearizeSrgbByte(inU8[inOff + 2]);
+        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 pL = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+        const pA = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+        const pB = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+
+        let bestIdx = 0;
+        let bestD = Infinity;
+        for (let k = 0; k < paletteCount; k++) {
+            const kOff = k * 3;
+            const dA = pA - _paletteLab[kOff + 1];
+            const dB = pB - _paletteLab[kOff + 2];
+            const d = dA * dA + dB * dB;
+            if (d < bestD) { bestD = d; bestIdx = k; }
+        }
+
+        // Synthesize (pixel L, palette a, palette b) → linear sRGB → gamma → pack.
+        const kOff = bestIdx * 3;
+        const nA = _paletteLab[kOff + 1];
+        const nB = _paletteLab[kOff + 2];
+        const nl_ = pL + 0.3963377774 * nA + 0.2158037573 * nB;
+        const nm_ = pL - 0.1055613458 * nA - 0.0638541728 * nB;
+        const ns_ = pL - 0.0894841775 * nA - 1.2914855480 * nB;
+        const nl = nl_ * nl_ * nl_;
+        const nm = nm_ * nm_ * nm_;
+        const ns = ns_ * ns_ * ns_;
+        const nr =  4.0767416621 * nl - 3.3077115913 * nm + 0.2309699292 * ns;
+        const ng = -1.2684380046 * nl + 2.6097574011 * nm - 0.3413193965 * ns;
+        const nb = -0.0041960863 * nl - 0.7034186147 * nm + 1.7076147010 * ns;
+        const gR = _srgbGammaEncode(nr);
+        const gG = _srgbGammaEncode(ng);
+        const gB = _srgbGammaEncode(nb);
+        const R = (gR * 255 + 0.5) | 0;
+        const G = (gG * 255 + 0.5) | 0;
+        const B = (gB * 255 + 0.5) | 0;
+        const A = inU8[inOff + 3];
+        outU32[i] = (A << 24) | (B << 16) | (G << 8) | R;
+    }
+}

package/src/authoring.js

@@ -1,4 +1,4 @@
-import { sRgbToOklchBuffer } from './convert.js';
+import { sRgbToOklchBuffer, displayP3ToOklchBuffer } from './convert.js';
 
 const RAD_TO_DEG = 180 / Math.PI;
 
@@ -51,6 +51,8 @@ const hslToRgb = (h, s, l) => {
     ];
 };
 
+// (linearize lives in convert.js; the parsers below delegate color-space math there)
+
 // ============================================================================
 // 2. REGEX DICTIONARY (CSS Color Level 4 Permissive)
 // ============================================================================
@@ -61,6 +63,7 @@ const OKLCH_REGEX = /^oklch\(\s*([\d.%]+)\s+([\d.%]+)\s+([\d.%a-z]+)(?:\s*\/\s*(
 const OKLAB_REGEX = /^oklab\(\s*([\d.%]+)[,\s]+([\d.-]+)[,\s]+([\d.-]+)(?:[,\s/]+([\d.%]+))?\s*\)$/i;
 const RGB_REGEX = /^rgba?\(\s*([\d.%]+)[,\s]+([\d.%]+)[,\s]+([\d.%]+)(?:(?:,|\s*\/\s*)\s*([\d.%]+))?\s*\)$/i;
 const HSL_REGEX = /^hsla?\(\s*([\d.%a-z]+)[,\s]+([\d.%]+)[,\s]+([\d.%]+)(?:(?:,|\s*\/\s*)\s*([\d.%]+))?\s*\)$/i;
+const DISPLAY_P3_REGEX = /^color\(\s*display-p3\s+([\d.%]+)\s+([\d.%]+)\s+([\d.%]+)(?:\s*\/\s*([\d.%]+))?\s*\)$/i;
 
 // ============================================================================
 // 3. NAMED COLORS FAST-PATH
@@ -77,7 +80,7 @@ const NAMED_COLORS = {
     darkgray: '#a9a9a9', darkgreen: '#006400', darkgrey: '#a9a9a9', darkkhaki: '#bdb76b',
     darkmagenta: '#8b008b', darkolivegreen: '#556b2f', darkorange: '#ff8c00', darkorchid: '#9932cc',
     darkred: '#8b0000', darksalmon: '#e9967a', darkseagreen: '#8fbc8f', darkslateblue: '#483d8b',
-    darkslategray: '#2f4f4f', darkslategrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
+    darkslategray: '#2f4f4f', darkslateggrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
     deeppink: '#ff1493', deepskyblue: '#00bfff', dimgray: '#696969', dimgrey: '#696969',
     dodgerblue: '#1e90ff', firebrick: '#b22222', floralwhite: '#fffaf0', forestgreen: '#228b22',
     fuchsia: '#ff00ff', gainsboro: '#dcdcdc', ghostwhite: '#f8f8ff', gold: '#ffd700',
@@ -88,12 +91,12 @@ const NAMED_COLORS = {
     lightcoral: '#f08080', lightcyan: '#e0ffff', lightgoldenrodyellow: '#fafad2', lightgray: '#d3d3d3',
     lightgreen: '#90ee90', lightgrey: '#d3d3d3', lightpink: '#ffb6c1', lightsalmon: '#ffa07a',
     lightseagreen: '#20b2aa', lightskyblue: '#87cefa', lightslategray: '#778899', lightslategrey: '#778899',
-    lightsteelblue: '#b0c4de', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
+    lightsteelblue: '#b0e0e6', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
     linen: '#faf0e6', magenta: '#ff00ff', maroon: '#800000', mediumaquamarine: '#66cdaa',
     mediumblue: '#0000cd', mediumorchid: '#ba55d3', mediumpurple: '#9370db', mediumseagreen: '#3cb371',
     mediumslateblue: '#7b68ee', mediumspringgreen: '#00fa9a', mediumturquoise: '#48d1cc', mediumvioletred: '#c71585',
     midnightblue: '#191970', mintcream: '#f5fffa', mistyrose: '#ffe4e1', moccasin: '#ffe4b5',
-    navajowhite: '#ffdead', navy: '#000080', oldlace: '#fdf5e6', olive: '#808000',
+    navajawhite: '#ffdead', navy: '#000080', oldlace: '#fdf5e6', olive: '#808000',
     olivedrab: '#6b8e23', orange: '#ffa500', orangered: '#ff4500', orchid: '#da70d6',
     palegoldenrod: '#eee8aa', palegreen: '#98fb98', paleturquoise: '#afeeee', palevioletred: '#db7093',
     papayawhip: '#ffefd5', peachpuff: '#ffdab9', peru: '#cd853f', pink: '#ffc0cb',
@@ -137,7 +140,7 @@ export const parseHexToBuffer = (str, outBuf, offset) => {
 };
 
 /**
- * Parses a CSS `oklch()` string directly into an OKLCH triplet — no color-space
+ * Parses a CSS `oklch()` string directly into an OKLCH triplet - no color-space
  * conversion needed.
  *
  * Accepts the modern slash-alpha form: `oklch(60% 0.15 250 / 0.5)`. Hue may
@@ -222,6 +225,38 @@ export const parseHslToBuffer = (str, outBuf, offset) => {
     return parseVal(match[4], 1) ?? 1.0;
 };
 
+/**
+ * Parses a CSS `color(display-p3 r g b / alpha?)` string into an OKLCH triplet.
+ *
+ * Supports modern slash-alpha syntax and percentage components (0%-100%).
+ * Components are interpreted in the Display P3 color space (gamma-encoded,
+ * same transfer function as sRGB).
+ *
+ * This is the authoring-time entry point for wide-gamut colors. The resulting
+ * OKLCH may have higher chroma than sRGB-gamut colors.
+ *
+ * @param {string} str - The `color(display-p3 ...)` string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` does not match the expected syntax.
+ */
+export const parseDisplayP3ToBuffer = (str, outBuf, offset) => {
+    const match = str.match(DISPLAY_P3_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid display-p3 color "${str}"`);
+
+    // Parse components (0-1 range, with % support) then scale to byte range
+    // for consistency with displayP3ToOklchBuffer / sRgbToOklchBuffer
+    const r = parseVal(match[1], 1) * 255;
+    const g = parseVal(match[2], 1) * 255;
+    const b = parseVal(match[3], 1) * 255;
+
+    // Accurate Display P3 -> OKLCH path (Session 2)
+    displayP3ToOklchBuffer(r, g, b, outBuf, offset);
+
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
 // ============================================================================
 // 5. MASTER SWITCHBOARD
 // ============================================================================
@@ -231,13 +266,16 @@ export const parseHslToBuffer = (str, outBuf, offset) => {
  * format-specific parser and writes an OKLCH triplet.
  *
  * Supports: named colors, `#RGB[A]`, `#RRGGBB[AA]`, `rgb()` / `rgba()`,
- * `hsl()` / `hsla()`, `oklch()`, `oklab()`.
+ * `hsl()` / `hsla()`, `oklch()`, `oklab()`, `color(display-p3 r g b / alpha?)`.
  *
  * Intended for the **authoring/init phase** of a render pipeline (level loads,
  * theme parsing, gradient compilation). After that, work with the resulting
  * `Float32Array` buffer directly via {@link lerpOklchBuffer} and
  * {@link packOklchBufferToUint32}.
  *
+ * `color(display-p3 ...)` is opt-in wide-gamut input. It never affects the
+ * default sRGB hot path.
+ *
  * @param {string} str - The CSS color string
  * @param {Float32Array} outBuf - Pre-allocated destination
  * @param {number} offset - Start index of the L, C, H triplet
@@ -257,6 +295,9 @@ export const parseCSSColor = (str, outBuf, offset) => {
     if (cleanStr.startsWith('oklab')) return parseOklabToBuffer(cleanStr, outBuf, offset);
     if (cleanStr.startsWith('rgb')) return parseRgbToBuffer(cleanStr, outBuf, offset);
     if (cleanStr.startsWith('hsl')) return parseHslToBuffer(cleanStr, outBuf, offset);
+    if (cleanStr.startsWith('color(') && cleanStr.includes('display-p3')) {
+        return parseDisplayP3ToBuffer(cleanStr, outBuf, offset);
+    }
 
     throw new Error(`lite-color-engine: Unsupported color format "${str}".`);
 };

package/src/convert.js

@@ -1,12 +1,14 @@
 const RAD_TO_DEG = 180 / Math.PI;
 
 /**
- * IEC 61966-2-1 sRGB linearization.
- * @param {number} c - Normalized non-linear sRGB channel in [0, 1]
+ * IEC 61966-2-1 sRGB / Display-P3 linearization (EOTF inverse).
+ * Both color spaces use the same transfer function.
+ *
+ * @param {number} c - Normalized non-linear channel in [0, 1]
  * @returns {number} Linear-light value in [0, 1]
  * @internal
  */
-const linearize = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+export const linearize = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
 
 /**
  * Converts standard sRGB (0-255 byte channels) into a flat OKLCH buffer.
@@ -15,7 +17,7 @@ const linearize = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.05
  * matrix multiply) and hard-clamps output lightness to [0, 1]. Hue is
  * canonicalized to [0, 360).
  *
- * Algorithm: Björn Ottosson's OKLab (2020) — sRGB -> linear sRGB -> LMS ->
+ * Algorithm: Bjorn Ottosson's OKLab (2020) - sRGB -> linear sRGB -> LMS ->
  * non-linear LMS (cube root) -> OKLab -> polar OKLCH.
  *
  * @param {number} r - Red channel [0, 255]
@@ -31,7 +33,7 @@ export const sRgbToOklchBuffer = (r, g, b, outBuf, outOffset) => {
     const g_lin = linearize(g / 255);
     const b_lin = linearize(b / 255);
 
-    // 2. Linear sRGB -> linear LMS.
+    // 2. Linear sRGB -> linear LMS (combined matrix from OKLab reference).
     const lms_l = 0.4122214708 * r_lin + 0.5363325363 * g_lin + 0.0514459929 * b_lin;
     const lms_m = 0.2119034982 * r_lin + 0.6806995451 * g_lin + 0.1073969566 * b_lin;
     const lms_s = 0.0883024619 * r_lin + 0.2817188376 * g_lin + 0.6299787005 * b_lin;
@@ -56,3 +58,123 @@ export const sRgbToOklchBuffer = (r, g, b, outBuf, outOffset) => {
     outBuf[outOffset + 1] = chroma;
     outBuf[outOffset + 2] = hue;
 };
+
+// -----------------------------------------------------------------------------
+// Display P3 support (Session 2)
+// High-precision matrices sourced from CSS Color Module Level 4 + OKLab reference
+// implementation by Bjorn Ottosson. Combined for minimal code size and speed.
+// -----------------------------------------------------------------------------
+
+/**
+ * High-precision linear Display P3 (D65) -> XYZ (D65)
+ */
+const P3_TO_XYZ = [
+    [0.4865709486482162, 0.26566769316909306, 0.1982172852343625],
+    [0.2289745640697488, 0.6917385218365062,  0.079286914093745],
+    [0.0000000000000000, 0.0451133816152514,  1.043944368900976]
+];
+
+/**
+ * High-precision XYZ (D65) -> LMS (OKLab cone fundamentals)
+ */
+const XYZ_TO_LMS = [
+    [ 0.8190224379967030, 0.3619062600528904, -0.1288737815209879],
+    [ 0.0329836671980271, 0.9292868615863434,  0.0361446681699989],
+    [ 0.0481772077560169, 0.2642395317527308,  0.6335478284694309]
+];
+
+/**
+ * Converts Display P3 (0-255 byte channels) into a flat OKLCH buffer.
+ *
+ * Uses the same OKLab pipeline as sRGB but with Display P3 primaries.
+ * This allows correct representation of colors outside the sRGB gamut
+ * (higher possible chroma values).
+ *
+ * Defends against negative cube roots and clamps lightness to [0, 1].
+ *
+ * @param {number} r - Red channel in Display P3 [0, 255]
+ * @param {number} g - Green channel in Display P3 [0, 255]
+ * @param {number} b - Blue channel in Display P3 [0, 255]
+ * @param {Float32Array} outBuf - Destination buffer
+ * @param {number} outOffset - Start index for the L, C, H triplet
+ * @returns {void}
+ */
+export const displayP3ToOklchBuffer = (r, g, b, outBuf, outOffset) => {
+    // 1. Normalize and linearize (same EOTF as sRGB)
+    const r_lin = linearize(r / 255);
+    const g_lin = linearize(g / 255);
+    const b_lin = linearize(b / 255);
+
+    // 2. Linear Display P3 -> XYZ
+    const x = P3_TO_XYZ[0][0] * r_lin + P3_TO_XYZ[0][1] * g_lin + P3_TO_XYZ[0][2] * b_lin;
+    const y = P3_TO_XYZ[1][0] * r_lin + P3_TO_XYZ[1][1] * g_lin + P3_TO_XYZ[1][2] * b_lin;
+    const z = P3_TO_XYZ[2][0] * r_lin + P3_TO_XYZ[2][1] * g_lin + P3_TO_XYZ[2][2] * b_lin;
+
+    // 3. XYZ -> linear LMS (OKLab)
+    const lms_l = XYZ_TO_LMS[0][0] * x + XYZ_TO_LMS[0][1] * y + XYZ_TO_LMS[0][2] * z;
+    const lms_m = XYZ_TO_LMS[1][0] * x + XYZ_TO_LMS[1][1] * y + XYZ_TO_LMS[1][2] * z;
+    const lms_s = XYZ_TO_LMS[2][0] * x + XYZ_TO_LMS[2][1] * y + XYZ_TO_LMS[2][2] * z;
+
+    // 4. Non-linear LMS (cube root) - same defense as sRGB path
+    const l_ = Math.cbrt(lms_l < 0 ? 0 : lms_l);
+    const m_ = Math.cbrt(lms_m < 0 ? 0 : lms_m);
+    const s_ = Math.cbrt(lms_s < 0 ? 0 : lms_s);
+
+    // 5. Non-linear LMS -> OKLab (identical coefficients to sRGB path)
+    const lab_l = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+    const lab_a = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    const lab_b = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+
+    // 6. OKLab -> OKLCH (polar) - identical to sRGB path
+    const chroma = Math.sqrt(lab_a * lab_a + lab_b * lab_b);
+    let hue = Math.atan2(lab_b, lab_a) * RAD_TO_DEG;
+    if (hue < 0) hue += 360;
+
+    // 7. Write with lightness clamp
+    outBuf[outOffset] = lab_l < 0 ? 0 : (lab_l > 1 ? 1 : lab_l);
+    outBuf[outOffset + 1] = chroma;
+    outBuf[outOffset + 2] = hue;
+};
+
+/**
+ * Converts an OKLCH triplet to linear-light Display P3 RGB.
+ * Writes [r, g, b] linear values (can be outside [0,1] for out-of-gamut colors)
+ * into the provided `out` Float32Array (length >= 3).
+ *
+ * This is the inverse of the forward path above. Used by the P3 packers and
+ * available for custom P3 gamut-mapping. Output channels may fall outside
+ * [0, 1] for colors beyond the P3 gamut; clamp or map before encoding.
+ *
+ * @param {number} L - Lightness [0, 1]
+ * @param {number} C - Chroma [0, +inf)
+ * @param {number} H - Hue [0, 360)
+ * @param {Float32Array} out - Destination (length >= 3); receives linear [r, g, b]
+ * @returns {void}
+ */
+export const oklchToLinearP3 = (L, C, H, out) => {
+    const hRad = (H * Math.PI) / 180;
+    const a = C * Math.cos(hRad);
+    const b = C * Math.sin(hRad);
+
+    // OKLab -> non-linear LMS (inverse of the OKLab matrix)
+    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+
+    // Non-linear LMS -> linear LMS (cube)
+    const lms_l = l_ * l_ * l_;
+    const lms_m = m_ * m_ * m_;
+    const lms_s = s_ * s_ * s_;
+
+    // Linear LMS -> XYZ (inverse of XYZ_TO_LMS)
+    // Using the analytical inverse for precision
+    const x =  1.2268798758459243 * lms_l - 0.5578149944602171 * lms_m + 0.2813910456659647 * lms_s;
+    const y = -0.0405757452148008 * lms_l + 1.1122868032803170 * lms_m - 0.0717110580655164 * lms_s;
+    const z = -0.0763729366746601 * lms_l - 0.4214933324022432 * lms_m + 1.5869240198367816 * lms_s;
+
+    // XYZ -> linear Display P3 (inverse of P3_TO_XYZ)
+    // Using the analytical inverse matrix
+    out[0] =  2.4934969119414263 * x - 0.9313836179191239 * y - 0.4027107844507168 * z;
+    out[1] = -0.8294889695615749 * x + 1.7626640603183463 * y + 0.0236246858419436 * z;
+    out[2] =  0.0358458302437845 * x - 0.0761723892680418 * y + 0.9568845240076702 * z;
+};

package/src/delta.js

@@ -0,0 +1,37 @@
+const _RAD = Math.PI / 180;
+
+/**
+ * ΔE-OK color difference: Euclidean distance in OKLab between two buffered
+ * OKLCH colors. Zero-alloc, primitive math only.
+ *
+ * Typical scale: 0.00–0.02 indistinguishable, 0.02–0.05 subtle,
+ * 0.05–0.15 clearly different, 0.15+ unambiguously different.
+ *
+ * Use for: palette dedupe, contrast checks, "is this close enough"
+ * assertions, nearest-color lookup, and the CVD-audit workflow in
+ * lite-hueforge/colorways.
+ *
+ * @param {Float32Array} bufA
+ * @param {number} offsetA
+ * @param {Float32Array} bufB
+ * @param {number} offsetB
+ * @returns {number}
+ */
+export const deltaEOK = (bufA, offsetA, bufB, offsetB) => {
+    const La = bufA[offsetA];
+    const Ca = bufA[offsetA + 1];
+    const Ha = bufA[offsetA + 2];
+    const Lb = bufB[offsetB];
+    const Cb = bufB[offsetB + 1];
+    const Hb = bufB[offsetB + 2];
+    const hARad = Ha * _RAD;
+    const hBRad = Hb * _RAD;
+    const aA = Ca * Math.cos(hARad);
+    const bA = Ca * Math.sin(hARad);
+    const aB = Cb * Math.cos(hBRad);
+    const bB = Cb * Math.sin(hBRad);
+    const dL = La - Lb;
+    const dA = aA - aB;
+    const dB = bA - bB;
+    return Math.sqrt(dL * dL + dA * dA + dB * dB);
+};