@woosh/meep-engine 3.8.0 → 3.10.0

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

@@ -1,20 +1,29 @@
-/**
- *
- * @param {number[]} output
- * @param {number} r
- * @param {number} g
- * @param {number} b
- */
-export function linear_srgb_to_oklab(output, r, g, b) {
-    const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
-    const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
-    const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
-
-    const l_ = Math.cbrt(l);
-    const m_ = Math.cbrt(m);
-    const s_ = Math.cbrt(s);
-
-    output[0] = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
-    output[1] = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
-    output[2] = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+/**
+ * Linear sRGB to OkLab.
+ *
+ * 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, r, g, b) {
+    const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+    const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+    const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+
+    const l_ = Math.cbrt(l);
+    const m_ = Math.cbrt(m);
+    const s_ = Math.cbrt(s);
+
+    output[0] = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+    output[1] = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+    output[2] = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
 }

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

@@ -0,0 +1,51 @@
+/**
+ * Polynomial fits for the chroma of the "mid" curve at a given hue.
+ *
+ * Ottosson's coefficients, kept in Horner form as he wrote them. They approximate the shape of the sRGB gamut
+ * well enough that OkHSL's saturation stays smooth across hue, which is the whole reason OkHSL exists rather
+ * than just normalising chroma by the cusp.
+ *
+ * @param {number[]|ArrayLike<number>} output S, T
+ * @param {number} a_ normalised OkLab a
+ * @param {number} b_ normalised OkLab b
+ * @returns {number[]|ArrayLike<number>} output
+ */
+export function okhsl_st_mid(output: number[] | ArrayLike<number>, a_: number, b_: number): number[] | ArrayLike<number>;
+/**
+ * The three chroma anchors OkHSL's saturation curve is built from, at a given lightness and hue.
+ *
+ * OkHSL differs from OkHSV in what saturation 1 means: here it is the gamut boundary *at this lightness*, so
+ * a very light or very dark colour has little chroma available and `s = 1` gives that little, rather than
+ * OkHSV's behaviour of trading lightness for it. That is what makes OkHSL the better basis for lighten and
+ * darken — moving `l` does not silently change how saturated the colour looks.
+ *
+ * Three anchors rather than two because a straight line from 0 to the boundary is visibly wrong in the middle;
+ * `C_mid` pins saturation 0.8 to the perceptually sensible chroma so the curve bends the right way.
+ *
+ * @param {number[]|ArrayLike<number>} output C_0, C_mid, C_max; see {@link OKHSL_C_0} and friends
+ * @param {number} L OkLab lightness
+ * @param {number} a_ normalised OkLab a
+ * @param {number} b_ normalised OkLab b
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function okhsl_chroma_bounds(output: number[] | ArrayLike<number>, L: number, a_: number, b_: number): number[] | ArrayLike<number>;
+/**
+ * Index of the chroma at which saturation stops behaving linearly, in {@link okhsl_chroma_bounds}' output.
+ * @type {number}
+ */
+export const OKHSL_C_0: number;
+/**
+ * Index of the chroma that saturation 0.8 maps to.
+ * @type {number}
+ */
+export const OKHSL_C_MID: number;
+/**
+ * Index of the chroma at the gamut boundary, which saturation 1 maps to.
+ * @type {number}
+ */
+export const OKHSL_C_MAX: number;
+//# sourceMappingURL=okhsl_chroma_bounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"okhsl_chroma_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/okhsl_chroma_bounds.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;GAWG;AACH,qCALW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,MAC1B,MAAM,MACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CA6BtC;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4CAVW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAwCtC;AAvHD;;;GAGG;AACH,wBAFU,MAAM,CAEW;AAE3B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,0BAFU,MAAM,CAEa"}

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

@@ -0,0 +1,128 @@
+import { find_cusp } from "./find_cusp.js";
+import { find_gamut_intersection } from "./find_gamut_intersection.js";
+
+/**
+ * @type {number[]}
+ */
+const cusp = [0, 0];
+
+/**
+ * Index of the chroma at which saturation stops behaving linearly, in {@link okhsl_chroma_bounds}' output.
+ * @type {number}
+ */
+export const OKHSL_C_0 = 0;
+
+/**
+ * Index of the chroma that saturation 0.8 maps to.
+ * @type {number}
+ */
+export const OKHSL_C_MID = 1;
+
+/**
+ * Index of the chroma at the gamut boundary, which saturation 1 maps to.
+ * @type {number}
+ */
+export const OKHSL_C_MAX = 2;
+
+/**
+ * Polynomial fits for the chroma of the "mid" curve at a given hue.
+ *
+ * Ottosson's coefficients, kept in Horner form as he wrote them. They approximate the shape of the sRGB gamut
+ * well enough that OkHSL's saturation stays smooth across hue, which is the whole reason OkHSL exists rather
+ * than just normalising chroma by the cusp.
+ *
+ * @param {number[]|ArrayLike<number>} output S, T
+ * @param {number} a_ normalised OkLab a
+ * @param {number} b_ normalised OkLab b
+ * @returns {number[]|ArrayLike<number>} output
+ */
+export function okhsl_st_mid(output, a_, b_) {
+
+    output[0] = 0.11516993 + 1 / (
+        +7.44778970
+        + 4.15901240 * b_
+        + a_ * (-2.19557347
+            + 1.75198401 * b_
+            + a_ * (-2.13704948
+                - 10.02301043 * b_
+                + a_ * (-4.24894561
+                    + 5.38770819 * b_ + 4.69891013 * a_
+                )))
+    );
+
+    output[1] = 0.11239642 + 1 / (
+        +1.61320320
+        - 0.68124379 * b_
+        + a_ * (+0.40370612
+            + 0.90148123 * b_
+            + a_ * (-0.27087943
+                + 0.61223990 * b_
+                + a_ * (+0.00299215
+                    - 0.45399568 * b_ - 0.14661872 * a_
+                )))
+    );
+
+    return output;
+}
+
+/**
+ * @type {number[]}
+ */
+const st_mid = [0, 0];
+
+/**
+ * The three chroma anchors OkHSL's saturation curve is built from, at a given lightness and hue.
+ *
+ * OkHSL differs from OkHSV in what saturation 1 means: here it is the gamut boundary *at this lightness*, so
+ * a very light or very dark colour has little chroma available and `s = 1` gives that little, rather than
+ * OkHSV's behaviour of trading lightness for it. That is what makes OkHSL the better basis for lighten and
+ * darken — moving `l` does not silently change how saturated the colour looks.
+ *
+ * Three anchors rather than two because a straight line from 0 to the boundary is visibly wrong in the middle;
+ * `C_mid` pins saturation 0.8 to the perceptually sensible chroma so the curve bends the right way.
+ *
+ * @param {number[]|ArrayLike<number>} output C_0, C_mid, C_max; see {@link OKHSL_C_0} and friends
+ * @param {number} L OkLab lightness
+ * @param {number} a_ normalised OkLab a
+ * @param {number} b_ normalised OkLab b
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function okhsl_chroma_bounds(output, L, a_, b_) {
+
+    find_cusp(cusp, a_, b_);
+
+    const C_max = find_gamut_intersection(a_, b_, L, 1, L);
+
+    const S_max = cusp[1] / cusp[0];
+    const T_max = cusp[1] / (1 - cusp[0]);
+
+    // compensates for the gamut's curved top, which the straight-line cusp model over-estimates
+    const k = C_max / Math.min(L * S_max, (1 - L) * T_max);
+
+    okhsl_st_mid(st_mid, a_, b_);
+
+    const mid_a = L * st_mid[0];
+    const mid_b = (1 - L) * st_mid[1];
+
+    // a soft minimum rather than min(), so that C_mid is smooth where the two bounds cross and a gradient
+    // through that lightness does not kink
+    const C_mid = 0.9 * k * Math.sqrt(Math.sqrt(1 / (
+        1 / (mid_a * mid_a * mid_a * mid_a) + 1 / (mid_b * mid_b * mid_b * mid_b)
+    )));
+
+    // C_0's shape is hue-independent, so these stand in for the average S and T
+    const zero_a = L * 0.4;
+    const zero_b = (1 - L) * 0.8;
+
+    const C_0 = Math.sqrt(1 / (1 / (zero_a * zero_a) + 1 / (zero_b * zero_b)));
+
+    output[OKHSL_C_0] = C_0;
+    output[OKHSL_C_MID] = C_mid;
+    output[OKHSL_C_MAX] = C_max;
+
+    return output;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * OkHSL to linear sRGB.
+ *
+ * The counterpart to {@link linear_srgb_to_okhsl}, and the sibling of {@link okhsv_to_linear_srgb} that
+ * Ottosson defines alongside it but which was never ported. Prefer it over OkHSV when adjusting lightness:
+ * OkHSL's `l` is perceptual lightness with saturation held fixed, so lightening does not wash a colour out.
+ *
+ * @param {number[]|ArrayLike<number>} output linear sRGB
+ * @param {number} h hue in turns
+ * @param {number} s saturation, `[0, 1]`
+ * @param {number} l lightness, `[0, 1]`
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function okhsl_to_linear_srgb(output: number[] | ArrayLike<number>, h: number, s: number, l: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=okhsl_to_linear_srgb.d.ts.map

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

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

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

@@ -0,0 +1,85 @@
+import { OKHSL_C_0, OKHSL_C_MAX, OKHSL_C_MID, okhsl_chroma_bounds } from "./okhsl_chroma_bounds.js";
+import { oklab_to_linear_srgb } from "./oklab_to_linear_srgb.js";
+import { toe_inv } from "./toe.js";
+
+/**
+ * @type {number[]}
+ */
+const bounds = [0, 0, 0];
+
+/**
+ * Saturation at which the curve switches from the C_0 segment to the C_max one, pinned to C_mid.
+ * @type {number}
+ */
+const MID = 0.8;
+
+/**
+ * OkHSL to linear sRGB.
+ *
+ * The counterpart to {@link linear_srgb_to_okhsl}, and the sibling of {@link okhsv_to_linear_srgb} that
+ * Ottosson defines alongside it but which was never ported. Prefer it over OkHSV when adjusting lightness:
+ * OkHSL's `l` is perceptual lightness with saturation held fixed, so lightening does not wash a colour out.
+ *
+ * @param {number[]|ArrayLike<number>} output linear sRGB
+ * @param {number} h hue in turns
+ * @param {number} s saturation, `[0, 1]`
+ * @param {number} l lightness, `[0, 1]`
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see https://bottosson.github.io/posts/colorpicker/
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function okhsl_to_linear_srgb(output, h, s, l) {
+
+    if (l >= 1) {
+        // the chroma bounds divide by (1 - L), so the endpoints are handled directly rather than by epsilon
+        output[0] = 1;
+        output[1] = 1;
+        output[2] = 1;
+
+        return output;
+    }
+
+    if (l <= 0) {
+        output[0] = 0;
+        output[1] = 0;
+        output[2] = 0;
+
+        return output;
+    }
+
+    const a_ = Math.cos(2 * Math.PI * h);
+    const b_ = Math.sin(2 * Math.PI * h);
+
+    const L = toe_inv(l);
+
+    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];
+
+    // Two rational segments joined at s = MID. They are chosen so that chroma leaves 0 with slope C_0,
+    // passes through C_mid at MID, and reaches C_max at 1 — a straight line through those three points would
+    // be visibly wrong in the middle of the range.
+    let C;
+
+    if (s < MID) {
+        const t = s / MID;
+        const k_1 = MID * C_0;
+        const k_2 = 1 - k_1 / C_mid;
+
+        C = t * k_1 / (1 - k_2 * t);
+    } else {
+        const t = (s - MID) / (1 - MID);
+        const k_1 = (1 - MID) * C_mid * C_mid / (MID * MID * C_0);
+        const k_2 = 1 - k_1 / (C_max - C_mid);
+
+        C = C_mid + t * k_1 / (1 - k_2 * t);
+    }
+
+    oklab_to_linear_srgb(output, L, C * a_, C * b_);
+
+    return output;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * OkLab to OkLCh: the same space in polar coordinates.
+ *
+ * OkLCh is what CSS Color 4 exposes, and it is the natural place to rotate a hue or scale a saturation,
+ * because those are one coordinate each here and a coupled pair in OkLab.
+ *
+ * `h` is in turns, `[0, 1)`, matching the rest of this package rather than CSS's degrees — every other hue in
+ * `core/color` is a turn, and one unit convention beats being locally familiar. Multiply by 360 for CSS.
+ *
+ * A neutral has no meaningful hue; it gets 0 rather than whatever `atan2` makes of two values that are
+ * rounding noise.
+ *
+ * @param {number[]|ArrayLike<number>} output L, C, h
+ * @param {number} L
+ * @param {number} a
+ * @param {number} b
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see oklch_to_oklab
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function oklab_to_oklch(output: number[] | ArrayLike<number>, L: number, a: number, b: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=oklab_to_oklch.d.ts.map

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

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

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

@@ -0,0 +1,35 @@
+/**
+ * OkLab to OkLCh: the same space in polar coordinates.
+ *
+ * OkLCh is what CSS Color 4 exposes, and it is the natural place to rotate a hue or scale a saturation,
+ * because those are one coordinate each here and a coupled pair in OkLab.
+ *
+ * `h` is in turns, `[0, 1)`, matching the rest of this package rather than CSS's degrees — every other hue in
+ * `core/color` is a turn, and one unit convention beats being locally familiar. Multiply by 360 for CSS.
+ *
+ * A neutral has no meaningful hue; it gets 0 rather than whatever `atan2` makes of two values that are
+ * rounding noise.
+ *
+ * @param {number[]|ArrayLike<number>} output L, C, h
+ * @param {number} L
+ * @param {number} a
+ * @param {number} b
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see oklch_to_oklab
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function oklab_to_oklch(output, L, a, b) {
+
+    const C = Math.sqrt(a * a + b * b);
+
+    // 1e-6 against a full chroma of ~0.32; sized to catch the ~1e-7 a neutral lands on
+    const h = C < 1e-6 ? 0 : (Math.atan2(b, a) / (2 * Math.PI) + 1) % 1;
+
+    output[0] = L;
+    output[1] = C;
+    output[2] = h;
+
+    return output;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * OkLCh back to OkLab. The inverse of {@link oklab_to_oklch}.
+ *
+ * `h` is in turns, `[0, 1)`. Values outside the range wrap, since sine and cosine are periodic anyway — there
+ * is no need to normalise first.
+ *
+ * @param {number[]|ArrayLike<number>} output L, a, b
+ * @param {number} L
+ * @param {number} C
+ * @param {number} h hue in turns
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see oklab_to_oklch
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function oklch_to_oklab(output: number[] | ArrayLike<number>, L: number, C: number, h: number): number[] | ArrayLike<number>;
+//# sourceMappingURL=oklch_to_oklab.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oklch_to_oklab.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/oklch_to_oklab.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,uCAVW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,KAC1B,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAetC"}

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

@@ -0,0 +1,26 @@
+/**
+ * OkLCh back to OkLab. The inverse of {@link oklab_to_oklch}.
+ *
+ * `h` is in turns, `[0, 1)`. Values outside the range wrap, since sine and cosine are periodic anyway — there
+ * is no need to normalise first.
+ *
+ * @param {number[]|ArrayLike<number>} output L, a, b
+ * @param {number} L
+ * @param {number} C
+ * @param {number} h hue in turns
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see oklab_to_oklch
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function oklch_to_oklab(output, L, C, h) {
+
+    const angle = h * 2 * Math.PI;
+
+    output[0] = L;
+    output[1] = C * Math.cos(angle);
+    output[2] = C * Math.sin(angle);
+
+    return output;
+}

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

@@ -1,13 +1,25 @@
 /**
  * toe function for L_r
+ *
+ * Maps OkLab's own lightness onto one that tracks CIE L*. OkLab runs brighter than L* in the shadows, and this
+ * pulls those values down; {@link toe_inv} is the direction that lifts them back. Both endpoints are fixed.
+ *
  * @param {number} x
  * @return {number}
+ *
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
  */
 export function toe(x: number): number;
 /**
  * inverse toe function for L_r
+ *
  * @param {number} x
  * @return {number}
+ *
+ * @see toe
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
  */
 export function toe_inv(x: number): number;
 //# sourceMappingURL=toe.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"toe.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/toe.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,uBAHW,MAAM,GACL,MAAM,CAIjB;AAED;;;;GAIG;AACH,2BAHW,MAAM,GACL,MAAM,CAIjB"}
+{"version":3,"file":"toe.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/oklab/toe.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,uBANW,MAAM,GACL,MAAM,CAOjB;AAED;;;;;;;;;GASG;AACH,2BAPW,MAAM,GACL,MAAM,CAQjB"}

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

@@ -1,22 +1,34 @@
-
-const k_1 = 0.206;
-const k_2 = 0.03;
-const k_3 = (1. + k_1) / (1. + k_2);
-
-/**
- * toe function for L_r
- * @param {number} x
- * @return {number}
- */
-export function toe(x){
-    return 0.5 * (k_3 * x - k_1 + Math.sqrt((k_3 * x - k_1) * (k_3 * x - k_1) + 4 * k_2 * k_3 * x));
-}
-
-/**
- * inverse toe function for L_r
- * @param {number} x
- * @return {number}
- */
-export function toe_inv(x){
-    return (x * x + k_1 * x) / (k_3 * (x + k_2));
-}
+
+const k_1 = 0.206;
+const k_2 = 0.03;
+const k_3 = (1. + k_1) / (1. + k_2);
+
+/**
+ * toe function for L_r
+ *
+ * Maps OkLab's own lightness onto one that tracks CIE L*. OkLab runs brighter than L* in the shadows, and this
+ * pulls those values down; {@link toe_inv} is the direction that lifts them back. Both endpoints are fixed.
+ *
+ * @param {number} x
+ * @return {number}
+ *
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
+ */
+export function toe(x){
+    return 0.5 * (k_3 * x - k_1 + Math.sqrt((k_3 * x - k_1) * (k_3 * x - k_1) + 4 * k_2 * k_3 * x));
+}
+
+/**
+ * inverse toe function for L_r
+ *
+ * @param {number} x
+ * @return {number}
+ *
+ * @see toe
+ * @author Björn Ottosson
+ * @see https://bottosson.github.io/posts/colorpicker/
+ */
+export function toe_inv(x){
+    return (x * x + k_1 * x) / (k_3 * (x + k_2));
+}

package/src/core/color/operations/color_add.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Add two colours channel by channel.
+ *
+ * **All four channels**, alpha included, the same 4-vector convention {@link Color#multiply} follows. The rule
+ * across this directory: an unsuffixed name touches all four, and an `_rgb` suffix touches the three colour
+ * channels and copies alpha from the first input — see {@link color_multiply_rgb}.
+ *
+ * Nothing is clamped. Adding light legitimately goes above 1, and `Color` tolerates that; clamp with
+ * {@link color_clamp} when the result has to be displayable.
+ *
+ * @param {Color} a
+ * @param {Color} b
+ * @param {Color} [output] may be `a` or `b`
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_add(a: Color, b: Color, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_add.d.ts.map

package/src/core/color/operations/color_add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_add.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_add.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,6BARW,KAAK,KACL,KAAK,WACL,KAAK,GACH,KAAK,CAOjB;sBAtBqB,aAAa"}

package/src/core/color/operations/color_add.js

@@ -0,0 +1,23 @@
+import { Color } from "../Color.js";
+
+/**
+ * Add two colours channel by channel.
+ *
+ * **All four channels**, alpha included, the same 4-vector convention {@link Color#multiply} follows. The rule
+ * across this directory: an unsuffixed name touches all four, and an `_rgb` suffix touches the three colour
+ * channels and copies alpha from the first input — see {@link color_multiply_rgb}.
+ *
+ * Nothing is clamped. Adding light legitimately goes above 1, and `Color` tolerates that; clamp with
+ * {@link color_clamp} when the result has to be displayable.
+ *
+ * @param {Color} a
+ * @param {Color} b
+ * @param {Color} [output] may be `a` or `b`
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_add(a, b, output = new Color()) {
+    return output.set(a.r + b.r, a.g + b.g, a.b + b.b, a.a + b.a);
+}

package/src/core/color/operations/color_add_scaled.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Add `b * scale` to `a`, channel by channel.
+ *
+ * The accumulation primitive — summing weighted contributions is what an engine does most with colour, and
+ * doing it as `color_add(a, color_multiply_scalar(b, s))` would allocate an intermediate per term.
+ *
+ * **All four channels**; see {@link color_add} for the convention.
+ *
+ * @param {Color} a
+ * @param {Color} b
+ * @param {number} scale
+ * @param {Color} [output] may be `a` or `b`
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_add_scaled(a: Color, b: Color, scale: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_add_scaled.d.ts.map

package/src/core/color/operations/color_add_scaled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_add_scaled.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_add_scaled.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,oCATW,KAAK,KACL,KAAK,SACL,MAAM,WACN,KAAK,GACH,KAAK,CAcjB;sBA5BqB,aAAa"}

package/src/core/color/operations/color_add_scaled.js

@@ -0,0 +1,30 @@
+import { assert } from "../../assert.js";
+import { Color } from "../Color.js";
+
+/**
+ * Add `b * scale` to `a`, channel by channel.
+ *
+ * The accumulation primitive — summing weighted contributions is what an engine does most with colour, and
+ * doing it as `color_add(a, color_multiply_scalar(b, s))` would allocate an intermediate per term.
+ *
+ * **All four channels**; see {@link color_add} for the convention.
+ *
+ * @param {Color} a
+ * @param {Color} b
+ * @param {number} scale
+ * @param {Color} [output] may be `a` or `b`
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_add_scaled(a, b, scale, output = new Color()) {
+    assert.isNumber(scale, 'scale');
+
+    return output.set(
+        a.r + b.r * scale,
+        a.g + b.g * scale,
+        a.b + b.b * scale,
+        a.a + b.a * scale
+    );
+}