@zakkster/lite-color-engine 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,21 +1,74 @@
 # Changelog
 
+## [1.4.0] - 2026-07-10
+
+### Added
+- **CSS formatters (round-trip emit):**
+  - `formatOklchCss(buf, off, alpha?)` - emits `oklch(L% C H)` (or `.../ alpha` when
+    alpha is supplied and < 1). Round-trips through `parseCSSColor`.
+  - `formatHex(buf, off)` - emits `#rrggbb` via the accurate sRGB pack path.
+    Round-trips with `parseHexToBuffer` to within 1 LSB per channel.
+  - Both are authoring-time helpers (they allocate a string) and are not for
+    per-frame hot paths.
+
+### Fixed
+- Named-color table: `darkslateggrey` -> `darkslategrey` and `navajawhite` ->
+  `navajowhite` (previously unreachable typo keys), and `lightsteelblue` now
+  returns its correct value `#b0c4de` instead of powderblue's `#b0e0e6`.
+
+### Notes
+- No breaking changes; all v1.3 exports (batch kernels, 4k LUT, Display P3,
+  `sampleColorLUT`) are retained.
+
+---
+
+## [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 +81,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,64 +1,486 @@
 # @zakkster/lite-color-engine
 
-**Zero-GC, data-oriented OKLCH color engine** for high-performance WebGL / Canvas pipelines.
+> Zero-GC OKLCH color engine for hot paths. Parse once into `Float32Array` buffers, then interpolate, gamut-map, and pack straight into `ImageData` with no per-frame allocation. Built for 16ms render budgets, 100k-particle canvases, and 1MB extension bundles.
 
-## v1.2 Highlights — Wide Gamut + Accuracy Tiers
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-color-engine.svg?style=for-the-badge&color=00C853)](https://www.npmjs.com/package/@zakkster/lite-color-engine)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Hot%20Path-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![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)
+![ESM only](https://img.shields.io/badge/ESM-only-blue)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE.md)
 
-- Full `color(display-p3 r g b / alpha)` parsing support
-- Dedicated high-accuracy `packOklchBufferToUint32P3()` and fast variant
-- Three clear accuracy tiers for sRGB output:
-  1. **Fast** — `packOklchBufferToUint32Fast`
-  2. **Accurate-Clamp** — default `packOklchBufferToUint32`
-  3. **Gamut-Mapped** — `packOklchBufferToUint32MINDE`
+A color library built the way a game engine is built: **no allocation on the hot path.** Colors live in flat `Float32Array` OKLCH buffers. Interpolation, gamut mapping, and packing read and write those buffers in place and emit `Uint32Array` pixels that drop directly into a canvas `ImageData`. The result is perceptually-uniform OKLCH color at the throughput of raw integer math -- **~14 million colors/second** through the LUT packer, enough to recolor a **100,000-particle** field every frame at 60fps.
 
-P3 output is **opt-in only** — never affects default paths or bundle size.
+It is not a wrapper around `culori` or `color.js`. There are no objects, no strings, and no garbage per frame. The one thing it depends on is [`@zakkster/lite-lerp`](https://www.npmjs.com/package/@zakkster/lite-lerp).
 
-## Core Philosophy
+```bash
+npm install @zakkster/lite-color-engine
+```
+
+```js
+import {
+  parseCSSColor,
+  lerpOklchBuffer,
+  packOklchBufferToUint32
+} from "@zakkster/lite-color-engine";
+
+const a = new Float32Array(3);
+const b = new Float32Array(3);
+const t = new Float32Array(3);           // scratch, allocated once
+
+parseCSSColor("oklch(0.72 0.15 30)", a, 0);   // warm
+parseCSSColor("oklch(0.66 0.18 265)", b, 0);  // cool
+
+// Per frame, zero allocations:
+lerpOklchBuffer(a, 0, b, 0, 0.5, t, 0);       // perceptual midpoint (shortest-hue)
+const pixel = packOklchBufferToUint32(t, 0);  // 0xAABBGGRR for a Uint32Array/ImageData
+```
+
+Perceptually-uniform blends, correct sRGB output, no heap traffic. That is the whole pitch.
+
+---
+
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [What you get](#what-you-get)
+- [The buffer model](#the-buffer-model)
+- [The pipeline in one diagram](#the-pipeline-in-one-diagram)
+- [Accuracy tiers](#accuracy-tiers)
+- [Batch kernels and the 100k particle case](#batch-kernels-and-the-100k-particle-case)
+- [Benchmarks](#benchmarks)
+- [API reference](#api-reference)
+- [Wide gamut (Display P3)](#wide-gamut-display-p3)
+- [Gamut mapping (`/gamut`)](#gamut-mapping-gamut)
+- [Palette remap (`/remap`)](#palette-remap-remap)
+- [Formatters](#formatters)
+- [Allocation profile](#allocation-profile)
+- [Tree-shaking and subpaths](#tree-shaking-and-subpaths)
+- [Testing](#testing)
+- [Integration recipes](#integration-recipes)
+- [Browser and runtime support](#browser-and-runtime-support)
+- [What this is not](#what-this-is-not)
+- [FAQ](#faq)
+
+---
+
+## Why this exists
+
+Color work in animation loops has a hidden cost: most libraries allocate. A `culori` blend returns a fresh object; a `color.js` conversion builds intermediate arrays; `hsl()` string interpolation allocates strings. One color is nothing. Sixty thousand colors, sixty times a second, is a GC storm that shows up as jank on exactly the frames you care about.
+
+`lite-color-engine` was written under three constraints at once:
+
+1. **No allocation after warm-up.** Parsing and LUT baking allocate; the per-frame path -- lerp, pack, sample -- touches no heap. All scratch is caller-owned `Float32Array`.
+2. **Perceptually uniform by default.** Interpolation happens in OKLCH, so a red-to-blue gradient doesn't muddy through gray and lightness stays even. Hue takes the shortest path around the wheel.
+3. **Output that's actually correct.** The default packer uses the true IEC 61966-2-1 sRGB transfer, so `#rrggbb -> OKLCH -> pack` round-trips to within 1 LSB. Faster, looser tiers are opt-in, never the default.
+
+OKLCH is the right space for interpolation. Flat typed arrays are the right representation for throughput. This library is the intersection.
+
+---
+
+## What you get
+
+**Parse (authoring-time)**
+- `parseCSSColor(str, out, off)` -- universal: hex, `rgb()/rgba()`, `hsl()/hsla()`, `oklch()`, `oklab()`, `color(display-p3 ...)`, and 140+ named colors.
+- `parseHexToBuffer`, `parseRgbToBuffer`, `parseHslToBuffer`, `parseOklchToBuffer`, `parseOklabToBuffer`, `parseDisplayP3ToBuffer` -- direct parsers when you already know the format.
+
+**Interpolate (hot path)**
+- `lerpOklchBuffer(a, offA, b, offB, t, out, off)` -- one perceptual blend, shortest-path hue.
+- `lerpOklchBufferN(a, offA, b, offB, t, out, off, n)` -- bulk blend of `n` triplets, one call.
+
+**Pack to pixels (hot path)**
+- `packOklchBufferToUint32(buf, off, alpha?)` -- accurate sRGB, round-trip exact.
+- `packOklchBufferToUint32Fast(buf, off, alpha?)` -- `sqrt` approximation, ~2x, ~10/255 drift.
+- `packOklchBufferToUint32IntoN(src, offSrc, dst, offDst, n, alpha?, useLut?)` -- bulk pack `n` colors into a `Uint32Array`; `useLut` swaps in a 4k transfer LUT (~4x, within 1 LSB).
+- `packOklchBufferToUint32P3` / `...P3Fast` -- Display P3 output.
+
+**Bake and sample (hot path)**
+- `bakeGradientToUint32(keyframes, numStops, resolution?, easeFn?, packer?)` -- pre-render a gradient into a `Uint32Array` LUT once.
+- `sampleColorLUT(lut, t)` -- branch-light O(1) lookup, no allocation.
+
+**Format (authoring-time)**
+- `formatOklchCss(buf, off, alpha?)` -- back to `oklch(60.0% 0.150 250.0)`.
+- `formatHex(buf, off)` -- back to `#rrggbb`.
+
+**Measure**
+- `deltaEOK(a, offA, b, offB)` -- perceptual color difference (Euclidean in OKLab).
+
+**Subpaths (opt-in, tree-shaken separately)**
+- `@zakkster/lite-color-engine/gamut` -- MINDE gamut mapping.
+- `@zakkster/lite-color-engine/remap` -- palette quantization for whole pixel buffers.
+
+Full types ship in [`index.d.ts`](./index.d.ts); every public symbol has JSDoc.
+
+---
+
+## The buffer model
+
+A color is three `Float32` lanes -- **L, C, H** -- somewhere in a `Float32Array` you own. That's it. There is no `Color` class.
+
+```js
+// Store 1,000 colors in one flat buffer (Structure-of-Arrays friendly).
+const colors = new Float32Array(1000 * 3);
+parseCSSColor("crimson", colors, 42 * 3);   // write color #42 at offset 126
+```
+
+Every function takes `(buffer, offset)` pairs, so the same three functions work on a single color, a gradient row, or a 100k-particle system -- no per-color wrapper object is ever created. Packers emit a 32-bit integer in **little-endian RGBA** byte order, which is exactly the layout a `Uint32Array` view of a canvas `ImageData` expects:
+
+```js
+const img = ctx.createImageData(w, h);
+const px  = new Uint32Array(img.data.buffer);   // px[i] = one pixel
+px[i] = packOklchBufferToUint32(colors, i * 3); // write directly, no copy
+ctx.putImageData(img, 0, 0);
+```
+
+---
+
+## The pipeline in one diagram
+
+```mermaid
+flowchart LR
+  A["CSS string<br/>oklch(...) or hex"] -->|parse, once| B["OKLCH buffer<br/>Float32Array L,C,H"]
+  B -->|lerpOklchBuffer / N| C["blended OKLCH<br/>Float32Array"]
+  B -->|bakeGradientToUint32| D["gradient LUT<br/>Uint32Array"]
+  C -->|packOklchBufferToUint32*| E["packed pixel<br/>Uint32 RGBA"]
+  D -->|sampleColorLUT| E
+  E -->|Uint32Array view| F["ImageData"]
+  F --> G["canvas"]
+```
+
+Everything left of `E` is `Float32`; everything from `E` right is integer pixels. The boundary is a single pack call. No object crosses it.
+
+---
+
+## Accuracy tiers
+
+The same OKLCH triplet can be packed several ways. Pick the trade-off per workload:
+
+| Tier | Function | Transfer | Speed (100k) | Error vs exact | Use when |
+|---|---|---|---|---|---|
+| **Fast** | `packOklchBufferToUint32Fast` | `sqrt` approx | ~fastest | ~10/255 midtone | huge counts, alpha-blended over content |
+| **Accurate** | `packOklchBufferToUint32` | true sRGB `pow` | baseline (~3M/s) | exact (round-trips) | correctness, exports, single colors |
+| **LUT** | `packOklchBufferToUint32IntoN(..., true)` | 4096-entry LUT | **~4x accurate (~14M/s)** | <= 1 LSB | 100k/frame, batched |
+| **P3** | `packOklchBufferToUint32P3` / `Fast` | P3 primaries | ~accurate / ~fast | -- | `display-p3` canvas contexts |
+| **Gamut** | `packOklchBufferToUint32MINDE` (`/gamut`) | chroma reduction | slowest | hue-preserving | vivid OKLCH that overflows sRGB |
+
+The **LUT tier gives you Fast-packer speed at Accurate-packer quality** -- it is the one to reach for in particle systems.
+
+---
+
+## Batch kernels and the 100k particle case
+
+v1.3 added buffer-to-buffer kernels for the shape a particle system actually has: one big SoA buffer in, one big pixel buffer out.
+
+```js
+import { lerpOklchBufferN, packOklchBufferToUint32IntoN } from "@zakkster/lite-color-engine";
+
+const N = 100_000;
+const from = new Float32Array(N * 3);
+const to   = new Float32Array(N * 3);
+const cur  = new Float32Array(N * 3);
+const px   = new Uint32Array(N);          // -> Uint32Array 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);
+```
+
+**An honest note on where the speed comes from.** The batch functions are mostly an *ergonomics* win, not a raw-throughput win: in V8 a clean monomorphic scalar loop inlines about as well as a hand-batched call, so accurate batch packing runs at the same speed as a scalar loop, and batch lerp is break-even. **The real win is `useLut: true`**, which removes `pow()` from the hot path. Everything below is measured, and the ratios -- not the absolute milliseconds -- are what to trust across machines.
+
+---
+
+## Benchmarks
+
+Reproduce with `node bench/benchmark.mjs` (median of 80 runs, 100k in-gamut triplets):
+
+| Packing 100k OKLCH -> Uint32 / frame | Throughput | ms/frame |
+|---|---|---|
+| scalar loop / batch accurate | ~3.2M/s | ~31 ms |
+| **batch + `useLut: true`** | **~13-14M/s** | **~7 ms** |
+| Fast (`sqrt`, ~10/255 error) | ~15M/s | ~7 ms |
+
+**What holds across machines (the safe headlines):**
+- LUT packing is **~4x** the accurate path.
+- LUT is **within 1 LSB** of exact -- i.e. *Fast-packer speed at Accurate-packer quality*.
+- Batching **by itself** is a wash (lerp ~1.0x, accurate pack ~1.0x); both are `pow`-bound, not call-bound.
+- 100k lerp+pack fits a 60fps frame budget **only with the LUT** (~10 ms vs ~35 ms accurate).
+
+Absolute milliseconds vary by device; the benchmark prints your machine's numbers and a paste-ready table.
+
+---
+
+## API reference
+
+### Parsing
+
+```ts
+parseCSSColor(str: string, out: Float32Array, off: number): number; // returns alpha
+parseHexToBuffer(str, out, off): number;
+parseRgbToBuffer(str, out, off): number;
+parseHslToBuffer(str, out, off): number;
+parseOklchToBuffer(str, out, off): number;
+parseOklabToBuffer(str, out, off): number;
+parseDisplayP3ToBuffer(str, out, off): number;
+```
+
+Each writes `[L, C, H]` at `out[off..off+2]` and returns the parsed alpha (`1.0` when absent). `parseCSSColor` sniffs the format and dispatches. Parsing allocates (regex, temporaries) and is meant for setup, not the frame loop.
+
+### Interpolation
+
+```ts
+lerpOklchBuffer(a, offA, b, offB, t: number, out, off): void;
+lerpOklchBufferN(a, offA, b, offB, t: number, out, off, n: number): void;
+```
+
+Lightness clamps to `[0,1]`, chroma to `[0, +inf)`, hue takes the **shortest path** and is canonicalized to `[0, 360)`. `lerpOklchBufferN` shares one `t` across `n` triplets and is bit-for-bit identical to `n` scalar calls. In-place safe.
+
+### Packing
+
+```ts
+packOklchBufferToUint32(buf, off, alpha = 1): number;      // accurate sRGB
+packOklchBufferToUint32Fast(buf, off, alpha = 1): number;  // sqrt approx
+packOklchBufferToUint32IntoN(src, offSrc, dst, offDst, n, alpha = 1, useLut = false): void;
+packOklchBufferToUint32P3(buf, off, alpha = 1): number;    // Display P3
+packOklchBufferToUint32P3Fast(buf, off, alpha = 1): number;
+```
 
-Parse once at init → work with `Float32Array` OKLCH buffers → zero allocations on the hot path.
+All return (or write) a 32-bit integer in little-endian RGBA order, hard-clamped to gamut. `IntoN` writes `n` pixels into `dst` at stride 1.
 
-## Installation
+### Gradient LUT
+
+```ts
+bakeGradientToUint32(
+  keyframes: Float32Array,   // contiguous [L0,C0,H0, L1,C1,H1, ...]
+  numStops: number,          // >= 2
+  resolution = 256,          // >= 2
+  easeFn?: (t: number) => number,
+  packer = packOklchBufferToUint32
+): Uint32Array;
+
+sampleColorLUT(lut: Uint32Array, t: number): number; // O(1), clamped, no alloc
+```
+
+Bake once (uses `lerpOklchBuffer` internally, so gradients are perceptual and hue-correct), then `sampleColorLUT` in the loop. Pass a custom `packer` to bake a P3 or gamut-mapped LUT.
+
+### Difference
+
+```ts
+deltaEOK(a, offA, b, offB): number; // Euclidean distance in OKLab
+```
+
+---
+
+## Wide gamut (Display P3)
+
+Parse `color(display-p3 ...)` and pack for a P3 canvas context. Colors outside sRGB but inside P3 keep their saturation.
+
+```js
+const c = new Float32Array(3);
+parseCSSColor("color(display-p3 0.9 0.2 0.35)", c, 0);
+
+const ctx = canvas.getContext("2d", { colorSpace: "display-p3" });
+const img = ctx.createImageData(w, h, { colorSpace: "display-p3" });
+const px  = new Uint32Array(img.data.buffer);
+px[i] = packOklchBufferToUint32P3(c, 0);
+```
+
+P3 is strictly opt-in. The default sRGB path and bundle are untouched if you never import the P3 packers.
+
+---
+
+## Gamut mapping (`/gamut`)
+
+Vivid OKLCH colors can fall outside sRGB. The default packers hard-clamp (fast, can shift hue). For hue-preserving results, the `/gamut` subpath does **MINDE** (minimum-delta-E) chroma reduction -- it walks chroma down until the color fits, keeping lightness and hue.
+
+```js
+import { packOklchBufferToUint32MINDE, gamutMapToSrgbBuffer } from "@zakkster/lite-color-engine/gamut";
+
+const px = packOklchBufferToUint32MINDE(buf, 0);        // pack with gamut mapping
+gamutMapToSrgbBuffer(inBuf, 0, outBuf, 0);              // or map in OKLCH space
+```
+
+`gamutMapToSrgbBuffer` is `@zakkster/lite-lerp`-free and self-contained, so the subpath loads standalone.
+
+---
+
+## Palette remap (`/remap`)
+
+Quantize a whole RGBA8 pixel buffer to a fixed palette using perceptual (OKLab) nearest-color -- for dithering-free posterization, theming, and retro/CRT looks.
+
+```js
+import { remapPixelsToPalette } from "@zakkster/lite-color-engine/remap";
+
+// paletteLch: Float32Array of [L,C,H] triplets; inU8: RGBA8 pixels; outU32: packed result
+remapPixelsToPalette(inU8, paletteLch, outU32, pixelCount, paletteCount, opts);
+```
+
+Lower-level building blocks are exported too: `sRgba8ToOklabBuffer`, `oklchToOklabBuffer`, `oklabToOklchBuffer`, `nearestPaletteIndexBuffer`.
+
+---
+
+## Formatters
+
+Round-trip OKLCH buffers back to CSS for exports, design tools, and telemetry (authoring-time; they allocate a string).
+
+```js
+import { formatOklchCss, formatHex } from "@zakkster/lite-color-engine";
+
+const b = new Float32Array(3);
+parseCSSColor("#3fa9c8", b, 0);
+formatOklchCss(b, 0);       // "oklch(68.7% 0.105 221.0)"
+formatOklchCss(b, 0, 0.8);  // "oklch(68.7% 0.105 221.0) / 0.800"
+formatHex(b, 0);            // "#3fa9c8"
+```
+
+`formatHex` uses the accurate pack path, so it round-trips with `parseHexToBuffer` to within 1 LSB. Alpha is emitted only when supplied and below 1.
+
+---
+
+## Allocation profile
+
+Honest accounting of where memory is spent:
+
+| Operation | Allocates | Per-frame allocation |
+|---|---|---|
+| `parseCSSColor` / `parse*` | regex + temporaries | (setup only) |
+| `bakeGradientToUint32` | one `Uint32Array` LUT | (setup only) |
+| `formatOklchCss` / `formatHex` | one string | (authoring only) |
+| `lerpOklchBuffer` / `N` | -- | **0** |
+| `packOklchBufferToUint32*` | -- | **0** |
+| `packOklchBufferToUint32IntoN` | -- | **0** |
+| `sampleColorLUT` | -- | **0** |
+| `deltaEOK` | -- | **0** |
+
+The 4k sRGB LUT behind `useLut` is a single module-load allocation, shared process-wide.
+
+---
+
+## Tree-shaking and subpaths
+
+`sideEffects: false`, pure ESM. Import only what you touch and the rest never enters your bundle. Wide-gamut mapping and palette remap live behind subpaths so they cost nothing unless imported:
+
+```js
+import { lerpOklchBuffer } from "@zakkster/lite-color-engine";          // core
+import { packOklchBufferToUint32MINDE } from "@zakkster/lite-color-engine/gamut";
+import { remapPixelsToPalette } from "@zakkster/lite-color-engine/remap";
+```
+
+One runtime dependency: [`@zakkster/lite-lerp`](https://www.npmjs.com/package/@zakkster/lite-lerp) (zero-dep itself).
+
+---
+
+## Testing
+
+117 tests across 7 files (`node --test` via Vitest):
+
+- **Parsing / authoring** -- every format, named colors, alpha, malformed input.
+- **Convert** -- sRGB and P3 round-trips against reference math.
+- **Runtime** -- pack byte order, transfer accuracy, `Fast` error bounds.
+- **Batch** -- `lerpOklchBufferN` and `packOklchBufferToUint32IntoN` proven **bit-for-bit** equal to scalar loops; LUT within 1 LSB.
+- **Formatters** -- hex/OKLCH round-trip, alpha rules, buffer purity.
+- **Gamut / Remap** -- MINDE hue preservation, palette nearest-color.
+- **DeltaE** -- perceptual difference against known pairs.
 
 ```bash
-npm install @zakkster/lite-color-engine
+npm test            # full suite
+node bench/benchmark.mjs   # reproduce the perf numbers
 ```
 
-## Quick Start
+---
+
+## Integration recipes
+
+### Scrolling canvas gradient (zero-GC)
 
 ```js
-import { 
-  parseCSSColor, 
-  lerpOklchBuffer, 
-  packOklchBufferToUint32,
-  packOklchBufferToUint32P3 
-} from '@zakkster/lite-color-engine';
+import { bakeGradientToUint32, sampleColorLUT, parseCSSColor } from "@zakkster/lite-color-engine";
+
+const stops = ["oklch(0.7 0.18 30)", "oklch(0.8 0.2 120)", "oklch(0.65 0.2 265)"];
+const kf = new Float32Array(stops.length * 3);
+stops.forEach((s, i) => parseCSSColor(s, kf, i * 3));
+const lut = bakeGradientToUint32(kf, stops.length, 512);
+
+function frame(t) {
+  for (let x = 0; x < w; x++) {
+    px[x] = sampleColorLUT(lut, (x / w + t * 0.0002) % 1);
+  }
+  for (let y = 1; y < h; y++) px.copyWithin(y * w, 0, w); // replicate row
+  ctx.putImageData(img, 0, 0);
+  requestAnimationFrame(frame);
+}
+```
+
+### 100k particles colored by life
 
-const buf = new Float32Array(3);
-parseCSSColor('color(display-p3 0.9 0.4 0.1)', buf, 0);
+```js
+import { bakeGradientToUint32, sampleColorLUT } from "@zakkster/lite-color-engine";
 
-// Later in render loop (zero GC)
-lerpOklchBuffer(bufA, 0, bufB, 0, t, temp, 0);
-const pixel = packOklchBufferToUint32P3(temp, 0); // or packOklchBufferToUint32
+const lut = bakeGradientToUint32(kf, kf.length / 3, 256);
+function render() {
+  px.fill(0xFF000000);                            // px = Uint32Array view of ImageData
+  for (let i = 0; i < N; i++) {
+    const color = sampleColorLUT(lut, life[i] / maxLife[i]);
+    px[(partY[i] | 0) * w + (partX[i] | 0)] = color;   // direct pixel write
+  }
+  ctx.putImageData(img, 0, 0);
+}
 ```
 
-## Accuracy Tiers
+(A full oscilloscope-themed demo with this scene ships in `demo/index.html` -- run `npx serve .` from the package root.)
+
+---
+
+## Browser and runtime support
+
+<details>
+<summary>Support matrix.</summary>
+
+Pure ES2020 typed arrays + `Math`. Runs anywhere modern JS runs.
+
+| Target | Supported |
+|---|---|
+| Chrome / Edge (last 2 majors) | yes |
+| Firefox (last 2 majors) | yes |
+| Safari 15+ | yes |
+| Node.js 18+ | yes |
+| Bun / Deno | yes |
+| Twitch Extensions (1MB / 3s) | yes |
+| Cloudflare Workers | yes |
+
+Display-P3 canvas output additionally needs a browser with `{ colorSpace: "display-p3" }` support (Chrome/Safari). ESM-only; no CommonJS build.
+
+</details>
+
+---
+
+## What this is not
+
+- **Not a `Color` object library.** No class, no method chaining. If you want `color("red").lighten(0.1).hex()`, use `culori` or `color.js`; they allocate, and for authoring that's fine.
+- **Not a CSS engine.** It parses the color grammar it needs, not `calc()`, relative color syntax, or `color-mix()`.
+- **Not a full ICC color-management stack.** It handles sRGB and Display P3. No CMYK, no arbitrary ICC profiles.
+- **Not a renderer.** It produces pixels; you own the canvas, the loop, and the physics.
+
+---
+
+## FAQ
+
+**Why OKLCH and not HSL or Lab?** HSL interpolation muddies and shifts lightness; Lab hue paths are awkward. OKLCH is perceptually uniform *and* has a natural hue axis, so gradients stay clean and even.
 
-| Tier              | Function                        | Use Case                          | Trade-off          |
-|-------------------|----------------------------------|-----------------------------------|--------------------|
-| Fast              | `packOklchBufferToUint32Fast`   | Particles, high volume            | ~10/255 midtone error |
-| Accurate-Clamp    | `packOklchBufferToUint32`       | Most UI / general use             | Hard clamp (hue shift near edge) |
-| Gamut-Mapped      | `packOklchBufferToUint32MINDE`  | Critical gradients & authoring    | ~30x slower, best quality |
+**Why `Float32Array` instead of objects?** Objects allocate and pointer-chase. Flat arrays are cache-friendly and let the same function serve one color or a million. It's the difference between 3M and jank, and 14M and smooth.
 
-> `packOklchBufferToUint32MINDE` ships on the `/gamut` subpath:
-> `import { packOklchBufferToUint32MINDE } from '@zakkster/lite-color-engine/gamut';`
-> The `Fast`, `Accurate-Clamp`, and both `P3` packers come from the main entry.
+**Is the `Fast` packer wrong?** It's approximate -- `sqrt` instead of the sRGB transfer, ~10/255 in midtones. Fine when the pixel is alpha-blended over arbitrary content; not for exact round-trips. Use the LUT tier if you want speed *and* accuracy.
 
-For Display P3 output, use the `P3` variants.
+**Do I have to manage buffers myself?** Yes -- that's the point. You allocate scratch once at setup and reuse it. The library never allocates behind your back on the frame path.
 
-## Documentation
+**Does `useLut` change my output?** By at most 1 LSB per channel versus the exact packer -- imperceptible, and it removes `pow()` from the loop for ~4x throughput.
 
-See full API in `llms.txt` or the source `src/` files.
+---
 
 ## License
 
-MIT
+MIT (c) Zahary Shinikchiev. See [LICENSE.md](./LICENSE.md).

package/index.d.ts

@@ -87,6 +87,25 @@ export function parseCSSColor(str: string, outBuf: Float32Array, offset: number)
  */
 export function parseDisplayP3ToBuffer(str: string, outBuf: Float32Array, offset: number): number;
 
+// ============================================================================
+// Formatters (round-trip emit - authoring layer)
+// ============================================================================
+
+/**
+ * Emits a modern CSS `oklch(L% C H)` string (or with `/ alpha`) from a buffered
+ * OKLCH triplet. Precision is chosen for good visual and numeric round-tripping
+ * through `parseCSSColor`. Alpha is omitted when not supplied or >= 0.9995.
+ * Authoring-time helper (allocates a string); not for per-frame hot paths.
+ */
+export function formatOklchCss(buf: Float32Array, off: number, alpha?: number): string;
+
+/**
+ * Converts an OKLCH triplet to a `#rrggbb` hex string via the accurate sRGB
+ * pack path. Round-trips with `parseHexToBuffer` to within 1 LSB per channel.
+ * Authoring-time helper (allocates a string); not for per-frame hot paths.
+ */
+export function formatHex(buf: Float32Array, off: number): string;
+
 // ============================================================================
 // Convert (Raw Math)
 // ============================================================================
@@ -155,6 +174,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 +231,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

@@ -5,15 +5,19 @@ export {
     parseOklabToBuffer,
     parseOklchToBuffer,
     parseRgbToBuffer,
-    parseDisplayP3ToBuffer
+    parseDisplayP3ToBuffer,
+    formatOklchCss,
+    formatHex
 } from './src/authoring.js';
 
 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.4)
 
 ## Core Exports
 
@@ -6,17 +6,27 @@
 - `parseCSSColor(str, outBuf, offset)` — Universal parser. Now supports `color(display-p3 r g b / alpha)`
 - `parseDisplayP3ToBuffer(str, outBuf, offset)` — Direct P3 parser
 
+### Formatters (v1.4, authoring-time - allocate a string)
+- `formatOklchCss(buf, off, alpha?)` - OKLCH triplet -> `oklch(L% C H)` (or `/ alpha`); round-trips via parseCSSColor.
+- `formatHex(buf, off)` - OKLCH triplet -> `#rrggbb` via the accurate pack path; round-trips with parseHexToBuffer within 1 LSB.
+
 ### 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)
+### 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.4.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/authoring.js

@@ -1,4 +1,5 @@
 import { sRgbToOklchBuffer, displayP3ToOklchBuffer } from './convert.js';
+import { packOklchBufferToUint32 } from './runtime.js';
 
 const RAD_TO_DEG = 180 / Math.PI;
 
@@ -80,7 +81,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', darkslateggrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
+    darkslategray: '#2f4f4f', darkslategrey: '#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',
@@ -91,12 +92,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: '#b0e0e6', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
+    lightsteelblue: '#b0c4de', 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',
-    navajawhite: '#ffdead', navy: '#000080', oldlace: '#fdf5e6', olive: '#808000',
+    navajowhite: '#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',
@@ -301,3 +302,59 @@ export const parseCSSColor = (str, outBuf, offset) => {
 
     throw new Error(`lite-color-engine: Unsupported color format "${str}".`);
 };
+
+// ============================================================================
+// 6. FORMATTERS (round-trip emit - authoring layer, string allocation is fine)
+// ============================================================================
+
+/**
+ * Emits a modern CSS `oklch(...)` string from an OKLCH buffer triplet.
+ * Suitable for exports, CSS custom properties, gradient studios, telemetry, etc.
+ *
+ * Lightness is emitted as a percentage (e.g. `60.0%`), chroma and hue with
+ * enough precision to round-trip through `parseOklchToBuffer`/`parseCSSColor`.
+ * Alpha is included only when supplied and below 1.
+ *
+ * This is an authoring-time helper: it allocates a string and is not intended
+ * for per-frame hot paths.
+ *
+ * @param {Float32Array} buf - Buffer containing [L, C, H]
+ * @param {number} off - Offset of the triplet
+ * @param {number} [alpha] - Optional alpha [0, 1]. Omitted from output when >= 0.9995 or not supplied.
+ * @returns {string} e.g. "oklch(60.0% 0.150 250.0)" or with " / 0.800"
+ */
+export const formatOklchCss = (buf, off, alpha) => {
+    const l = buf[off] * 100;
+    const c = buf[off + 1];
+    const h = buf[off + 2];
+    let s = `oklch(${l.toFixed(1)}% ${c.toFixed(3)} ${h.toFixed(1)})`;
+    if (alpha != null && alpha < 0.9995) {
+        s += ` / ${alpha.toFixed(3)}`;
+    }
+    return s;
+};
+
+/**
+ * Converts an OKLCH buffer triplet to a 6-digit `#rrggbb` hex string (no alpha).
+ *
+ * Uses the accurate sRGB transfer + pack path, so it round-trips with
+ * `parseHexToBuffer` + `packOklchBufferToUint32` to within 1 LSB per channel
+ * (the accurate packer's rounding tolerance). Out-of-sRGB-gamut input is hard
+ * clamped, matching the packer.
+ *
+ * Authoring-time helper: allocates a string, not for per-frame hot paths.
+ *
+ * @param {Float32Array} buf - Buffer containing [L, C, H]
+ * @param {number} off - Offset of the triplet
+ * @returns {string} e.g. "#ff0000"
+ */
+export const formatHex = (buf, off) => {
+    const u = packOklchBufferToUint32(buf, off);
+    const r = u & 0xff;
+    const g = (u >>> 8) & 0xff;
+    const b = (u >>> 16) & 0xff;
+    return '#' +
+        r.toString(16).padStart(2, '0') +
+        g.toString(16).padStart(2, '0') +
+        b.toString(16).padStart(2, '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) => {