@texel/color 1.1.4 → 1.1.6

package/DOC.md

@@ -0,0 +1,17 @@
+`@texel/color` is a minimal and modern color library for JavaScript. Especially useful for real-time applications, generative art, and graphics on the web.
+
+## Source Code
+
+The source code is on GitHub:
+
+[https://github.com/texel-org/color](https://github.com/texel-org/color)
+
+## Docs
+
+The documentation is held here:
+
+[https://texel-org.github.io/color](https://texel-org.github.io/color)
+
+## Usage
+
+For installation and usage, see the [README.md page](https://github.com/texel-org/color/) on the GitHub repository.

package/README.md

@@ -73,7 +73,13 @@ context.fillStyle = color;
 context.fillRect(0,0, canvas.width, canvas.height);
 ```
 
-## API
+## API Docs
+
+Auto-generated documentation with all exposed methods can be found here:
+
+[https://texel-org.github.io/color](https://texel-org.github.io/color)
+
+## API Details
 
 #### `output = convert(coords, fromSpace, toSpace, output = [0, 0, 0])`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texel/color",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "a minimal and modern color library",
   "type": "module",
   "main": "./src/index.js",
@@ -10,20 +10,26 @@
     "url": "https://github.com/mattdesl"
   },
   "devDependencies": {
+    "better-docs": "^2.7.3",
     "canvas-sketch": "^0.7.7",
     "canvas-sketch-cli": "^1.11.21",
     "colorjs.io": "^0.5.2",
     "culori": "^4.0.1",
     "esbuild": "^0.23.0",
     "faucet": "^0.0.4",
+    "jsdoc": "^4.0.4",
     "pako": "^2.1.0",
     "png-tools": "^1.0.4",
     "prettier": "^3.3.3",
     "tape": "^5.8.1",
-    "terser": "^5.31.3"
+    "terser": "^5.31.3",
+    "tsd-jsdoc": "^2.5.0"
   },
+  "types": "./types/types.d.ts",
   "scripts": {
     "visualize": "canvas-sketch-cli test/canvas-graph.js --open",
+    "docs": "jsdoc src -t node_modules/better-docs -c tools/.jsdoc.json -d docs -R DOC.md",
+    "types": "jsdoc src -t node_modules/tsd-jsdoc/dist -c tools/.jsdoc.types.json -d types",
     "test": "faucet test/test*.js",
     "bench": "node test/bench-colorjs.js",
     "bench:node": "NODE_ENV=production node --prof --no-logfile-per-isolate test/bench-node.js && node --prof-process v8.log",

package/src/core.js

@@ -2,6 +2,48 @@ import { clamp, floatToByte, hexToRGB, vec3 } from "./util.js";
 import { LMS_to_OKLab_M, OKLab_to_LMS_M } from "./conversion_matrices.js";
 import { listColorSpaces, sRGB, XYZ } from "./spaces.js";
 
+/**
+ * @typedef {number[][]} Matrix3x3
+ * @description A 3x3 matrix represented as an array of arrays.
+ * @example
+ * const matrix = [
+ *   [a, b, c],
+ *   [d, e, f],
+ *   [g, h, i]
+ * ];
+ */
+
+/**
+ * @typedef {number[]} Vector
+ * @description A n-dimensional vector represented as an array of numbers, typically in 3D (X, Y, Z).
+ * @example
+ * const vec = [ x, y, z ];
+ */
+
+/**
+ * @typedef {Object} ChromaticAdaptation
+ * @property {Matrix3x3} from the matrix to convert from the source whitepoint to the destination whitepoint
+ * @property {Matrix3x3} to the matrix to convert from the destination whitepoint to the source whitepoint
+ */
+
+/**
+ * @typedef {Object} ColorSpace
+ * @property {String} id the unique identifier for this color space in lowercase
+ * @property {Matrix3x3} [toXYZ_M] optional matrix to convert this color directly to XYZ D65
+ * @property {Matrix3x3} [fromXYZ_M] optional matrix to convert XYZ D65 to this color space
+ * @property {Matrix3x3} [toLMS_M] optional matrix to convert this color space to OKLab's LMS intermediary form
+ * @property {Matrix3x3} [fromLMS_M] optional matrix to convert OKLab's LMS intermediary form to this color space
+ * @property {ChromaticAdaptation} [adapt] optional chromatic adaptation matrices
+ * @property {ColorSpace} [base] an optional base color space that this space is derived from
+ * @property {function} [toBase] if a base color space exists, this maps the color to the base space form (e.g. gamma to the linear base space)
+ * @property {function} [fromBase] if a base color space exists, this maps the color from the base space form (e.g. the linear base space to the gamma space)
+ */
+
+/**
+ * @typedef {Object} ColorGamut
+ * @property {ColorSpace} space the color space associated with this color gamut
+ */
+
 const tmp3 = vec3();
 
 const cubed3 = (lms) => {
@@ -21,18 +63,45 @@ const cbrt3 = (lms) => {
 
 const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 
+/**
+ * Converts OKLab color to another color space.
+ * @param {Vector} OKLab The OKLab color.
+ * @param {Matrix3x3} LMS_to_output The transformation matrix from LMS to the output color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category oklab
+ */
 export const OKLab_to = (OKLab, LMS_to_output, out = vec3()) => {
   transform(OKLab, OKLab_to_LMS_M, out);
   cubed3(out);
   return transform(out, LMS_to_output, out);
 };
 
+/**
+ * Converts a color from another color space to OKLab.
+ * @param {Vector} input The input color.
+ * @param {Matrix3x3} input_to_LMS The transformation matrix from the input color space to LMS.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category oklab
+ */
 export const OKLab_from = (input, input_to_LMS, out = vec3()) => {
   transform(input, input_to_LMS, out);
   cbrt3(out);
   return transform(out, LMS_to_OKLab_M, out);
 };
 
+/**
+ * Transforms a color vector by the specified 3x3 transformation matrix.
+ * @param {Vector} input The input color.
+ * @param {Matrix3x3} matrix The transformation matrix.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category core
+ */
 export const transform = (input, matrix, out = vec3()) => {
   const x = dot3(input, matrix[0]);
   const y = dot3(input, matrix[1]);
@@ -49,6 +118,15 @@ const vec3Copy = (input, output) => {
   output[2] = input[2];
 };
 
+/**
+ * Serializes a color to a CSS color string.
+ * @param {Vector} input The input color.
+ * @param {ColorSpace} inputSpace The input color space.
+ * @param {ColorSpace} [outputSpace=inputSpace] The output color space.
+ * @returns {string} The serialized color string.
+ * @method
+ * @category core
+ */
 export const serialize = (input, inputSpace, outputSpace = inputSpace) => {
   if (!inputSpace) throw new Error(`must specify an input space`);
   // extract alpha if present
@@ -86,13 +164,33 @@ const stripAlpha = (coords) => {
   return coords;
 };
 
-const parseFloatValue = str => parseFloat(str) || 0;
+const parseFloatValue = (str) => parseFloat(str) || 0;
 
 const parseColorValue = (str, is255 = false) => {
   if (is255) return clamp(parseFloatValue(str) / 0xff, 0, 0xff);
-  else return str.includes('%') ? parseFloatValue(str) / 100 : parseFloatValue(str);
+  else
+    return str.includes("%")
+      ? parseFloatValue(str) / 100
+      : parseFloatValue(str);
 };
 
+/**
+ * Deserializes a color string to an object with <code>id</code> (color space string) and <code>coords</code> (the vector, in 3 or 4 dimensions).
+ * Note this does not return a <code>ColorSpace</code> object; you may want to use the example code below to map the string ID to a <code>ColorSpace</code>, but this will increase the size of your final bundle as it references all spaces.
+ *
+ * @example
+ * import { listColorSpaces, deserialize } from "@texel/color";
+ *
+ * const { id, coords } = deserialize(str);
+ * // now find the actual color space object
+ * const space = listColorSpaces().find((f) => id === f.id);
+ * console.log(space, coords);
+ *
+ * @param {string} input The color string to deserialize.
+ * @returns {{id: string, coords: Vector}} The deserialized color object.
+ * @method
+ * @category core
+ */
 export const deserialize = (input) => {
   if (typeof input !== "string") {
     throw new Error(`expected a string as input`);
@@ -114,9 +212,9 @@ export const deserialize = (input) => {
       throw new Error(`could not parse color string ${input}`);
     }
     const fn = parts[1].toLowerCase();
-    if (/^rgba?$/i.test(fn) && parts[2].includes(',')) {
-      const coords = parts[2].split(',').map((v, i) => {
-        return parseColorValue(v.trim(), i < 3)
+    if (/^rgba?$/i.test(fn) && parts[2].includes(",")) {
+      const coords = parts[2].split(",").map((v, i) => {
+        return parseColorValue(v.trim(), i < 3);
       });
       return {
         id: "srgb",
@@ -139,7 +237,7 @@ export const deserialize = (input) => {
         if (/^(oklab|oklch)$/i.test(fn)) {
           id = fn;
         } else if (/rgba?/i.test(fn)) {
-          id = 'srgb';
+          id = "srgb";
           div255 = true;
         } else {
           throw new Error(`unknown color function ${fn}`);
@@ -168,6 +266,15 @@ export const deserialize = (input) => {
   }
 };
 
+/**
+ * Parses a color string and converts it to the target color space.
+ * @param {string} input The color string to parse.
+ * @param {ColorSpace} targetSpace The target color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The parsed and converted color.
+ * @method
+ * @category core
+ */
 export const parse = (input, targetSpace, out = vec3()) => {
   if (!targetSpace)
     throw new Error(`must specify a target space to parse into`);
@@ -188,6 +295,16 @@ export const parse = (input, targetSpace, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts a color from one color space to another.
+ * @param {Vector} input The input color.
+ * @param {ColorSpace} fromSpace The source color space.
+ * @param {ColorSpace} toSpace The target color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The converted color.
+ * @method
+ * @category core
+ */
 export const convert = (input, fromSpace, toSpace, out = vec3()) => {
   // place into output
   vec3Copy(input, out);
@@ -310,8 +427,14 @@ export const convert = (input, fromSpace, toSpace, out = vec3()) => {
   return out;
 };
 
-// Calculate deltaE OK
-// simple root sum of squares
+/**
+ * Calculates the DeltaEOK (color difference) between two OKLab colors.
+ * @param {Vector} oklab1 The first OKLab color.
+ * @param {Vector} oklab2 The second OKLab color.
+ * @returns {number} The delta E value.
+ * @method
+ * @category core
+ */
 export const deltaEOK = (oklab1, oklab2) => {
   let dL = oklab1[0] - oklab2[0];
   let da = oklab1[1] - oklab2[1];

package/src/gamut.js

@@ -12,9 +12,37 @@ import { OKLab_to, convert } from "./core.js";
 
 const DEFAULT_ALPHA = 0.05;
 
+/**
+ * @typedef {function} GamutMapMethod
+ * @description A function that maps an OKLCH color to a lightness value.
+ * @param {Vector} oklch The input OKLCH color
+ * @param {number[]} cusp A 2D cusp point in the form [L, C]
+ * @category mapping
+ */
+
+/**
+ * A {@link GamutMapMethod} that maintains the color's lightness.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToL = (oklch) => oklch[0];
+/**
+ * A {@link GamutMapMethod} that maps towards middle gray (L = 0.5).
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToGray = () => 0.5;
+/**
+ * A {@link GamutMapMethod} that maps towards the lightness of the current hue's cusp.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToCuspL = (_, cusp) => cusp[0];
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards gray.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToAdaptiveGray = (oklch, cusp) => {
   const Ld = oklch[0] - cusp[0];
   const k = 2 * (Ld > 0 ? 1 - cusp[0] : cusp[0]);
@@ -24,7 +52,11 @@ export const MapToAdaptiveGray = (oklch, cusp) => {
     0.5 * (Math.sign(Ld) * (e1 - Math.sqrt(e1 * e1 - 2 * k * Math.abs(Ld))))
   );
 };
-
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards the cusp's lightness.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToAdaptiveCuspL = (oklch) => {
   const Ld = oklch[0] - 0.5;
   const e1 = 0.5 + Math.abs(Ld) + DEFAULT_ALPHA * oklch[1];
@@ -55,6 +87,17 @@ const setYZ = (v, a, b) => {
   v[2] = b;
 };
 
+/**
+ * Computes the maximum saturation (S = C/L) possible for a given hue that fits within
+ * the RGB gamut, using the given coefficients.
+ * @param {number} a The normalized a component of the hue.
+ * @param {number} b The normalized b component of the hue.
+ * @param {number[][]} lmsToRgb The LMS to RGB conversion matrix.
+ * @param {number[][][]} okCoeff The OKLab coefficients.
+ * @returns {number} The maximum saturation.
+ * @method
+ * @category mapping
+ */
 export const computeMaxSaturationOKLC = (a, b, lmsToRgb, okCoeff) => {
   // https://github.com/color-js/color.js/blob/main/src/spaces/okhsl.js
   // Finds the maximum saturation possible for a given hue that fits in RGB.
@@ -132,6 +175,13 @@ export const computeMaxSaturationOKLC = (a, b, lmsToRgb, okCoeff) => {
   return sat;
 };
 
+/**
+ * Retrieves the LMS to RGB conversion matrix from the given gamut.
+ * @param {ColorGamut} gamut The gamut object.
+ * @returns {Matrix3x3} The LMS to RGB conversion matrix.
+ * @method
+ * @category mapping
+ */
 export const getGamutLMStoRGB = (gamut) => {
   if (!gamut) throw new Error(`expected gamut to have { space }`);
   const lmsToRGB = (gamut.space.base ?? gamut.space).fromLMS_M;
@@ -140,6 +190,16 @@ export const getGamutLMStoRGB = (gamut) => {
   return lmsToRGB;
 };
 
+/**
+ * Finds the cusp of the OKLCH color space for a given hue.
+ * @param {number} a The normalized a component of the hue.
+ * @param {number} b The normalized b component of the hue.
+ * @param {ColorGamut} gamut The gamut object.
+ * @param {number[]} [out=[0, 0]] The output array to store the cusp values.
+ * @returns {number[]} The cusp values [L, C].
+ * @method
+ * @category mapping
+ */
 export const findCuspOKLCH = (a, b, gamut, out = [0, 0]) => {
   const lmsToRgb = getGamutLMStoRGB(gamut);
   const okCoeff = gamut.coefficients;
@@ -182,14 +242,14 @@ export const findGamutIntersectionOKLCH = (a, b, l1, c1, l0, cusp, gamut) => {
 
   // Find the intersection for upper and lower half separately
   if ((l1 - l0) * cusp[1] - (cusp[0] - l0) * c1 <= 0.0) {
-    const denom = (c1 * cusp[0] + cusp[1] * (l0 - l1));
+    const denom = c1 * cusp[0] + cusp[1] * (l0 - l1);
     // Lower half
     t = denom === 0 ? 0 : (cusp[1] * l0) / denom;
   } else {
     // Upper half
 
     // First intersect with triangle
-    const denom = (c1 * (cusp[0] - 1.0) + cusp[1] * (l0 - l1));
+    const denom = c1 * (cusp[0] - 1.0) + cusp[1] * (l0 - l1);
     t = denom === 0 ? 0 : (cusp[1] * (l0 - 1.0)) / denom;
 
     // Then one step Halley's method
@@ -256,7 +316,17 @@ export const findGamutIntersectionOKLCH = (a, b, l1, c1, l0, cusp, gamut) => {
 };
 
 /**
- * Takes any OKLCH value and maps it to fall within the given gamut.
+ * Applies fast approximate gamut mapping in OKLab space on the given OKLCH input color,
+ * using the specified gamut and converting to the target color space.
+ * @param {Vector} oklch The input OKLCH color that you wish to gamut map.
+ * @param {ColorGamut} [gamut=sRGBGamut] The gamut object.
+ * @param {ColorSpace} [targetSpace=gamut.space] The target color space.
+ * @param {Vector} [out=vec3()] The output array to store the mapped color.
+ * @param {GamutMapMethod} [mapping=MapToCuspL] The gamut mapping function.
+ * @param {Vector} [cusp] Optional, you can provide the cusp values [L, C] to avoid re-computing them.
+ * @returns {Vector} The mapped color in the target color space.
+ * @method
+ * @category mapping
  */
 export const gamutMapOKLCH = (
   oklch,

package/src/okhsl.js

@@ -116,6 +116,16 @@ const getCs = (l, a, b, cusp, gamut) => {
   return [c0, cMid, cMax];
 };
 
+/**
+ * Converts OKHSL color to OKLab color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} hsl - The OKHSL color as an array [h, s, l].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKLab color.
+ * @returns {Vector} The OKLab color as an array [L, a, b].
+ */
 export const OKHSLToOKLab = (hsl, gamut = sRGBGamut, out = vec3()) => {
   // Convert Okhsl to Oklab.
   let h = hsl[0],
@@ -171,6 +181,16 @@ export const OKHSLToOKLab = (hsl, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts OKLab color to OKHSL color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} lab - The OKLab color as an array [L, a, b].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKHSL color.
+ * @returns {Vector} The OKHSL color as an array [h, s, l].
+ */
 export const OKLabToOKHSL = (lab, gamut = sRGBGamut, out = vec3()) => {
   // Oklab to Okhsl.
 
@@ -234,6 +254,16 @@ export const OKLabToOKHSL = (lab, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts OKHSV color to OKLab color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} hsv - The OKHSV color as an array [h, s, v].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKLab color.
+ * @returns {Vector} The OKLab color as an array [L, a, b].
+ */
 export const OKHSVToOKLab = (hsv, gamut = sRGBGamut, out = vec3()) => {
   // Convert from Okhsv to Oklab."""
 
@@ -288,6 +318,16 @@ export const OKHSVToOKLab = (hsv, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts OKLab color to OKHSV color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} lab The OKLab color as an array [L, a, b].
+ * @param {ColorGamut} [gamut=sRGBGamut] The color gamut.
+ * @param {Vector} [out=vec3()] The output array to store the OKHSV color.
+ * @returns {Vector} The OKHSV color as an array [h, s, v].
+ */
 export const OKLabToOKHSV = (lab, gamut = sRGBGamut, out = vec3()) => {
   // Oklab to Okhsv.
   const lmsToRgb = getGamutLMStoRGB(gamut);

package/src/spaces/a98-rgb.js

@@ -19,6 +19,11 @@ const A98RGBToGamma = (val) => {
   return sign * Math.pow(abs, 256 / 563);
 };
 
+/**
+ * The Adobe RGB (1998) color space in linear form, without a transfer function, aliased as <code>"a98-rgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const A98RGBLinear = {
   id: "a98-rgb-linear",
   toXYZ_M: linear_A98RGB_to_XYZ_M,
@@ -27,6 +32,11 @@ export const A98RGBLinear = {
   fromLMS_M: LMS_to_linear_A98RGB_M,
 };
 
+/**
+ * The Adobe RGB (1998) color space, with a transfer function, aliased as <code>"a98-rgb"</code>. Inherits from the {@link A98RGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const A98RGB = {
   id: "a98-rgb",
   base: A98RGBLinear,
@@ -44,6 +54,11 @@ export const A98RGB = {
   },
 };
 
+/**
+ * A color gamut for the {@link A98RGB}, or Adobe RGB (1998), color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const A98RGBGamut = {
   space: A98RGB,
   coefficients: OKLab_to_linear_A98RGB_coefficients,

package/src/spaces/display-p3.js

@@ -7,6 +7,11 @@ import {
 } from "../conversion_matrices.js";
 import { sRGBGammaToLinearVec3, sRGBLinearToGammaVec3 } from "./util.js";
 
+/**
+ * The Display-P3 color space in linear form, without a transfer function, aliased as <code>"display-p3-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const DisplayP3Linear = {
   id: "display-p3-linear",
   toXYZ_M: linear_DisplayP3_to_XYZ_M,
@@ -15,6 +20,11 @@ export const DisplayP3Linear = {
   fromLMS_M: LMS_to_linear_DisplayP3_M,
 };
 
+/**
+ * The Display-P3 color space, with a transfer function, aliased as <code>"display-p3"</code>. Inherits from the {@link DisplayP3Linear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const DisplayP3 = {
   id: "display-p3",
   base: DisplayP3Linear,
@@ -22,6 +32,11 @@ export const DisplayP3 = {
   fromBase: sRGBLinearToGammaVec3,
 };
 
+/**
+ * A color gamut for the {@link DisplayP3} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const DisplayP3Gamut = {
   space: DisplayP3,
   coefficients: OKLab_to_linear_DisplayP3_coefficients,

package/src/spaces/oklab.js

@@ -13,10 +13,20 @@ import { sRGBGamut } from "./srgb.js";
 // based on colorjs.io, could perhaps use a more specific number than this
 const ACHROMATIC_EPSILON = (0.4 - 0.0) / 100000;
 
+/**
+ * The OKLab color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKLab = {
   id: "oklab",
 };
 
+/**
+ * The OKLCH color space, with Lightness, Chroma, and Hue components. This is the cylindrical form of the {@link OKLab} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKLCH = {
   id: "oklch",
   base: OKLab,
@@ -51,6 +61,13 @@ export const OKLCH = {
   },
 };
 
+/**
+ * An implementation of the OKHSL color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKHSL = {
   // Note: sRGB gamut only
   // For other gamuts, use okhsl method directly
@@ -60,6 +77,13 @@ export const OKHSL = {
   fromBase: (oklab, out = vec3()) => OKLabToOKHSL(oklab, sRGBGamut, out),
 };
 
+/**
+ * An implementation of the OKHSV color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKHSV = {
   // Note: sRGB gamut only
   // For other gamuts, use okhsv method directly

package/src/spaces/prophoto-rgb.js

@@ -35,6 +35,11 @@ const ProPhotoRGBToGamma = (v) => (v >= Et ? v ** (1 / 1.8) : 16 * v);
 //   return abs >= Et ? sign * Math.pow(abs, 1 / 1.8) : 16 * val;
 // };
 
+/**
+ * The ProPhotoRGB color space in linear form, without a transfer function, aliased as <code>"prophoto-rgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const ProPhotoRGBLinear = {
   id: "prophoto-rgb-linear",
   adapt: {
@@ -47,6 +52,11 @@ export const ProPhotoRGBLinear = {
   fromXYZ_M: XYZ_to_linear_ProPhotoRGB_M,
 };
 
+/**
+ * The ProPhotoRGB color space, with a transfer function, aliased as <code>"prophoto-rgb"</code>. Inherits from the {@link ProPhotoRGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const ProPhotoRGB = {
   id: "prophoto-rgb",
   base: ProPhotoRGBLinear,

package/src/spaces/rec2020.js

@@ -16,6 +16,11 @@ const Rec2020ToLinear = (val) =>
 const Rec2020ToGamma = (val) =>
   val >= BETA ? ALPHA * Math.pow(val, 0.45) - (ALPHA - 1) : 4.5 * val;
 
+/**
+ * The Rec2020 color space in linear form, without a transfer function, aliased as <code>"rec2020-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const Rec2020Linear = {
   id: "rec2020-linear",
   toXYZ_M: linear_Rec2020_to_XYZ_M,
@@ -24,6 +29,11 @@ export const Rec2020Linear = {
   fromLMS_M: LMS_to_linear_Rec2020_M,
 };
 
+/**
+ * The Rec2020 color space, with a transfer function, aliased as <code>"rec2020"</code>. Inherits from the {@link Rec2020Linear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const Rec2020 = {
   id: "rec2020",
   base: Rec2020Linear,
@@ -41,6 +51,11 @@ export const Rec2020 = {
   },
 };
 
+/**
+ * A color gamut for the {@link Rec2020} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const Rec2020Gamut = {
   space: Rec2020,
   coefficients: OKLab_to_linear_Rec2020_coefficients,

package/src/spaces/srgb.js

@@ -8,6 +8,11 @@ import {
 
 import { sRGBGammaToLinearVec3, sRGBLinearToGammaVec3 } from "./util.js";
 
+/**
+ * The sRGB color space in linear form, without a transfer function, aliased as <code>"srgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGBLinear = {
   id: "srgb-linear",
   toXYZ_M: linear_sRGB_to_XYZ_M,
@@ -16,6 +21,11 @@ export const sRGBLinear = {
   fromLMS_M: LMS_to_linear_sRGB_M,
 };
 
+/**
+ * The sRGB color space, with a transfer function, aliased as <code>"srgb"</code>. Inherits from the {@link sRGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGB = {
   id: "srgb",
   base: sRGBLinear,
@@ -23,6 +33,11 @@ export const sRGB = {
   fromBase: sRGBLinearToGammaVec3,
 };
 
+/**
+ * A color gamut for the {@link sRGB} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const sRGBGamut = {
   space: sRGB,
   coefficients: OKLab_to_linear_sRGB_coefficients,

package/src/spaces/util.js

@@ -1,5 +1,12 @@
 import { vec3 } from "../util.js";
 
+/**
+ * Converts a single sRGB gamma-corrected channel value to linear light (un-companded) form.
+ * @param {number} val - The sRGB gamma-corrected channel value in the range [0, 1].
+ * @returns {number} The linear light channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBGammaToLinear = (val) => {
   // convert a single channel value
   // where in-gamut values are in the range [0 - 1]
@@ -15,6 +22,13 @@ export const sRGBGammaToLinear = (val) => {
     : sign * Math.pow((abs + 0.055) / 1.055, 2.4);
 };
 
+/**
+ * Converts a single linear-light channel value to sRGB gamma-corrected form.
+ * @param {number} val - The linear-light channel value in the range [0, 1].
+ * @returns {number} The sRGB gamma-corrected channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBLinearToGamma = (val) => {
   // convert a single channel linear-light value in range 0-1
   // to gamma corrected form

package/src/spaces/xyz.js

@@ -28,20 +28,44 @@ export const D50_to_D65_M = [
   [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
 ];
 
+/**
+ * Converts a color from XYZ with D65 whitepoint to XYZ with D50 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D65 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D50 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D50 whitepoint.
+ */
 export const XYZD65ToD50 = (XYZ, out = vec3()) =>
   transform(XYZ, D65_to_D50_M, out);
 
+/**
+ * Converts a color from XYZ with D50 whitepoint to XYZ with D65 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D50 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D65 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D65 whitepoint.
+ */
 export const XYZD50ToD65 = (XYZ, out = vec3()) =>
   transform(XYZ, D50_to_D65_M, out);
 
-// XYZ using D65 whitepoint
+/**
+ * XYZ color space with D65 whitepoint, aliased as <code>"xyz"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZ = {
   id: "xyz", // xyz-d65
   toLMS_M: XYZ_to_LMS_M,
   fromLMS_M: LMS_to_XYZ_M,
 };
 
-// XYZ using D50 whitepoint
+/**
+ * XYZ color space with D50 whitepoint, aliased as <code>"xyz-d50"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZD50 = {
   id: "xyz-d50",
   base: XYZ,

package/src/spaces.js

@@ -18,6 +18,13 @@ export * from "./spaces/rec2020.js";
 export * from "./spaces/a98-rgb.js";
 export * from "./spaces/prophoto-rgb.js";
 
+/**
+ * Returns a list of color spaces.
+ *
+ * @method
+ * @returns {ColorSpace[]} An array of color space objects.
+ * @category core
+ */
 export const listColorSpaces = () => {
   return [
     XYZ, // D65
@@ -39,6 +46,13 @@ export const listColorSpaces = () => {
   ];
 };
 
+/**
+ * Returns a list of color gamuts.
+ *
+ * @method
+ * @returns {ColorGamut[]} An array of color gamut objects.
+ * @category core
+ */
 export const listColorGamuts = () => {
   return [sRGBGamut, DisplayP3Gamut, Rec2020Gamut, A98RGBGamut];
 };

package/src/util.js

@@ -1,15 +1,60 @@
-const GAMUT_EPSILON = 0.000075;
-
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @method
+ * @param {number} value The value to clamp.
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ * @returns {number} The clamped value.
+ * @category utils
+ */
 export const clamp = (value, min, max) => Math.max(Math.min(value, max), min);
 
+/**
+ * Linearly interpolates between two values.
+ * @method
+ * @param {number} min The start value.
+ * @param {number} max The end value.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated value.
+ * @category utils
+ */
 export const lerp = (min, max, t) => min * (1 - t) + max * t;
 
+/**
+ * Converts degrees to radians.
+ * @method
+ * @param {number} n The angle in degrees.
+ * @returns {number} The angle in radians.
+ * @category utils
+ */
 export const degToRad = (n) => (n * Math.PI) / 180;
 
+/**
+ * Converts radians to degrees.
+ * @method
+ * @param {number} n The angle in radians.
+ * @returns {number} The angle in degrees.
+ * @category utils
+ */
 export const radToDeg = (n) => (n * 180) / Math.PI;
 
+/**
+ * Constrains an angle to the range [0, 360).
+ * @method
+ * @param {number} angle The angle in degrees.
+ * @returns {number} The constrained angle.
+ * @category utils
+ */
 export const constrainAngle = (angle) => ((angle % 360) + 360) % 360;
 
+/**
+ * Converts a hex color string to an RGB array.
+ * @method
+ * @param {string} str The hex color string.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The RGB array.
+ * @category rgb
+ */
 export const hexToRGB = (str, out = vec3()) => {
   let hex = str.replace(/#/, "");
   if (hex.length === 3) {
@@ -26,12 +71,31 @@ export const hexToRGB = (str, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts an RGB array to a hex color string.
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @returns {string} The hex color string.
+ * @category rgb
+ */
 export const RGBToHex = (rgb) =>
   `#${rgb.map((n) => floatToByte(n).toString(16).padStart(2, "0")).join("")}`;
 
-/** @deprecated use RGBToHex */
+/**
+ * @method
+ * @deprecated Use RGBToHex instead.
+ * @category rgb
+ */
 export const RGBtoHex = RGBToHex;
 
+/**
+ * Checks if an RGB color is within the gamut.
+ * @method
+ * @param {Vector} lrgb The linear RGB array.
+ * @param {number} [ep=GAMUT_EPSILON] The epsilon value for comparison.
+ * @returns {boolean} True if the color is within the gamut, false otherwise.
+ * @category rgb
+ */
 export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
   const r = lrgb[0];
   const g = lrgb[1];
@@ -46,6 +110,14 @@ export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
   );
 };
 
+/**
+ * Clamps an RGB array to the range [0, 1].
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The clamped RGB array.
+ * @category rgb
+ */
 export const clampedRGB = (rgb, out = vec3()) => {
   out[0] = clamp(rgb[0], 0, 1);
   out[1] = clamp(rgb[1], 0, 1);
@@ -53,6 +125,14 @@ export const clampedRGB = (rgb, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts xyY color space to XYZ color space.
+ * @method
+ * @param {Vector} arg The xyY array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The XYZ array.
+ * @category xyz
+ */
 export const xyY_to_XYZ = (arg, out = vec3()) => {
   let X, Y, Z, x, y;
   x = arg[0];
@@ -70,6 +150,14 @@ export const xyY_to_XYZ = (arg, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts XYZ color space to xyY color space.
+ * @method
+ * @param {Vector} arg The XYZ array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The xyY array.
+ * @category xyz
+ */
 export const XYZ_to_xyY = (arg, out = vec3()) => {
   let sum, X, Y, Z;
   X = arg[0];
@@ -87,29 +175,43 @@ export const XYZ_to_xyY = (arg, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts a float value to a byte value.
+ * @method
+ * @param {number} n The float value.
+ * @returns {number} The byte value.
+ * @category utils
+ */
 export const floatToByte = (n) => clamp(Math.round(255 * n), 0, 255);
 
-// Undocumented
-
+/**
+ * Creates a new vec3 array.
+ * @method
+ * @returns {Vector} The vec3 array.
+ * @category utils
+ */
 export const vec3 = () => [0, 0, 0];
 
-// export const normalizeHue = (hue) => ((hue = hue % 360) < 0 ? hue + 360 : hue);
-
-// in degrees
-// export const angle_delta = (angle1, angle2) => {
-//   const diff = ((angle2 - angle1 + 180) % 360) - 180;
-//   return diff < -180 ? diff + 360 : diff;
-// };
-
-// function shortAngleDistRad(a0, a1) {
-//   var max = Math.PI * 2;
-//   var da = (a1 - a0) % max;
-//   return ((2 * da) % max) - da;
-// }
-
+/**
+ * Calculates the delta angle between two angles.
+ * @method
+ * @param {number} a0 The first angle in degrees.
+ * @param {number} a1 The second angle in degrees.
+ * @returns {number} The delta angle in degrees.
+ * @category utils
+ */
 export const deltaAngle = (a0, a1) => {
   var da = (a1 - a0) % 360;
   return ((2 * da) % 360) - da;
 };
 
+/**
+ * Linearly interpolates between two angles.
+ * @method
+ * @param {number} a0 The start angle in degrees.
+ * @param {number} a1 The end angle in degrees.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated angle in degrees.
+ * @category utils
+ */
 export const lerpAngle = (a0, a1, t) => a0 + deltaAngle(a0, a1) * t;

package/types/types.d.ts

@@ -0,0 +1,332 @@
+declare module "@texel/color" {
+    /**
+     * A 3x3 matrix represented as an array of arrays.
+     * @example
+     * const matrix = [
+     *   [a, b, c],
+     *   [d, e, f],
+     *   [g, h, i]
+     * ];
+     */
+    type Matrix3x3 = number[][];
+    /**
+     * A n-dimensional vector represented as an array of numbers, typically in 3D (X, Y, Z).
+     * @example
+     * const vec = [ x, y, z ];
+     */
+    type Vector = number[];
+    /**
+     * @property from - the matrix to convert from the source whitepoint to the destination whitepoint
+     * @property to - the matrix to convert from the destination whitepoint to the source whitepoint
+     */
+    type ChromaticAdaptation = {
+        from: Matrix3x3;
+        to: Matrix3x3;
+    };
+    /**
+     * @property id - the unique identifier for this color space in lowercase
+     * @property [toXYZ_M] - optional matrix to convert this color directly to XYZ D65
+     * @property [fromXYZ_M] - optional matrix to convert XYZ D65 to this color space
+     * @property [toLMS_M] - optional matrix to convert this color space to OKLab's LMS intermediary form
+     * @property [fromLMS_M] - optional matrix to convert OKLab's LMS intermediary form to this color space
+     * @property [adapt] - optional chromatic adaptation matrices
+     * @property [base] - an optional base color space that this space is derived from
+     * @property [toBase] - if a base color space exists, this maps the color to the base space form (e.g. gamma to the linear base space)
+     * @property [fromBase] - if a base color space exists, this maps the color from the base space form (e.g. the linear base space to the gamma space)
+     */
+    type ColorSpace = {
+        id: string;
+        toXYZ_M?: Matrix3x3;
+        fromXYZ_M?: Matrix3x3;
+        toLMS_M?: Matrix3x3;
+        fromLMS_M?: Matrix3x3;
+        adapt?: ChromaticAdaptation;
+        base?: ColorSpace;
+        toBase?: (...params: any[]) => any;
+        fromBase?: (...params: any[]) => any;
+    };
+    /**
+     * @property space - the color space associated with this color gamut
+     */
+    type ColorGamut = {
+        space: ColorSpace;
+    };
+    /**
+     * Converts OKLab color to another color space.
+     * @param OKLab - The OKLab color.
+     * @param LMS_to_output - The transformation matrix from LMS to the output color space.
+     * @param [out = vec3()] - The output vector.
+     * @returns The transformed color.
+     */
+    function OKLab_to(OKLab: Vector, LMS_to_output: Matrix3x3, out?: Vector): Vector;
+    /**
+     * Converts a color from another color space to OKLab.
+     * @param input - The input color.
+     * @param input_to_LMS - The transformation matrix from the input color space to LMS.
+     * @param [out = vec3()] - The output vector.
+     * @returns The transformed color.
+     */
+    function OKLab_from(input: Vector, input_to_LMS: Matrix3x3, out?: Vector): Vector;
+    /**
+     * Transforms a color vector by the specified 3x3 transformation matrix.
+     * @param input - The input color.
+     * @param matrix - The transformation matrix.
+     * @param [out = vec3()] - The output vector.
+     * @returns The transformed color.
+     */
+    function transform(input: Vector, matrix: Matrix3x3, out?: Vector): Vector;
+    /**
+     * Serializes a color to a CSS color string.
+     * @param input - The input color.
+     * @param inputSpace - The input color space.
+     * @param [outputSpace = inputSpace] - The output color space.
+     * @returns The serialized color string.
+     */
+    function serialize(input: Vector, inputSpace: ColorSpace, outputSpace?: ColorSpace): string;
+    /**
+     * Deserializes a color string to an object with <code>id</code> (color space string) and <code>coords</code> (the vector, in 3 or 4 dimensions).
+     * Note this does not return a <code>ColorSpace</code> object; you may want to use the example code below to map the string ID to a <code>ColorSpace</code>, but this will increase the size of your final bundle as it references all spaces.
+     * @example
+     * import { listColorSpaces, deserialize } from "@texel/color";
+     *
+     * const { id, coords } = deserialize(str);
+     * // now find the actual color space object
+     * const space = listColorSpaces().find((f) => id === f.id);
+     * console.log(space, coords);
+     * @param input - The color string to deserialize.
+     * @returns The deserialized color object.
+     */
+    function deserialize(input: string): any;
+    /**
+     * Parses a color string and converts it to the target color space.
+     * @param input - The color string to parse.
+     * @param targetSpace - The target color space.
+     * @param [out = vec3()] - The output vector.
+     * @returns The parsed and converted color.
+     */
+    function parse(input: string, targetSpace: ColorSpace, out?: Vector): Vector;
+    /**
+     * Converts a color from one color space to another.
+     * @param input - The input color.
+     * @param fromSpace - The source color space.
+     * @param toSpace - The target color space.
+     * @param [out = vec3()] - The output vector.
+     * @returns The converted color.
+     */
+    function convert(input: Vector, fromSpace: ColorSpace, toSpace: ColorSpace, out?: Vector): Vector;
+    /**
+     * Calculates the DeltaEOK (color difference) between two OKLab colors.
+     * @param oklab1 - The first OKLab color.
+     * @param oklab2 - The second OKLab color.
+     * @returns The delta E value.
+     */
+    function deltaEOK(oklab1: Vector, oklab2: Vector): number;
+    /**
+     * A function that maps an OKLCH color to a lightness value.
+     * @param oklch - The input OKLCH color
+     * @param cusp - A 2D cusp point in the form [L, C]
+     */
+    type GamutMapMethod = (oklch: Vector, cusp: number[]) => void;
+    /**
+     * A {@link GamutMapMethod} that maintains the color's lightness.
+     */
+    const MapToL: GamutMapMethod;
+    /**
+     * A {@link GamutMapMethod} that maps towards middle gray (L = 0.5).
+     */
+    const MapToGray: GamutMapMethod;
+    /**
+     * A {@link GamutMapMethod} that maps towards the lightness of the current hue's cusp.
+     */
+    const MapToCuspL: GamutMapMethod;
+    /**
+     * A {@link GamutMapMethod} that adaptively maps towards gray.
+     */
+    const MapToAdaptiveGray: GamutMapMethod;
+    /**
+     * A {@link GamutMapMethod} that adaptively maps towards the cusp's lightness.
+     */
+    const MapToAdaptiveCuspL: GamutMapMethod;
+    /**
+     * Computes the maximum saturation (S = C/L) possible for a given hue that fits within
+     * the RGB gamut, using the given coefficients.
+     * @param a - The normalized a component of the hue.
+     * @param b - The normalized b component of the hue.
+     * @param lmsToRgb - The LMS to RGB conversion matrix.
+     * @param okCoeff - The OKLab coefficients.
+     * @returns The maximum saturation.
+     */
+    function computeMaxSaturationOKLC(a: number, b: number, lmsToRgb: number[][], okCoeff: number[][][]): number;
+    /**
+     * Retrieves the LMS to RGB conversion matrix from the given gamut.
+     * @param gamut - The gamut object.
+     * @returns The LMS to RGB conversion matrix.
+     */
+    function getGamutLMStoRGB(gamut: ColorGamut): Matrix3x3;
+    /**
+     * Finds the cusp of the OKLCH color space for a given hue.
+     * @param a - The normalized a component of the hue.
+     * @param b - The normalized b component of the hue.
+     * @param gamut - The gamut object.
+     * @param [out = [0, 0]] - The output array to store the cusp values.
+     * @returns The cusp values [L, C].
+     */
+    function findCuspOKLCH(a: number, b: number, gamut: ColorGamut, out?: number[]): number[];
+    /**
+     * Applies fast approximate gamut mapping in OKLab space on the given OKLCH input color,
+     * using the specified gamut and converting to the target color space.
+     * @param oklch - The input OKLCH color that you wish to gamut map.
+     * @param [gamut = sRGBGamut] - The gamut object.
+     * @param [targetSpace = gamut.space] - The target color space.
+     * @param [out = vec3()] - The output array to store the mapped color.
+     * @param [mapping = MapToCuspL] - The gamut mapping function.
+     * @param [cusp] - Optional, you can provide the cusp values [L, C] to avoid re-computing them.
+     * @returns The mapped color in the target color space.
+     */
+    function gamutMapOKLCH(oklch: Vector, gamut?: ColorGamut, targetSpace?: ColorSpace, out?: Vector, mapping?: GamutMapMethod, cusp?: Vector): Vector;
+    /**
+     * Converts OKHSL color to OKLab color.
+     * @param hsl - The OKHSL color as an array [h, s, l].
+     * @param [gamut = sRGBGamut] - The color gamut.
+     * @param [out = vec3()] - The output array to store the OKLab color.
+     * @returns The OKLab color as an array [L, a, b].
+     */
+    function OKHSLToOKLab(hsl: Vector, gamut?: ColorGamut, out?: Vector): Vector;
+    /**
+     * Converts OKLab color to OKHSL color.
+     * @param lab - The OKLab color as an array [L, a, b].
+     * @param [gamut = sRGBGamut] - The color gamut.
+     * @param [out = vec3()] - The output array to store the OKHSL color.
+     * @returns The OKHSL color as an array [h, s, l].
+     */
+    function OKLabToOKHSL(lab: Vector, gamut?: ColorGamut, out?: Vector): Vector;
+    /**
+     * Converts OKHSV color to OKLab color.
+     * @param hsv - The OKHSV color as an array [h, s, v].
+     * @param [gamut = sRGBGamut] - The color gamut.
+     * @param [out = vec3()] - The output array to store the OKLab color.
+     * @returns The OKLab color as an array [L, a, b].
+     */
+    function OKHSVToOKLab(hsv: Vector, gamut?: ColorGamut, out?: Vector): Vector;
+    /**
+     * Converts OKLab color to OKHSV color.
+     * @param lab - The OKLab color as an array [L, a, b].
+     * @param [gamut = sRGBGamut] - The color gamut.
+     * @param [out = vec3()] - The output array to store the OKHSV color.
+     * @returns The OKHSV color as an array [h, s, v].
+     */
+    function OKLabToOKHSV(lab: Vector, gamut?: ColorGamut, out?: Vector): Vector;
+    /**
+     * Returns a list of color spaces.
+     * @returns An array of color space objects.
+     */
+    function listColorSpaces(): ColorSpace[];
+    /**
+     * Returns a list of color gamuts.
+     * @returns An array of color gamut objects.
+     */
+    function listColorGamuts(): ColorGamut[];
+    /**
+     * Clamps a value between a minimum and maximum value.
+     * @param value - The value to clamp.
+     * @param min - The minimum value.
+     * @param max - The maximum value.
+     * @returns The clamped value.
+     */
+    function clamp(value: number, min: number, max: number): number;
+    /**
+     * Linearly interpolates between two values.
+     * @param min - The start value.
+     * @param max - The end value.
+     * @param t - The interpolation factor between 0 and 1.
+     * @returns The interpolated value.
+     */
+    function lerp(min: number, max: number, t: number): number;
+    /**
+     * Converts degrees to radians.
+     * @param n - The angle in degrees.
+     * @returns The angle in radians.
+     */
+    function degToRad(n: number): number;
+    /**
+     * Converts radians to degrees.
+     * @param n - The angle in radians.
+     * @returns The angle in degrees.
+     */
+    function radToDeg(n: number): number;
+    /**
+     * Constrains an angle to the range [0, 360).
+     * @param angle - The angle in degrees.
+     * @returns The constrained angle.
+     */
+    function constrainAngle(angle: number): number;
+    /**
+     * Converts a hex color string to an RGB array.
+     * @param str - The hex color string.
+     * @param [out = vec3()] - The output array.
+     * @returns The RGB array.
+     */
+    function hexToRGB(str: string, out?: Vector): Vector;
+    /**
+     * Converts an RGB array to a hex color string.
+     * @param rgb - The RGB array.
+     * @returns The hex color string.
+     */
+    function RGBToHex(rgb: Vector): string;
+    function RGBtoHex(): void;
+    /**
+     * Checks if an RGB color is within the gamut.
+     * @param lrgb - The linear RGB array.
+     * @param [ep = GAMUT_EPSILON] - The epsilon value for comparison.
+     * @returns True if the color is within the gamut, false otherwise.
+     */
+    function isRGBInGamut(lrgb: Vector, ep?: number): boolean;
+    /**
+     * Clamps an RGB array to the range [0, 1].
+     * @param rgb - The RGB array.
+     * @param [out = vec3()] - The output array.
+     * @returns The clamped RGB array.
+     */
+    function clampedRGB(rgb: Vector, out?: Vector): Vector;
+    /**
+     * Converts xyY color space to XYZ color space.
+     * @param arg - The xyY array.
+     * @param [out = vec3()] - The output array.
+     * @returns The XYZ array.
+     */
+    function xyY_to_XYZ(arg: Vector, out?: Vector): Vector;
+    /**
+     * Converts XYZ color space to xyY color space.
+     * @param arg - The XYZ array.
+     * @param [out = vec3()] - The output array.
+     * @returns The xyY array.
+     */
+    function XYZ_to_xyY(arg: Vector, out?: Vector): Vector;
+    /**
+     * Converts a float value to a byte value.
+     * @param n - The float value.
+     * @returns The byte value.
+     */
+    function floatToByte(n: number): number;
+    /**
+     * Creates a new vec3 array.
+     * @returns The vec3 array.
+     */
+    function vec3(): Vector;
+    /**
+     * Calculates the delta angle between two angles.
+     * @param a0 - The first angle in degrees.
+     * @param a1 - The second angle in degrees.
+     * @returns The delta angle in degrees.
+     */
+    function deltaAngle(a0: number, a1: number): number;
+    /**
+     * Linearly interpolates between two angles.
+     * @param a0 - The start angle in degrees.
+     * @param a1 - The end angle in degrees.
+     * @param t - The interpolation factor between 0 and 1.
+     * @returns The interpolated angle in degrees.
+     */
+    function lerpAngle(a0: number, a1: number, t: number): number;
+}
+