@zakkster/lite-color-engine 1.0.0

package/llms.txt

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@zakkster/lite-color-engine",
+  "version": "1.0.0",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "description": "Zero-GC, data-oriented OKLCH color engine and WebGL/Canvas buffer pipeline.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "index.d.ts",
+      "import": "index.js",
+      "default": "index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "llms.txt",
+    "LICENSE.txt"
+  ],
+  "keywords": [
+    "color",
+    "oklch",
+    "oklab",
+    "zero-gc",
+    "webgl",
+    "canvas",
+    "lut",
+    "interpolation",
+    "gradient",
+    "color-space",
+    "dod",
+    "data-oriented",
+    "high-performance",
+    "game-dev"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zakkster/lite-lerp": "^1.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0"
+  },
+  "license": "Mit",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-color-engine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-color-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-color-engine/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/authoring.js

@@ -0,0 +1,262 @@
+import { sRgbToOklchBuffer } from './convert.js';
+
+const RAD_TO_DEG = 180 / Math.PI;
+
+// ============================================================================
+// 1. UTILITIES
+// ============================================================================
+
+/**
+ * Parses a CSS numeric token. `'50%'` -> `0.5 * max`. `'50'` -> `50`. `''` / undefined -> undefined.
+ * @internal
+ */
+const parseVal = (val, max = 1) => {
+    if (val === undefined || val === null || val === '') return undefined;
+    return val.endsWith('%') ? (parseFloat(val) / 100) * max : parseFloat(val);
+};
+
+/**
+ * Parses a CSS hue token, accepting `deg` (default), `rad`, and `turn` units.
+ * Result is canonicalized to [0, 360).
+ * @internal
+ */
+const parseHue = (val) => {
+    let h = parseFloat(val);
+    if (val.includes('rad')) h *= RAD_TO_DEG;
+    if (val.includes('turn')) h *= 360;
+    const m = h % 360;
+    return m < 0 ? m + 360 : m;
+};
+
+/**
+ * Reference HSL -> sRGB conversion. Used as a stepping stone before sRGB -> OKLCH.
+ * @internal
+ */
+const hslToRgb = (h, s, l) => {
+    h /= 360;
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const hue2rgb = (p, q, t) => {
+        if (t < 0) t += 1;
+        if (t > 1) t -= 1;
+        if (t < 1 / 6) return p + (q - p) * 6 * t;
+        if (t < 1 / 2) return q;
+        if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    return [
+        (hue2rgb(p, q, h + 1 / 3) * 255 + 0.5) | 0,
+        (hue2rgb(p, q, h) * 255 + 0.5) | 0,
+        (hue2rgb(p, q, h - 1 / 3) * 255 + 0.5) | 0
+    ];
+};
+
+// ============================================================================
+// 2. REGEX DICTIONARY (CSS Color Level 4 Permissive)
+// ============================================================================
+
+const HEX_REGEX = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i;
+const SHORT_HEX_REGEX = /^#([a-f\d])([a-f\d])([a-f\d])([a-f\d])?$/i;
+const OKLCH_REGEX = /^oklch\(\s*([\d.%]+)\s+([\d.%]+)\s+([\d.%a-z]+)(?:\s*\/\s*([\d.%]+))?\s*\)$/i;
+const OKLAB_REGEX = /^oklab\(\s*([\d.%]+)[,\s]+([\d.-]+)[,\s]+([\d.-]+)(?:[,\s/]+([\d.%]+))?\s*\)$/i;
+const RGB_REGEX = /^rgba?\(\s*([\d.%]+)[,\s]+([\d.%]+)[,\s]+([\d.%]+)(?:(?:,|\s*\/\s*)\s*([\d.%]+))?\s*\)$/i;
+const HSL_REGEX = /^hsla?\(\s*([\d.%a-z]+)[,\s]+([\d.%]+)[,\s]+([\d.%]+)(?:(?:,|\s*\/\s*)\s*([\d.%]+))?\s*\)$/i;
+
+// ============================================================================
+// 3. NAMED COLORS FAST-PATH
+// ============================================================================
+
+/** CSS Color Module Level 4 named-color table. Single allocation at module load. */
+const NAMED_COLORS = {
+    aliceblue: '#f0f8ff', antiquewhite: '#faebd7', aqua: '#00ffff', aquamarine: '#7fffd4',
+    azure: '#f0ffff', beige: '#f5f5dc', bisque: '#ffe4c4', black: '#000000',
+    blanchedalmond: '#ffebcd', blue: '#0000ff', blueviolet: '#8a2be2', brown: '#a52a2a',
+    burlywood: '#deb887', cadetblue: '#5f9ea0', chartreuse: '#7fff00', chocolate: '#d2691e',
+    coral: '#ff7f50', cornflowerblue: '#6495ed', cornsilk: '#fff8dc', crimson: '#dc143c',
+    cyan: '#00ffff', darkblue: '#00008b', darkcyan: '#008b8b', darkgoldenrod: '#b8860b',
+    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', 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',
+    goldenrod: '#daa520', gray: '#808080', green: '#008000', greenyellow: '#adff2f',
+    grey: '#808080', honeydew: '#f0fff0', hotpink: '#ff69b4', indianred: '#cd5c5c',
+    indigo: '#4b0082', ivory: '#fffff0', khaki: '#f0e68c', lavender: '#e6e6fa',
+    lavenderblush: '#fff0f5', lawngreen: '#7cfc00', lemonchiffon: '#fffacd', lightblue: '#add8e6',
+    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: '#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',
+    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',
+    plum: '#dda0dd', powderblue: '#b0e0e6', purple: '#800080', rebeccapurple: '#663399',
+    red: '#ff0000', rosybrown: '#bc8f8f', royalblue: '#4169e1', saddlebrown: '#8b4513',
+    salmon: '#fa8072', sandybrown: '#f4a460', seagreen: '#2e8b57', seashell: '#fff5ee',
+    sienna: '#a0522d', silver: '#c0c0c0', skyblue: '#87ceeb', slateblue: '#6a5acd',
+    slategray: '#708090', slategrey: '#708090', snow: '#fffafa', springgreen: '#00ff7f',
+    steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080', thistle: '#d8bfd8',
+    tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee', wheat: '#f5deb3',
+    white: '#ffffff', whitesmoke: '#f5f5f5', yellow: '#ffff00', yellowgreen: '#9acd32',
+    transparent: '#00000000'
+};
+
+// ============================================================================
+// 4. PARSERS
+// ============================================================================
+
+/**
+ * Parses a CSS hex string (`#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`) into an
+ * OKLCH triplet at `outBuf[offset..offset+2]`.
+ *
+ * @param {string} str - The hex string (with leading `#`)
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` is not a valid hex literal.
+ */
+export const parseHexToBuffer = (str, outBuf, offset) => {
+    let match = str.match(HEX_REGEX);
+    if (!match) {
+        match = str.match(SHORT_HEX_REGEX);
+        if (!match) throw new Error(`lite-color-engine: Invalid HEX "${str}"`);
+        match = [
+            match[0], match[1] + match[1], match[2] + match[2],
+            match[3] + match[3], match[4] ? match[4] + match[4] : undefined
+        ];
+    }
+    sRgbToOklchBuffer(parseInt(match[1], 16), parseInt(match[2], 16), parseInt(match[3], 16), outBuf, offset);
+    return match[4] ? parseInt(match[4], 16) / 255 : 1.0;
+};
+
+/**
+ * Parses a CSS `oklch()` string directly into an OKLCH triplet — no color-space
+ * conversion needed.
+ *
+ * Accepts the modern slash-alpha form: `oklch(60% 0.15 250 / 0.5)`. Hue may
+ * carry a `deg`, `rad`, or `turn` unit.
+ *
+ * @param {string} str - The `oklch(...)` string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` does not match `oklch(...)`.
+ */
+export const parseOklchToBuffer = (str, outBuf, offset) => {
+    const match = str.match(OKLCH_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid OKLCH "${str}"`);
+    outBuf[offset] = parseVal(match[1], 1);
+    outBuf[offset + 1] = parseVal(match[2], 1);
+    outBuf[offset + 2] = parseHue(match[3]);
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
+/**
+ * Parses a CSS `oklab()` string and converts (a, b) -> (C, H) via polar math
+ * before writing the OKLCH triplet.
+ *
+ * @param {string} str - The `oklab(...)` string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` does not match `oklab(...)`.
+ */
+export const parseOklabToBuffer = (str, outBuf, offset) => {
+    const match = str.match(OKLAB_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid OKLAB "${str}"`);
+    const l = parseVal(match[1], 1);
+    const a = parseFloat(match[2]);
+    const b = parseFloat(match[3]);
+    const c = Math.sqrt(a * a + b * b);
+
+    outBuf[offset] = l < 0 ? 0 : (l > 1 ? 1 : l);
+    outBuf[offset + 1] = c || 0;
+    let h = Math.atan2(b, a) * RAD_TO_DEG;
+    if (h < 0) h += 360;
+    outBuf[offset + 2] = h;
+
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
+/**
+ * Parses a CSS `rgb()` / `rgba()` string and converts to OKLCH.
+ *
+ * Accepts comma-separated and modern slash-alpha forms, with `0-255` or `%`
+ * channel values. Conversion uses the proper sRGB linearization.
+ *
+ * @param {string} str - The `rgb(...)` / `rgba(...)` string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` does not match `rgb(...)` / `rgba(...)`.
+ */
+export const parseRgbToBuffer = (str, outBuf, offset) => {
+    const match = str.match(RGB_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid RGB "${str}"`);
+    sRgbToOklchBuffer(parseVal(match[1], 255), parseVal(match[2], 255), parseVal(match[3], 255), outBuf, offset);
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
+/**
+ * Parses a CSS `hsl()` / `hsla()` string, converts via sRGB, and writes the
+ * OKLCH triplet.
+ *
+ * @param {string} str - The `hsl(...)` / `hsla(...)` string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]; defaults to `1.0` when omitted.
+ * @throws If `str` does not match `hsl(...)` / `hsla(...)`.
+ */
+export const parseHslToBuffer = (str, outBuf, offset) => {
+    const match = str.match(HSL_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid HSL "${str}"`);
+    const [r, g, b] = hslToRgb(parseHue(match[1]), parseVal(match[2], 1), parseVal(match[3], 1));
+    sRgbToOklchBuffer(r, g, b, outBuf, offset);
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
+// ============================================================================
+// 5. MASTER SWITCHBOARD
+// ============================================================================
+
+/**
+ * Universal CSS color parser. Dispatches by string prefix to the appropriate
+ * format-specific parser and writes an OKLCH triplet.
+ *
+ * Supports: named colors, `#RGB[A]`, `#RRGGBB[AA]`, `rgb()` / `rgba()`,
+ * `hsl()` / `hsla()`, `oklch()`, `oklab()`.
+ *
+ * Intended for the **authoring/init phase** of a render pipeline (level loads,
+ * theme parsing, gradient compilation). After that, work with the resulting
+ * `Float32Array` buffer directly via {@link lerpOklchBuffer} and
+ * {@link packOklchBufferToUint32}.
+ *
+ * @param {string} str - The CSS color string
+ * @param {Float32Array} outBuf - Pre-allocated destination
+ * @param {number} offset - Start index of the L, C, H triplet
+ * @returns {number} Parsed alpha in [0, 1]
+ * @throws If `str` is not a recognized format
+ */
+export const parseCSSColor = (str, outBuf, offset) => {
+    const cleanStr = str.trim().toLowerCase();
+
+    const named = NAMED_COLORS[cleanStr];
+    if (named) {
+        return parseHexToBuffer(named, outBuf, offset);
+    }
+
+    if (cleanStr.startsWith('#')) return parseHexToBuffer(cleanStr, outBuf, offset);
+    if (cleanStr.startsWith('oklch')) return parseOklchToBuffer(cleanStr, outBuf, offset);
+    if (cleanStr.startsWith('oklab')) return parseOklabToBuffer(cleanStr, outBuf, offset);
+    if (cleanStr.startsWith('rgb')) return parseRgbToBuffer(cleanStr, outBuf, offset);
+    if (cleanStr.startsWith('hsl')) return parseHslToBuffer(cleanStr, outBuf, offset);
+
+    throw new Error(`lite-color-engine: Unsupported color format "${str}".`);
+};

package/src/convert.js

@@ -0,0 +1,58 @@
+const RAD_TO_DEG = 180 / Math.PI;
+
+/**
+ * IEC 61966-2-1 sRGB linearization.
+ * @param {number} c - Normalized non-linear sRGB channel in [0, 1]
+ * @returns {number} Linear-light value in [0, 1]
+ * @internal
+ */
+const linearize = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+
+/**
+ * Converts standard sRGB (0-255 byte channels) into a flat OKLCH buffer.
+ *
+ * Defends against negative floating-point cube roots (numerical noise from the
+ * matrix multiply) and hard-clamps output lightness to [0, 1]. Hue is
+ * canonicalized to [0, 360).
+ *
+ * Algorithm: Björn Ottosson's OKLab (2020) — sRGB -> linear sRGB -> LMS ->
+ * non-linear LMS (cube root) -> OKLab -> polar OKLCH.
+ *
+ * @param {number} r - Red channel [0, 255]
+ * @param {number} g - Green channel [0, 255]
+ * @param {number} b - Blue channel [0, 255]
+ * @param {Float32Array} outBuf - Destination buffer
+ * @param {number} outOffset - Start index for the L, C, H triplet
+ * @returns {void}
+ */
+export const sRgbToOklchBuffer = (r, g, b, outBuf, outOffset) => {
+    // 1. Normalize and linearize.
+    const r_lin = linearize(r / 255);
+    const g_lin = linearize(g / 255);
+    const b_lin = linearize(b / 255);
+
+    // 2. Linear sRGB -> linear LMS.
+    const lms_l = 0.4122214708 * r_lin + 0.5363325363 * g_lin + 0.0514459929 * b_lin;
+    const lms_m = 0.2119034982 * r_lin + 0.6806995451 * g_lin + 0.1073969566 * b_lin;
+    const lms_s = 0.0883024619 * r_lin + 0.2817188376 * g_lin + 0.6299787005 * b_lin;
+
+    // 3. Non-linear LMS (defended against negative-NaN propagation from matrix noise).
+    const l_ = Math.cbrt(lms_l < 0 ? 0 : lms_l);
+    const m_ = Math.cbrt(lms_m < 0 ? 0 : lms_m);
+    const s_ = Math.cbrt(lms_s < 0 ? 0 : lms_s);
+
+    // 4. Non-linear LMS -> OKLab.
+    const lab_l = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+    const lab_a = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    const lab_b = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+
+    // 5. OKLab -> OKLCH (polar).
+    const chroma = Math.sqrt(lab_a * lab_a + lab_b * lab_b);
+    let hue = Math.atan2(lab_b, lab_a) * RAD_TO_DEG;
+    if (hue < 0) hue += 360;
+
+    // 6. Write to buffer with a strict lightness clamp.
+    outBuf[outOffset] = lab_l < 0 ? 0 : (lab_l > 1 ? 1 : lab_l);
+    outBuf[outOffset + 1] = chroma;
+    outBuf[outOffset + 2] = hue;
+};

package/src/lut.js

@@ -0,0 +1,68 @@
+import { lerpOklchBuffer, packOklchBufferToUint32 } from './runtime.js';
+
+/**
+ * Bakes a multi-stop OKLCH gradient into a ready-to-render `Uint32Array`.
+ *
+ * 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).
+ *
+ * @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)
+ * @param {number} [resolution=256] - Number of LUT entries to bake (must be >= 2)
+ * @param {(t: number) => number} [easeFn] - Optional easing applied to `t` before stop selection
+ * @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.
+ * @returns {Uint32Array} LUT of 32-bit packed colors
+ * @throws If `numStops < 2` or `resolution < 2`
+ */
+export const bakeGradientToUint32 = (
+    keyframesBuf,
+    numStops,
+    resolution = 256,
+    easeFn,
+    packer = packOklchBufferToUint32
+) => {
+    if (numStops < 2) {
+        throw new Error('lite-color-engine: bakeGradientToUint32 requires numStops >= 2');
+    }
+    if (resolution < 2) {
+        throw new Error('lite-color-engine: bakeGradientToUint32 requires resolution >= 2');
+    }
+
+    const outLUT = new Uint32Array(resolution);
+    const tempOklch = new Float32Array(3);
+
+    const step = 1 / (resolution - 1);
+    const last = numStops - 1;
+    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;
+
+        const scaledT = t * last;
+        let index = scaledT | 0; // bitwise fast-floor for positive values
+        if (index >= last) index = last - 1;
+
+        const localT = scaledT - index;
+        const offsetA = index * 3;
+        const offsetB = offsetA + 3;
+
+        lerpOklchBuffer(keyframesBuf, offsetA, keyframesBuf, offsetB, localT, tempOklch, 0);
+        outLUT[i] = packer(tempOklch, 0, 1.0);
+    }
+
+    return outLUT;
+};