@zakkster/lite-color-engine 1.3.0 → 1.5.0

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)
 // ============================================================================
@@ -212,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.
@@ -226,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
@@ -259,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.
  *
@@ -281,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`.
@@ -293,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(
@@ -300,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

@@ -5,7 +5,9 @@ export {
     parseOklabToBuffer,
     parseOklchToBuffer,
     parseRgbToBuffer,
-    parseDisplayP3ToBuffer
+    parseDisplayP3ToBuffer,
+    formatOklchCss,
+    formatHex
 } from './src/authoring.js';
 
 export { bakeGradientToUint32 } from './src/lut.js';
@@ -15,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.3)
+# lite-color-engine - LLM Reference (v1.5)
 
 ## Core Exports
 
@@ -6,29 +6,60 @@
 - `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
+- `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.3.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/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/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);