@woosh/meep-engine 3.9.0 → 3.11.0

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

@@ -0,0 +1,22 @@
+/**
+ * Clamp every channel into `[0, 1]`.
+ *
+ * The blunt instrument, and it is worth knowing that it is blunt: clamping per channel changes hue whenever
+ * the channels are clipped by different amounts, so `(1.5, 0.4, 0)` comes back a different colour rather than
+ * a less saturated one. Use `gamut_clip_preserve_chroma` and its siblings when hue matters; use this when the
+ * point is simply to guarantee a displayable value — writing to an 8-bit buffer, or mopping up the ~1e-7 that
+ * an OkHSV round trip overshoots by.
+ *
+ * Alpha is clamped too; unlike the colour channels it has no meaning outside `[0, 1]`.
+ *
+ * @param {Color} input
+ * @param {Color} [output] may be `input`
+ * @returns {Color} `output`
+ *
+ * @see color_is_in_gamut to test before clamping
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_clamp(input: Color, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_clamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_clamp.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_clamp.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,mCARW,KAAK,WACL,KAAK,GACH,KAAK,CAQjB;sBAvBqB,aAAa"}

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

@@ -0,0 +1,25 @@
+import { clamp01 } from "../../math/clamp01.js";
+import { Color } from "../Color.js";
+
+/**
+ * Clamp every channel into `[0, 1]`.
+ *
+ * The blunt instrument, and it is worth knowing that it is blunt: clamping per channel changes hue whenever
+ * the channels are clipped by different amounts, so `(1.5, 0.4, 0)` comes back a different colour rather than
+ * a less saturated one. Use `gamut_clip_preserve_chroma` and its siblings when hue matters; use this when the
+ * point is simply to guarantee a displayable value — writing to an 8-bit buffer, or mopping up the ~1e-7 that
+ * an OkHSV round trip overshoots by.
+ *
+ * Alpha is clamped too; unlike the colour channels it has no meaning outside `[0, 1]`.
+ *
+ * @param {Color} input
+ * @param {Color} [output] may be `input`
+ * @returns {Color} `output`
+ *
+ * @see color_is_in_gamut to test before clamping
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_clamp(input, output = new Color()) {
+    return output.set(clamp01(input.r), clamp01(input.g), clamp01(input.b), clamp01(input.a));
+}

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

@@ -4,7 +4,8 @@
  * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
  * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
  *
- * @param {Color} input
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
  * @param {number} [amount]
  * @returns {Color} `input` when `amount` is 0, otherwise a new Color
  */

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

@@ -1 +1 @@
-{"version":3,"file":"color_darken.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_darken.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,oDAHW,MAAM,SAahB"}
+{"version":3,"file":"color_darken.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_darken.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,oDAHW,MAAM,SAahB"}

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

@@ -1,24 +1,25 @@
-import { assert } from "../../assert.js";
-import { OKHSV_CHANNEL_VALUE, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
-
-/**
- * Darken a colour by scaling its OkHSV value channel down.
- *
- * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
- * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
- *
- * @param {Color} input
- * @param {number} [amount]
- * @returns {Color} `input` when `amount` is 0, otherwise a new Color
- */
-export function color_darken(input, amount = 1) {
-    assert.isNumber(amount, 'amount');
-    assert.greaterThanOrEqual(amount, 0, 'amount');
-
-    if (amount === 0) {
-        // skip allocation, no change
-        return input;
-    }
-
-    return color_scale_okhsv_channel(input, OKHSV_CHANNEL_VALUE, 1 - amount);
-}
+import { assert } from "../../assert.js";
+import { OKHSV_CHANNEL_VALUE, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
+
+/**
+ * Darken a colour by scaling its OkHSV value channel down.
+ *
+ * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
+ * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
+ *
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
+ * @param {number} [amount]
+ * @returns {Color} `input` when `amount` is 0, otherwise a new Color
+ */
+export function color_darken(input, amount = 1) {
+    assert.isNumber(amount, 'amount');
+    assert.greaterThanOrEqual(amount, 0, 'amount');
+
+    if (amount === 0) {
+        // skip allocation, no change
+        return input;
+    }
+
+    return color_scale_okhsv_channel(input, OKHSV_CHANNEL_VALUE, 1 - amount);
+}

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

@@ -4,7 +4,8 @@
  * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
  * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
  *
- * @param {Color} input
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
  * @param {number} [amount]
  * @returns {Color} `input` when `amount` is 0, otherwise a new Color
  */

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

@@ -1 +1 @@
-{"version":3,"file":"color_desaturate.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_desaturate.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wDAHW,MAAM,SAahB"}
+{"version":3,"file":"color_desaturate.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_desaturate.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wDAHW,MAAM,SAahB"}

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

@@ -1,24 +1,25 @@
-import { assert } from "../../assert.js";
-import { OKHSV_CHANNEL_SATURATION, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
-
-/**
- * Desaturate a colour by scaling its OkHSV saturation channel down.
- *
- * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
- * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
- *
- * @param {Color} input
- * @param {number} [amount]
- * @returns {Color} `input` when `amount` is 0, otherwise a new Color
- */
-export function color_desaturate(input, amount = 1) {
-    assert.isNumber(amount, 'amount');
-    assert.greaterThanOrEqual(amount, 0, 'amount');
-
-    if (amount === 0) {
-        // skip allocation, no change
-        return input;
-    }
-
-    return color_scale_okhsv_channel(input, OKHSV_CHANNEL_SATURATION, 1 - amount);
-}
+import { assert } from "../../assert.js";
+import { OKHSV_CHANNEL_SATURATION, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
+
+/**
+ * Desaturate a colour by scaling its OkHSV saturation channel down.
+ *
+ * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
+ * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
+ *
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
+ * @param {number} [amount]
+ * @returns {Color} `input` when `amount` is 0, otherwise a new Color
+ */
+export function color_desaturate(input, amount = 1) {
+    assert.isNumber(amount, 'amount');
+    assert.greaterThanOrEqual(amount, 0, 'amount');
+
+    if (amount === 0) {
+        // skip allocation, no change
+        return input;
+    }
+
+    return color_scale_okhsv_channel(input, OKHSV_CHANNEL_SATURATION, 1 - amount);
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Read a colour as HSL.
+ *
+ * The inverse of {@link Color#setHSL}, which existed with no way back — `getHSV`/`fromHSV` are a pair, HSL
+ * had neither. A free function rather than a method, so the class does not grow.
+ *
+ * Hue is in turns, `[0, 1)`, matching `setHSL` and every other hue in the package.
+ *
+ * @param {number[]|ArrayLike<number>} output h, s, l
+ * @param {Color} input
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see Color#setHSL
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_get_hsl(output: number[] | ArrayLike<number>, input: Color): number[] | ArrayLike<number>;
+//# sourceMappingURL=color_get_hsl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_get_hsl.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_get_hsl.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,sCARW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAExB,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CA+CtC"}

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

@@ -0,0 +1,60 @@
+import { euclidean_modulo } from "../../math/euclidean_modulo.js";
+
+/**
+ * Read a colour as HSL.
+ *
+ * The inverse of {@link Color#setHSL}, which existed with no way back — `getHSV`/`fromHSV` are a pair, HSL
+ * had neither. A free function rather than a method, so the class does not grow.
+ *
+ * Hue is in turns, `[0, 1)`, matching `setHSL` and every other hue in the package.
+ *
+ * @param {number[]|ArrayLike<number>} output h, s, l
+ * @param {Color} input
+ * @returns {number[]|ArrayLike<number>} output
+ *
+ * @see Color#setHSL
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_get_hsl(output, input) {
+
+    const r = input.r;
+    const g = input.g;
+    const b = input.b;
+
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+
+    const l = (max + min) / 2;
+
+    const d = max - min;
+
+    if (d === 0) {
+        // achromatic; hue is undefined, and 0 is the conventional answer
+        output[0] = 0;
+        output[1] = 0;
+        output[2] = l;
+
+        return output;
+    }
+
+    // HSL's saturation is chroma over the *available* range at this lightness, which shrinks toward both
+    // ends — that is the whole difference from HSV, whose denominator is just `max`
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    let h;
+
+    if (max === r) {
+        h = (g - b) / d;
+    } else if (max === g) {
+        h = (b - r) / d + 2;
+    } else {
+        h = (r - g) / d + 4;
+    }
+
+    output[0] = euclidean_modulo(h / 6, 1);
+    output[1] = s;
+    output[2] = l;
+
+    return output;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Whether all three colour channels lie within `[0, 1]`.
+ *
+ * Alpha is not considered — this asks whether the *colour* is displayable, and there are several ways to
+ * produce one that is not: `setHCL` and `setHSI` are unbounded by contract, an OkHSV round trip overshoots by
+ * ~1e-7, and HDR content is out of gamut by design.
+ *
+ * `tolerance` exists for that last case: exactly the difference between "this needs gamut mapping" and "this
+ * is floating-point noise from a round trip". Pass 1e-6 to ignore the noise.
+ *
+ * @param {Color} input
+ * @param {number} [tolerance] how far outside `[0, 1]` still counts as inside
+ * @returns {boolean}
+ *
+ * @see color_clamp
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_is_in_gamut(input: Color, tolerance?: number): boolean;
+//# sourceMappingURL=color_is_in_gamut.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_is_in_gamut.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_is_in_gamut.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,4DAPW,MAAM,GACJ,OAAO,CAenB"}

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

@@ -0,0 +1,30 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Whether all three colour channels lie within `[0, 1]`.
+ *
+ * Alpha is not considered — this asks whether the *colour* is displayable, and there are several ways to
+ * produce one that is not: `setHCL` and `setHSI` are unbounded by contract, an OkHSV round trip overshoots by
+ * ~1e-7, and HDR content is out of gamut by design.
+ *
+ * `tolerance` exists for that last case: exactly the difference between "this needs gamut mapping" and "this
+ * is floating-point noise from a round trip". Pass 1e-6 to ignore the noise.
+ *
+ * @param {Color} input
+ * @param {number} [tolerance] how far outside `[0, 1]` still counts as inside
+ * @returns {boolean}
+ *
+ * @see color_clamp
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_is_in_gamut(input, tolerance = 0) {
+    assert.isNumber(tolerance, 'tolerance');
+
+    const low = -tolerance;
+    const high = 1 + tolerance;
+
+    return input.r >= low && input.r <= high
+        && input.g >= low && input.g <= high
+        && input.b >= low && input.b <= high;
+}

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

@@ -1,10 +1,19 @@
 /**
  * Performs linear interpolation of two colors in perceptual color space,
- * Useful for palette generation and other use cases where perceptual likeness is important
- * @param {Color} color_0
- * @param {Color} color_1
+ * Useful for palette generation and other use cases where perceptual likeness is important.
+ *
+ * Interpolates in OkHSV, taking the shortest arc around the hue circle. That is not the same operation as
+ * {@link Color#lerpColors}, which interpolates the raw channels — the two differ substantially at mid-`t`,
+ * and between two hues the per-channel version passes through a desaturated middle while this one does not.
+ * Reach for this when the intermediate colours are meant to be looked at, and for `lerpColors` when the
+ * colour is a vector being blended alongside other vectors.
+ *
+ * @param {Color} color_0 **linear** sRGB
+ * @param {Color} color_1 **linear** sRGB
  * @param {number} t
  * @returns {Color}
+ *
+ * @see Color#lerpColors for the per-channel alternative
  */
 export function color_lerp(color_0: Color, color_1: Color, t: number): Color;
 import { Color } from "../Color.js";

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

@@ -1 +1 @@
-{"version":3,"file":"color_lerp.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_lerp.js"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,oCALW,KAAK,WACL,KAAK,KACL,MAAM,GACJ,KAAK,CA6BjB;sBA3CqB,aAAa"}
+{"version":3,"file":"color_lerp.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_lerp.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;GAgBG;AACH,oCAPW,KAAK,WACL,KAAK,KACL,MAAM,GACJ,KAAK,CA+BjB;sBApDqB,aAAa"}

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

@@ -1,47 +1,56 @@
-import { assert } from "../../assert.js";
-import { clamp01 } from "../../math/clamp01.js";
-import { lerp } from "../../math/lerp.js";
-import { Color } from "../Color.js";
-import { linear_srgb_to_okhsv } from "../oklab/linear_srgb_to_okhsv.js";
-import { okhsv_to_linear_srgb } from "../oklab/okhsv_to_linear_srgb.js";
-
-const hsv_0 = [0, 0, 0];
-const hsv_1 = [0, 0, 0];
-const hsv_2 = [0, 0, 0];
-
-/**
- * Performs linear interpolation of two colors in perceptual color space,
- * Useful for palette generation and other use cases where perceptual likeness is important
- * @param {Color} color_0
- * @param {Color} color_1
- * @param {number} t
- * @returns {Color}
- */
-export function color_lerp(color_0, color_1, t) {
-    assert.defined(color_0, 'color_0');
-    assert.defined(color_1, 'color_1');
-    assert.isNumber(t, 't');
-
-    const r = new Color();
-
-    linear_srgb_to_okhsv(hsv_0, color_0.r, color_0.g, color_0.b);
-    linear_srgb_to_okhsv(hsv_1, color_1.r, color_1.g, color_1.b);
-
-    const _t = clamp01(t);
-
-    // Hue is circular (wraps at 1.0), so it must be interpolated along the shortest arc rather than linearly,
-    // otherwise the blend takes the long way around and passes through the wrong hues. Saturation and value
-    // are linear. JS `%` can return negative values, so the wrap math is guarded explicitly.
-    const h0 = hsv_0[0];
-    const h1 = hsv_1[0];
-    const hue_delta = ((h1 - h0) % 1 + 1.5) % 1 - 0.5; // signed shortest-arc delta in (-0.5, 0.5]
-
-    hsv_2[0] = ((h0 + hue_delta * _t) % 1 + 1) % 1;
-    hsv_2[1] = lerp(hsv_0[1], hsv_1[1], _t);
-    hsv_2[2] = lerp(hsv_0[2], hsv_1[2], _t);
-
-    okhsv_to_linear_srgb(r, ...hsv_2);
-    r.a = lerp(color_0.a, color_1.a, _t);
-
-    return r;
+import { assert } from "../../assert.js";
+import { clamp01 } from "../../math/clamp01.js";
+import { lerp } from "../../math/lerp.js";
+import { Color } from "../Color.js";
+import { linear_srgb_to_okhsv } from "../oklab/linear_srgb_to_okhsv.js";
+import { okhsv_to_linear_srgb } from "../oklab/okhsv_to_linear_srgb.js";
+
+const hsv_0 = [0, 0, 0];
+const hsv_1 = [0, 0, 0];
+const hsv_2 = [0, 0, 0];
+
+/**
+ * Performs linear interpolation of two colors in perceptual color space,
+ * Useful for palette generation and other use cases where perceptual likeness is important.
+ *
+ * Interpolates in OkHSV, taking the shortest arc around the hue circle. That is not the same operation as
+ * {@link Color#lerpColors}, which interpolates the raw channels — the two differ substantially at mid-`t`,
+ * and between two hues the per-channel version passes through a desaturated middle while this one does not.
+ * Reach for this when the intermediate colours are meant to be looked at, and for `lerpColors` when the
+ * colour is a vector being blended alongside other vectors.
+ *
+ * @param {Color} color_0 **linear** sRGB
+ * @param {Color} color_1 **linear** sRGB
+ * @param {number} t
+ * @returns {Color}
+ *
+ * @see Color#lerpColors for the per-channel alternative
+ */
+export function color_lerp(color_0, color_1, t) {
+    assert.defined(color_0, 'color_0');
+    assert.defined(color_1, 'color_1');
+    assert.isNumber(t, 't');
+
+    const r = new Color();
+
+    linear_srgb_to_okhsv(hsv_0, color_0.r, color_0.g, color_0.b);
+    linear_srgb_to_okhsv(hsv_1, color_1.r, color_1.g, color_1.b);
+
+    const _t = clamp01(t);
+
+    // Hue is circular (wraps at 1.0), so it must be interpolated along the shortest arc rather than linearly,
+    // otherwise the blend takes the long way around and passes through the wrong hues. Saturation and value
+    // are linear. JS `%` can return negative values, so the wrap math is guarded explicitly.
+    const h0 = hsv_0[0];
+    const h1 = hsv_1[0];
+    const hue_delta = ((h1 - h0) % 1 + 1.5) % 1 - 0.5; // signed shortest-arc delta in (-0.5, 0.5]
+
+    hsv_2[0] = ((h0 + hue_delta * _t) % 1 + 1) % 1;
+    hsv_2[1] = lerp(hsv_0[1], hsv_1[1], _t);
+    hsv_2[2] = lerp(hsv_0[2], hsv_1[2], _t);
+
+    okhsv_to_linear_srgb(r, ...hsv_2);
+    r.a = lerp(color_0.a, color_1.a, _t);
+
+    return r;
 }

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

@@ -1,11 +1,15 @@
 /**
- * Lighten a colour by scaling its OkHSV value channel up.
+ * Lighten a colour by moving its OkHSV value channel toward 1.
  *
- * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
- * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
+ * `amount` is the fraction of the remaining distance to white covered, so 1 lightens fully and 0 is a no-op
+ * that returns `input` itself rather than a copy.
  *
- * @param {Color} input
- * @param {number} [amount]
+ * Mixing toward 1 rather than scaling by `1 + amount`: a multiplicative scale has a fixed point at 0, so it
+ * could not lighten black — the most common input there is — at any amount.
+ *
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
+ * @param {number} [amount] fraction of the distance to full value, `[0, 1]`
  * @returns {Color} `input` when `amount` is 0, otherwise a new Color
  */
 export function color_lighten(input: Color, amount?: number): Color;

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

@@ -1 +1 @@
-{"version":3,"file":"color_lighten.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_lighten.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,qDAHW,MAAM,SAahB"}
+{"version":3,"file":"color_lighten.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_lighten.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,qDAHW,MAAM,SAahB"}

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

@@ -1,24 +1,29 @@
-import { assert } from "../../assert.js";
-import { OKHSV_CHANNEL_VALUE, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
-
-/**
- * Lighten a colour by scaling its OkHSV value channel up.
- *
- * `amount` of 0 is a no-op and returns `input` itself rather than a copy. The scaled channel is clamped to
- * `[0, 1]`, so an `amount` beyond the useful range saturates rather than wrapping.
- *
- * @param {Color} input
- * @param {number} [amount]
- * @returns {Color} `input` when `amount` is 0, otherwise a new Color
- */
-export function color_lighten(input, amount = 1) {
-    assert.isNumber(amount, 'amount');
-    assert.greaterThanOrEqual(amount, 0, 'amount');
-
-    if (amount === 0) {
-        // skip allocation, no change
-        return input;
-    }
-
-    return color_scale_okhsv_channel(input, OKHSV_CHANNEL_VALUE, 1 + amount);
-}
+import { assert } from "../../assert.js";
+import { color_mix_okhsv_channel } from "./color_mix_okhsv_channel.js";
+import { OKHSV_CHANNEL_VALUE } from "./color_scale_okhsv_channel.js";
+
+/**
+ * Lighten a colour by moving its OkHSV value channel toward 1.
+ *
+ * `amount` is the fraction of the remaining distance to white covered, so 1 lightens fully and 0 is a no-op
+ * that returns `input` itself rather than a copy.
+ *
+ * Mixing toward 1 rather than scaling by `1 + amount`: a multiplicative scale has a fixed point at 0, so it
+ * could not lighten black — the most common input there is — at any amount.
+ *
+ * @param {Color} input **linear** sRGB. A `Color` from {@link Color#parse} is encoded — decode it with
+ *  {@link Color.from_sRGB_to_linear} first, or call {@link color_srgb_apply} instead.
+ * @param {number} [amount] fraction of the distance to full value, `[0, 1]`
+ * @returns {Color} `input` when `amount` is 0, otherwise a new Color
+ */
+export function color_lighten(input, amount = 1) {
+    assert.isNumber(amount, 'amount');
+    assert.greaterThanOrEqual(amount, 0, 'amount');
+
+    if (amount === 0) {
+        // skip allocation, no change
+        return input;
+    }
+
+    return color_mix_okhsv_channel(input, OKHSV_CHANNEL_VALUE, 1, amount);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Convert `input` to OkHSV, move one channel a fraction of the way toward `target`, and convert back.
+ *
+ * The additive counterpart to {@link color_scale_okhsv_channel}. The difference matters at the endpoints: a
+ * multiplicative scale has a fixed point at 0, so `v * (1 + amount)` cannot lighten black no matter how large
+ * `amount` gets, and by symmetry cannot saturate an achromatic colour. Mixing toward an endpoint has no fixed
+ * point at either end.
+ *
+ * Toward `target = 0` the two forms coincide — `lerp(v, 0, amount)` is `v * (1 - amount)` — which is why
+ * {@link color_darken} and {@link color_desaturate} were left on the multiplicative path rather than having
+ * their numerics moved for no behavioural gain.
+ *
+ * @param {Color} input **linear** sRGB
+ * @param {number} channel OkHSV channel index; see {@link OKHSV_CHANNEL_SATURATION} / {@link OKHSV_CHANNEL_VALUE}
+ * @param {number} target the value that channel approaches, normally 0 or 1
+ * @param {number} amount fraction of the remaining distance to cover, `[0, 1]`
+ * @returns {Color} a new Color
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_mix_okhsv_channel(input: Color, channel: number, target: number, amount: number): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_mix_okhsv_channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_mix_okhsv_channel.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_mix_okhsv_channel.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+CATW,KAAK,WACL,MAAM,UACN,MAAM,UACN,MAAM,GACJ,KAAK,CAkBjB;sBA/CqB,aAAa"}

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

@@ -0,0 +1,48 @@
+import { Color } from "../Color.js";
+import { clamp01 } from "../../math/clamp01.js";
+import { lerp } from "../../math/lerp.js";
+import { linear_srgb_to_okhsv } from "../oklab/linear_srgb_to_okhsv.js";
+import { okhsv_to_linear_srgb } from "../oklab/okhsv_to_linear_srgb.js";
+
+const hsv = [0, 0, 0];
+
+/**
+ * @type {number[]}
+ */
+const rgb = [0, 0, 0];
+
+/**
+ * Convert `input` to OkHSV, move one channel a fraction of the way toward `target`, and convert back.
+ *
+ * The additive counterpart to {@link color_scale_okhsv_channel}. The difference matters at the endpoints: a
+ * multiplicative scale has a fixed point at 0, so `v * (1 + amount)` cannot lighten black no matter how large
+ * `amount` gets, and by symmetry cannot saturate an achromatic colour. Mixing toward an endpoint has no fixed
+ * point at either end.
+ *
+ * Toward `target = 0` the two forms coincide — `lerp(v, 0, amount)` is `v * (1 - amount)` — which is why
+ * {@link color_darken} and {@link color_desaturate} were left on the multiplicative path rather than having
+ * their numerics moved for no behavioural gain.
+ *
+ * @param {Color} input **linear** sRGB
+ * @param {number} channel OkHSV channel index; see {@link OKHSV_CHANNEL_SATURATION} / {@link OKHSV_CHANNEL_VALUE}
+ * @param {number} target the value that channel approaches, normally 0 or 1
+ * @param {number} amount fraction of the remaining distance to cover, `[0, 1]`
+ * @returns {Color} a new Color
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_mix_okhsv_channel(input, channel, target, amount) {
+    const result = new Color();
+
+    linear_srgb_to_okhsv(hsv, input.r, input.g, input.b);
+
+    hsv[channel] = clamp01(lerp(hsv[channel], target, amount));
+
+    okhsv_to_linear_srgb(rgb, hsv[0], hsv[1], hsv[2]);
+
+    // see color_scale_okhsv_channel on why the result is clamped and why alpha travels around the conversion
+    result.set(clamp01(rgb[0]), clamp01(rgb[1]), clamp01(rgb[2]), input.a);
+
+    return result;
+}