@zakkster/lite-color-engine 1.1.0 → 1.3.0

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/runtime.js

@@ -1,4 +1,5 @@
 import { lerp, lerpAngle } from '@zakkster/lite-lerp';
+import { oklchToLinearP3 } from './convert.js';
 
 const DEG_TO_RAD = Math.PI / 180;
 
@@ -7,7 +8,7 @@ const DEG_TO_RAD = Math.PI / 180;
  *
  * Hue is canonicalized to [0, 360) via `lerpAngle` (shortest-path) so gradients
  * never wrap the long way around the color wheel. Lightness is hard-clamped
- * to [0, 1] and chroma to [0, +∞).
+ * to [0, 1] and chroma to [0, +inf).
  *
  * Source and destination may be the same buffer at different offsets.
  *
@@ -35,9 +36,50 @@ export const lerpOklchBuffer = (bufA, offsetA, bufB, offsetB, t, outBuf, outOffs
     outBuf[outOffset + 2] = h < 0 ? h + 360 : h;
 };
 
+/**
+ * Batch sibling of {@link lerpOklchBuffer}. Interpolates `n` consecutive OKLCH
+ * triplets (stride 3) with a single shared `t`, amortizing per-call overhead
+ * across large particle systems (100k+ entities).
+ *
+ * For each i in [0, n): lerps a[offA + i*3 ..] with b[offB + i*3 ..] into
+ * out[offOut + i*3 ..]. Per-triplet math is identical to the scalar version,
+ * so results are bit-for-bit equal to calling it n times.
+ *
+ * In-place is safe (a === out, offA === offOut): each iteration reads its three
+ * source lanes before writing them. Zero allocations; monomorphic hot loop.
+ *
+ * @param {Float32Array} a - Source buffer A
+ * @param {number} offA - Base offset of the first color in A
+ * @param {Float32Array} b - Source buffer B
+ * @param {number} offB - Base offset of the first color in B
+ * @param {number} t - Interpolation factor [0, 1] (extrapolates then clamps)
+ * @param {Float32Array} out - Destination buffer
+ * @param {number} offOut - Base offset of the first output color
+ * @param {number} n - Number of triplets to process (n <= 0 is a no-op)
+ * @returns {void}
+ */
+export const lerpOklchBufferN = (a, offA, b, offB, t, out, offOut, n) => {
+    if (n <= 0) return;
+    for (let i = 0; i < n; i++) {
+        const ia = offA + i * 3;
+        const ib = offB + i * 3;
+        const io = offOut + i * 3;
+
+        const l = lerp(a[ia], b[ib], t);
+        out[io] = l < 0 ? 0 : (l > 1 ? 1 : l);
+
+        const c = lerp(a[ia + 1], b[ib + 1], t);
+        out[io + 1] = c < 0 ? 0 : c;
+
+        let h = lerpAngle(a[ia + 2], b[ib + 2], t);
+        h = h % 360;
+        out[io + 2] = h < 0 ? h + 360 : h;
+    }
+};
+
 /**
  * Internal: shared OKLCH -> linear sRGB kernel.
- * Inlined into both pack variants for V8 to monomorphize.
+ * Inlined into every sRGB pack variant so V8 monomorphizes it.
  *
  * Returns a 3-tuple via `outRgb` (length 3). Strictly clamped to [0, 1].
  * @internal
@@ -59,8 +101,7 @@ const oklchToLinearSrgbClamped = (l, c, h, outRgb) => {
     const g = -1.2684380046 * lms_l + 2.6097574011 * lms_m - 0.3413193965 * lms_s;
     const b = -0.0041960863 * lms_l - 0.7034186147 * lms_m + 1.7076147010 * lms_s;
 
-    // Hard gamut clamp (fast path; replaces the expensive MINDE algorithm).
-    // Chroma reduction (Lab-space gamut mapping) is planned for v1.1.
+    // Hard gamut clamp (fast path; MINDE chroma reduction lives on the /gamut subpath).
     outRgb[0] = r < 0 ? 0 : (r > 1 ? 1 : r);
     outRgb[1] = g < 0 ? 0 : (g > 1 ? 1 : g);
     outRgb[2] = b < 0 ? 0 : (b > 1 ? 1 : b);
@@ -68,11 +109,42 @@ const oklchToLinearSrgbClamped = (l, c, h, outRgb) => {
 
 // Module-level scratch (zero-GC: single allocation at module load).
 const _scratchRgb = new Float32Array(3);
+const _scratchRgbP3 = new Float32Array(3);
+
+/**
+ * Precomputed 4096-entry LUT for the sRGB transfer (linear -> encoded byte).
+ * Entry i corresponds to linear value i/4095, so the table spans [0, 1] exactly.
+ * The linear branch (slope 12.92) is the steepest region; at 4096 samples its
+ * per-step delta is < 1 byte, so nearest-index lookups stay within ~1 LSB of
+ * the exact pow() encoding. One-time module-load cost, then O(1) lookup.
+ * @internal
+ */
+const SRGB_LUT = new Uint8ClampedArray(4096);
+{
+    for (let i = 0; i < 4096; i++) {
+        const c = i / 4095;
+        const enc = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+        SRGB_LUT[i] = (enc * 255 + 0.5) | 0;
+    }
+}
+
+/**
+ * LUT-based linear-to-sRGB byte using nearest-index lookup. Near-exact (~1 LSB)
+ * versus {@link linearToSrgbByte} but branch-free and pow-free on the hot path.
+ * @internal
+ */
+const linearToSrgbByteLut = (c) => {
+    if (c <= 0) return 0;
+    if (c >= 1) return 255;
+    return SRGB_LUT[(c * 4095 + 0.5) | 0];
+};
 
 /**
  * Encodes a linear-light channel (already clamped to [0, 1]) to an sRGB
  * 8-bit byte using the proper IEC 61966-2-1 transfer function. Round-tripping
  * sRGB(255-bytes) -> OKLCH -> here recovers the original byte exactly.
+ *
+ * This is also the correct transfer function for Display P3.
  * @internal
  */
 const linearToSrgbByte = (c) => {
@@ -84,7 +156,7 @@ const linearToSrgbByte = (c) => {
 
 /**
  * Converts an OKLCH buffer triplet to a 32-bit unsigned integer in
- * little-endian RGBA byte order — the format consumed directly by a
+ * little-endian RGBA byte order - the format consumed directly by a
  * `Uint32Array` view of `Canvas ImageData`.
  *
  * Uses the proper sRGB transfer function (`pow(c, 1/2.4)` branch). For a
@@ -132,10 +204,113 @@ export const packOklchBufferToUint32Fast = (buf, offset, alpha = 1.0) => {
     return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
 };
 
+/**
+ * Batch sibling of {@link packOklchBufferToUint32}. Packs `n` OKLCH triplets
+ * (stride 3, from `src`) into `n` consecutive Uint32 pixels (stride 1, into
+ * `dst`) - the shape a SoA particle system feeds straight into `ImageData`.
+ *
+ * With `useLut=false` the output is bit-for-bit identical to calling
+ * {@link packOklchBufferToUint32} n times. With `useLut=true` it uses the 4k
+ * transfer LUT: near-exact (~1 LSB) at close to fast-packer throughput, with a
+ * single one-time table allocation and no per-color pow(). The branch is hoisted
+ * out of the loop so each variant stays monomorphic.
+ *
+ * @param {Float32Array} src - Source OKLCH buffer (stride 3)
+ * @param {number} offSrc - Base offset of the first triplet in src
+ * @param {Uint32Array} dst - Destination packed-color buffer (stride 1)
+ * @param {number} offDst - Base offset of the first packed color in dst
+ * @param {number} n - Number of colors to pack (n <= 0 is a no-op)
+ * @param {number} [alpha=1.0] - Shared alpha for all n colors
+ * @param {boolean} [useLut=false] - Opt in to the 4k LUT transfer (near-exact, faster)
+ * @returns {void}
+ */
+export const packOklchBufferToUint32IntoN = (src, offSrc, dst, offDst, n, alpha = 1.0, useLut = false) => {
+    if (n <= 0) return;
+    const a8 = alpha <= 0 ? 0 : (alpha >= 1 ? 255 : (alpha * 255 + 0.5) | 0);
+    const aHi = a8 << 24;
+
+    if (useLut) {
+        for (let i = 0; i < n; i++) {
+            const io = offSrc + i * 3;
+            oklchToLinearSrgbClamped(src[io], src[io + 1], src[io + 2], _scratchRgb);
+            const r8 = linearToSrgbByteLut(_scratchRgb[0]);
+            const g8 = linearToSrgbByteLut(_scratchRgb[1]);
+            const b8 = linearToSrgbByteLut(_scratchRgb[2]);
+            dst[offDst + i] = (aHi | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+        }
+    } else {
+        for (let i = 0; i < n; i++) {
+            const io = offSrc + i * 3;
+            oklchToLinearSrgbClamped(src[io], src[io + 1], src[io + 2], _scratchRgb);
+            const r8 = linearToSrgbByte(_scratchRgb[0]);
+            const g8 = linearToSrgbByte(_scratchRgb[1]);
+            const b8 = linearToSrgbByte(_scratchRgb[2]);
+            dst[offDst + i] = (aHi | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+        }
+    }
+};
+
+/**
+ * Internal helper: OKLCH -> linear Display P3 with hard clamp to [0, 1].
+ * Mirrors oklchToLinearSrgbClamped but targets the wider P3 gamut.
+ * @internal
+ */
+const oklchToLinearP3Clamped = (l, c, h, outRgb) => {
+    oklchToLinearP3(l, c, h, outRgb);
+    outRgb[0] = outRgb[0] < 0 ? 0 : (outRgb[0] > 1 ? 1 : outRgb[0]);
+    outRgb[1] = outRgb[1] < 0 ? 0 : (outRgb[1] > 1 ? 1 : outRgb[1]);
+    outRgb[2] = outRgb[2] < 0 ? 0 : (outRgb[2] > 1 ? 1 : outRgb[2]);
+};
+
+/**
+ * Converts an OKLCH buffer triplet to a 32-bit unsigned integer in
+ * little-endian RGBA byte order, encoded for **Display P3** color space.
+ *
+ * Use this when your canvas context was created with `{ colorSpace: 'display-p3' }`.
+ * Colors that are out of sRGB but inside P3 will be preserved with higher
+ * saturation than the regular sRGB packers.
+ *
+ * The transfer function is identical to sRGB (IEC 61966-2-1).
+ *
+ * @param {Float32Array} buf - Buffer containing the OKLCH triplet
+ * @param {number} offset - Start index in the buffer
+ * @param {number} [alpha=1.0] - Alpha [0, 1]; values outside the range are clamped
+ * @returns {number} 32-bit unsigned integer (little-endian RGBA byte order)
+ */
+export const packOklchBufferToUint32P3 = (buf, offset, alpha = 1.0) => {
+    oklchToLinearP3Clamped(buf[offset], buf[offset + 1], buf[offset + 2], _scratchRgbP3);
+    const r8 = linearToSrgbByte(_scratchRgbP3[0]);
+    const g8 = linearToSrgbByte(_scratchRgbP3[1]);
+    const b8 = linearToSrgbByte(_scratchRgbP3[2]);
+    const a8 = alpha <= 0 ? 0 : (alpha >= 1 ? 255 : (alpha * 255 + 0.5) | 0);
+    return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+};
+
+/**
+ * Faster, less accurate sibling of {@link packOklchBufferToUint32P3}.
+ *
+ * Uses `Math.sqrt` approximation for the transfer function (same trade-off as
+ * the sRGB fast path). Useful for high-volume particle systems or when
+ * baking many P3 gradients where absolute round-trip precision is not critical.
+ *
+ * @param {Float32Array} buf - Buffer containing the OKLCH triplet
+ * @param {number} offset - Start index in the buffer
+ * @param {number} [alpha=1.0] - Alpha [0, 1]; values outside the range are clamped
+ * @returns {number} 32-bit unsigned integer (little-endian RGBA byte order)
+ */
+export const packOklchBufferToUint32P3Fast = (buf, offset, alpha = 1.0) => {
+    oklchToLinearP3Clamped(buf[offset], buf[offset + 1], buf[offset + 2], _scratchRgbP3);
+    const r8 = (Math.sqrt(_scratchRgbP3[0]) * 255) | 0;
+    const g8 = (Math.sqrt(_scratchRgbP3[1]) * 255) | 0;
+    const b8 = (Math.sqrt(_scratchRgbP3[2]) * 255) | 0;
+    const a8 = alpha <= 0 ? 0 : (alpha >= 1 ? 255 : (alpha * 255) | 0);
+    return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+};
+
 /**
  * Zero-GC LUT sampler. Looks up a baked gradient color by `t` in [0, 1].
  *
- * Performs an inline clamp + bitwise-truncated index — no allocations, no
+ * Performs an inline clamp + bitwise-truncated index - no allocations, no
  * function calls, no bounds checks beyond the single comparison pair. Use
  * inside particle systems, shader-style canvas loops, etc.
  *