@zakkster/lite-color-engine 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # Changelog
 
+## [1.5.0] - 2026-07-13
+
+### Added
+
+- **Blue-noise dither kernels** — shared kernel for the whole ecosystem
+  (studio, hueforge, gradient consumers) so there is exactly one
+  implementation to reason about:
+  - `getBlueNoise64()` — returns a shared, read-only `Uint8Array(4096)`
+    holding a 64x64 void-and-cluster blue-noise tile. Lazily decoded from
+    an inlined base64 blob on first call (sub-millisecond); subsequent
+    calls return the same reference. Histogram is exactly uniform (each
+    byte 0..255 appears 16 times). Index via
+    `tile[((y & 63) << 6) | (x & 63)]`; the tile is torus-tileable.
+    Generator committed as `tools/generate-bluenoise.mjs` with a fixed
+    seed. The tile is gated on its *spectral* properties, not just its
+    fingerprint — see `test/bluenoise-spectral.test.js`.
+  - `packOklchBufferToUint32Dithered(buf, off, alpha = 1.0, noise01 = 0.5)`
+    — scalar dithered packer. Threshold offset applied in gamma-encoded space, with
+    the same `noise01` shared across R, G, B (luminance-patterned dither,
+    no chroma speckle). Alpha is undithered. Parity guarantee:
+    `noise01 === 0.5` reproduces the byte output of
+    `packOklchBufferToUint32` bit-for-bit.
+  - `packOklchBufferToUint32IntoNDithered(src, offSrc, dst, offDst, n,
+    alpha, noiseTile, x0, y0, rowWidth)` — batch variant that walks the
+    tile in row-major order over an arbitrary destination rectangle. Zero
+    allocations; no modulo/division in the hot loop.
+
+  **Honest note on `useLut`:** the batch dithered packer does *not* accept
+  the 4k transfer LUT flag. `SRGB_LUT` stores rounded bytes, which
+  discards the sub-integer information the dither threshold shift needs;
+  enabling it would silently collapse dither to plain rounding. A
+  companion `Float32Array` LUT of encoded floats (~16 KB, lazy) is a
+  v1.6 candidate that would restore this axis.
+
+- **Batch P3 packer:** `packOklchBufferToUint32P3IntoN(src, offSrc, dst,
+  offDst, n, alpha?, useLut?)` — P3 sibling of the v1.3 sRGB batch. The
+  P3 transfer function is identical to sRGB (IEC 61966-2-1), so the same
+  `SRGB_LUT` is reused when `useLut=true` — no separate 4 KB table is
+  allocated. Same accuracy story as the sRGB LUT path (within 1 LSB of
+  exact) and same fast-packer throughput class.
+
+- **Batch MINDE:** `gamutMapToSrgbBufferN(inBuf, off, outBuf, offOut, n)`
+  (on the `./gamut` subpath) — batch sibling of the scalar MINDE mapper.
+  Bit-for-bit identical to `n` scalar calls; the batch amortizes call
+  overhead for authoring / LUT-building large color runs (hueforge P3
+  exporters, studio bake paths) that today loop the scalar. Setup-time /
+  bake-time convenience — MINDE stays out of the per-frame hot path.
+
+- **Cyclic LUT bake:** `bakeGradientToUint32` gained a trailing `opts`
+  parameter with `{ closed: true }`. In closed mode, stops are treated
+  cyclically (last stop wraps back to first), sample positions become
+  `i / resolution` (period spacing, no duplicated endpoint), and
+  `easeFn` outputs are period-wrapped via `t - floor(t)` instead of
+  clamped. Pairs with `sampleColorLUTWrapped` on the consumer side. The
+  seam continuity is asserted: `|lut[res-1] - lut[0]|` per channel is
+  bounded by the maximum adjacent-cell interior delta.
+
+- **Preflight gate (stale-base cure):** `npm run preflight` fetches the
+  latest published tarball via `npm pack` and hash-compares every file
+  in `files[]` against the working tree. Hard-fails on code drift
+  (`index.js`, `index.d.ts`, `src/**`, `package.json`); warns for doc
+  drift (`README.md`, `CHANGELOG.md`, `LICENSE.md`, `llms.txt`). This is
+  the structural cure for the v1.3/v1.4 regressions that started from an
+  unrebased working tree. Session protocol: run preflight before feature
+  work.
+
+### Fixed (pre-release, against the 1.5.0 release candidate)
+
+- **Blue-noise tile: Phase 3 of the void-and-cluster generator was
+  inverted.** The RC selected the 0-cell with the *highest* filtered
+  ones-field — the cell most surrounded by 1s, which is an **isolated**
+  zero (the largest void of the complement), not its tightest cluster.
+  The correct selector is the *minimum*: because the filter is toroidal
+  and constant-sum, `zerosField = sum(K) - onesField`, so
+  `argmax(zerosField) === argmin(onesField)` and Phase 3 reduces to the
+  same `findLargestVoid()` call as Phase 2.
+
+  Effect: ranks below 2048 were unaffected, so every threshold pattern at
+  or below mid-gray was correct — and every threshold pattern **above**
+  it was 5–7x over-clustered. Dithering was sound in the shadows and
+  broken in the highlights, which is exactly where a dither earns its
+  keep. Radial power at `r=1` was 2.05 against a white-noise floor of
+  0.083: at the tile period the RC tile was *worse than random*.
+
+  The tile fingerprint therefore rotates:
+  `78926ec1…` → `8867ddb65e16379ad42244fa24b82dcbd813c684ce14944f86a9e3e8f6b72968`.
+  Same seed (`0xc0ffee1e`), same generator, one comparator.
+
+- **The RC gates could not see any of it.** All 17 tests in
+  `dither.test.js` passed the defective tile. A uniform histogram is
+  invariant under *any* permutation of ranks (a linear ramp satisfies
+  it); the SHA-256 assertion pins the artifact rather than validating it,
+  and was cementing the defect into the contract; and "dithered
+  run-length halved vs undithered" is satisfied by white noise too — it
+  tests *that* there is noise, not that the noise is blue. The
+  generator's own self-check measured field variance at `T=128` **only**,
+  which is precisely the one threshold an inverted Phase 3 cannot affect,
+  and it reported an identical healthy 0.5133 for the broken and the
+  fixed tile.
+
+  New `test/bluenoise-spectral.test.js` gates the property the feature is
+  named after: minority-phase clumpiness under 0.70 across `T=16..240`,
+  that curve symmetric about `T=128` (the assertion that fails the RC
+  first), radial power for `r<=4` below the white-noise floor, high-band
+  power above it, and wrap-edge decorrelation within 82% of interior. The
+  generator now runs the same sweep as a hard gate and refuses to emit a
+  tile that fails it.
+
+- `packOklchBufferToUint32Dithered` had no parameter defaults while every
+  sibling packer defaults `alpha = 1.0`. Calling it with the plain
+  packer's arity returned `0x00000000` — silent transparent black. It now
+  defaults `alpha = 1.0, noise01 = 0.5`, so a 2-argument call is exactly
+  `packOklchBufferToUint32`.
+
+- **The sRGB transfer function had 8 copies in `src/runtime.js`** — 6 of them
+  added by the F1 dither work, which inlined the encode per channel in both
+  dithered packers. They now derive from a single `srgbEncode(c)` helper, which
+  `SRGB_LUT` and `linearToSrgbByte` also route through: one definition of the
+  IEC 61966-2-1 constants in the module. The dither packers genuinely cannot use
+  `linearToSrgbByte` (it rounds) or `SRGB_LUT` (it stores rounded bytes) — they
+  need the sub-integer encoded value — but that argued for extracting the shared
+  step, not for copying it six times. The real exposure was the
+  `noise01 === 0.5` parity guarantee: it holds only while the dither path and
+  the plain path agree on the encode, and nothing structural was keeping them in
+  step. Now they are the same function, and the parity test guards it.
+
+  Measured, since "the duplication forces V8 to monomorphize the loop" is a
+  testable claim: interleaved A/B, 40 rounds, 12 primer passes, N=100k. The
+  helper form came in at 0.9978x / 0.9981x / 0.9967x / 0.9983x of the inlined
+  form on the dithered batch, and within +/-0.3% on the scalar. V8 inlines it
+  outright. The duplication bought nothing.
+
+  `src/Gamut.js` and `src/Remap.js` keep their own single copies **on purpose**.
+  Both modules currently have zero imports, and `Gamut.js` is a subpath export
+  (`./gamut`); making it import from `runtime.js` would drag the module-level
+  `SRGB_LUT` build and the 5.4 KB blue-noise blob into the gamut consumer's
+  graph. One duplicated line each is the cheaper trade. A shared `src/transfer.js`
+  would collapse the last two without that cost, if it is ever worth a file.
+
+- `getBlueNoise64()` read `Buffer` as a free identifier. Webpack 4 and
+  browserify pattern-match that token and inject the ~20 KB buffer
+  polyfill into browser bundles — for a package whose pitch is a
+  single zero-dependency file. Now reads `globalThis.Buffer`, which is
+  not matched; browser builds stay on the `atob` path.
+
+### Demo
+
+- `demo/index.html` particle cull guard rewritten from `(out of range)` to
+  `!(in range)`. Identical for every finite value and the same four compares —
+  but NaN makes every comparison false, so the old form let a NaN coordinate
+  through to `(pY[i] | 0) * w + (pX[i] | 0)`, where `NaN | 0` is `0` and the
+  particle silently paints pixel (0,0) forever. Not reachable today (the `+ 1`
+  in `d2` rules out the divide-by-zero and `F_DAMP` bounds the integration);
+  this is a free guard against a future edit to the force math.
+
+### Known / deferred
+
+- **Dither DC bias.** `noise01 = byte / 256` has mean `127.5/256 =
+  0.498046875`, not `0.5`, so `floor(v + noise)` darkens by a constant
+  `-1/512` LSB on every pixel. It is deterministic, not noise, and
+  invisible (0.2% of one code value) — but it is a bias, and the JSDoc
+  leans on "the mean and variance of a uniform distribution" as if that
+  mean were 0.5. The fix, `(byte + 0.5) / 256`, would centre it exactly —
+  at the cost of the `noise01 === 0.5` parity guarantee, since no byte
+  maps to 127.5. Kept as-is for v1.5; the parity property is worth more
+  than 1/512 of a code value. Revisit alongside the v1.6 float-LUT.
+
+### Notes
+
+- No breaking changes. All v1.4 exports (batch kernels, 4k LUT, Display
+  P3, CSS formatters, `sampleColorLUT`) are retained with identical
+  byte-level output.
+- Existing open-mode `bakeGradientToUint32` calls are byte-identical to
+  v1.4 (verified by regression tests) — closed mode is opt-in via the
+  new trailing `opts` argument.
+- Zero-GC audit: every new hot-path function is allocation-free after
+  the one-time lazy noise decode.
+
+---
+
 ## [1.4.0] - 2026-07-10
 
 ### Added

package/README.md

@@ -8,6 +8,7 @@
 [![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)
+[![Coverage Status](https://coveralls.io/repos/github/PeshoVurtoleta/lite-color-engine/badge.svg?branch=main)](https://coveralls.io/github/PeshoVurtoleta/lite-color-engine?branch=main)
 ![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)
@@ -214,6 +215,34 @@ Absolute milliseconds vary by device; the benchmark prints your machine's number
 
 ---
 
+## New in v1.5
+
+Three additions that make the engine the ecosystem's shared color kernel for `lite-gradient-studio` v1.2 and `lite-hueforge` v1.5:
+
+**Blue-noise dither kernels.** `getBlueNoise64()` returns a shared 64x64 void-and-cluster tile as a `Uint8Array(4096)`, decoded on first call from an inlined base64 blob and reused thereafter (histogram is exactly uniform: each byte 0..255 appears 16 times; torus-tileable). `packOklchBufferToUint32Dithered(buf, off, alpha = 1.0, noise01 = 0.5)` and its batch sibling `packOklchBufferToUint32IntoNDithered(..., noiseTile, x0, y0, rowWidth)` apply a threshold-offset dither in gamma-encoded space, shared across R/G/B — luminance-only, no chroma speckle. Parity: `noise01 === 0.5` reproduces the plain packer bit-for-bit. Zero allocations after the one-time noise decode.
+
+```js
+import { getBlueNoise64, packOklchBufferToUint32IntoNDithered } from "@zakkster/lite-color-engine";
+
+const tile = getBlueNoise64();
+// Pack a full row of the destination raster, walking the tile in row-major order:
+packOklchBufferToUint32IntoNDithered(oklchBuf, 0, pxOut, y * W, W, 1.0, tile, 0, y, W);
+```
+
+**Cyclic LUT bake.** `bakeGradientToUint32` gained a trailing `opts` argument: `{ closed: true }` bakes a period-spaced LUT (samples at `i / resolution`, no duplicated endpoint) where the last stop wraps back to the first. Pair with `sampleColorLUTWrapped` (in `@zakkster/lite-color-lerp` v1.1) for hue wheels and cyclic colorways. Open-mode calls are byte-identical to v1.4.
+
+**P3 and MINDE batch parity.** `packOklchBufferToUint32P3IntoN` closes the last gap in the batch-kernel family — same shape as the sRGB batch, and `useLut=true` reuses the existing `SRGB_LUT` (the P3 transfer function is IEC 61966-2-1, identical to sRGB), so there is no second table to allocate. `gamutMapToSrgbBufferN` (on the `/gamut` subpath) batches MINDE for bulk authoring / LUT-build workloads that today loop the scalar.
+
+**Preflight (`npm run preflight`).** Fetches the latest published tarball via `npm pack` and hash-compares against the working tree. Hard-fails on drift in code (`index.js`, `index.d.ts`, `src/**`, `package.json`); warns for doc drift only. Run it before starting feature work — this is the structural cure for the stale-base regressions that hit v1.3 and v1.4.
+
+**The tile is gated on its spectrum, not its fingerprint.** `test/bluenoise-spectral.test.js` asserts what "blue noise" actually means: minority-phase clumpiness stays under 0.70 across thresholds 16..240, that curve is symmetric about T=128, radial power for `r <= 4` sits below the white-noise floor of 1/12, high-band power sits above it, and the wrap edges are as decorrelated as the interior. A uniform histogram does **not** imply blue noise — a linear ramp has a perfectly uniform histogram. The v1.5.0 release candidate shipped a tile that passed every histogram, fingerprint and banding gate and was still 7x over-clustered above mid-gray; the SHA-256 assertion was pinning the defect rather than catching it. The generator now runs the same sweep as a hard gate and refuses to emit a tile that fails it.
+
+**Known gap.** There is no dithered *P3* batch — `packOklchBufferToUint32P3IntoNDithered` does not exist in v1.5. Wide-gamut surfaces band too; it is a v1.6 candidate alongside the float LUT.
+
+See CHANGELOG for the honest-notes edition, including why the dithered batch does not accept `useLut` (short version: the LUT stores pre-rounded bytes; dither needs sub-integer encoded values — a float LUT that restores this axis is a v1.6 candidate), and the deferred `-1/512` LSB dither DC bias.
+
+---
+
 ## API reference
 
 ### Parsing
@@ -431,7 +460,7 @@ function render() {
 }
 ```
 
-(A full oscilloscope-themed demo with this scene ships in `demo/index.html` -- run `npx serve .` from the package root.)
+(A full oscilloscope-themed demo ships in `demo/index.html` -- run `npx serve .` from the package root. Five scenes: particle field, batch kernels, accuracy tiers + the v1.5 P3 batch on a `display-p3` canvas, blue-noise dither on a shallow highlight ramp, and the open-vs-closed cyclic bake shown as a hue ring with its seam measured live.)
 
 ---
 

package/index.d.ts

@@ -231,6 +231,28 @@ export function packOklchBufferToUint32Fast(
     alpha?: number
 ): number;
 
+/**
+ * Dithered sibling of {@link packOklchBufferToUint32}. Applies a threshold-
+ * offset dither in gamma-encoded space with a caller-supplied `noise01` value,
+ * shared across R/G/B so the dither is a luminance pattern (no chroma speckle).
+ * Alpha is undithered.
+ *
+ * Parity: `noise01 === 0.5` reproduces the byte output of the plain packer
+ * exactly (asserted by the test suite).
+ *
+ * `noise01` is expected in `[0, 1)`. When driven from the shared blue-noise
+ * tile, use `getBlueNoise64()[((y & 63) << 6) | (x & 63)] / 256`, which stays
+ * strictly below 1 and gives a low-discrepancy sample.
+ *
+ * @returns 32-bit unsigned integer in little-endian RGBA byte order.
+ */
+export function packOklchBufferToUint32Dithered(
+    buf: Float32Array,
+    offset: number,
+    alpha?: number,
+    noise01?: 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.
@@ -245,6 +267,30 @@ export function packOklchBufferToUint32IntoN(
     useLut?: boolean
 ): void;
 
+/**
+ * Dithered batch packer: walks a 64x64 blue-noise tile in row-major order and
+ * applies a per-pixel luminance-patterned threshold dither (same noise value
+ * across R/G/B; alpha undithered). The tile is torus-indexed
+ * (`tile[((y & 63) << 6) | (x & 63)]`) so any `x0`/`y0`/`rowWidth` combination
+ * is safe. Zero allocations; no modulo/division in the hot loop.
+ *
+ * The 4k sRGB transfer LUT is *not* an option here — that LUT stores rounded
+ * bytes and would silently degrade the dither to plain rounding. A companion
+ * float LUT restoring this axis is a v1.6 candidate.
+ */
+export function packOklchBufferToUint32IntoNDithered(
+    src: Float32Array,
+    offSrc: number,
+    dst: Uint32Array,
+    offDst: number,
+    n: number,
+    alpha: number,
+    noiseTile: Uint8Array,
+    x0: number,
+    y0: number,
+    rowWidth: number
+): void;
+
 /**
  * Encodes an OKLCH triplet to a 32-bit unsigned integer in little-endian RGBA
  * byte order for a **Display P3** canvas context
@@ -278,6 +324,37 @@ export function packOklchBufferToUint32P3Fast(
     alpha?: number
 ): number;
 
+/**
+ * Batch sibling of {@link packOklchBufferToUint32P3}. Packs `n` OKLCH triplets
+ * (stride 3) into `n` Uint32 pixels encoded for Display P3. `useLut=true`
+ * shares the 4k sRGB transfer LUT (the P3 transfer function is IEC 61966-2-1,
+ * identical to sRGB — no separate table is allocated), giving fast-packer
+ * throughput at within ~1 LSB of the exact encoder.
+ */
+export function packOklchBufferToUint32P3IntoN(
+    src: Float32Array,
+    offSrc: number,
+    dst: Uint32Array,
+    offDst: number,
+    n: number,
+    alpha?: number,
+    useLut?: boolean
+): void;
+
+/**
+ * Returns the shared 64x64 blue-noise tile as a `Uint8Array(4096)`, lazily
+ * decoded from an inlined base64 blob on first call and reused thereafter.
+ *
+ * Index a pixel via `tile[((y & 63) << 6) | (x & 63)]`. The tile is
+ * torus-tileable: repeating it end-to-end on either axis is spectrally
+ * seamless. Each byte 0..255 appears exactly 16 times (uniform histogram),
+ * so `byte / 256` gives a low-discrepancy sample in `[0, 1)`.
+ *
+ * The returned reference is shared and must not be mutated; callers that
+ * need to modify the values should copy first.
+ */
+export function getBlueNoise64(): Uint8Array;
+
 /**
  * Zero-GC sampler for a baked LUT. Inline `t`-clamp + bitwise-truncated index.
  *
@@ -300,10 +377,17 @@ export type OklchPackerFn = (buf: Float32Array, offset: number, alpha?: number)
  * 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
- * optional `easeFn` warps the parametric position **before** stop selection.
- * Easing outputs outside `[0, 1]` are clamped (the LUT is fixed-resolution
- * and cannot represent overshoot).
+ * **Open mode** (default): stops are evenly distributed — stop _i_ at
+ * `i / (numStops - 1)`; LUT sample _j_ at `j / (resolution - 1)`. Sample 0
+ * lands on stop 0, sample `resolution-1` on the last stop. Overshoot from
+ * `easeFn` is clamped to `[0, 1]`.
+ *
+ * **Closed mode** (`opts.closed = true`, new in v1.5): stops are treated
+ * cyclically — the wrap segment runs from `stops[numStops-1]` back to
+ * `stops[0]`. Sample _j_ is at `j / resolution` (period spacing, no duplicated
+ * endpoint). `easeFn` outputs are wrapped via `t - floor(t)` instead of
+ * clamped. Pair with `sampleColorLUTWrapped` on the consumer side (hue wheels,
+ * cyclic colorways).
  *
  * @param keyframesBuf Contiguous buffer of `[L0, C0, H0, L1, C1, H1, ...]`.
  * @param numStops Stop count; must be `>= 2`.
@@ -312,6 +396,7 @@ export type OklchPackerFn = (buf: Float32Array, offset: number, alpha?: number)
  * @param packer Optional packer override. Defaults to the accurate
  *               {@link packOklchBufferToUint32}. Pass
  *               {@link packOklchBufferToUint32Fast} for ~2x bake throughput.
+ * @param opts Optional bake options. `{ closed: true }` bakes a cyclic LUT.
  * @throws If `numStops < 2` or `resolution < 2`.
  */
 export function bakeGradientToUint32(
@@ -319,7 +404,8 @@ export function bakeGradientToUint32(
     numStops: number,
     resolution?: number,
     easeFn?: (t: number) => number,
-    packer?: OklchPackerFn
+    packer?: OklchPackerFn,
+    opts?: { closed?: boolean }
 ): Uint32Array;
 
 // ============================================================================

package/index.js

@@ -17,10 +17,14 @@ export {
     lerpOklchBufferN,
     packOklchBufferToUint32,
     packOklchBufferToUint32Fast,
+    packOklchBufferToUint32Dithered,
     packOklchBufferToUint32IntoN,
+    packOklchBufferToUint32IntoNDithered,
     packOklchBufferToUint32P3,
     packOklchBufferToUint32P3Fast,
-    sampleColorLUT
+    packOklchBufferToUint32P3IntoN,
+    sampleColorLUT,
+    getBlueNoise64
 } from './src/runtime.js';
 
 export {

package/llms.txt

@@ -1,4 +1,4 @@
-# lite-color-engine - LLM Reference (v1.4)
+# lite-color-engine - LLM Reference (v1.5)
 
 ## Core Exports
 
@@ -12,27 +12,54 @@
 
 ### Conversion
 - `sRgbToOklchBuffer(r, g, b, out, off)`
-- `displayP3ToOklchBuffer(r, g, b, out, off)` — New in v1.2
+- `displayP3ToOklchBuffer(r, g, b, out, off)`
 - `oklchToLinearP3(L, C, H, out)` — Inverse for P3 packing
 
 ### Runtime (Hot Path - Zero GC)
 - `lerpOklchBuffer(...)`
 - `packOklchBufferToUint32(buf, off, alpha?)` - Accurate sRGB
 - `packOklchBufferToUint32Fast(...)` - Fast approx
+- `packOklchBufferToUint32Dithered(buf, off, alpha?, noise01?)` — defaults `alpha=1.0, noise01=0.5`, so a 2-arg call is exactly `packOklchBufferToUint32` — **v1.5** dithered sRGB packer.
+  Luminance-only threshold dither (same `noise01` across R/G/B, no chroma speckle).
+  `noise01 = 0.5` reproduces the plain packer exactly.
 - `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).
+- `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).
+- `packOklchBufferToUint32P3IntoN(src, offSrc, dst, offDst, n, alpha?, useLut?)` — **v1.5** P3 batch. `useLut=true` reuses the same `SRGB_LUT` (identical transfer function per IEC 61966-2-1); no separate table is allocated.
+- `packOklchBufferToUint32IntoNDithered(src, offSrc, dst, offDst, n, alpha, noiseTile, x0, y0, rowWidth)` — **v1.5** dithered batch. Walks a 64x64 blue-noise tile in row-major order over destination `(x0, y0)` with `rowWidth`. Zero allocations, no modulo in hot loop. Exact-encoder only (see note below).
+- Note: the batch win comes from `useLut`, not from call-amortization (accurate batch ~= scalar loop in V8; pow-bound). The dithered batch has no `useLut` axis — `SRGB_LUT` stores rounded bytes, which would collapse the dither threshold; a float LUT restoring this is a v1.6 candidate.
+
+### Blue-noise tile (v1.5)
+- `getBlueNoise64()` — Returns the shared 64x64 blue-noise tile as `Uint8Array(4096)`.
+  Lazily decoded from an inlined base64 blob on first call (sub-ms), then shared. Void-and-cluster,
+  histogram exactly uniform (16x each byte). Index via `tile[((y & 63) << 6) | (x & 63)]`.
+  Do not mutate the returned reference. Torus-tileable on both axes.
+- The tile is gated on SPECTRAL properties, not just its SHA-256 fingerprint
+  (`test/bluenoise-spectral.test.js`): minority-phase clumpiness < 0.70 across thresholds
+  16..240, that curve symmetric about T=128, radial power for r<=4 below the white-noise
+  floor of 1/12, high-band power above it, wrap edges as decorrelated as the interior.
+  A uniform histogram does NOT imply blue noise — a linear ramp has a perfectly uniform
+  histogram. The 1.5.0 release candidate shipped a tile that passed every histogram /
+  fingerprint / banding gate and was still 7x over-clustered above mid-gray (inverted
+  Phase 3 selector in the generator). Do not treat the fingerprint as the gate.
 
 ### 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.
+- `gamutMapToSrgbBuffer(inBuf, off, outBuf, offOut)` — MINDE chroma-reduction gamut map (scalar).
+- `gamutMapToSrgbBufferN(inBuf, off, outBuf, offOut, n)` — **v1.5** batch MINDE. Bit-for-bit identical to n scalar calls; for authoring / LUT-build bulk mapping.
+- `packOklchBufferToUint32MINDE(buf, off, alpha?)` — MINDE + pack. ~30x slower than the core packer; LUT-build/authoring time only.
+
+### LUT (Gradient Baking)
+- `bakeGradientToUint32(keyframesBuf, numStops, resolution?, easeFn?, packer?, opts?)` — accepts any of the above packers.
+  - **v1.5:** trailing `opts` object. `{ closed: true }` bakes a cyclic LUT: sample positions `i / resolution` (period, no duplicated endpoint), wrap segment last->first, ease outputs period-wrapped via `t - floor(t)`. Pair with `sampleColorLUTWrapped` on the consumer side (hue wheels, cyclic colorways).
+  - Open mode (default) is byte-identical to v1.4.
+
+## Session Gate (v1.5)
 
-### LUT
-- `bakeGradientToUint32(..., packer?)` — Accepts any of the above packers
+- `npm run preflight` — mandatory before feature work. Fetches the published tarball via `npm pack` and hash-compares against HEAD. Hard-fails on code drift (`index.js`, `index.d.ts`, `src/**`, `package.json`); warns for doc drift.
 
 ## Key Principles
 - All hot-path functions are allocation-free

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-color-engine",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "description": "Zero-GC, data-oriented OKLCH color engine and WebGL/Canvas buffer pipeline.",
   "type": "module",
@@ -60,13 +60,14 @@
   ],
   "scripts": {
     "test": "vitest run",
-    "bench": "node bench/benchmark.mjs"
+    "bench": "node bench/benchmark.mjs",
+    "preflight": "node tools/preflight.mjs"
   },
   "dependencies": {
     "@zakkster/lite-lerp": "^1.0.0"
   },
   "devDependencies": {
-    "vitest": "^1.0.0"
+    "vitest": "^4.1.10"
   },
   "license": "MIT",
   "homepage": "https://github.com/PeshoVurtoleta/lite-color-engine#readme",

package/src/Gamut.d.ts

@@ -19,6 +19,24 @@ export function gamutMapToSrgbBuffer(
     outOffset: number
 ): void;
 
+/**
+ * Batch sibling of `gamutMapToSrgbBuffer`. Maps `n` OKLCH triplets (stride 3)
+ * from `inBuf` into `outBuf` at the equivalent stride, using the same CSS
+ * Color 4 MINDE bisection. Bit-for-bit identical to `n` scalar calls; the
+ * batch exists to amortize call overhead for authoring / LUT-building large
+ * color runs (hueforge P3 exporters, studio bake paths).
+ *
+ * Setup-time / bake-time convenience — MINDE stays out of the per-frame hot
+ * path (~30x slower than the core packer). Zero allocations.
+ */
+export function gamutMapToSrgbBufferN(
+    inBuf: Float32Array,
+    inOffset: number,
+    outBuf: Float32Array,
+    outOffset: number,
+    n: number
+): void;
+
 /**
  * Accurate sibling of `packOklchBufferToUint32`. Runs MINDE gamut mapping
  * before packing, eliminating the hue-shift artifacts of the hard channel

package/src/Gamut.js

@@ -189,6 +189,39 @@ export function gamutMapToSrgbBuffer(inBuf, inOffset, outBuf, outOffset) {
 }
 
 
+// -----------------------------------------------------------------------------
+// gamutMapToSrgbBufferN
+// -----------------------------------------------------------------------------
+
+/**
+ * Batch sibling of {@link gamutMapToSrgbBuffer}. Maps `n` OKLCH triplets
+ * (stride 3) from `inBuf` into `outBuf` at the equivalent stride, using the
+ * same CSS Color 4 MINDE bisection as the scalar path. Bit-for-bit identical
+ * to calling {@link gamutMapToSrgbBuffer} `n` times; the batch exists to
+ * amortize call overhead when authoring / LUT-building large color runs
+ * (hueforge P3 exporters, studio bake paths) that today loop the scalar.
+ *
+ * MINDE is ~30x slower than the core packer and stays out of the per-frame
+ * hot path — this batch is a setup-time / bake-time convenience. Zero
+ * allocations (reuses the module-level scratch). In-place is safe when
+ * `inBuf === outBuf` at aligned offsets: each iteration reads its three
+ * source lanes into `_rgb`/`_clipLch` scratch before writing back.
+ *
+ * @param {Float32Array} inBuf - Source OKLCH buffer (stride 3)
+ * @param {number} inOffset - Base offset of the first triplet in inBuf
+ * @param {Float32Array} outBuf - Destination OKLCH buffer (stride 3)
+ * @param {number} outOffset - Base offset of the first triplet in outBuf
+ * @param {number} n - Number of triplets to map (n <= 0 is a no-op)
+ * @returns {void}
+ */
+export function gamutMapToSrgbBufferN(inBuf, inOffset, outBuf, outOffset, n) {
+    if (n <= 0) return;
+    for (let i = 0; i < n; i++) {
+        gamutMapToSrgbBuffer(inBuf, inOffset + i * 3, outBuf, outOffset + i * 3);
+    }
+}
+
+
 // -----------------------------------------------------------------------------
 // packOklchBufferToUint32MINDE
 // -----------------------------------------------------------------------------

package/src/lut.js

@@ -6,11 +6,17 @@ import { lerpOklchBuffer, packOklchBufferToUint32 } from './runtime.js';
  * The output is in little-endian RGBA byte order — drop it directly into a
  * `Uint32Array` view of `Canvas ImageData`, or `texImage2D` with `RGBA / UNSIGNED_BYTE`.
  *
- * Stops are evenly spaced across the gradient (stop _i_ is at `i / (numStops - 1)`).
- * The optional `easeFn` warps the parametric position **before** stop selection,
- * letting you bias which stop dominates which range of the LUT. Easing outputs
- * outside `[0, 1]` are clamped (the LUT is fixed-resolution and cannot
- * represent overshoot).
+ * **Open mode (default):** stop _i_ is at `i / (numStops - 1)`; LUT sample _j_
+ * is at `j / (resolution - 1)`. Sample 0 lands on stop 0, sample `resolution-1`
+ * lands on the last stop. Overshoot from `easeFn` is clamped to `[0, 1]`.
+ *
+ * **Closed mode** (`opts.closed = true`, new in v1.5): stops are treated
+ * cyclically — the wrap segment runs from `stops[numStops-1]` back to
+ * `stops[0]`. Sample _j_ is at `j / resolution` (period spacing, no duplicated
+ * endpoint), so `sample[resolution-1]` sits just before wrapping back to
+ * sample 0. This is the LUT baked by hue-wheel gradients / cyclic colorways —
+ * pair it with `sampleColorLUTWrapped` on the consumer side. `easeFn` outputs
+ * in closed mode are wrapped via `t - floor(t)` (period) instead of clamped.
  *
  * @param {Float32Array} keyframesBuf - Contiguous buffer of `[L0, C0, H0, L1, C1, H1, ...]`
  * @param {number} numStops - Count of color stops in the buffer (must be >= 2)
@@ -19,6 +25,8 @@ import { lerpOklchBuffer, packOklchBufferToUint32 } from './runtime.js';
  * @param {(buf: Float32Array, offset: number, alpha?: number) => number} [packer]
  *        Optional packer override. Defaults to the accurate `packOklchBufferToUint32`.
  *        Pass `packOklchBufferToUint32Fast` for ~2x throughput at the cost of round-trip accuracy.
+ * @param {{ closed?: boolean }} [opts]
+ *        Optional bake options. `closed: true` bakes a cyclic LUT (see above).
  * @returns {Uint32Array} LUT of 32-bit packed colors
  * @throws If `numStops < 2` or `resolution < 2`
  */
@@ -27,7 +35,8 @@ export const bakeGradientToUint32 = (
     numStops,
     resolution = 256,
     easeFn,
-    packer = packOklchBufferToUint32
+    packer = packOklchBufferToUint32,
+    opts
 ) => {
     if (numStops < 2) {
         throw new Error('lite-color-engine: bakeGradientToUint32 requires numStops >= 2');
@@ -36,29 +45,41 @@ export const bakeGradientToUint32 = (
         throw new Error('lite-color-engine: bakeGradientToUint32 requires resolution >= 2');
     }
 
+    const closed = opts != null && opts.closed === true;
     const outLUT = new Uint32Array(resolution);
     const tempOklch = new Float32Array(3);
 
-    const step = 1 / (resolution - 1);
-    const last = numStops - 1;
+    // Open: N-1 segments, samples at i/(res-1), t clamped to [0,1].
+    // Closed: N segments (last wraps last->first), samples at i/res, t period-wrapped.
+    const step = closed ? 1 / resolution : 1 / (resolution - 1);
+    const scale = closed ? numStops : (numStops - 1);
+    const maxIndex = closed ? (numStops - 1) : (numStops - 2);
+    const wrapIndex = numStops - 1; // only meaningful in closed mode
     const hasEase = typeof easeFn === 'function';
 
     for (let i = 0; i < resolution; i++) {
         const rawT = i * step;
         let t = hasEase ? easeFn(rawT) : rawT;
 
-        // LUTs are fixed-resolution; overshoot/undershoot is undefined and
-        // would either NaN-poison the buffer or extrapolate silently.
-        if (t < 0) t = 0;
-        else if (t > 1) t = 1;
+        if (closed) {
+            // Period wrap: `t - floor(t)` maps R to [0, 1). Handles ease overshoot
+            // and negative outputs uniformly; the cyclic contract has no clamp.
+            t = t - Math.floor(t);
+        } else {
+            // LUTs are fixed-resolution; overshoot/undershoot is undefined and
+            // would either NaN-poison the buffer or extrapolate silently.
+            if (t < 0) t = 0;
+            else if (t > 1) t = 1;
+        }
 
-        const scaledT = t * last;
-        let index = scaledT | 0; // bitwise fast-floor for positive values
-        if (index >= last) index = last - 1;
+        const scaledT = t * scale;
+        let index = scaledT | 0; // bitwise fast-floor for non-negative values
+        if (index > maxIndex) index = maxIndex;
 
         const localT = scaledT - index;
         const offsetA = index * 3;
-        const offsetB = offsetA + 3;
+        // Closed mode: the wrap segment (last -> first) reads keyframe 0 as B.
+        const offsetB = (closed && index === wrapIndex) ? 0 : offsetA + 3;
 
         lerpOklchBuffer(keyframesBuf, offsetA, keyframesBuf, offsetB, localT, tempOklch, 0);
         outLUT[i] = packer(tempOklch, 0, 1.0);

package/src/runtime.js

@@ -119,11 +119,23 @@ const _scratchRgbP3 = new Float32Array(3);
  * the exact pow() encoding. One-time module-load cost, then O(1) lookup.
  * @internal
  */
+/**
+ * The sRGB / Display P3 transfer function (IEC 61966-2-1), returning the
+ * gamma-encoded value in [0, 1] rather than a rounded byte. This is the single
+ * definition of the EOTF constants for every encoded-domain caller; the dither
+ * packers need the sub-integer value, so they cannot go through
+ * linearToSrgbByte (which rounds) or SRGB_LUT (which stores rounded bytes).
+ *
+ * @param {number} c - Linear-light channel, already clamped to [0, 1]
+ * @returns {number} Gamma-encoded channel in [0, 1]
+ */
+const srgbEncode = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055);
+
 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;
+        const enc = srgbEncode(c);
         SRGB_LUT[i] = (enc * 255 + 0.5) | 0;
     }
 }
@@ -139,6 +151,133 @@ const linearToSrgbByteLut = (c) => {
     return SRGB_LUT[(c * 4095 + 0.5) | 0];
 };
 
+// -- Blue-noise tile (void-and-cluster, 64x64) -------------------------------
+// Generator: tools/generate-bluenoise.mjs v1.1.0, seed 0xc0ffee1e.
+// SHA-256 of decoded tile: 8867ddb65e16379ad42244fa24b82dcbd813c684ce14944f86a9e3e8f6b72968
+// Histogram: each byte 0..255 appears exactly 16 times (4096/256).
+// Spectral: gated by test/bluenoise-spectral.test.js -- minority-phase clumpiness
+// stays under 0.70 across T=16..240 and is symmetric about T=128, and radial power
+// for r<=4 sits below 0.02 (the white-noise floor is 0.083). The fingerprint above
+// pins a tile that PASSES those gates; it is not a substitute for them.
+// The base64 form is 5464 chars; decoded lazily on first access into a shared,
+// read-only Uint8Array(4096). Do not mutate the returned reference.
+const BLUE_NOISE_64_B64 =
+    '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';
+
+let _blueNoise64 = null;
+/**
+ * Returns the shared 64x64 blue-noise tile as a `Uint8Array(4096)`, decoded
+ * once on first call from an inlined base64 blob and reused thereafter.
+ *
+ * Index a pixel via `tile[(y & 63) << 6 | (x & 63)]`. The tile is torus-tileable:
+ * repeating it end-to-end on either axis is spectrally seamless. Each byte value
+ * 0..255 appears exactly 16 times (uniform histogram, 4096/256), so
+ * `noise01 = byte / 256` gives a low-discrepancy sample in `[0, 1)` that has
+ * exactly the mean and variance of a uniform distribution over 256 buckets.
+ *
+ * The tile is generated by `tools/generate-bluenoise.mjs` (void-and-cluster,
+ * Ulichney 1993) and committed as a base64 blob; decode is sub-millisecond.
+ * The returned reference is shared and must not be mutated; callers that need
+ * to modify the values should copy first.
+ *
+ * @returns {Uint8Array} 4096-entry blue-noise tile (row-major, 64 wide)
+ */
+export const getBlueNoise64 = () => {
+    if (_blueNoise64 !== null) return _blueNoise64;
+    // Node has Buffer; browsers/DOM have atob. Prefer Buffer when available
+    // (faster and does not throw on stray whitespace) and fall back to atob.
+    const b64 = BLUE_NOISE_64_B64;
+    // Read Buffer off globalThis rather than as a free identifier: webpack 4 and
+    // browserify pattern-match the bare `Buffer` token and inject the ~20 KB buffer
+    // polyfill into browser bundles. `globalThis.Buffer` is not matched, so a
+    // browser build stays on the atob path and the package stays zero-cost.
+    const NodeBuffer = globalThis.Buffer;
+    let bytes;
+    if (NodeBuffer !== undefined && typeof NodeBuffer.from === 'function') {
+        const buf = NodeBuffer.from(b64, 'base64');
+        bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    } else {
+        // atob path (browsers / non-Node runtimes)
+        const bin = atob(b64);
+        bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    }
+    // Copy into a stable, standalone Uint8Array (avoids sharing with Buffer's pool)
+    _blueNoise64 = new Uint8Array(bytes);
+    return _blueNoise64;
+};
+
 /**
  * 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
@@ -150,7 +289,7 @@ const linearToSrgbByteLut = (c) => {
 const linearToSrgbByte = (c) => {
     if (c <= 0) return 0;
     if (c >= 1) return 255;
-    const enc = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+    const enc = srgbEncode(c);
     return (enc * 255 + 0.5) | 0;
 };
 
@@ -204,6 +343,48 @@ export const packOklchBufferToUint32Fast = (buf, offset, alpha = 1.0) => {
     return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
 };
 
+/**
+ * Dithered sibling of {@link packOklchBufferToUint32}. Applies a threshold-
+ * offset dither in gamma-encoded space using a caller-supplied `noise01` value.
+ *
+ * The same `noise01` is applied to all three color channels (R, G, B) so the
+ * dither is a **luminance pattern** — no chroma speckle. Alpha is undithered.
+ *
+ * Parity guarantee: when `noise01 === 0.5`, this returns the exact same 32-bit
+ * value as {@link packOklchBufferToUint32} for the same inputs (the round-half
+ * behavior collapses into the identical `floor(enc*255 + 0.5)` expression).
+ * This is asserted by the test suite.
+ *
+ * The `noise01` argument is expected to be in `[0, 1)`; values >= 1 will be
+ * folded to 255 by the byte clamp. When indexing the shared blue-noise tile,
+ * derive it as `noiseTile[(y & 63) << 6 | (x & 63)] / 256` — this yields
+ * values in `[0, 255/256]` and never overflows a byte.
+ *
+ * Both trailing arguments default so that a call with the plain packer's arity
+ * behaves like the plain packer instead of silently producing transparent black:
+ * `packOklchBufferToUint32Dithered(buf, off)` === `packOklchBufferToUint32(buf, off)`.
+ *
+ * @param {Float32Array} buf - Buffer containing the OKLCH triplet
+ * @param {number} offset - Start index in the buffer
+ * @param {number} [alpha=1.0] - Alpha [0, 1]; values outside the range are clamped
+ * @param {number} [noise01=0.5] - Dither threshold offset in `[0, 1)`; 0.5 = no dither
+ * @returns {number} 32-bit unsigned integer (little-endian RGBA byte order)
+ */
+export const packOklchBufferToUint32Dithered = (buf, offset, alpha = 1.0, noise01 = 0.5) => {
+    oklchToLinearSrgbClamped(buf[offset], buf[offset + 1], buf[offset + 2], _scratchRgb);
+    const cr = _scratchRgb[0], cg = _scratchRgb[1], cb = _scratchRgb[2];
+    // Gamma-encode (mirrors linearToSrgbByte but without the final *255-round step)
+    const encR = srgbEncode(cr);
+    const encG = srgbEncode(cg);
+    const encB = srgbEncode(cb);
+    // Shared noise offset per pixel; floor via `| 0` (safe for non-negative values).
+    let r8 = (encR * 255 + noise01) | 0; if (r8 > 255) r8 = 255;
+    let g8 = (encG * 255 + noise01) | 0; if (g8 > 255) g8 = 255;
+    let b8 = (encB * 255 + noise01) | 0; if (b8 > 255) b8 = 255;
+    const a8 = alpha <= 0 ? 0 : (alpha >= 1 ? 255 : (alpha * 255 + 0.5) | 0);
+    return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+};
+
 /**
  * Batch sibling of {@link packOklchBufferToUint32}. Packs `n` OKLCH triplets
  * (stride 3, from `src`) into `n` consecutive Uint32 pixels (stride 1, into
@@ -250,6 +431,74 @@ export const packOklchBufferToUint32IntoN = (src, offSrc, dst, offDst, n, alpha
     }
 };
 
+/**
+ * Batch dithered sibling of {@link packOklchBufferToUint32IntoN}. Packs `n`
+ * OKLCH triplets into `n` Uint32 pixels while walking a 64x64 blue-noise tile
+ * in row-major order, applying a per-pixel luminance-patterned threshold
+ * dither (same noise value across R/G/B; alpha undithered).
+ *
+ * Pixel `i` in the batch is treated as destination position `(x0 + col, y0 + row)`,
+ * where `col = i % rowWidth` and `row = (i / rowWidth) | 0`. The tile is indexed
+ * torus-style: `tile[((y & 63) << 6) | (x & 63)]`, so any `x0`/`y0`/`rowWidth`
+ * combination is safe — the tile just wraps.
+ *
+ * The dither is applied in gamma-encoded space so it perturbs perceptual (not
+ * linear) intensity — visually correct on 8-bit sRGB displays.
+ *
+ * **On useLut:** the non-dithered batch (`packOklchBufferToUint32IntoN`) has a
+ * `useLut` flag that swaps the exact `pow()` transfer for the 4k LUT. That LUT
+ * stores *rounded bytes*, which discards the sub-integer information the
+ * dither threshold needs. Enabling it here would silently degrade dither to
+ * plain rounding. A future v1.6 candidate is a companion `Float32Array` LUT
+ * of encoded floats (~16 KB) that would restore this axis; deferred to keep
+ * v1.5 surface tight. This function therefore uses the exact encoder only.
+ *
+ * Zero allocations; the tile-walk state is a pair of integer locals, no modulo
+ * or division in the hot loop.
+ *
+ * @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 - Shared alpha [0, 1] for all n colors
+ * @param {Uint8Array} noiseTile - 64x64 blue-noise tile (from {@link getBlueNoise64})
+ * @param {number} x0 - Starting destination column
+ * @param {number} y0 - Starting destination row
+ * @param {number} rowWidth - Pixels per destination row (wrap point for column)
+ * @returns {void}
+ */
+export const packOklchBufferToUint32IntoNDithered = (
+    src, offSrc, dst, offDst, n, alpha, noiseTile, x0, y0, rowWidth
+) => {
+    if (n <= 0) return;
+    const a8 = alpha <= 0 ? 0 : (alpha >= 1 ? 255 : (alpha * 255 + 0.5) | 0);
+    const aHi = a8 << 24;
+    const NOISE_SCALE = 1 / 256;
+    const startCol = x0 | 0;
+    const wrapAt = startCol + (rowWidth | 0);
+    let px = startCol, py = y0 | 0;
+
+    for (let i = 0; i < n; i++) {
+        const io = offSrc + i * 3;
+        oklchToLinearSrgbClamped(src[io], src[io + 1], src[io + 2], _scratchRgb);
+        // Blue-noise sample, torus-indexed
+        const noise01 = noiseTile[((py & 63) << 6) | (px & 63)] * NOISE_SCALE;
+        // Exact gamma encode; shared noise offset across R/G/B (luminance dither)
+        const cr = _scratchRgb[0], cg = _scratchRgb[1], cb = _scratchRgb[2];
+        const encR = srgbEncode(cr);
+        const encG = srgbEncode(cg);
+        const encB = srgbEncode(cb);
+        let r8 = (encR * 255 + noise01) | 0; if (r8 > 255) r8 = 255;
+        let g8 = (encG * 255 + noise01) | 0; if (g8 > 255) g8 = 255;
+        let b8 = (encB * 255 + noise01) | 0; if (b8 > 255) b8 = 255;
+        dst[offDst + i] = (aHi | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+        // Advance pixel position; wrap column at row edge
+        px++;
+        if (px === wrapAt) { px = startCol; py++; }
+    }
+};
+
 /**
  * Internal helper: OKLCH -> linear Display P3 with hard clamp to [0, 1].
  * Mirrors oklchToLinearSrgbClamped but targets the wider P3 gamut.
@@ -307,6 +556,52 @@ export const packOklchBufferToUint32P3Fast = (buf, offset, alpha = 1.0) => {
     return ((a8 << 24) | (b8 << 16) | (g8 << 8) | r8) >>> 0;
 };
 
+/**
+ * Batch sibling of {@link packOklchBufferToUint32P3}. Packs `n` OKLCH triplets
+ * (stride 3) into `n` consecutive Uint32 pixels encoded for **Display P3**.
+ *
+ * With `useLut=false` the output is bit-for-bit identical to calling
+ * {@link packOklchBufferToUint32P3} n times. With `useLut=true` it uses the
+ * shared 4k transfer LUT (the P3 transfer function is identical to sRGB per
+ * IEC 61966-2-1, so no separate table is allocated). Near-exact within ~1 LSB
+ * at close to fast-packer throughput; 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 transfer LUT (near-exact, faster)
+ * @returns {void}
+ */
+export const packOklchBufferToUint32P3IntoN = (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;
+            oklchToLinearP3Clamped(src[io], src[io + 1], src[io + 2], _scratchRgbP3);
+            const r8 = linearToSrgbByteLut(_scratchRgbP3[0]);
+            const g8 = linearToSrgbByteLut(_scratchRgbP3[1]);
+            const b8 = linearToSrgbByteLut(_scratchRgbP3[2]);
+            dst[offDst + i] = (aHi | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+        }
+    } else {
+        for (let i = 0; i < n; i++) {
+            const io = offSrc + i * 3;
+            oklchToLinearP3Clamped(src[io], src[io + 1], src[io + 2], _scratchRgbP3);
+            const r8 = linearToSrgbByte(_scratchRgbP3[0]);
+            const g8 = linearToSrgbByte(_scratchRgbP3[1]);
+            const b8 = linearToSrgbByte(_scratchRgbP3[2]);
+            dst[offDst + i] = (aHi | (b8 << 16) | (g8 << 8) | r8) >>> 0;
+        }
+    }
+};
+
 /**
  * Zero-GC LUT sampler. Looks up a baked gradient color by `t` in [0, 1].
  *