@woosh/meep-engine 3.8.0 → 3.10.0

package/src/core/color/PQ/PQ_constants.d.ts

@@ -29,6 +29,16 @@ export const PQ_MAX_NITS: number;
  * Luminance of SDR reference white, in nits, per ITU-R BT.2408. This is the engine's `1.0`, and it is
  * NOT PQ's `1.0`: converting between the two scales is the caller's job and needs
  * {@link PQ_SDR_WHITE_LINEAR} in one direction or its reciprocal in the other.
+ *
+ * It is also not the only number in the engine called a reference white, so: this one is a *renderer*
+ * convention, applied by callers of {@link linear_to_PQ} / {@link PQ_to_linear} rather than folded into
+ * them. The GPU's `chunk_eotfSt2084` folds 100 into its own transfer pair, but that 100 is GT7's "Standard
+ * 1.0 unit" shared with `chunk_tonemap_gt7`, not a competing SDR white. `avif/native/color/transfer_to_linear.js`
+ * uses a third 100, the reference display that H.273's SDR curves are defined against. The boundary where
+ * the conventions meet is named explicitly, as `linear_reference_nits`, in `sampler2d_to_avif` and
+ * `avif_to_sampler2d`.
+ *
+ * @see chunk_eotfSt2084 for the GPU side and the full comparison
  * @type {number}
  */
 export const SDR_WHITE_NITS: number;

package/src/core/color/PQ/PQ_constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PQ_constants.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/PQ_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kCAAkC;AAClC,oBADW,MAAM,CACoB;AAErC,+BAA+B;AAC/B,oBADW,MAAM,CACa;AAE9B,iCAAiC;AACjC,oBADW,MAAM,CACc;AAE/B,gCAAgC;AAChC,oBADW,MAAM,CACe;AAEhC,gCAAgC;AAChC,oBADW,MAAM,CACY;AAE7B;;;;;GAKG;AACH,0BAFU,MAAM,CAEiB;AAEjC;;;;;GAKG;AACH,6BAFU,MAAM,CAEkB;AAElC;;;;;;GAMG;AACH,kCAFU,MAAM,CAEgD"}
+{"version":3,"file":"PQ_constants.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/PQ_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kCAAkC;AAClC,oBADW,MAAM,CACoB;AAErC,+BAA+B;AAC/B,oBADW,MAAM,CACa;AAE9B,iCAAiC;AACjC,oBADW,MAAM,CACc;AAE/B,gCAAgC;AAChC,oBADW,MAAM,CACe;AAEhC,gCAAgC;AAChC,oBADW,MAAM,CACY;AAE7B;;;;;GAKG;AACH,0BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,6BAFU,MAAM,CAEkB;AAElC;;;;;;GAMG;AACH,kCAFU,MAAM,CAEgD"}

package/src/core/color/PQ/PQ_constants.js

@@ -36,6 +36,16 @@ export const PQ_MAX_NITS = 10000;
  * Luminance of SDR reference white, in nits, per ITU-R BT.2408. This is the engine's `1.0`, and it is
  * NOT PQ's `1.0`: converting between the two scales is the caller's job and needs
  * {@link PQ_SDR_WHITE_LINEAR} in one direction or its reciprocal in the other.
+ *
+ * It is also not the only number in the engine called a reference white, so: this one is a *renderer*
+ * convention, applied by callers of {@link linear_to_PQ} / {@link PQ_to_linear} rather than folded into
+ * them. The GPU's `chunk_eotfSt2084` folds 100 into its own transfer pair, but that 100 is GT7's "Standard
+ * 1.0 unit" shared with `chunk_tonemap_gt7`, not a competing SDR white. `avif/native/color/transfer_to_linear.js`
+ * uses a third 100, the reference display that H.273's SDR curves are defined against. The boundary where
+ * the conventions meet is named explicitly, as `linear_reference_nits`, in `sampler2d_to_avif` and
+ * `avif_to_sampler2d`.
+ *
+ * @see chunk_eotfSt2084 for the GPU side and the full comparison
  * @type {number}
  */
 export const SDR_WHITE_NITS = 203;

package/src/core/color/PQ/linear_to_PQ.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear_to_PQ.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/linear_to_PQ.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qCAPW,MAAM,GACJ,MAAM,CAUlB"}
+{"version":3,"file":"linear_to_PQ.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/linear_to_PQ.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qCAPW,MAAM,GACJ,MAAM,CAelB"}

package/src/core/color/PQ/linear_to_PQ.js

@@ -1,3 +1,4 @@
+import { assert } from "../../assert.js";
 import { PQ_C1, PQ_C2, PQ_C3, PQ_M1, PQ_M2 } from "./PQ_constants.js";
 
 /**
@@ -26,6 +27,11 @@ import { PQ_C1, PQ_C2, PQ_C3, PQ_M1, PQ_M2 } from "./PQ_constants.js";
  * @copyright Company Named Limited (c) 2026
  */
 export function linear_to_PQ(linear) {
+    // validated per the package rule: a non-finite input has no encoding, while a negative one does have a
+    // defined answer and is clamped below rather than rejected
+    assert.isNumber(linear, 'linear');
+    assert.isFinite(linear, 'linear');
+
     const y = Math.pow(Math.max(linear, 0), PQ_M1);
 
     return Math.pow((PQ_C1 + PQ_C2 * y) / (1 + PQ_C3 * y), PQ_M2);

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

@@ -0,0 +1,50 @@
+/**
+ * The Rec.709 / sRGB primaries, as coefficients, in one place.
+ *
+ * These numbers previously appeared at three different precisions in three files — 4 significant digits in
+ * `rgb_to_luminance`, 15 in the WGSL `chunk_rgb_to_luminance`, and 20 in `rgb_to_xyz`'s middle row — which is
+ * how a single quantity comes to look like three quantities. Nothing was wrong with any of them; the problem
+ * is that there was no way to tell whether a future edit to one was meant to apply to the others.
+ *
+ * They are *derived* values, not the rounded ones quoted in IEC 61966-2-1. Deriving them from the chromaticity
+ * coordinates below rather than quoting `0.2126 / 0.7152 / 0.0722` is what makes linear white land on
+ * `Y = 1` and on `L* = 100, a* = 0, b* = 0` exactly, which the rest of this package relies on:
+ *
+ * ```
+ *  xr, yr = 0.6400, 0.3300
+ *  xg, yg = 0.3000, 0.6000
+ *  xb, yb = 0.1500, 0.0600
+ *  xw, yw = 0.3127, 0.3290   (D65)
+ * ```
+ *
+ * The difference from the rounded spec values is ~1e-4 — below an 8-bit quantum, and below f32 rounding in
+ * the WGSL twins, so aligning on these costs nothing and settles which spelling is normative.
+ *
+ * @see chunk_rgb_to_luminance the WGSL twin, which must carry the same digits
+ * @see https://en.wikipedia.org/wiki/Luminance
+ */
+/**
+ * Red's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_R: number;
+/**
+ * Green's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_G: number;
+/**
+ * Blue's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_B: number;
+/**
+ * Exponent of the sRGB OETF's power segment, `1 / 2.4`.
+ *
+ * Written out rather than computed so that the WGSL twin can carry the identical literal; the two used to
+ * differ in their trailing digits (`0.41666666666` against `0.4166666666666667`) for no reason anyone
+ * recorded.
+ * @type {number}
+ */
+export const SRGB_OETF_EXPONENT: number;
+//# sourceMappingURL=REC709_PRIMARIES.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"REC709_PRIMARIES.d.ts","sourceRoot":"","sources":["../../../../src/core/color/REC709_PRIMARIES.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,iCAFU,MAAM,CAEyC;AAEzD;;;GAGG;AACH,iCAFU,MAAM,CAEyC;AAEzD;;;GAGG;AACH,iCAFU,MAAM,CAEyC;AAEzD;;;;;;;GAOG;AACH,iCAFU,MAAM,CAEqC"}

package/src/core/color/REC709_PRIMARIES.js

@@ -0,0 +1,53 @@
+/**
+ * The Rec.709 / sRGB primaries, as coefficients, in one place.
+ *
+ * These numbers previously appeared at three different precisions in three files — 4 significant digits in
+ * `rgb_to_luminance`, 15 in the WGSL `chunk_rgb_to_luminance`, and 20 in `rgb_to_xyz`'s middle row — which is
+ * how a single quantity comes to look like three quantities. Nothing was wrong with any of them; the problem
+ * is that there was no way to tell whether a future edit to one was meant to apply to the others.
+ *
+ * They are *derived* values, not the rounded ones quoted in IEC 61966-2-1. Deriving them from the chromaticity
+ * coordinates below rather than quoting `0.2126 / 0.7152 / 0.0722` is what makes linear white land on
+ * `Y = 1` and on `L* = 100, a* = 0, b* = 0` exactly, which the rest of this package relies on:
+ *
+ * ```
+ *  xr, yr = 0.6400, 0.3300
+ *  xg, yg = 0.3000, 0.6000
+ *  xb, yb = 0.1500, 0.0600
+ *  xw, yw = 0.3127, 0.3290   (D65)
+ * ```
+ *
+ * The difference from the rounded spec values is ~1e-4 — below an 8-bit quantum, and below f32 rounding in
+ * the WGSL twins, so aligning on these costs nothing and settles which spelling is normative.
+ *
+ * @see chunk_rgb_to_luminance the WGSL twin, which must carry the same digits
+ * @see https://en.wikipedia.org/wiki/Luminance
+ */
+
+/**
+ * Red's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_R = 0.21263900587151035754;
+
+/**
+ * Green's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_G = 0.71516867876775592746;
+
+/**
+ * Blue's contribution to relative luminance.
+ * @type {number}
+ */
+export const REC709_LUMINANCE_B = 0.07219231536073371500;
+
+/**
+ * Exponent of the sRGB OETF's power segment, `1 / 2.4`.
+ *
+ * Written out rather than computed so that the WGSL twin can carry the identical literal; the two used to
+ * differ in their trailing digits (`0.41666666666` against `0.4166666666666667`) for no reason anyone
+ * recorded.
+ * @type {number}
+ */
+export const SRGB_OETF_EXPONENT = 0.4166666666666667;

package/src/core/color/construct/color_from_hex.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Build a `Color` from a CSS hex literal.
+ *
+ * Accepts all four forms — `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` — and throws on anything else, naming the
+ * offending string.
+ *
+ * The result holds **encoded** sRGB, because that is what a hex literal is. Decode with
+ * {@link Color.from_sRGB_to_linear} before handing it to anything in `operations/`, or use
+ * {@link color_srgb_apply}.
+ *
+ * @param {string} hex
+ * @param {Color} [output]
+ * @returns {Color} `output`, holding **encoded** sRGB
+ * @throws Error if `hex` is not one of the four accepted forms
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_hex(hex: string, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_from_hex.d.ts.map

package/src/core/color/construct/color_from_hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_from_hex.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/construct/color_from_hex.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCARW,MAAM,WACN,KAAK,GACH,KAAK,CAgBjB;sBA/BqB,aAAa"}

package/src/core/color/construct/color_from_hex.js

@@ -0,0 +1,33 @@
+import { uint8_to_float } from "../../binary/uint8_to_float.js";
+import { Color } from "../Color.js";
+import { hex_to_rgb } from "../hex/hex_to_rgb.js";
+
+/**
+ * Build a `Color` from a CSS hex literal.
+ *
+ * Accepts all four forms — `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` — and throws on anything else, naming the
+ * offending string.
+ *
+ * The result holds **encoded** sRGB, because that is what a hex literal is. Decode with
+ * {@link Color.from_sRGB_to_linear} before handing it to anything in `operations/`, or use
+ * {@link color_srgb_apply}.
+ *
+ * @param {string} hex
+ * @param {Color} [output]
+ * @returns {Color} `output`, holding **encoded** sRGB
+ * @throws Error if `hex` is not one of the four accepted forms
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_hex(hex, output = new Color()) {
+
+    const { r, g, b, a } = hex_to_rgb(hex);
+
+    return output.set(
+        uint8_to_float(r),
+        uint8_to_float(g),
+        uint8_to_float(b),
+        uint8_to_float(a)
+    );
+}

package/src/core/color/construct/color_from_temperature.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build a `Color` from a blackbody colour temperature.
+ *
+ * `kelvin_to_rgb` has been here all along with no `Color`-shaped way to reach it.
+ *
+ * The result holds **encoded** sRGB — `kelvin_to_rgb`'s own contract, and the one place in the package where
+ * that was already stated. Convert with {@link Color.from_sRGB_to_linear} before mixing it with anything.
+ *
+ * Alpha is set to 1. Useful range is roughly 1000 K to 40000 K; below the Draper point the result fades to
+ * black, which is the physically sensible answer rather than an error.
+ *
+ * @param {number} kelvin colour temperature
+ * @param {Color} [output]
+ * @returns {Color} `output`, holding **encoded** sRGB
+ *
+ * @see kelvin_to_rgb
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_temperature(kelvin: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_from_temperature.d.ts.map

package/src/core/color/construct/color_from_temperature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_from_temperature.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/construct/color_from_temperature.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CARW,MAAM,WACN,KAAK,GACH,KAAK,CAWjB;sBAhCqB,aAAa"}

package/src/core/color/construct/color_from_temperature.js

@@ -0,0 +1,33 @@
+import { Color } from "../Color.js";
+import { kelvin_to_rgb } from "../kelvin/kelvin_to_rgb.js";
+
+/**
+ * @type {number[]}
+ */
+const scratch = [0, 0, 0];
+
+/**
+ * Build a `Color` from a blackbody colour temperature.
+ *
+ * `kelvin_to_rgb` has been here all along with no `Color`-shaped way to reach it.
+ *
+ * The result holds **encoded** sRGB — `kelvin_to_rgb`'s own contract, and the one place in the package where
+ * that was already stated. Convert with {@link Color.from_sRGB_to_linear} before mixing it with anything.
+ *
+ * Alpha is set to 1. Useful range is roughly 1000 K to 40000 K; below the Draper point the result fades to
+ * black, which is the physically sensible answer rather than an error.
+ *
+ * @param {number} kelvin colour temperature
+ * @param {Color} [output]
+ * @returns {Color} `output`, holding **encoded** sRGB
+ *
+ * @see kelvin_to_rgb
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_temperature(kelvin, output = new Color()) {
+
+    kelvin_to_rgb(scratch, 0, kelvin);
+
+    return output.set(scratch[0], scratch[1], scratch[2], 1);
+}

package/src/core/color/construct/color_from_uint24.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build a `Color` from a packed 24-bit `0xRRGGBB` value. Alpha is set to 1.
+ *
+ * `Color.fromUint` exists as an instance method; constructing from a packed integer took two lines because
+ * there was no static. This is that static, as a free function.
+ *
+ * Values outside `[0, 0xFFFFFF]` throw rather than being truncated — see {@link int_to_rgb}.
+ *
+ * @param {number} value 24-bit `0xRRGGBB`
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ * @throws Error if `value` is not an integer in `[0, 0xFFFFFF]`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_uint24(value: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_from_uint24.d.ts.map

package/src/core/color/construct/color_from_uint24.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_from_uint24.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/construct/color_from_uint24.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,yCARW,MAAM,WACN,KAAK,GACH,KAAK,CAWjB;sBAxBqB,aAAa"}

package/src/core/color/construct/color_from_uint24.js

@@ -0,0 +1,26 @@
+import { uint8_to_float } from "../../binary/uint8_to_float.js";
+import { Color } from "../Color.js";
+import { int_to_rgb } from "../int_to_rgb.js";
+
+/**
+ * Build a `Color` from a packed 24-bit `0xRRGGBB` value. Alpha is set to 1.
+ *
+ * `Color.fromUint` exists as an instance method; constructing from a packed integer took two lines because
+ * there was no static. This is that static, as a free function.
+ *
+ * Values outside `[0, 0xFFFFFF]` throw rather than being truncated — see {@link int_to_rgb}.
+ *
+ * @param {number} value 24-bit `0xRRGGBB`
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ * @throws Error if `value` is not an integer in `[0, 0xFFFFFF]`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_uint24(value, output = new Color()) {
+
+    const { r, g, b } = int_to_rgb(value);
+
+    return output.set(uint8_to_float(r), uint8_to_float(g), uint8_to_float(b), 1);
+}

package/src/core/color/construct/color_from_uint32.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build a `Color` from a packed 32-bit `0xRRGGBBAA` value.
+ *
+ * The byte order is {@link Color#toUint32}'s, which is what `serialize_scene` writes — red in the most
+ * significant byte, alpha in the least. Note that this is *not* the `0xAARRGGBB` that some tooling uses;
+ * there is no way to tell the two apart from the bits, which is why {@link parse_color} refuses 32-bit input
+ * entirely rather than guessing.
+ *
+ * @param {number} value 32-bit `0xRRGGBBAA`
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ * @throws Error if `value` is not an integer in `[0, 0xFFFFFFFF]`
+ *
+ * @see Color#toUint32
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_uint32(value: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_from_uint32.d.ts.map

package/src/core/color/construct/color_from_uint32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_from_uint32.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/construct/color_from_uint32.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;GAgBG;AACH,yCATW,MAAM,WACN,KAAK,GACH,KAAK,CAmBjB;sBArCqB,aAAa"}

package/src/core/color/construct/color_from_uint32.js

@@ -0,0 +1,39 @@
+import { uint8_to_float } from "../../binary/uint8_to_float.js";
+import { Color } from "../Color.js";
+
+/**
+ * Largest value that fits in four packed bytes.
+ * @type {number}
+ */
+const UINT32_MAX = 0xFFFFFFFF;
+
+/**
+ * Build a `Color` from a packed 32-bit `0xRRGGBBAA` value.
+ *
+ * The byte order is {@link Color#toUint32}'s, which is what `serialize_scene` writes — red in the most
+ * significant byte, alpha in the least. Note that this is *not* the `0xAARRGGBB` that some tooling uses;
+ * there is no way to tell the two apart from the bits, which is why {@link parse_color} refuses 32-bit input
+ * entirely rather than guessing.
+ *
+ * @param {number} value 32-bit `0xRRGGBBAA`
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ * @throws Error if `value` is not an integer in `[0, 0xFFFFFFFF]`
+ *
+ * @see Color#toUint32
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_from_uint32(value, output = new Color()) {
+
+    if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {
+        throw new Error(`Failed to decode color '${value}', expected an integer in [0, 0xFFFFFFFF]`);
+    }
+
+    return output.set(
+        uint8_to_float((value >>> 24) & 0xFF),
+        uint8_to_float((value >>> 16) & 0xFF),
+        uint8_to_float((value >>> 8) & 0xFF),
+        uint8_to_float(value & 0xFF)
+    );
+}

package/src/core/color/construct/color_gray.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build a neutral `Color` with all three channels at `value`.
+ *
+ * Space-agnostic like the class itself: a linear 0.5 and an encoded 0.5 are different greys, and this writes
+ * whichever one you hand it without comment.
+ *
+ * @param {number} value
+ * @param {number} [alpha]
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_gray(value: number, alpha?: number, output?: Color): Color;
+import { Color } from "../Color.js";
+//# sourceMappingURL=color_gray.d.ts.map

package/src/core/color/construct/color_gray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color_gray.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/construct/color_gray.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,kCARW,MAAM,UACN,MAAM,WACN,KAAK,GACH,KAAK,CASjB;sBApBqB,aAAa"}

package/src/core/color/construct/color_gray.js

@@ -0,0 +1,22 @@
+import { assert } from "../../assert.js";
+import { Color } from "../Color.js";
+
+/**
+ * Build a neutral `Color` with all three channels at `value`.
+ *
+ * Space-agnostic like the class itself: a linear 0.5 and an encoded 0.5 are different greys, and this writes
+ * whichever one you hand it without comment.
+ *
+ * @param {number} value
+ * @param {number} [alpha]
+ * @param {Color} [output]
+ * @returns {Color} `output`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function color_gray(value, alpha = 1, output = new Color()) {
+    assert.isNumber(value, 'value');
+
+    return output.set(value, value, value, alpha);
+}

package/src/core/color/hex/hex2rgb.d.ts

@@ -1,12 +1,2 @@
-/**
- *
- * @param {string} hex expect form #FFFFFF or #FFFFFFFF for RGBA
- * @returns {{r: number, g: number, b: number, a:number}} rgb
- */
-export function hex2rgb(hex: string): {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-};
+export { hex_to_rgb as hex2rgb } from "./hex_to_rgb.js";
 //# sourceMappingURL=hex2rgb.d.ts.map

package/src/core/color/hex/hex2rgb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hex2rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/hex2rgb.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,6BAHW,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,CAkBvD"}
+{"version":3,"file":"hex2rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/hex2rgb.js"],"names":[],"mappings":""}

package/src/core/color/hex/hex2rgb.js

@@ -1,24 +1,7 @@
-import { hex2dec } from "../../binary/hex2dec.js";
-
-/**
- *
- * @param {string} hex expect form #FFFFFF or #FFFFFFFF for RGBA
- * @returns {{r: number, g: number, b: number, a:number}} rgb
- */
-export function hex2rgb(hex) {
-
-
-    const result = {
-        r: hex2dec(hex.slice(1, 3)),
-        g: hex2dec(hex.slice(3, 5)),
-        b: hex2dec(hex.slice(5, 7))
-    };
-
-    if (hex.length > 7) {
-        result.a = hex2dec(hex.slice(7, 9));
-    }else{
-        result.a = 0xFF;
-    }
-
-    return result;
-}
+/**
+ * @deprecated Renamed to `hex_to_rgb`, following the package's `name_to_name` convention.
+ *
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a published
+ * interface as a function signature.
+ */
+export { hex_to_rgb as hex2rgb } from "./hex_to_rgb.js";

package/src/core/color/hex/hex_to_rgb.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Decode a CSS hex colour.
+ *
+ * Accepts all four CSS forms: `#RGB`, `#RGBA`, `#RRGGBB` and `#RRGGBBAA`. Anything else throws, naming the
+ * offending string — the short forms are the two most common ways to write a colour by hand, and decoding
+ * them by fixed byte offsets used to yield a `NaN` blue rather than an error.
+ *
+ * @param {string} hex `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`
+ * @returns {{r: number, g: number, b: number, a:number}} channels in the Uint8 range (0...255)
+ * @throws Error if `hex` is not one of the four accepted forms
+ */
+export function hex_to_rgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+//# sourceMappingURL=hex_to_rgb.d.ts.map

package/src/core/color/hex/hex_to_rgb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/hex_to_rgb.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;GAUG;AACH,gCAJW,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,CAyBvD"}

package/src/core/color/hex/hex_to_rgb.js

@@ -0,0 +1,62 @@
+import { hex2dec } from "../../binary/hex2dec.js";
+
+/**
+ * The four CSS hex forms, and nothing else.
+ *
+ * Validating up front rather than letting {@link hex2dec} run on a bad slice: `parseInt` returns `NaN` for
+ * an out-of-range slice, and a `NaN` channel only surfaces several frames later, inside whichever consumer
+ * happens to assert. Worse, that consumer's guard is an `assert`, so a build with asserts stripped
+ * propagates the `NaN` instead of throwing.
+ *
+ * @type {RegExp}
+ */
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * Expand a single hex nibble to a byte, the way CSS does: `f` → `ff`, `3` → `33`.
+ *
+ * Duplicating the nibble rather than shifting it keeps the endpoints exact — `f` must land on 255, not 240.
+ *
+ * @param {string} nibble
+ * @returns {number}
+ */
+function expand_nibble(nibble) {
+    const v = hex2dec(nibble);
+
+    return v * 0x11;
+}
+
+/**
+ * Decode a CSS hex colour.
+ *
+ * Accepts all four CSS forms: `#RGB`, `#RGBA`, `#RRGGBB` and `#RRGGBBAA`. Anything else throws, naming the
+ * offending string — the short forms are the two most common ways to write a colour by hand, and decoding
+ * them by fixed byte offsets used to yield a `NaN` blue rather than an error.
+ *
+ * @param {string} hex `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`
+ * @returns {{r: number, g: number, b: number, a:number}} channels in the Uint8 range (0...255)
+ * @throws Error if `hex` is not one of the four accepted forms
+ */
+export function hex_to_rgb(hex) {
+
+    if (typeof hex !== "string" || !HEX_COLOR.test(hex)) {
+        throw new Error(`Failed to decode hex color '${hex}', expected #RGB, #RGBA, #RRGGBB or #RRGGBBAA`);
+    }
+
+    if (hex.length <= 5) {
+        // short form, one nibble per channel
+        return {
+            r: expand_nibble(hex.charAt(1)),
+            g: expand_nibble(hex.charAt(2)),
+            b: expand_nibble(hex.charAt(3)),
+            a: hex.length === 5 ? expand_nibble(hex.charAt(4)) : 0xFF
+        };
+    }
+
+    return {
+        r: hex2dec(hex.slice(1, 3)),
+        g: hex2dec(hex.slice(3, 5)),
+        b: hex2dec(hex.slice(5, 7)),
+        a: hex.length === 9 ? hex2dec(hex.slice(7, 9)) : 0xFF
+    };
+}

package/src/core/color/hex/rgb2hex.d.ts

@@ -1,9 +1,2 @@
-/**
- * Takes values in 0..255 range
- * @param {number} r
- * @param {number} g
- * @param {number} b
- * @returns {string}
- */
-export function rgb2hex(r: number, g: number, b: number): string;
+export { rgb_to_hex as rgb2hex } from "./rgb_to_hex.js";
 //# sourceMappingURL=rgb2hex.d.ts.map

package/src/core/color/hex/rgb2hex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb2hex.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/rgb2hex.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,2BALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAKlB"}
+{"version":3,"file":"rgb2hex.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/rgb2hex.js"],"names":[],"mappings":""}

package/src/core/color/hex/rgb2hex.js

@@ -1,13 +1,7 @@
-import { dec2hex } from "../../binary/dec2hex.js";
-
-/**
- * Takes values in 0..255 range
- * @param {number} r
- * @param {number} g
- * @param {number} b
- * @returns {string}
- */
-export function rgb2hex(r, g, b) {
-
-    return dec2hex(r) + dec2hex(g) + dec2hex(b);
-}
+/**
+ * @deprecated Renamed to `rgb_to_hex`, following the package's `name_to_name` convention.
+ *
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a published
+ * interface as a function signature.
+ */
+export { rgb_to_hex as rgb2hex } from "./rgb_to_hex.js";

package/src/core/color/hex/rgb_to_hex.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Takes values in 0..255 range
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {string}
+ */
+export function rgb_to_hex(r: number, g: number, b: number): string;
+//# sourceMappingURL=rgb_to_hex.d.ts.map

package/src/core/color/hex/rgb_to_hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb_to_hex.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/hex/rgb_to_hex.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,8BALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAKlB"}