@woosh/meep-engine 3.9.0 → 3.11.0

package/src/core/color/oklab/gamut_clip_at_l0.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bring an out-of-gamut linear sRGB colour back inside the cube by reducing its chroma along the line toward
+ * `(L0, 0)` in OkLab, preserving hue exactly.
+ *
+ * The shared body of the three `gamut_clip_*` entry points, which differ only in how they pick `L0` — the
+ * lightness the colour is pulled toward. That single choice is the whole design space of this family of
+ * algorithms, so it is the only thing the callers supply.
+ *
+ * In-gamut colours are returned untouched rather than round-tripped, which also means an exact primary stays
+ * bit-identical instead of picking up conversion noise.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @param {function(number, number, number, number): number} choose_l0 given `(L, C, a_, b_)`, the lightness to project toward
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_at_l0(output: number[] | ArrayLike<number>, r: number, g: number, b: number, choose_l0: (arg0: number, arg1: number, arg2: number, arg3: number) => number): number[] | ArrayLike<number>;
+/**
+ * Chroma below which a colour is treated as neutral and its hue direction is meaningless.
+ *
+ * Full chroma in OkLab is ~0.32, so this is four orders of magnitude below anything a display resolves; it is
+ * sized to catch the ~3e-8 that a neutral actually lands on rather than to quantise real colours.
+ *
+ * @type {number}
+ */
+export const GAMUT_CLIP_CHROMA_EPSILON: number;
+//# sourceMappingURL=gamut_clip_at_l0.d.ts.map

package/src/core/color/oklab/gamut_clip_at_l0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamut_clip_at_l0.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/gamut_clip_at_l0.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yCAXW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,KACN,MAAM,KACN,MAAM,oBACG,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,MAAM,GAC9C,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAkDtC;AA5ED;;;;;;;GAOG;AACH,wCAFU,MAAM,CAE8B"}

package/src/core/color/oklab/gamut_clip_at_l0.js

@@ -0,0 +1,84 @@
+import { clamp01 } from "../../math/clamp01.js";
+import { linear_srgb_to_oklab } from "./linear_srgb_to_oklab.js";
+import { find_gamut_intersection } from "./find_gamut_intersection.js";
+import { oklab_to_linear_srgb } from "./oklab_to_linear_srgb.js";
+
+const Lab = [0, 0, 0];
+
+/**
+ * Chroma below which a colour is treated as neutral and its hue direction is meaningless.
+ *
+ * Full chroma in OkLab is ~0.32, so this is four orders of magnitude below anything a display resolves; it is
+ * sized to catch the ~3e-8 that a neutral actually lands on rather than to quantise real colours.
+ *
+ * @type {number}
+ */
+export const GAMUT_CLIP_CHROMA_EPSILON = 1e-5;
+
+/**
+ * Bring an out-of-gamut linear sRGB colour back inside the cube by reducing its chroma along the line toward
+ * `(L0, 0)` in OkLab, preserving hue exactly.
+ *
+ * The shared body of the three `gamut_clip_*` entry points, which differ only in how they pick `L0` — the
+ * lightness the colour is pulled toward. That single choice is the whole design space of this family of
+ * algorithms, so it is the only thing the callers supply.
+ *
+ * In-gamut colours are returned untouched rather than round-tripped, which also means an exact primary stays
+ * bit-identical instead of picking up conversion noise.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @param {function(number, number, number, number): number} choose_l0 given `(L, C, a_, b_)`, the lightness to project toward
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_at_l0(output, r, g, b, choose_l0) {
+
+    if (r >= 0 && g >= 0 && b >= 0 && r <= 1 && g <= 1 && b <= 1) {
+        // already displayable, nothing to do
+        output[0] = r;
+        output[1] = g;
+        output[2] = b;
+
+        return output;
+    }
+
+    linear_srgb_to_oklab(Lab, r, g, b);
+
+    const L = Lab[0];
+
+    const C = Math.sqrt(Lab[1] * Lab[1] + Lab[2] * Lab[2]);
+
+    if (C < GAMUT_CLIP_CHROMA_EPSILON) {
+        // Neutral, so there is no hue to preserve and it is out of gamut in lightness alone — clamping the
+        // channels *is* the correct clip here, and it is also the only safe one. Normalising `a` and `b` at
+        // this point divides two numbers that are pure rounding noise (a neutral lands at ~3e-8, not 0) and
+        // yields a confident, meaningless hue direction; for a negative neutral that direction produces a
+        // negative cusp chroma, `find_gamut_intersection` bails to Number.MAX_VALUE, and the result is NaN.
+        output[0] = clamp01(r);
+        output[1] = clamp01(g);
+        output[2] = clamp01(b);
+
+        return output;
+    }
+
+    const a_ = Lab[1] / C;
+    const b_ = Lab[2] / C;
+
+    const L0 = choose_l0(L, C, a_, b_);
+
+    // `t` is how far along the line from (L0, 0) to (L, C) the gamut boundary sits
+    const t = find_gamut_intersection(a_, b_, L, C, L0);
+
+    const L_clipped = L0 * (1 - t) + t * L;
+    const C_clipped = t * C;
+
+    oklab_to_linear_srgb(output, L_clipped, C_clipped * a_, C_clipped * b_);
+
+    return output;
+}

package/src/core/color/oklab/gamut_clip_preserve_chroma.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Clip an out-of-gamut linear sRGB colour to the sRGB cube, keeping its lightness and hue and giving up
+ * chroma.
+ *
+ * The most literal of the three strategies: it walks straight in toward the neutral axis at the same L*, so
+ * a colour never changes how light it looks. That is the right default when the colours being clipped are
+ * meant to stay comparable in brightness to each other.
+ *
+ * The cost is that very saturated colours near the top or bottom of the range have almost no chroma available
+ * at their own lightness, so they desaturate hard. {@link gamut_clip_project_to_lcusp} and
+ * {@link gamut_clip_adaptive_l0} trade some lightness accuracy to avoid that.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB in `[0, 1]`
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_preserve_chroma(output: number[] | ArrayLike<number>, r: number, g: number, b: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=gamut_clip_preserve_chroma.d.ts.map

package/src/core/color/oklab/gamut_clip_preserve_chroma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamut_clip_preserve_chroma.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/gamut_clip_preserve_chroma.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,mDAVW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAQtC"}

package/src/core/color/oklab/gamut_clip_preserve_chroma.js

@@ -0,0 +1,37 @@
+import { clamp01 } from "../../math/clamp01.js";
+import { gamut_clip_at_l0 } from "./gamut_clip_at_l0.js";
+
+/**
+ * Project toward the colour's own lightness, clamped to `[0, 1]`.
+ * @param {number} L
+ * @returns {number}
+ */
+function l0_same_lightness(L) {
+    return clamp01(L);
+}
+
+/**
+ * Clip an out-of-gamut linear sRGB colour to the sRGB cube, keeping its lightness and hue and giving up
+ * chroma.
+ *
+ * The most literal of the three strategies: it walks straight in toward the neutral axis at the same L*, so
+ * a colour never changes how light it looks. That is the right default when the colours being clipped are
+ * meant to stay comparable in brightness to each other.
+ *
+ * The cost is that very saturated colours near the top or bottom of the range have almost no chroma available
+ * at their own lightness, so they desaturate hard. {@link gamut_clip_project_to_lcusp} and
+ * {@link gamut_clip_adaptive_l0} trade some lightness accuracy to avoid that.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB in `[0, 1]`
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_preserve_chroma(output, r, g, b) {
+    return gamut_clip_at_l0(output, r, g, b, l0_same_lightness);
+}

package/src/core/color/oklab/gamut_clip_project_to_lcusp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Clip an out-of-gamut linear sRGB colour toward the lightness of its hue's cusp — the most saturated
+ * colour the gamut holds at that hue.
+ *
+ * Aiming at the cusp rather than at the colour's own lightness keeps far more chroma, because the line into
+ * the gamut passes through its widest part. The trade is that lightness moves: a very bright out-of-gamut
+ * yellow comes back darker, a deep out-of-gamut blue comes back lighter.
+ *
+ * Prefer this when saturation is what the image is about, and {@link gamut_clip_preserve_chroma} when
+ * relative brightness is.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB in `[0, 1]`
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_project_to_lcusp(output: number[] | ArrayLike<number>, r: number, g: number, b: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=gamut_clip_project_to_lcusp.d.ts.map

package/src/core/color/oklab/gamut_clip_project_to_lcusp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamut_clip_project_to_lcusp.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/gamut_clip_project_to_lcusp.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oDAVW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAQtC"}

package/src/core/color/oklab/gamut_clip_project_to_lcusp.js

@@ -0,0 +1,46 @@
+import { find_cusp } from "./find_cusp.js";
+import { gamut_clip_at_l0 } from "./gamut_clip_at_l0.js";
+
+/**
+ * @type {number[]}
+ */
+const cusp = [0, 0];
+
+/**
+ * Project toward the lightness of this hue's most saturated point.
+ * @param {number} L
+ * @param {number} C
+ * @param {number} a_
+ * @param {number} b_
+ * @returns {number}
+ */
+function l0_cusp_lightness(L, C, a_, b_) {
+    find_cusp(cusp, a_, b_);
+
+    return cusp[0];
+}
+
+/**
+ * Clip an out-of-gamut linear sRGB colour toward the lightness of its hue's cusp — the most saturated
+ * colour the gamut holds at that hue.
+ *
+ * Aiming at the cusp rather than at the colour's own lightness keeps far more chroma, because the line into
+ * the gamut passes through its widest part. The trade is that lightness moves: a very bright out-of-gamut
+ * yellow comes back darker, a deep out-of-gamut blue comes back lighter.
+ *
+ * Prefer this when saturation is what the image is about, and {@link gamut_clip_preserve_chroma} when
+ * relative brightness is.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 3, receives linear sRGB in `[0, 1]`
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gamut_clip_project_to_lcusp(output, r, g, b) {
+    return gamut_clip_at_l0(output, r, g, b, l0_cusp_lightness);
+}

package/src/core/color/oklab/linear_srgb_to_okhsl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Linear sRGB to OkHSL.
+ *
+ * Ottosson defines OkHSL beside OkHSV; only OkHSV was ported here. The difference is what saturation means:
+ * OkHSV's `v` trades lightness for chroma at the top of the range, OkHSL's `l` does not, so OkHSL is the
+ * better basis for a lighten/darken operation — see {@link okhsl_to_linear_srgb}.
+ *
+ * @param {number[]|ArrayLike<number>} output h, s, l
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function linear_srgb_to_okhsl(output: number[] | ArrayLike<number>, r: number, g: number, b: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=linear_srgb_to_okhsl.d.ts.map

package/src/core/color/oklab/linear_srgb_to_okhsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear_srgb_to_okhsl.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/linear_srgb_to_okhsl.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAVW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAsDtC"}

package/src/core/color/oklab/linear_srgb_to_okhsl.js

@@ -0,0 +1,93 @@
+import { linear_srgb_to_oklab } from "./linear_srgb_to_oklab.js";
+import { OKHSL_C_0, OKHSL_C_MAX, OKHSL_C_MID, okhsl_chroma_bounds } from "./okhsl_chroma_bounds.js";
+import { toe } from "./toe.js";
+
+/**
+ * @type {number[]}
+ */
+const Lab = [0, 0, 0];
+
+/**
+ * @type {number[]}
+ */
+const bounds = [0, 0, 0];
+
+/**
+ * Saturation at which the curve switches segments. Must match {@link okhsl_to_linear_srgb}.
+ * @type {number}
+ */
+const MID = 0.8;
+
+/**
+ * Chroma below which a colour is treated as neutral. See {@link linear_srgb_to_okhsv}, which has the same
+ * problem for the same reason: a neutral lands at ~1e-7, not 0.
+ * @type {number}
+ */
+const NEUTRAL_CHROMA_EPSILON = 1e-6;
+
+/**
+ * Linear sRGB to OkHSL.
+ *
+ * Ottosson defines OkHSL beside OkHSV; only OkHSV was ported here. The difference is what saturation means:
+ * OkHSV's `v` trades lightness for chroma at the top of the range, OkHSL's `l` does not, so OkHSL is the
+ * better basis for a lighten/darken operation — see {@link okhsl_to_linear_srgb}.
+ *
+ * @param {number[]|ArrayLike<number>} output h, s, l
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function linear_srgb_to_okhsl(output, r, g, b) {
+
+    linear_srgb_to_oklab(Lab, r, g, b);
+
+    const L = Lab[0];
+
+    const C = Math.sqrt(Lab[1] * Lab[1] + Lab[2] * Lab[2]);
+
+    if (C < NEUTRAL_CHROMA_EPSILON || L <= 0 || L >= 1) {
+        // neutral, or at an endpoint where the chroma bounds are degenerate
+        output[0] = 0;
+        output[1] = 0;
+        output[2] = toe(L);
+
+        return output;
+    }
+
+    const a_ = Lab[1] / C;
+    const b_ = Lab[2] / C;
+
+    const h = 0.5 + 0.5 * Math.atan2(-Lab[2], -Lab[1]) / Math.PI;
+
+    okhsl_chroma_bounds(bounds, L, a_, b_);
+
+    const C_0 = bounds[OKHSL_C_0];
+    const C_mid = bounds[OKHSL_C_MID];
+    const C_max = bounds[OKHSL_C_MAX];
+
+    // the inverse of the two rational segments in okhsl_to_linear_srgb
+    let s;
+
+    if (C < C_mid) {
+        const k_1 = MID * C_0;
+        const k_2 = 1 - k_1 / C_mid;
+
+        s = MID * C / (k_1 + k_2 * C);
+    } else {
+        const k_1 = (1 - MID) * C_mid * C_mid / (MID * MID * C_0);
+        const k_2 = 1 - k_1 / (C_max - C_mid);
+
+        s = MID + (1 - MID) * (C - C_mid) / (k_1 + k_2 * (C - C_mid));
+    }
+
+    output[0] = h;
+    output[1] = s;
+    output[2] = toe(L);
+
+    return output;
+}

package/src/core/color/oklab/linear_srgb_to_okhsv.d.ts

@@ -1,9 +1,17 @@
 /**
+ * Linear sRGB to OkHSV.
  *
- * @param {number[]} output
- * @param {number} r
- * @param {number} g
- * @param {number} b
+ * See {@link linear_srgb_to_okhsl} for the sibling space, and for why OkHSL is the better basis when the
+ * operation is "make this lighter" rather than "make this brighter".
+ *
+ * @param {number[]} output h, s, v
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ *
+ * @see okhsv_to_linear_srgb
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
  */
 export function linear_srgb_to_okhsv(output: number[], r: number, g: number, b: number): void;
 //# sourceMappingURL=linear_srgb_to_okhsv.d.ts.map

package/src/core/color/oklab/linear_srgb_to_okhsv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear_srgb_to_okhsv.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/linear_srgb_to_okhsv.js"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,6CALW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QA4DhB"}
+{"version":3,"file":"linear_srgb_to_okhsv.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/linear_srgb_to_okhsv.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;GAcG;AACH,6CATW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QAsEhB"}

package/src/core/color/oklab/linear_srgb_to_okhsv.js

@@ -1,85 +1,109 @@
-import { v2_length } from "../../geom/vec2/v2_length.js";
-import { find_cusp } from "./find_cusp.js";
-import { linear_srgb_to_oklab } from "./linear_srgb_to_oklab.js";
-import { oklab_to_linear_srgb } from "./oklab_to_linear_srgb.js";
-import { toe, toe_inv } from "./toe.js";
-
-const Lab = [0, 0, 0];
-
-/**
- *
- * @type {number[]}
- */
-const cusp = [0, 0];
-/**
- *
- * @type {number[]}
- */
-const rgb_scale = [0, 0, 0];
-
-/**
- *
- * @param {number[]} output
- * @param {number} r
- * @param {number} g
- * @param {number} b
- */
-export function linear_srgb_to_okhsv(output, r, g, b) {
-
-    linear_srgb_to_oklab(Lab, r, g, b)
-
-    let L = Lab[0];
-
-    if(L === 0){
-        // going to be all 0s
-        output[0] = 0;
-        output[1] = 0;
-        output[2] = 0;
-        return ;
-    }
-
-    let C = v2_length(Lab[1], Lab[2]);
-
-    let a_ = Lab[1] / C;
-    let b_ = Lab[2] / C;
-
-    const h = 0.5 + 0.5 * Math.atan2(-Lab[2], -Lab[1]) / Math.PI;
-
-    find_cusp(cusp, a_, b_);
-
-    const S_max = cusp[1] / cusp[0];
-    const T_max = cusp[1] / (1 - cusp[0]);
-
-    const S_0 = 0.5;
-    const k = 1 - S_0 / S_max;
-
-    // first we find L_v, C_v, L_vt and C_vt
-
-    const t = T_max / (C + L * T_max);
-    const L_v = t * L;
-    const C_v = t * C;
-
-    const L_vt = toe_inv(L_v);
-    const C_vt = C_v * L_vt / L_v;
-
-    // we can then use these to invert the step that compensates for the toe and the curved top part of the triangle:
-
-    oklab_to_linear_srgb(rgb_scale, L_vt, a_ * C_vt, b_ * C_vt);
-
-    const scale_L = Math.cbrt(1. / Math.max(rgb_scale[0], rgb_scale[1], rgb_scale[2], 0));
-
-    L = L / scale_L;
-    C = C / scale_L;
-
-    C = C * toe(L) / L;
-    L = toe(L);
-
-    // we can now compute v and s:
-
-    const v = L / L_v;
-    const s = (S_0 + T_max) * C_v / ((T_max * S_0) + T_max * k * C_v);
-
-    output[0] = h;
-    output[1] = s;
-    output[2] = v;
+import { v2_length } from "../../geom/vec2/v2_length.js";
+import { find_cusp } from "./find_cusp.js";
+import { linear_srgb_to_oklab } from "./linear_srgb_to_oklab.js";
+import { oklab_to_linear_srgb } from "./oklab_to_linear_srgb.js";
+import { toe, toe_inv } from "./toe.js";
+
+const Lab = [0, 0, 0];
+
+/**
+ *
+ * @type {number[]}
+ */
+const cusp = [0, 0];
+/**
+ *
+ * @type {number[]}
+ */
+const rgb_scale = [0, 0, 0];
+
+/**
+ * Below this chroma a colour is treated as neutral and given hue 0, saturation 0.
+ *
+ * Full chroma in OkLab is ~0.32, so this is four orders of magnitude below anything a display can resolve;
+ * it is sized to catch the ~1e-7 that grey actually lands on, not to quantise real colours.
+ *
+ * @type {number}
+ */
+const NEUTRAL_CHROMA_EPSILON = 1e-6;
+
+/**
+ * Linear sRGB to OkHSV.
+ *
+ * See {@link linear_srgb_to_okhsl} for the sibling space, and for why OkHSL is the better basis when the
+ * operation is "make this lighter" rather than "make this brighter".
+ *
+ * @param {number[]} output h, s, v
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ *
+ * @see okhsv_to_linear_srgb
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
+ */
+export function linear_srgb_to_okhsv(output, r, g, b) {
+
+    linear_srgb_to_oklab(Lab, r, g, b)
+
+    let L = Lab[0];
+
+    let C = v2_length(Lab[1], Lab[2]);
+
+    if (C < NEUTRAL_CHROMA_EPSILON) {
+        // Neutral. Guarding on chroma rather than on `L === 0` because exact-zero chroma is not what the sRGB
+        // path produces: the three OkLab row sums differ in their last bits, so grey lands at C ~ 1e-7 and
+        // slips past an equality test. The two divisions below then hand every neutral the same arbitrary
+        // hue (0.2496) and a saturation of 1e-7 instead of 0.
+        //
+        // `toe(L)` is the value `okhsv_to_linear_srgb` inverts at s = 0, so the round trip still closes; black
+        // falls out of it as 0, which is what the old `L === 0` branch returned.
+        output[0] = 0;
+        output[1] = 0;
+        output[2] = toe(L);
+        return;
+    }
+
+    let a_ = Lab[1] / C;
+    let b_ = Lab[2] / C;
+
+    const h = 0.5 + 0.5 * Math.atan2(-Lab[2], -Lab[1]) / Math.PI;
+
+    find_cusp(cusp, a_, b_);
+
+    const S_max = cusp[1] / cusp[0];
+    const T_max = cusp[1] / (1 - cusp[0]);
+
+    const S_0 = 0.5;
+    const k = 1 - S_0 / S_max;
+
+    // first we find L_v, C_v, L_vt and C_vt
+
+    const t = T_max / (C + L * T_max);
+    const L_v = t * L;
+    const C_v = t * C;
+
+    const L_vt = toe_inv(L_v);
+    const C_vt = C_v * L_vt / L_v;
+
+    // we can then use these to invert the step that compensates for the toe and the curved top part of the triangle:
+
+    oklab_to_linear_srgb(rgb_scale, L_vt, a_ * C_vt, b_ * C_vt);
+
+    const scale_L = Math.cbrt(1. / Math.max(rgb_scale[0], rgb_scale[1], rgb_scale[2], 0));
+
+    L = L / scale_L;
+    C = C / scale_L;
+
+    C = C * toe(L) / L;
+    L = toe(L);
+
+    // we can now compute v and s:
+
+    const v = L / L_v;
+    const s = (S_0 + T_max) * C_v / ((T_max * S_0) + T_max * k * C_v);
+
+    output[0] = h;
+    output[1] = s;
+    output[2] = v;
 }

package/src/core/color/oklab/linear_srgb_to_oklab.d.ts

@@ -1,9 +1,18 @@
 /**
+ * Linear sRGB to OkLab.
  *
- * @param {number[]} output
- * @param {number} r
- * @param {number} g
- * @param {number} b
+ * The coefficients are published to 10 significant digits, which is what bounds the round trip with
+ * {@link oklab_to_linear_srgb} at ~7e-8 rather than at machine precision, and why a neutral lands on a chroma
+ * of ~1e-7 instead of 0.
+ *
+ * @param {number[]} output L, a, b
+ * @param {number} r linear sRGB
+ * @param {number} g linear sRGB
+ * @param {number} b linear sRGB
+ *
+ * @see oklab_to_linear_srgb
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/oklab/
  */
 export function linear_srgb_to_oklab(output: number[], r: number, g: number, b: number): void;
 //# sourceMappingURL=linear_srgb_to_oklab.d.ts.map

package/src/core/color/oklab/linear_srgb_to_oklab.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear_srgb_to_oklab.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/linear_srgb_to_oklab.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,6CALW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QAchB"}
+{"version":3,"file":"linear_srgb_to_oklab.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/linear_srgb_to_oklab.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,6CATW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QAkBhB"}