@zakkster/lite-color-engine 1.1.0 → 1.2.0

package/index.d.ts

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

package/index.js

@@ -4,7 +4,8 @@ export {
     parseHslToBuffer,
     parseOklabToBuffer,
     parseOklchToBuffer,
-    parseRgbToBuffer
+    parseRgbToBuffer,
+    parseDisplayP3ToBuffer
 } from './src/authoring.js';
 
 export { bakeGradientToUint32 } from './src/lut.js';
@@ -13,9 +14,15 @@ export {
     lerpOklchBuffer,
     packOklchBufferToUint32,
     packOklchBufferToUint32Fast,
+    packOklchBufferToUint32P3,
+    packOklchBufferToUint32P3Fast,
     sampleColorLUT
 } from './src/runtime.js';
 
-export { sRgbToOklchBuffer } from './src/convert.js';
+export {
+    sRgbToOklchBuffer,
+    displayP3ToOklchBuffer,
+    oklchToLinearP3
+} from './src/convert.js';
 
 export { deltaEOK } from './src/delta.js';

package/llms.txt

@@ -1,275 +1,38 @@
-# @zakkster/lite-color-engine — LLM Reference
+# lite-color-engine — LLM Reference (v1.2)
 
-> 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).
+## Core Exports
 
-## Identity
+### Parsing
+- `parseCSSColor(str, outBuf, offset)` — Universal parser. Now supports `color(display-p3 r g b / alpha)`
+- `parseDisplayP3ToBuffer(str, outBuf, offset)` — Direct P3 parser
 
-- **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`
+### Conversion
+- `sRgbToOklchBuffer(r, g, b, out, off)`
+- `displayP3ToOklchBuffer(r, g, b, out, off)` — New in v1.2
+- `oklchToLinearP3(L, C, H, out)` — Inverse for P3 packing
 
-## Mental model
+### Runtime (Hot Path — Zero GC)
+- `lerpOklchBuffer(...)`
+- `packOklchBufferToUint32(buf, off, alpha?)` — Accurate sRGB
+- `packOklchBufferToUint32Fast(...)` — Fast approx
+- `packOklchBufferToUint32P3(buf, off, alpha?)` — Accurate P3 output
+- `packOklchBufferToUint32P3Fast(...)` — Fast P3 output
 
-Every color in this library is exactly **3 contiguous Float32 entries** in a `Float32Array`: `[L, C, H]`.
+### 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.
 
-- `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.
+### LUT
+- `bakeGradientToUint32(..., packer?)` — Accepts any of the above packers
 
-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).
+## Key Principles
+- All hot-path functions are allocation-free
+- P3 is strictly opt-in
+- Use `Float32Array` buffers for everything
+- Prefer `parse*ToBuffer` at init time
 
-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.
+## Accuracy Tiers (v1.2)
+1. Fast
+2. Accurate-Clamp (default)
+3. Gamut-Mapped (MINDE)
 
-## Public API surface
-
-### Authoring (init-time, allocations OK)
-
-```js
-import {
-    parseCSSColor,
-    parseHexToBuffer,
-    parseRgbToBuffer,
-    parseHslToBuffer,
-    parseOklchToBuffer,
-    parseOklabToBuffer,
-} from '@zakkster/lite-color-engine';
-```
-
-All five format-specific parsers and `parseCSSColor` have the same signature:
-
-```ts
-(str: string, outBuf: Float32Array, offset: number) => number /* alpha [0,1] */
-```
-
-`parseCSSColor` dispatches by string prefix. Use it unless you know the format and care about shaving the dispatch.
-
-Throws on invalid input.
-
-### Convert (raw math)
-
-```js
-import { sRgbToOklchBuffer } from '@zakkster/lite-color-engine';
-
-sRgbToOklchBuffer(r, g, b, outBuf, outOffset);
-// r, g, b are 0-255 bytes. Writes 3 floats to outBuf.
-```
-
-### Runtime (zero allocations)
-
-```js
-import {
-    lerpOklchBuffer,
-    packOklchBufferToUint32,
-    packOklchBufferToUint32Fast,
-    sampleColorLUT,
-} from '@zakkster/lite-color-engine';
-```
-
-Signatures:
-
-```ts
-lerpOklchBuffer(
-    bufA: Float32Array, offsetA: number,
-    bufB: Float32Array, offsetB: number,
-    t: number,
-    outBuf: Float32Array, outOffset: number
-): void;
-
-packOklchBufferToUint32(buf: Float32Array, offset: number, alpha?: number): number;
-packOklchBufferToUint32Fast(buf: Float32Array, offset: number, alpha?: number): number;
-
-sampleColorLUT(lut: Uint32Array, t: number): number;
-```
-
-### Difference (ΔE-OK)
-
-```js
-import { deltaEOK } from '@zakkster/lite-color-engine';
-
-deltaEOK(bufA: Float32Array, offsetA: number,
-         bufB: Float32Array, offsetB: number): number;
-```
-
-Euclidean distance in OKLab between two buffered OKLCH colors. Zero allocations. Typical scale: `0.02` indistinguishable, `0.05` subtle, `0.15+` unambiguously different.
-
-### Gamut sub-export (`/gamut`)
-
-```js
-import {
-    gamutMapToSrgbBuffer,
-    packOklchBufferToUint32MINDE,
-} from '@zakkster/lite-color-engine/gamut';
-
-gamutMapToSrgbBuffer(
-    inBuf: Float32Array, inOffset: number,
-    outBuf: Float32Array, outOffset: number
-): void;
-
-packOklchBufferToUint32MINDE(
-    buf: Float32Array, offset: number, alpha?: number
-): number;
-```
-
-CSS Color 4 MINDE chroma-reduction gamut mapping. Bisection on chroma at fixed L and H with a JND threshold. `packOklchBufferToUint32MINDE` is signature-compatible with the core packer, so you can pass it directly as the `packer` argument to `bakeGradientToUint32` to bake gamut-accurate LUTs.
-
-~30× slower than the core packer. Belongs at LUT-build or authoring time, not per-frame.
-
-### Remap sub-export (`/remap`)
-
-```js
-import {
-    sRgba8ToOklabBuffer,
-    oklchToOklabBuffer,
-    oklabToOklchBuffer,
-    nearestPaletteIndexBuffer,
-    remapPixelsToPalette,
-} from '@zakkster/lite-color-engine/remap';
-
-sRgba8ToOklabBuffer(
-    inU8: Uint8Array | Uint8ClampedArray,
-    outLab: Float32Array, pixelCount: number
-): void;
-
-oklchToOklabBuffer(inLch: Float32Array, outLab: Float32Array, pixelCount: number): void;
-oklabToOklchBuffer(inLab: Float32Array, outLch: Float32Array, pixelCount: number): void;
-
-nearestPaletteIndexBuffer(
-    pixelsLab: Float32Array, paletteLab: Float32Array,
-    indicesOut: Uint32Array | Uint16Array | Uint8Array,
-    pixelCount: number, paletteCount: number,
-    opts?: { preserveLightness?: boolean }
-): void;
-
-remapPixelsToPalette(
-    inU8: Uint8Array | Uint8ClampedArray,
-    paletteLch: Float32Array,
-    outU32: Uint32Array,
-    pixelCount: number, paletteCount: number,
-    opts?: { preserveLightness?: boolean }
-): void;
-```
-
-SoA palette-remap kernels. Search happens in OKLab (Euclidean distance). Palette is authored in OKLCH and converted to OKLab once per call. `remapPixelsToPalette` uses grow-only module-level scratch for the palette conversion — no per-frame allocation. Alpha byte from the input passes through unchanged in the output. `preserveLightness` searches by `(a, b)` only and synthesizes output as `(pixel.L, palette.a, palette.b)` — retains shading structure under recolor.
-
-### LUT (gradient baking)
-
-```js
-import { bakeGradientToUint32 } from '@zakkster/lite-color-engine';
-
-bakeGradientToUint32(
-    keyframesBuf: Float32Array,         // [L0,C0,H0, L1,C1,H1, ...]
-    numStops: number,                   // >= 2
-    resolution?: number,                // default 256, >= 2
-    easeFn?: (t: number) => number,
-    packer?: (buf: Float32Array, offset: number, alpha?: number) => number
-): Uint32Array;
-```
-
-## Integration patterns
-
-### Pattern 1 — palette load
-
-```js
-const palette = new Float32Array(3 * COLOR_COUNT);
-const alphas  = new Float32Array(COLOR_COUNT);
-for (let i = 0; i < cssStrings.length; i++) {
-    alphas[i] = parseCSSColor(cssStrings[i], palette, i * 3);
-}
-// palette is now your color storage for the program lifetime.
-```
-
-### Pattern 2 — per-frame tween
-
-```js
-const scratch = new Float32Array(3);   // module-level, allocated ONCE
-
-function frame(t) {
-    lerpOklchBuffer(palette, 0, palette, 3, t, scratch, 0);
-    return packOklchBufferToUint32(scratch, 0, 1.0);
-}
-```
-
-### Pattern 3 — gradient LUT for a particle system
-
-```js
-const stops = new Float32Array(9);
-parseCSSColor('#ff0000', stops, 0);
-parseCSSColor('#ffd700', stops, 3);
-parseCSSColor('#00aaff', stops, 6);
-
-const lut = bakeGradientToUint32(stops, 3, 256);
-
-// In the render loop:
-for (let i = 0; i < particles.count; i++) {
-    const lifeT = particles.life[i];
-    pixels32[particles.pixelIdx[i]] = sampleColorLUT(lut, lifeT);
-}
-```
-
-### Pattern 4 — direct ImageData write
-
-```js
-const imgData = ctx.createImageData(width, height);
-const pixels  = new Uint32Array(imgData.data.buffer);  // RGBA-LE view
-
-for (let i = 0; i < pixels.length; i++) {
-    pixels[i] = sampleColorLUT(lut, i / pixels.length);
-}
-ctx.putImageData(imgData, 0, 0);
-```
-
-## Invariants the library guarantees
-
-- After any successful write, `outBuf[offset + 2]` (hue) is in `[0, 360)`.
-- After any successful write, `outBuf[offset]` (lightness) is in `[0, 1]`.
-- After any successful write, `outBuf[offset + 1]` (chroma) is in `[0, +∞)`.
-- `packOklchBufferToUint32` and `packOklchBufferToUint32Fast` return values that are **always** non-negative integers (they apply `>>> 0`).
-- Hue interpolation is **always** shortest-path (uses `lerpAngle` from `@zakkster/lite-lerp`).
-- Bake output bytes are **always** little-endian RGBA. Same on every browser.
-
-## Common pitfalls
-
-- **Mistaking the byte order.** The pack functions return little-endian RGBA, so on x86 the low byte is R. If you mask with `(packed >> 24) & 0xff` expecting red, you'll get alpha. Use `packed & 0xff` for red.
-
-- **Storing per-color objects anyway.** The library is explicitly buffer-first. If you find yourself writing `{ l, c, h }` wrappers, you've reintroduced GC pressure; just use the offset-based API.
-
-- **Choosing the Fast packer for UI.** `packOklchBufferToUint32Fast` darkens mid-tones by ~10/255 and shifts warm midtones toward black. Use it for transient pixels (particle trails, alpha-blended sprites). Use the accurate variant for anything a designer or QA might compare against the source color.
-
-- **Using non-monotonic eases with the LUT.** `bakeGradientToUint32` clamps eased `t` to `[0, 1]`. Overshoot easings (`easeOutBack`, etc.) get silently capped because a fixed-resolution LUT cannot represent overshoot. If you need overshoot, drive the eased `t` at sample time with `sampleColorLUT(lut, easeFn(t))` instead.
-
-- **Forgetting alpha is returned, not written.** Parsers return alpha. They do not write it to the buffer. If you mix parsers and hand-written buffers, decide on an alpha layout up front (sibling array, stride-4, or per-instance) and stick with it.
-
-## What this library is NOT
-
-- It is not a general-purpose color manipulation library. No `darken`, `lighten`, `mix`, `saturate`, `complement`, etc. methods. Compose your own from the buffer math primitives.
-- The core `packOklchBufferToUint32` uses a hard channel clamp for its runtime fast path. Accurate CSS Color 4 MINDE chroma-reduction gamut mapping ships in the `/gamut` sub-export (see below) — use that at LUT-build or authoring time when the hue-shift artifacts of the hard clamp matter.
-- It is not a CSS parser for everything. It does CSS Color Level 4 colors. It does not handle `color()`, `color-mix()`, relative color syntax, or system colors.
-- It is not async. There are no Promises. Every function is synchronous and side-effect-free (writes only to its `outBuf` argument).
-
-## Performance budget
-
-| Operation | Wall-clock estimate (modern V8, 2024 laptop) |
-|---|---|
-| `parseCSSColor` | ~1µs per call (not the hot path; numbers vary by format) |
-| `lerpOklchBuffer` | ~50ns per call |
-| `packOklchBufferToUint32` | ~150ns per call |
-| `packOklchBufferToUint32Fast` | ~80ns per call |
-| `sampleColorLUT` | ~10ns per call |
-| `bakeGradientToUint32(..., 256)` | ~50µs total |
-
-Absolute numbers depend on hardware. Relative ratios are stable.
-
-## Versioning
-
-`1.0.x` — the locked core public API surface. No breaking changes within the major. Patch releases for bug fixes; minor releases may **add** functions but not remove or rename.
-
-`1.1.0` — adds `deltaEOK` in core, plus two additive sub-exports:
-- `@zakkster/lite-color-engine/gamut` — CSS Color 4 MINDE gamut mapping and an accurate packer.
-- `@zakkster/lite-color-engine/remap` — SoA batch converters and palette-remap kernels.
-
-No breaking changes; the v1.0 surface is untouched. See `CHANGELOG.md` for full details.
+Use P3 variants when targeting `canvas.getContext('2d', { colorSpace: 'display-p3' })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-color-engine",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "description": "Zero-GC, data-oriented OKLCH color engine with MINDE gamut mapping and palette-remap kernels for WebGL/Canvas pipelines.",
   "type": "module",

package/src/authoring.js

@@ -1,4 +1,4 @@
-import { sRgbToOklchBuffer } from './convert.js';
+import { sRgbToOklchBuffer, displayP3ToOklchBuffer } from './convert.js';
 
 const RAD_TO_DEG = 180 / Math.PI;
 
@@ -51,6 +51,8 @@ const hslToRgb = (h, s, l) => {
     ];
 };
 
+// (linearize lives in convert.js; the parsers below delegate color-space math there)
+
 // ============================================================================
 // 2. REGEX DICTIONARY (CSS Color Level 4 Permissive)
 // ============================================================================
@@ -61,6 +63,7 @@ const OKLCH_REGEX = /^oklch\(\s*([\d.%]+)\s+([\d.%]+)\s+([\d.%a-z]+)(?:\s*\/\s*(
 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;
+const DISPLAY_P3_REGEX = /^color\(\s*display-p3\s+([\d.%]+)\s+([\d.%]+)\s+([\d.%]+)(?:\s*\/\s*([\d.%]+))?\s*\)$/i;
 
 // ============================================================================
 // 3. NAMED COLORS FAST-PATH
@@ -77,7 +80,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', darkslategrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
+    darkslategray: '#2f4f4f', darkslateggrey: '#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',
@@ -88,12 +91,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: '#b0c4de', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
+    lightsteelblue: '#b0e0e6', 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',
+    navajawhite: '#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',
@@ -137,7 +140,7 @@ export const parseHexToBuffer = (str, outBuf, offset) => {
 };
 
 /**
- * Parses a CSS `oklch()` string directly into an OKLCH triplet — no color-space
+ * 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
@@ -222,6 +225,38 @@ export const parseHslToBuffer = (str, outBuf, offset) => {
     return parseVal(match[4], 1) ?? 1.0;
 };
 
+/**
+ * Parses a CSS `color(display-p3 r g b / alpha?)` string into an OKLCH triplet.
+ *
+ * Supports modern slash-alpha syntax and percentage components (0%-100%).
+ * Components are interpreted in the Display P3 color space (gamma-encoded,
+ * same transfer function as sRGB).
+ *
+ * This is the authoring-time entry point for wide-gamut colors. The resulting
+ * OKLCH may have higher chroma than sRGB-gamut colors.
+ *
+ * @param {string} str - The `color(display-p3 ...)` 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 the expected syntax.
+ */
+export const parseDisplayP3ToBuffer = (str, outBuf, offset) => {
+    const match = str.match(DISPLAY_P3_REGEX);
+    if (!match) throw new Error(`lite-color-engine: Invalid display-p3 color "${str}"`);
+
+    // Parse components (0-1 range, with % support) then scale to byte range
+    // for consistency with displayP3ToOklchBuffer / sRgbToOklchBuffer
+    const r = parseVal(match[1], 1) * 255;
+    const g = parseVal(match[2], 1) * 255;
+    const b = parseVal(match[3], 1) * 255;
+
+    // Accurate Display P3 -> OKLCH path (Session 2)
+    displayP3ToOklchBuffer(r, g, b, outBuf, offset);
+
+    return parseVal(match[4], 1) ?? 1.0;
+};
+
 // ============================================================================
 // 5. MASTER SWITCHBOARD
 // ============================================================================
@@ -231,13 +266,16 @@ export const parseHslToBuffer = (str, outBuf, offset) => {
  * format-specific parser and writes an OKLCH triplet.
  *
  * Supports: named colors, `#RGB[A]`, `#RRGGBB[AA]`, `rgb()` / `rgba()`,
- * `hsl()` / `hsla()`, `oklch()`, `oklab()`.
+ * `hsl()` / `hsla()`, `oklch()`, `oklab()`, `color(display-p3 r g b / alpha?)`.
  *
  * Intended for the **authoring/init phase** of a render pipeline (level loads,
  * theme parsing, gradient compilation). After that, work with the resulting
  * `Float32Array` buffer directly via {@link lerpOklchBuffer} and
  * {@link packOklchBufferToUint32}.
  *
+ * `color(display-p3 ...)` is opt-in wide-gamut input. It never affects the
+ * default sRGB hot path.
+ *
  * @param {string} str - The CSS color string
  * @param {Float32Array} outBuf - Pre-allocated destination
  * @param {number} offset - Start index of the L, C, H triplet
@@ -257,6 +295,9 @@ export const parseCSSColor = (str, 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);
+    if (cleanStr.startsWith('color(') && cleanStr.includes('display-p3')) {
+        return parseDisplayP3ToBuffer(cleanStr, outBuf, offset);
+    }
 
     throw new Error(`lite-color-engine: Unsupported color format "${str}".`);
 };