@zakkster/lite-color-engine 1.0.4 → 1.2.0

package/llms.txt

@@ -1,201 +1,38 @@
-# @zakkster/lite-color-engine — LLM Reference
+# lite-color-engine — LLM Reference (v1.2)
 
-> Zero-GC, data-oriented OKLCH color engine for WebGL/Canvas rendering pipelines.
-> Buffer-and-offset API. Three layers: authoring (CSS parsing), LUT (gradient
-> baking), runtime (zero-allocation hot path).
+## Core Exports
 
-## Identity
+### Parsing
+- `parseCSSColor(str, outBuf, offset)` — Universal parser. Now supports `color(display-p3 r g b / alpha)`
+- `parseDisplayP3ToBuffer(str, outBuf, offset)` — Direct P3 parser
 
-- **Package name:** `@zakkster/lite-color-engine`
-- **Module type:** ESM only (`"type": "module"`)
-- **Peer dependency:** `@zakkster/lite-lerp` (provides `lerp`, `lerpAngle`)
-- **Bundle:** sub-2KB min+gzip
-- **Side effects:** none (`"sideEffects": false`)
-- **Node:** `>=18`
+### Conversion
+- `sRgbToOklchBuffer(r, g, b, out, off)`
+- `displayP3ToOklchBuffer(r, g, b, out, off)` — New in v1.2
+- `oklchToLinearP3(L, C, H, out)` — Inverse for P3 packing
 
-## Mental model
+### 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
 
-Every color in this library is exactly **3 contiguous Float32 entries** in a `Float32Array`: `[L, C, H]`.
+### 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.
 
-- `L` (Lightness): `[0, 1]`, perceptually uniform.
-- `C` (Chroma): `[0, ~0.4]` in practice, mathematically unbounded but only a small chroma range maps to displayable sRGB.
-- `H` (Hue): `[0, 360)` degrees. Always canonicalized after every write.
+### LUT
+- `bakeGradientToUint32(..., packer?)` — Accepts any of the above packers
 
-Alpha is **not** stored in the OKLCH buffer. Parsers return alpha as a `number`. If you need alpha alongside color, store it in a sibling `Float32Array` or add a fourth slot yourself (the library only reads the first three).
+## Key Principles
+- All hot-path functions are allocation-free
+- P3 is strictly opt-in
+- Use `Float32Array` buffers for everything
+- Prefer `parse*ToBuffer` at init time
 
-The output of the pack functions is a 32-bit unsigned integer in **little-endian RGBA byte order** — exactly what `new Uint32Array(imageData.data.buffer)` consumes. Browsers are universally little-endian; do not byte-swap.
+## Accuracy Tiers (v1.2)
+1. Fast
+2. Accurate-Clamp (default)
+3. Gamut-Mapped (MINDE)
 
-## Public API surface
-
-### Authoring (init-time, allocations OK)
-
-```js
-import {
-    parseCSSColor,
-    parseHexToBuffer,
-    parseRgbToBuffer,
-    parseHslToBuffer,
-    parseOklchToBuffer,
-    parseOklabToBuffer,
-} from '@zakkster/lite-color-engine';
-```
-
-All five format-specific parsers and `parseCSSColor` have the same signature:
-
-```ts
-(str: string, outBuf: Float32Array, offset: number) => number /* alpha [0,1] */
-```
-
-`parseCSSColor` dispatches by string prefix. Use it unless you know the format and care about shaving the dispatch.
-
-Throws on invalid input.
-
-### Convert (raw math)
-
-```js
-import { sRgbToOklchBuffer } from '@zakkster/lite-color-engine';
-
-sRgbToOklchBuffer(r, g, b, outBuf, outOffset);
-// r, g, b are 0-255 bytes. Writes 3 floats to outBuf.
-```
-
-### Runtime (zero allocations)
-
-```js
-import {
-    lerpOklchBuffer,
-    packOklchBufferToUint32,
-    packOklchBufferToUint32Fast,
-    sampleColorLUT,
-} from '@zakkster/lite-color-engine';
-```
-
-Signatures:
-
-```ts
-lerpOklchBuffer(
-    bufA: Float32Array, offsetA: number,
-    bufB: Float32Array, offsetB: number,
-    t: number,
-    outBuf: Float32Array, outOffset: number
-): void;
-
-packOklchBufferToUint32(buf: Float32Array, offset: number, alpha?: number): number;
-packOklchBufferToUint32Fast(buf: Float32Array, offset: number, alpha?: number): number;
-
-sampleColorLUT(lut: Uint32Array, t: number): number;
-```
-
-### LUT (gradient baking)
-
-```js
-import { bakeGradientToUint32 } from '@zakkster/lite-color-engine';
-
-bakeGradientToUint32(
-    keyframesBuf: Float32Array,         // [L0,C0,H0, L1,C1,H1, ...]
-    numStops: number,                   // >= 2
-    resolution?: number,                // default 256, >= 2
-    easeFn?: (t: number) => number,
-    packer?: (buf: Float32Array, offset: number, alpha?: number) => number
-): Uint32Array;
-```
-
-## Integration patterns
-
-### Pattern 1 — palette load
-
-```js
-const palette = new Float32Array(3 * COLOR_COUNT);
-const alphas  = new Float32Array(COLOR_COUNT);
-for (let i = 0; i < cssStrings.length; i++) {
-    alphas[i] = parseCSSColor(cssStrings[i], palette, i * 3);
-}
-// palette is now your color storage for the program lifetime.
-```
-
-### Pattern 2 — per-frame tween
-
-```js
-const scratch = new Float32Array(3);   // module-level, allocated ONCE
-
-function frame(t) {
-    lerpOklchBuffer(palette, 0, palette, 3, t, scratch, 0);
-    return packOklchBufferToUint32(scratch, 0, 1.0);
-}
-```
-
-### Pattern 3 — gradient LUT for a particle system
-
-```js
-const stops = new Float32Array(9);
-parseCSSColor('#ff0000', stops, 0);
-parseCSSColor('#ffd700', stops, 3);
-parseCSSColor('#00aaff', stops, 6);
-
-const lut = bakeGradientToUint32(stops, 3, 256);
-
-// In the render loop:
-for (let i = 0; i < particles.count; i++) {
-    const lifeT = particles.life[i];
-    pixels32[particles.pixelIdx[i]] = sampleColorLUT(lut, lifeT);
-}
-```
-
-### Pattern 4 — direct ImageData write
-
-```js
-const imgData = ctx.createImageData(width, height);
-const pixels  = new Uint32Array(imgData.data.buffer);  // RGBA-LE view
-
-for (let i = 0; i < pixels.length; i++) {
-    pixels[i] = sampleColorLUT(lut, i / pixels.length);
-}
-ctx.putImageData(imgData, 0, 0);
-```
-
-## Invariants the library guarantees
-
-- After any successful write, `outBuf[offset + 2]` (hue) is in `[0, 360)`.
-- After any successful write, `outBuf[offset]` (lightness) is in `[0, 1]`.
-- After any successful write, `outBuf[offset + 1]` (chroma) is in `[0, +∞)`.
-- `packOklchBufferToUint32` and `packOklchBufferToUint32Fast` return values that are **always** non-negative integers (they apply `>>> 0`).
-- Hue interpolation is **always** shortest-path (uses `lerpAngle` from `@zakkster/lite-lerp`).
-- Bake output bytes are **always** little-endian RGBA. Same on every browser.
-
-## Common pitfalls
-
-- **Mistaking the byte order.** The pack functions return little-endian RGBA, so on x86 the low byte is R. If you mask with `(packed >> 24) & 0xff` expecting red, you'll get alpha. Use `packed & 0xff` for red.
-
-- **Storing per-color objects anyway.** The library is explicitly buffer-first. If you find yourself writing `{ l, c, h }` wrappers, you've reintroduced GC pressure; just use the offset-based API.
-
-- **Choosing the Fast packer for UI.** `packOklchBufferToUint32Fast` darkens mid-tones by ~10/255 and shifts warm midtones toward black. Use it for transient pixels (particle trails, alpha-blended sprites). Use the accurate variant for anything a designer or QA might compare against the source color.
-
-- **Using non-monotonic eases with the LUT.** `bakeGradientToUint32` clamps eased `t` to `[0, 1]`. Overshoot easings (`easeOutBack`, etc.) get silently capped because a fixed-resolution LUT cannot represent overshoot. If you need overshoot, drive the eased `t` at sample time with `sampleColorLUT(lut, easeFn(t))` instead.
-
-- **Forgetting alpha is returned, not written.** Parsers return alpha. They do not write it to the buffer. If you mix parsers and hand-written buffers, decide on an alpha layout up front (sibling array, stride-4, or per-instance) and stick with it.
-
-## What this library is NOT
-
-- It is not a general-purpose color manipulation library. No `darken`, `lighten`, `mix`, `saturate`, `complement`, etc. methods. Compose your own from the buffer math primitives.
-- It is not a gamut mapper. Pack uses a hard clamp; out-of-gamut OKLCH values are clipped per-channel, not mapped via MINDE chroma reduction. Proper gamut mapping is on the v1.1 roadmap.
-- It is not a CSS parser for everything. It does CSS Color Level 4 colors. It does not handle `color()`, `color-mix()`, relative color syntax, or system colors.
-- It is not async. There are no Promises. Every function is synchronous and side-effect-free (writes only to its `outBuf` argument).
-
-## Performance budget
-
-| Operation | Wall-clock estimate (modern V8, 2024 laptop) |
-|---|---|
-| `parseCSSColor` | ~1µs per call (not the hot path; numbers vary by format) |
-| `lerpOklchBuffer` | ~50ns per call |
-| `packOklchBufferToUint32` | ~150ns per call |
-| `packOklchBufferToUint32Fast` | ~80ns per call |
-| `sampleColorLUT` | ~10ns per call |
-| `bakeGradientToUint32(..., 256)` | ~50µs total |
-
-Absolute numbers depend on hardware. Relative ratios are stable.
-
-## Versioning
-
-`1.0.x` — the locked public API surface above. No breaking changes within the major. Patch releases for bug fixes; minor releases may **add** functions but not remove or rename.
-
-`1.1` (planned) — see `ROADMAP.md` if present, or the Pairs-well-with section of the README.
+Use P3 variants when targeting `canvas.getContext('2d', { colorSpace: 'display-p3' })`.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-color-engine",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "description": "Zero-GC, data-oriented OKLCH color engine and WebGL/Canvas buffer pipeline.",
+  "description": "Zero-GC, data-oriented OKLCH color engine with MINDE gamut mapping and palette-remap kernels for WebGL/Canvas pipelines.",
   "type": "module",
   "sideEffects": false,
   "main": "./index.js",
@@ -10,10 +10,22 @@
   "types": "./index.d.ts",
   "exports": {
     ".": {
-      "node": "./index.js",
       "types": "./index.d.ts",
+      "node": "./index.js",
       "import": "./index.js",
       "default": "./index.js"
+    },
+    "./gamut": {
+      "types": "./src/Gamut.d.ts",
+      "node": "./src/Gamut.js",
+      "import": "./src/Gamut.js",
+      "default": "./src/Gamut.js"
+    },
+    "./remap": {
+      "types": "./src/Remap.d.ts",
+      "node": "./src/Remap.js",
+      "import": "./src/Remap.js",
+      "default": "./src/Remap.js"
     }
   },
   "files": [
@@ -21,13 +33,18 @@
     "index.js",
     "index.d.ts",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
-    "LICENSE.txt"
+    "LICENSE.md"
   ],
   "keywords": [
     "color",
     "oklch",
     "oklab",
+    "gamut-mapping",
+    "minde",
+    "palette",
+    "remap",
     "zero-gc",
     "webgl",
     "canvas",
@@ -35,6 +52,7 @@
     "interpolation",
     "gradient",
     "color-space",
+    "delta-e",
     "dod",
     "data-oriented",
     "high-performance",
@@ -66,4 +84,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/src/Gamut.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @zakkster/lite-color-engine/gamut
+ *
+ * CSS Color 4 MINDE chroma-reduction gamut mapping, plus an accurate packer.
+ * Sub-export so the bisection loop does not bloat the core bundle.
+ */
+
+/**
+ * CSS Color 4 MINDE chroma reduction. Reduces chroma at fixed L and H until
+ * the color is inside the sRGB gamut, using bisection with a JND threshold.
+ * Zero allocations on the hot path. Source and destination may alias.
+ *
+ * Writes `[L, C', H]` at `outBuf[outOffset..outOffset+2]`.
+ */
+export function gamutMapToSrgbBuffer(
+    inBuf: Float32Array,
+    inOffset: number,
+    outBuf: Float32Array,
+    outOffset: number
+): void;
+
+/**
+ * Accurate sibling of `packOklchBufferToUint32`. Runs MINDE gamut mapping
+ * before packing, eliminating the hue-shift artifacts of the hard channel
+ * clamp near the sRGB gamut boundary.
+ *
+ * ~30x slower than the core packer — use at LUT build time or authoring
+ * time, not per-frame. Returns an unsigned RGBA-LE Uint32.
+ *
+ * Signature-compatible with `bakeGradientToUint32`'s `packer` argument, so
+ * you can bake gamut-accurate LUTs by passing this as the packer.
+ */
+export function packOklchBufferToUint32MINDE(
+    buf: Float32Array,
+    offset: number,
+    alpha?: number
+): number;

package/src/Gamut.js

@@ -0,0 +1,228 @@
+// -----------------------------------------------------------------------------
+// @zakkster/lite-color-engine/gamut
+//
+// CSS Color 4 MINDE gamut mapping (chroma reduction in OKLab).
+//
+// Reference: https://www.w3.org/TR/css-color-4/#binsearch-gamut-mapping
+// V1.1-PLAN P0/#1.
+//
+// Self-contained module: local internal converters, no cross-file imports.
+// This costs ~40 lines of duplicated math but keeps the sub-export loadable
+// in isolation and independent of any future refactor of src/converters.js.
+// Fits the ecosystem's "duplicate small math, share only what earns it" rule.
+//
+// Trust model matches v1.0: buffers assumed well-shaped; L, C, H bounds
+// enforced at write time (canonical hue in [0, 360), L clamped to [0, 1]).
+// -----------------------------------------------------------------------------
+
+const _RAD = Math.PI / 180;
+const _DEG = 180 / Math.PI;
+
+// Module-level scratch. Never allocated during a call.
+const _rgb = new Float32Array(3);
+const _clipLch = new Float32Array(3);
+
+// CSS Color 4 constants.
+const JND = 0.02;
+const EPSILON = 0.0001;
+const MAX_ITER = 8;
+
+// OKLCH → linear sRGB, writes 3 floats to `out`.
+function _oklchToLinearRgb(L, C, H, out) {
+    const hRad = H * _RAD;
+    const a = C * Math.cos(hRad);
+    const b = C * Math.sin(hRad);
+    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 l = l_ * l_ * l_;
+    const m = m_ * m_ * m_;
+    const s = s_ * s_ * s_;
+    out[0] =  4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    out[1] = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    out[2] = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+}
+
+// Linear sRGB → OKLCH, writes 3 floats [L, C, H] with H in [0, 360).
+function _linearRgbToOklch(r, g, b, out, off) {
+    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.7936177850 * m_ - 0.0040720468 * s_;
+    const A = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    const B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+    const C = Math.sqrt(A * A + B * B);
+    let H = Math.atan2(B, A) * _DEG;
+    if (H < 0) H += 360;
+    out[off]     = L;
+    out[off + 1] = C;
+    out[off + 2] = H;
+}
+
+// sRGB gamma encode a linear channel to gamma-encoded [0, 1].
+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;
+}
+
+// Pre-declared bindings for tight ΔE-OK loops.
+function _deltaOKFromLchLinearRgb(L, C, H, cR, cG, cB) {
+    // Original OKLab (a, b) from OKLCH
+    const hRad = H * _RAD;
+    const oA = C * Math.cos(hRad);
+    const oB = C * Math.sin(hRad);
+    // Clipped in-gamut linear RGB → OKLab
+    const l = 0.4122214708 * cR + 0.5363325363 * cG + 0.0514459929 * cB;
+    const m = 0.2119034982 * cR + 0.6806995451 * cG + 0.1073969566 * cB;
+    const s = 0.0883024619 * cR + 0.2817188376 * cG + 0.6299787005 * cB;
+    const l_ = Math.cbrt(l);
+    const m_ = Math.cbrt(m);
+    const s_ = Math.cbrt(s);
+    const cL = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+    const cA = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    const cBB = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+    const dL = L - cL;
+    const dA = oA - cA;
+    const dB = oB - cBB;
+    return Math.sqrt(dL * dL + dA * dA + dB * dB);
+}
+
+
+// -----------------------------------------------------------------------------
+// gamutMapToSrgbBuffer
+// -----------------------------------------------------------------------------
+
+/**
+ * CSS Color 4 chroma-reduction gamut mapping. Reduces chroma at fixed L and H
+ * until the color is inside the sRGB gamut, using bisection with a JND
+ * threshold. Zero allocations on the hot path.
+ *
+ * Writes gamut-mapped [L, C', H] at `outBuf[outOffset..outOffset+2]`.
+ * Source and destination may alias.
+ *
+ * @param {Float32Array} inBuf
+ * @param {number} inOffset
+ * @param {Float32Array} outBuf
+ * @param {number} outOffset
+ */
+export function gamutMapToSrgbBuffer(inBuf, inOffset, outBuf, outOffset) {
+    const L = inBuf[inOffset];
+    const C = inBuf[inOffset + 1];
+    const H = inBuf[inOffset + 2];
+
+    // Endpoints: L outside [0, 1] collapses to black or white in destination.
+    if (L >= 1) {
+        outBuf[outOffset] = 1;
+        outBuf[outOffset + 1] = 0;
+        outBuf[outOffset + 2] = H;
+        return;
+    }
+    if (L <= 0) {
+        outBuf[outOffset] = 0;
+        outBuf[outOffset + 1] = 0;
+        outBuf[outOffset + 2] = H;
+        return;
+    }
+    if (C <= 0) {
+        outBuf[outOffset] = L;
+        outBuf[outOffset + 1] = 0;
+        outBuf[outOffset + 2] = H;
+        return;
+    }
+
+    // In-gamut? Emit unchanged.
+    _oklchToLinearRgb(L, C, H, _rgb);
+    if (
+        _rgb[0] >= -EPSILON && _rgb[0] <= 1 + EPSILON &&
+        _rgb[1] >= -EPSILON && _rgb[1] <= 1 + EPSILON &&
+        _rgb[2] >= -EPSILON && _rgb[2] <= 1 + EPSILON
+    ) {
+        outBuf[outOffset]     = L;
+        outBuf[outOffset + 1] = C;
+        outBuf[outOffset + 2] = H;
+        return;
+    }
+
+    // Full-chroma clip. If ΔE < JND, we're done — return the OKLCH of the clip.
+    let cR = _rgb[0] < 0 ? 0 : _rgb[0] > 1 ? 1 : _rgb[0];
+    let cG = _rgb[1] < 0 ? 0 : _rgb[1] > 1 ? 1 : _rgb[1];
+    let cB = _rgb[2] < 0 ? 0 : _rgb[2] > 1 ? 1 : _rgb[2];
+    if (_deltaOKFromLchLinearRgb(L, C, H, cR, cG, cB) < JND) {
+        _linearRgbToOklch(cR, cG, cB, outBuf, outOffset);
+        return;
+    }
+
+    // Bisection on chroma at fixed L, H.
+    let low = 0;
+    let high = C;
+    for (let iter = 0; iter < MAX_ITER; iter++) {
+        if (high - low < EPSILON) break;
+        const mid = (low + high) * 0.5;
+        _oklchToLinearRgb(L, mid, H, _rgb);
+        const inGamut = (
+            _rgb[0] >= -EPSILON && _rgb[0] <= 1 + EPSILON &&
+            _rgb[1] >= -EPSILON && _rgb[1] <= 1 + EPSILON &&
+            _rgb[2] >= -EPSILON && _rgb[2] <= 1 + EPSILON
+        );
+        if (inGamut) {
+            low = mid;
+        } else {
+            cR = _rgb[0] < 0 ? 0 : _rgb[0] > 1 ? 1 : _rgb[0];
+            cG = _rgb[1] < 0 ? 0 : _rgb[1] > 1 ? 1 : _rgb[1];
+            cB = _rgb[2] < 0 ? 0 : _rgb[2] > 1 ? 1 : _rgb[2];
+            if (_deltaOKFromLchLinearRgb(L, mid, H, cR, cG, cB) < JND) {
+                _linearRgbToOklch(cR, cG, cB, outBuf, outOffset);
+                return;
+            }
+            high = mid;
+        }
+    }
+
+    // Converged: `low` is the largest in-gamut chroma at this (L, H).
+    outBuf[outOffset]     = L;
+    outBuf[outOffset + 1] = low;
+    outBuf[outOffset + 2] = H;
+}
+
+
+// -----------------------------------------------------------------------------
+// packOklchBufferToUint32MINDE
+// -----------------------------------------------------------------------------
+
+/**
+ * Drop-in accurate sibling of `packOklchBufferToUint32`. Runs MINDE gamut
+ * mapping before packing, eliminating the visible hue shifts that the
+ * hard channel-clamp produces near the sRGB gamut boundary.
+ *
+ * ~30x slower than the core packer — belongs at LUT build time or authoring
+ * time, not in per-frame interpolation. Zero allocations.
+ *
+ * @param {Float32Array} buf
+ * @param {number} offset
+ * @param {number} [alpha=1] alpha in [0, 1]; packed into the high byte
+ * @returns {number} RGBA-LE Uint32
+ */
+export function packOklchBufferToUint32MINDE(buf, offset, alpha) {
+    gamutMapToSrgbBuffer(buf, offset, _clipLch, 0);
+    const L = _clipLch[0];
+    const C = _clipLch[1];
+    const H = _clipLch[2];
+    _oklchToLinearRgb(L, C, H, _rgb);
+    // Guard-clamp: post-MINDE the values should be in [0, 1] modulo epsilon,
+    // but the raw matrix output can still be a hair outside due to rounding.
+    let r = _srgbGammaEncode(_rgb[0]);
+    let g = _srgbGammaEncode(_rgb[1]);
+    let b = _srgbGammaEncode(_rgb[2]);
+    const R = (r * 255 + 0.5) | 0;
+    const G = (g * 255 + 0.5) | 0;
+    const B = (b * 255 + 0.5) | 0;
+    const a = alpha == null ? 1 : (alpha < 0 ? 0 : alpha > 1 ? 1 : alpha);
+    const A = (a * 255 + 0.5) | 0;
+    // RGBA-LE: byte order R, G, B, A. `>>> 0` normalizes to unsigned uint32
+    // so the value is comparable and matches v1.0 packer conventions.
+    return (((A & 0xFF) << 24) | ((B & 0xFF) << 16) | ((G & 0xFF) << 8) | (R & 0xFF)) >>> 0;
+}

package/src/Remap.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @zakkster/lite-color-engine/remap
+ *
+ * SoA remap kernels: nearest-palette-index search in OKLab, plus a one-shot
+ * pixel-remap function for image recoloring. The engine layer that
+ * `lite-hueforge v1.3 remapImageToPalette` sits on top of.
+ *
+ * Search happens in OKLab (Euclidean distance). Palette is authored in OKLCH
+ * and converted to OKLab once at call entry.
+ */
+
+/**
+ * Batch RGBA8 → OKLab. Reads 4 bytes per pixel, writes 3 floats per pixel.
+ * Alpha is discarded; carry it separately if needed.
+ */
+export function sRgba8ToOklabBuffer(
+    inU8: Uint8Array | Uint8ClampedArray,
+    outLab: Float32Array,
+    pixelCount: number
+): void;
+
+/** Batch OKLCH → OKLab. Both buffers stride 3. */
+export function oklchToOklabBuffer(
+    inLch: Float32Array,
+    outLab: Float32Array,
+    pixelCount: number
+): void;
+
+/** Batch OKLab → OKLCH. Hue canonicalized to `[0, 360)`. Both buffers stride 3. */
+export function oklabToOklchBuffer(
+    inLab: Float32Array,
+    outLch: Float32Array,
+    pixelCount: number
+): void;
+
+export interface NearestPaletteOptions {
+    /**
+     * If true, distance uses (a, b) only — matches by chroma coords and
+     * ignores lightness. Enables the shading-preserve remap trick.
+     * Default: false.
+     */
+    preserveLightness?: boolean;
+}
+
+/**
+ * For each pixel in `pixelsLab`, write the index of the nearest palette
+ * color in `paletteLab` (squared Euclidean distance in OKLab) into
+ * `indicesOut`. Tie-break: lowest index wins. Deterministic.
+ */
+export function nearestPaletteIndexBuffer(
+    pixelsLab: Float32Array,
+    paletteLab: Float32Array,
+    indicesOut: Uint32Array | Uint16Array | Uint8Array,
+    pixelCount: number,
+    paletteCount: number,
+    opts?: NearestPaletteOptions
+): void;
+
+export interface RemapPixelsOptions {
+    /**
+     * If true, search by (a, b) only and synthesize output per pixel using
+     * the pixel's original L and the palette color's (a, b). Preserves
+     * shading structure under recolor — the AI-motif recolor look.
+     * ~40% slower than the fast path. Default: false.
+     */
+    preserveLightness?: boolean;
+}
+
+/**
+ * One-shot end-to-end: read RGBA8 pixels, find nearest palette color per
+ * pixel by ΔE-OK in OKLab, write RGBA-LE Uint32 result. Handles palette
+ * OKLCH→OKLab conversion internally. Alpha byte passes through unchanged.
+ *
+ * Fast path (`preserveLightness=false`): pre-packs palette to Uint32 once,
+ * per-pixel is convert-search-gather.
+ *
+ * Preserve path (`preserveLightness=true`): synthesizes each output pixel
+ * from `(pixel.L, palette.a, palette.b)` — shading is retained.
+ */
+export function remapPixelsToPalette(
+    inU8: Uint8Array | Uint8ClampedArray,
+    paletteLch: Float32Array,
+    outU32: Uint32Array,
+    pixelCount: number,
+    paletteCount: number,
+    opts?: RemapPixelsOptions
+): void;