@zakkster/lite-color-engine 1.1.0 → 1.3.0

package/index.d.ts

@@ -9,11 +9,11 @@
  *  - H (Hue):       [0, 360) degrees
  *
  * Pack output is a 32-bit unsigned integer in **little-endian RGBA** byte
- * order — drop straight into `new Uint32Array(imageData.data.buffer)`.
+ * order - drop straight into `new Uint32Array(imageData.data.buffer)`.
  */
 
 // ============================================================================
-// Authoring (CSS Parsing → OKLCH Buffer)
+// Authoring (CSS Parsing -> OKLCH Buffer)
 // ============================================================================
 
 /**
@@ -33,7 +33,7 @@ export function parseHexToBuffer(str: string, outBuf: Float32Array, offset: numb
 export function parseOklchToBuffer(str: string, outBuf: Float32Array, offset: number): number;
 
 /**
- * Parses a CSS `oklab(...)` string and converts (a, b) → polar (C, H) before
+ * Parses a CSS `oklab(...)` string and converts (a, b) -> polar (C, H) before
  * writing the OKLCH triplet.
  * @returns Parsed alpha in `[0, 1]`; defaults to `1.0` when omitted.
  * @throws If the string is not a valid `oklab(...)` literal.
@@ -61,17 +61,32 @@ export function parseHslToBuffer(str: string, outBuf: Float32Array, offset: numb
  * format-specific parser.
  *
  * Supports: 148 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. After
  * compilation, work with the resulting `Float32Array` buffers directly via
  * {@link lerpOklchBuffer} and {@link packOklchBufferToUint32}.
  *
+ * `color(display-p3 ...)` is opt-in wide-gamut input; it never affects the
+ * default sRGB hot path.
+ *
  * @returns Parsed alpha in `[0, 1]`.
  * @throws If the string is not a recognized format.
  */
 export function parseCSSColor(str: string, outBuf: Float32Array, offset: number): number;
 
+/**
+ * Parses a CSS `color(display-p3 r g b / alpha?)` string into the OKLCH triplet
+ * at `outBuf[offset..offset+2]`. Components accept `0-1` numbers or `%`.
+ *
+ * Wide-gamut authoring entry point: the resulting OKLCH may carry higher chroma
+ * than any sRGB-gamut color.
+ *
+ * @returns Parsed alpha in `[0, 1]`; defaults to `1.0` when omitted.
+ * @throws If the string is not a valid `color(display-p3 ...)` literal.
+ */
+export function parseDisplayP3ToBuffer(str: string, outBuf: Float32Array, offset: number): number;
+
 // ============================================================================
 // Convert (Raw Math)
 // ============================================================================
@@ -80,7 +95,7 @@ export function parseCSSColor(str: string, outBuf: Float32Array, offset: number)
  * Converts standard sRGB (0-255 byte channels) into a flat OKLCH buffer at
  * `outBuf[outOffset..outOffset+2]`.
  *
- * Implements Björn Ottosson's OKLab (2020) algorithm with defenses against
+ * Implements Bjorn Ottosson's OKLab (2020) algorithm with defenses against
  * NaN-propagating negative cube-root inputs and a strict lightness clamp.
  */
 export function sRgbToOklchBuffer(
@@ -91,6 +106,30 @@ export function sRgbToOklchBuffer(
     outOffset: number
 ): void;
 
+/**
+ * Converts Display P3 (0-255 byte channels) into a flat OKLCH buffer, using the
+ * P3 primaries via a P3 -> XYZ -> LMS -> OKLab pipeline. Lets colors outside the
+ * sRGB gamut be represented with their true (higher) chroma.
+ *
+ * Same OKLab defenses and lightness clamp as {@link sRgbToOklchBuffer}.
+ */
+export function displayP3ToOklchBuffer(
+    r: number,
+    g: number,
+    b: number,
+    outBuf: Float32Array,
+    outOffset: number
+): void;
+
+/**
+ * Inverse of {@link displayP3ToOklchBuffer}: converts an OKLCH triplet to
+ * **linear-light** Display P3 and writes `[r, g, b]` into `out` (length >= 3).
+ *
+ * Output channels may fall outside `[0, 1]` for colors beyond the P3 gamut;
+ * clamp or gamut-map before encoding. Used by the P3 packers.
+ */
+export function oklchToLinearP3(L: number, C: number, H: number, out: Float32Array): void;
+
 // ============================================================================
 // Runtime (Zero-GC Hot Path)
 // ============================================================================
@@ -100,7 +139,7 @@ export function sRgbToOklchBuffer(
  *
  * Hue uses **shortest-path** interpolation (`lerpAngle`) so gradients never
  * wrap the long way around the wheel. Lightness is hard-clamped to `[0, 1]`
- * and chroma to `[0, +∞)`. Hue is canonicalized to `[0, 360)`.
+ * and chroma to `[0, +inf)`. Hue is canonicalized to `[0, 360)`.
  *
  * Source and destination buffers may alias (same buffer, different offsets).
  *
@@ -116,13 +155,29 @@ 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
+ * RGBA** byte order - the format consumed directly by `Canvas ImageData` via
  * a `Uint32Array` view.
  *
  * Uses the proper sRGB transfer function (`pow(c, 1/2.4)` branch).
- * Round-tripping `sRGB → OKLCH → here` recovers the original byte exactly
+ * Round-tripping `sRGB -> OKLCH -> here` recovers the original byte exactly
  * (within rounding).
  *
  * For a faster `Math.sqrt`-approximated sibling (~2x throughput, ~10/255
@@ -157,6 +212,53 @@ 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
+ * (`getContext('2d', { colorSpace: 'display-p3' })`).
+ *
+ * Colors that are out of sRGB but inside P3 are preserved at their true
+ * saturation instead of being clamped down. Transfer function is identical to
+ * sRGB (IEC 61966-2-1).
+ *
+ * @param alpha Alpha in `[0, 1]`. Default `1.0`.
+ * @returns 32-bit unsigned integer in little-endian RGBA byte order.
+ */
+export function packOklchBufferToUint32P3(
+    buf: Float32Array,
+    offset: number,
+    alpha?: number
+): number;
+
+/**
+ * Faster, less accurate variant of {@link packOklchBufferToUint32P3}: uses a
+ * `Math.sqrt` transfer approximation (same trade-off as
+ * {@link packOklchBufferToUint32Fast}). For high-volume P3 particle/gradient
+ * baking where exact round-trip is not required.
+ *
+ * @param alpha Alpha in `[0, 1]`. Default `1.0`.
+ * @returns 32-bit unsigned integer in little-endian RGBA byte order.
+ */
+export function packOklchBufferToUint32P3Fast(
+    buf: Float32Array,
+    offset: number,
+    alpha?: number
+): number;
+
 /**
  * Zero-GC sampler for a baked LUT. Inline `t`-clamp + bitwise-truncated index.
  *
@@ -176,7 +278,7 @@ export type OklchPackerFn = (buf: Float32Array, offset: number, alpha?: number)
 /**
  * Bakes a multi-stop OKLCH gradient into a ready-to-render `Uint32Array`.
  *
- * Output bytes are little-endian RGBA — drop into a `Uint32Array` view of
+ * Output bytes are little-endian RGBA - drop into a `Uint32Array` view of
  * `Canvas ImageData`, or upload as `RGBA / UNSIGNED_BYTE` via `texImage2D`.
  *
  * Stops are evenly distributed: stop _i_ is at `i / (numStops - 1)`. The
@@ -202,11 +304,11 @@ export function bakeGradientToUint32(
 ): Uint32Array;
 
 // ============================================================================
-// Difference (ΔE-OK)
+// Difference (deltaE-OK)
 // ============================================================================
 
 /**
- * ΔE-OK color difference: Euclidean distance in OKLab between two buffered
+ * deltaE-OK color difference: Euclidean distance in OKLab between two buffered
  * OKLCH colors. Zero-allocation.
  *
  * Typical scale: `0.02` indistinguishable, `0.05` subtle, `0.15+` unambiguous.

package/index.js

@@ -4,18 +4,27 @@ export {
     parseHslToBuffer,
     parseOklabToBuffer,
     parseOklchToBuffer,
-    parseRgbToBuffer
+    parseRgbToBuffer,
+    parseDisplayP3ToBuffer
 } from './src/authoring.js';
 
 export { bakeGradientToUint32 } from './src/lut.js';
 
 export {
     lerpOklchBuffer,
+    lerpOklchBufferN,
     packOklchBufferToUint32,
     packOklchBufferToUint32Fast,
+    packOklchBufferToUint32IntoN,
+    packOklchBufferToUint32P3,
+    packOklchBufferToUint32P3Fast,
     sampleColorLUT
 } from './src/runtime.js';
 
-export { sRgbToOklchBuffer } from './src/convert.js';
+export {
+    sRgbToOklchBuffer,
+    displayP3ToOklchBuffer,
+    oklchToLinearP3
+} from './src/convert.js';
 
 export { deltaEOK } from './src/delta.js';

package/llms.txt

@@ -1,275 +1,44 @@
-# @zakkster/lite-color-engine — LLM Reference
-
-> 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).
-
-## Identity
-
-- **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`
-
-## Mental model
-
-Every color in this library is exactly **3 contiguous Float32 entries** in a `Float32Array`: `[L, C, H]`.
-
-- `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.
-
-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).
-
-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.
-
-## 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;
-```
-
-### Difference (ΔE-OK)
-
-```js
-import { deltaEOK } from '@zakkster/lite-color-engine';
-
-deltaEOK(bufA: Float32Array, offsetA: number,
-         bufB: Float32Array, offsetB: number): number;
-```
-
-Euclidean distance in OKLab between two buffered OKLCH colors. Zero allocations. Typical scale: `0.02` indistinguishable, `0.05` subtle, `0.15+` unambiguously different.
-
-### Gamut sub-export (`/gamut`)
-
-```js
-import {
-    gamutMapToSrgbBuffer,
-    packOklchBufferToUint32MINDE,
-} from '@zakkster/lite-color-engine/gamut';
-
-gamutMapToSrgbBuffer(
-    inBuf: Float32Array, inOffset: number,
-    outBuf: Float32Array, outOffset: number
-): void;
-
-packOklchBufferToUint32MINDE(
-    buf: Float32Array, offset: number, alpha?: number
-): number;
-```
-
-CSS Color 4 MINDE chroma-reduction gamut mapping. Bisection on chroma at fixed L and H with a JND threshold. `packOklchBufferToUint32MINDE` is signature-compatible with the core packer, so you can pass it directly as the `packer` argument to `bakeGradientToUint32` to bake gamut-accurate LUTs.
-
-~30× slower than the core packer. Belongs at LUT-build or authoring time, not per-frame.
-
-### Remap sub-export (`/remap`)
-
-```js
-import {
-    sRgba8ToOklabBuffer,
-    oklchToOklabBuffer,
-    oklabToOklchBuffer,
-    nearestPaletteIndexBuffer,
-    remapPixelsToPalette,
-} from '@zakkster/lite-color-engine/remap';
-
-sRgba8ToOklabBuffer(
-    inU8: Uint8Array | Uint8ClampedArray,
-    outLab: Float32Array, pixelCount: number
-): void;
-
-oklchToOklabBuffer(inLch: Float32Array, outLab: Float32Array, pixelCount: number): void;
-oklabToOklchBuffer(inLab: Float32Array, outLch: Float32Array, pixelCount: number): void;
-
-nearestPaletteIndexBuffer(
-    pixelsLab: Float32Array, paletteLab: Float32Array,
-    indicesOut: Uint32Array | Uint16Array | Uint8Array,
-    pixelCount: number, paletteCount: number,
-    opts?: { preserveLightness?: boolean }
-): void;
-
-remapPixelsToPalette(
-    inU8: Uint8Array | Uint8ClampedArray,
-    paletteLch: Float32Array,
-    outU32: Uint32Array,
-    pixelCount: number, paletteCount: number,
-    opts?: { preserveLightness?: boolean }
-): void;
-```
-
-SoA palette-remap kernels. Search happens in OKLab (Euclidean distance). Palette is authored in OKLCH and converted to OKLab once per call. `remapPixelsToPalette` uses grow-only module-level scratch for the palette conversion — no per-frame allocation. Alpha byte from the input passes through unchanged in the output. `preserveLightness` searches by `(a, b)` only and synthesizes output as `(pixel.L, palette.a, palette.b)` — retains shading structure under recolor.
-
-### 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.
-- The core `packOklchBufferToUint32` uses a hard channel clamp for its runtime fast path. Accurate CSS Color 4 MINDE chroma-reduction gamut mapping ships in the `/gamut` sub-export (see below) — use that at LUT-build or authoring time when the hue-shift artifacts of the hard clamp matter.
-- 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 core public API surface. No breaking changes within the major. Patch releases for bug fixes; minor releases may **add** functions but not remove or rename.
-
-`1.1.0` — adds `deltaEOK` in core, plus two additive sub-exports:
-- `@zakkster/lite-color-engine/gamut` — CSS Color 4 MINDE gamut mapping and an accurate packer.
-- `@zakkster/lite-color-engine/remap` — SoA batch converters and palette-remap kernels.
-
-No breaking changes; the v1.0 surface is untouched. See `CHANGELOG.md` for full details.
+# lite-color-engine - LLM Reference (v1.3)
+
+## Core Exports
+
+### Parsing
+- `parseCSSColor(str, outBuf, offset)` — Universal parser. Now supports `color(display-p3 r g b / alpha)`
+- `parseDisplayP3ToBuffer(str, outBuf, offset)` — Direct P3 parser
+
+### 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
+
+### 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
+- `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.
+
+### LUT
+- `bakeGradientToUint32(..., packer?)` — Accepts any of the above packers
+
+## 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
+
+## Accuracy Tiers (v1.2)
+1. Fast
+2. Accurate-Clamp (default)
+3. Gamut-Mapped (MINDE)
+
+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.1.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"