@woosh/meep-engine 3.8.0 → 3.10.0

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

@@ -0,0 +1,21 @@
+/**
+ * Scale the three colour channels, leaving alpha as it was.
+ *
+ * The exposure and tint operation. {@link Color#multiplyScalar} scales all four, which is defensible as a
+ * 4-vector multiply but is almost never what a caller adjusting brightness wants — fading transparency as a
+ * side effect of turning the lights up reads as an engine bug rather than a caller bug.
+ *
+ * Nothing is clamped; scaling light above 1 is meaningful for HDR.
+ *
+ * @param {Color} input
+ * @param {number} scale
+ * @param {Color} [output] may be `input`
+ * @returns {Color} `output`
+ *
+ * @see Color#multiplyScalar for the 4-vector version
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_multiply_rgb(input: Color, scale: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_multiply_rgb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_multiply_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_multiply_rgb.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CATW,KAAK,SACL,MAAM,WACN,KAAK,GACH,KAAK,CAUjB;sBAxBqB,aAAa"}

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

@@ -0,0 +1,26 @@
+import { assert } from "../../assert.js";
+import { Color } from "../Color.js";
+
+/**
+ * Scale the three colour channels, leaving alpha as it was.
+ *
+ * The exposure and tint operation. {@link Color#multiplyScalar} scales all four, which is defensible as a
+ * 4-vector multiply but is almost never what a caller adjusting brightness wants — fading transparency as a
+ * side effect of turning the lights up reads as an engine bug rather than a caller bug.
+ *
+ * Nothing is clamped; scaling light above 1 is meaningful for HDR.
+ *
+ * @param {Color} input
+ * @param {number} scale
+ * @param {Color} [output] may be `input`
+ * @returns {Color} `output`
+ *
+ * @see Color#multiplyScalar for the 4-vector version
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_multiply_rgb(input, scale, output = new Color()) {
+    assert.isNumber(scale, 'scale');
+
+    return output.set(input.r * scale, input.g * scale, input.b * scale, input.a);
+}

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

@@ -1,11 +1,15 @@
 /**
- * Saturate a colour by scaling its OkHSV saturation channel up.
+ * Saturate a colour by moving its OkHSV saturation 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 full saturation covered, so 1 saturates fully and 0
+ * is a no-op that returns `input` itself rather than a copy.
  *
- * @param {Color} input
- * @param {number} [amount]
+ * Mirrors {@link color_lighten}: a multiplicative scale has a fixed point at 0, so it could not saturate a
+ * neutral 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 saturation, `[0, 1]`
  * @returns {Color} `input` when `amount` is 0, otherwise a new Color
  */
 export function color_saturate(input: Color, amount?: number): Color;

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

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

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

@@ -1,24 +1,29 @@
-import { assert } from "../../assert.js";
-import { OKHSV_CHANNEL_SATURATION, color_scale_okhsv_channel } from "./color_scale_okhsv_channel.js";
-
-/**
- * Saturate a colour by scaling its OkHSV saturation 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_saturate(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 { color_mix_okhsv_channel } from "./color_mix_okhsv_channel.js";
+import { OKHSV_CHANNEL_SATURATION } from "./color_scale_okhsv_channel.js";
+
+/**
+ * Saturate a colour by moving its OkHSV saturation channel toward 1.
+ *
+ * `amount` is the fraction of the remaining distance to full saturation covered, so 1 saturates fully and 0
+ * is a no-op that returns `input` itself rather than a copy.
+ *
+ * Mirrors {@link color_lighten}: a multiplicative scale has a fixed point at 0, so it could not saturate a
+ * neutral 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 saturation, `[0, 1]`
+ * @returns {Color} `input` when `amount` is 0, otherwise a new Color
+ */
+export function color_saturate(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_SATURATION, 1, amount);
+}

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

@@ -5,7 +5,7 @@
  * {@link color_desaturate}, which differed only in the channel index and the factor. `channel` is a
  * numeric index, not a string key — the four public functions remain the typed entry points.
  *
- * @param {Color} input
+ * @param {Color} input **linear** sRGB
  * @param {number} channel OkHSV channel index; see {@link OKHSV_CHANNEL_SATURATION} / {@link OKHSV_CHANNEL_VALUE}
  * @param {number} factor multiplier applied to that channel
  * @returns {Color} a new Color

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

@@ -1 +1 @@
-{"version":3,"file":"color_scale_okhsv_channel.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_scale_okhsv_channel.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AACH,iDARW,KAAK,WACL,MAAM,UACN,MAAM,GACJ,KAAK,CAejB;AAvCD;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,kCAFU,MAAM,CAEqB;sBAff,aAAa"}
+{"version":3,"file":"color_scale_okhsv_channel.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_scale_okhsv_channel.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;GAcG;AACH,iDARW,KAAK,WACL,MAAM,UACN,MAAM,GACJ,KAAK,CAuBjB;AApDD;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,kCAFU,MAAM,CAEqB;sBAff,aAAa"}

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

@@ -1,45 +1,58 @@
-import { Color } from "../Color.js";
-import { clamp01 } from "../../math/clamp01.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";
-
-/**
- * OkHSV channel index for saturation.
- * @type {number}
- */
-export const OKHSV_CHANNEL_SATURATION = 1;
-
-/**
- * OkHSV channel index for value.
- * @type {number}
- */
-export const OKHSV_CHANNEL_VALUE = 2;
-
-const hsv = [0, 0, 0];
-
-/**
- * Convert `input` to OkHSV, multiply one channel by `factor`, clamp it to `[0, 1]`, and convert back.
- *
- * Shared body of {@link color_lighten} / {@link color_darken} / {@link color_saturate} /
- * {@link color_desaturate}, which differed only in the channel index and the factor. `channel` is a
- * numeric index, not a string key — the four public functions remain the typed entry points.
- *
- * @param {Color} input
- * @param {number} channel OkHSV channel index; see {@link OKHSV_CHANNEL_SATURATION} / {@link OKHSV_CHANNEL_VALUE}
- * @param {number} factor multiplier applied to that channel
- * @returns {Color} a new Color
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function color_scale_okhsv_channel(input, channel, factor) {
-    const result = new Color();
-
-    linear_srgb_to_okhsv(hsv, input.r, input.g, input.b);
-
-    hsv[channel] = clamp01(hsv[channel] * factor);
-
-    okhsv_to_linear_srgb(result, hsv[0], hsv[1], hsv[2]);
-
-    return result;
-}
+import { Color } from "../Color.js";
+import { clamp01 } from "../../math/clamp01.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";
+
+/**
+ * OkHSV channel index for saturation.
+ * @type {number}
+ */
+export const OKHSV_CHANNEL_SATURATION = 1;
+
+/**
+ * OkHSV channel index for value.
+ * @type {number}
+ */
+export const OKHSV_CHANNEL_VALUE = 2;
+
+const hsv = [0, 0, 0];
+
+/**
+ * @type {number[]}
+ */
+const rgb = [0, 0, 0];
+
+/**
+ * Convert `input` to OkHSV, multiply one channel by `factor`, clamp it to `[0, 1]`, and convert back.
+ *
+ * Shared body of {@link color_lighten} / {@link color_darken} / {@link color_saturate} /
+ * {@link color_desaturate}, which differed only in the channel index and the factor. `channel` is a
+ * numeric index, not a string key — the four public functions remain the typed entry points.
+ *
+ * @param {Color} input **linear** sRGB
+ * @param {number} channel OkHSV channel index; see {@link OKHSV_CHANNEL_SATURATION} / {@link OKHSV_CHANNEL_VALUE}
+ * @param {number} factor multiplier applied to that channel
+ * @returns {Color} a new Color
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_scale_okhsv_channel(input, channel, factor) {
+    const result = new Color();
+
+    linear_srgb_to_okhsv(hsv, input.r, input.g, input.b);
+
+    hsv[channel] = clamp01(hsv[channel] * factor);
+
+    okhsv_to_linear_srgb(rgb, hsv[0], hsv[1], hsv[2]);
+
+    // The OkHSV round trip overshoots by ~1e-7 — white comes back as (1.00000007, 0.99999998, 0.99999974) —
+    // so without this the operations hand back colours marginally outside [0, 1], which is a surprise from a
+    // function whose whole job is to adjust an in-gamut colour.
+    //
+    // Alpha is carried around the conversion rather than through it, since OkHSV has no alpha; that matches
+    // color_lerp, which interpolates it.
+    result.set(clamp01(rgb[0]), clamp01(rgb[1]), clamp01(rgb[2]), input.a);
+
+    return result;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Run one of the `operations/` functions on an **encoded** sRGB colour, decoding on the way in and re-encoding
+ * on the way out.
+ *
+ * Every operation in this directory converts through OkLab, which is defined over *linear* light, so they all
+ * expect linear input. Meanwhile the UI path — `ColorPickerView`, `ColorEditor`, anything built from
+ * {@link Color#parse} or a hex literal — holds encoded values. Passing one to the other is silently wrong
+ * rather than loudly wrong: you get a plausible colour that is lightened by the wrong amount.
+ *
+ * Rather than expecting every caller to remember the conversion, it lives here once. This is the practical
+ * substitute for tagging `Color` with its colour space, which it deliberately is not.
+ *
+ * @example
+ *  // encoded in, encoded out — safe to hand straight back to CSS
+ *  const lighter = color_srgb_apply(Color.parse('#808080'), color_lighten, 0.5);
+ *  element.style.background = lighter.toHex();
+ *
+ * @param {Color} input **encoded** sRGB, as produced by {@link Color#parse} or a hex literal
+ * @param {function(Color, number): Color} operation one of the `color_*` operations, e.g. {@link color_lighten}
+ * @param {number} amount passed through to `operation`
+ * @returns {Color} a new Color holding **encoded** sRGB
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_srgb_apply(input: Color, operation: (arg0: Color, arg1: number) => Color, amount: number): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_srgb_apply.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color_srgb_apply.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/operations/color_srgb_apply.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wCARW,KAAK,oBACI,KAAK,QAAE,MAAM,KAAG,KAAK,UAC9B,MAAM,GACJ,KAAK,CAgBjB;sBAtCqB,aAAa"}

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

@@ -0,0 +1,40 @@
+import { assert } from "../../assert.js";
+import { Color } from "../Color.js";
+
+/**
+ * Run one of the `operations/` functions on an **encoded** sRGB colour, decoding on the way in and re-encoding
+ * on the way out.
+ *
+ * Every operation in this directory converts through OkLab, which is defined over *linear* light, so they all
+ * expect linear input. Meanwhile the UI path — `ColorPickerView`, `ColorEditor`, anything built from
+ * {@link Color#parse} or a hex literal — holds encoded values. Passing one to the other is silently wrong
+ * rather than loudly wrong: you get a plausible colour that is lightened by the wrong amount.
+ *
+ * Rather than expecting every caller to remember the conversion, it lives here once. This is the practical
+ * substitute for tagging `Color` with its colour space, which it deliberately is not.
+ *
+ * @example
+ *  // encoded in, encoded out — safe to hand straight back to CSS
+ *  const lighter = color_srgb_apply(Color.parse('#808080'), color_lighten, 0.5);
+ *  element.style.background = lighter.toHex();
+ *
+ * @param {Color} input **encoded** sRGB, as produced by {@link Color#parse} or a hex literal
+ * @param {function(Color, number): Color} operation one of the `color_*` operations, e.g. {@link color_lighten}
+ * @param {number} amount passed through to `operation`
+ * @returns {Color} a new Color holding **encoded** sRGB
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_srgb_apply(input, operation, amount) {
+    assert.defined(input, 'input');
+    assert.isFunction(operation, 'operation');
+
+    const linear = Color.from_sRGB_to_linear(input);
+
+    const result = operation(linear, amount);
+
+    // `result` is either the Color the operation allocated or, for a no-op amount, `linear` itself. Both are
+    // ours, so the re-encode is done in place rather than allocating a third Color; `input` is never touched.
+    return Color.from_linear_to_sRGB(result, result);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Subtract `b` from `a` channel by channel.
+ *
+ * **All four channels**; see {@link color_add} for the convention and for why nothing is clamped.
+ *
+ * @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_sub(a: Color, b: Color, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_sub.d.ts.map

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

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

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

@@ -0,0 +1,18 @@
+import { Color } from "../Color.js";
+
+/**
+ * Subtract `b` from `a` channel by channel.
+ *
+ * **All four channels**; see {@link color_add} for the convention and for why nothing is clamped.
+ *
+ * @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_sub(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/parse_color.d.ts

@@ -1,7 +1,16 @@
 /**
  * Parses most CSS-format colors
- * @param {string|number} c
+ *
+ * The string forms are matched whole, after trimming — a colour embedded in a larger string is a parse
+ * failure, not a match.
+ *
+ * A numeric argument is a 24-bit `0xRRGGBB` literal, with no alpha. There is deliberately no 32-bit form:
+ * `0xAARRGGBB` and `0xRRGGBBAA` are both plausible readings of the same bits, so a 32-bit value is rejected
+ * rather than guessed at.
+ *
+ * @param {string|number} c a CSS colour string, or a 24-bit `0xRRGGBB` integer
  * @returns {number[]} Numeric array, values are in Uint8 range (0...255) for RGB and 0..1 for Alpha
+ * @throws Error if the string cannot be decoded, or the number is not an integer in `[0, 0xFFFFFF]`
  */
 export function parse_color(c: string | number): number[];
 //# sourceMappingURL=parse_color.d.ts.map

package/src/core/color/parse_color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse_color.d.ts","sourceRoot":"","sources":["../../../../src/core/color/parse_color.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,+BAHW,MAAM,GAAC,MAAM,GACX,MAAM,EAAE,CAsEpB"}
+{"version":3,"file":"parse_color.d.ts","sourceRoot":"","sources":["../../../../src/core/color/parse_color.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;GAaG;AACH,+BAJW,MAAM,GAAC,MAAM,GACX,MAAM,EAAE,CA0EpB"}

package/src/core/color/parse_color.js

@@ -1,84 +1,100 @@
-import { uint8_to_float } from "../binary/uint8_to_float.js";
-import { hex2rgb } from "./hex/hex2rgb.js";
-import { hsv2rgb } from "./hsv/hsv2rgb.js";
-
-
-const rgbRegEx = /rgb\(\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\s*\)/;
-const rgbaRegEx = /rgba\(\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\s*\)/;
-const hsvRegEx = /hsv\(([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\)/;
-
-/**
- * Parses most CSS-format colors
- * @param {string|number} c
- * @returns {number[]} Numeric array, values are in Uint8 range (0...255) for RGB and 0..1 for Alpha
- */
-export function parse_color(c) {
-
-    const result = [];
-
-    const type_of_code = typeof c;
-
-    let r, g, b, a = 1;
-
-    if (type_of_code === "string") {
-        const cL = c.toLowerCase();
-
-        let match;
-
-        if ((match = cL.match(rgbRegEx)) !== null) {
-
-            r = parseFloat(match[1]);
-            g = parseFloat(match[2]);
-            b = parseFloat(match[3]);
-
-        } else if ((match = cL.match(rgbaRegEx)) !== null) {
-
-            r = parseFloat(match[1]);
-            g = parseFloat(match[2]);
-            b = parseFloat(match[3]);
-            a = parseFloat(match[4]);
-
-        } else if ((match = cL.match(hsvRegEx)) !== null) {
-
-            const rgb = hsv2rgb(
-                parseFloat(match[1]),
-                parseFloat(match[2]),
-                parseFloat(match[3])
-            );
-
-            r = rgb.r;
-            g = rgb.g;
-            b = rgb.b;
-
-        } else if (cL.startsWith('#')) {
-
-            const rgb = hex2rgb(cL);
-
-            r = rgb.r;
-            g = rgb.g;
-            b = rgb.b;
-            a = uint8_to_float(rgb.a);
-
-
-        } else {
-            throw new Error(`Failed to decode color string '${c}' `);
-        }
-    } else if (type_of_code === 'number') {
-
-        r = c >> 16;
-        g = (c >> 8) & 0xFF;
-        b = (c) & 0xFF;
-
-    } else {
-        throw new Error(`Failed to decode color '${c}'`);
-    }
-
-    result[0] = r;
-    result[1] = g;
-    result[2] = b;
-    result[3] = a;
-
-
-    return result;
-}
-
+import { uint8_to_float } from "../binary/uint8_to_float.js";
+import { hex_to_rgb } from "./hex/hex_to_rgb.js";
+import { int_to_rgb } from "./int_to_rgb.js";
+import { hsv_to_rgb_uint8 } from "./hsv/hsv_to_rgb_uint8.js";
+
+
+// Anchored, and matched against a trimmed string. Unanchored, these scanned for a colour anywhere inside
+// their input, so 'background: rgb(1,2,3) !important' parsed happily as rgb(1,2,3) — which contradicts the
+// docstring and means a malformed string that happens to contain a colour never surfaces as an error.
+const rgbRegEx = /^rgb\(\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\s*\)$/;
+const rgbaRegEx = /^rgba\(\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\s*\)$/;
+const hsvRegEx = /^hsv\(\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?),\s*([0-9]+(?:\.[0-9]*)?)\s*\)$/;
+
+/**
+ * Parses most CSS-format colors
+ *
+ * The string forms are matched whole, after trimming — a colour embedded in a larger string is a parse
+ * failure, not a match.
+ *
+ * A numeric argument is a 24-bit `0xRRGGBB` literal, with no alpha. There is deliberately no 32-bit form:
+ * `0xAARRGGBB` and `0xRRGGBBAA` are both plausible readings of the same bits, so a 32-bit value is rejected
+ * rather than guessed at.
+ *
+ * @param {string|number} c a CSS colour string, or a 24-bit `0xRRGGBB` integer
+ * @returns {number[]} Numeric array, values are in Uint8 range (0...255) for RGB and 0..1 for Alpha
+ * @throws Error if the string cannot be decoded, or the number is not an integer in `[0, 0xFFFFFF]`
+ */
+export function parse_color(c) {
+
+    const result = [];
+
+    const type_of_code = typeof c;
+
+    let r, g, b, a = 1;
+
+    if (type_of_code === "string") {
+        const cL = c.trim().toLowerCase();
+
+        let match;
+
+        if ((match = cL.match(rgbRegEx)) !== null) {
+
+            r = parseFloat(match[1]);
+            g = parseFloat(match[2]);
+            b = parseFloat(match[3]);
+
+        } else if ((match = cL.match(rgbaRegEx)) !== null) {
+
+            r = parseFloat(match[1]);
+            g = parseFloat(match[2]);
+            b = parseFloat(match[3]);
+            a = parseFloat(match[4]);
+
+        } else if ((match = cL.match(hsvRegEx)) !== null) {
+
+            const rgb = hsv_to_rgb_uint8(
+                parseFloat(match[1]),
+                parseFloat(match[2]),
+                parseFloat(match[3])
+            );
+
+            r = rgb.r;
+            g = rgb.g;
+            b = rgb.b;
+
+        } else if (cL.startsWith('#')) {
+
+            const rgb = hex_to_rgb(cL);
+
+            r = rgb.r;
+            g = rgb.g;
+            b = rgb.b;
+            a = uint8_to_float(rgb.a);
+
+
+        } else {
+            throw new Error(`Failed to decode color string '${c}' `);
+        }
+    } else if (type_of_code === 'number') {
+
+        // 24-bit 0xRRGGBB only, unpacked and validated by the one implementation of that in the package
+        const rgb = int_to_rgb(c);
+
+        r = rgb.r;
+        g = rgb.g;
+        b = rgb.b;
+
+    } else {
+        throw new Error(`Failed to decode color '${c}'`);
+    }
+
+    result[0] = r;
+    result[1] = g;
+    result[2] = b;
+    result[3] = a;
+
+
+    return result;
+}
+

package/src/core/color/parse_color_normalized.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Parses a CSS colour into four channels all on the same `[0, 1]` scale.
+ *
+ * {@link parse_color} returns a mixed unit — RGB in bytes, alpha already normalised — which is the most
+ * surprising thing about it and, until now, meant every caller wanting floats had to know to divide three of
+ * the four elements by 255. `Color.parse` carried exactly that knowledge, which is the kind of thing that
+ * belongs in the colour package rather than in whoever is reading from it.
+ *
+ * `parse_color` keeps its published contract unchanged; the units are documented there and a downstream caller
+ * may well be relying on the byte scale. This is the normalised view of the same parse.
+ *
+ * The result is **encoded** sRGB, since that is what a CSS literal holds — see the note on {@link Color}.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 4, receives r, g, b, a
+ * @param {string|number} value a CSS colour string, or a 24-bit `0xRRGGBB` integer
+ * @returns {number[]|ArrayLike<number>} output
+ * @throws Error if the value cannot be parsed
+ *
+ * @see parse_color for the byte-scaled form
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_color_normalized(output: number[] | ArrayLike<number>, value: string | number): number[] | ArrayLike<number>;
+//# sourceMappingURL=parse_color_normalized.d.ts.map

package/src/core/color/parse_color_normalized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_color_normalized.d.ts","sourceRoot":"","sources":["../../../../src/core/color/parse_color_normalized.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,+CATW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,SAC1B,MAAM,GAAC,MAAM,GACX,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,CAmBtC"}