@zakkster/lite-color-engine 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,21 +1,52 @@
 # Changelog
 
+## [1.3.0] - 2026-07-10
+
+### Added
+- **Batch kernels for large particle systems (100k+):**
+  - `lerpOklchBufferN(a, offA, b, offB, t, out, offOut, n)` - interpolate `n` OKLCH
+    triplets (stride 3) with a shared `t`. Bit-for-bit identical to `n` scalar
+    `lerpOklchBuffer` calls; supports in-place and offset addressing.
+  - `packOklchBufferToUint32IntoN(src, offSrc, dst, offDst, n, alpha?, useLut?)` -
+    pack `n` OKLCH triplets straight into a `Uint32Array` (dst stride 1), the exact
+    shape a SoA particle system blits into `ImageData`.
+- **Opt-in 4096-entry sRGB transfer LUT** (`useLut: true` on the batch packer):
+  removes `pow()` from the hot path for **~2.7x** packing throughput at **within
+  1 LSB** of the exact encoder. Single one-time table allocation.
+
+### Performance (measured, Node 22 / V8, 100k in-gamut triplets, median of 80)
+- Packing: accurate ~3.2M colors/s (~32 ms/frame); LUT ~14M colors/s (~7 ms/frame) - **~4.4x**.
+  The LUT runs at Fast-packer speed (`sqrt`) while staying within 1 LSB of exact.
+- 100k lerp+pack fits a 60fps frame only with the LUT (~10 ms vs ~35 ms accurate).
+- Honest caveat: the speedup is the **LUT**, not the batching. Accurate batch
+  packing runs at the same speed as a scalar loop (pow-bound), and batch lerp is
+  not measurably faster than a scalar loop in V8. The batch APIs are primarily
+  about ergonomics (whole-buffer ops) and unlocking the LUT path. Reproduce with
+  `node bench/benchmark.mjs`.
+
+### Notes
+- All hot paths remain zero-GC and allocation-free per frame.
+- No breaking changes; all v1.2 exports (including Display P3 and `sampleColorLUT`)
+  are retained.
+
+---
+
 ## [1.2.0] - 2026-07-10
 
 ### Added
 - **Wide Gamut Support (Display P3)**
   - `parseCSSColor('color(display-p3 r g b / alpha)')` now supported in the universal parser
-  - New `displayP3ToOklchBuffer()` conversion function with accurate P3 → XYZ → OKLab pipeline
-  - `packOklchBufferToUint32P3()` — accurate packer for `display-p3` canvas contexts
-  - `packOklchBufferToUint32P3Fast()` — high-speed sqrt approximation for P3 output
+  - New `displayP3ToOklchBuffer()` conversion function with accurate P3 -> XYZ -> OKLab pipeline
+  - `packOklchBufferToUint32P3()` - accurate packer for `display-p3` canvas contexts
+  - `packOklchBufferToUint32P3Fast()` - high-speed sqrt approximation for P3 output
   - `oklchToLinearP3()` inverse conversion helper
 
 - **Accuracy Tiers** (now clearly documented)
   - Fast (`packOklchBufferToUint32Fast`)
   - Accurate-Clamp (default `packOklchBufferToUint32`)
-  - Gamut-Mapped (`packOklchBufferToUint32MINDE` / P3 equivalent)
+  - Gamut-Mapped (`packOklchBufferToUint32MINDE`, on the `/gamut` subpath)
 
-- `bakeGradientToUint32()` already supported custom packers — now officially documented for P3 usage.
+- `bakeGradientToUint32()` already supported custom packers - now officially documented for P3 usage.
 
 ### Changed
 - Improved documentation around color gamut handling and when to use each packer.
@@ -28,5 +59,6 @@
 ---
 
 ## [1.1.0] - Previous
-- Added `deltaEOK` and MINDE gamut mapping (`/gamut` sub-export)
-- Added palette remapping utilities (`/remap`)
+
+- Core zero-GC OKLCH engine: parsing, buffer lerp, packers, delta-E, gradient LUT baking,
+  gamut mapping (`/gamut`) and palette remap (`/remap`) subpaths.

package/README.md

@@ -1,7 +1,41 @@
 # @zakkster/lite-color-engine
 
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-color-engine.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-color-engine)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Hot%20path-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-color-engine?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-color-engine)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-color-engine?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-color-engine)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-color-engine?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-color-engine)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
 **Zero-GC, data-oriented OKLCH color engine** for high-performance WebGL / Canvas pipelines.
 
+## v1.3 Highlights — Batch Kernels + 4k Transfer LUT
+
+Built for the 100k-particle case: bulk buffer -> buffer operations plus an opt-in
+transfer LUT that removes `pow()` from the hot path.
+
+- `lerpOklchBufferN(a, offA, b, offB, t, out, offOut, n)` — interpolate `n` triplets in one call.
+- `packOklchBufferToUint32IntoN(src, offSrc, dst, offDst, n, alpha?, useLut?)` — pack `n` OKLCH triplets straight into a `Uint32Array`.
+- `useLut: true` opts into a precomputed 4096-entry sRGB transfer LUT — **~4.4x** the packing throughput of the accurate path, within **1 LSB** of exact. That is essentially Fast-packer speed at near-exact accuracy (the `sqrt` Fast packer drifts ~10/255). One module-load allocation; still zero-GC per frame.
+
+**Honest note on batching.** The LUT is the real win. The batch functions themselves
+mostly save ergonomics, not cycles: in V8 the accurate batch packer runs at essentially
+the same speed as a scalar loop (the cost is `pow()`, not call overhead), and batch lerp
+is only marginally faster. Reach for `useLut: true` when you need the speedup.
+
+| Packing 100k OKLCH -> Uint32 / frame | Throughput | ms/frame |
+|--------------------------------------|-----------|----------|
+| scalar loop / batch accurate         | ~3.2M/s   | ~32 ms   |
+| **batch + `useLut: true`**           | **~14M/s**| **~7 ms**|
+| Fast (`sqrt`, ~10/255 error)         | ~15M/s    | ~7 ms    |
+
+*(Node 22 / V8, 100k in-gamut triplets, median of 80 runs; browser V8 is comparable.
+Reproduce with `node bench/benchmark.mjs`. Your numbers will vary.)*
+
 ## v1.2 Highlights — Wide Gamut + Accuracy Tiers
 
 - Full `color(display-p3 r g b / alpha)` parsing support
@@ -41,6 +75,26 @@ lerpOklchBuffer(bufA, 0, bufB, 0, t, temp, 0);
 const pixel = packOklchBufferToUint32P3(temp, 0); // or packOklchBufferToUint32
 ```
 
+### Batch (100k particles)
+
+```js
+import {
+  lerpOklchBufferN,
+  packOklchBufferToUint32IntoN
+} from '@zakkster/lite-color-engine';
+
+const N = 100000;
+const from = new Float32Array(N * 3);   // OKLCH triplets
+const to   = new Float32Array(N * 3);
+const cur  = new Float32Array(N * 3);
+const px   = new Uint32Array(N);        // -> view of ImageData
+
+// Per frame, zero allocations:
+lerpOklchBufferN(from, 0, to, 0, t, cur, 0, N);
+packOklchBufferToUint32IntoN(cur, 0, px, 0, N, 1.0, /* useLut */ true);
+// px now holds N packed RGBA pixels; blit via a Uint32Array view of ImageData.
+```
+
 ## Accuracy Tiers
 
 | Tier              | Function                        | Use Case                          | Trade-off          |

package/index.d.ts

@@ -155,6 +155,22 @@ export function lerpOklchBuffer(
     outOffset: number
 ): void;
 
+/**
+ * Batch lerp for particle systems / high-N use cases. Amortizes JS call overhead.
+ *
+ * Lerps n triplets with shared `t`: a[offA + i*3...] <-> b[offB + i*3...] -> out[offOut + i*3...]
+ */
+export function lerpOklchBufferN(
+    a: Float32Array,
+    offA: number,
+    b: Float32Array,
+    offB: number,
+    t: number,
+    out: Float32Array,
+    offOut: number,
+    n: number
+): void;
+
 /**
  * Encodes an OKLCH triplet to a 32-bit unsigned integer in **little-endian
  * RGBA** byte order - the format consumed directly by `Canvas ImageData` via
@@ -196,6 +212,20 @@ export function packOklchBufferToUint32Fast(
     alpha?: number
 ): number;
 
+/**
+ * Batch packer: n OKLCH triplets -> n Uint32 packed colors (stride 1 in dst).
+ * Opt-in 4k sRGB LUT (`useLut=true`) for fast-packer throughput at near-exact accuracy.
+ */
+export function packOklchBufferToUint32IntoN(
+    src: Float32Array,
+    offSrc: number,
+    dst: Uint32Array,
+    offDst: number,
+    n: number,
+    alpha?: number,
+    useLut?: boolean
+): void;
+
 /**
  * Encodes an OKLCH triplet to a 32-bit unsigned integer in little-endian RGBA
  * byte order for a **Display P3** canvas context

package/index.js

@@ -12,8 +12,10 @@ export { bakeGradientToUint32 } from './src/lut.js';
 
 export {
     lerpOklchBuffer,
+    lerpOklchBufferN,
     packOklchBufferToUint32,
     packOklchBufferToUint32Fast,
+    packOklchBufferToUint32IntoN,
     packOklchBufferToUint32P3,
     packOklchBufferToUint32P3Fast,
     sampleColorLUT

package/llms.txt

@@ -1,4 +1,4 @@
-# lite-color-engine — LLM Reference (v1.2)
+# lite-color-engine - LLM Reference (v1.3)
 
 ## Core Exports
 
@@ -11,12 +11,18 @@
 - `displayP3ToOklchBuffer(r, g, b, out, off)` — New in v1.2
 - `oklchToLinearP3(L, C, H, out)` — Inverse for P3 packing
 
-### Runtime (Hot Path — Zero GC)
+### Runtime (Hot Path - Zero GC)
 - `lerpOklchBuffer(...)`
-- `packOklchBufferToUint32(buf, off, alpha?)` — Accurate sRGB
-- `packOklchBufferToUint32Fast(...)` — Fast approx
-- `packOklchBufferToUint32P3(buf, off, alpha?)` — Accurate P3 output
-- `packOklchBufferToUint32P3Fast(...)` — Fast P3 output
+- `packOklchBufferToUint32(buf, off, alpha?)` - Accurate sRGB
+- `packOklchBufferToUint32Fast(...)` - Fast approx
+- `packOklchBufferToUint32P3(buf, off, alpha?)` - Accurate P3 output
+- `packOklchBufferToUint32P3Fast(...)` - Fast P3 output
+- `sampleColorLUT(lut, t)` - O(1) lookup into a baked gradient LUT
+
+### Batch kernels (v1.3, for 100k+ particle systems)
+- `lerpOklchBufferN(a, offA, b, offB, t, out, offOut, n)` - bulk lerp n triplets (stride 3), bit-exact to n scalar calls.
+- `packOklchBufferToUint32IntoN(src, offSrc, dst, offDst, n, alpha?, useLut?)` - bulk pack n OKLCH -> Uint32 (dst stride 1). `useLut=true` uses the 4k transfer LUT (~4.4x throughput vs accurate, within 1 LSB; Fast-packer speed at near-exact accuracy).
+- Note: the batch win comes from `useLut`, not from call-amortization (accurate batch ~= scalar loop in V8; pow-bound).
 
 ### Gamut mapping (subpath: `@zakkster/lite-color-engine/gamut`, NOT hot-path)
 - `packOklchBufferToUint32MINDE(buf, off, alpha?)` — MINDE chroma-reduction gamut map. ~30x slower than the core packer; use at LUT-build/authoring time.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-color-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "description": "Zero-GC, data-oriented OKLCH color engine with MINDE gamut mapping and palette-remap kernels for WebGL/Canvas pipelines.",
+  "description": "Zero-GC, data-oriented OKLCH color engine and WebGL/Canvas buffer pipeline.",
   "type": "module",
   "sideEffects": false,
   "main": "./index.js",
@@ -59,7 +59,8 @@
     "game-dev"
   ],
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "bench": "node bench/benchmark.mjs"
   },
   "dependencies": {
     "@zakkster/lite-lerp": "^1.0.0"

package/src/runtime.js

@@ -36,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
@@ -60,7 +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).
+    // 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);
@@ -70,6 +111,34 @@ const oklchToLinearSrgbClamped = (l, c, h, outRgb) => {
 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
@@ -136,8 +205,54 @@ export const packOklchBufferToUint32Fast = (buf, offset, alpha = 1.0) => {
 };
 
 /**
- * Internal helper: OKLCH -> linear Display P3 with hard clamp to [0,1].
- * Mirrors the structure of oklchToLinearSrgbClamped but targets the wider P3 gamut.
+ * 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) => {